SILICON LABS OpenThread SDK 2.4.0.0 GA Software User Guide

: June 17, 2024
: SILICON LABS

Table of Contents

OpenThread SDK 2.4.0.0 GA Software
KEY FEATURES
Compatibility and Use Notices
New Items
Improvements
Fixed Issues
Known Issues in the Current Release
Deprecated Items
Removed Items
Multiprotocol Gateway and RCP
Using This Release
Disclaimer
Trademark Information
Documents / Resources

Silicon Labs OpenThread SDK 2.4.0.0 GA
Gecko SDK Suite 4.4
December 13, 2023

OpenThread SDK 2.4.0.0 GA Software

SILICON LABS OpenThread SDK 2.4.0.0 GA Software

Thread is a secure, reliable, scalable, and upgradeable wireless IPv6 mesh networking protocol. It provides low-cost bridging to other IP networks while optimized for low-power / battery-backed operation. The Thread stack is designed specifically for Connected Home applications where IP-based networking is desired, and a variety of application layers may be required.
OpenThread released by Google is an open-source implementation of Thread. Google has released OpenThread to accelerate the development of products for the connected home and commercial buildings. With a narrow platform abstraction layer and a small
memory footprint, OpenThread is highly portable. It supports system-on-chip (SoC), network co-processor (NCP), and radio co-processor (RCP) designs.
Silicon Labs has developed an OpenThread-based SDK tailored to work with Silicon Labs hardware. The Silicon Labs OpenThread SDK is a fully tested enhanced version of the GitHub source. It supports a broader range of hardware than does the GitHub version, and includes documentation and example applications not available on GitHub.
These release notes cover SDK version(s): 2.4.0.0 GA released on December 13, 2023

KEY FEATURES

OpenThread

Thread 1.3.0 certification compliance with Thread Test Harness v59.0 for SoC and Host-RCP architectures
Thread 1.3.1 feature support – Experimental
Crash Handler support
TrustZone Evaluation support
MR21 support for OpenThread RCP – Pro- duction

Multi-Protocol

Concurrent Listening support (RCP) – MG21 and MG24
Concurrent Multiprotocol (CMP) Zigbee NCP + OpenThread RCP – production quality
Dynamic Multiprotocol Bluetooth + Con current Multiprotocol (CMP) Zigbee and OpenThread support on SoC

Compatibility and Use Notices

For information about security updates and notices, see the Security chapter of the Gecko Platform Release notes installed with this SDK or on the TECH DOCS tab on https://www.silabs.com/developers/thread . Silicon Labs also strongly recommends that you subscribe to Security Advisories for up-to-date information. For instructions, or if you are new to the Silicon Labs OpenThread SDK, see Using This Release.
Compatible Compilers: GCC (The GNU Compiler Collection) version 12.2.1, provided with Simplicity Studio.

New Items

This release of the Gecko SDK (GSDK) will be the last with combined support for all EFM and EFR devices, except for patches to this version as needed. Starting in mid-2024 we will introduce separate SDKs:

The existing Gecko SDK will continue with support for Series 0 and 1 devices.
A new SDK will cater specifically to Series 2 and 3 devices.

The Gecko SDK will continue to support all Series 0 and 1 devices with no change to the long-term support, maintenance, quality, and responsiveness provided under our software policy.
The new SDK will branch from Gecko SDK and begin to offer new features that help developers take advantage of the advanced capabilities of our Series 2 and 3 products.
This decision aligns with customer feedback, reflecting our commitment to elevate quality, ensure stability, and enhance performance for an exceptional user experience across our software SDKs.
1.1 New Components
Added in release 2.4.0.0

ot_crash_handler – This component provides a set of APIs for printing crash info. In the case of a crash, this component captures the details and prints them on the next reboot.
ot_rtt_log – This component adds support for RTT logging, which is the mechanism used for the platform defined logging interface.

1.2 New Features
Added in release 2.4.0.0

