SILICON LABS SDK 7.4.1.0 GA Zigbee Protocol Stack Software User Guide

295498| UART reception sometimes drops bytes under heavy load in the Zigbee+BLE dynamic multiprotocol use case.| Use hardware flow control or lower the baud rate.

312291

| EMHAL: The halCommonGetIntxxMillisecondTick functions on Linux hosts currently use the getting meofday function, which is not guaranteed to be monotonic. If the system time changes, it can cause issues with stack timing.|

Modify these functions to use clock_gettime with the CLOCK_MONOTONIC source instead.

338151| Initializing NCP with a low packet buffer count value may cause corrupt packets.| Use the 0xFF reserved value for packet buffer count to avoid the too-low default value
387750| The issue with Route Table Request formats on the end device.| Under Investigation
400418| A touchlink initiator cannot link to a non-factory-new end-device target.| No known workaround.

424355

| A non-factory-new sleepy end device touchline target-capable initiator is not able to receive a device information response in certain circumstances.|

Under Investigation

465180

| The Coexistence Radio Blocker Optimization item “Enable Runtime Control” may block proper Zigbee operation.| Optional ‘Wi-Fi Select’ Control of Blocker Optimization should be left “Disabled”.

480550

| The OTA cluster has its built-in fragmentation method, hence it should not use APS fragmentation. Although, in case APS encryption is enabled it grows the payload of the ImageBlockResponses to a size where the APS fragmentation is activated. This could lead to the OTA process failing.|

No known workaround

481128

| Detailed Reset Cause and crash details should be available by default via the Virtual UART (Serial 0) on NCP platforms when the Diagnostics plugin and Virtual UART peripheral are enabled.| Since Serial 0 is already initialized in the NCP, customers can enable the emberAfNcpInitCallback in the Zigbee NCP Framework and call the appropriate diagnostic functions (halGetExtendedResetInfo, halGetExtendedResetString, halPrintCrashSummary, halPrintCrashDetails, and halPrintCrashData) in this callback to print this data to Serial 0 for viewing in the Network Analyzer capture log.

For an example of how to use these functions, refer to the code included in a -main-soc.c’s emberAfMainInit() when EXTENDED_RESET_INFO is defined.

486369

| If a DynamicMultiProtocolLightSoc forming a new network has child nodes remaining from a network it has left, emberAfGetChildTableSize returns a non- zero value in startIdentifyOnAllChildNodes, causing Tx 66 error messages when addressing the “ghost” children.| Mass-erase the part if possible before creating a new network or programmatically check the child table after leaving the network and delete all children using emberRemoveChild before forming a new network.

495563

| Joining SPI NCP Sleepy End Device Sample App doesn’t short poll, therefore the joining attempt fails at the state of Update TC Link Key.| The device that wishes to join should be in Short Poll mode before attempting to join. This mode can be forced by the End Device Support plugin.

497832

| In Network Analyzer the Zigbee Application Support Command Breakdown for the Verify Key Request Frame mistakenly references the part of the payload that indicates the frame Source Address as the Destination Address.|

No known workaround

519905

521782

| Spi-NCP may very rarely fail to start up bootloader communication using the ‘bootload’ CLI command of the ota-client plugin.|

Restart the bootload process

620596

| NCP SPI Example for BRD4181A (EFR32xGMG21)

nWake default pin defined cannot be used as a wake-up pin.

|

Change the default pin for nWake from PD03 to a EM2/3 wake-up-enabled pin in the NCP-SPI Plugin.

631713

| A Zigbee End Device will report address conflicts repeatedly if the plugin “Zigbee PRO Stack Library” is used instead of “Zigbee PRO Leaf Library”.| Use the”Zigbee PRO Leaf Library” instead of the “Zigbee PRO Stack Library” plugin.

670702

| Inefficiencies within the Reporting plugin can lead to significant latency based on data write frequency and table size, which may interfere with customer application code, including event timing.| If doing frequent writes, consider checking reporting conditions and sending reports manually rather than using the plugin.

708258

| Uninitialized value in groups-server.c via addEntryToGroupTable() can create a spurious binding and cause group cast reporting messages to be sent.| Add “binding.clusterId = EMBER_AF_INVALID_CLUSTER_ID;” after “binding.type

= EMBER_MULTICAST_BINDING;”

757775

|

All EFR32 parts have a unique RSSI offset. In addition, board design, antennas and enclosure can impact RSSI.

| When creating a new project, install the RAIL Utility, RSSI component. This feature includes the default RSSI Offset Silabs measured for each part. This offset can be modified if necessary after RF testing of your complete product.

758965

| ZCL cluster components and the ZCL command discovery table are not synchronized. Therefore, when enabling or disabling a ZCL cluster component, implemented commands will not be enabled/disabled in the corresponding ZCL Advanced Configurator command tab.| Manually enable/disable discovery for the desired ZCL commands in the ZCL Advanced Configurator.
765735| The OTA update fails on Sleepy End Device with enabled Page Request.| Use Block Request instead of Page Request.

845649

|

Removing CLI: The core component does not eliminate EEPROM cli calls to sl_cli.h.

| Delete the eeprom-cli.c file that calls the sl_cli.h. Additionally, calls to sl_cli.h as well as sl_cli_command_arg_t in the ota-storage-simple-eeprom can be commented out.

857200

| ias-zone-server. c allows for a binding to be created with a “0000000000000000” CIE address and posteriorly does not allow further bindings.| No known workaround
1019961| Generated Z3Gateway makefile hardcodes “gcc” as CC| No known workaround
ID #| Description| Workaround
---|---|---

1039767

|

