Migrating from WiSeConnect SDK v4.0.0 to v4.0.2#

Overview#

This guide describes how to update an existing application from WiSeConnect™ SDK v4.0.0 to v4.0.2.

Version 4.0.2 introduces behavioral changes and updated usage constraints on existing APIs, adds new APIs and structures, and deprecates a set of misspelled macro aliases compared to v4.0.0. Several APIs require updated application-level handling.

Note: Version 4.0.1 was an intermediate release with no Wi-Fi SDK deprecations or new public APIs. This guide covers the cumulative changes from v4.0.0 through v4.0.2.

Migration Steps#

Follow these steps to convert a WiSeConnect SDK v4.0.0 application to a v4.0.2 application:

  1. Open your existing application project in Simplicity Studio.

  2. [Mandatory] If your application uses SL_WIFI_SCAN_TYPE_EXTENDED, update the scan callback handler to use data_length to allocate a buffer and retrieve results via sl_wifi_get_stored_scan_results(). Note that the sl_wifi_extended_scan_result_t structure now includes a new seen_count field.

  3. [Mandatory] If your application calls sl_wifi_set_max_tx_power, ensure it is called before sl_wifi_connect or sl_wifi_start_ap.

  4. [Recommended] If your application uses DNS resolution with custom timeouts or retries, consider migrating to the new sl_net_dns_resolve_hostname_v2 API, which provides configurable initial_timeout_sec and retry_count parameters with exponential backoff.

  5. [Recommended] If your application uses MQTT with long passwords, you can now configure passwords up to 512 bytes in sl_mqtt_client_credentials_t. If your application receives large MQTT payloads, the SDK now automatically reassembles fragmented messages up to SL_MQTT_CLIENT_MAX_RX_PAYLOAD_SIZE (default 8192 bytes, user-configurable).

  6. [Recommended] If your application uses sl_wifi_set_11ax_config, note that 802.11ax configuration is now documented as not supported in SL_WIFI_ACCESS_POINT_MODE.

  7. [Recommended] In the project files, update the v4.0.2 deprecated macro spellings with the corresponding *_EXTENSION_VALID equivalents. This step is not mandatory (the misspelled names remain as compatibility aliases) but recommended to ensure compatibility with future releases.

  8. [Recommended] If you have not yet migrated away from the v3.5.3 deprecated APIs listed in the v3.5.3 to v4.0.0 migration guide, we recommend completing that migration before June 2027, the end of the deprecation period for that release.

Refer to the tables in each of the sections that follow, which map the v4.0.0 API elements to v4.0.2. In some instances, the differences between v4.0.0 and v4.0.2 are highlighted in bold text.

New APIs#

Module

API

Description

Network Stack

sl_net_dns_resolve_hostname_v2

Resolves a host name to an IP address with configurable initial_timeout_sec (5–10 seconds) and retry_count parameters. Retry timeouts use exponential backoff (T, 2T, 4T, ..., capped at 45 s per attempt). Set initial_timeout_sec to 0 for asynchronous (non-blocking) behavior.

Updated APIs#

Note: Due to a behavioral change in the extended scan callback, applications using SL_WIFI_SCAN_TYPE_EXTENDED must be updated to use data_length from the callback to size the buffer passed to sl_wifi_get_stored_scan_results.

Module

v4.0.0

v4.0.2

Wi-Fi

For SL_WIFI_SCAN_TYPE_EXTENDED, the scan callback was invoked with data set to NULL and data_length set to 0. The application had no indication of the number of scan results or the buffer size required to retrieve them.

The scan callback is now invoked with data set to NULL and data_length set to the total size of the scan results (i.e., scan count * sizeof(sl_wifi_extended_scan_result_t)). The application must allocate a buffer of size data_length and pass it to sl_wifi_get_stored_scan_results() to retrieve the complete scan results.

Wi-Fi

sl_wifi_set_max_tx_power had no documented calling-order constraint.

Added pre-condition: sl_wifi_set_max_tx_power must be called before sl_wifi_connect or sl_wifi_start_ap.

Wi-Fi

Documented limitations for sl_si91x_select(): supports a maximum of 10 sockets per call; supports read and write fd_sets only (not exceptfds); operates only with connected sockets (listening sockets are not supported).

Wi-Fi

SL_SI91X_CUSTOM_FEAT_SOC_CLK_CONFIG_160MHZ had no documented coexistence constraint.

This configuration is NOT supported in WLAN+BLE coexistence mode.

Wi-Fi

