Wi-Fi APIs#

rsi_driver_send_data#

int32_t rsi_driver_send_data (uint32_t sockID, uint8_t * buffer, uint32_t length, struct rsi_sockaddr * destAddr)

Send data packet. This is a blocking API.

Returns

• 0 - Success Negative Value - Failure

rsi_driver_process_recv_data#

int32_t rsi_driver_process_recv_data (rsi_pkt_t * pkt)

This API processes received data packet. This is a non-blocking API.

Returns

• 0 - Success Negative Value - Failure

rsi_nwk_register_callbacks#

int16_t rsi_nwk_register_callbacks (uint32_t callback_id, void(*)(uint8_t command_type, uint32_t status, const uint8_t *buffer, const uint32_t length) callback_handler_ptr, status, buffer, length)

Register the call backs. This is a non-blocking API.

Returns

• 0 - Success Non-Zero Value - Failure -3 Command given in wrong state If call_back_id is greater than the maximum callbacks to register, returns 1

prototypes of the call back functions#

rsi_wlan_radio_init#

int32_t rsi_wlan_radio_init (void )

This API initializes wlan radio parameters and WLAN supplicant parameters. This API returns the WLAN MAC address of the module to the host.

• rsi_wireless_init() API must be called before this rsi_wlan_radio_init() API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is greater than 0 0x0021- Command given in wrong state

Note

• rsi_wlan_radio_init() is used if user wants to configure any other parameters which are supposed to be given before rsi_wlan_scan() or rsi_wlan_scan_async() API

rsi_wlan_filter_broadcast#

int32_t rsi_wlan_filter_broadcast (uint16_t beacon_drop_threshold, uint8_t filter_bcast_in_tim, uint8_t filter_bcast_tim_till_next_cmd)

Program the ignoring broad cast packet threshold levels when station is in powersave mode and is used to achieve low currents in standby associated mode. This is blocking API.

Note

• Validity of this bit is dependent on the filter_bcast_tim_till_next_cmd

Returns

• 0 - Success Non-Zero Value - If return value is less than 0 -2: Invalid parameters -3: Command given in wrong state -4: Buffer not available to serve the command return value is greater than 0 0x0021

rsi_check_state#

int32_t rsi_check_state (int32_t type)

Check the WLAN state.

Returns

• 0 - If in IP config state -20 - If not in IP config state

rsi_sort_scan_results_array_based_on_rssi#

void rsi_sort_scan_results_array_based_on_rssi (struct wpa_scan_results_arr * scan_results_array)

Sort the scan results in 'scan_results_array' in the order of RSSI. Application should call this API to get the scan result in sorted order.

• rsi_wlan_scan_with_bitmap_options() API needs to be called before this API.

Returns

• Void

rsi_config_timeout#

int32_t rsi_config_timeout (uint32_t timeout_type, uint16_t timeout_value)

This API is used to set timeouts. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

Note

• Packet is sent as Wlan Keep alive before rsi_config_ipaddress() After rsi_config_ipaddress() it is sent as gratuitous ARP.

Returns

• 0 - Success Non-Zero Value - Failure

send_timeout#

int32_t send_timeout (uint32_t timeout_bitmap, uint16_t timeout_value)

This API is used to set timeouts. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

Note

• Packet is sent as Wlan Keep alive before rsi_config_ipaddress() After rsi_config_ipaddress() it is sent as gratuitous ARP.

Returns

• 0 - Success Non-Zero Value - Failure

rsi_wlan_scan_with_bitmap_options#

int32_t rsi_wlan_scan_with_bitmap_options (int8_t * ssid, uint8_t chno, rsi_rsp_scan_t * result, uint32_t length, uint32_t scan_bitmap)

Scan available access points and post scan response to application. Application must call this API to get the scan results. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure

rsi_wlan_scan_async_with_bitmap_options#

int32_t rsi_wlan_scan_async_with_bitmap_options (int8_t * ssid, uint8_t chno, uint32_t bitmap, void(*)(uint16_t status, const uint8_t *buffer, const uint16_t length) scan_response_handler, buffer, length, scan_bitmap)

Scan available access points and post scan response to application. Application must call this API to get the scan results. This is a non-blocking API.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure

rsi_wlan_scan#

int32_t rsi_wlan_scan (int8_t * ssid, uint8_t chno, rsi_rsp_scan_t * result, uint32_t length)

Scan the surrounding Wi-Fi networks. This is a blocking API. Invoke rsi_wlan_scan_async(), which is an asynchronous call. Wait on WLAN command semaphore to get the status of the scan results. Return RSI_SUCCESS on success and optionally, a maximum of 11 scan results if rsi_rsp_scan_t parameter is configured. In case of failure, an appropriate error code is returned to the application.

• rsi_wireless_init() API needs to be called before this API.

Channels supported in 2.4 GHz Band#

Channels supported in 5 GHz Band#

DFS Channels supported in 5 GHz Band#

Channels supported in 4.9 GHz Band#

Note

• To set various timeouts, user should change the following macros in rsi_wlan_config.h #define RSI_TIMEOUT_SUPPORT RSI_ENABLE #define RSI_TIMEOUT_BIT_MAP 2 #define RSI_TIMEOUT_VALUE 150 (This macro can be configured based on user requirement)

  timeout_bitmap	Description
  timeout_bitmap[0]	Set timeout for association and authentication request.timeout_value : timeout value in ms(default 300ms).
  timeout_bitmap[1]	Sets each channel active scan time in ms (default 100ms)
  timeout_bitmap[2]	Used for WLAN keep alive timeout(default value is 30s)
  timeout_bitmap[31-3]	Reserved

Scan structure#

Returns

• Success - RSI_SUCCESS

• Failure - Non-Zero values

       `If return value is less than 0` \n
  
               **RSI_ERROR_INVALID_PARAM**                 - Invalid parameters \n
  
           **RSI_ERROR_COMMAND_GIVEN_IN_WRONG_STATE**  - Command given in wrong state \n
  
           **RSI_ERROR_PKT_ALLOCATION_FAILURE**        - Buffer not available to serve the command \n
  
                   `Other expected error codes are :` \n
  
               **0x0002, 0x0003, 0x0005, 0x000A, 0x0014, 0x0015, 0x001A, 0x0021,0x0024,0x0025,0x0026,0x002C,0x003c**
  

Note

• Refer to Error Codes section for above error codes description Error Codes.

rsi_wlan_scan_async#

int32_t rsi_wlan_scan_async (int8_t * ssid, uint8_t chno, void(*)(uint16_t status, const uint8_t *buffer, const uint16_t length) scan_response_handler, Status, Buffer, Length)

Scan the surrounding Wi-Fi networks. A scan response handler is registered with it to get the response for scan.This is a non-blocking API.

Note

• If status is Success , the argument buffer passed to scan_response_handler holds scan results in rsi_rsp_scan_t structure format.

• rsi_wireless_init() API needs to be called before this API.

Note

• SSID is a null terminated string.

Channels supported in 2.4 GHz Band#

Channels supported in 5 GHz Band#

Note

• To set various timeouts, user should change the following macros in rsi_wlan_config.h #define RSI_TIMEOUT_SUPPORT RSI_ENABLE #define RSI_TIMEOUT_BIT_MAP 4 #define RSI_TIMEOUT_VALUE 300

Scan Response structure format#

Scan structure#

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not available to serve the command If return value is greater than 0 0x0002, 0x0003, 0x0005, 0x000A, 0x0014, 0x0015, 0x001A, 0x0021,0x0024,0x0025,0x0026,0x002C,0x003c

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_connect#

int32_t rsi_wlan_connect (int8_t * ssid, rsi_security_mode_t sec_type, void * secret_key)

Connect to the specified Wi-Fi network. This is a blocking API. Call asynch connect to trigger connect call to AP and return RSI_SUCCESS or error in case of failure.

