SILICON LABS 7.1.5.0 Zigbee EmberZNet SDK User Guide

SILICON LABS 7.1.5.0 Zigbee EmberZNet SDK

Product Information

Specifications

• Zigbee EmberZNet SDK version: 7.1.5.0 GA
• Gecko SDK Suite version: 4.1 June 28, 2023
• Vendor: Silicon Labs
• Compatibility: EFR32xG21, Revision C and later
• Compatible Compilers: GCC version 10.3-2021.10

Product Usage Instructions

Using This Release

If you are new to the Zigbee EmberZNet SDK, it is recommended to follow these steps:

1. Refer to the Security chapter of the Gecko Platform Release notes for security updates.
2. Subscribe to Security Advisories for up-to-date information.
3. Verify that you are using the correct files and compilers as specified.
4. For detailed instructions on using the SDK, visit the provided link: Zigbee EmberZNet SDK Documentation

New Items in Release 7.1.0.0

New Applications
The Z3GatewayCpc application has been added to facilitate EZSP frame communication using CPC. Ensure the CPC daemon is running on the host for this application to work correctly.

New Components

• The Token Interface component allows access to nvm3 tokens from the host. Refer to the New API section for more details.
• Zigbee EZSP CPC enables communication using the Co-processor Communication feature, preventing the use of NCP bootloading feature in Zigbee components.

New APIs

• The Trust Center Backup Component includes new functions for EUI64 override and updating Zigbeed tokens during power up of the NCP node.
• A new API emberSetRadioIeee802154CcaMode() is available for configuring the 802.15.4 CCA mode in the radio.

Frequently Asked Questions (FAQ)

• Q: Where can I find the latest security updates for the Zigbee EmberZNet SDK?
  A: For security updates and notices, refer to the Security chapter of the Gecko Platform Release notes or visit the TECH DOCS tab on the official Silicon Labs website.

• Q: How can I subscribe to Security Advisories for this product?
  A: To subscribe to Security Advisories and receive up-to-date information, follow the instructions provided in the product documentation or contact Silicon Labs support.

Zigbee EmberZNet SDK 7.1.5.0 GA Gecko SDK Suite 4.1 June 28, 2023

Silicon Labs is the vendor of choice for OEMs developing Zigbee networking into their products. The Silicon Labs Zigbee platform is the most integrated, complete, and feature-rich Zigbee solution available.
Silicon Labs EmberZNet SDK contains Silicon Labs’ implementation of the Zigbee stack specification.

These release notes cover SDK version(s):

• 7.1.5.0 released June 28, 2023 (support for EFR32xG21, Revision C and later, plus bug fixes)
• 7.1.4.0 released January 18, 2023
• 7.1.3.0 released October 19, 2022 (early access part support only)
• 7.1.2.0 released September 28, 2022
• 7.1.1.0 released August 17, 2022
• 7.1.0.0 released June 8, 2022

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/zigbee-emberznet. 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 Zigbee EmberZNet SDK, see Using This Release.

Compatible Compilers:
IAR Embedded Workbench for ARM (IAR-EWARM) version 9.20.4.

• Using wine to build with the IarBuild.exe command line utility or IAR Embedded Workbench GUI on macOS or Linux could result in incorrect files being used due to collisions in wine’s hashing algorithm for generating short file names.
• Customers on macOS or Linux are advised not to build with IAR outside of Simplicity Studio. Customers who do should carefully verify that the correct files are being used.

GCC (The GNU Compiler Collection) version 10.3-2021.10, provided with Simplicity Studio.

KEY FEATURES

• 2.4GHz Zigbee Smart Energy support for xG24
• 802.15.4 Signal Identifier and MAC CCA Mode 2 and 3 support for xG24
• Zigbee Green Power Gateway Backup
• Updated GCC and IAR Compiler Version
• Alpha Concurrent Multiprotocol Zigbee in NCP mode and Open-Thread in RCP mode
• Alpha Dynamic Multiprotocol Bluetooth and multi-PAN 802.15.4 in RCP mode

New Items

New Applications
New in release 7.1.0.0
The Z3GatewayCpc application has been added a host-side application that can send and receive EZSP frames using CPC. This appli-cation is meant to work with an NCP application that also uses the CPC feature. This application requires the CPC daemon to be running on the host. CPC setup is described in https://github.com/SiliconLabs/cpc-daemon/blob/main/readme.md.
Two Zigbee – NCP + OpenThread – RCP applications have been added, one for UART and one for SPI. These applications demonstrate the Zigbee NCP and OpenThread RCP running concurrently using an RTOS. For more information on these applications, see AN1333: Running Zigbee, OpenThread, and Bluetooth Concurrently on a Linux Host with a Multiprotocol RCP.

