Asynchronous Message Reference

The following are asynchronous messages with defined status codes, corresponding to key events observed by the local device. See message* for more information on the “message” RPC response.

The message format is as follows:

<message>
    <status type="int">0x1234</status>
    <description type="string">Human-readable description</description>
    <severity type="int">0x1</severity>
    ...other parameters as appropriate...
</message>

The “status” parameter gives a specific 16-bit integer status code corresponding to what the message is about, i.e. status 0x0000 corresponds to “local device has finished initialization”. Depending on the status code, other parameters may be included, i.e. a MAC address might be included if the status is about another device on the network. Separating parameters in this fashion is done because it is inconvenient to parse the description string of the message for useful information.

Local Device Status

The following messages correspond to the status of the local device.

Status Codes

Code Name Severity Description
0x0000 Init Complete Warning (1) Device initialization, including importing of Python modules and instantiation of objects, has completed.
0x0001 Joined Network Warning (1) Device has detected that its XBee radio is joined to a ZigBee network.
       
As of 1.5.0: Added parameter discovery_status (see Discovery Status Codes below). If local device discovery is complete a call to get_device_information will return the fully discovered information for gateway. If incomplete wait for a message* with status Discovery Complete before calling get_device_information.”  
0x0002 Left Network Warning (1) Device has detected that its XBee radio has left a ZigBee network (previously was joined and now is not joined).
0x0003 Time Synchronized Warning (1) Device has synchronized its time with some time source.
0x0004 Modem Status Debug (0) As of 1.4.0: This message indicates a change in the ZigBee state; for example, when a device has joined or left a network. Will include modem_status parameter that gives the new XBee status. (See Modem Status Codes below and XBee SE Manual for more details on modem status messages).

Modem Status Codes (for Modem Status message)

ID Status
0x0 Hardware reset
0x1 Watchdog timer reset
0x2 Joined network (routers and end devices)
0x3 Disassociated
0x6 Coordinator started
0x7 Network security key was updated
0x10 Key establishment complete
0x80 Stack error

Examples

<message>
    <status type="int">0x0</status>
    <description type="string">Initialization complete, starting main loop</description>
    <severity type="int">0x1</severity>
</message>

<message>
    <status type="int">0x1</status>
    <description type="string">Local device detected that it is joined to a ZigBee network</description>
    <severity type="int">0x1</severity>
    <discovery_status type="int">0x0</discovery_status>
</message>

<message>
    <status type="int">0x2</status>
    <description type="string">Local device detected that it has left a ZigBee network</description>
    <severity type="int">0x1</severity>
</message>

<message>
    <status type="int">0x3</status>
    <description type="string">Synchronization with NTP time server successful</description>
    <severity type="int">0x1</severity>
</message>

Remote Device Status

The following messages correspond to the status of other devices on the network, as observed by the local device. See Device Activity for more details on how device activity is determined.

Status Codes

Code Name Severity Description
0x0100 Device Registered Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: Device address/link key pair has been registered with the XBee radio.

0x0101 Device Unregistered Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: Device address/link key pair has been unregistered from the XBee radio.

0x0102 Known Device Active Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: A device which was previously known by the local device has been detected on the network and appears to be active.

As of 1.5.0: Added parameter discovery_status (see Discovery Status Codes below). If discovery is complete, a call to get_device_information will return the fully discovered information for the device. If incomplete, wait for a message* with status Discovery Complete before calling get_device_information.

0x0103 Unknown Device Active Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: A device which was previously unknown by the local device has been detected on the network and appears to be active.

As of 1.5.0: Added parameter discovery_status (see Discovery Status Codes below). If discovery is complete, a call to get_device_information will return the fully discovered information for the device. If incomplete, wait for a message* with status Discovery Complete before calling get_device_information.

0x0104 Device Inactive Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: A device which previously appeared to be active now appears to be inactive or unresponsive.

0x0105 Known Device Announce Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: A ZDO Device Announce message has been received from a device previously known by the local device.

0x0106 Unknown Device Announce Warning (1)

Before 1.3.3: Message generated without status parameter.

As of 1.3.3: A ZDO Device Announce message has been received from a device previously unknown by the local device.

0x0107 Device Discovery Complete Warning (1) As of 1.5.0: Device automatic discovery is complete. Will include discovery_status parameter that gives the status of service discovery (in this case either complete(1) or complete with errors(2), see Discovery Status Codes below). The discovery process happens after a device joins the network, the gateway joins a network, the gateway restarts, or if the RPC command refresh_device_information is sent with the parameter ‘full_refresh’ set to True. A call to get_device_information will return the fully discovered information for the device.
0x0109 Join Notification Debug (0) As of 1.4.0: Remote device tries to join the network. This message is only generated when the gateway is a coordinator. Will include join_status parameter that gives the type of ZigBee join. (See Join Notification Status Codes below and XBee SE Manual for more details on join status messages).
0x010A Device Authenticated Debug (0) As of 1.4.0: Remote device successfully completes key establishment. This message is only generated when the gateway is a coordinator. (See XBee SE Manual for more details on device authenticated messages).