Crash Handler support – With this release, a crash handler component has been introduced for use with OpenThread applications.
By including it in an OpenThread project, it will automatically capture detailed information about core registers, information about the C stack, and reset information. On the next boot-up, this data is printed using the OpenThread logging system.
TrustZone evaluation support – Added evaluation workspaces to enable TrustZone for OpenThread CLI applications.
Features introduced with OpenThread up to and including commit 7074a43e4. This includes support for ongoing Thread 1.3.1 fea- tures. The default setting for Silicon Labs sample applications is still 1.3.0.

1.3 New APIs
Added in release 2.4.0.0

otPlatResetToBootloader – reset to bootloader mode. Users can either call this API directly in code or via the CLI command “reset bootloader”.

1.4 New Radio Board Support
Added in release 2.4.0.0
Support has been added for the following radio boards:

BRD4198A – EFR32MG24B210F1536IM48-B

Improvements

Changed in release 2.4.0.0

Logging – Default log mechanism is changed from RTT to UART. RTT logging and associated libraries are removed from ot_thirdparty and added to a new component, ot_rtt_log.
Posix vendor extension options:
Changed OT_POSIX_CONFIG_RCP_VENDOR_DEPS_PACKAGE value from SilabsRcpDeps to posix_vendor_rcp.cmake.
Removed CMAKE_MODULE_PATH option.
NCP sample applications – Prebuilt NCP sample applications are considered experimental and are no longer packaged as prebuilt demos.
SL_OPENTHREAD_CSL_TX_UNCERTAINTY, SL_OPENTHREAD_HFXO_ACCURACY SL_OPENTHREAD_LFXO_ACCURACY, are now configurable.
Improvements introduced with OpenThread up to and including commit 7074a43e4.
The OT_CONFIG CMake option has been replaced in favor of two new options: OT_PLATFORM_CONFIG and OT_PROJECT_CONFIG.
Changes and clarifications in CSL APIs. The major CLI/API change is that now csl period requires microsecond value instead of 10 symbol units.
Changes in the Spinel Interface. The Spinel interface is now created based on radio URL protocol to support multiple interfaces (hdlc/spi/vendor) at the same time. Silicon Labs CPC builds will continue to support only one interface, which is the vendor interface (CPC).
During build time, setting OT_POSIX_CONFIG_RCP_BUS is now deprecated. Instead turn on one or more of OT_POSIX_RCP_HDLC_BUS, OT_POSIX_RCP_SPI_BUS, or OT_POSIX_RCP_VENDOR_BUS as needed.

Fixed Issues

Fixed in release 2.4.0.0

ID #	Description
1124161	High traffic environments will no longer cause buffers containing

received packet payloads to be overwritten before being processed.
1148720| SED current draw has been improved.
1169011| Increased the stack size of OpenThread task to 4608 bytes (SL_OPENTHREAD_OS_STACK_TASK_SIZE) for DMP applications to avoid stack overflow while joining the thread network.
1193597| OpenThread Radio PAL now maintains Max channel power table.
1227529| Fixed the typo in OPENTHREAD_SPINEL_CONFIG_TX_WAIT_TIME_SECS to OPENTHREAD_SPINEL_CONFIG_RCP_TX_WAIT_TIME_SECS in lower-mac-spinel-config header.

Known Issues in the Current Release

Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on https://www.si- labs.com/developers/thread in the Tech Docs tab.

ID #| Description|

Workaround

---|---|---
482915

495241