New Components
New in release 7.1.0.0
Token Interface
A token interface component was added to allow access to the nvm3 tokens from host. Refer to the New API section for more information.

Zigbee EZSP CPC

The Zigbee EZSP CPC component has been added. This component satisfies the requirements of the EZSP Common component and is only applicable when creating a host application. The EZSP CPC component provides a means to send EZSP traffic over a Co-processor Communication (CPC) link. This component is mutually exclusive with the EZSP UART and EZSP SPI components, which handle sending EZSP traffic over a UART or SPI link, respectively. Refer to AN1333: Running Zigbee, OpenThread, and Bluetooth Concurrently on a Linux Host with a Multiprotocol RCP for details of how to configure a system that uses the CPC feature.
Any Zigbee host application that uses the Co-processor Communication (CPC) feature to communicate to and from the NCP must not use the NCP bootloading feature as it is present in the Zigbee components. The CPC daemon is responsible for bootloading a new image to the NCP. For more information, see https://github.com/SiliconLabs/cpc-daemon/blob/main/readme.md.

New APIs
New in release 7.1.0.0
Trust Center Backup Component
The new token interface component provides the following four new APIs:

• uint8_t emberGetTokenCount(void);
• EmberStatus emberGetTokenInfo(uint8_t index, EmberTokenInfo *tokenInfo);
• EmberStatus emberGetTokenData(uint32_t token, uint32_t index, EmberTokenData *tokenData);
• EmberStatus emberSetTokenData(uint32_t token, uint32_t index, EmberTokenData *tokenData);

A new function ( void emberGetRestoredEui64(EmberEUI64 eui64) ) is added to override the EUI64 with the new eui64 token (see below) during power up of the NCP node as part of restore operation.
The Trust Center Back up component is updated with a new function emberAfTrustCenterBackupWriteNcpTokenToZigbeedTokens. This reads an NCP token back-up file that was saved during trust center back up operation and updates the Zigbeed tokens.

Miscellaneous

emberSetRadioIeee802154CcaMode() – A new API has been added to configure the 802.15.4 CCA mode in the radio. See documentation regarding emberSetRadioIeee802154CcaMode.
Added a new configuration option to be used in the sl_set_passive_ack_config() API. The new enum for sl_passive_ack_config_enum_t is SL_PASSIVE_ACK_THRESHOLD_WITH_REBROADCAST_ALL_NODES. This configuration is for both originating and relaying (non-originating) nodes. All configured nodes check for passive ACKs from minAcksNeeded neighbors. They will not rebroadcast received message if all passive ACKs have been received.

New CLI Commands
New in release 7.1.0.0
A new CLI command has been added to configure 802.15.4 CCA mode in the radio. See documentation regarding config-cca-mode.
A new CLI command has been added corresponding to the new emberAfTrustCenterBackupWriteNcpTokenToZigbeedTokens() API (see above).

New Tokens
New in release 7.1.0.0
Trust Center Backup
A new eui64 token is added to the stack token group to save the EUI64 of the operational network that is being backed up.

New Platform Support

• New in release 7.1.5.0
  Added support for BRD4195B and BRD4196B.

• New in release 7.1.1.0
  Added support for BRD2703A.

• New in release 7.1.0.0
  Added support for BRD4186, BRD4187, BRD4188, BRD2601 SOC and BRD4319, BRD4316, BRD4317 module radio boards.

New Documentation
All components have documentation available. If you have an issue seeing the documentation when you select the component in Project Configurator, you can find it here: http://docs.silabs.com/zigbee/7.1

New in release 7.1.1.0

AN1389: Running Zigbee Host Applications in a Docker Container (Replacement for removal of Cygwin as a supported windows host platform)
AN1384: Over-the-Air Bootload Server and Client Setup for Zigbee SDK 7.0 and Higher (Replacement for AN728)

New in release 7.1.0.0

AN1321: Configuring Peripherals for 32 Bit devices with Zigbee 7.0 and Higher
AN1385: Supplemental Performance Results for Multi-PAN RCP for OpenThread and Zigbee
AN1387: Backing Up and Restoring a Z3 Green Power Combo Gateway

