ZigBee Interface¶
The following are the RPC requests and responses added by the RPC_ZigBee_Interface class. These methods perform actions with the XBee radio that do not correspond to specific protocols beyond basic ZigBee.
add_device¶
Adds the device to the gateway’s list of known devices and to devices.ini. Additionally, if the XBee on the gateway is a coordinator and a link key or installation code is provided, the link key for the device will be added to the link key table of the XBee. This will allow the remote device to join the network if the network is not using a global link key. An optional join time can be specified which will temporarily enable node joining on the gateway.
Note
While node joining is enabled, the gateway will periodically send ZDO permit joining requests to the network. If other devices already on the network support this command, this will cause them to also enable joining. This in turn will allow the joining device to join the network even if it cannot directly communicate with the gateway.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| device_address | MAC | 64-bit extended address of the remote device to be added. |
| join_time* | int | Number of seconds for which node joining will be enabled on the gateway. If not provided, the existing node joining behavior will not be affected. |
| link_key* | int, base16 or base64 | The 128-bit link key of the remote device. |
| installation_code* | string, base16 or base64 | The installation code of the remote device. An installation code is functionally equivalent to a link key and will be converted to a link key by the gateway. If provided as a string, it is assumed that the installation code is in hexadecimal but may contain non-hex characters, which will be removed automatically. Installation codes must be 48, 64, 96 or 128 bits and additionally must include an appended 16-bit CRC. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| device_address | MAC | 64-bit extended address of the remote device to be added. |
| join_time | int | The number of seconds for which joining will be enabled on the gateway. |
Example
<add_device>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
<join_time>0x100</join_time>
<link_key type="base16">56777777777777777777777777777777</link_key>
</add_device>
<add_device_response>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
<join_time type="int">0x100</join_time>
</add_device_response>
remove_device¶
Removes a device from the gateway’s list of known devices and from devices.ini. Additionally, if the XBee on the gateway is a coordinator, the link key for that device will be removed from the link key table of the XBee. Optionally, once the device is removed, a ZDO leave request may be sent to the device asking it to leave the network.
Note
Additional request and response parameters added in version 1.4.0.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| device_address | MAC | 64-bit extended address of the remote device to be removed. |
| remove_from_network* | bool | As of 1.4.0: If TRUE, the target device will also be sent a ZDO leave network request. If FALSE, the target device will not be sent the request. If not specified, the request will be sent if the gateway is a coordinator, but not if the gateway is a router. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| device_address | MAC | 64-bit extended address of the remote device that was removed. |
Example
<remove_device>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
</remove_device>
<remove_device_response>
<device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
</remove_device_response>
enable_joining¶
Enables node joining on the gateway for the specified number of seconds, or requests the amount of time for which joining will be enabled. If set to 0, node joining is immediately disabled instead.
Note
While node joining is enabled, the gateway will periodically send ZDO permit joining requests to the network. If other devices already on the network support this command, this will cause them to also enable joining. This in turn will allow the joining device to join the network even if it cannot directly communicate with the gateway.
Note
As of 1.6.0 joining time is stored in flash and will be preserved across reboots.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| join_time* | int | If provided, the number of seconds for which node joining will be enabled on the gateway. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| join_time | int | Number of seconds for which node joining will be enabled on the gateway. |
Example
<enable_joining>
<join_time>0x100</join_time>
</enable_joining>
<enable_joining_response>
<join_time type="int">0x100</join_time>
</enable_joining_response>
get_zigbee_network_status¶
Returns various values relating to the status of the gateway on the ZigBee network. The meanings of the various fields vary depending on whether the gateway is functioning as a ZigBee coordinator or router.
Note
Additional response parameters added in version 1.4.0.
Request Parameters
None
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| status_description | string | A human-readable description of the network status. |
| status | int | 8-bit enumerated network status value. Corresponds to the Association Indication response as given by an XBee ATAI command. |
| channel | int | The ZigBee channel of the network that the gateway has formed or is joined to, if any. |
| pan_id | int | The 16-bit operating ID of the network that the gateway has formed is joined to, if any. |
| extended_pan_id | int | The 64-bit extended ID of the network that the gateway has formed or is joined to, if any. |
| configured_extended_pan_id | int | The 64-bit extended ID of the network that the gateway will form or join to. If 0, a random ID will be chosen when forming a network, or any ID will be chosen when joining a network. |
| addr_extended | MAC | The 64-bit extended address of the gateway’s XBee radio. |
| addr_short | MAC | The 16-bit network (short) address of the gateway’s XBee radio. |
| certificate_type* | int | As of 1.4.0: The type of Smart Energy certificate loaded on the device, if available. Possible values are: 0 = No certificate, 1 = Unknown, 2 = Production, 3 = Test. Not included if the XBee does not support Smart Energy certificates. Additionally, XBee versions prior to 3x28 do not support certificate type detection, in which case only values 0 and 1 can be returned. |
Example
<get_zigbee_network_status/>
<get_zigbee_network_status_response>
<status_description type="string">Success: Joined or formed Network</status_description>
<status type="int">0x0</status>
<channel type="int">0x10</channel>
<pan_id type="int">0x1234</pan_id>
<extended_pan_id type="int">0x12345678</extended_pan_id>
<configured_extended_pan_id type="int">0x0</configured_extended_pan_id>
<addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
<addr_short type="MAC">0000</addr_short>
<certificate_type type="int">0x2</certificate_type>
</get_zigbee_network_status_response>
configure_zigbee_network¶
Sets the parameters on the gateway related to joining or forming a network.
Note
Most parameters in this command will cause the gateway to reform or leave the current network it is joined to.
Note
Additional request parameters added in version 1.4.0.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| extended_pan_id* | int | If the gateway is a coordinator, this is the 64-bit extended ID of the network to form. If 0, a random ID will be chosen. If gateway is a router, this is the 64-bit extended ID of the network to join. If 0, the gateway will join any network that is allowing joining. |
| channel_mask* | int | 16-bit bitmask of the channels to allow when joining or forming a network. Bits 0 - 15 map to channels 11 - 26, respectively. |
| link_key* | int, base16 | If the gateway is a coordinator, this is the 128-bit global pre-shared link key that the network will use. If set to 0, a random link key will be chosen, effectively disabling the global pre-shared link key. If the gateway is a router, this is the 128-bit link key that will be used when joining a network. |
| installation_code* | int, base16, string | The installation code of the gateway. An installation code is functionally equivalent to a link key and will be converted to a link key by the gateway. If provided as a string, it is assumed that the installation code is in hexadecimal but may contain non-hex characters, which will be removed automatically. Installation codes must be 48, 64, 96 or 128 bits and additionally must include an appended 16-bit CRC. |
| join_interval* | int | If the gateway is a router, this is the interval between network join attempts while the gateway is not on a network, in seconds. This parameter is equivalent to the join interval registry setting (see “ZDO_Device_Manager.join_interval” in Registry Settings). |
| network_key* | int, base16 | As of 1.4.0: Sets the 128-bit ZigBee network key that the gateway will use. If the gateway is a coordinator, changing the network key will not reset the network; other devices on the network will have their network key automatically updated. It may not be possible to set this value if the gateway is a router. |
| enable_coordinator* | bool | As of 1.6.0: For X2e gateways, will configure the XBee radio as a coordinator if True or router if False. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| extended_pan_id | int | The 64-bit extended ID of the network that the gateway will form or join to. If 0, a random ID will be chosen when forming a network, or any ID will be chosen when joining a network. |
| channel_mask | int | 16-bit bitmask of the channels to allow when joining or forming a network. Bits 0 - 15 map to channels 11 - 26, respectively. |
| join_interval* | int | Only included if the gateway is a router. This is the interval between network join attempts while the gateway is not on a network, in seconds. |
| enable_coordinator | bool | As of 1.6.0: If True, the XBee radio is configured as a coordinator. If False, the radio is configured as a router. |
Example
<configure_zigbee_network>
<extended_pan_id>0x1234567890ABCDEF</extended_pan_id>
<channel_mask>0x1FC0</channel_mask>
<installation_code type="string">1234-5678-90AB-BA9E</installation_code>
<join_interval>90</join_interval>
</configure_zigbee_network>
<configure_zigbee_network_response>
<extended_pan_id type="int">0x1234567890ABCDEF</extended_pan_id>
<channel_mask type="int">0x1FC0</channel_mask>
<join_interval type="int">90</join_interval>
</configure_zigbee_network_response>
leave_network¶
Will cause a router gateway to leave its current network and a coordinator gateway to reform its network.
Request Parameters
None
Response Parameters
None
Example
<leave_network/>
<leave_network_response/>
refresh_device_information¶
Initiates a refresh of the gateway’s information about devices on the network. Normally this is equivalent to the periodic refresh performed automatically by the gateway (see Device Activity). However, the refresh operation can also be unicast to a specific device. Additionally, a full refresh may be performed, which will always peform all ZDO descriptor queries; a normal refresh will not perform these queries for devices which have already responded to them.
Note
Additional request and response parameters added in version 1.5.0.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| full_refresh* | bool | If TRUE, a full refresh will be performed, which will force all ZDO descriptor queries to be sent to devices even if they have already responded to them previously. Defaults to FALSE. |
| clear_inactive* | bool | As of 1.5.0: If TRUE and the gateway is a coordinator, any devices which do not respond to the refresh operation will have their detailed information such as clusters and attributes cleared, leaving only the MAC address and some basic information. If the gateway is a router, the device entry will be removed entirely. Defaults to FALSE. |
| device_address* | MAC | If provided, only information about the specified device will be refreshed. If not provided, information about the entire network will be refreshed. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| full_refresh | bool | If TRUE, a full refresh was performed. |
| purge_inactive | bool | If TRUE, devices which do not respond to the refresh will be purged. |
| device_address* | MAC | Only included if the original request specified a device, and indicates that only information about the specified device was refreshed. |
Example
<refresh_device_information>
<full_refresh>TRUE</full_refresh>
</refresh_device_information>
<refresh_device_information_response>
<full_refresh type="bool">TRUE</full_refresh>
</refresh_device_information_response>
get_device_information¶
Returns the gateway’s information about devices on the network.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| device_address* | MAC | The 64-bit extended address of the device whose information will be returned. If not provided, information for all devices will be returned. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| record_list | list | A list of records of type ZDODeviceRecord. Each record corresponds to a device on the network. If information for all devices is returned, the first record in the list will always correspond to the local device. |
Examples
Note that some of the contents of ZDODeviceRecord have been simplified in this example.
<get_device_information/>
<get_device_information_response>
<record_list type="list">
<item type="ZDODeviceRecord">
<active_endpoints type="list">
<item type="int">0x5E</item>
</active_endpoints>
<power_descriptor type="Power_Desc_rsp">
...
</power_descriptor>
<node_type type="int">0x0</node_type>
<addr_short type="MAC">0000</addr_short>
<addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
<node_descriptor type="Node_Desc_rsp">
...
</node_descriptor>
<active type="bool">TRUE</active>
<manufacturer_id type="int">0x101E</manufacturer_id>
<simple_descriptors type="dict">
<endpoint_0x5E type="Simple_Desc_rsp">
<status type="int">0x0</status>
<nwk_addr type="MAC">0000</nwk_addr>
<profile_id type="int">0x109</profile_id>
<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_id type="int">0x5E</endpoint_id>
<device_id type="int">0x500</device_id>
<device_version type="int">0x1</device_version>
</endpoint_0x5E>
</simple_descriptors>
</item>
<item type="ZDODeviceRecord">
<active type="bool">FALSE</active>
<addr_extended type="MAC">11:22:33:44:AA:BB:CC:DD</addr_extended>
<node_type type="int">-0x1</node_type>
</item>
</record_list>
</get_device_information_response>
get_join_status¶
Returns the gateway’s information on devices which have attempted to join, have joined, have authenticated with or have left the network since the gateway was last powered on, or since the information was last cleared.
Note
Added in version 1.4.0. No information will be available if the gateway’s XBee version is older than 3x28.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| device_address* | MAC | The 64-bit extended address of the device whose join status will be returned. If not provided, join status for all applicable devices will be returned. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| record_list | list | A list of records of type DeviceJoinStatusRecord. Each record corresponds to the join status of a particular device. |
Example
<get_join_status/>
<get_join_status_response>
<record_list type="list">
<item type="DeviceJoinStatusRecord">
<addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
<status type="int">0x1</status>
<timestamp type="int">0x12345678</timestamp>
</item>
<item type="DeviceJoinStatusRecord">
<addr_extended type="MAC">11:22:33:44:55:66:77:90</addr_extended>
<status type="int">0x3</status>
<timestamp type="int">0x12345000</timestamp>
</item>
</record_list>
</get_join_status_response>
clear_join_status¶
Clears the gateway’s current information on device joining.
Note
Added in version 1.4.0.
Request Parameters
None
Response Parameters
None
Example
<clear_join_status/>
<clear_join_status_response/>
xbee_AT¶
The XBee radio on the gateway provides a set of AT commands to control register values and perform certain actions. The xbee_AT request provides direct and unmanaged access to these commands. Because this command provides direct access to radio parameters, it is possible for it to interfere with gateway operations if used improperly. Accordingly it should only be used by advanced users who understand the AT command set. Refer to the XBee SE Manual.
Note
Additional request parameters added in version 1.4.0.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| command | string | Two-character XBee AT command code. |
| value* | int, base16, base64 or string | If included, this value will be used to set the corresponding register value or provide command parameters. If not included, the corresponding register value will be retrieved or command will be issued with no parameters. |
| apply* | bool | As of 1.4.0: If FALSE, the AT command will not be applied to the XBee until a later xbee_AT command with apply=TRUE, or the AT command ‘AC’, is sent. Defaults to TRUE. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| command | string | Two-character XBee AT command code. |
| value* | int | Not included if the original request did not include a value and the AT command code corresponded to a command with no parameters. Otherwise, this will be the value of the requested register value or the command parameters given in the original request. |
Example
<xbee_AT>
<command type="string">OI</command>
</xbee_AT>
<xbee_AT_response>
<command type="string">OI</command>
<value type="int">0x1234</value>
</xbee_AT_response>
bind¶
Performs a ZDO bind between a cluster on the gateway and a cluster on a remote device.
Note
Some clusters will automatically perform binding (see SE Client Clusters and Device Activity). This command is only needed if binding is required and either the automatic binding on these clusters fails or binding is needed for different clusters.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| destination_address | MAC | 64-bit extended address of the remote device to send the ZDO bind request to. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the remote device containing the cluster to bind. As of 1.5.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device containing the cluster to bind. As of 1.5.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| cluster_id | int | 16-bit identifier of the cluster to bind. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| status | int | Indicates the success or failure of the bind request using standard ZDO status values. Typical values are success (0x00) and not supported (0x84). |
| source_address | MAC | 64-bit extended address of the remote device that the ZDO bind request was sent to. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the remote device containing the cluster that was bound (if successful). |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device containing the cluster that was bound (if successful). |
| cluster_id | int | 16-bit identifier of the cluster that was bound (if successful). |
Example
<bind>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address >
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0700</cluster_id>
</bind>
<bind_response>
<status type="int">0x0</status>
<source_address type="MAC">00:11:22:33:44:55:66:77</destination_address >
<source_endpoint_id type="int">0x10</destination_endpoint_id>
<destination_endpoint_id type="int">0x5E</source_endpoint_id>
<cluster_id type="int">0x0700</cluster_id>
</bind_response>
unbind¶
Performs a ZDO unbind between a cluster on the gateway and a cluster on a remote device.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| destination_address | MAC | 64-bit extended address of the remote device to send the ZDO unbind request to. |
| destination_endpoint_id* | int | 8-bit identifier of the endpoint on the remote device containing the cluster to unbind. As of 1.5.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | 8-bit identifier of the endpoint on the local device containing the cluster to unbind. As of 1.5.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| cluster_id | int | 16-bit identifier of the cluster to unbind. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| status | int | Indicates the success or failure of the bind request using standard ZDO status values. Typical values are success (0x00) and not supported (0x84). |
| source_address | MAC | 64-bit extended address of the remote device that the ZDO unbind request was sent to. |
| source_endpoint_id | int | 8-bit identifier of the endpoint on the remote device containing the cluster that was unbound (if successful). |
| destination_endpoint_id | int | 8-bit identifier of the endpoint on the local device containing the cluster that was unbound (if successful). |
| cluster_id | int | 16-bit identifier of the cluster that was unbound (if successful). |
Example
<unbind>
<destination_address type="MAC">00:11:22:33:44:55:66:77</destination_address >
<destination_endpoint_id>0x10</destination_endpoint_id>
<source_endpoint_id>0x5E</source_endpoint_id>
<cluster_id>0x0700</cluster_id>
</unbind>
<unbind_response>
<status type="int">0x0</status>
<source_address type="MAC">00:11:22:33:44:55:66:77</destination_address >
<source_endpoint_id type="int">0x10</destination_endpoint_id>
<destination_endpoint_id type="int">0x5E</source_endpoint_id>
<cluster_id type="int">0x0700</cluster_id>
</unbind_response>
send_zigbee¶
Sends a raw ZigBee message to a given cluster on a device. Typically this is used for message pass-through behavior on clusters which do not support ZCL.
Note
Because there is no defined encoding for the message, there is no way to track transactions and thus no way to correlate a response message with the request. This is why the RPC response message is an echo of the request and not a response from the target device. Response messages for raw ZigBee are always treated as asynchronous messages (see received_zigbee*).
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| destination_address* | MAC | If provided, the 64-bit extended address of the remote device to send to. If not provided, the message will be sent to the local device. |
| destination_endpoint_id* | int | The 8-bit identifier of the endpoint on the target device to send to. As of 1.5.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| source_endpoint_id* | int | The 8-bit identifier of the endpoint on the local device to send from. As of 1.5.0: If not provided, the correct endpoint is guessed based on the gateway’s discovery information. |
| cluster_id | int | The 16-bit identifier of the cluster to send the message over. |
| payload | base16 or base64 | The payload of the message to send. |
| enable_APS_encryption* | bool | If TRUE, the message will be sent using APS encryption. If FALSE, the message will not use APS encryption. If not provided, the default setting of the cluster will be used. |
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| destination_address | MAC | The 64-bit extended address of the device that was sent to. |
| destination_endpoint_id | int | The 8-bit identifier of the endpoint on the target device that was sent to. |
| source_endpoint_id | int | The 8-bit identifier of the endpoint on the local device that was sent from. |
| profile_id | int | The 16-bit identifier of the profile of the sent message. |
| cluster_id | int | The 16-bit identifier of the cluster that the message was sent over. |
| payload | base16 or base64 | The payload of the message that was sent. |
| enable_APS_encryption | bool | If TRUE, the message was sent using APS encryption. If FALSE, the message did not use APS encryption. |
Example
<send_zigbee>
<destination_address type="MAC">11:22:33:44:AA:BB:CC:DD</destination_address>
<destination_endpoint_id>0x11</destination_endpoint_id>
<source_endpoint_id>0x30</source_endpoint_id>
<cluster_id>0xABCD</cluster_id>
<payload type="base16">12345678AABBCCDDEEFF</payload>
</send_zigbee>
<send_zigbee_response>
<destination_address type="MAC">11:22:33:44:AA:BB:CC:DD</destination_address>
<destination_endpoint_id type="int">0x11</destination_endpoint_id>
<source_endpoint_id type="int">0x30</source_endpoint_id>
<profile_id type="int">0xAAAA</profile_id>
<cluster_id type="int">0xABCD</cluster_id>
<payload type="base16">12345678AABBCCDDEEFF</payload>
<enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
</send_zigbee_response>
received_zigbee*¶
Response only. Generated when a ZigBee message is received on a cluster which does not support ZCL.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| source_address | MAC | The 64-bit extended address of the device that sent the message. |
| source_endpoint_id | int | The 8-bit identifier of the endpoint on the device that sent the message. |
| destination_endpoint_id | int | The 8-bit identifier of the endpoint on the local device that received the message. |
| profile_id | int | The 16-bit identifier of the profile of the received message. |
| cluster_id | int | The 16-bit identifier of the cluster that the message was received on. |
| payload | base16 or base64 | The payload of the message that was received. |
| enable_APS_encryption | bool | If TRUE, the received message used APS encryption. If FALSE, the message did not use APS encryption. |
Example
<received_zigbee>
<source_address type="MAC">11:22:33:44:AA:BB:CC:DD</source_address>
<source_endpoint_id type="int">0x11</source_endpoint_id>
<destination_endpoint_id type="int">0x30</destination_endpoint_id>
<profile_id type="int">0xAAAA</profile_id>
<cluster_id type="int">0xABCD</cluster_id>
<payload type="base16">FFEEDDBBCCAA</payload>
<enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
</received_zigbee>