| A known limitation with the UART driver can cause characters to be lost on CLI input or output. This can happen during particularly long critical sections that may disable interrupts, so it can be alleviated by repeating the CLI or waiting long enough for state changes.| No known workaround
815275| Ability to modify the Radio CCA Modes at compile- time using a configuration option in Simplicity Studio is currently not supported.| Use the SL_OPENTHREAD_RADIO_CCA_MODE configuration option defined in openthread-core- efr32-config.h header file included with your project.
1094232| Intermittently, ot-ctl terminates after a factoryreset when using a CPCd connection.| No known workaround
1064242| OpenThread prefix commands sometimes fail to add prefix for OTBR over CPC.| No known workaround
1177718| MG24 Hangs when otInstanceErasePersistentInfo() is run in app_init()| No known workaround
1163281| The OTBR DUTs that need to pass Thread Certification Test “5.10.2 MATN-TC-02: Multicast listener registration and first use” need to enable the ‘REFERENCE_DEVICE’ flag during OTBR bootstrap and setup. This issue will be addressed in a later release with a newer OpenThread stack that fixes this issue.| Compile with REFERENCE_DEVICE.
1185623| When Matter hub is down, MADs lose routing of unicast messages (bindings)| No known workaround
1208578| Yocto OTBR build encountering CPCd linking issues| No known workaround

Deprecated Items

Deprecated in release 2.4.0.0

The ot_thirdparty component has been

Removed Items

None

Multiprotocol Gateway and RCP

7.1 New Items
Added in release 2.4.0.0
Concurrent listening, the ability for the Zigbee and OpenThread stacks to operate on independent 802.15.4 channels when using an EFR32xG24 or xG21 RCP, is released. Concurrent listening is not available for the 802.15.4 RCP/Bluetooth RCP combination, the Zigbee NCP/OpenThread RCP combination, or for the Zigbee/OpenThread system-on-chip (SoC). It will be added to those products in a future release.
The OpenThread CLI vendor extension has been added to the OpenThread host apps of multiprotocol containers. This includes the coex cli commands.
7 .2 Improvements
Changed in release 2.4.0.0
The Zigbee NCP/OpenThread RCP multiprotocol combination is now production quality.
7.3 Fixed Issues
Fixed in release 2.4.0.0

ID #	Description
1081828	Throughput issue with FreeRTOS-based Zigbee/BLE DMP sample

applications.
1090921| Z3GatewayCpc had trouble forming a network in a noisy environment.
1153055| An assert on the host was caused when there was a communication failure when reading the NCP version from the zigbee_ncp-ble_ncp-uart sample app.
1155676| The 802.15.4 RCP discarded all received unicast packets (after MAC acking) if multiple 15.4 interfaces shared the same 16-bit node ID.
1173178| The host falsely reported hundreds of packets received with mfglib in the Host-RCP setup.
1190859| EZSP error when sending mfglib random packets in the Host-RCP setup.
1199706| Data polls from forgotten end device children were not properly setting a pending frame on the RCP to queue a Leave & Rejoin command to the former child.
1207967| The “mfglib send random” command was sending out extra packets on Zigbeed.
1208012| The mfglib rx mode did not update packet info correctly when receiving on the RCP.
1214359| The coordinator node crashed when 80 or more routers tried to join simultaneously in the Host-RCP setup.

1216470

| After relaying a broadcast for address mask 0xFFFF, a Zigbee RCP acting as a parent device would leave the pending data flag set for each child. This resulted in each child staying awake expecting data after each poll, and required some other pending data transaction to each end device to eventually clear this state.

7.4 Known Issues in the Current Release

Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on https://www.si- labs.com/developers/gecko-software-development- kit.

ID #	Description	Workaround
811732	Custom token support is not available when using Zigbeed.	Support is

planned in a future release.
937562| Bluetoothctl ‘advertise on’ command fails with rcp-uart- 802154-blehci app on Raspberry Pi OS 11.| Use btmgmt app instead of bluetoothctl.
1022972| Coex not working on ZB NCP + OT RCP.| Support is planned for a future release.
---|---|---
1074205| The CMP RCP does not support two networks on the same PAN id.| Use different PAN ids for each network. Support is planned in a future release.
1122723| In a busy environment the CLI may become unresponsive in the z3 -light_ot-ftd_soc app.| No known workaround.
1170052| CMP Zigbee NCP + OT RCP and DMP Zigbee NCP + BLE NCP may not fit on 64KB and lower RAM parts in this current release.| 64KB parts not currently supported for these apps.
1213701| RCP may fail to indicate pending data for sleepy child during OTA upgrade to child in a noisy environment, resulting in update process terminating unexpectedly.| Will be addressed in a future release.
1221299| Mfglib RSSI readings differ between RCP and NCP.| Will be addressed in a future release.