Improvements

Changed APIs
Changed in release 7.1.0.0
Return type of emberStartScan and ezspStartScan functions has been changed from EmberStatus to sl_status_t. As a result, the EZSP_PROTOCOL_VERSION is now 9.

Other Improvements

• Changed in release 7.1.2.0
  DynamicMultiprotocolLightMinimal and DynamicMultiprotocolLightSedMinimal are now shown as supported regardless of whether a board has an LCD or has shared button/LED, allowing boards like BRD2703A (which doesn’t have a shared button/LED) to see these applications in Simplicity Studio.

• Changed in release 7.1.1.0
  EZSP Protocol Version changed from 8 to 9 in EmberZNet release 7.1.0.0, but was not previously recorded in the 7.1.0.0 release notes. The corresponding note under 7.1.0.0 in Section 2.1 is revised accordingly.

• Changed in release 7.1.0.0
  GreenPower Combo Host Applications
  The GP Sink Table initialization sequence is changed in host applications that use the Green Power Server cluster and is now called after the NCP is configured.

EZSP CPC
The Zigbee EZSP protocol is now integrated with the Co-processor Communication (CPC) feature. EZSP frames between the host and NCP can now be transported using CPC as the medium. To this effect, the host-side EZSP CPC component has been added. For more information please refer to the New Components section.

Trust Center Backup Component
Extended the Trust Center Back up component with additional functions to support backing-up and restoring tokens using the new token interface APIs. Refer to the New API section for more information.

OTA Update
OTA file search directory is now configurable at runtime using ‘-d’ option in the host application.

Power Source in Device Announce Message
The EmberZNet stack now allows the MAC Capability field of Device Announce messages to dynamically update power source-related subfields in device announce. Whereas previously Capability field values were derived with respect to the Zigbee Device type (Coordina-tor, Router, End Device, Sleepy End Device), now the bit indicating whether the device is connected to a main power supply will be updated in response to changes of the ZDO Power Descriptor. When the Power Descriptor is changed (via the emberSetPowerDescriptor API in stack-info.h) the device will check to see if the state of the “On Main Power” subfield of the descriptor has changed with respect to the corresponding field in the Capability field. In the case where the update to the Power Descriptor changes the state of the On Main Power indication, the updated Device Capabilities will be cached in RAM and returned on subsequent field accesses.
These values are not persisted across reboot, and it is the responsibility of the application to ensure that the Power Descriptor is kept up to date to reflect the current device state.
The long-term guidance for users developing applications with non-standard power configurations (i.e. non-sleepy devices with battery power) is to make use of the ZCL Power Cluster and its associated attributes and commands rather than the stack-level messages and ZDO interfaces. Use of the Cluster interfaces to set and a query Power configuration of devices will likely result in a more consistent experience, and a more straightforward path through device testing and certification.

Multi Network and Multi PAN Components

The Multi Network Stub and Multi PAN Stub components have been removed. These components are no longer needed by a project. Simplicity Studio will prompt the user to upgrade older project files, which will have the reference to these components removed.
Users not utilizing the Multi Network or Multi PAN components will see a drop in flash consumption by the resulting image compared to previous software releases.

Miscellaneous
Incoming packet handler data now includes the NWK header as well.
Type of boolean now changed to bool in the EmberZNet SDK.

Fixed Issues

Fixed in release 7.1.5.0

the local node is not joined to any network. The returned EmberCurrentSecurityState will contain valid data regardless of the joining status of the node.
1159689| Fixed spurious frame pending bit set when there is no data pending.

Fixed in release 7.1.4.0

sinkList.type equal to EMBER_GP_SINK_TYPE_GROUPCAST

The gp sink table now stores the group id for the group cast sink type (EMBER_GP_SINK_TYPE_GROUPCAST) in the token. The sink type enumeration is updated to remove the EMBER_GP_SINK_TYPE_SINK_GROUPLIST.

Fixed in release 7.1.2.0

Host-RCP architecture.
1036743| Implemented CLI to support mac retries on the Host-RCP architecture.
1026938| DMP applications do not fail the trust center link key update process when the key used in the verification is different from the updated key.

Fixed in release 7.1.1.0