• rsi_wireless_init() API needs to be called before this API.

Note

• To set various timeouts, user should change the following macros in rsi_wlan_config.h #define RSI_TIMEOUT_SUPPORT RSI_ENABLE #define RSI_TIMEOUT_BIT_MAP 4 #define RSI_TIMEOUT_VALUE 300 timeout_bitmap[0] - Set timeout for association and authentication request. timeout_value : timeout value in ms(default 300ms). timeout_bitmap[1] - Sets each channel active scan time in ms (default 100ms) timeout_bitmap[2] - Used for WLAN keep alive timeout(default value is 30s) timeout_bitmap[31-3] - reserved

• To set Rejoin params, user should configure the following macros in rsi_wlan_config.h RSI_REJOIN_PARAMS_SUPPORT : Enable to send rejoin parameters command during Wi-Fi client connection RSI_REJOIN_MAX_RETRY : Number of maximum rejoin retries by module note : If Max retries is 0 , retries infinity times RSI_REJOIN_SCAN_INTERVAL : Periodicity of rejoin attempt RSI_REJOIN_BEACON_MISSED_COUNT : Number of consecutive beacon misses after which modules goes to unconnected state RSI_REJOIN_FIRST_TIME_RETRY : ENABLE - Try to rejoin in the first attempt after join failure. DISABLE - Try to rejoin based on maximum rejoin retries configured. When RSI_REJOIN_PARAMS_SUPPORT is enabled in the rsi_wlan_config.h, this rejoin frame will be sent to the firmware after scan done in the SAPI.

• This API internally handles following commands based on wlan_cb state and sends the next command and finally sends the join command. • Set mac address • Band • Timeout • Init • Set region • WMM parameters • Scan • EAP config • WMM PS parameters • WPS method • Set WEP keys • Host PSK • Rejoin params • Join For example, After calling rsi_wireless_init(), wlan_cb state is updated to opermode done state. So when we call this API, it will execute band, init, scan and join commands. After calling rsi_wlan_disconnect() or else after rejoin failure, wlan_cb state is updated to band done state. So when we call this API, it will execute init, scan and join commands. After calling rsi_wlan_scan()/ rsi_wlan_scan_with_bitmap_options() API, wlan_cb state is updated to scan done state. So when we call this API, it will execute join command directly.

EAP configuration#

For EAP configuration below arguments are required and are congifured in rsi_wlan_config.h in enterprise_client applicaiton. • eap_method, inner_method, user_identity, password, okc, private_key_password • eap_method is 32 bytes and it can be any one of the following methods: TLS, TTLS, FAST, PEAP or LEAP, should be given as string in RSI_EAP_METHOD. • inner_method is 32 bytes, this field is valid only in TTLS/PEAP. In case of TTLS/PEAP supported inner methods are MSCHAP/MSCHAPV2. In case of TLS/FAST/LEAP this field is not valid and it should be fixed to MSCHAPV2. Here MSCHAP/MSCHAPV2 are given in RSI_EAP_INNER_METHOD. • user_identity is 64 bytes, this can be configured in USER_IDENTITY of rsi_eap_connectivity.c of enterprise_client application and this should be a string. • password is 128 bytes, this can be configured in PASSWORD of rsi_eap_connectivity.c of enterprise_client application and this should be a string. • okc is 4 bytes, This argument is used to enable or disable or select multiple features from user this value can be modified by OKC_VALUE macro.

• BIT[0] of OKC is used to enable or disable opportunistic key caching (OKC), –0 – disable –1 – enable – When this is enabled, module will use cached PMKID to get MSK(Master Session Key) which is need for generating PMK which is needed for 4-way handshake.

• BIT[1] of OKC is used to enable or disable CA certification for PEAP connection. –0 – CA certificate is not required. –1 – CA certificate is required.

• BIT[2-12] of OKC argument are used for Cipher list selection for EAP connection. All possible ciphers are listed below

  BIT position	Cipher selected
  2	DHE-RSA-AES256-SHA256
  3	DHE-RSA-AES128-SHA256
  4	DHE-RSA-AES256-SHA
  5	DHE-RSA-AES128-SHA
  6	AES256-SHA256
  7	AES128-SHA256
  8	AES256-SHA
  9	AES128-SHA
  10	RC4-SHA
  11	DES-CBC3-SHA
  12	RC4-MD5

• BIT[13-31] of OKC argument is reserved.

• When user sets BIT[1] and does not provide the CA certificate for PEAP connection then error is thrown. If user provides invalid CA certificate then also error is thrown. User can set either one or multiple bits from BIT[2-12] to provide the cipher's list. When user does not provide any value in OKC's BIT[2-12] then by default all the ciphers are selected. • private_key_password is 82 bytes,This is password for encrypted private key given to the module. Module will use this password during decryption of encrypted private key. password length must be 80 bytes or less. Should be configured in RSI_PRIVATE_KEY_PASSWORD.

Returns

• Success - RSI_SUCCESS Failure - Non-Zero Value

      `if return value is less than zero :\n
  

RSI_ERROR_INVALID_PARAM - Invalid parameters RSI_ERROR_COMMAND_GIVEN_IN_WRONG_STATE - Command given in wrong state RSI_ERROR_PKT_ALLOCATION_FAILURE - Buffer not available to serve the command `Other expected error code are : 0x0002,0x0003,0x0005,0x0008,0x0009,0x000A,0x000E,0x0014,0x0015,0x0016,0x0019,0x001A,0x001E,0x0020,0x0021,0x0024,0x0025,0x0026,0x0028,0x0039,0x003C,0x0044,0x0045,0x0046,0x0047,0x0048,0x0049,0xFFF8Note

• WPA3 security not supported in AP mode. WPA3 STA supports both H2E and Hunting-and-pecking for WPA3 authentication. It picks authentication algorithm based on AP's capability. WPA3 STA supports PMKSA caching. If STA has valid PMKID (generated after first connection) with an AP it will trigger OPEN authentication for successive connection attempts. By default the lifetime for PMKSA entry is 12 hours. In WPA3 Personal Transition Mode if both WPA2 and WPA3 APs are available in scan results, STA will pick the AP which has strongest RSSI (it could be either WPA2 or WPA3). If connected WPA3 AP enables Transition Disable Indication, from that moment onwards STA in transistion mode will not try connections to WPA2 APs. This behavior will persist until reset of the STA.

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_connect_async#

int32_t rsi_wlan_connect_async (int8_t * ssid, rsi_security_mode_t sec_type, void * secret_key, void(*)(uint16_t status, const uint8_t *buffer, const uint16_t length) join_response_handler, Status, Buffer, length)

Connect to the specified Wi-Fi network.A join response handler is registered to get the response for join.. This is a non-blocking API.

• rsi_wireless_init() API needs to be called before this API.

Note

• The module gets a default IP of 192.168.100.76 if it becomes a Group Owner or Access Point in case of IPv4. and gets a default IP of 2001:db8:0:1:0:0:0:120 in case of IPv6.

• To set Rejoin params, user should configure the following macros in rsi_wlan_config.h RSI_REJOIN_PARAMS_SUPPORT : Enable to send rejoin parameters command during Wi-Fi client connection RSI_REJOIN_MAX_RETRY : Number of maximum rejoin retries by module note : If Max retries is 0 , retries infinity times RSI_REJOIN_SCAN_INTERVAL : Periodicity of rejoin attempt RSI_REJOIN_BEACON_MISSED_COUNT : Number of consecutive beacon misses after which modules goes to unconnected state RSI_REJOIN_FIRST_TIME_RETRY : ENABLE - Try to rejoin in the first attempt after join failure. DISABLE - Try to rejoin based on maximum rejoin retries configured. When RSI_REJOIN_PARAMS_SUPPORT is enabled in the rsi_wlan_config.h, this rejoin frame will be sent to the firmware after scan done in the SAPI.