7.5 Deprecated Items
None
7.6 Removed Items
Removed in release 2.4.0.0
The “NONCOMPLIANT_ACK_TIMING_WORKAROUND” macro has been removed. All RCP apps now by default support 192 µsec turnaround time for non-enhanced acks while still using 256 µsec turnaround time for enhanced acks required by CSL.

Using This Release

This release contains the following

Silicon Labs OpenThread stack
Silicon Labs OpenThread sample applications
Silicon Labs OpenThread border router

For more information about the OpenThread SDK see QSG170: Silicon Labs OpenThread QuickStart Guide .If you are new to Thread see UG103.11: Thread Fundamentals.
8.1 Installation and Use
The OpenThread SDK is part of the Gecko SDK (GSDK), the suite of Silicon Labs SDKs. To quickly get started with OpenThread and the GSDK, start by installing Simplicity Studio 5, which will set up your development environment and walk you through GSDK installation. Simplicity Studio 5 includes everything needed for IoT product development with Silicon Labs devices, including a resource and project launcher, software configuration tools, full IDE with GNU toolchain, and analysis tools. Installation instructions are provided in the online Simplicity Studio 5 User’s Guide.
Alternatively, Gecko SDK may be installed manually by downloading or cloning the latest from GitHub. See https://github.com/Sili- conLabs/gecko_sdk for more information.
The GSDK default installation location has changed beginning with Simplicity Studio 5.3.

Windows: C:\Users\\SimplicityStudio\SDKs\gecko_sdk
MacOS: /Users//SimplicityStudio/SDKs/gecko_sdk

