Module:xbee

From Digi Developer

Jump to: navigation, search

Additional ZigBee functionality is provided by the zigbee module included on the Software and Documentation CD media included with your Python-enabled Digi product. Descriptions of supported methods and types follow.

Contents

Methods

ddo_get_param()

Purpose

get a Digi Device Objects parameter value.

Syntax
ddo_get_param(addr_extended, id[, timeout, order=False]) . string
Description

Get a DDO parameter id by using the 64-bit address given by addr_extended

Parameter addr_extended is a string formatted like "[00:13:a2:00:40:0a:07:8d]!". If addr_extended is None, the request is performed on the local radio.

Parameter id is a 2-byte string such as 'NI'. To make DDO parameter requests of remote radios, all radio module firmware versions must support this capability. For a description of valid id values, see the XBee™ Series 2 OEM RF Modules Product Manual (part number 90000866_B).

Optional parameter timeout is maximum time in seconds to wait for a response.

Optional parameter order is True to send this command in the same order relative to other commands and data transmissions. Concurrent commands to multiple nodes may be processed out of order. This option forces all previous commands to be sent to the local radio before this one, and all later commands to be sent after this one. Use of this option may significantly delay processing of commands.

Return

To properly interpret the binary string returned from this function, please see the API manual for the radio module. It may be useful to use the struct module to construct the type into a more useful data type.

An exception is thrown if the addressed node does not respond or is sleeping, or if the parameters are malformed. Therefore you must wrap any calls with a try:/except: statement.

This call may block for many seconds if the remote node is sleeping or offline - therefore avoid application designs which repeatedly query nodes which might be offline. For example do not blindly attempt to read ten DDO parameters from the same node in a row; if the first ddo_get_param() call timeouts, then so should the remaining nine. Instead, when the first DDO call fails, record the node as offline and return at a future time to try reading the ten DDO parameters again.

ddo_set_param()

Purpose

set a Digi Device Objects parameter value

Syntax
ddo_set_param(addr_extended, id[, value, timeout, order=False, apply=True]) . boolean 
Description

Set a DDO parameter id by using the 64-bit address given by addr_extended and the given value value.

Parameter addr_extended is a string formatted like "[00:13:a2:00:40:0a:07:8d]!". If addr_extended is None, the request is performed on the local radio.

Parameter id is a 2-byte string such as 'NI'. To make DDO parameter requests of remote radios, all radio module firmware versions must support this capability. For a description of valid values for id, see the XBee™ Series 2 OEM RF Modules Product Manual (part number 90000866_B).

Parameter value must be either a string or an integer. Do not submit any value when the parameter does NOT require a value - as for example as with the 'FR' command to reboot the Xbee device.

Optional parameter timeout is maximum time in seconds to wait for a response.

Optional parameter order is True to send this command in the same order relative to other commands and data transmissions. Concurrent commands to multiple nodes may be processed out of order. This option forces all previous commands to be sent to the local radio before this one, and all later commands to be sent after this one. Use of this option may significantly delay processing of commands.

Optional parameter apply is True to apply changes to node settings immediately. If apply is False, changes are queued in the node until a command with apply set to True or the AC command is sent to the node.

Note: if addr_extended is a broadcast address (such as "00:00:00:00:00:00:FF:FF!") which will have no response, then you must set timeout=0 or ddo_set_param() will throw an exception and fail.

Return

A boolean True or False is returned if the remote node accepts or rejects the SET command. Otherwise an exception is thrown if the addressed node does not respond or is sleeping, or if the parameters are malformed. Therefore you must wrap any calls with a try-except statement. See ddo_get_param() for more usage hints.

ddo_command()

Purpose

Execute a Digi Device Objects command

Syntax
ddo_command(addr_extended, id[, param, timeout, order=False, apply=True]) . string or None
Description

Execute a DDO command given by id by using the 64-bit address given by addr_extended and the optional parameter param.

Parameter addr_extended is a string formatted like "[00:13:a2:00:40:0a:07:8d]!". If addr_extended is None, the request is performed on the local radio.

Parameter id is a 2-byte string such as 'NI'. To send DDO commands to remote radios, all radio module firmware versions must support this capability. For a description of valid values for id, see the XBee™ Series 2 OEM RF Modules Product Manual (part number 90000866_B).

Parameter param must be either a string or an integer. Do not submit any value when the command does NOT require a value - as for example as with the 'FR' command to reboot the Xbee device.

Optional parameter timeout is maximum time in seconds to wait for a response.

Optional parameter order is True to send this command in the same order relative to other commands and data transmissions. Concurrent commands to multiple nodes may be processed out of order. This option forces all previous commands to be sent to the local radio before this one, and all later commands to be sent after this one. Use of this option may significantly delay processing of commands.

Optional parameter apply is True to apply changes to node settings immediately. If apply is False, changes are queued in the node until a command with apply set to True or the AC command is sent to the node.

Return

A string is returned if the command produces a result. To properly interpret the binary string returned from this function, please see the API manual for the radio module. It may be useful to use the struct module to construct the type into a more useful data type.

An exception is thrown if the addressed node does not respond or is sleeping, or if the parameters are malformed. Therefore you must wrap any calls with a try-except statement. See ddo_get_param() for more usage hints.

get_node_list()

Purpose

Perform a node discovery.

Syntax
get_node_list([refresh=True, clear=refresh, discover_digi=False, discover_zigbee=False]) . (node, node, …, node) 
Description

