Add Devices to the ZigBee SE Network¶
The Google App sample may be used to send RPC requests to the gateway. (See Send and Receive Messages) Please read this section first if you do not have a means of sending RPC requests to the gateway. Additionally, the In-Premise Display/Meter Simulator sample may be used to simulate devices to add to your network. (See In-Premise Display/Meter Simulation Sample)
Smart Energy Security Overview¶
Smart Energy imposes security protocols above and beyond a normal ZigBee network. Devices join the encrypted Smart Energy network using a pre-shared link key or installation code (installation codes are hashed into link keys). In a Smart Energy network, each device can have its own link key or installation code. After a device joins the network it will initiate key establishment.
During key establishment the trust center will establish an APS key with the device. This key is used to encrypt critical data between the trust center and the joining device so that no other device can decrypt the data portion of the message. The trust center can also establish APS keys for any two authenticated devices so that they can securely communicate as well.
Key establishment utilizes certificates on both the trust center and joining device to authenticate that the device has been certified. Generally certificates are either production certificates or test certificates and all devices on a network must be of the same type. The X2e gateway is manufactured with a production certificate. See Smart Energy Certificate Management for instructions on obtaining and installing a test certificate.
The following generic steps need to be taken for a device to join:
- Install test or production certificate on joining device to match Smart Energy network. If joining device is already configured with an appropriate certificate this step may not be necessary.
- Register link key/installation code of joining device with the trust center.
- Enable joining on the Smart Energy network.
- Instruct joining device to join the Smart Energy network.
Add Device to Trust Center Gateway¶
In order to add a device to the Smart Energy network with the X2e gateway running as a trust center (ESI Coordinator), use the add_device RPC request. This will add a device with the given link key or installation code to the device table stored in the ESI. Joining will be enabled for the specified amount of time (set in these examples to 600 seconds). Fill in the device_address and link_key/installation_code parameters as appropriate to match the joining device.
Installation codes include a built in validity check (CRC16) and decrease the chance for incorrect entry when registering devices. Installation codes are preferred to the derived link key and should be provided by most device vendors. However, if an installation code is not available the link key can still be entered directly.
The add_device request has the following format:
<add_device>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
<join_time>600</join_time>
<installation_code type="base16">83FED3407A932B70</installation_code>
</add_device>
or
<add_device>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
<join_time>600</join_time>
<link_key type="base16">56777777777777777777777777777777</link_key>
</add_device>
Once the add_device RPC request has been sent, instruct the joining device to join the network. Once a device joins the network and has been detected, the gateway will generate a message with the following format:
<message>
<description type="string">ZDO_Device_Manager - Device 11:22:33:44:55:66:77:88 detected and marked as active</description>
<severity>0x1</severity>
</message>
Note
This may not be the first message you receive. Often, there are one or two other messages before the device is marked active.
Verify Device is on Gateway’s Network¶
To verify that a device is joined to the gateway’s network, use the identify RPC request. This request should make the device physically identify itself in some way. The X2e gateways will blink the association LED at a faster rate after receiving a ZCL Identify command.
This request has the following format:
<identify>
<destination_address type="MAC">11:22:33:44:55:66:77:88</destination_address>
<source_endpoint_id>0x5E</source_endpoint_id>
<destination_endpoint_id>0x5E</destination_endpoint_id>
<identify_time>30</identify_time>
</identify>
Fill in the destination_address and destination_endpoint_id as appropriate to match the joining device. The identify_time parameter specifies how long the device should identify itself in seconds.
Get List of Devices on Network¶
To get a list of devices on a gateway’s network, use the get_device_information RPC request. This request will retrieve all currently known information about all devices on the network from the gateway, including endpoints and clusters. The response will show which devices are active, i.e. which devices have joined the network and are currently communicating with the gateway.
This RPC request has the following format:
<get_device_information />
Here is an example of a response showing the local device configured as an ESI and another device which has not yet been detected as active. The contents of some descriptors have been omitted.
<get_device_information_response>
<record_list type="list">
<item type="ZDODeviceRecord">
<addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
<active type="bool">TRUE</active>
<node_type type="int">0x0</node_type>
<addr_short type="MAC">0000</addr_short>
<manufacturer_id type="int">0x101E</manufacturer_id>
<active_endpoints type="list">
<item type="int">0x5E</item>
</active_endpoints>
<power_descriptor type="Power_Desc_rsp">
...
</power_descriptor>
<node_descriptor type="Node_Desc_rsp">
...
</node_descriptor>
<simple_descriptors type="dict">
<endpoint_0x5E type="Simple_Desc_rsp">
...
<output_cluster_id_list type="list">
<item type="int">0x0</item>
<item type="int">0x3</item>
<item type="int">0x702</item>
<item type="int">0x800</item>
</output_cluster_id_list>
<input_cluster_id_list type="list">
<item type="int">0x0</item>
<item type="int">0x3</item>
<item type="int">0xA</item>
<item type="int">0x700</item>
<item type="int">0x701</item>
<item type="int">0x703</item>
<item type="int">0x800</item>
</input_cluster_id_list>
</endpoint_0x5E>
</simple_descriptors>
</item>
<item type="ZDODeviceRecord">
<addr_extended type="MAC">00:11:AA:BB:CC:DD:EE:FF</addr_extended>
<active type="bool">FALSE</active>
<node_type type="int">-0x1</node_type>
</item>
</record_list>
</get_device_information_response>
Note
The local device is always listed first. See ZDO Records for information on the above device information parameters.
Remove Device¶
To remove a device from the network, use the remove_device RPC request. This request will send a ZDO Mgmt_Leave_req to the device, remove the device from the list returned by get_device_information_response, and if the gateway is a trust center (ESI coordinator), unregister the link key / installation code for this device from the XBee.
This request has the following format:
<remove_device>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
</remove_device>