checked before processing. An unexpectedly long response could cause a stack overflow.
693536| Fixed an issue where receiving ZDO leave request from a non-parent caused an end device to leave the network.
709981| Fixed an issue that prevented FreeRTOS from being used as a kernel on Zigbee-BLE DMP applications.
748977| Fixed an issue where SPI-EZSP bootloader was unable to launch rcp- spi-802154 on BRD4158a.
756023| Fixed an issue where NCP failed to start after increasing the APS unicast message queue size.
821967| Fixed an issue where an end device would be stuck in “EMBER_JOINING_NETWORK” state when one of the candidate networks closed in the middle of the joining process.
822369| Fixed an issue on EMBER_AF_PLUGIN_OTA_CLIENT_AUTO_START where the OTA client configuration did not take effect in Zigbee on the component-based framework.
833513| Fixed an issue that allowed a router device (Z3Light) to form a centralized network.
833778| Fixed an issue that caused the reportAttributes packet to not be sent in some cases.
841910| Fixed an issue where SE registration plugin unnecessarily required test harness plugin.
843370| Fixed an issue where psa-crypto was enabled by default for gpd-sensor and gpd-switch. We now use RAIL to generate random number for a lower code footprint, but customers can use a stronger random generator by enabling the psa_crypto component, if desired.
843811| Fixed an issue where the message sent callback does not fire when the message is fragmented
845573| A docker container solution is provided by AN1389: Running Zigbee Host Applications in a Docker Container to demonstrate how to run Zigbee host apps on Windows. Note that this is a replacement for building host apps using Cygwin on Windows.
848717| Fixed an issue that made it impossible to set the extension field using ZCL scene CLI.
ID #| Description
---|---
855059| Fixed an issue where Simple Metering and Prepayment cluster command’s parser functions to service the respective ZCL commands in the Gas Proxy Function component were missing.
855066| Fixed an issue where the Simple Metering cluster command’s parser functions to service the respective ZCL Commands in Meter Mirror and GBCS Gas Meter components were missing.
855111| Fixed the ‘print time’ CLI command to print UTC time on the console as designed.
855153| Fixed missing CLI arguments from ‘plugin meter-snapshot-server publish’ command.
855168| Fixed an issue where the Sleepy Message queue component was not de- queuing the packets due to missing the correct event initialization.
855177| Fixed tunnel check/monitoring event in the comms-hub-function component so it activates upon receiving stack status EMBER_NETWORK_UP and becomes inactive upon receiving stack status EMBER_NETWORK_DOWN.
855185| Enabled time util CLI commands to print date/time when zigbee_debug_print component is present in the project.
855829| All data types of size 3, 5, 6, 7 bytes defined by the ZCL specification in the form of Enum/Bitmap/Int/Uint used to be passed as a string or a hex value inside curly braces by the ZCL CLI. The ZCL CLI has now been updated to pass integers instead.

For example:

“zcl price pub-billing-period 11223344 100 0 \”40\” 2 1″ should now change to “zcl price pub-billing-period 11223344 100 0 3159042 2 1”. Here \”40\” was essentially a BITMAP24 which can now just be passed as an integer(3159042) instead.

856047| Fixed an issue where Maximum Time to Wait for Events on the gateway support plugin didn’t take effect after changing default value.
856155| DynamicMultiprotocol minimal application binaries will no longer show up as demo applications.
857679| Fixed an issue where EZSP frames were rendered incorrectly on the debug channel.
858626| Fixed an issue where the rejoin command used the same argument for both of its parameters.
858628| Zigbee RTOS stack task size is now specified directly in bytes instead of converting a value in words into bytes. As a result, the default value of SL_ZIGBEE_OS_STACK_TASK_SIZE has been changed from 1400 to 5600.
858769| Fixed an issue where a Z3Gateway process resulted in 90%-100% CPU usage when adding event.
1019484

1019601

| Fixed an issue where Legacy HAL watchdog functions caused compilation errors due to undefined symbols when supporting headers were not present.

Fixed in release 7.1.0.0

398694

519731

823888

