XBee radios have multiple I/O lines that can be used to gather Digital or Analog data, then transmit that data to another XBee for interpretation. Because sample data is always provided in an API format, it can be intimidating trying to understand the received sample frame even with an understanding of other XBee API frames. This article should assist in both understanding how to generate the sample data and properly interpret the results.
The ADC on XBee radios are 10-bit, which will provide a resolution from 0 to 1023 (0x03FF). Each XBee has varying requirements for acceptable ADC voltage ranges. Please refer to the individual product manual or the chart below for the XBee you are using in your design. Regardless of which XBee you chose, you must not exceed 3.3V on any pin or you will damage the radio module.
Programmable XBees have their own unique requirements and are exempt from the entirety of this article. The secondary micro-controller on this XBee is connected to the ADC pins instead of the RF processor. Refer to the product manual for pinout and information if you are using this variant.*The Series 1 XBee (802.15.4 and DigiMesh 2.4), XBee-Pro 900, and XBee-Pro 868 have a VREF pin that must be connected in order to use ADC samples. Typically this is connected to VCC so that your ADC range is between 0 and 3.3V. Even if you are not using an XBee that requires a VREF, it is recommended to connect VREF to VCC in order to provide compatibility with other XBees.
All XBee radios have pull-up resistors on the I/O and other lines. The pull-up resistors are enabled on every pin by default, but can be disabled or enabled using the PR parameter. Some XBees have the option to use pull-down resistors instead, the PD parameter is used to determine the direction of the resistor, whether it is a pull-up or pull-down. Both the PR and PD commands are bitfield masks. Because each radio will have a different range of acceptable values for both PR and PD, please refer to the individual product manual for the layout of these bitfield masks.
WARNING: The PR parameter affects more than just the I/O lines. Even if you wish to disable all pull-up resistors on the radio, you must leave PR=0x80. This will leave the pull-up resistor enabled on the DIN pin. If you leave DIN floating, then the module will enter command mode upon startup and during every wake period when using cyclic sleep. This will greatly impact battery life and radio stability.
There are two ways to sample data: Automatic sampling or queried. With automatic sampling, the radio takes a sample either periodically (based on a sample rate) or when a change is detected on one or more digital pins. This will sample the XBee’s I/O lines and transmit that sample to another XBee that you specify with the Destination Address parameters. With queried sampling, one radio requests the sample data from another XBee using a Remote AT Command.
With the IR parameter set, the radio will periodically sample all of the I/O lines that are set as inputs and send the sample data to a destination XBee specified by DH and DL. There is a maximum sample rate that can be set, although the IR parameter will allow a value as low as 1ms per sample, going below what the radio’s processor is capable of will result in incorrect values and lost samples.
Example:Sample Rates work very well with cyclic sleep modes, since the radio will sample once per wake period and immediately go back to sleep. If more than one sample per wake period is required, then modifications to the SO (Sleep Options) and ST (Time before Sleep) parameter are needed.
I want to sample ADC1, DIO2, and DIO3 once every minute and send the sample to a specific radio. To conserve battery life, the radio should only sample once per wake period.
With this configuration, the radio will wake once every minute, sample D1 as an ADC, D2 and D3 as Digital Inputs, and send the single sample to the radio with the address 0013A200 12345678 before going back to sleep. The IR parameter does not exceed the radio’s wake period (this varies depending on the radio, but with the default settings it will only be a few milliseconds) so only one sample will be taken and sent over-the-air once per minute as defined by the sleep period instead of the sample rate interval.
The IC (Digital IO Change Detection) parameter is a bitfield mask and allows the radio to monitor specified Digital I/O lines. When a change is detected on these pins (edge triggered), the radio will sample all of the I/O lines that are set as inputs and send the sample data to a destination XBee specified by DH and DL.
Change Detect does not work well with sleep modes, and should be used with the radio in an always-on configuration. The reason behind this is that the edge transition on the monitored pins must occur while the radio is awake. For example, if DIO5 is used as the change detect, and the pin is HIGH during a wake period, but transitions to LOW while the radio is asleep, then the edge was not detected and no sample will be generated. Change detect has the same limitations as IR when it comes to sample frequency.
I want to monitor DIO3 and DIO5 for any change, and if a change is detected to transmit a sample of ADC1, ADC2, DIO3, DIO4, and DIO5 to a specific radio.
The radio will constantly monitor the status of DIO3 and DIO5, when a transition from HIGH to LOW or from LOW to HIGH is seen on these pins, the radio will sample all of the I/O lines that are set as inputs and transmit a single sample to the radio with the address 0013A200 12345678.
Note that you can combine both Sample Rate and Change Detect. This might be useful in scenarios where a longer interval is needed for periodic sampling, but you want the ability to take an instantaneous sample if a change is detected on a specific pin.
To request a sample remotely, we need to issue the IS command to a remote radio. In order to do this, the XBee that is requesting the sample must have API enabled since the request is sent as a "Remote AT Command". The radio that is actually sampling the I/O lines does not have to be in API mode.
A Remote AT Command (frame type 0x17) is sent into the local radio with the remote radio as the intended recipient. The command being sent is IS, to request a sample.
The remote radio receives the command and triggers a sample of the I/O lines that are set as inputs.
An AT Command Response frame (0x97) is generated and is sent over-the-air back to the local radio, this contains all of the sample data.
Example:This frame can be generated using the latest version of XCTU.
Open X-CTU with an API XBee connected. The remote XBee must have at least one input defined in order for a sample to be taken. For example D1=2, D2=2, D3=3 will give you two Analog and one digital values.
Open the terminal tab and open the serial connection.
Click on the + icon in the "Send Frames" section to add a new frame.
Type a name in the Frame Name field, then click Create frame using ‘Frames Generator’ tool.
In the Frame Type list, chose 0x17 – Remote AT Command.
For the 64-bit dest. Address, type in the address of the remote node.
For the AT command, type 49 53 in the Hex field. Alternatively, click the "ASCII" option and type IS.
Click OK to enter the API frame into the "Add API" window.
With your Remote AT Command frame selected, click Send selected frame.
You should now have two items in your Frames log, one for the outgoing Remote AT Command Request, and one for an incoming Remote Command Response.
In the next section, we'll cover how to interpret this response frame and decipher the sample data.
Samples taken automatically using either a Sample Rate (IR) or Change Detect (IC) will arrive as an API frame. The frame type is 0x92 (IO Data Sample Rx Indicator). Contained in this single frame are digital and analog masks indicating which I/O lines are configured as inputs, and our actual sample data. There is a lot of information, and it can be intimidating to parse out the useful information, so we’ll decrypt a sample frame here.
In the example frame above, the digital channel mask is 0x0018 = 00011000b. So DIO3 and DIO4 are set as a Digital Input on the sampling XBee. The Digital Samples field is 0x0010 = 00010000b. So DIO4 is HIGH, DIO3 is LOW.
In the example frame above, the analog channel mask is 0x03 = 0011b. So AD0 and AD1 are set as a ADCs on the sampling XBee. As a result, we know two 2-byte analog samples are included in the frame. AD0 is the first sample and is 0x022F, the second sample is AD2 and is 0x01FE.
When a sample is queried using an IS command from a Remote AT Command (0x17) frame, a response frame will be generated. This response is very similar to that of the automatic sample, but it is received as a Remote Command Response frame (0x97) instead.
**The Analog Channel Mask is a bitfield mask, and indicates which I/O lines are set as an ADC:In the example frame above, the digital channel mask is 0x1810 = 1100000010000b. So DIO4, DIO11, and DIO12 are set as a Digital Input on the sampling XBee. The Digital Samples field is 0x0800 = 100000000000b. So DI11 is HIGH, DIO4 and DIo12 are LOW.
In the example frame above, the analog channel mask is 0x0E = 1110b. So AD1, AD2, and AD3 are set as ADCs on the sampling XBee. As a result, we know three 2-byte analog samples are included in the frame. AD1 is the first sample and is 0x005A, the second sample is AD2 which is 0x01AE, and the third sample is AD3 which is 0x020C.
Digi has a variety of adapters that are designed for taking samples or have sensors built in for additional functionality. The API frame structure with adapters is the same as we have covered, but the formulas for converting the sampled analog value into a useful measurement are different. Because all of these adapters use ZigBee XBees, the VREF in the formulas is 1200 (1.2V).
Two additional parameters exist for this firmware, IT and IU. With IT enabled, the radio can take multiple samples per transmission. This can reduce RF traffic since fewer transmissions are happening. IU is required in order to output the sample data instead of using I/O Line Passing.
The frame structure for the received frames is slightly different when compared to DigiMesh and ZigBee. 802.15.4 modules operate with 16-bit addressing (with a user-defined MY parameter) or with the full 64-bit address (by setting MY=FFFF). As a result, the API frame types are different.
This frame type is used if the remote radio is using 16-bit addressing and is automatically generating a frame because either IR or IC is set.
If multiple samples are included (Sample Quantity > 1), then you will have multiple sets of sample data: the sample data consists of all fields between Channel Mask and Checksum.
The Digital Samples follows the same format as the Channel Mask. In the example frame above, the Digital Sample field is 0x0018 = 0x11000. So DIO3 and DIO4 = HIGH, DIO6 = LOW. The analog samples are ADC0 = 0x0046, ADC1 = 0x0154, and ADC2 = 0x020A.In the example frame above, the channel mask is 0xE58 = 111001011000b. So on the sampling XBee, DIO3, DIO4, and DIO6 are set as a Digital Input while ADC0, ADC1, and ADC2 are set as analog inputs.
This frame type is identical to the 16-bit I/O frame, except that instead of a 1-byte, 16-bit address field, this frame type uses a 2-byte, 64-bit address field. This frame will only be generated if the MY parameter is set to 0xFFFF on the sampling radio.
Queried samples (IS) can be sent to sleeping End Devices. This is because the End Device’s parent will buffer the IS command until the End Device’s next wake period. This is makes ZigBee an ideal choice for remote sampling applications.
The receiving XBee must be in API mode when using periodic sampling and change detect. If the receiving XBee is in AT mode, no output will be generated. The sampling XBee does not have to be in API mode.
The receiving XBee must be in API mode when using periodic sampling and change detect. If the receiving XBee is in transparent mode, no output will be generated. The sampling XBee does not have to be in API mode.