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:
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.
EmberPacketAction
Description
EMBER_ACCEPT_PACKET
The stack will continue processing the packet
EMBER_ACCEPT_PACKET_
OVERRIDE_SECURITY
Treat an incoming packet as if it was encrypted irrespective whether it is encrypted. On an outgoing packet clear the security bit in the NWK header.
EMBER_ACCEPT_PACKET_
SKIP_NWK_CRYPTO
An outgoing packet will not be NWK encrypted irrespective of its security settings. No functionality on an incoming packet
EMBER_DROP_PACKET
The packet will be dropped. The stack will not process it any further.
EMBER_MANGLE_PACKET
The contents of the packet have been changed in the packet handoff callback. The stack will continue to use the mangled packet
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
Zigbee & Thread Knowledge Base
Packet Handoff plugin how-to guide
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:
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
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
BEACON
(panId)
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
MAC_COMMAND
(NULL)
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
NWK_DATA_PRE_DECRYPTION
(n/a)
EMBER_ZIGBEE_PACKET_TYPE_
NWK_COMMAND_PRE_DECRYPTION
(networkHeaderSize)
(n/a)
EMBER_ZIGBEE_PACKET_TYPE_
NWK_DATA
(NULL)
(networkHeaderSize)
EMBER_ZIGBEE_PACKET_TYPE_
NWK_COMMAND
(NULL)
(networkHeaderSize)
EMBER_ZIGBEE_PACKET_TYPE_
APS_DATA
(NULL)
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
APS_COMMAND
(frameControl)
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
ZDO
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
ZCL
(NULL)
(NULL)
EMBER_ZIGBEE_PACKET_TYPE_
INTERPAN
(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.
EmberPacketAction
Description
EMBER_ACCEPT_PACKET
The stack will continue processing the packet
EMBER_ACCEPT_PACKET_
OVERRIDE_SECURITY
EMBER_ACCEPT_PACKET_
SKIP_NWK_CRYPTO
EMBER_DROP_PACKET
EMBER_MANGLE_PACKET
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
NWK_COMMAND
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
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
and
as described above.