EmberZNet Serial Protocol#
All EZSP frames begin with the same three fields: sequence, frame control, and frame ID. The format of the rest of the frame depends on the frame ID. EZSP Frame Format defines the format for all frame IDs. Most of the frames have a fixed length. A few, such as those containing application messages, are of variable length. The frame control indicates the direction of the message (command or response). For commands, the frame control also contains power management information (SPI interface only). For responses, the frame control also contains status information.
The host initiates a two-message transaction by sending a command message to the NCP. The NCP then sends a response message to the host. When connected using the SPI interface, if the NCP needs to communicate a callback to the host, it will indicate this using the interrupt line and then wait for the host to send the callback command. When connected using the UART interface, the NCP can send callbacks to the host asynchronously as soon as they occur.
When a command contains an application message, the host must supply a one-byte tag. This tag is used in future commands and responses to refer to the message. For example, when sending a message, the host provides both the message contents and a tag. The tag is then used to report the fate of the message in a later response from the NCP.
Silicon Labs designed EZSP to be very familiar to customers who have used the EmberZNet PRO stack Application Programming Interface (API). The majority of the commands and responses are functionally identical to those found in EmberZNet PRO. The variations are due mainly to the timing differences of running the application on a separate processor across a serial interface.
EZSP Protocol Version#
The EZSP Protocol Version identifies the version number of the EZSP API. This version number changes across EmberZNet PRO software releases when the EZSP API changes in a way that is not backward-compatible. To interoperate, the host and NCP must use compatible EZSP protocol versions. Following NCP reset, the host first issues the version command to the NCP to confirm that the two are operating with compatible versions. If they are not, operation cannot proceed. This document describes current EZSP version that is identified by the macro EZSP_PROTOCOL_VERSION and stack type 2 (mesh).
The macro EZSP_PROTOCOL_VERSION is updated to correspond to a change that affects the protocol. The EZSP Protocol Version for this EmberZNet PRO software release is 16.
Byte Order#
All multiple octet fields are transmitted and received with the least significant octet first, also referred to as “little endian”. This is the same byte order convention specified by 802.15.4 and ZigBee. Note that EUI64 fields are treated as a 64-bit number and are therefore transmitted and received in little endian order. Each individual octet is transmitted and received by the SPI or UART interface. See AN706: EZSP-UART Host Interface Guide and AN711: EZSP-SPI Host Interface Guide for more information about the UART and SPI interfaces respectively.
Conceptual Overview#
This section provides an overview of the concepts that are specific to EZSP or that differ from the EmberZNet PRO stack API. The commands and responses mentioned in this overview are described in more detail later in this document.
Stack Configuration#
To ensure that the NCP and the host agree on the protocol format, the first command sent by the host after the NCP has reset must be the version command. There are a number of configuration values that affect the behavior of the stack. The host can read these values at any time using the getConfigurationValue command. After the NCP has reset, the host can modify any of the default values using the setConfigurationValue command. The host must then provide information about the application endpoints using the addEndpoint command.
The following table gives the minimum and maximum values for each of the configuration values. Also listed is the RAM cost—the number of bytes of additional RAM required to increase the configuration value by one. Because the total amount of RAM is fixed, the additional RAM required must be made available by reducing one of the other configuration values.
Note: Due to code size constraints, Silicon Labs does not bound check any EZSP values on the NCP. Silicon Labs recommends implementing bound checks on the host side.
Configuration Values#
Configuration Value | Min | Max | Units | RAM Cost | Description |
|---|---|---|---|---|---|
SL_ZIGBEE_EZSP_CONFIG_PACKET_BUFFER_COUNT | 5 | 253 | packet buffers | 39 | The number of packet buffers available to the stack. When set to the special value 0xFF, the NCP will allocate all remaining configuration RAM towards packet buffers, such that the resulting count will be the largest whole number of packet buffers that can fit into the available memory. |
SL_ZIGBEE_EZSP_CONFIG_NEIGHBOR_TABLE_SIZE | 16 | 26 | neighbors | 18 | The maximum number of router neighbors the stack can keep track of. A neighbor is a node within radio range. |
SL_ZIGBEE_EZSP_CONFIG_APS_UNICAST_MESSAGE_COUNT | 0 | messages | 6 | The maximum number of APS retried messages the stack can be transmitting at any time. | |
SL_ZIGBEE_EZSP_CONFIG_BINDING_TABLE_SIZE | 0 | 127 | entries | 2 | The maximum number of non-volatile bindings supported by the stack. |
SL_ZIGBEE_EZSP_CONFIG_ADDRESS_TABLE_SIZE | 0 | entries | 12 | The maximum number of EUI64 to network address associations that the stack can maintain for the application. (Note: The total number of such address associations maintained by the NCP is the sum of the value of this setting and the value of EZSP_CONFIG_TRUST_CENTER_ADDRESS_CAC HE_SIZE.). | |
SL_ZIGBEE_EZSP_CONFIG_MULTICAST_TABLE_SIZE | 0 | entries | 4 | The maximum number of multicast groups that the device may be a member of. | |
SL_ZIGBEE_EZSP_CONFIG_ROUTE_TABLE_SIZE | 0 | entries | 6 | The maximum number of destinations to which a node can route messages. This includes both messages originating at this node and those relayed for others. | |
SL_ZIGBEE_EZSP_CONFIG_DISCOVERY_TABLE_SIZE | 0 | entries | 10 | The number of simultaneous route discoveries that a node will support. | |
SL_ZIGBEE_EZSP_CONFIG_BROADCAST_ALARM_DATA_SIZE | 0 | 16 | bytes | 1 | The size of the alarm broadcast buffer. |
SL_ZIGBEE_EZSP_CONFIG_UNICAST_ALARM_DATA_SIZE (A) | 0 | 16 | bytes | (C) | The size of the unicast alarm buffers allocated for end device children. |
SL_ZIGBEE_EZSP_CONFIG_STACK_PROFILE | 0 | 0 | Specifies the stack profile. | ||
SL_ZIGBEE_EZSP_CONFIG_SECURITY_LEVEL | 0 | 5 | 0 | The security level used for security at the MAC and network layers. The supported values are 0 (no security) and 5 (payload is encrypted and a four-byte MIC is used for authentication). | |
SL_ZIGBEE_EZSP_CONFIG_MAX_HOPS (B) | 0 | hops | 0 | The maximum number of hops for a message. | |
SL_ZIGBEE_EZSP_CONFIG_MAX_END_DEVICE_CHILDREN (C) | 0 | 64 | children | 9 + (A) | The maximum number of end device children that a router will support. |
SL_ZIGBEE_EZSP_CONFIG_INDIRECT_TRANSMISSION_TIMEOUT | 0 | 30000 | milliseconds | 0 | The maximum amount of time that the MAC will hold a message for indirect transmission to a child. |
SL_ZIGBEE_EZSP_CONFIG_END_DEVICE_POLL_TIMEOUT | 0 | 14 | 2^(D) seconds | 0 | The maximum amount of time that an end device child can wait between polls. If no poll is heard within this timeout, then the parent removes the end device from its tables. The timeout corresponding to a value of zero is 10 seconds. The timeout corresponding to a nonzero value N is 2^N minutes, ranging from 2^1 = 2 minutes to 2^14 = 16384 minutes. |
SL_ZIGBEE_EZSP_CONFIG_MOBILE_NODE_POLL_TIMEOUT | 0 | quarter seconds | 0 | The maximum amount of time that a mobile node can wait between polls. If no poll is heard within this timeout, then the parent removes the mobile node from its tables. | |
SL_ZIGBEE_EZSP_CONFIG_RESERVED_MOBILE_CHILD_ENTRIES | 0 | (C) | entries | 0 | The number of child table entries reserved for use only by mobile nodes. |
SL_ZIGBEE_EZSP_CONFIG_TX_POWER_MODE | 0 | 3 | 0 | Enables boost power mode and/or the alternate transmitter output. | |
SL_ZIGBEE_EZSP_CONFIG_DISABLE_RELAY | 0 | 1 | 0 | 0: Allow this node to relay messages. 1: Prevent this node from relaying messages. | |
SL_ZIGBEE_EZSP_CONFIG_TRUST_CENTER_ADDRESS_CACHE_SIZE | 0 | entries | 12 | The maximum number of EUI64 to network address associations that the Trust Center can maintain. These address cache entries are reserved for and reused by the Trust Center when processing device join/rejoin authentications. This cache size limits the number of overlapping joins the Trust Center can process within a narrow time window (e.g. two seconds), and thus should be set to the maximum number of near simultaneous joins the Trust Center is expected to accommodate. (Note: The total number of such address associations maintained by the NCP is the sum of the value of this setting and the value of ::EZSP_CONFIG_ADDRES S_TABLE_SIZE.) | |
SL_ZIGBEE_EZSP_CONFIG_SOURCE_ROUTE_TABLE_SIZE | 0 | entries | 4 | The size of the source route table. | |
SL_ZIGBEE_EZSP_CONFIG_FRAGMENT_WINDOW_SIZE | 0 | 8 | blocks | 0 | The number of blocks of a fragmented message that can be sent in a single window. |
SL_ZIGBEE_EZSP_CONFIG_FRAGMENT_DELAY_MS | 0 | milliseconds | 0 | The time the stack will wait between sending blocks of a fragmented message. | |
SL_ZIGBEE_EZSP_CONFIG_KEY_TABLE_SIZE | 0 | entries | 4 | The size of the Key Table used for storing individual link keys (if the device is a Trust Center) or Application Link Keys (if the device is a normal node). | |
SL_ZIGBEE_EZSP_CONFIG_APS_ACK_TIMEOUT | milliseconds | 0 | The APS ACK timeout value. The stack waits this amount of time between resends of APS retried messages. | ||
SL_ZIGBEE_EZSP_CONFIG_END_DEVICE_BIND_TIMEOUT | 1 | seconds | 0 | The time the coordinator will wait for a second end device bind request to arrive. | |
SL_ZIGBEE_EZSP_CONFIG_PAN_ID_CONFLICT_REPORT_THRESHOLD | 1 | 63 | reports per minute | 0 | The number of PAN id conflict reports that must be received by the network manager within one minute to trigger a PAN id change. |
SL_ZIGBEE_EZSP_CONFIG_REQUEST_KEY_TIMEOUT | 0 | 10 | minutes | 0 | The timeout value in minutes for how long the Trust Center or a normal node waits for the ZigBee Request Key to complete. On the Trust Center this controls whether or not the device buffers the request, waiting for a matching pair of ZigBee Request Key. If the value is non-zero, the Trust Center buffers and waits for that amount of time. If the value is zero, the Trust Center does not buffer the request and immediately responds to the request. Zero is the most compliant behavior. |
SL_ZIGBEE_EZSP_CONFIG_CERTIFICATE_TABLE_SIZE | 0 | 1 | 0 | This value indicates the size of the runtime modifiable certificate table. Normally certificates are stored in MFG tokens but this table can be used to field upgrade devices with new Smart Energy certificates. This value cannot be set, it can only be queried. | |
SL_ZIGBEE_EZSP_CONFIG_APPLICATION_ZDO_FLAGS | 0 | 255 | 0 | This is a bitmask that controls which incoming ZDO request messages are passed to the application. The bits are defined in the EmberZdoConfigurationFlag s enumeration. To see if the application is required to send a ZDO response in reply to an incoming message, the application must check the APS options bitfield within the incomingMessageHandler callback to see if the EMBER_APS_OPTION_ZD O_RESPONSE_REQUIRED flag is set. | |
SL_ZIGBEE_EZSP_CONFIG_BROADCAST_TABLE_SIZE | 15 | 254 | entries | 6 | The maximum number of broadcasts during a single broadcast timeout period. |
SL_ZIGBEE_EZSP_CONFIG_MAC_FILTER_TABLE_SIZE | 0 | 254 | entries | 2 | The size of the MAC filter list table. |
SL_ZIGBEE_EZSP_CONFIG_SUPPORTED_NETWORKS | 1 | 2 | entries | 72 | The number of supported networks. |
SL_ZIGBEE_EZSP_CONFIG_SEND_MULTICASTS_TO_SLEEPY_ADDRESS | 0 | 1 | 0 | Whether multicasts are sent to the RxOnWhenIdle=true address (0xFFFD) or the sleepy broadcast address (0xFFFF). The RxOnWhenIdle=true address is the ZigBee compliant destination for multicasts. 0=false, 1=true | |
SL_ZIGBEE_EZSP_CONFIG_ZLL_GROUP_ADDRESSES | 0 | 255 | 0 | ZLL group address initial configuration. | |
SL_ZIGBEE_EZSP_CONFIG_ZLL_RSSI_THRESHOLD | -128 | 127 | 0 | ZLL RSSI threshold initial configuration. | |
SL_ZIGBEE_EZSP_CONFIG_RF4CE_PAIRING_TABLE_SIZE | 0 | 126 | entries | 48 | The maximum number of pairings supported by the stack. Controllers must support at least one pairing table entry while targets must support at least five. |
SL_ZIGBEE_EZSP_CONFIG_RF4CE_PENDING_OUTGOING_PACKET_TABLE_SIZE | 0 | 16 | entries | 16 | The maximum number of outgoing RF4CE packets supported by the stack. |
SL_ZIGBEE_EZSP_CONFIG_MTORR_FLOW_CONTROL | 0 | 1 | 0 | Toggles the MTORR flow control in the stack. 0=false, 1=true | |
(Deprecated)SL_ZIGBEE_EZSP_CONFIG_TRANSIENT_KEY_TIMEOUT_S | 0 | 65535 | seconds | 0 | The amount of time a trust center will store a transient key with which a device can use to join the network. |
Policy Settings#
There are some situations when the NCP must decide but there is not enough time to consult with the host. The host can control what decision is made by setting the policy in advance. The NCP will then make decisions according to the current policy. The host is informed via callbacks each time a decision is made, but by the time the news reaches the host, it is too late to change that decision. You can change the policies at any time by using the setPolicy command.
A policy is used for trust center behavior, external binding modification requests, unicast replies, generating pollHandler callbacks, and the contents of the messageSent callback.
Unicast Replies#
The policy for unicast replies allows the host to decide whether it wants to supply the NCP with a reply payload for every retried unicast received. If the host sets the policy to not supply a reply, the NCP will automatically send an empty reply (containing no payload) for every retried unicast received. If the host sets the policy to supply the reply, then the NCP will only send a reply when instructed by the host.
If the reply does not reach the sender before the APS retry timeout expires, the sender will transmit the unicast again. The host must process the incoming message and supply the reply quickly enough to avoid retransmission by the sender. Provided this timing constraint is met, multiple unicasts can be received before the first reply is supplied and the replies can be supplied in any order.
SPI Interface Callbacks#
Asynchronous callbacks from the NCP are sent to the host as the response to a callback command. The NCP uses the interrupt line to indicate that the host should send a callback command. The NCP will queue multiple callbacks while it waits for the host. Each response only delivers one callback. If the NCP receives the callback command when there are no pending callbacks, it will reply with the noCallbacks response.
UART Interface Callbacks#
By default, callbacks from the NCP are sent to the host asynchronously as soon as they occur, and the host never needs to send the callback command. The host can disable asynchronous callbacks by setting SL_ZIGBEE_EZSP_VALUE_UART_SYNCH_CALLBACKS to 1 using the setValue command. Callbacks will then only be sent to the host as the response to a callback command.
SPI Interface Power Management#
The NCP always idles its processor whenever possible. To further reduce power consumption when connected using the SPI interface, the NCP can be put to sleep by the host. The UART interface is designed for gateway applications and does not support power management. In power down mode, only an external interrupt will wake the NCP. In deep sleep mode, the NCP will use its internal timer to wake up for scheduled events. The NCP provides two independent timers that the host can use for any purpose, including waking up the NCP from deep sleep mode. Timers are set using the setTimer command and generate timerHandler callbacks.
The frame control byte of every command tells the NCP which sleep mode to enter after it has responded to the command. Including this information in every command (instead of having a separate power management command) allows the NCP to be put to sleep faster. If the host needs to put the NCP to sleep without also performing another action, the nopcommand can be used.
In deep sleep mode, the NCP will wake up for an internal event. If the event does not produce a callback for the host, the NCP will go back to sleep once the event has been handled. If the event does produce a callback, the NCP will signal the host and remain awake waiting for the callback command. If the frame control byte of the callback command specifies deep sleep mode, then the NCP would normally go back to sleep after responding with the callback. However, if there is a second callback pending, the NCP will remain awake waiting for another callback command.
To avoid disrupting the operation of the network, only put the NCP to sleep when it is not joined to a network or when it is joined as a sleeping end device. If the NCP is joined as a sleeping end device, then it must poll its parent in order to receive messages. The host controls the polling behavior using the pollForData command. Polls are sent periodically with the interval set by the host or a single poll can be sent. The result of every poll attempt is optionally reported using the pollCompleteHandler callback.
Tokens#
Some of the non-volatile storage on the NCP is made available for use by the host. Tokens stored in the NCP’s non-volatile memory can be read and written using the setToken and getToken commands. Tokens preserve their values between reboots. The manufacturing tokens stored in the User Data and Lock Bits regions of the NCP can be read using the getMfgToken command.
NCP Status#
The frame control byte of every response sent by the NCP contains four status fields:
The overflow bit is set if the NCP ran out of memory at any time since the previous response was sent. If this bit is set, then messages may have been lost.
The truncated bit is set if the NCP truncated the current response. If this bit is set, the command from the host produced a response larger than the maximum EZSP frame length.
The callback pending bit is set if the NCP has one or more callbacks that have not been delivered to the host.
The callback type field identifies a response as either an asynchronous callback (UART interface only), a synchronous callback, or not a callback.
You can use the nop command to check the status of the NCP without also performing another action.
Random Number Generator#
The host can obtain a random number from the NCP using the getRandomNumber command. The random number is generated from analog noise in the radio and can be used to seed a random number generator on the host.