SILICON LABS EmberZNet SDK Gecko Software Development Kit User Guide

SILICON LABS EmberZNet SDK Gecko Software Development Kit

Product Information

Specifications

• Zigbee EmberZNet SDK Version: 7.4.2.0
• Gecko SDK Suite Version: 4.4
• Release Date: April 10, 2024
• Vendor: Silicon Labs
• Platform: Silicon Labs Zigbee
• Key Features : Multiprotocol (CMP) Zigbee and OpenThread support on SoC
• Compatible Compilers: GCC (The GNU Compiler Collection) version 12.2.1
• EZSP Protocol Version: 0x0D

Product Usage Instructions

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 the latest information.

Using This Release
If you are new to the Zigbee EmberZNet SDK, follow the instructions provided to ensure correct usage.

Key Features Utilization
Take advantage of the multiprotocol support for Zigbee and OpenThread on the SoC platform for enhanced connectivity.

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.4.2.0 released April 10, 2024
• 7.4.1.0 released February 14, 2024
• 7.4.0.0 released December 13, 2023

KEY FEATURES

Zigbee

• Zigbee R23 compliance
• Zigbee Smart Energy 1.4a compliance – pro-duction
• Zigbee GP 1.1.2 compliance – Alpha
• MG27 support – production
• Improved support for Secure Vault parts
• Sleepy support on NCP SPI (non-CPC) applications – Alpha

Multiprotocol

• Concurrent Listening support (RCP) – MG21 and MG24
• Concurrent Multiprotocol (CMP) Zigbee NCP + OpenThread RCP – production
• Dynamic Multiprotocol Bluetooth + Concurrent 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 at 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, seeUsing This Release.

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

• 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 12.2.1, provided with Simplicity Studio. The EZSP protocol version for this release is 0x0D.

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
New in release 7.4.0.0

• The “zigbee_direct_security_p256” and “zigbee_direct_security_curve25519” components have been added so that users can configure a specific Zigbee Direct security option.
• Users are allowed to have multiple “zigbee_direct_security” components enabled on a Zigbee direct device (ZDD) application. In this case, the actual security option depends on the Zigbee Virtual Device (ZVD) configuration.

New APIs
New in release 7.4.2.0

• Extended SPI NCP to be used as sleepy in some Host-NCP use cases. In this use case, the SPI NCP can be configured as a sleepy end device. The host Z3Gateway sample application is extended with additional custom CLI code responsible for commanding the NCP to enter one of the sleep modes through the custom CLI command sleep mode, and must wake up using the custom CLI command wakeup before further EZSP communication.
• Introduced a new API sl_zigbee_af_isr_event_init to initialize the application framework events that are intended to be activated inside an interrupt service routine(ISR). These events, which are scheduled from the ISR, must have a delay param of 0 milliseconds. In other words, events from ISR must be activated as an immediate event. There is no event deactivation allowed inside ISR. The reason for the above is as follows. The event system uses the event queue manipulation during scheduling (activating with a non-zero delay, or deactivating) an event. To minimize the latency, an ISR should activate an event with 0 delay, that gets scheduled as the next event in the next event queue processing. This allows further delay, or deactivation, to be carried out after ISR exits. To distinguish the events intended to be used inside ISR, the event structure is marked with a sli_zigbee_isr_event_marker during initialization. Refer to the zigbee_app_framework_event.h source file for details of this new function.
• Clarification on the use of the new function emberUpdateMultiMacRejoinChannelMaskForSelectionOrJoiningDevice that is called inside the stack API emberFindAndRejoinNetworkWithReason to get a channel mask used for rejoining. The SE1.4a specification restricts the change of interface (from 2.4GHz to sub-GHz or vice versa) during the rejoining of a Multi-Mac Joining End device type device. Since the device type is an application framework configuration (that is, the joining end device type will be either a sub-GHz device or a 2.4 GHz device, not both, at configuration), this call provides the channel mask based on that configuration so that the rejoin mask is always same as the joining interface mask.