Perform a node discovery and return a tuple of nodes.

If the refresh parameter is set to True, this function will block and a fresh node discovery is performed. If no discovery methods are selected, a method appropriate for the network type will be used.

If refresh is set to False, this function returns a cached copy of the node discovery list. This cached version may include devices that were unable to be discovered within the discovery timeout imposed during a blocking call. If discovery methods are selected, newly discovered nodes will be added to the cached list.

If the clear parameter is set to True, this function will clear the cached list and perform a network discovery. If the clear parameter is set to False, this function will add newly discovered nodes to the existing cached list. If the clear parameter not specified, this function will clear the cached list if a network discovery is being performed.

If the discover_digi parameter is set to True this function will block and network discovery of Digi nodes will be performed. This obtains extended information supported by Digi nodes.

If the discover_zigbee parameter is set to True this function will block and network discovery of ZigBee nodes will be performed. This obtains information from standard ZigBee nodes.

register_joining_device()

Purpose

Register a new node into the local trust center key table.

Syntax
register_joining_device(addr_extended, key)
Description

This method is available on a gateway running a Smart Energy profile trust center.

Register a new node with the 64-bit address given by addr_extended, and set its initial trust center link key to key.

Parameter addr_extended is a string formatted like "[00:13:a2:00:40:0a:07:8d]!".

Parameter key is a binary string of up to 16 bytes. If key is less than 16 bytes, the upper bytes are padded with 0.

Return

An exception is thrown if a registration error occurs, or if the parameters are malformed. Therefore you must wrap any calls with a try-except statement.

unregister_joining_device()

Purpose

Unregister a node from the local trust center key table.

Syntax
unregister_joining_device(addr_extended)
Description

This method is available on a gateway running a Smart Energy profile trust center.

Remove the node with the 64-bit address given by addr_extended and its key from the local trust center key table.

Parameter addr_extended is a string formatted like "[00:13:a2:00:40:0a:07:8d]!".

Return

An exception is thrown if the given node is not registered, an error occurs, or if the parameter is malformed. Therefore you must wrap any calls with a try-except statement.

Classes

node

Name

node – a python object returned from a node discovery

Attributes
Name Type Description Example
type string node role/type in mesh is in ['coordinator', 'router', 'end']
addr_extended string 64-bit extended hardware address "[00:13:a2:00:40:0a:07:8d]!"
addr_short string 16-bit network assigned address "[49c3]!"
addr_parent string 16-bit network parent address "[fffe]!"
source_route tuple tuple of 16-bit network addresses in the source route from the node.
First element is a neighbor of the node. Last element is a neighbor of the gateway node.
Empty if the node is one hop away, or no source route has been received from the node.
Present in gateway firmware version 2.15 and later.
("[1234]!", "[5678]!")
profile_id int node profile ID 0xC105 or 49413
manufacturer_id int node manufacturer ID 0x101E or 4126
label string node’s string label (Setting 'NI') "TK103U"
device_type int node’s device type (Setting 'DD'). Upper 16 bits contain the module type. Lower 16 bits contain the product type. Will be 0 if the node does not support 'DD' 0x00030001
Methods

to_socket_addr()

Purpose

transform a node into a socket address tuple

Syntax
to_socket_addr([endpoint,] [profile_id,] [cluster_id,] [use_short]) . 
    (“address!”, endpoint, profile_id, cluster_id) 
Description

Transform this node into a socket address tuple, suitable for use with functions from the socket modules. If use_short is True, the short node address representation is used instead of the 64-bit extended address, which is used by default.

ZigBee Module Examples

Perform a Network Node Discovery

# 
# Perform a node discovery and print out# the list of discovered nodes to stdio. 
# 
 
# import the zigbee module into its own namespace:
import zigbee 
 
# Perform a node discovery:
node_list = zigbee.getnodelist() 
 
# Print the table: 
print "%12s %12s %8s %24s" % \
    ("Label", "Type", "Short", "Extended")
print "%12s %12s %8s %24s" % \
    ("-" * 12, "-" * 12, "-" * 8, "-" * 24) 
 
for node in node_list: 
    print "%12s %12s %8s %12s" % \
        (node.label, node.type, \
            node.addr_short, node.addr_extended)

Use DDO to Read Temperature from XBee Sensor

# 
# Collect a sample from a known XBee Sensor adapter
# and parse it into a temperature.
# 
 
 
# import zigbee and xbee_sensor modules:
import zigbee
import xbee_sensor 
 
 
# configure known destination:
DESTINATION="[00:13:a2:00:40:0a:07:8d]!" 
 
 
# Note: for clarity, the try: except: statements required to handle timeout is not shown
 
# ensure sensor is powered from adapter:
zigbee.ddo_set_param(DESTINATION, 'D2', 5)
zigbee.ddo_set_param(DESTINATION, 'AC', '') 
 
 
# get and parse sample:
sample = zigbee.ddo_get_param(DESTINATION, '1S')
xbee_temp = xbee_sensor.XBeeWatchportT()
xbee_temp.parse_sample(sample)
print "Temperature is: %f degrees Celsius" % (xbee_temp.temperature)

Create your own display-mesh command

This page includes a fully functional application using ddo_get_param() and getnodelist(): Create Your Own Custom Node List on a Digi ConnectPort X2/X4/X8 gateway

Personal tools
Wiki Editing