The packet handoff component enables applications to access Zigbee messages at various points during their transit through the Zigbee stack. Primarily used for debugging, it also allows for the dropping, mangling, or modification of packets, enabling a variety of custom behaviors. Additionally, erroneous or unwanted messages can be intercepted and altered before the stack processes them.

Warning: Dropping, mangling or otherwise interfering with incoming or outgoing packets may affect Zigbee compliance and interoperability with other Zigbee certified devices. This is for expert users and to be used with great care.

Important Note: The packet handoff callbacks are called directly from the Zigbee stack and in case of RTOS based applications they will not pass through the IPC Layer to the application thread, but instead must be handled within the Zigbee stack thread. 

How to enable

The Packet Handoff Component can be enabled from the Software Components tab of the Project Configurator (open .slcp file of your project). You can find the component in Zigbee > Utility > Packet Handoff.
 

When this component is installed, it offers the option to allow all or different types of Zigbee or raw 15.4 packets which can be selected. Additionally you also provide a buffer size to store the flat packet buffers.

APIs

When including the packet handoff plugin, it is possible to select which of the packet types described further down will be handed to the following two callbacks:

EmberPacketAction emberAfIncomingPacketFilterCallback(EmberZigbeePacketType packetType,
                                                      uint8_t* packetData,
                                                      uint8_t* size_p,
                                                      void *data);

EmberPacketAction emberAfOutgoingPacketFilterCallback(EmberZigbeePacketType packetType,
                                                      uint8_t* packetData,
                                                      uint8_t* size_p,
                                                      void* data);

PacketType  represents the type of packet received. See * ::EmberZigbeePacketType.

packetData A flat buffer containing the packet contents. The buffer starts with the command id followed by the payload.

size_p a pointer to the size of the packet data

data This is a pointer to auxiliary data for the command. This depends on the packet type.

Packet Types

The table below lists all packet types used by the packet handoff feature and whether they are supported on the incoming and outgoing side. It also shows any corresponding auxiliary data and indicates what field first byte of the handed over payload comprises of.

Packet Actions

Both the incoming and the outgoing callbacks use an 'EmberPacketAction' as the return type. The following definitions are available for this. They are defined in ember-types.h.

Supported Packet Actions per Packet Type

Note: Any unknown or unsupported return value provided through the callbacks is treated as EMBER_ACCEPT_PACKET.

Example:

This is an example that is included in the app.c of Zigbee SoC application or in zigbeed:

// packetHandoff
EmberPacketAction emberAfIncomingPacketFilterCallback (EmberZigbeePacketType packetType, int8u *packetData, int8u *size_p, void *data){

  switch (packetType)
    {
    //case <packetType>:
      //code
      //break;
    case EMBER_ZIGBEE_PACKET_TYPE_APS_DATA: // APS packet
      syslog(LOG_INFO, "APS_DATA ----> %u", packetType);
      break;
    default:
      break;
    }

  syslog(LOG_INFO, "Packet data bytes ---->");
  for (int i = 0; i < *size_p; ++i)
    {
      syslog(LOG_INFO, "%x", packetData[i]);
    }
  // Depending on your use case you can change the EmberPacketAction you return
  return EMBER_ACCEPT_PACKET; 
}

(x)NCP support

The packet handoff plugin as described above is only available in SoC mode. This is to avoid overloading the serial lines between the host and NCP with these intermediary packet types.

When building an xNCP the following two callbacks are available on the NCP

 

 EmberPacketAction sli_zigbee_af_packet_handoff_incoming_callback(EmberZigbeePacketType packetType,
                                                EmberMessageBuffer packetBuffer, 
                                                                  uint8_t index,
                                                                    void *data); 

EmberPacketAction sli_zigbee_af_packet_handoff_outgoing_callback(EmberZigbeePacketType packetType,             
                                                EmberMessageBuffer packetBuffer, 
                                                                  uint8_t index,  
                                                                    void *data);

packetType is one of the packet types described below

packetBuffer is a message buffer containing the complete message as it is handled by the stack

index is a pointer to the first byte in the packet buffer which represents the start of the defined packet type

data is auxiliary data which differs depending on the corresponding packet type

There is an issue when generating custom ZCL clusters using Simplicity SDK (SiSDK) 2024.12.x.  For ZAP to be able to generate the custom clusters, the required steps are slightly different for Zigbee projects and for Matter projects.  Follow the steps for the correct section.

Zigbee Projects

1. Exit Simplicity Studio and make sure no instances of ZAP are running using the OS task manager.
2. Go to the 2024.12.x SiSDK folder.  Default is in the user folders at [SimplicityStudio/SDKs/simplicity_sdk].
3. In the app/zcl subfolder, paste your custom xml file.
4. Use a text editor to open the app/zcl/zcl-zap.json file,
5. Add your custom xml file name to "xmlFile" array in this file, making sure to include the '.xml' extension.

Matter Projects

1. Exit Simplicity Studio and make sure no instances of ZAP are running using the OS task manager.
2. Go to the 2024.12.x SiSDK folder.  Default is in the user folders at [SimplicityStudio/SDKs/simplicity_sdk].
3. Copy your custom xml file to the extension/matter_extension/third_party/matter_sdk/src/app/zap-templates/zcl folder.
4. Use a text editor to open extension/matter_extension/src/app/zap-templates/zcl/zcl.json.
5. Add your custom xml file name to "xmlFile" array in this file, making sure to include the '.xml' extension. 

When you start Simplicity Studio and open the ZAP tool for a Zigbee / Matter project, the custom clusters should be available to enable and configure.

Zigbee Stack has already provided the ota server solution for NCP mode,where the over-the-air (OTA) upgrade server application runs on a host with a POSIX file system.However, some customers with more streamlined "thin" gateway solutions seek to implement an OTA server device on a system-on-chip (SoC) design model.Here are some instructions on how to setup the ota server on a SoC device.

• HW Platform: EFR32MG12 (BRD4162 development board) mounted to WSTK
• SW Platform: EmberZNet 6.4.1 SDK with Zigbee Application Framework (SOC, not Host)
• Bootoader: SPI flash storage bootloader(single image), the ota image is stored in the SPI flash

1.Generate a Z3light sample and enable the ota server relative plugins and options,for more detaileds please refer to the attached isc file. For adapting the code logic of the OTA Simple Storage EEPROM Driver Plugin,SOC Bootloading Support option must be disabled and OTA Storage Start Offset must be set to 0.

2. Modify the emAfOtaStorageDriverGetRealOffset() as below only on the server side.

bool emAfOtaStorageDriverGetRealOffset(uint32_t* offset,

uint32_t* length)

{

bool spansBreak = false;

uint32_t realOffset = *offset;

*offset = realOffset;

return spansBreak;

}

3.Build the bootloader and Z3light applicaton firmwares and upload them to the board.

4.Flash the ota file to the SPI flash with commander tool.

5.Issue cli command<plugin ota-storage-common printImages> on the console, the below information should be printed,that means the the ota file is parsed correctly and the ota server is available now.

Next step, you can try to setup a ota client to download the ota firmware from this ota server. Here is a relevant KBA for your reference.How to setup OTA Server and OTA Client on WSTK+4162 radio boards?