Zigbee router network retry queue overflow issue in multi-thread RTOS use case.

| Zigbee Stack is not thread-safe. As a result, calling Zigbee stack APIs from another task is not supported in the OS environment and may put the stack into a “non-working” state. Refer to the following App note for more information and a workaround using the event handler.

https://www.silabs.com/documents/public/application- notes/an1322-dynamic-multiprotocol-bluetooth-zigbee- sdk- 7x.pdf .

1064370| The Z3Switch sample application only enabled one button (instance: btn1) by default which leads to a mismatch in the but- ton description in the project file.| Workaround: Install the btn0 instance manually during Z3Switch project creation.
1161063| Z3Light and potentially other applications report incorrect cluster revision values.| Manually update the cluster revision attribute to their appropriate revision.
1164768,

1171478,

1171479

| ERROR: ezspErrorHandler 0x34 reported repeatedly during mfglib receive mode| To reduce the error messages printed, configure EMBER_AF_PLUGIN_GATEWAY_MAX_WAIT_FOR_EV

ENT_TIMEOUT_MS on the host app to 100, so the callback queue is freed more quickly.

1252460| SimEEPROM recovery routines (for both v1 and v2) run at startup may perform misaligned flash page erase calls resulting in assertions during em_msc. c’s MSC_ErasePage routine.| *Workaround: Place the following line of code at the top of the MSC_ErasePage() function in em_msc.c: start address  =  (uint32_t)((uint32_t)startAddress &**

~(FLASH_PAGE_SIZE- 1));

Deprecated Items

Deprecated in release
In GSDK 7.4.0.0 onwards, including this patch, the “-v” option in a Z3Gateway for a linux host application to create a telnet interface with port 4900 or 4901 is deprecated. The alternative recommended way to create a telnet interface is to use linux utilities such as “socat”.

Deprecated in release
Removed the following deprecated security APIs:

• emberGetKey()
• emberGetKeyTableEntry()
• emberSetKeyTableEntry()
• emberHaveLinkKey()
• emberAddOrUpdateKeyTableEntry()
• emberAddTransientLinkKey()
• emberGetTransientKeyTableEntry()
• emberGetTransientLinkKey()
• emberHmacAesHash()

Use the APIs provided by Zigbee Security Manager for access to key storage and HMAC hashing.

Removed Items

Removed in release

• Removed duplicate public APIs in public header file gp-types.h.
• The zigbee_end_device_bind component has been removed. This component was used for the coordinator to broker binding re-quests for end devices. This optional functionality was removed from R22 of the Zigbee core spec.
• Removed setPacketBufferCount() in af-host.c and useless check case EZSP_CONFIG_PACKET_BUFFER_COUNT: in command-handlers.c.
• Removed memoryAllocation argument because there is no need to divide into two phases when initializing NCP.
• Removed emberAfNcpInitCallback() in se14-comms-hub, se14-ihd, and se14-meter-gas ‘s app.c.
• Removed setting EZSP_CONFIG_RETRY_QUEUE_SIZE value during ncp initialization in ncp-configuration.c

Multiprotocol Gateway and RCP

New Items
Added in release

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

Improvements
Changed in release

• The Zigbee NCP/OpenThread RCP multiprotocol combination is now production quality.

Fixed Issues
Fixed in release

1213701

| zigbeed didn’t allow a source match table entry to be created for a child if 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 child being could be removed despite messages pending.

Fixed in release

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.

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.

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

Will be addressed in a future release

1221299| Mfglib RSSI readings differ between RCP and NCP.| 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

• 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:

• Zigbee stack
• Zigbee Application Framework
• Zigbee Sample Applications

For more information about Zigbee and the EmberZNet SDK see UG103.02: Zigbee Fundamentals.
If you are a first-time user, see QSG180: Zigbee EmberZNet Quick-Start Guide for SDK 7.0 and Higher, for instructions on configuring your development environment, building and flashing a sample application, and documentation references pointing to next steps.

Installation and Use

The Zigbee EmberZNet SDK is provided as part of the Gecko SDK (GSDK), the suite of Silicon Labs SDKs. To quickly get started with the GSDK, install 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.

Simplicity Studio installs the GSDK by default in:

• (Windows): C:\Users\\SimplicityStudio\SDKs\gecko_sdk
• (MacOS): /Users//SimplicityStudio/SDKs/gecko_sdk

Documentation specific to the SDK version is installed with the SDK. Additional information can often be found in the knowledge base articles (KBAs). API references and other information about this and earlier releases is available on https://docs.silabs.com/.

Security Information

Secure Vault Integration
For applications that choose to store keys securely using the Secure Key Storage component on Secure Vault-High parts, the following table shows the protected keys and their storage protection characteristics that the Zigbee Security Manager component manages.

Manager

• 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.
• User applications never need to interact with the majority of these keys. Existing APIs to manage Link Key Table keys or Transient Keys are still available to the user application and now route through the Zigbee Security Manager component.
• Some of these keys may become non-exportable to the user application in the future. User applications are encouraged to not rely on the exporting of keys unless absolutely necessary.
• 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.

Support
Development Kit customers are eligible for training and technical support. Use the Silicon Laboratories Zigbee web page to obtain infor-mation about all Silicon Labs Zigbee products and services, and to sign up for product support.
You can contact Silicon Laboratories support at http://www.silabs.com/support.

Simplicity Studio
One-click access to MCU and wireless tools, documentation, software, source code libraries & more. Available for Windows, Mac and Linux!

• www.silabs.com/IoT
• www.silabs.com/simplicity
• www.silabs.com/quality
• 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 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 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 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.

CONTACT

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

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

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>