SILICON LABS 2.4.1.0 GA OpenThread SDK Gecko SDK Suite 4.4 User Guide

SILICON LABS 2.4.1.0 GA OpenThread SDK Gecko SDK Suite 4.4

Product Information

Specifications

• Product Name: Silicon Labs OpenThread SDK
• Version: 2.4.1.0 GA
• Gecko SDK Suite Version: 4.4
• Release Date: February 14, 2024
• Key Features: OpenThread, Multi-Protocol Support
• Compatible Compilers: GCC version 12.2.1

Product Usage Instructions

About OpenThread

• OpenThread is a secure, reliable, scalable, and upgradeable wireless IPv6 mesh networking protocol optimized for low-power operation.
• It is designed for Connected Home applications where IP-based networking is desired.

SDK Overview

• The Silicon Labs OpenThread SDK is a tailored version of the open-source OpenThread implementation by Google.
• It supports a wider range of hardware and includes additional documentation and example applications.

Key Features

• Supports a variety of hardware designs (SoC, NCP, RCP)
• Enhanced version of the GitHub source
• Supports multi-protocol communication

Compatibility and Use Notices

• For security updates and notices, refer to the Security chapter of the Gecko Platform Release notes or visit the Silicon Labs website.
• Subscribe to Security Advisories for up-to-date information.

Compatible Compilers

The SDK is compatible with GCC version 12.2.1 provided with Simplicity Studio.

FAQ

Q: What is the purpose of OpenThread?

• A: OpenThread is a wireless mesh networking protocol designed for secure, low-power operation in Connected Home applications.

Q: What hardware designs does the Silicon Labs OpenThread SDK support?

• A: The SDK supports system-on-chip (SoC), network co-processor (NCP), and radio co-processor (RCP) designs.

Q: How can I stay informed about security updates?

• A: Refer to the Security chapter of the Gecko Platform Release notes or subscribe to Security Advisories on the Silicon Labs website.
• 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.1.0 GA released on February 14, 2024
• 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

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.

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.

New Features Added in release 2.4.1.0

• Support added for factory diagnostic channel and transmit power CLI commands.

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 features. The default setting for Silicon Labs sample applications is still 1.3.0.

New APIs Added in release 2.4.1.0

• otPlatDiagChannelSet – This function sets the channel to use for factory diagnostics.
• otPlatDiagTxPowerSet – This function sets the transmit power to use for factory diagnostics.

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”.
• 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 – The default log mechanism is changed from RTT to UART. RTT logging and associated libraries are removed from ot_third-party 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 a 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.1.0

provided paths, and by using pkg-config.
1235923| Fixed a wrapping bug in calls to otPlatAlarmMilliStartAt and otPlatAlarmMicroStartAt.
1243597| Removed extra ot-ble-dmp-no-buttons sample apps from the demos folder.
1251932| Increased OPENTHREAD_CONFIG_CSL_RECEIVE_TIME_AHEAD to 750 µsec for default FTD and MTD certification libraries for use with devices under test using library-based certification.

Fixed in release 2.4.0.0

received packet payloads to be overwritten before being processed.
1148720| SED’s current draw has been improved.
1169011| Increased the stack size of the 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 the 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/threadin the Tech Docs tab.

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| The 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.
1177718| MG24 Hangs when otInstanceErasePersistentInfo() is run in app_init()| No known workaround

1163281

1196499

| 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.
1 249492| FactoryReset and Reset commands via dBus cause the OTBR agent to exit unexpectedly.| No known workaround
1251926| Crash Handler sends a crash log before the host is ready.| No known workaround
1251952| instance Reset To Boot loader undefined when building with the open thread certification libraries and including the bootloader_interface component.| Modify the logic in openthread-core-efr32-config.h to disable OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MOD E_ENABLE. For example, #if defined(SL_CATALOG_GECKO_BOOTLOADERINTERFACE PRESENT) #define OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENA BLE 0 #endif

Deprecated Items

Deprecated in release 2.4.0.0

• The ot_thirdparty component has been deprecated.

Removed Items None

Multiprotocol Gateway and RCP

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 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.

Improvements

• Changed in release 2.4.0.0
• The Zigbee NCP/OpenThread RCP multiprotocol combination is now production quality.

Fixed Issues Fixed in release 2.4.1.0.

for a child if the MAC indirect queue has data already pending for that child. This behavior could lead to application-layer transactions between the child and some other device failing due to lack of APS Ack or app-layer response, most notably the disruption and unexpected termination of ZCL OTA Upgrades targeting the child device.
1244461| Source match table entry for the child being could be removed despite messages pending.

Fixed in release 2.4.0.0

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 hacking) if multiple 15.4 interfaces share 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.
ID #| Description
---|---
**** 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.

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 at https://www.si- labs.com/developers/gecko-software-development-kit.

planned in a future release.
937562| Bluetoothctl ‘advertise on’ command fails with rcp-uart- 802154-blah 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.
1124140| z3-light_ot-ftd_soc sample app is not able to form the Zigbee network if the OT network is up already.| Start the Zigbee network first and the OT network after.
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 are not currently supported for these apps.
1209958| The ZB/OT/BLE RCP on Bobcat and Bobcat Lite can stop working after a few minutes when running all three protocols| This will be addressed in a future release
1221299| Mfglib RSSI readings differ between RCP and NCP.| This will be addressed in a future release.
1231021| OTBR can assert when 80+ zigbee devices are joining simultaneously.| Added a fix that may workaround the issue. Will be fully addressed in a future release.

Deprecated Items

None 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.

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 at https://docs.silabs.com/openthread/latest/. Select your SDK version in the upper right.

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

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) 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

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 the Silicon Labs RCP with the OpenThread Border Router for details on how to set up the correct version of the OpenThread Border Router Docker container.
• It is available at 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 the Silicon Labs RCP with the OpenThread Border Router 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.

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.

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 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)’ are checked, and that you are subscribed at minimum for your platform and protocol. Click Save to save any changes.

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.

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!
• IoT Portfolio www.silabs.com/IoT
• SW/HW www.silabs.com/simplicity
• Quality www.silabs.com/quality
• Support & Community www.silabs.com/community

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 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 the use of the information 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 III 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 the 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, visit www.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 is 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

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 at 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.

References

• Silicon Labs
• Silicon Labs
• About Us - Silicon Labs
• Silicon Labs Community
• Internet of Things (IoT) - Silicon Labs
• Simplicity Studio - Silicon Labs
• Technical Support - Silicon Labs
• Developing with OpenThread - latest - OpenThread Silicon Labs
• GitHub - openthread/openthread: OpenThread released by Google is an open-source implementation of the Thread networking protocol
• GitHub - openthread/ot-br-posix: OpenThread Border Router, a Thread border router for POSIX-based platforms.
• Thread Software Development Kit - Silicon Labs

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>