SAPI Changelog#

This section describes details of changes and enhancements in the RS9116W SAPI library that are likely to impact backward compatibility. To improve developer experience, significant folder structure changes were made in the June 2021 WiSeConnect 2.4 SDK release. A list of additional changes for previous releases is also provided.

SAPI Changelog#

Folder/Filename Changes for Release: 2.4#

The SAPI directory in the root folder of the SDK has been changed from sapis to sapi. The changes listed in the following table were made to files and sub-folders inside the sapi directory.

Previous Name

New Name

Notes

bt_ble

bluetooth

Renamed

Moved bt_ble/rsi_audio_codec to root level third_party/sbc_audio_codec

Moved rsi_bt_sbc_codec.c from root level third_party/sbc_audio_codec to the sapi/bluetooth directory

Removed various unsupported source files for profiles including hfp, hid, iap, sdp and l2cap

build

-

Removed

drivers

drivers

No change

Renamed drivers/intf to drivers/device_interface

Removed various unsupported source files from the package including rsi_zb.c, rsi_zb-utility.c, rsi_iap.c

examples

-

Moved to the root directory of the SDK

hal

-

Moved into root level platforms directory

nwk

network

Renamed

Renamed sapis/nwk/applications to sapi/network/protocols

Moved mqtt_client from sapis/nwk/applications to root level third_party/mqtt_client. In the mqtt_client/src directory, renamed MQTT_Wrappers.c to MQTT_sapi_wrappers.c

Moved aws_sdk from sapis/nwk/applications to root level third_party/aws_sdk

os

rtos

Renamed

Renamed os/free_rtos to rtos/freertos_wrapper

Moved sapis/os/amazon-freertos to root level third_party/amazon-freertos

puf

-

No longer included in the SDK

rom

-

No longer included in the SDK

Modifications for Release: 2.4#

Timeout Error Indication and Recovery Mechanism#

All SAPI command response-timeout errors return 0xFFFFFFE2 if the firmware takes more time than the configured timeout. If a timeout error occurs, the application must reset the device and driver state to recover from the error.

Wi-Fi APIs

Notes

rsi_sort_scan_results_array_based_on_rssi()

Sort the Scan results in the order of RSSI. The application should call this API to get the scan result in sorted order.

Bluetooth APIs

Notes

rsi_bt_a2dp_init()

Initialize A2DP profile with either user defined audio codec parameters or default stack audio codec params. This is a blocking API.

rsi_bt_avrcp_init()

Set the AVRCP profile mode and also enable the media player selection feature, if required. This is a blocking API

rsi_bt_avrcp_set_addr_player_resp()

Send Addressed player response from the Target to Controller. This is a blocking API

rsi_bt_avrcp_get_folder_items_resp()

Send Folder items response from Target to Controller. This is a Blocking API

rsi_bt_avrcp_get_tot_num_items_resp()

Send the response for the total number of items from the Target to Controller. This is a blocking API.

rsi_bt_request_authentication()

The Authentication procedure usually starts from the stack itself after the PHY Level Connection completes, however if authentication is disabled after PHY Level Connection, and Authentication is needed, then firstly enable Authentication then call this API. This is a blocking API.

rsi_bt_encryption_enable_or_disable()

Usually Encryption procedure will start from stack itself once PHY Level Connection and authentication is completed, however the user can decide whether to enable/disable encryption from the host. This is a blocking API.

rsi_bt_per_cw_mode()

Keep the device in continuous wave mode. It is not necessary to call this API if transmit_mode is set to CONTINUOUS_WAVE_MODE in rsi_bt_tx_per_params_s structure.

rsi_bt_vendor_ar_enable()

Issue vendor specific command for setting AutoRate in controller on given inputs. This is a blocking API. A received event rsi_bt_on_ar_stats_t has AutoRate Stats.

rsi_bt_vendor_dynamic_pwr()

Issue vendor specific command for setting dynamic_tx_power_index in controller on given inputs. This is a blocking API.

rsi_bt_vendor_avdtp_stats_enabled()

Issue vendor specific command for setting avdtp stats enable in controller, to receive the stats. This is a blocking API. A received event rsi_bt_on_avdtp_stats_t has AVDTP stats.

System APIs

Notes

rsi_send_freq_offset()

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

rsi_calib_write()

RF Calibration Process. This API commands the firmware to update the existing FLASH/EFuse calibration data. This is a blocking API.

rsi_send_feature_frame_dyn()

Select internal or external RF type and clock frequency to pass Feature enables dynamically. This is a blocking API.

rsi_register_wait_timeout_error_callbacks()

Register SAPI wait timeout handler. This is non-blocking API.

Modifications for Release: 2.3#

Wi-Fi/Network APIs

Notes

Resolution for Backward Compatibility

rsi_wlan_get_status(), rsi_wlan_socket_get_status()

Description: Added support for Socket ID based return status for Socket APIs.

No changes required. By default, both rsi_wlan_get_status() and rsi_wlan_socket_get_status() return the actual status of Socket APIs.

Purpose: To get socket ID based return status for socket APIs. This change is an enhancement.