New in release 7.4.0.0

• Added a new API sl_zigbee_token_factory_reset to reset Zigbee NVM3 tokens to their default value.
• Added the API bool sl_zigbee_sec_man_link_key_slot_available(EmberEUI64 eui), which returns true if the link key table can add or update an entry with this address (table is not full).

Added a new API bool sl_zb_sec_man_compare_key_to_value (sl_zb_sec_man_context_t context, sl_zb_sec_man_key_t key), which returns true if the key being referenced by context has the same value as the key supplied in the argument.

New Platform Support
New in release 7.4.0.0
Zigbee stack support for the following new parts is added in this release: EFR32MG24A010F768IM40 and EFR32MG24A020F768IM40.

New Documentation
New in release 7.4.0.0
Updated the description for the Zigbee Secure Key Storage component to reflect the addition of Zigbee Secure Key Storage Upgrade (which adds backward compatibility with existing projects).
Added a new application note for interacting with the Zigbee Security Manager group of components (AN1412: Zigbee Security Manager).

Intended Behavior
Users are reminded that Zigbee unsynchronized CSL transmissions are subject to protocol preemption at the radio scheduler. In the SleepyToSleepy applications, BLE can and will preempt a Zigbee CSL transmission, which will terminate the transmission. Scheduler preemption is more common for unsynchronized CSL, given that a potentially lengthy wake-up frame sequence may be used. Users wishing to adjust transmission priorities may use the DMP Tuning and Testing component to do so. Users may also consult UG305: Dynamic Multiprotocol User’s Guide for more information.

Improvements

Changed in release 7.4.0.0
emberCounterHandler API Doc Changes
In previous versions, the Counter Handler callback for MAC and APS layer EmberCounterTypes concerning packet RX and TX was not being passed the passing proper target node ID or data arguments, and API documentation concerning behavior of certain counters that used these parameters was unclear or misleading. While the signature of emberCounterHandler() has not changed, the way its parameters are populated have changed slightly.

• Comments around EmberCounterType enums in ember-types.h have been expanded for clarity.

• The Node ID parameter to the Counter Handler for TX-related counters now checks whether the destination address mode indicates a valid short ID before using it. (If not, no destination address is populated, and a placeholder value of
  EMBER_UNKNOWN_NODE_ID is used instead.)

• The Node ID parameter to the Counter Handler for RX-related counters now reflects the source node ID, not the destination node ID.

• Retry count is not passed as the data parameter for EMBER_COUNTER_MAC_TXUNICAST SUCCESS/FAILED counters as described in ember-types.h in previous versions, but this was never properly populated in previously released versions so its value in previous releases would always have been 0. This behavior has been clarified in the description of those EmberCounterTypes. However, the Retry count for APS layer retries continues to be populated in the data parameter for
  EMBER_COUNTER_APS_TX_UNICAST_SUCCESS/FAILED counter types, to be consistent with prior releases.

• All counters that populate the Node ID or data parameter for the callback have been audited to ensure they pass the expected data, address, or EMBER_UNKNOWN_NODE_ID if a Node ID was expected but could not be obtained from the packet, as described in the revised ember-types.h documentation.

• The Counter handler for EMBER_COUNTER_MAC_TX_UNICAST_RETRY now correctly reflects the MAC layer destination node ID and number of retries in its Destination Node ID and data parameters.

• The Counter handler for EMBER_COUNTER_PHY_CCA_FAIL_COUNT now provides destination node ID information through the Node ID parameter about the intended MAC layer target of the message that failed transmission.

Updated Green Power Code
Green power server code is updated with various improvements including:

• Added more validation code for incoming commands with invalid endpoint when receiving on the GP server.
• Added code to handle the case when there is no more space to build green power messages.
• The sink now drops pairing configuration with action remove pairing in some cases per spec section A.3.5.2.4.1.
• The sink now saves the existing group list of an entry before removing when processing Pairing Configuration with action extend.
• The Translation query command returns “NOT FOUND” as the error code when the translation table is empty or the index is bigger than number of entries in the table.
• Changed the version of GP endpoint in some apps from 1 to 0.

