This section describes commands that set and report on security keys.
( PH:0x02, SH:0x00 ) - Preconfigured Key Option Write Command
Overview
The Preconfigured Key Option Write command is sent by the Host to the Module and serves to dictate which key the application will use when attempting to join a network; either the Preconfigured Link Key or the key derived from Installation Code.
The application default is to join with the Preconfigured Link Key. This configuration is not stored in non-volatile memory and should therefore be set prior to initiating any Scan and Join activity (i.e., while in the Network Down state) and subsequent to a reset or power-cycle.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0 | Joining Key Option | 0x00 = Join using Preconfigured Link Key |
Effect on Receipt
The Module will apply the chosen key the next time it attempts to join a network. This command only has an effect while Module is in the Network Down state and therefore prior to initiating any scan and join activity.
Allowed Context
Network Down.
Sent By Host/Module
Host.
( PH:0x02, SH:0x01 ) - Preconfigured Key Option Request Command
Overview
The Preconfigured Key Option Request is sent by the Host to the Module to query the current application Preconfigured Key Option.
Payload
This command has no payload.
Effect on Receipt
The Module will respond with a Preconfigured Key Option Response.
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x02 ) - Preconfigured Key Option Response Command
Overview
The Preconfigured Key Option Response is sent by the Module to the Host when queried with a Preconfigured Key Option Request. The command has the same payload as the Preconfigured Key Option Write command.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0 | Joining Key Option | 0x00 = Join using Preconfigured Link Key |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x03 ) - Install Code Request Command
Overview
The Install Code Request frame is sent by the Host to the Module to query the application Installation Code. It should be noted that the Installation Code is assigned to the Module at production time and cannot be modified.
Payload
This command has no payload.
Effect on Receipt
The Module responds with an Install Code Response
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x04 ) - Install Code Response Command
Overview
The Install Code Response frame is sent by the Module to the Host when queried with an Install Code Request.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0 | Installation Code Length | 8, 10, 14, or 18 as defined by the Zigbee Smart Energy Specification |
1..n | Installation Code | MSB First |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x05 ) - Link Key Write Command
Overview
The Link Key Write command is sent by the Host to the Module in order to set the application Preconfigured Link Key. The Host may only set the Preconfigured Link Key while the application is in the Network Down state.
If the Host subsequently forms a network as a coordinator, the key will be applied as the Global Trust Center Link Key. Otherwise, if the Host joins a network as either a router or end device, the key will be applied as the Joining Key.
The Preconfigured Link Key is not stored in non-volatile memory and must therefore be set prior to forming or joining a network subsequent to a Reset or power-cycle. If the Host does not manually set the key, the application will use the default Preconfigured Link Key specified by the Zigbee Home Automation Specification.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0..15 | Preconfigured Link Key | Default = {0x5A, 0x69, 0x67, 0x42, 0x65, 0x65, 0x41, 0x6C, 0x6C, 0x69, 0x61, 0x6E, 0x63, 0x65, 0x30, 0x39} = “ZigbeeAlliance09” |
Effect on Receipt
The Module will apply this Preconfigured Link Key when it either forms or joins a network, the latter when the Joining Key Option corresponds to Preconfigured Link Key.
Allowed Context
Network Down.
Sent By Host/Module
Host.
( PH:0x02, SH:0x06 ) - Link Key Request Command
Overview
The Link Key Request is sent by the Host to the Module to request the current application Link Key. The Module responds with a Link Key Response. When the Module is configured as a coordinator, it will return the Global Trust Center Link Key. When the Module is otherwise configured and not joined to a network, it will return the Preconfigured Link Key and likewise, when joined to a network, it returns the current Trust Center Link Key assigned to it.
Payload
This command has no payload.
Effect on Receipt
The Module will apply this Preconfigured Link Key when it either forms or joins a network, the latter when the Joining Key Option corresponds to Preconfigured Link Key.
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x07 ) - Link Key Response Command
Overview
The Link Key Response is sent by the Module to the Host when queried with a Link Key Request. The command has the same payload as the Link Key Write command.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0..15 | Preconfigured Link Key | Default = {0x5A, 0x69, 0x67, 0x42, 0x65, 0x65, 0x41, 0x6C, 0x6C, 0x69, 0x61, 0x6E, 0x63, 0x65, 0x30, 0x39} = “ZigbeeAlliance09” |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x08 ) - Network Key Write Command
Overview
The Network Key Write command is sent by the Host to the Module in order to set the application Preconfigured Network Key. The Host may only set the Network Key while the application is in the Network Down state, after which the key will be automatically randomized.
The Network Key is only applied if the Host subsequently forms a network as a coordinator. If serving as a router or end device, the application will receive a Network Key from the network Trust Center.
The Network Key is not stored in non-volatile memory and must therefore be set prior to forming a network subsequent to a Reset or power-cycle. If the Host does not manually set the key, the application will generate a random value for it upon forming a network.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0..15 | Network Key |
Effect on Receipt
Preconfigured Network Key is set, but is only applied if the Host subsequently forms a network as a coordinator.
Allowed Context
Network Down.
Sent By Host/Module
Host.
( PH:0x02, SH:0x09 ) - Network Key Request Command
Overview
The Network Key Request command is sent by the Host to the Module to query the application Network Key. The Module will respond with a Network Key Response. If the application has not formed a network, the response will convey the Preconfigured Network Key. Otherwise, the response will convey the current Network Key.
Payload
This command has no payload.
Effect on Receipt
The Module will respond with a Network Key Response
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x0A ) - Network Key Response Command
Overview
The Network Key Response command is sent by the Module to the Host when queried with a Network Key Request. The command has the same payload as Network Key Write command.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0..15 | Network Key |
Effect on Receipt
None.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x02, SH:0x20 ) - Trust Center Install Code Add
Overview
The Trust Center Install Code Add command is sent by the Host to the Module to commission a new device to the network with that install code. This is used in the scenario when Module is configured as a coordinator (trust center) and trying to commission other devices onto the network. Module will use a link key derived from the install code to authenticate the joining device.
Host must add the install codes before opening the permit join window for devices to join.
The install codes are cleared when Module leaves the network, or loses power, or receives the command Clear Trust Center Install Codes.
The maximum number of device install codes that can be added is indicated by Trust Center Install Code Max Count Response.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0..7 | EUI64 Address | EUI64 of the device, which the install code belongs to, LSB First |
8 | Install Code Size | The size in bytes n of the Installation Code, including the two-byte CRC, where n can be any of |
9..8+n | Install Code | MSB First |
Effect on Receipt
Module shall send Status Response with the following list of possible status
Status Response | Enum | Description |
---|---|---|
Success | 0x00 | Install code successfully added |
Invalid Data | 0x02 | Install code is invalid (e.g. invalid length, invalid CRC) |
Storage Full | 0x04 | Exceeding max number of device install codes that can be added |
Allowed Context
Network Up.
Sent By Host/Module
Host.
( PH:0x02, SH:0x23 ) - Clear Trust Center Install Codes
Overview
The Clear Trust Center Install Codes command is sent by Host to Module to clear all device install codes stored on the Module.
Payload
The command has no payload.
Effect on Receipt
Module clears all install codes.
Allowed Context
All Contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x24 ) - Trust Center Install Code Max Count Request
Overview
The Trust Center Install Code Max Count Request command is sent by Host to Module to query the maximum number of install codes that can be stored in the trust center.
Payload
The command has no payload.
Effect on Receipt
Module shall send Trust Center Install Code Max Count Response.
Allowed Context
All Contexts.
Sent By Host/Module
Module.
( PH:0x02, SH:0x25 ) - Trust Center Install Code Max Count Response
Overview
The Trust Center Install Code Max Count Response command is sent by Module to Host in response to Trust Center Install Code Max Count Response.
The payload indicates the maximum number of device install codes that can be stored on the Module.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0 | Max Count | Max number of install codes that can be stored in the trust center |
Effect on Receipt
None.
Allowed Context
Same context as request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x26 ) - Trust Center Security Policy Write
Overview
The Trust Center Security Policy Write command is sent by the Host to the Module to write the Trust Center security policy. The security policies are not saved by Module in non-volatile memory, so it is recommended for the Host to write them during startup configuration after every power-up.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0 | Require Join By Install Code | Sets the value of the bdbJoinUsesInstallCodeKey parameter as per the Zigbee Base Device specification. 0x00 = False (Default) |
1 | Require Key Exchange | Sets the value of the bdbTrustCenterRequireKeyExchange parameter as per the Zigbee Base Device specification. 0x00 = False (Default) |
Effect on Receipt
Module shall send Status Response with the following list of possible status
Status Response | Enum | Description |
---|---|---|
Success | 0x00 | Security policies written successfully |
Invalid Data | 0x02 | data values are invalid |
Incorrect Length | 0x07 | Requires a payload of at least 2 bytes |
Allowed Context
All contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x27 ) - Trust Center Security Policy Request
Overview
The Trust Center Security Policy Request is sent by the Host to the Module to request for the current Trust Center security policy.
Payload
The command has no payload.
Effect on Receipt
Module shall respond with Trust Center Security Policy Response.
Allowed Context
All contexts.
Sent By Host/Module
Host.
( PH:0x02, SH:0x28 ) - Trust Center Security Policy Response
Overview
The Trust Center Security Policy Response frame is sent by the Module to the Host in response to Trust Center Security Policy Request.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0 | Require Join By Install Code | 0x00 = False |
1 | Require Key Exchange | 0x00 = False |
Effect on Receipt
None.
Allowed Context
Same context as the request.
Sent By Host/Module
Module.
( PH:0x02, SH:0x29 ) - Trust Center Key Exchange Status Update
Overview
The Trust Center Key Exchange Status Update is sent by the Module to the Host to report the status of key exchange for a device that just joined the network.
At the end of a successful key exchange, the device establishes a unique link key with the TC.
Payload
Byte Index | Field Name | Notes |
---|---|---|
0..1 | Device Node ID | |
2..9 | Device EUI64 | |
10 | Key Exchange Status | See Key Exchange Status Enumerations |
Key Exchange Status Enumerations
Enum | Name | Failure Status | TC / Requester |
---|---|---|---|
0x00 | EMBER KEY STATUS NONE | No | Requester |
0x01 | EMBER APP LINK KEY ESTABLISHED | No | Requester |
0x03 | EMBER TRUST CENTER LINK KEY ESTABLISHED | No | Requester |
0x04 | EMBER KEY ESTABLISHMENT TIMEOUT | Yes | Requester |
0x05 | EMBER KEY TABLE FULL | Yes | Requester |
0x06 | EMBER TC RESPONDED TO KEY REQUEST | No | TC |
0x07 | EMBER TC APP KEY SENT TO REQUESTER | No | TC |
0x08 | EMBER TC RESPONSE TO KEY REQUEST FAILED | Yes | TC |
0x09 | EMBER TC REQUEST KEY TYPE NOT SUPPORTED | Yes | TC |
0x0A | EMBER TC NO LINK KEY FOR REQUESTER | Yes | TC |
0x0B | EMBER TC REQUESTER EUI64 UNKNOWN | Yes | TC |
0x0C | EMBER TC RECEIVED FIRST APP KEY REQUEST | Yes | TC |
0x0D | EMBER TC TIMEOUT WAITING FOR SECOND APP KEY REQUEST | Yes | TC |
0x0E | EMBER TC NON MATCHING APP KEY REQUEST RECEIVED | Yes | TC |
0x0F | EMBER TC FAILED TO SEND APP KEYS | Yes | TC |
0x10 | EMBER TC FAILED TO STORE APP KEY REQUEST | Yes | TC |
0x11 | EMBER TC REJECTED APP KEY REQUEST | Yes | TC |
0x12 | EMBER TC FAILED TO GENERATE NEW KEY | Yes | TC |
0x13 | EMBER TC FAILED TO SEND TC KEY | Yes | TC |
0x1E | EMBER TRUST CENTER IS PRE R21 | No | Requester |
0x32 | EMBER TC REQUESTER VERIFY KEY TIMEOUT | Yes | TC |
0x33 | EMBER TC REQUESTER VERIFY KEY FAILURE | Yes | TC |
0x34 | EMBER TC REQUESTER VERIFY KEY SUCCESS | No | TC |
0x64 | EMBER VERIFY LINK KEY FAILURE | Yes | Requester |
0x65 | EMBER VERIFY LINK KEY SUCCESS | No | Requester |
Effect on Receipt
None.
Allowed Context
Network Up.
Sent By Host/Module
Module.