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 EZSP-UART Host Interface Guide and 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 some of the default values using the setConfigurationValue command. The host must then provide information about the application endpoints using the addEndpoint command.
Note: Some configuration parameters are read-only, and setting them won't have any effect. Refer to the Mutable column in the following table to identify writable parameters: Yes indicates writable, and No indicates read-only.
Configuration Values#
| Configuration ID | ID Value | Default | Min | Max | Mutable | Description |
|---|---|---|---|---|---|---|
| SL_ZIGBEE_EZSP_CONFIG_PACKET_BUFFER_HEAP_SIZE | 0x01 | 4096 | None | None | No | The NCP no longer supports configuration of packet buffer heap at runtime using this parameter. Packet buffer heap space must be configured using the SL_ZIGBEE_PACKET_BUFFER_HEAP_SIZE macro when building the NCP project. |
| SL_ZIGBEE_EZSP_CONFIG_NEIGHBOR_TABLE_SIZE | 0x02 | 16 | 1 | 26 | Yes | The maximum number of router neighbors the stack can keep track of. A neighbor is a node within radio range. Supported values are 1, 16 and 26. Setting this value lower than 8 is not recommended. |
| SL_ZIGBEE_EZSP_CONFIG_APS_UNICAST_MESSAGE_COUNT | 0x03 | 10 | None | None | Yes | The maximum number of APS retried messages the stack can be transmitting at any time. |
| SL_ZIGBEE_EZSP_CONFIG_BINDING_TABLE_SIZE | 0x04 | 2 | None | None | Yes | The maximum number of nonvolatile bindings that the stack supports. |
| SL_ZIGBEE_EZSP_CONFIG_ADDRESS_TABLE_SIZE | 0x05 | 12 | None | None | Yes | 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 ::SL_ZIGBEE_EZSP_CONFIG_TRUST_CENTER_ADDRESS_CACHE_SIZE). |
| SL_ZIGBEE_EZSP_CONFIG_MULTICAST_TABLE_SIZE | 0x06 | 8 | None | None | Yes | The maximum number of multicast groups that the device may be a member of. |
| SL_ZIGBEE_EZSP_CONFIG_ROUTE_TABLE_SIZE | 0x07 | 0 | 0 | 254 | Yes | 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 | 0x08 | 8 | 4 | None | Yes | The number of simultaneous route discoveries that a node will support. |
| SL_ZIGBEE_EZSP_CONFIG_STACK_PROFILE | 0x0C | 2 | 0 | 2 | Yes | Specifies the stack profile. Profile 0 is proprietary/non-standard, Profile 1 is basic Zigbee using tree addressing for small networks, and Profile 2 (Zigbee PRO) is the full-featured standard stack recommended for production use. |
| SL_ZIGBEE_EZSP_CONFIG_SECURITY_LEVEL | 0x0D | 5 | 0 | 5 | Yes | 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 | 0x10 | 30 | None | None | Yes | The maximum number of hops for a message. |
| SL_ZIGBEE_EZSP_CONFIG_MAX_END_DEVICE_CHILDREN | 0x11 | 6 | None | 64 | Yes | The maximum number of end device children that a router will support. |
| SL_ZIGBEE_EZSP_CONFIG_INDIRECT_TRANSMISSION_TIMEOUT | 0x12 | 7680 | None | 30000 | Yes | The maximum amount of time (in milliseconds) that the MAC will hold a message for indirect transmission to a child. |
| SL_ZIGBEE_EZSP_CONFIG_END_DEVICE_POLL_TIMEOUT | 0x13 | 8 | 0 | 14 | Yes | 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. Value range 0-14. 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_TX_POWER_MODE | 0x17 | 0 | 0 | 3 | Yes | Enables boost power mode and/or the alternate transmitter output. See EmberConfigTxPowerMode. |
| SL_ZIGBEE_EZSP_CONFIG_DISABLE_RELAY | 0x18 | 0 | 0 | 1 | Yes | 0: Allow this node to relay messages. 1: Prevent this node from relaying messages. |
| SL_ZIGBEE_EZSP_CONFIG_TRUST_CENTER_ADDRESS_CACHE_SIZE | 0x19 | 2 | 0 | 4 | Yes | 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 (for example, 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 ::SL_ZIGBEE_EZSP_CONFIG_ADDRESS_TABLE_SIZE.) |
| SL_ZIGBEE_EZSP_CONFIG_SOURCE_ROUTE_TABLE_SIZE | 0x1A | 0 | None | None | Yes | The size of the source route table. |
| SL_ZIGBEE_EZSP_CONFIG_FRAGMENT_WINDOW_SIZE | 0x1C | 8 | None | None | Yes | The number of blocks of a fragmented message that can be sent in a single window. |
| SL_ZIGBEE_EZSP_CONFIG_FRAGMENT_DELAY_MS | 0x1D | 0 | 0 | 255 | Yes | The time the stack will wait (in milliseconds) between sending blocks of a fragmented message. |
| SL_ZIGBEE_EZSP_CONFIG_KEY_TABLE_SIZE | 0x1E | None | None | None | No | 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). Key table size must be configured on the NCP using the zigbee_security_link_keys component. This config is for reading only. |
| SL_ZIGBEE_EZSP_CONFIG_APS_ACK_TIMEOUT | 0x1F | 1600 | None | None | Yes | The APS ACK timeout value. The stack waits this amount of time between resends of APS retried messages. |
| SL_ZIGBEE_EZSP_CONFIG_BEACON_JITTER_DURATION | 0x20 | 3 | None | 3 | Yes | The duration of a beacon jitter, in the units used by the 15.4 scan parameter (((1 << duration) + 1) \* 15ms), when responding to a beacon request. Because the recommended scan duration of a joining device is 3 for 2.4 GHz devices, any value passed in to this function greater than 3 will be rejected. |
| SL_ZIGBEE_EZSP_CONFIG_PAN_ID_CONFLICT_REPORT_THRESHOLD | 0x22 | 2 | None | None | Yes | 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 | 0x24 | 0 | 0 | 10 | Yes | 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 nonzero, 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 | 0x29 | 0 | 0 | 1 | No | 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 | 0x2A | 0 | None | None | Yes | This is a bitmask that controls which incoming ZDO request messages are passed to the application. The bits are defined in the sl_zigbee_zdo_configuration_flags_t 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 SL_ZIGBEE_APS_OPTION_ZDO_RESPONSE_REQUIRED flag is set. |
| SL_ZIGBEE_EZSP_CONFIG_BROADCAST_TABLE_SIZE | 0x2B | 15 | 15 | 254 | Yes | The maximum number of broadcasts during a single broadcast timeout period. |
| SL_ZIGBEE_EZSP_CONFIG_MAC_FILTER_TABLE_SIZE | 0x2C | None | None | None | Yes | The size of the MAC filter list table. |
| SL_ZIGBEE_EZSP_CONFIG_SUPPORTED_NETWORKS | 0x2D | 2 | 1 | 2 | Yes | The number of supported networks. |
| SL_ZIGBEE_EZSP_CONFIG_SEND_MULTICASTS_TO_SLEEPY_ADDRESS | 0x2E | 0 | 0 | 1 | Yes | 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. If the value is 0, multicasts are sent to the RxOnWhenIdle address (0xFFFD). If the value is 1, multicasts are sent to the sleepy broadcast address (0xFFFF). |
| SL_ZIGBEE_EZSP_CONFIG_ZLL_GROUP_ADDRESSES | 0x2F | 0 | None | None | Yes | ZLL group address initial configuration. |
| SL_ZIGBEE_EZSP_CONFIG_ZLL_RSSI_THRESHOLD | 0x30 | -40 | None | None | Yes | The RSSI threshold applied to incoming scan requests. The stack will ignore scan requests with corrected RSSI values less than this threshold. |
| SL_ZIGBEE_EZSP_CONFIG_MTORR_FLOW_CONTROL | 0x33 | None | None | None | Yes | Toggles the MTORR flow control in the stack. |
| SL_ZIGBEE_EZSP_CONFIG_RETRY_QUEUE_SIZE | 0x34 | 16 | None | None | Yes | Setting the retry queue size. Applies to all queues. Default value in the sample applications is 16. |
| SL_ZIGBEE_EZSP_CONFIG_NEW_BROADCAST_ENTRY_THRESHOLD | 0x35 | None | None | None | Yes | Setting the new broadcast entry threshold. The number (BROADCAST_TABLE_SIZE - NEW_BROADCAST_ENTRY_THRESHOLD) of broadcast table entries are reserved for relaying the broadcast messages originated on other devices. The local device will fail to originate a broadcast message after this threshold is reached. Setting this value to BROADCAST_TABLE_SIZE and greater will effectively kill this limitation. |
| SL_ZIGBEE_EZSP_CONFIG_TRANSIENT_KEY_TIMEOUT_S | 0x36 | 300 | None | None | Yes | The length of time (in seconds), that a trust center will store a transient link key that a device can use to join its network. A transient key is added with a call to emberAddTransientLinkKey. After the transient key is added, it will be removed once this amount of time has passed. A joining device will not be able to use that key to join until it is added again on the trust center. |
| SL_ZIGBEE_EZSP_CONFIG_BROADCAST_MIN_ACKS_NEEDED | 0x37 | None | None | None | Yes | The number of passive acknowledgements to record from neighbors before we stop retransmitting broadcasts. |
| SL_ZIGBEE_EZSP_CONFIG_TC_REJOINS_USING_WELL_KNOWN_KEY_TIMEOUT_S | 0x38 | None | None | None | Yes | The length of time, in seconds, that a trust center will allow a Trust Center (insecure) rejoin for a device that is using the well-known link key. This timeout takes effect once rejoins using the well-known key has been allowed. This command updates the sli_zigbee_allow_tc_rejoins_using_well_known_key_timeout_sec value. |
| SL_ZIGBEE_EZSP_CONFIG_CTUNE_VALUE | 0x39 | None | 0x0000 | 0x01FF | Yes | Valid range of a CTUNE value is 0x0000-0x01FF. Higher order bits (0xFE00) of the 16-bit value are ignored. Note: setting this parameter invokes the internal manufacturer library function, mfglibInternalSetCtune on the NCP. If the manufacturing library component is not installed on the NCP, setting the config value will not take effect. |
| SL_ZIGBEE_EZSP_CONFIG_ASSUME_TC_CONCENTRATOR_TYPE | 0x40 | None | None | None | Yes | To configure non-trust center node to assume a concentrator type of the trust center it join to, until it receive many-to-one route request from the trust center. For the trust center node, concentrator type is configured from the concentrator plugin. The stack by default assumes trust center be a low RAM concentrator that make other devices send route record to the trust center even without receiving a many-to-one route request. The default concentrator type can be changed by setting appropriate sl_zigbee_assume_trust_center_concentrator_type_t config value. |
| SL_ZIGBEE_EZSP_CONFIG_GP_PROXY_TABLE_SIZE | 0x41 | 5 | None | None | No | This is green power proxy table size. This value is read only and cannot be set at runtime. |
| SL_ZIGBEE_EZSP_CONFIG_GP_SINK_TABLE_SIZE | 0x42 | 0 | None | None | No | This is green power sink table size. This value is read only and cannot be set at runtime. |
| SL_ZIGBEE_EZSP_CONFIG_END_DEVICE_CONFIGURATION | 0x43 | None | 0 | 1 | Yes | This is the configuration advertised by the end device to the parent when joining/rejoining, either SL_ZIGBEE_END_DEVICE_CONFIG_NONE or SL_ZIGBEE_END_DEVICE_CONFIG_PERSIST_DATA_ON_PARENT. |
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.