Additional Parameters

Parameter Type Description
addr_extended MAC 64-bit extended address of the remote device.
addr_short* MAC 16-bit network address of the remote device. Included only for ‘Known Device Announce’ and ‘Unknown Device Announce’ messages.
join_status* int As of 1.4.0: Enumerated status value for devices trying to join gateway (See Join Notification Status Codes below). Included only for ‘Join Notification’ messages.
discovery_status* int As of 1.5.0: Enumerated status value for automatic service discovery of devices on the network (See Discovery Status Codes below). Included only for ‘Joined Network’, ‘Known Device Active’, ‘Unknown Device Active’, and ‘Device Discovery Complete’ messages.

Join Notification Status Codes

ID Status
0x0 Standard security secured rejoin
0x1 Standard security unsecured join
0x2 Device left
0x3 Standard security unsecured rejoin
0x4 High security secured rejoin
0x5 High security unsecured join
0x7 High security unsecured rejoin

Discovery Status Codes

ID Status
0x0 Discovery Incomplete
0x1 Discovery Complete
0x2 Discovery Complete with Errors

Examples

<message>
    <status type="int">0x100</status>
    <description type="string">ZDO_Device_Manager - Device 11:22:33:44:55:66:77:88 registered with XBee</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
</message>

<message>
    <status type="int">0x101</status>
    <description type="string">ZDO_Device_Manager - Device 11:22:33:44:55:66:77:88 unregistered from XBee</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
</message>

<message>
    <status type="int">0x102</status>
    <description type="string">ZDO_Device_Manager - Device 11:22:33:44:55:66:77:88 detected and marked as active</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
    <discovery_status type="int">0x0</discovery_status>
</message>

<message>
    <status type="int">0x103</status>
    <description type="string">ZDO_Device_Manager - New Device 11:22:33:44:55:66:77:88 detected and marked as active</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
    <discovery_status type="int">0x0</discovery_status>
</message>

<message>
    <status type="int">0x104</status>
    <description type="string">ZDO_Device_Manager - Device 11:22:33:44:55:66:77:88 marked as inactive because of transmission failures</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
</message>

<message>
    <status type="int">0x105</status>
    <description type="string">ZDO_Device_Manager - Received device announce message from known device 11:22:33:44:55:66:77:88 (NWK: 1234)</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
    <addr_short type="MAC">1234</addr_short>
</message>

<message>
    <status type="int">0x106</status>
    <description type="string">ZDO_Device_Manager - Received device announce message from known device 11:22:33:44:55:66:77:88 (NWK: 1234)</description>
    <severity type="int">0x1</severity>
    <addr_extended type="MAC">11:22:33:44:55:66:77:88</addr_extended>
    <addr_short type="MAC">1234</addr_short>
</message>

ZigBee Conversation Status

The following messages correspond to

Status Codes

Code Name Severity Description
0x0200 Conversation General Error Warning (1)

Before 1.4.0: Message generated without status parameter.

As of 1.4.0: General error occurred when handling a response from remote device.

0x0201 Conversation TX Status Error Warning (1)

Before 1.4.0: Message generated without status parameter.

As of 1.4.0: Transmission error when sending to remote device. (See ZigBee Transmission Status Codes below and XBee SE Manual for more details on TX status messages).

0x0202 Conversation Timeout Error Warning (1)

Before 1.4.0: Message generated without status parameter.

As of 1.4.0: Timeout occurred when waiting for response from remote device. Timeout duration can be set using the registry setting Conversation.default_timeout. (See Registry Settings).

ZigBee Transmission Status Codes (for Conversation TX Status Error message)

ID Status
0x00 Success
0x02 CCA Failure
0x18 No Buffers
0x21 Network Ack Failure
0x22 Not Joined to Network
0x24 Address Not Found
0x25 Route Not Found
0x26 Relay of Broadcast Not Heard
0x2B Invalid Binding Table Index
0x2C Invalid Endpoint
0x32 Resource Error
0x74 Data Payload Too Large
0xBB Key Not Authorized

Examples

<message>
    <status type="int">0x200</status>
    <description type="string"></description>
    <severity type="int">0x1</severity>
</message>

<message>
    <status type="int">0x201</status>
    <description type="string"></description>
    <severity type="int">0x1</severity>
</message>

<message>
    <status type="int">0x202</status>
    <description type="string"></description>
    <severity type="int">0x1</severity>
</message>