XBee Analog I/O Adapter
From Digi Developer
|Product Name:||XBee Analog Adapter|
|Digi Product Page:|||
The XBee Analog Adapter is a product designed to take analog input readings and communicate them across the XBee network. For more details of usage and configuration, please review the Drop-in-Networking Accessories User's Guide at: http://www.digi.com/din/docs. This Analog Adapter is designed for ZB Firmware.
Major Features of the XBee Analog Adapter:
- 4 Analog input terminals supporting Ten Volt mode, Current Loop mode, and Differential mode.
- Easy to use screw terminal connector.
- Power output of 12 Volt 50mA in mains powered mode.
- Optional battery powered for isolated locations.
The XBee Analog Adapter is supported on all Digi's XBee protocols. All of Digi's gateway products that are using the same XBee protocol as the adapter are compatible.
Example: If you have a gateway product with a XBee ZB radio installed, a XBee ZB Analog Adapter is compatible, but not a XBee ZNet 2.5 Analog Adapter.
There are two distinct versions of the XBee Analog Adapter hardware, each supporting a different sub-set of the Digi XBee modules. They are NOT interchangeable and putting the incorrect XBee on the incorrect adapter will return bad data. One model supports ZB and ZNet XBee only, while the other supports 802.15.4, DigiMesh and the Digi Point-to-Multipoint XBee.
The XBee Analog adapter uses a unique function set for each of the protocols, requiring that configuration of the radio be done via the RF interface through remote AT commands.
Important: Serial communications functionality is disabled on XBee Analog and Digital I/O Adapters
For the XBee Analog and Digital I/O Adapters, the XBee firmware disables the XBee module’s serial communications functionality, so that the pins normally used for serial communications can instead be used for additional I/O functionality. As a result, once an XBee module has been loaded with the firmware image specific to the XBee Analog or Digital I/O Adapters, the XBee module can no longer be configured using X-CTU, the XBee serial API, or local AT commands.
The only way to configure these adapters is by using the Ident or Ident/Reset commissioning and identification button (described in the topic "Commissioning and identity behaviors" in the Drop-in Networking Accessories User's Guide) and OTA commands—either by using a ConnectPort gateway, X-CTU, or by using the remote command API of another serial-enabled module associated to the same network.
Mode and Terminal configuration
The Analog Adapter's terminals must be configured in pairs. The terminals have the option of not being the same mode as the other terminal in its pair, with the exception of Differential input mode. Terminals 1 and 2 are bound together, terminals 3 and 4 are bound together.
- To configure the mode for terminals 1 and 2
- D8=4, D4=4, D6=4, (Enables Terminals 1 and 2 for Current Loop mode)
- D8=4, D4=4, D6=5, (Enables Terminal 1 for Current Loop mode, Terminal 2 for Ten Volt mode)
- D8=4, D4=5, D6=4, (Enables Terminal 1 for Ten Volt mode, Terminal 2 for Current Loop mode)
- D8=4, D4=5, D6=5, (Enables Terminals 1 and 2 for Ten Volt mode)
- D8=5, D4=4, D6=4, (Enables Terminals 1 and 2 for Differential mode)
- All other combinations are invalid and may result in inconsistent behavior
- To configure the mode for terminals 3 and 4
- P0=4, D7=4, P2=4, (Enables Terminals 3 and 4 for Current Loop mode)
- P0=4, D7=4, P2=5, (Enables Terminal 3 for Current Loop mode, Terminal 5 for Ten Volt mode)
- P0=4, D7=5, P2=4, (Enables Terminal 3 for Ten Volt mode, Terminal 4 for Current Loop mode)
- P0=4, D7=5, P2=5, (Enables Terminals 3 and 4 for Ten Volt Mode)
- P0=5, D7=4, P2=4, (Enables Terminals 3 and 4 for Differential mode)
- All other combinations are invalid and may result in inconsistent behavior
- To enable terminals 1-4 for analog input
- D0=2 (Enables Terminal 1 for analog input)
- D1=2 (Enables Terminal 2 for analog input)
- D2=2 (Enables Terminal 3 for analog input)
- D3=2 (Enables Terminal 4 for analog input)
Sensor Readings Retrieval
Once the device has been configured, it is time to start polling sensor samples from the device. There are two methods of retrieving the sample, active polling and passive polling. Both methods of polling require the user to parse the 'IS' data structure for the sensor readings. More information on the 'IS' data structure here: IS Data structure
Active polling is when an application or user on the XBee network sends the Remote AT command 'IS', which causes the Analog sensor to take a sensor reading and return the results to the requester.
- Simple to setup
- User-Controlled timing of samples
- For reliable responses, requires a non-sleeping Analog Adapter.
Passive polling is when the Analog adapter periodically sends a sensor reading and send it to the configurable destination address. To setup a Analog adapter to send periodic sensor readings to an address, configure the 'IR' parameter to be the rate in milliseconds to send the reading, and the 'DH' and 'DL' addresses to match the 'SH' and 'SL' address of the XBee node desired. In cases where the adapter is also sleeping, the device sends sensor readings at least once every wake cycle. If you desire the device to send only one sensor reading per wake cycle (recommended), set the 'IR' parameter to 0xFFFF.
- Allows for sleeping Analog adapters to reliably get sensor readings to the destination address
- Consistent timing of samples
- More difficult to setup, requires working knowledge of sleep settings.
Terminal 6 is the power out pin. It can be set in either battery pack voltage out or +12VDC at 50mA out if mains powered. To set battery pack voltage output, set dip switch 1 to the on position. To enable +12VDC output, set dip switch 2 to the on position. Setting both to the on position defaults to +12VDC output but incurs extra battery drain as well.
Once the desired power output is selected, the 'P3' setting needs to be set to 5.
Note: In order for consistent output voltage, the XBee Adapter cannot sleep. Using the power out function of this adapter in conjunction with batteries will result in significant additional battery usage.
DIA Configuration and Programming Examples
The DIA is a python framework designed to gather information from multiple sources, provide programmatic control over the information collecting, and present the data either to a software platform such as the Device Cloud or directly to the user through a variety of methods.
The DIA supports the XBee Analog Adapter. For an example configuration file: XBee_Analog_I/O_DIA_Example
Python Programming Examples
The XBee Analog Adapter may also be controlled from a Digi gateway device using the embedded XBee python module's function calls ddo_get_param() and ddo_set_param(). If you wish to use the adapter in a passive polling situation, you must also use the sockets API to receive the sensor readings from the Analog adapter.
Below is a quick demonstration of how to send commands to configure terminals 1 and 2 to Ten Volt mode, enable them for analog input, and retrieve an analog sample.
from xbee import ddo_get_param, ddo_set_param addr = '[00:13:a2:00:40:48:59:95]!' ##Enabling Ten volt mode on terminals 1 and 2 ddo_set_param(addr, 'D8', 4) ddo_set_param(addr, 'D4', 5) ddo_set_param(addr, 'D6', 5) ##Enabling terminals 1 and 2 for analog input ddo_set_param(addr, 'D0', 2) ddo_set_param(addr, 'D1', 2) ##Applying changes and writing to flash ddo_set_param(addr, 'AC') ddo_set_param(addr, 'WR') ##Taking a sensor sample, printing the raw binary string to STDOUT sample = ddo_get_param(addr, 'IS') print 'sample(%d)' % len(sample), for by in sample: print '%02X' % ord(by), print
Here is an example using 4-20mA on input #1 and #2. Since we enable the 50mA 12vdc power output from terminal #6, you would wire your sensor's '+' wire to terminal 6, then your '-' wire to terminal 1. Terminal 6 'sources' your current loop, and terminal 1 'sinks' it.
from xbee import ddo_get_param, ddo_set_param addr = '[00:13:a2:00:40:48:59:95]!' ##Enabling Ten volt mode on terminals 1 and 2 ddo_set_param(addr, 'D8', 4) ddo_set_param(addr, 'D4', 4) ddo_set_param(addr, 'D6', 4) ##Enabling terminals 1 and 2 for analog input ddo_set_param(addr, 'D0', 2) ddo_set_param(addr, 'D1', 2) ##Enabling terminals 6 to output 50mA @ 12vdc ## make sure your enable DIP switch #2 to ON (#1 off) to ## use your external power supply to drive the 12vdc power-out. ddo_set_param(addr, 'P3', 5) ##Applying changes and writing to flash ddo_set_param(addr, 'AC') ddo_set_param(addr, 'WR') ##Taking a sensor sample, printing the raw binary string to STDOUT sample = ddo_get_param(addr, 'IS') print 'sample(%d)' % len(sample), for by in sample: print '%02X' % ord(by), print
Usage Tricks and Hints
Hard-Coding a Fixed PAN ID
Page Hardcoding_a_fixed_XBee_PAN_ID describes a simple way to semi-permanently force in a fixed PAN ID - this is especially useful for the XBee AIO and DIO adapters since XCTU cannot talk serially to them.
Reflashing the XBee
Because the AIO firmware disables the serial port on the XBee, reflashing can be challenging. Manually activate the XBee bootloader to speed the process: Bootloader_to_force_XBee_reflash
Associating with the Correct Gateway
A user with multiple gateways will find the initial setup of the XBee AIO Adapter challenging. With other products, XCTU can be used to preload a profile with the desired PAN ID. However, an XBee with the AIO firmware cannot communicate with XCTU because it has no available serial port. Therefore your only option is the use the commissioning 4-button press.
The problem is that you may have multiple gateways on any single channel, so when the XBee AIO Adapter moves to a new channel, it may NOT notice your desired gateway until it has cycled through the channel list many times. For example, if you have 10 active gateways within range, they may be on only 3 or 4 channels of the 14 available.
Some simple solutions:
- Use a commissioning gateway which has had the SC/Scan Channels setting changed from default - for example to 0x0C00, which is only channels 0x15 or 0x16 and NOT the defaults down near channel 0x0D. This increases the probability that your gateway is on a channel by itself. A low-cost ConnectPort X2 makes a nice commissioning gateway.
- Leave the commissioning gateway's PAN Id 0x0 so it uses a large random PAN ID.
- If you have an XBee with an external antenna:
- Remove the XBee's antenna to weaken its range, reducing the number of visible gateways.
- If the gateway has an external antenna, consider linking the XBee directly by wire to the gateway's RPSMA connector. This insures your commissioning gateway's signal is the strongest which the XBee AIO Adapter can see.
- Use the commissioning 4-button press to move the XBee AIO Adapter between channels until it shows up on your commissioning gateway's node list, then manually force in other settings, followed last by your desired PAN ID. Just remember that applying the new PAN ID will cause the XBee AIO Adapter to leave association with your commissioning gateway.