Wi-SUN SDK 2.5.1.0 GA Simplicity SDK Suite 2024.12.3
Release Date: August 6, 2025
Wireless Smart Ubiquitous Network (Wi-SUN) is a leading IPv6 sub-GHz mesh technology for smart city and smart utility applications. It enables interoperable, multi-service, and secure wireless mesh networks for service providers, utilities, municipalities, and other enterprises. Wi-SUN is suitable for large-scale outdoor IoT wireless communication networks, supporting both line-powered and battery-powered nodes.
Silicon Labs' Wi-SUN hardware is certified by the Wi-SUN Alliance. Wi-SUN builds upon open standard internet protocols (IP) and APIs, allowing developers to extend existing infrastructure platforms. It is designed for scalability, long-range capabilities, high-data throughput, and IPv6 support, simplifying wireless infrastructure for industrial applications and smart city evolution.
These release notes cover the following SDK versions:
- 2.5.1.0 released August 6, 2025.
- 2.5.0.0 released April 1, 2025.
- 2.4.0.0 released February 5, 2025.
- 2.3.0.0 released December 16, 2024.
KEY FEATURES
Wi-SUN Stack
- Direct Connect
- PAN Defect
Wi-SUN Applications
- Border Router CLI source code
- Border Router CLI with Wi-Fi Backhaul
Compatibility and Use Notices
For security updates and notices, refer to the Security chapter in the Platform Release Notes installed with this SDK or available on the TECH DOCS tab at https://www.silabs.com/developers/wi-sun-protocol-stack. Silicon Labs recommends subscribing to Security Advisories for the latest information. For instructions or if you are new to the Silicon Labs Wi-SUN SDK, consult 'Using This Release'.
Compatible Compilers:
- IAR Embedded Workbench for ARM (IAR-EWARM) version 9.40.1
- Users building with the IARBuild.exe command-line utility or IAR Embedded Workbench GUI on macOS or Linux via Wine should be aware that Wine's hashing algorithm for generating short file names could lead to incorrect files being used due to collisions. Customers on macOS or Linux are advised to build with IAR exclusively within Simplicity Studio or to carefully verify the correctness of files used when building outside of Simplicity Studio.
- GCC (The GNU Compiler Collection) version 12.2.1, provided with Simplicity Studio.
1 Wi-SUN Stack
1.1 New Items
Added in release 2.5.0.0
- Moved
chan_params_tableout of the library. This table contains an exhaustive list of PHY configurations as specified in Wi-SUN PHY TPS. Moving it out enhances customization capabilities and allows for reduced firmware flash footprint by maintaining only necessary entries for production.
Added in release 2.4.0.0
- Added
sl_wisun_set_preferred_pan()API, allowing a device to prioritize connection to its preferred PAN. - Enabled ETSI Adaptive Power Control for the EU region.
- Updated BZ and SG channel plans according to PHY TPS 2v03.
Added in release 2.3.0.0
- Added
sl_wisun_br_set_ipv6_up_handler()andsl_wisun_br_ipv6_down()APIs to facilitate packet routing between a PAN network and another network behind the border router. These APIs are demonstrated in the new "Wi-SUN - SoC Border Router CLI with Wi-Fi connectivity" sample application and are exclusively usable from a border router. - Added
sl_wisun_set_leaf()API to configure an FFN (Full Function Node) to act as an RPL (Routing Protocol for Low-Power and Lossy Networks) leaf. Leaf nodes do not perform routing and do not advertise Pas and DIOs (Destination Oriented Datagrams). - Added
sl_wisun_set_tx_power_ddbm()API for setting transmit power with 0.1 dB resolution. - Introduced tracing functions:
sl_wisun_trace_debug(),sl_wisun_trace_info(),sl_wisun_trace_warn(), andsl_wisun_trace_error()for logging events in the Wi-SUN stack journal. - Added
lfn_na_wait_duration_min FFN connection parameters to configure the retransmission interval for DAO (Destination Advertisement Object) on behalf of a registered LFN (Low Power Node). - Added
sl_wisun_set_phy_sensitivity()API to override the default RX sensitivity for a chosen PHY. - Introduced Direct Connect functionality with associated APIs:
sl_wisun_set_direct_connect_state(),sl_wisun_set_direct_connect_pmk(), andsl_wisun_accept_direct_connect_link(). These enable Direct Connect, set the Direct Connect security key, and accept a new Direct Connect link, providing an alternate local interface. Version 2.3 supports only the server side of Direct Connect and accepts one link establishment at a time. Refer to the dedicated documentation on docs.silabs.com for details. - Introduced PAN Defect functionality with associated APIs
sl_wisun_br_pan_defect_advertise()and eventSL_WISUN_MSG_PAN_DEFECT_IND_ID. Refer to the dedicated documentation on docs.silabs.com for details. - Added Wi-SUN border router libraries and public APIs headers, which were previously private.
- Added DAO No-Path transmission to de-register a router before it leaves the network.
1.2 Improvements
Changed in release 2.4.0.0
- Improved messaging for routers unable to parent a device attempting to join. Routers now send an NA with an error status in response to an NS with an ARO when their neighbor table is full.
- Temporarily denied parenting for routers unable to accept new children, preventing devices from attempting to connect to routers that will not accept them.
Changed In release 2.3.0.0
- Updated RX sensitivities with new values.
- Updated Registration Refresh Request as mandated by FAN TPS 1.1v09.
- Updated NA channel plans 4 and 5 as mandated by PHY TPS amendment 1VA12.
- Improved retransmission mechanism to address rare instances where retransmission attempts were skipped due to a busy medium or high collision rates caused by hidden node communications.
- Enhanced handling of parent changes and losses by reworking secondary parent selection and secondary parent route usage policies, making the network more resilient.
- Reduced the weight given to the initial ETX (Estimated Transmission Count) measurement in the ETX EWMA (Exponentially Weighted Moving Average) to prevent instabilities during the initial deployment of large networks.
- Reduced the weight given to the initial RSL (Received Signal Level) measurement in the RSL EWMA.
- Reworked MAC, FFN, and LFN bootstrap state machines.
- Raised TCP maximum segment size (mss).
- Dropped deprecated definitions related to socket options.
1.3 Fixed Issues
Fixed in release 2.5.1.0
| ID # | Description |
| 1455220 | Fixed to clear the alternative PAN cache along with the credential cache. |
| 1454000 | Fixed an issue where Preferred PAN and PAN Defect generated excessive traffic. |
| 1453003 | Fixed an issue that caused significantly longer connection times when an error occurred during DAO transmission. Routers were unable to send a second DAO until PAN timeout. |
| 1419046 | Fixed an issue that caused devices to remain stuck in join state 3 when they could not decrypt a PC (Pre-Shared Key) from their previous PAN. |
| 1446315 | Fixed ETSI Adaptive Power Control with FAN TPS version 1.0. |
| 1441981 | Fixed an issue where LFN failed in join state 3 after failing to decrypt an FFN-specific packet. |
| 1441042 | Fixed frame counter mismatch issues with multiple PANs and hard resets, which caused abnormally long reconnection durations. |
| 1438701 | Fixed an LFN issue when multiple frames advertised an updated LUS-IE (LFN Update Status Information Element). |
| 1438027 | Fixed memory corruption when PC was received without correct encryption keys. |
| 1437500 | Fixed the return option value of getsockopt() for the SO_SNDLOWAT option. |
| 1436839 | Fixed send/sendto setting the wrong errno when sendq was full and the socket was not in blocking mode. |
| 1436839 | Fixed send/sendto not returning the correct number of sent bytes in the case of a partial packet send. |
| 1435786 | Fixed setting errno values for socket APIs, which were missing for some socket APIs. |
| 1429143 | Fixed an issue by deleting ND (Neighbor Discovery) entries upon receiving an NS (Neighbor Solicitation) with ARO containing a lifetime of 0. |
| 1426446 | Fixed a rescheduling issue with LFN frames that could prevent a node from operating correctly. |
| 1412117 | Fixed a radio configuration file error with SG PHYs. |
Fixed in release 2.5.0.0
| ID # | Description |
| 1419046 | Fixed an issue causing a router to remain in join state 3 after a failed reconnection attempt, triggered by key rotation while the device was disconnected. |
| 1417818 | Removed RSL-IE from EDFE Init Frame as per the latest Wi-SUN TPS version. |
| 1415416 | Fixed the EDFE timeout calculation, which was previously stopped at the end of ACK packet reception instead of the beginning. |
| 1414646 | When receiving an NS with ARO, the stack now inspects both the inner and outer IPv6 headers. The outer header does not guarantee a GUA (Global Unicast Address), which previously caused Neighbor Cache refresh to be missed when link-local addresses were used in the outer header and GUAs in the inner. |
| 1412771 | Fixed an FHSS (Frequency Hopping Spread Spectrum) synchronization issue due to incorrect UFSI (Uplink Frame Synchronization Information) values. |
| 1411742 | Fixed an issue causing the PAN defect and Preferred PAN features to conflict, leading routers that left their preferred PAN due to a PAN defect to roam back and forth. |
| 1412791 | Advertised border router address/prefix lifetime as infinite instead of 0 in DIO packets. |
Fixed in release 2.4.0.0
| ID # | Description |
| 1384392 | Fixed a PSA crypto key lock that prevented authentication after multiple attempts over the device's lifetime. The transient key used during the 4-way handshake was never expiring. |
| 1385981 | LFNs were not dropping security handshake frames from a previous connection prior to new authentication attempts; this has been fixed. |
| 1385791 | Fixed an issue preventing LFNs from sending LPAS (Low Power Association) correctly. |
| 1388948 | LFNs did not unregister from multicast groups when the corresponding socket was closed; this has been fixed. |
| 1387966 | Fixed RCP reset triggered when MAC would purge LFN frames upon LFN PAN Advertisement transmission. |
| 1392144 | Fixed DHCP preferred lifetime when address lifetime is infinite. |
| 1366711 | Routers were not unregistering when changing parent by sending an NS(ARO) with no lifetime; this has been fixed. |
| 1399233 | Fixed Neighbor Cache Refresh. |
| 1225514 | FFNs and LFNs now have storage for Frame Counters of up to 15 different PANs. Previously, they only kept one set of frame counters, making roaming between PANs nearly impossible. |
Fixed in release 2.3.0.0
| ID # | Description |
| 1328491 | Fixed an issue causing multicast packet lifetime to be extended, leading to instability under heavy multicast load. |
| 1375635 | Fixed PAN cost calculation where an integer division caused it to be systematically underestimated, leading to invalid EAP target selections. |
| 1379621 | Fixed an interoperability issue caused by incorrect behavior during EAP identifier roll-over. The specification recommends using a random EAP identifier when starting a new authentication. Silicon Labs authenticator always initialized the EAP identifier to 0, and the supplicant did not handle the roll-over. |
| 1368019 | Fixed a memory leak when a node was disconnected and had neighbors with registered POM-IE (Parent Object Message Information Element) info. |
| 1319942 | Fixed the RPL candidate parent set. The potential candidate RSL is now used as a criterion for acceptance into the candidate parent set. This modification reduces the number of probe transmissions required to compute the ETX. |
| 1359822 | Routers now immediately send probes to all new entries in the candidate set. Previously, probes were transmitted every 30 minutes by default, causing the promotion of a candidate to preferred parent to take up to 30 minutes. |
| 1361545 | Fixed the transmission of a POM-IE containing only one entry. |
| 1333058 | Fixed multicast transmissions to LFNs. FFN parents were not properly tracking LFN's multicast group registration and deregistration. |
| 1358322 | Fixed an error causing the IPv6 hop limit of multicast packets to be forwarded to LFNs. The outer header hop limit is not intended to be forwarded to LFNs, which was a potential source of interoperability issues. |
| 1367594 | Fixed an invalid memory access of candidate parent timeouts while disconnected. On a candidate timeout, the stack attempted to free all contexts, including one that was not yet initialized due to the disconnected state. |
| 1323858 | Routers were only deregistering from their preferred parent, skipping deregistration from their secondary parent, which caused routing errors after reconnection. |
| 1310166 | Fixed a radio reconfiguration issue in case of RX timeout event, which caused the radio to remain in the idle state until the next transmit event. |
1.4 Known Issues in the Current Release
Issues in bold were added since the previous release.
| ID # | Description | Workaround |
| 1119464 | Packets sent when FSK FEC is enabled can infringe ARIB regulation. | Until this problem is addressed correctly, the stack will refuse to start if both ARIB enforcement and FEC are enabled. |
| 1067978 | Packets sent using a PHY with a bandwidth larger than the base PHY's bandwidth can infringe ARIB regulation. | Limit communications when using mode switch with ARIB enforcement enabled. |
| 1176014 | FG25 asserts with a RAIL ASSERT_FAILED_RTCC_SYNC_STALE_DATA error code when entering EM2 (Energy Mode 2). | Prevent the power manager from entering EM2 by adding a requirement on EM1 in the application. |
| 1373879 | The RCP (Radio Co-Processor) is sometimes unable to send packets using mode switch. |
1.5 Deprecated Items
None
1.6 Removed Items
None
2 Wi-SUN Applications
2.1 New Items
Added in release 2.5.0.0
- Dynamic Data Provisioning support for all applications.
Added in release 2.3.0.0
- Wi-SUN - SoC Border Router CLI
- Opened the source code of the application, making it shared and buildable from Simplicity Studio.
- Introduced a new variant demonstrating backhaul connectivity using Silicon Labs SiWx917 Wi-Fi NCP with WiSeConnect SDK v3.4.0 and Iwip. This variant can connect multiple Wi-SUN PANs via a broader network behind the border router.
- Added support for an external DHCPv6 server using a DHCPv6 relay.
- Wi-SUN - SoC Socket application: This application merges the previously removed applications:
- Wi-SUN - SoC UDP Client
- Wi-SUN - SoC UDP Server
- Wi-SUN - SoC TCP Client
- Wi-SUN - SoC TCP Server
2.2 Improvements
Changed in release 2.5.0.0
- Wi-SUN RCP
- Updated the default trace level.
- TFTP Client
- Request error flags are now stored in the status event flag of the TFTP client instance.
- API Signature changes
void app_project_info_get(app_project_info_t * const dest)changed tosl_status_t app_project_info_get(app_project_info_t * const dest)void sl_wisun_udp_client_read(const int32_t sockid, const uint16_t size)changed tovoid sl_wisun_udp_client_read(const int32_t sockid)
Changed in release 2.4.0.0
- Wi-SUN - SoC Network Measurement
- Added a CLI command option to set TX Power in dBm units (ddBm has been supported since 2.3.0.0).
Changed in release 2.3.0.0
- TFTP Improvements
- Block Size Option (RFC 2348)
- Timeout Interval Option (RFC 2349)
- Added new configurations for the OTA DFU (Over-The-Air Device Firmware Update) component to set block size and timeout options:
SL_WISUN_OTA_DFU_TFTP_DATA_BLOCK_SIZESL_WISUN_OTA_DFU_TFTP_TIMEOUT_SEC
- Application memory statistic component improvements: enhanced print cosmetics and reduced verbosity.
- Wi-SUN Services related CLI components are merged into one: Wi-SUN CLI component. CLI commands can be enabled/disabled individually via configurations (e.g.,
SL_WISUN_OTA_DFU_CLI_ENABLED). - Wi-SUN CoAP component improvements:
- Tick event trigger feature for CoAP Notification Service.
- Optional verbose mode for CoAP Resource Handler.
- New CoAP Resource Handler extended auto response callback type to include the source address as an argument.
- Redirecting response feature for CoAP Resource Handler with a custom callback to create a new destination address.
- API signature changes
sl_status_t app_wisun_setting_set_tx_power(const int8_t * const tx_power)changed tosl_status_t app_wisun_setting_set_tx_power(const int16_t * const tx_power)sl_status_t app_wisun_setting_get_tx_power(int8_t *const tx_power)changed tosl_status_t app_wisun_setting_get_tx_power(int16_t *const tx_power)void sl_wisun_coap_rhnd_service_resp_received_hnd(sl_wisun_coap_packet_t *req_packet)changed tovoid sl_wisun_coap_rhnd_service_resp_received_hnd(const sockaddr_in6_t * const src_addr, sl_wisun_coap_packet_t * req_packet)void sl_wisun_tcp_client_create(const char *ip_address, uint16_t port)changed toint32_t sl_wisun_tcp_client_create(const char *ip_address, uint16_t port)void sl_wisun_udp_client_create(void)changed toint32_t sl_wisun_udp_client_create(void)
2.3 Fixed Issues
Fixed in release 2.5.1.0
| ID # | Description |
| 1455763 | Increased SL_WISUN_OTA_DFU_TFTP_TIMEOUT_SEC to 8 seconds in OTA DFU configuration. |
| 1440939 | Fixed TFTP client buffer initialization when option negotiation is used. The buffer should be reallocated properly if the Client and Server negotiate a new data block size. |
| 1429346 | Wi-SUN SoC CoAP Meter: Fixed the schedule of measurement and packet sending. The LFN wakeup event triggered the measurement. The elapsed time between LFN wakeup events was not equal to the LFN unicast interval, thus a lowpass filter was applied. |
Fixed in release 2.5.0.0
| ID # | Description |
| 1394656 | Wi-SUN RCP: Aborted packets now always send a confirmation. |
| 1402855 | Wi-SUN RCP: Fixed the Source Addressing Mode of EDFE Response frames. |
| 1390370 | Wi-SUN SoC BR CLI: Properly handles SL_WISUN_MSG_REGULATION_TX_LEVEL_IND_ID, which was causing error traces to be logged when activating ARIB regional regulations. |
| 1424755 | Wi-SUN RCP: Fixed the channel mask used by mode-switch packets. |
| 1425635 | Project info getter and printer in the app_project_info component: Fixed null pointer check. The getter return value is implemented using sl_status_t. |
| 1425148 | More descriptive debug logs and error handling for OTA DFU. |
| 1424813 | app_os_stat component: The severity of missing the following important configuration parameters has been raised from warning to error:
|
| 1419074 | UDP client: Unnecessary size parameter removed from the sl_wisun_udp_client_read() API. |
| 1414763 | UDP client: In sl_wisun_udp_client_read(), the return value handling of recvfrom() has been fixed. |
Fixed in release 2.4.0.0
| ID # | Description |
| 1333516 | Wi-SUN SoC CLI w/ Wi-FI backhaul: Fixed tasks' priority. FreeRTOS task priority was too low compared to the WiSeConnect highest priority task, causing FreeRTOS's xTimerQueue to fill up quickly and eventually leading to an assert. |
| 1392032 | Events added in 2.3.0.0 are now handled in the Wi-SUN Event Manager:
|
Fixed in release 2.3.0.0
| ID # | Description |
| 1333516 | Fixed TX Power setting (ddBm) in the Wi-SUN Application Core component (missing multiplication by 10). |
| 1332965 | Fixed: The stop command could not stop TFTP file transmission (also in case of OTA DFU). |
| 1305481 | Fixed heap usage printing issue at the Application memory statistic component by replacing the legacy heap statistics getter with the Memory Manager's solution. |
| 1295815 | Reduced iPerf test result JSON length to fit within 1024 bytes (libcoap3 support). |
| 1380166 | Replaced polling connection loop with waiting for connection event in CoAP threads. |
| 1362884 | Wi-SUN SoC CLI: Fixed multicast group registration. The CLI command handler was still using the legacy socket API option type definition. |
2.4 Known Issues in the Current Release
Issues in bold were added since the previous release.
| ID # | Description | Workaround |
| 1327376 | The RCP UART driver is unstable under certain conditions that have not yet been identified. These instabilities cause CRC errors that the RCP or wsbrd cannot recover from. | Use CPC instead of the RCP lightweight interface. |
| 1067236 | The border router RCP SPI interface is unstable when used with a throughput higher than 1 Mbytes/s. | The use of the border router RCP SPI interface is not recommended at this time. |
| Simplicity Studio - Network Analyzer: Wi-SUN Encrypted Packets are not supported. Undecoded frames (only after Ack) according to PTI issues on Series 2. |
2.5 Deprecated Items
None.
2.6 Removed Items
- Wi-SUN - SoC Meter application removed. The Wi-SUN - SoC CoAP Meter application can be used instead by uninstalling the Wi-SUN CoAP component.
- Wi-SUN - SoC Collector application removed. The Wi-SUN - SoC CoAP Collector application can be used instead by uninstalling the WiSUN CoAP component.
3 Using This Release
This release includes:
- Wi-SUN stack library
- Wi-SUN sample applications
- Wi-SUN border router pre-compiled demos
- Documentation
For first-time users, see https://docs.silabs.com/wisun/latest/wisun-getting-started-overview/.
3.1 Installation and Use
The Wi-SUN SDK is provided as part of the Simplicity SDK, Silicon Labs' suite of SDKs. To quickly get started, install Simplicity Studio 5, which sets up the development environment and guides through Simplicity SDK installation. Simplicity Studio 5 includes all necessary tools for IoT product development with Silicon Labs devices, such as a resource and project launcher, software configuration tools, a full IDE with GNU toolchain, and analysis tools. Installation instructions are available in the online Simplicity Studio 5 User's Guide.
Alternatively, the Simplicity SDK can be installed manually by downloading or cloning the latest version from GitHub: https://github.com/SiliconLabs/simplicity_sdk.
Simplicity Studio installs the Simplicity SDK by default in:
- Windows:
C:\Users\<NAME>\SimplicityStudio\SDKs\simplicity_sdk - MacOS:
/Users/<NAME>/SimplicityStudio/SDKs/simplicity_sdk
SDK-specific documentation is installed with the SDK.
3.2 Security Information
Secure Vault Integration
This version of the stack does not integrate Secure Vault Key Management.
Security Advisories
To subscribe to Security Advisories, log in to the Silicon Labs customer portal, navigate to Account Home, and click the Manage Notifications tile. Ensure that 'Software/Security Advisory Notices & Product Change Notices (PCNs)' is checked, and that you are subscribed for your platform and protocol. Click Save to apply changes.
3.3 Support
Development Kit customers are eligible for training and technical support. Contact Silicon Laboratories support at http://www.silabs.com/support.
3.4 SDK Release and Maintenance Policy
For details, see SDK Release and Maintenance Policy.
Simplicity Studio
One-click access to MCU and wireless tools, documentation, software, source code libraries & more. Available for Windows, Mac and Linux!
Disclaimer
Silicon Labs provides the latest, accurate, and in-depth documentation for all peripherals and modules available for system and software implementers using Silicon Labs products. Characterization data, available modules and peripherals, memory sizes, and memory addresses refer to each specific device. "Typical" parameters may vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Labs reserves the right to make changes without further notice to product information, specifications, and descriptions, and does not guarantee the accuracy or completeness of the included information. Silicon Labs may update product firmware during manufacturing for security or reliability reasons without prior notification; such changes will not alter product specifications or performance. Silicon Labs shall not be liable for the consequences of using the information supplied in this document. This document does not imply or expressly grant any license to design or fabricate integrated circuits. Silicon Labs products are not designed or authorized for use in any FDA Class III devices, applications requiring FDA premarket approval, or Life Support Systems without the specific written consent of Silicon Labs. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can reasonably be expected to result in significant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used in weapons of mass destruction, including but not limited to nuclear, biological, or chemical weapons, or missiles capable of delivering such weapons. Silicon Labs disclaims all express and implied warranties and shall not be responsible or liable for any injuries or damages related to the use of a Silicon Labs product in such unauthorized applications.
Trademark Information
Silicon Laboratories Inc. ®, Silicon Laboratories ®, Silicon Labs ®, SiLabs ® and the Silicon Labs logo ®, Bluegiga ®, Bluegiga Logo ®, EFM ®, EFM32 ®, EFR, Ember ®, Energy Micro, Energy Micro logo and combinations thereof, "the world's most energy friendly microcontrollers", Redpine Signals ®, WiSeConnect, n-Link, EZLink ®, EZRadio ®, EZRadioPRO ®, Gecko ®, Gecko OS, Gecko OS Studio, Precision32 ®, Simplicity Studio ®, Telegesis, the Telegesis Logo ®, USBXpress ®, Zentri, the Zentri logo and Zentri DMS, Z-Wave ®, and others are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. Wi-Fi is a registered trademark of the Wi-Fi Alliance. All other products or brand names mentioned herein are trademarks of their respective holders.