• This API internally handles following commands based on wlan_cb state and sends the next command and finally sends the join command. • Set mac address • Band • Timeout • Init • Set region • WMM parameters • Scan • EAP config • WMM PS parameters • WPS method • Set WEP keys • Host PSK • Rejoin params • Join For example, After calling rsi_wireless_init(), wlan_cb state is updated to opermode done state. So when we call this API, it will execute band, init, scan and join commands. After calling rsi_wlan_disconnect() or else after rejoin failure, wlan_cb state is updated to band done state. So when we call this API, it will execute init, scan and join commands. After calling rsi_wlan_scan()/ rsi_wlan_scan_with_bitmap_options() API, wlan_cb state is updated to scan done state. So when we call this API, it will execute join command directly.

Returns

• 0 - Success Non-Zero - Failure -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not availableto serve the command

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_bgscan_profile#

int32_t rsi_wlan_bgscan_profile (uint8_t cmd, rsi_rsp_scan_t * result, uint32_t length)

Get background scan results or stop bgscan. This is a blocking API.

• rsi_wlan_connect() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure -3 - Command given in wrong state -4 - Buffer not availableto serve the command.

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_execute_post_connect_cmds#

int32_t rsi_wlan_execute_post_connect_cmds (void )

Enable scan and roaming after connecting to the Access Point. This is a blocking API.

• rsi_wlan_connect() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -3 - Command given in wrong state -4 - Buffer not available to serve the command If return value is greater than 0 0x0006,0x0021,0x002C,0x004A,0x0025,0x0026

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_wps_push_button_event#

int32_t rsi_wlan_wps_push_button_event (int8_t * ssid)

Start the WPS Push button in AP mode. Must be called after rsi_wlan_ap_start API once it has returned Success. This is a blocking API.

• rsi_wlan_ap_start() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4 - Buffer not available to serve the command If return value is greater than 0 0x0021

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_send_freq_offset#

int32_t rsi_send_freq_offset (int32_t freq_offset_in_khz)

Application to provide feedback of Frequency error in KHz. This is a blocking API.

Returns

• 0 - Success Non zero Value - Failure 0xFC - Frequency offset sent is zero 0xFB - Frequency offset specified goes beyond the upper limit or lower limit and indicates that frequency offset cannot be changed further.

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_calib_write#

int32_t rsi_calib_write (uint8_t target, uint32_t flags, int8_t gain_offset, int32_t xo_ctune)

RF calibration process. This API will command the firmware to update the existing Flash/EFuse calibration data. This is a blocking API.

• rsi_transmit_test_start(), rsi_send_freq_offset() API needs to be called before this API.This API is relevant in PER mode only.

Note

• To recalibrate gain offset after it has been burnt to flash, the user is required to first reset gain offset and then follow the calibration flow. e.g.: rsi_calib_write(BURN_INTO_FLASH,BURN_GAIN_OFFSET,0,0); // which resets gain offset Recalibration is not possible if EFuse is being used instead of flash as calibration data storage

Returns

• 0 - Success Non-Zero Value - Failure

rsi_parse#

int16_t rsi_parse (void * address, uint16_t length, uint8_t * value)

Parse and convert the given value in ASCII to the datatype of a given length.. This is a non-blocking API.

Returns

• 0 - Success Non-Zero Value - Failure

rsi_wlan_wps_generate_pin#

int32_t rsi_wlan_wps_generate_pin (uint8_t * wps_pin, uint16_t length, 8-byte)

Generate WPS pin. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4 - Buffer not available to serve the command If return value is greater than 0 0x0021,0x002C,0x0025,0x0037,0x0038

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_wps_enter_pin#

int32_t rsi_wlan_wps_enter_pin (int8_t * wps_pin, Same)

Validate WPS pin entered. This is a blocking API.

• rsi_wlan_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure

rsi_get_random_bytes#

int32_t rsi_get_random_bytes (uint8_t * result, uint32_t length)

Get random bytes from the device. This is a blocking API.

Returns

• 0 - Success Non-Zero Value - Failure

rsi_wlan_disconnect#

int32_t rsi_wlan_disconnect (void )

Disconnect module from the connected access point. This is a blocking API.

• rsi_wlan_connect() API needs to be called before this API.

Returns

• Non-Zero Value - Failure 0 - Success If return value is less than 0 -3 - Command given in wrong state -4 - Buffer not availableto serve the command If return value is greater than 0 0x0006,0x0021,0x002C,0x004A,0x0025,0x0026

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_disconnect_stations#

int32_t rsi_wlan_disconnect_stations (uint8_t * mac_address)

Disconnect the connected stations in AP mode. This is a blocking API.

• rsi_wlan_ap_start() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4 - Buffer not available to serve the command If return value is greater than 0 0x0013, 0x0021, 0x002C, 0x0015

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_config_ipaddress#

int32_t rsi_config_ipaddress (rsi_ip_version_t version, uint8_t mode, uint8_t * ip_addr, uint8_t * mask, uint8_t * gw, uint8_t * ipconfig_rsp, uint16_t length, uint8_t vap_id)

Configure the IP address to the module. This is a blocking API. Send IPconfig command to configure IP address with input parameters (like ipversion, static mode/dhcp mode,vap_id)and return error in case of invalid parameters.

• rsi_wlan_connect() API needs to be called before this API.

Returns

• Success - RSI_SUCCESS Failure - Non-Zero Value RSI_ERROR_INVALID_PARAM - Invalid parametersRSI_ERROR_COMMAND_GIVEN_IN_WRONG_STATE - Command given in wrong state RSI_ERROR_PKT_ALLOCATION_FAILURE - Buffer not available to serve the command

Note

• Refer to Error Codes section for the description of other error codes Error Codes.

rsi_wlan_set_certificate_index#

int32_t rsi_wlan_set_certificate_index (uint8_t certificate_type, uint8_t cert_inx, uint8_t * buffer, uint32_t certificate_length)

Write or erase certificate into module. This is a blocking API.

• rsi_wireless_init() API must be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 Invalid Parameters -3 Command given in wrong state -4 Buffer not available to serve the command If return value is greater than 0 0x0015,0x0021,0x0025,0x0026,0x002C

Note

• Index-based certificate loading is valid only for storing certificates on to RAM or flash but not both at the same time. Enable BIT(27) in tcp_ip_feature_bit_map to load SSl certificate into RAM. Enable BIT(31) in tcp_ip_feature_bit_map and BIT (29) in ext_tcp_ip_feature_bit_map to open 3 SSL client sockets. Three SSL client sockets feature supported only in WLAN mode.

rsi_wlan_get_status#

int32_t rsi_wlan_get_status (void )

Check the status (specific error code) of errors encountered during a call to a WLAN API or BSD sockets functions. User can call this API to check the error code.This is a non-blocking API.

Returns

• Return the error code that previously occurred. If no error occurred, return 0.

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_get#

int32_t rsi_wlan_get (rsi_wlan_query_cmd_t cmd_type, uint8_t * response, uint16_t length)

Get the required information based on the type of command. This is a blocking API.

• rsi_wireless_init () API needs to be called before this API. Return WLAN status

Note

• RSI_WLAN_INFO is relevant in both station and AP mode. RSI_SOCKETS_INFO is relevant in both station mode and AP mode. RSI_STATIONS_INFO is relevant in AP mode RSI_GET_WLAN_STATS is relevant in AP and Station mode

Returns

• Non-Zero Value - Failure 0 - Success -3 - Command given in wrong state -4 - Buffer not availableto serve the command -6 - Insufficient input buffer given

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_set#

int32_t rsi_wlan_set (rsi_wlan_set_cmd_t cmd_type, uint8_t * request, uint16_t length)