Using CSMA in the GPDF Send function is restricted because Green Power Devices are minimal energy devices and do not use CSMA in most of the designs. Instead, the preferred design is to send out multiple packets using the same energy budget.
Removed the use of a hidden endpoint in the Green Power Server plugin option. Use one of the application endpoints instead.

Network Key Update Plugin Code Improvements
Changed the periodic network key update period to be as long as 1 year.

Restructured Some APIs to Avoid Unnecessary Key Export
Made changes to favor the use of key contexts over plaintext key data.

• sl_zigbee_send_security_challenge_request now takes in a sl_zb_sec_man_context_t argument in place of EmberKeyData.
• The sl_zb_sec_man_derived_key_type enum’s values are now a 16-bit bitmask to directly support certain key derivations that com-bine multiple derived types.

Fixed Issues

Fixed in release 7.4.2.0

1252268

| The zigbee host application option to open an IP port on 4900/4901 is deprecated.

The alternative way to use a remote connection in order to interact with the host application may be to use the socat utility in most supported operating systems.

(Other ref: 1232361)

1254541

| A new event initialization function, sl_zigbee_af_isr_event_init, is introduced to allow the initialization of the application events intended to be activated from an interrupt service routine (ISR).

These events can only be activated from the ISR with delay of 0 msec.

These events shall not be scheduled with a non-zero delay or deactivated from within ISR.

The application framework documentation for the above function has been added. Please refer to docs.silabs.com for this release for the above API documents.

(Other ref: 1252940)

1255175| Fixed issue that caused the APS Verify Key Confirm message processing error. (Other ref: 1227738)

1260605

| Optional optionsMask parameter for “net multi-phy-start” CLI command was being ignored and always treated as 0.

(Other ref: 1258636)

1262538| Fixed an issue that the GP server did not drop frame with FC equal to stored FC. (Other ref: 1259936)
1263124| Removed code for deprecated MAC command handling. (Other ref: 1262368)
1266765| Fixed an issue with the label of the pro leaf stack. (Other ref: 1259298)
1270706| Fixed an issue that prevented the application framework to send out ZCL default response for success case.
1272181| Fixed an issue that caused build failure when enabling expanded reporting table on Z3Gateway. (Other ref: 1188397)

1272280

| The SE1.4a specification requires a Multi-MAC Joining End Device to rejoin on the same interface it has previously joined. No change of interface (switching from 2.4GHz to Sub-GHz or vice versa) is allowed during rejoining. The rejoin may be initiated as a result of parent loss or a power recycle of the node. In both of these cases, the stack API emberFindAndRejoinNetworkWithReason is called internally to start the rejoin process, and this API needs the rejoin channel mask as an argument. This channel mask is aquired by the stack by the calling function, emberUpdateMultiMacRejoinChannelMaskForSelectionOrJoiningDevice, that is implemented as source and as part of the application project.

A default implementation can be found in the ember-configuration.c as a WEAK function so that a user override is possible.

1273235

| Triggering a child removal operation for a sleepy end device child when an Association Response or Rejoin Response is still pending delivery for that child can result in two erasures for the same child entry. This will leave the emberChildCount() off by -1. If this is the last child in the table to be removed, this can lead to an underflow of the child count. This inhibit any further join/rejoin attempts by any end devices until a reset or LeaveNetwork is performed, which may result in an assert failure (citing child.c) in certain releases.

1273585

| The initialization value for the green power security frame counters in non volatile memory is set to 0 from 0xFFFFFFFF.

(Other ref: 1269700)

1277012| If the child table is full, and an existing child of the local device tries to rejoin, the rejoin is incorrectly rejected, causing the child entry to be removed and forcing the child to rejoin again to get reassociated with that parent.