1.x.x: rsi_wlan_get_status() is used to get the return status of any SAPI command in case of a failure. The same API was used to get socket API status as well.

2.x.x: rsi_wlan_socket_get_status() added to get return status for socket APIs based on socket ID input. Latest SAPI driver stores response for each socket id

Impact: In multi-threaded applications using rsi_wlan_get_status(), may not return exact Socket ID based status, as it may get over-written. Applications should use rsi_wlan_socket_get_status() instead of rsi_wlan_get_status() for getting actual return status for Socket APIs, especially in muti-threaded applications.

Enable 'socket wait close' configuration if using TCP Sockets in Application.

If TCP sockets is used in an application, enable EXT_TCP_IP_WAIT_FOR_SOCKET_CLOSE in RSI_EXT_TCPIP_FEATURE_BITMAP. For enabling RSI_EXT_TCPIP_FEATURE_BITMAP, need to enable TCP_IP_FEAT_EXTENSION_VALID in RSI_TCP_IP_FEATURE_BIT_MAP. These macros are defined in rsi_wlan_config.h

See rsi_shutdown() for details.

Bluetooth APIs

Notes

Resolution for Backward Compatibility

384kB memory requirement

It is mandatory to configure 384kB memory when using BT Classic, BLE and COEX. RS9116W firmware, from 2.X.X release supports only this mode.

In rsi_wlan_config.h set RSI_EXT_CUSTOM_FEATURE_BIT_MAP = EXT_FEAT_384K_MODE. To enable RSI_EXT_CUSTOM_FEATURE_BIT_MAP, set RSI_CUSTOM_FEATURE_BIT_MAP = FEAT_CUSTOM_FEAT_EXTENTION_VALID. If EXT_FEAT_256K_MODE is used, the device may fail to work.

-

-

-

Support for HEX based input BD address in SAPI applications

Purpose: To avoid input BD address conversion from ASCII to HEX as RS9116W expect BD address in HEX format. This change is an enhancement.

Backward compatibility is achieved by BD_ADDR_IN_ASCII in rsi_bt_config.h and rsi_ble_config.h. Enable BD_ADDR_IN_ASCII to take input Bluetooth Address (Device Address) in ASCII format in SAPI based applications. Disable BD_ADDR_IN_ASCII to take input Bluetooth Address (Device Address) in 6 bytes HEX format in SAPI based applications. By default, BD_ADDR_IN_ASCII is not defined in RS9116W SAPI examples and library. Existing users should enable BD_ADDR_IN_ASCII in their applications to ensure SAPI library supports ASCII based BD address input.

1.1.x: RS9116W expects BD address in 6 bytes of HEX as input. But existing SAPI applications expect BD address input in ASCII and coverts it into HEX (internally in SAPI core) and then passes it to RS9116W

2.x: Added support to take the input as a 6 bytes of HEX value which avoids ASCII to HEX conversion.

Impact: Existing designs which are developed with ASCII based BD address input will not work.

-

-

-

BLE data flow mechanism to support flow control and multiple connections

Purpose: To maintain multiple BLE connections and serve them independently, RS9116W firmware and SAPI are enhanced with support for connection based buffer management and flow control between host (application) and RS9116W (firmware). This is an enhancement.

The app needs to use the APIs as described to check for buffer full response from RS9116W device. Device returns RSI_ERROR_BLE_DEV_BUF_FULL to host whenever all buffers associated to that particular connection are occupied. When this error is observed, application should clear RSI_DATA_TRANSMIT_EVENT for that particular connection and should not call the API again until buffers in the device are freed. Once buffers are freed, RS9116W device sends an asynchronous request to host application to indicate device is ready to accept more data from host application. RSI_BLE_MORE_DATA_REQ_EVT is the asynchronous event sent by the device. Upon receiving this event, host application should set RSI_DATA_TRANSMIT_EVENT and resume API calls. For following APIs this flow should be implemented, rsi_ble_get_profiles_async()rsi_ble_get_profile_async()rsi_ble_get_char_services_async()rsi_ble_get_att_value_async()rsi_ble_set_att_value_async()rsi_ble_set_att_cmd()rsi_ble_indicate_value()rsi_ble_notify_value()rsi_ble_set_att_value()rsi_ble_set_att_value_async()

1.1.x: In earlier design, connection based buffer management was not supported. This effects data throughput, connectivity and simultaneous connections in different ways. In this design, when there is a data write request to remote BLE device from application, RS9116W provides response only after receiving the response from the remote device. There was no flow control mechanism in this case and one connection can consume all the buffers in RS9116W impacting other connection's control and data flows.

2.x: In the new design, connection based buffer management is implemented (using dedicated buffers for each connected device ). If there are no buffers available in the RS9116W device, it returns an error to the host with that particular device address, stating that buffers are not available for that connection. Once the buffer are freed (device serves pending events), then the device will send an event (more data request) to the host requesting to send the data

New API/Event: ble_on_le_more_data_req_event

Impact: All existing applications which use attribute write, long write or prepare write should be changed as per the new design, otherwise will not work. This impacts only BLE data flows. Not applicable for BT-Classic.