Request configuration based on the command type. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API. For setting MAC address, call this API immediately after rsi_wireless_init() and before calling any other API. rsi_config_ipaddress() needs to be call for RSI_CFG_SAVE and RSI_CFG_STORE.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not available to serve the command If return value is greater than 0 0x0002, 0x0003, 0x0005, 0x000A, 0x0014, 0x0015, 0x001A, 0x0021,0x0024,0x0025,0x0026,0x002C,0x003c

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_buffer_config#

int32_t rsi_wlan_buffer_config (void , dynamic_rx_pool, dynamic_global_pool)

Configure the TX ,RX global buffers ratio. This is a blocking API.

• rsi_wlan_buffer_config() API needs to be called after opermode command only

Returns

• Non-Zero Value - Failure 0 - Success -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not availableto serve the command If return value is greater than zero : 0x0021

Note

• Refer to Error Codes section for the description of the above error codes Error Codes Parameters given here are used internally by the API

rsi_wlan_ap_start#

int32_t rsi_wlan_ap_start (int8_t * ssid, uint8_t channel, rsi_security_mode_t security_type, rsi_encryption_mode_t encryption_mode, uint8_t * password, uint16_t beacon_interval, uint8_t dtim_period)

Start the module in access point mode with the given configuration. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

The following table maps the channel number to the actual radio frequency in the 2.4 GHz spectrum#

The following table maps the channel number to the actual radio frequency in the 5 GHz spectrum#

Note

• DFS channels are not supported in AP mode.

Returns

• Non-Zero Value - Failure 0 - Success -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not availableto serve the command

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_power_save_with_listen_interval#

int32_t rsi_wlan_power_save_with_listen_interval (uint8_t psp_mode, uint8_t psp_type, uint16_t listen_interval)

Set the power save profile in WLAN mode with listen interval-based wakeup. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

Note

• Valid only if BIT (7) in join_feature_bit_map is set. This value is given in time units (1024 microsecond). Used to configure sleep duration in power save and should be less than the listen interval configured by RSI_LISTEN_INTERVAL Macro in join command parameters in rsi_wlan_config.h file.

• 1. psp_type is only valid in psp_mode 1 and 2.

• 2. psp_type UAPSD is applicable only if WMM_PS is enabled in rsi_wlan_config.h file.

• 3. In RSI_MAX_PSP mode, Few access points will not aggregate the packets, when power save is enabled from STA. This may cause the drop in throughputs.

• 4. For the power save mode 3, select RSI_SLEEP_MODE_2 in psp_mode and RSI_HAND_SHAKE_TYPE as MSG_BASED in rsi_wlan_config.h file.

• 5. For the power save mode 9, select RSI_SLEEP_MODE_8 in psp_mode and RSI_HAND_SHAKE_TYPE as MSG_BASED in rsi_wlan_config.h file.

• 6. For the deep sleep without ram retention case, select RSI_SLEEP_MODE_10 in psp_mode and RSI_HAND_SHAKE_TYPE as MSG_BASED for msg_based or GPIO_BASED for gpio_based.

• 7. For LP sleep, select RSI_SLEEP_MODE_2 in psp_mode, select RSI_SELECT_LP_OR_ULP_MODE as RSI_LP_MODE and RSI_HAND_SHAKE_TYPE as MSG_BASED/GPIO_BASED in rsi_wlan_config.h file.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not available to serve the command

rsi_wlan_power_save_profile#

int32_t rsi_wlan_power_save_profile (uint8_t psp_mode, uint8_t psp_type)

Set the power save profile in WLAN mode. This is a blocking API.

• rsi_wireless_init() API needs to be called before this API.

Enhanced max psp#

Enhanced max PSP is recommended. This essentially a MAX PSP mode but switches to Fast PSP mode if AP does not deliver data within 20ms for PS-Poll. To enable this mode, follow procedure below: Add ENABLE_ENHANCED_MAX_PSP (BIT(26)) in RSI_CONFIG_FEATURE_BITMAP Set psp_type to RSI_FAST_PSP (1) Configure Monitor interval by RSI_MONITOR_INTERVAL in rsi_wlan_config.h file. (default value is 50 ms) Note

• 1. psp_type is only valid in psp_mode 1 and 2.

• 2. psp_type UAPSD is applicable only if WMM_PS is enabled in rsi_wlan_config.h file.

• 3. In RSI_MAX_PSP mode, Few Access points won't aggregate the packets, when power save is enabled from STA. This may cause the drop in throughputs.

• 4. For the power save mode 3, select RSI_SLEEP_MODE_2 in psp_mode and RSI_HAND_SHAKE_TYPE as MSG_BASED in rsi_wlan_config.h file.

• 5. For the power save mode 9, select RSI_SLEEP_MODE_8 in psp_mode and RSI_HAND_SHAKE_TYPE as MSG_BASED in rsi_wlan_config.h file.

• 6. For the deep sleep without ram retention case, select RSI_SLEEP_MODE_10 in psp_mode and RSI_HAND_SHAKE_TYPE as MSG_BASED for msg_based or GPIO_BASED for gpio_based.

• 7. For LP sleep, select RSI_SLEEP_MODE_2 in psp_mode, select RSI_SELECT_LP_OR_ULP_MODE as RSI_LP_MODE and RSI_HAND_SHAKE_TYPE as MSG_BASED/GPIO_BASED in rsi_wlan_config.h file.

• Powersave handshake option:

  • When sleep clock source is configured to '32KHz bypass clock on UULP_VBAT_GPIO_3', use UULP_VBAT_GPIO_0 for SLEEP_IND_FROM_DEV set RS9116_SILICON_CHIP_VER in 'RS9116.NB0.WC.GENR.OSI.X.X.X\host\sapis.h' to 'CHIP_VER_1P4_AND_ABOVE'

  • If not using external clock on UULP_VBAT_GPIO_3' as sleep clock source, use UULP_VBAT_GPIO_3 for SLEEP_IND_FROM_DEV set RS9116_SILICON_CHIP_VER in 'RS9116.NB0.WC.GENR.OSI.X.X.X\host\sapis.h' to 'CHIP_VER_1P3'. EXT_FEAT_LOW_POWER_MODE is not supported for 1.3 version chipset(CHIP_VER_1P3).

Power save modes description#

• Power Save Mode 0 In this mode, module is active and power save is disabled. It can be configured any time, while the module is configured in Power Save mode 2 or 8.

• Power save Mode 1 Once the module is configured to power save mode 1, it wakes up periodically based upon the DTIM interval configured in connected AP. In power mode 1, only the RF of the module is in power save while SOC continues to work normally. This command has to be given only when module is in connected state (with the AP). After having configured the module to power save mode, the Host can issue subsequent commands. In power save mode 1 the module can receive data from host at any point of time but it can send/receive the data to/from remote terminal only when it is awake at DTIM intervals.

• Power Save Mode 2 Once the module is configured to power save mode 2, it can be woken up either by the Host or periodically during its sleep-wakeup cycle. Power Save mode 2 is GPIO based. In case of GPIO based mode, whenever host wants to send data to module, it gives wakeup request by asserting UULP GPIO #2. After wakeup, if the module is ready for data transfer, it sends wakeup indication to host by asserting UULP GPIO #3 or UULP GPIO #0. Host is required to wait until module gives wakeup indication before sending any data to the module. After the completion of data transfer, host can give sleep permission to module by de-asserting UULP GPIO #2. After recognizing sleep permission from host, module gives confirmation to host by de-asserting UULP GPIO #3 or UULP GPIO #0 and again goes back to its sleep-wakeup cycle. Module can send received packets or responses to host at any instant of time. No handshake is required on Rx path.