Fixed in release 7.4.1.0

legacy boot-loader interface component as a dependency.
1114905| Zigbee Direct: Improved handling of Leave Network Characteristic.
1180937| Fixed WDT reset when connecting Zigbee Direct ZDD to 3rd party ZVD.
1223904| Fixed an issue that caused the end device move to work incorrectly in a very busy environment.
1224393| Updated the Green Power sink table request handler code to update the response destination address.
1228808| Fixed the display issue with macro definitions in gp-types.h documentation.
1232297| Fixed an issue where emberSetOutgoingNwkFrameCounter and emberSetOutgoingApsFrameCounter did not work on 64-bit host applications (returning EMBER_BAD_ARGUMENT).
1232359| Fixed the gppTunnelingDelay parameter calculation in green power client command processing.

1240392

| ZDO Bind/Unbind Requests refused for access/permission reasons should return EMBER_ZDP_NOT_AUTHORIZED status rather than EMBER_ZDP_NOT_PERMITTED status as per Zigbee specifications.
1243523| Zigbee Direct: Improved stability of BLE connection to ZVD.
1249455| Fixed an issue that caused a sleepy end device to enter sleep when received a broadcast before receiving an ack.
1252295| Fix a typo error in component catalog macro SL_CATALOG_ZIGBEE_OTA_STORAGE_COMMON_PRESENT.

Fixed in release 7.4.0.0

that it can be removed when not needed.
1024246| Updated the function description for emberHaveLinkKey() and sl_zb_sec_man_have_link_key().
1036503| Added a description to recommend use of the Micrium Kernel for DMP sample apps.
1037661| An issue that was preventing the application to install either pro stack or leaf stack has been fixed.
1078136| Fixed an intermittent crash when modifying events from interrupt context

1081548

| Users are reminded that Zigbee unsynchronized CSL transmissions are subject to protocol preemption at the radio scheduler. In the SleepyToSleepy applications, BLE can and will preempt a Zigbee CSL transmission, which will terminate the transmission. Scheduler preemption is more common for unsynchronized CSL, given that a potentially lengthy wake up frame sequence may be used. Users wishing to adjust transmission priorities may use the DMP Tuning and Testing component to do so. Users may also consult UG305: Dynamic Multiprotocol User’s Guide for more information.

An issue has been fixed in CSL where a new wake up frame sequence that is received immediately following a previous payload frame would not be recorded correctly. This would result in a missed payload frame.

1084111| Initial sleepy SPI-NCP support for MG24 based boards are updated as part of this release.
1104056| Added support for network-steering to run on secondary network in case of multi-network
1120515| Fixed an issue where the channel did notchange when using the mfglib set-channel command.
1141109| Fixed an issue that caused the generated sample application ncp-uart- gp-multi-rail to miss some header files when using the Green Power adapter component with the -cp option.
1144316| Updated the description of some data structure types in gp-types.h documentation.
1144884| Fixed spurious frame pending bit set when there is no data pending.
1152512| Fixed a potential crash in low-mac-rail when modifying the event in isr context.
1154616| Added an exception for the condition to initialize the network with the case “Switching role from Sleepy End device to Non-sleepy End device”.
1157289| Fixed an issue that may cause BDB test failure DN-TLM-TC-02B.
ID #| Description
---|---
1157426| Fixed a build issue when building zigbee_simple_app with green_power_adapter component.
1157932| Added a condition to check if the “transition time” field is missing and set a default value 0xFFFF for this missing field.
1166340| Fixed an issue that was preventing the emberAfGpdfSend from sending out the intended number of repeated transmissions.
1167807| Fixed an issue where devices acting as Trust Centers in distributed networks would incorrectly clear their transient link keys each time a new device joined.
1169504| Fixed an issue that caused reset of a sleepy device upon force wake up.
1169966| Fixed missing return value validation in buffer allocation code.
1171477,

172270

