The packet handoff functionality allows the application to get access to Zigbee messages at different stages of their journey through the Zigbee stack. The main use for this is debugging, but with the ability to drop, mangle or otherwise modify a packet, a range of custom behavior can be achieved. Furthermore erroneous or otherwise unwanted messages can be dropped or mangled prior to them being processed by the stack.

With the release of our Gecko SDK 3.1 (EmberZNet 6.9.0) the already existing packet handoff functionality of EmberZNet has been extended. As before the packet handoff functionality is accessible via the packet handoff plugin and allows both incoming as well as outgoing packets of different types to be caught by the application. For specific packets it is possible to drop, mangle or perform other actions on the packet under control of the application. 

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 to be used with great care.

How to enable

The Packet Handoff plugin can be enabled from the plugins tab of the appbuilder, located under Utility. You can search for the term 'Packet' for quicker access. When selected, it offers options to allow all or different types of Zigbee or raw 15.4 packets which can be selected using the checkboxes. 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,

                                                      void *data);

   

EmberPacketAction emberAfOutgoingPacketFilterCallback(EmberZigbeePacketType packetType,

                                                      uint8_t *packetData,

                                                      uint8_t *size,

                                                      void *data);

PacketType is one of the packet types described below

packetData is a buffer containing the payload of the message with the first byte holding the information described in the table below

size is the length of the packet in bytes

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

These callbacks are selected from the callbacks tab of the appbuilder under 'Non cluster related' callbacks. You can search for the term 'packet' and use the + sign to expand all categories for quicker access.

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 Type	Description	Packet starts with	Incoming (Aux Data)	Outgoing (Aux Data)
EMBER_ZIGBEE_PACKET_TYPE_ RAW_MAC	Raw 802.15.4 MAC message	IEEE 802.15.4	(macPayloadLength)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ BEACON	A beacon	IEEE 802.15.4 Beacon	(panId)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ MAC_COMMAND	802.15.4 MAC Command	IEEE 802.15.4 Command	(NULL)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ NWK_DATA_PRE_DECRYPTION	Zigbee Network layer data message prior to NWK decryption	Zigbee Network	(networkHeaderSize)	(n/a)
EMBER_ZIGBEE_PACKET_TYPE_ NWK_COMMAND_PRE_DECRYPTION	Zigbee Network layer command prior to NWK decryption	Zigbee Network	(networkHeaderSize)	(n/a)
EMBER_ZIGBEE_PACKET_TYPE_ NWK_DATA	Zigbee Network layer data message	Zigbee Network	(NULL)	(networkHeaderSize)
EMBER_ZIGBEE_PACKET_TYPE_ NWK_COMMAND	Zigbee Network layer command	Zigbee Network	(NULL)	(networkHeaderSize)
EMBER_ZIGBEE_PACKET_TYPE_ APS_DATA	APS data	Zigbee Application Support	(NULL)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ APS_COMMAND	APS command	Zigbee Application Support Command	(frameControl)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ ZDO	Zigbee Device Object command	Zigbee Device Profile	(emCurrentApsStruct)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ ZCL	Zigbee Cluster Library command	Zigbee Cluster Library	(NULL)	(NULL)
EMBER_ZIGBEE_PACKET_TYPE_ INTERPAN	Interpan message	Zigbee Cluster Library (with Interpan info)	(senderEui64)	(NULL)

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

Packet type	EMBER_ACCEPT_ PACKET	EMBER_ACCEP T_PACKET_OV ERRIDE_SECURITY	EMBER_ACCEP T_PACKET_SKI P_NWK_CRYPTO	EMBER_ DROP_PACKET	EMBER_MA NGLE_PACKET
RAW_MAC
BEACON
MAC_COMMAND
NWK_DATA_PRE_DECRYPTION
NWK_COMMAND_PRE_DECRYPTION
NWK_DATA			(outgoing only)
NWK_COMMAND			(outgoing only)
APS_DATA
APS_COMMAND
ZDO
ZCL
INTERPAN

Note: Any unknown or unsupported return value provided through the callbacks is treated as 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 emberPacketHandoffIncoming(EmberZigbeePacketType packetType,

                                             EmberMessageBuffer packetBuffer,

                                             uint8_t index,

                                             void *data);

EmberPacketAction emberPacketHandoffOutgoing(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

These functions are also available on the SoC and feed into the packet handoff plugin which in turn exposes 

emberAfIncomingPacketFilterCallback()

and

emberAfOutgoingPacketFilterCallback()

as described above.