• Power Save mode 3 Power Mode 3 is message based power save. In Power Mode 3, both radio and SOC of RS9116-WiSeConnect are in power save mode. This mode is significant when module is in associated state with AP. Module wakes up periodically upon every DTIM and gives wakeup message ("WKP") to host. Module can not be woken up asynchronously. Every time module intends to go to sleep it sends a sleep request message ("SLP") to the host and expects host to send the acknowledgement message ("ACK"). Host either send acknowledgement ("ACK") or any other pending message. But once ACK is sent, Host should not send any other message unless next wakeup message from module is received. Module shall not go into complete power-save state, if ACK is not received from host for given sleep message. Module can send received packets or responses to host at any instant of time. No handshake is required on Rx path.

• Power Save mode 8 In Power save mode 8, both RF and SOC of the module are in complete power save mode. This mode is significant only when module is in un-connected state. Power Save mode 8 can be GPIO based. In case of GPIO based, host can wakeup the module from power save by asserting UULP GPIO #2. After wakeup, if the module is ready for data transfer, it sends wakeup indication to host by asserting UULP GPIO #3 or UULP GPIO #0. Host is required to wait until module gives wakeup indication before sending any data to the module. After the completion of data transfer, host can give sleep permission to module by de-asserting UULP GPIO #2. After recognizing sleep permission from host, module gives confirmation to host by de-asserting UULP GPIO #3 or UULP GPIO #0 and again goes back to its sleep-wakeup cycle. Module can send received packets or responses to host at any instant of time. No handshake is required on Rx path.

• Power save mode 9 In Power Mode 9 both Radio and SOC of RS9116-WiSeConnect are in complete power save mode. This mode is significant when module is not connected with any AP. Once power mode 9 command is given, the module sends ("SLP") request to host and wait for the ("ACK") from host and goes to sleep when ACK is given by host. Timer starts when power save command is issued and it can be configured by host using rsi_wlan_set_sleep_timer API. If host does not set any sleep time, then the timer is configured for 3sec by default. Upon wakeup module sends a wakeup message to the host and expects host to give ACK before it goes into next sleep cycle. Host either send ACK or any other messages but once ACK is sent no other packet should be sent before receiving next wakeup message. When ulp_mode_enable is set to '2', after waking up from sleep, the module sends WKP FRM SLEEP message to host when RAM retention is not enabled. After receiving WKP FRM SLEEP message, host needs to start giving commands from beginning (opermode) as module's state is not retained. Returns

  • 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid parameters -3 - Command given in wrong state -4 - Buffer not available to serve the command If return value is greater than 0 0x0021,0x0025,0x002C,0xFFF8,0x0015,0x0026,0x0052

  Note

  • If the user wants to enable power save in CoEx mode (WLAN + BT LE) mode - It is mandatory to enable WLAN power save along with BT LE power save.

  • The device will enter into power save if and only if both protocol (WLAN, BLE) power save modes are enabled.

  • Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_power_save_disable_and_enable#

int32_t rsi_wlan_power_save_disable_and_enable (uint8_t psp_mode, uint8_t psp_type)

Disable or enable the power save feature. This is a blocking API.

• rsi_wlan_power_save_profile() API needs to be called before this API.

Returns

• Non-Zero Value - Failure 0 - Success

rsi_transmit_test_start#

int32_t rsi_transmit_test_start (uint16_t power, uint32_t rate, uint16_t length, uint16_t mode, uint16_t channel)

Start the transmit test. This is a blocking API. This API is relevant in PER mode.

• rsi_wlan_radio_init() API needs to be called before this API.

Note

• 1. User can configure the maximum power level allowed for the given frequncey in the configured region by providing 127 as power level

• 2. User should configure a minimum delay (approx. 10 milliseconds) before and after rsi_transmit_test_start API to observe a stable output at requested dBm level.

Note

• 1. Rate flags can be added in rsi_wlan_common_config.h file i. BIT(6) - Immediate Transfer, set this bit to transfer packets immediately ignoring energy/traffic in channel

• 2. Before starting Continuous Wave mode, user must start Continuous mode with power and channel values that are intended to be used in Continuous Wave mode i.e. i. Start Continuous mode with intended power value and channel values - Pass any valid values for rate and length. ii. Stop Continuous mode iii Start Continuous Wave mode

• 3. If user wants to switch continuous wave mode, first need to stop the per mode and again need to give continous wave mode which user wants to switch.

Data Rates#

The following table maps the channel number to the actual radio frequency in the 2.4 GHz spectrum.#

Note

• To start transmit test in 12,13,14 channels, configure set region parameters in rsi_wlan_config.h

The following table maps the channel number to the actual radio frequency in the 5 GHz spectrum for 20MHz channel bandwidth. The channel numbers in 5 GHz range is from 36 to 165.#

Returns

• 0 - Success Non-Zero Value - Failure If less than zero -4 - Buffer not available to serve the command If greater than zero 0x000A, 0x0021, 0x0025, 0x002C

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_transmit_test_stop#

int32_t rsi_transmit_test_stop (void )

Stops the transmit test. This is a blocking API.

Note

• This API is relevant in PER mode.

• rsi_wlan_radio_init() API needs to be called before this API.

Returns

• 0 Successful execution of the command Non Zero Value Failure if return value is less than 0 -4: Buffer not available to serve the command If return value is greater than 0 0x0021, 0x0025, 0x002C

Note

• 1. User should configure a minimum delay (approx. 10 milliseconds) before and after rsi_transmit_test_start API to observe a stable output at requested dBm level.

• 2. Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_receive_stats_start#

int32_t rsi_wlan_receive_stats_start (uint16_t channel)

Get the Transmit (TX) & Receive (RX) packets statistics.When this API is called by the host with valid channel number, the module gives the statistics to the host for every 1 second asynchronously. If wlan_receive_stats_response_handler() is registered through rsi_wlan_register_callbacks(), it's a non blocking, otherwise, a blocking call.

• rsi_wlan_radio_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4: Buffer not available to serve the command If return value is greater than 0 0x0021, 0x0025, 0x002c, 0x000A

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_receive_stats_stop#

int32_t rsi_wlan_receive_stats_stop (void )

Stop the Transmit (TX) & Receive(RX) packets statistics. if wlan_receive_stats_response_handler() is registered through rsi_wlan_register_callbacks(), it's non blocking, otherwise, a blocking call.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4: Buffer not available to serve the command If return value is greater than 0 0x0021, 0x0025, 0x002c

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_wfd_start_discovery#

int32_t rsi_wlan_wfd_start_discovery (uint16_t go_intent, int8_t * device_name, uint16_t channel, int8_t * ssid_post_fix, uint8_t * psk, void(*)(uint16_t status, uint8_t *buffer, const uint32_t length) wlan_wfd_discovery_notify_handler, void(*)(uint16_t status, uint8_t *buffer, const uint32_t length) wlan_wfd_connection_request_notify_handler)

Start discovery in wi-fi direct mode.This is a non-blocking API. wlan_wfd_discovery_notify_handler() rsi_wlan_wfd_start_discovery() API is registered through rsi_wlan_register_callbacks(), its non blocking, otherwise blocking call.