| With mfglib start 1 no messages are transmitted but received, so the displayed terminal message “mfglib send complete” is wrong andchanged to “RXed %d packets in the last %d ms”.
1171935| Changed the periodic network key update period to be as long as 1 year.
1172778| Added the missing invocation of the emberAfPluginGreenPowerServerUpdateAliasCallback to the Green Power server..
1174288| Fixed an issue that causes the network steering process to assert if a call to stop ongoing scan is called.
1178393| Updated a documentation error.
1180445| In Smart Energy, OTA now continues to download if the Coordinator reaches Limited Duty Cycle.
1185509| Fixed an issue in CSL where a new wake up frame sequence that is received immediately following a previous payload frame would not be recorded correctly. This would result in a missed payload frame.
1186107| Fixed an issue that caused the unsuccessful decryption of received GPDFs to replace the incoming GPDF in the gp commissioning notification.
1188397| Fixed an issue that caused a compilation error when enabling extended report table size.
1194090| Corrected the failure status in the default response for Sink Commissioning Mode command – following section 3.3.4.8.2
1194963| Fixed an issue that memset the commissioningGpd structure before calling user callback emberAfGreenPowerServerPairingStatusCallback.
1194966| Fixed an issue where the endpoint and proxiesInvolved fields were not set with the Exit Commissioning action.
1196698| Fixed a spurious frame pending bit set when there was no data pending.
1199958| Added code to handle the case when there is no more space to build green power messages.
1202034| Fixed an issue where sl_zb_sec_man_context_t stack variable was not initialized correctly, causing joining with install code to fail.

1206040

| Calling emberRemoveChild() during a secure rejoin attempt by an end device can potentially lead to an extra decrement of the Child Count, potentially leading to a Child Count of -1 (255), inhibiting end devices from joining/rejoining due to an indicated lack of capacity in the Beacon.

1207580

| Child Table search functions within the stack are inconsistent in use of 0x0000 versus 0xFFFF for node ID return value representing invalid/empty entries, leading to problems checking for unused entries in APIs like emberRemoveChild().
1210706| Destination and PHY Index provided in EmberExtraCounterInfo struct as part of emberCounterHandler() may have been incorrect for MAC TX Unicast counter types.
1211610

1212525

| Fixed an issue where Dynamic Multiprotocol applications crashed after enabling Secure Key Storage Upgrade component.
1211847| While the signature of emberCounterHandler() has not changed, the way its parameters are populated have changed slightly. Changes around this API is explained in section 2 above.

1212449

| Outgoing Beacons were incorrectly categorized by the MAC layer, leading to emberCounterHandler() failing to catch these packets with the EMBER_COUNTER_MAC_TX_BROADCAST counter type and instead counting the Beacons with the EMBER_COUNTER_MAC_TX_UNICAST_SUCCESS counter type. That potentially resulted in unreliable values for the dest EmberNodeId parameter passed to the EmberCounterInfo struct
1214866| Sending data poll packet in certain high-traffic configurations may result in a bus fault.
1216552| An issue that causes an assertion under busy traffic conditions is fixed.
1216613| Fixed an issue which led to an incorrect value of groupcast radius in the proxy table.
ID #| Description
---|---
1222509| Router/coordinator sends a leave & rejoin request to a non-child polling end device, but the MAC destination is 0xFFFF instead of matching the NWK destination address.
1223842| Fixed an issue with generation of the sl_component_catalog.h that was leaving unwanted code in it causing compilation failure.
756628| Changed the invocation of application callback emberAfMacFilterMatchMessageCallback to only be called for the ZLL messages that are validated by the stack.
816088| Moved EMBER configuration from zigbeed_configuration.h to zigbeed.slcp.
829508| To avoid a race condition, additional validation was added in emberSetLogicalAndRadioChannel to return unsuccessful if the lower layers are busy or not in a state to change the channel.

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.

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.
278063| Smart Energy Tunneling plugins have conflicting treatment/usage of address table index.| No known workaround

289569

|

The 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