sl_wifi_set_11ax_config had no documented operating mode constraint.

Added documentation: 802.11ax configuration is applicable only to client-capable modes (SL_WIFI_CLIENT_MODE, SL_WIFI_ENTERPRISE_CLIENT_MODE, SL_WIFI_CONCURRENT_MODE). Not supported in SL_WIFI_ACCESS_POINT_MODE.

Wi-Fi

sl_wifi_update_gain_table / sl_wifi_update_su_gain_table gain table documentation for KCC and SRRC regions.

KCC region power values updated. SRRC region code changed from 0x24 to 0x2A with expanded channel/power entries.

Network Stack

Maximum MQTT password length was 60 bytes in sl_mqtt_client_credentials_t.password_length.

Maximum MQTT password length increased to 512 bytes in sl_mqtt_client_credentials_t.password_length.

Network Stack

sl_mqtt_client_message_t.content_length was limited to 1024 bytes.

Content length limit removed. For RX, the SDK automatically reassembles fragmented payloads. Maximum reassembly size is controlled by the new SL_MQTT_CLIENT_MAX_RX_PAYLOAD_SIZE macro (default 8192 bytes, user-configurable).

New Structures and Fields#

Module

Structure / Field

Description

Wi-Fi

sl_wifi_extended_scan_result_t.seen_count

New uint16_t field: number of times the same AP was observed in received frames.

Wi-Fi

sl_wifi_advanced_scan_configuration_t.advanced_scan_bitmap

New union member extending enable_instant_scan with a bitmap: BIT(0) – Enable Instant Scan, BIT(6) – Enable Non-periodic Scan, BIT(7) – Enable Extended Scan Results.

New Macros and Enums#

Module

Macro / Enum

Description

Network Stack

SL_MQTT_CLIENT_MAX_RX_PAYLOAD_SIZE

Configurable maximum MQTT RX payload size for large message reassembly (default 8192 bytes). Set to 0 to disable large payload reassembly.

Network Stack

SL_MQTT_CLIENT_RECEIVE_FAILED

New error enum: MQTT message receive operation failed.

Network Stack

SL_MQTT_CLIENT_RECEIVE_PAYLOAD_TOO_LARGE

New error enum: received payload exceeds SL_MQTT_CLIENT_MAX_RX_PAYLOAD_SIZE.

Network Stack

SL_MQTT_CLIENT_RECEIVE_MEMORY_ALLOCATION_FAILED

New error enum: memory allocation failed during message reassembly.

Network Stack

SL_MQTT_CLIENT_RECEIVE_DATA_CORRUPTED

New error enum: data corruption during message reassembly.

Deprecated APIs#

No new API deprecations were introduced in v4.0.1 or v4.0.2. All API deprecations from v4.0.0 remain in effect with a planned removal date of June 2027. Refer to the Migrating from v3.5.3 to v4.0.0 guide for the complete mapping of deprecated APIs.

Deprecated Structures#

No new structure deprecations were introduced in v4.0.1 or v4.0.2. All deprecations from v4.0.0 remain in effect. Refer to the Migrating from v3.5.3 to v4.0.0 guide for the complete mapping of deprecated structures.

Deprecated Enums#

No new enum deprecations were introduced in v4.0.1 or v4.0.2. All deprecations from v4.0.0 remain in effect. Refer to the Migrating from v3.5.3 to v4.0.0 guide for the complete mapping of deprecated enums.

Deprecated Macros#

Note: Starting from WC-4.0.2, the misspelled *_EXTENTION_VALID macro names are deprecated in favor of the corrected *_EXTENSION_VALID spellings. The *_EXTENSION_VALID macros are now the primary definitions, and the misspelled names are retained as compatibility aliases with documented deprecation notices. The default device configuration structs have also been updated to use the corrected spellings. All macro deprecations from v4.0.0 also remain in effect; refer to the Migrating from v3.5.3 to v4.0.0 guide for those.

Module

v4.0.0[Deprecated]

v4.0.2[New]

Wi-Fi

SL_SI91X_CUSTOM_FEAT_EXTENTION_VALID

SL_SI91X_CUSTOM_FEAT_EXTENSION_VALID

Wi-Fi

SL_SI91X_CONFIG_FEAT_EXTENTION_VALID

SL_SI91X_CONFIG_FEAT_EXTENSION_VALID

BLE

SL_SI91X_FEAT_BLE_CUSTOM_FEAT_EXTENTION_VALID

SL_SI91X_FEAT_BLE_CUSTOM_FEAT_EXTENSION_VALID

Note#