• rsi_wireless_init() API needs to be called before this API.

  Parameter	Description
  go_intent	Determine whether the device is intended to form a GO (group owner) or work as a Wi-Fi Direct Peer node.
  Value used in the GO negotiation process, when the module negotiates with another Wi-Fi Direct Node on who would become the Group Owner.
  Valid range of values for this parameter is: 0 to 16. Higher the number, higher is the willingness of the module to become a GO.
  After the module becomes a GO in Wi-Fi Direct mode, it appears as an Access Point to the client devices.
  If the number is between 0 and 15, a GO negotiation takes place. If the value is 16, the module forms an Autonomous GO without negotiating with any other device.
  device_name	Device name for the module. The maximum length of this field is 32 characters and the remaining bytes are filled with 0x00.
  Another Wi-Fi Direct device would see this name when it scans for Wi-Fi Direct nodes.
  channel	Operating channel number. The specified channel is used if the device becomes a GO or Autonomous GO
  ssid_post_fix	Used to add a postfix to the SSID in Wi-Fi Direct GO mode and Autonomous GO mode.
  psk	Passphrase of a maximum length of 63 characters (a null character should be supplied to make it 64 bytes in the structure).
  PSK used if the module becomes a GO owner.
  wlan_wfd_discovery_notify_handler	Asynchronous message sent from module to the host when module finds any Wi-Fi Direct node.
  Parameters involved are status, buffer. & length
  status	Response status. If status is zero, it means that the wfd device response has some device information
  buffer	Response buffer.
  Length	Response buffer length
  wlan_wfd_connection_request_notify_handler	Asynchronous message sent from module to the host when module receives a connection request from any remote Wi-Fi Direct node.
  Parameters involved are status, buffer, & length
  status	Response status. If status is zero, it means that the connection request has come from some device.
  buffer	Response buffer
  length	Response buffer length

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -3 - Command given in wrong state -4 - Buffer not available to serve the command If return value is greater than 0 0x001D, 0x0021, 0x002C, 0x0015

rsi_wlan_wfd_connect#

int32_t rsi_wlan_wfd_connect (int8_t * device_name, void(*)(uint16_t status, const uint8_t *buffer, const uint16_t length) join_response_handler, device_name, join_response_handler, status, buffer, length, <nodetype>)

A join_response_handler() API that connects to the specified Wi-Fi-Direct device.This is a non-blocking API. if join_response_handler() is registered through rsi_wlan_register_callbacks(), it's non blocking, otherwise, a blocking call.

• rsi_wlan_wfd_start_discovery() API needs to be called before this API.

Note

• The module gets a default IP of 192.168.100.76 if it becomes a Group Owner or Access Point in case of IPv4. and gets a default IP of 2001:db8:0:1:0:0:0:120 in case of IPv6.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4 - Buffer not available to serve the command If return value is greater than 0 0x0014, 0x0009, 0x0003, 0x0021, 0x0012c 0x0015

rsi_wlan_send_data#

int32_t rsi_wlan_send_data (uint8_t * buffer, uint32_t length)

Send the raw data in TCP/IP bypass mode. This is a blocking API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid Parameters -4 - Buffer not available to serve the command If return value is greater than 0 0x0021,0x002C,0x0025

rsi_wlan_ping_async#

int32_t rsi_wlan_ping_async (uint8_t flags, uint8_t * ip_address, uint16_t size, void(*)(uint16_t status, const uint8_t *buffer, const uint16_t length) wlan_ping_response_handler, status, buffer, length)

Send a ping request to the target IP address. If wlan_ping_response_handler() is registered through rsi_wlan_register_callbacks(), it's non blocking, otherwise, a blocking call.

• rsi_config_ipaddress() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid parameters -4 - Buffer not available to serve the command If return value is greater than 0 0x0015,0xBB21,0xBB4B,0xBB55

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_register_auto_config_rsp_handler#

void rsi_register_auto_config_rsp_handler (void(*)(uint16_t status, uint8_t state) rsi_auto_config_rsp_handler, status, state)

Register auto-configuration response handler.. This is a non-blocking API.

Returns

• Void

rsi_wlan_add_profile#

int32_t rsi_wlan_add_profile (uint32_t type, uint8_t * profile)

Add profile for auto configuration. This is a blocking API.

Note

• This API is not supported in current release.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure -4 - Buffer not availableto serve the command

rsi_wlan_get_state#

uint8_t rsi_wlan_get_state (void )

Get the current WLAN state.. This is a non-blocking API.

Returns

• Return the current WLAN state. WLAN states are as follows: RSI_WLAN_STATE_NONE = 0, RSI_WLAN_STATE_OPERMODE_DONE, RSI_WLAN_STATE_BAND_DONE, RSI_WLAN_STATE_INIT_DONE, RSI_WLAN_STATE_SCAN_DONE, RSI_WLAN_STATE_CONNECTED, RSI_WLAN_STATE_IP_CONFIG_DONE, RSI_WLAN_STATE_IPV6_CONFIG_DONE, RSI_WLAN_STATE_AUTO_CONFIG_GOING_ON, RSI_WLAN_STATE_AUTO_CONFIG_DONE, RSI_WLAN_STATE_AUTO_CONFIG_FAILED

rsi_wlan_get_profile#

int32_t rsi_wlan_get_profile (uint32_t type, rsi_config_profile_t * profile_rsp, uint16_t length)

Get the stored config profile. This is a blocking API.

Note

• This API is not supported in current release.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4 - Buffer not available to serve the command

rsi_fill_config_profile#

uint8_t* rsi_fill_config_profile (uint32_t type, uint8_t * profile_buffer)

Fill the config profile based on the profile type.. This is a non-blocking API.

• rsi_wireless_init() API needs to be called before this API.

Returns

• profile_buffer

rsi_wlan_delete_profile#

int32_t rsi_wlan_delete_profile (uint32_t type)

Delete stored configuration based on profile type. This is a blocking API.

Note

• This API is not supported in current release.

• rsi_wireless_init() API needs to be called before this API.

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -4 - Buffer not available to serve the command

rsi_wlan_enable_auto_config#

int32_t rsi_wlan_enable_auto_config (uint8_t enable, uint32_t type)

Enable or disable auto-config with respect to profile. This is a blocking API.

• rsi_wlan_set() API needs to be called before this API.

Note

• Currently Profile based feature is not supported.

Returns

• 0 - Success Non-Zero Value - Failure -4 - Buffer not available to serve the command

Note

• If user tries to give any other command during autojoin, then user gets error 0x002C. To avoid this, user have to disable auto_join feature and give other commands.

• The parameters of the following APIs are saved when rsi_wlan_enable_auto_config() is called: rsi_wireless_init(), rsi_wlan_scan(), rsi_wlan_scan_with_bitmap_options(), rsi_wlan_connect(), rsi_config_ipaddress(), rsi_wireless_antenna(), rsi_wlan_bgscan_profile(), rsi_radio_caps(), rsi_wlan_ap_start

rsi_wlan_pmk_generate#

int32_t rsi_wlan_pmk_generate (int8_t type, int8_t * psk, int8_t * ssid, uint8_t * pmk, uint16_t length, 32-byte)

Generate PMK if PSK and SSID are provided. This is a blocking API.

• rsi_wlan_connect() API needs to be called before this API.

Returns

• 0 - Successful execution of the command. If TYPE value is 3. Non-Zero Value - Failure If return value is greater than 0 0x0021, 0x0025,0x0026,0x0028,0x002C,0x0039,0x003a, 0x003b

Note

• Refer to Error Codes section for the description of the above error codes Error Codes.

rsi_wlan_set_sleep_timer#

int16_t rsi_wlan_set_sleep_timer (uint16_t sleep_time)

Configure the sleep timer mode of the module to go into sleep during power save operation. This is a blocking API.

• Can be issued any time in case of power save mode 9 (MSG_BASED).

Returns

• 0 - Success Non-Zero Value - Failure

rsi_wlan_register_callbacks#

uint16_t rsi_wlan_register_callbacks (uint32_t callback_id, void(*)(uint16_t status, uint8_t *buffer, const uint32_t length) callback_handler_ptr, status, buffer, length, (void*)callback_handler_ptr)

Register the WLAN callback functions. This is a non-blocking API.

Note

• Refer to Error Codes section for the description of the above error codes Error Codes

Prototypes of the callback functions with given callback id#

RSI_WLAN_ASYNC_STATS#

