Module:xbee
From Digi Developer
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, 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 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]!" |
| 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