| ZCL reporting plugin is modified so that a rarely-occurring exception condition (failure to read a reportable attribute’s value; possibly because the attribute’s endpoint is disabled) does not result in excess execution cycles, repetitive printing of a debug message, and (for an RTOS configuration) blocking of a lower priority task.
462074| Fixed an issue where the throughput plugin occasionally returned an invalid standard deviation by checking for underflow before the subtraction operation.
679417| Fixed an issue where a failed scan would not allow network-steering (with optimized scans) state machine to advance states.
739044| The Green Power Proxy now forwards the GPDF during commissioning with security failure bit set for a recommissioning GPD with different key type.
756571| Fixed the issue that caused emberPacketHandoffIncoming to receive bad index for EMBER_ZIGBEE_PACKET_TYPE_NWK_DATA/EMBER_ZIGBEE_PACKET_TYPE_NWK_COMMAND packets.
758183| Fixed an issue where OTA updates have been slow for NCP UART HW applications.
759023| The GPD sample has been fixed where it would not work on EFR32MG22 due to a buffer alignment issue.
760176| An issue was resolved where the Z3Gateway host application experienced high CPU load.
760785| The ZCL Default Response Policy setting has been changed from “always” to “conditional” for the following Zigbee sample applications, consistent with their configurations prior to SDK 4.0.0 / EmberZNet 7.0.0: Z3ColorControlLight, Z3DoorLockWithWwah, Z3LightWithWwah, Z3SleepyDoorLockWithWwah.
773136| A buffer assertion issue for incoming malformed packet has been fixed.
773651| Fixed issue that caused the raw_packet_send to send incorrect packet.
ID #| Description
---|---
819344| Fixed an issue where a SPI host application appears hung. If the user hits ENTER or inputs characters on the command line, the application proceeds to run. Such a hang prevents the device from going EMBER_NETWORK_UP on its own, with no user stimulus.
823604| Fixed an issue where component config did not display or allow configuring support for ‘read-modify-write’.
824310| An issue was fixed where an AF-based host application that uses the Green Power Server cluster was reset twice due improper NCP and GP Sink Table initialization sequence.
824289| The Green Power server and client now set the disable default response flag in ZCL frame header while sending out Green Power commands or responses.
824895| Fixed an issue in GPD decommissioning, where the GpPairingConfiguration command will now be issued for sink type group cast.
825777| Fixed an issue on the coordinator/router parent, where the parent did not correctly populate the child table with the details of the new joiner if a secure network layer command frame was not received from the joining end device.
825960| Fixed an issue where malformed Zigbee packet with invalid destination address causes an assert.
829115

843369

843370

| Compiler warnings have been fixed in various sample applications.
829602| Fixed an issue where ‘plugin mfglib stream start’ CLI command does not select the desired antenna TX mode.
831183| Fixed an issue that caused the coordinator to crash upon receiving a trust-center rejoin request after the network is closed for joining.
831270| Fixed an issue where the “Radio output power” CMSIS option in the configuration of the network-steering component had an incorrect data type.
833726| Fixed an issue where the high-byte of the manufacturer ID was mistakenly parsed as the command ID of the cluster, if manufacturer code was present in the message.
835380| Fixed missing Fragmentation component macros to propagate through configuration header.
841300| Restored ability to bypass emAfNetworkInit during initialization when EMBER_AF_TC_SWAP_OUT_TEST is defined.
842020| Fixed issue where calling emberStackPowerDown without the Debug Basic component causes linker errors.
842155| Fixed the network find unused CLI command for a host application that scans and forms the network.

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/zigbee-emberznet in the Tech Docs tab.

N/A

| The following apps/components are not supported in this release

·         Smart Energy multi-MAC switch coordinator

·         Smart Energy multi-MAC selection

·         NCP Sleepy

·         EM4 support

|

Features will be enabled in subsequent releases.

135649

| Multi-networking can cause APS frame counter confusion between networks.| Use emberAfSecurityInitCallback to add EMBER_NO_FRAME_COUNTER_RESET to

EmberInitialSecurityBitmask.

193492

| emberAfFillCommandGlobalServerToClientConfigureRe porting macro is broken. The filling of buffer creates incorrect command packet.| Use the “zcl global send-me-a-report” CLI command instead of the API.

266341

| Z3 Light sample app has two endpoints that support similar cluster commands, so duplicate responses may be generated for certain commands.|

No known workaround

271644

| A device that performs a classic join to a legacy ZLL gateway may eventually leave the network on its own initiative.|

No known workaround

278063| Smart Energy Tunneling plugins have conflicting treatment/usage of address table index.| No known workaround

281832

| Green Power Common plugin incorrectly formats groupList and groupListCount parameters of GP Pairing Configuration frame.|

No known workaround

289569

|

Network-creator component power level picklist doesn’t offer full range of supported values for EFR32

| Edit the range <-8..20> specified in the CMSIS comment for EMBER_AF_PLUGIN_NETWORK_CREATOR_RADIO_P

OWER in the