• Asychronous messages are used to indicate module state to host. Asynchronous message are enabled by setting bit 10 of the custom feature bitmap in opermode. • In async messages time_stamp, state_code, reason_code, rsi_channel, rsi_rssi and rsi_bssid are logged.

• time_stamp (4 bytes)

  • This is the value of the time stamp counter at the time of message; timestamps increment at intervals of 100ms.

• state_code (1 byte)

  • This field indicates the state of the module. state_code contains two parts, the upper nibble and lower nibble.

  • The upper nibble indicates the state of the rejoin process. The following table documents the possible values of the upper nibble of state_code.

    State	Upper Nibble	Indication
    Scan Trigger (State I)	0x00	Startup. Initial Roam
    0x10	Beacon Loss. Failover Roam
    0x20	De-authentication. AP induced roam / Disconnect from supplicant
    Scan Result/Decision (State II)	0x50	Current AP is best
    0x60	Better AP found
    0x70	No AP found
    Final Connection (State III)	0x80	Associated
    0x90	Unassociated

  • The lower nibble of state_code indicates the reason for a state change. The following table documents the possible values of the lower nibble of state_code.

    Lower Nibble	Reason for State Change
    0x00	No reason specified
    0x01	No response from AP for authentication request(Authentication denial)
    0x02	Association denial
    0x03	User configured AP is not present
    0x05	EAPOL TX failure
    0x06	Deauthentication from user
    0x07	PSK not configured
    0x08	key-handshake failure during rejoin/roaming/after connection(Disconnection from supplicant)
    0x09	Roaming not enabled

• reason_code (1 byte)

  • Indicates the reason for a failure.

  • These failures also include EAP connection errors for certificate parsing.

  • All supported reason codes are listed below

    reason_code	Reason codes
    0x00	No reason specified
    0x01	No response from AP for authentication request(Authentication denial)
    0x02	Association denial
    0x03	User configured AP is not present
    0x05	EAPOL TX failure
    0x06	Deauthentication from user
    0x07	PSK not configured
    0x08	key-handshake failure during rejoin/roaming/after connection(Disconnection from supplicant)
    0x09	Roaming not enabled
    0x10	Beacon Loss (failover Roam)
    0x20	De-authentication (AP induced Roam/Deauth from supplicant)
    0x28	TLS CA Cert not present
    0x29	TLS PRIVATE key not present
    0x2A	TLS Client Cert not present
    0x2B	TLS no Cert present
    0x2C	PEAP CA Cert not present
    0x2D	Server Cert Invalid Key Type
    0x2E	Server Intermediate CA Invalid Key Type
    0x2F	Server Root CA Invalid Key Type
    0x30	Client Cert Invalid Key Type
    0x31	Client Root CA Invalid Key Type
    0x32	FIPS Server Cert Invalid Length
    0x33	FIPS Server Intermediate CA Invalid Length
    0x34	FIPS Server Root CA Invalid Length
    0x35	FIPS Client Cert Invlaid Length
    0x36	FIPS Client Root CA Invalid Length
    0x37	Server Cert 4096-bit length support is not enabled
    0x38	Server Intermediate CA 4096-bit length support is not enabled
    0x39	Server Root CA 4096-bit length support is not enabled
    0x3A	Client Cert 4096-bit length support is not enabled
    0x3B	Client Root CA 4096-bit length support is not enabled
    0x3C	Server Cert Invalid Sign Alg
    0x3D	Server Intermediate CA Invalid Sign Alg
    0x3E	Server Root CA Invalid Sign Length
    0x3F	Client Cert Invalid Sign Alg
    0x40	Client Root CA Invalid Sign Length
    0x41	Server Intermediate CA not Present
    0x42	Server Root CA Parse Error
    0x43	Server Intermediate Root CA Parse Error
    0x44	Sever Cert Parse Error
    0x45	Client Cert Parse Error
    0x46	Incorrect Private Key Password
    0x47	EAP Failure Received
    0x48	Client Cert Bad Date Error
    0x49	Server Cert Bad Date Error
    0x4A	Server Root CA Bad Date Error
    0x4B	Client Root CA Bad Date Error
    0x4C	Server Intermediate Root CA Bad Date Error
    0x4D	Pem Header Error
    0x4E	Pem Footer Error
    0x4F	Client Intermediate CA Invalid Sign Length
    0x50	Client Intermediate CA Invalid Length
    0x51	FIPS Client Intermediate CA Invalid Length
    0x52	Client Intermediate CA invalid Key Type
    0x53	Pem Error

  • In addition to the above, reason code received in Deauthentication/Disassociation frame from AP is added. This will set the MSB bit of reason_code.

  • If MSB bit is set in reason code, then mask it with 0x7f to get the acutal reason code received in Deauthentication/Disassociation frame.

  • In RS9116 Rev 1.4, above reason codes will come only in TCP/IP bypass mode.

  • Pem Header Error(0x4D) or Pem Footer Error(0x4E) are only applicable if certificates are loaded individually. In case if certificates are loaded combinedly in a single file, only Pem Error(0x53) will be triggered for Header or Footer errors.

rsi_wlan_update_gain_table#

int32_t rsi_wlan_update_gain_table (uint8_t band, uint8_t bandwidth, uint8_t * payload, uint16_t payload_len)

Assign the user configurable channel gain values in different regions to the module from user.This method is used for overwriting default gain tables that are present in firmware. Customer can load all the three gain tables (i.e., 2.4GHz-20Mhz, 5GHz-20Mhz, 5GHz-40Mhz) one after other by changing band and bandwidth values. This is a blocking API.

Note

• 1. This frame has to be used by customers who has done FCC/ETSI/TELEC/KCC certification with their own antenna. All other customers should not use this. Inappropriate use of this frame may result in violation of FCC/ETSI/TELEC/KCC or any certifications and Silicon labs is not liable for that

• Internally firmware maintains two tables : Worldwide table & Region based table. Worldwide table is populated by firmware with Max power values that chip can transmit that meets target specs like EVM. Region based table has default gain value set.

  1. When certifying with user antenna, Region has to be set to Worldwide and sweep the power from 0 to 21dBm. Arrive at max power level that is passing certification especially band-edge.

  2. These FCC/ETSI/TELEC/KCC Max power level should be loaded in end-to-end mode via WLAN User Gain table. This has to be called done every boot-up since this information is not saved inside flash. Region based user gain table sent by application is copied onto Region based table .SoC uses this table in FCC/ETSI/TELEC/KCC to limit power and not to violate allowed limits. For Worldwide region firmware uses Worldwide table for Tx. For other regions(FCC/ETSI/TELEC/KCC), Firmware uses min value out of Worldwide & Region based table for Tx. Also there will be part to part variation across chips and offsets are estimated during manufacturing flow which will be applied as correction factor during normal mode of operation.

• rsi_radio_init() API needs to be called before this API