Documentation specific to the SDK version is installed with the SDK. API references and other information about this release are available on https://docs.silabs.com/openthread/latest/. Select your SDK version in the upper right.
8.2 OpenThread GitHub Repository
The Silicon Labs OpenThread SDK includes all changes from the OpenThread GitHub repo (https://github.com/openthread/openthread) up to and including commit 7074a43e4. An enhanced version of the OpenThread repo can be found in the following Simplicity Studio 5 GSDK location:

\util\third_party\openthread **8 .3 OpenThread Border Router GitHub Repository** The Silicon Labs OpenThread SDK includes all changes from the OpenThread border router GitHub repo [(https://github.com/openthread/ot-br- posix](https://github.com/openthread/ot-br-posix)) up to and including commit **42f98b27b**. An enhanced version of the OpenThread border router repo can be found in the following Simplicity Studio 5 GSDK location: \util\third_party\ot-br-posix **8.4 Using the Border Router ** For ease of use, Silicon Labs recommends the use of a Docker container for your OpenThread border router. Refer to [AN1256: Using](https://www.silabs.com/documents/public/application-notes/an1256-using- sl-rcp-with-openthread-border-router.pdf) [the Silicon Labs RCP with the OpenThread Border Router ](https://www.silabs.com/documents/public /application-notes/an1256-using-sl-rcp-with-openthread-border-router.pdf)for details on how to set up the correct version of OpenThread border router Docker container. It is available at [https://hub.docker.com/r/siliconlabsinc /openthread-border-router.](https://hub.docker.com/r/siliconlabsinc /openthread-border-router) If you are manually installing a border router, using the copies provided with the Silicon Labs OpenThread SDK, refer to [AN1256: Using](https://www.silabs.com/documents/public/application-notes/an1256-using- sl-rcp-with-openthread-border-router.pdf) [the Silicon Labs RCP with the OpenThread Border Router ](https://www.silabs.com/documents/public /application-notes/an1256-using-sl-rcp-with-openthread-border-router.pdf)for more details. Although updating the border router environment to a later GitHub version is supported on the OpenThread website, it may make the border router incompatible with the OpenThread RCP stack in the SDK. **8.5 NCP/RCP Support ** The OpenThread NCP support is included with OpenThread SDK but any use of this support should be considered experimental. The OpenThread RCP is fully implemented and supported. **8.6 Security Information** **Secure Vault Integration** When deployed to Secure Vault High devices, sensitive keys are protected using the Secure Vault Key Management functionality. The following table shows the protected keys and their storage protection characteristics.

Wrapped Key	Exportable / Non-Exportable	Notes
Thread Master Key	Exportable	Must be exportable to form the TLVs
PSKc	Exportable	Must be exportable to form the TLVs
Key Encryption Key	Exportable	Must be exportable to form the TLVs
MLE Key	Non-Exportable
Temporary MLE Key	Non-Exportable
MAC Previous Key	Non-Exportable
MAC Current Key	Non-Exportable
MAC Next Key	Non-Exportable

Wrapped keys that are marked as “Non-Exportable” can be used but cannot be viewed or shared at runtime.
Wrapped keys that are marked as “Exportable” can be used or shared at runtime but remain encrypted while stored in flash.
For more information on Secure Vault Key Management functionality, see AN1271: Secure Key Storage.
Security Advisories
To subscribe to Security Advisories, log in to the Silicon Labs customer portal, then select Account Home. Click HOME to go to the portal home page and then click the Manage Notifications tile. Make sure that ‘Software/Security Advisory Notices & Product Change Notices (PCNs)’ is checked, and that you are subscribed at minimum for your platform and protocol. Click Save to save any changes. SILICON LABS OpenThread SDK
2.4.0.0 GA Software - app

8.7 Support
Development Kit customers are eligible for training and technical support. Use the Silicon Laboratories Thread web page to obtain information about all Silicon Labs OpenThread products and services, and to sign up for product support.
You can contact Silicon Laboratories support at http://www.silabs.com/support.
8.8 Thread Certification
This release has been qualified for Thread 1.3.0 for both the SoC and Host-RCP architectures with Thread Test Harness v59.0 (Member Release). For Thread Product certifications tied to this major release and associated patch releases (with no OpenThread stack updates), Silicon Labs recommends using the above TH version for qualification.

Simplicity Studio
One-click access to MCU and wireless tools, documentation, software, source code libraries & more. Available for Windows, Mac and Linux! SILICON LABS
OpenThread SDK 2.4.0.0 GA Software - fig

| IoT Portfolio
www.silabs.com/IoT
---|---
| SW/HW
www.silabs.com/simplicity
| Quality
www.silabs.com/quality
| Quality
www.silabs.com/quality

Disclaimer

Silicon Labs intends to provide customers with the latest, accurate, and in- depth documentation of all peripherals and modules available for system and software implementers using or intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and “Typical” parameters provided can and do 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 the product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Without prior notification, Silicon Labs may update product firmware during the manufacturing process for security or reliability reasons. Such changes will not alter the specifications or the performance of the product. Silicon Labs shall have no liability for the consequences of use of the infor- mation supplied in this document. This document does not imply or expressly grant any license to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any FDA Class 1! devices, applications for which FDA premarket approval is required 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 be reasonably 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 use of a Silicon Labs product in such unauthorized applications.
Note: This content may contain offensive terminology that is now obsolete. Silicon Labs is replacing these terms with inclusive language wherever possible.
For more information, visitwww.silabs.com/about-us/inclusive-lexicon- project

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, ThreadArch®, 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 ls a registered trademark of the Wi-Fi Alliance. All other products or brand names mentioned herein are trademarks of their respective holders.

Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
www.silabs.com