Gain Table Payload Format#

           1. Gain table Format for 2.4G Band: (Each entry of the table is 1 byte)
              In 2Ghz, Max Gain/Power obtained from certification should be doubled and loaded.
           <TABLE NAME[]>= {
           <NO.of Regions>,
           <REGION NAME 1>, <CHANNEL_CODE_2G>,
           <CHANNEL NUMBER 1>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>, 
           <CHANNEL NUMBER 2>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>, 
           . 
           . 
           .
           .
           .       
           <CHANNEL NUMBER m-1>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>,
           <CHANNEL NUMBER m>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>, 
           <REGION NAME 2>, <CHANNEL_CODE_2G>,
           <CHANNEL NUMBER 1>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>,
           <CHANNEL NUMBER 2>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>,
           . 
           . 
           . 
           . 
           <CHANNEL NUMBER m-1>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>,
           <CHANNEL NUMBER m>, <2 * MAX POWER FOR b RATE>, <2 * MAX POWER FOR g RATE>, <2 * MAX POWER FOR n RATE>, 
           }; 

           Gain table Format for 5G Band: (Each entry of the table is 1 byte)
             In 5Ghz, Max Gain/Power obtained from certification should be loaded.
            <TABLE NAME[]>= { 
                              <NO.of Regions>, 
                              <REGION NAME 1>, <CHANNEL_CODE_5G>, 
                              <CHANNEL NUMBER IN BAND 1 IF ANY>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                               <BAND_NUMBER 1>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              <CHANNEL NUMBER IN BAND 2 IF ANY>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              <BAND_NUMBER 2>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              <CHANNEL NUMBER IN BAND 3 IF ANY>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              <BAND_NUMBER 3>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              <CHANNEL NUMBER IN BAND 4 IF ANY>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              <BAND_NUMBER 4>, <MAX POWER FOR 11a RATE>, <MAX POWER FOR n RATE>, 
                              . 
                              . 
                              . 
                              . 
                              . 
                              <REGION NAME y>, <CHANNEL_CODE_5G>, 
                              }; 
           2. Supported Region names:
                                   FCC, ETSI,TELEC, KCC 
                                  The following are the regions and the values to be passed instead of macros in the example.
                                  Region      |          Macro Value
                                  ------------|--------------------
                                  FCC         |            0
                                  ETSI        |            1
                                  TELEC       |            2
                                  KCC         |            4
           3. <CHANNEL_CODE_2G> is a 8 bit value which is encoded as:
              If TX powers of all the channels are same, then use CHANNEL_CODE_2G as 17. In this case, mention channel number as 255.
              Tf TX power is not same for all channels, then indicate CHANNEL_CODE_2G as no-of channels. And specify tx power values for all the channels indicated.
           4. <CHANNEL_CODE_5G> is a 8 bit value encoded as number of rows in a region for 5G band.
               a. 5G is divided into 4 sub bands: 
                     band 1: channel number <= 48 
                     band 2: channel number > 48 and channel number <= 64 
                     band 3: channel number > 64 and channel number <= 144 
                     band 4: channel number > 144 
               b. If any channel in a band has different set of power values, specify the channel number followed by power values. 
               c. If all the channels in a band 1 has same power values, specify the band number as 1 followed by power value. 
               d. If all the channels in a band 2 has same power values, specify the band number as 2 followed by power value. 
               e. If all the channels in a band 3 has same power values, specify the band number as 3 followed by power value. 
               f. If all the channels in a band 4 has same power values, specify the band number as 4 followed by power value.

Example payload formats#

                       Examples: 
                     For 2.4Ghz Band in 20Mhz bandwidth
                       {3, //NUM_OF_REGIONS 
                           FCC, 13, //NUM_OF_CHANNELS 
                       //   rate,  11b, 11g, 11n   
                               1,  34,  20,  20,  
                               2,  34,  28,  28,  
                               3,  34,  32,  32,  
                               4,  34,  36,  36,  
                               5,  34,  38,  38,  
                               6,  34,  40,  40,  
                               7,  34,  38,  38,  
                               8,  34,  36,  36,  
                               9,  34,  32,  32,  
                               10, 34,  32,  32,  
                               11, 34,  24,  24,  
                               12, 34,  16,  24,  
                               13, 34,  12,  12,  
                           TELEC, 17, 
                                255, 20,  16, 16, 
                           KCC, 17, 
                                255, 26,  20, 20, 
                       }; //}}} 

                     For 5Ghz band in 20Mhz bandwidth
                        {2, 
                        FCC, 6, 
                            1,  9, 10, //band 1 
                            2,  8,  9, //band 2 
                          100,  4,  4, //band 3 
                            3,  6,  8, //band 3 
                          149,  3,  3, //band 4 
                        TELEC, 4, 
                          1, 9, 10, //band 1 
                          2, 8, 10, //band 2   
                          3, 6,  8, //band 3   
                          4, 6,  7, //band 4 
                        };


                     For 5Ghz band in 40Mhz bandwidth
                        {2, 
                        FCC, 8, 
                            1,  9, 10, //band 1 
                           62,  8,  9, //band 2 
                            2,  8,  9, //band 2 
                          102,  4,  4, //band 3 
                          134,  6,  8, //band 3 
                            3,  6,  8, //band 3 
                          151,  3,  3, //band 4    
                            4,  6,  7, //band 4    
                        TELEC, 4, 
                           1, 9, 10, //band 1 
                           2, 8, 10, //band 2  
                           3, 6,  8, //band 3  
                           4, 6,  7, //band 4 
                        }; 

Customers using Certified MARS antenna should use the gain table structures below:#

                     For 2.4Ghz Band in 20Mhz bandwidth
                      {3,//NUM_OF_REGIONS
                          FCC, 0xD,//NUM_OF_CHANNELS
                      //   rate,  11b, 11g, 11n
                              1,  28,  32,  30,
                              2,  28,  32,  30,
                              3,  28,  32,  30,
                              4,  30,  28,  34,
                              5,  30,  28,  34,
                              6,  30,  28,  34,
                              7,  30,  28,  34,
                              8,  30,  28,  34,
                              9,  28,  30,  30,
                              10, 28,  30,  30,
                              11, 28,  30,  30,
                              12, 28,  30,  30,
                              13, 28,  30,  30,
                          TELEC,0x11, //NA
                               255, 20,  16, 16,
                          KCC, 0x11   //NA,
                               255, 26,  20, 20
                      };

                     For 5Ghz band in 20Mhz bandwidth
                      {2,
                      FCC, 0x6,
                          1, 12, 12, //band 1
                          2, 11, 11, //band 2   
                        100, 10, 12, //band 3   
                          3, 13, 13, //band 3   
                        140, 10, 11, //band 4   
                          4, 13, 13, //band 4   
                      TELEC, 0x4, //NA
                        1, 9, 10, //band 1
                        2, 8, 10, //band 2   
                        3, 6,  8, //band 3   
                        4, 6,  7, //band 4
                      };


                     For 5Ghz band in 40Mhz bandwidth
                      {2,
                      FCC, 0x8,   
                          1,  9,  9, //band 1
                         62,  8,  8, //band 2   
                          2,  9,  9, //band 2   
                        102,  9,  9, //band 3   
                        134, 12, 12, //band 3   
                          3, 10, 10, //band 3   
                        151, 11, 11, //band 4       
                          4, 11, 11, //band 4       
                      TELEC, 0x4, //NA  
                         1, 9, 10, //band 1
                         2, 8, 10, //band 2   
                         3, 6,  8, //band 3   
                         4, 6,  7, //band 4
                      };

Note

• 1. Length of the payload should match with payload_len parameter value.

• 2. In 2.4Ghz band, 40Mhz is not supported

Returns

• 0 - Success Non-Zero Value - Failure If return value is less than 0 -2 - Invalid parameters -3 - Command given in wrong state If return value is greater than 0 0x0021, 0x003E

Note

• Refer to Error Codes section for above error codes Error Codes.

rsi_wlan_csi_config_async#

int32_t rsi_wlan_csi_config_async (uint8_t enable, uint32_t periodicity, void(*)(uint16_t status, uint8_t *buffer, const uint32_t length) wlan_csi_data_response_handler)

Enable or disable CSI data retrieval with configured periodicity.

• rsi_wlan_scan() API needs to be called before this API.

Note

• Callback implementation example - void rsi_wlan_csi_data_response_handler(uint16_t status, rsi_rsp_csi_data_t *payload, const uint32_t payload_length)

Note

• rsi_rsp_csi_data_s : Structure type supposed to hold incoming CSI data

Returns

• 0 - Success Non-Zero Value - Failure -1 - Callback not registered -4 - Buffer unavailable to serve the command

Note

• Refer to Error Codes section for the description of the above error codes Error Codes