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.

General Information

ADC Voltages

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.

Pull-up and Pull-down Resistors

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.

Below are the pull-up and pull-down resistor values:

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.

How to Sample Data

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.

Automatic Sampling using a Sample Rate (IR)

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.

Maximum sample rates:

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.

Configuration Example:

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.

Configuration:

DH=0x0013A200
DL=0x12345678 (address of the collector node)
D1=0x02 (ADC)
D2=0x03 (Digital Input)
D3=0x03 (Digital Input)
IR=0x200 (512ms)
SM=0x04 (cyclic sleep)
SP=0x1770 (60 seconds)

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.

Automatic Sampling using Change Detect (IC)

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.

The bitfield mask for IC is a 2-byte value from 0x0 to 0xFFFF and is defined as follows:


Configuration:Example:
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.

DH=0x0013A200
DL=0x12345678 (address of the collector node)
D1=0x02 (ADC)
D2=0x02 (ADC)
D3=0x03 (Digital Input)
D4=0x03 (Digital Input)
D5=0x03 (Digital Input)
IC=0x40 (binary: 0010 1000)
SM=0x00 (always on)

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.

Remotely Queried Sample (IS)

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.

This is the format of the Remote AT Command frame that needs to be passed into the local radio:

Example:This frame can be generated using the latest version of XCTU.

How to request a sample from a remote XBee using the latest version of XCTU:

1. 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.
   
2. Open the terminal tab and open the serial connection.
   
3. Click on the + icon in the "Send Frames" section to add a new frame.
4. Type a name in the Frame Name field, then click Create frame using ‘Frames Generator’ tool.
5. In the Frame Type list, chose 0x17 – Remote AT Command.
6. For the 64-bit dest. Address, type in the address of the remote node.
7. For the AT command, type 49 53 in the Hex field. Alternatively, click the "ASCII" option and type IS.
8. Click OK to enter the API frame into the "Add API" window.
   
9. Click Add Frame.
   
10. With your Remote AT Command frame selected, click Send selected frame.
    
11. 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.
    
12. By clicking on the Response frame, you can see the frame details, which will contain our sample data:

Remote Command Response
7E 00 17 97 01 00 13 A2 00 40 33 1C F9 FF 0B 49 53 00 01 00 00 06 02 10 02 0D 5C
    - Start delimiter: 7E
    - Length: 00 17 (23)
    - Frame type: 97 (Remote Command Response)
    - Frame ID: 01 (1)
    - 64-bit source address: 00 13 A2 00 40 33 1C F9
    - 16-bit source address: FF 0B
    - AT Command: 49 53 (IS)
    - Status: 00 (Status OK)
    - Response: 01 00 00 06 02 10 02 0D (This is our sample data)
    - Checksum: 5C

In the next section, we'll cover how to interpret this response frame and decipher the sample data.

Understanding Received Sample Data

Received Automatic Sample

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.

Here is an example frame:
7E 00 16 92 00 13 A2 00 40 4C 0E BE 61 59 01 01 00 18 03 00 10 02 2F 01 FE 49

We’ll parse out the frame and identify each field and where the actual sample data is located:


*The Digital Channel Mask and Digital Samples fields are a bitfield mask, and indicates which I/O lines are set as a Digital Input:

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.

**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 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.

Queried Sample

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.

Example API frame:
7E 00 1B 97 01 00 13 A2 00 40 33 1C F9 79 05 49 53 00 01 18 10 0E 08 00 00 5A 01 AE 02 0C BB

We’ll parse out the frame and identify each field and where the actual sample data is located:


*The Digital Channel Mask and Digital Samples fields are a bitfield mask, and indicates which I/O lines are set as a Digital Input:


**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.
 

Converting Sample Data into Useful Measurements

For the analog samples, you will receive 2-byte values in hexadecimal format. All XBees have a 10-Bit ADC, so the acceptable range will be from 0x0000 to 0x03FF. In order to convert this value to a useful voltage level, we need to apply the following formula:

ADC/1023 (VREF) = Voltage

Example:
Using a ZigBee XBee, the ADC value we receive is 0x1AE. First we convert the hexadecimal value into decimal (0x1AE=430). ZigBee uses a 1.2V reference, so we can apply the formula as follows:
430/1023 (1.2V) = 504.4mV

Interpreting Data from Sensor Adapters

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).

LTH Sensor
Light: ADC1
Temperature: ADC2
Humidity: ADC3

Formulas:
Light: Lux = (ADC1 / 1023) * 1200
Temperature:  Temp_C = ( (ADC2/1023) * 1200) - 500 ) / 10
Humidity: ( ( (ADC3/1023) * 1200 ) * 108.2 / 33.2 ) / 5000 - 0.16) / 0.0062 )

Example:
If we receive a sample with the following values: ADC1 = 0x002D, ADC2 = 0x0269, and ADC3 = 0x01CE, the results would be:
Light = 52.7859 Lux
Temperature = 22.3754 Celsius
Humidity = 31.1673 RH


Wall Router
Light: ADC1
Temperature: ADC2

Formulas:
Light: Lux = (ADC1 / 1023) * 1200
Temperature:  Temp_C = ( (ADC2/1023) * 1200) - 500 ) / 10

Example:
If we receive a sample with the following values: ADC1 = 0x002E, and ADC2 = 0x02A1, the results would be:
Light = 53.9063 Lux
Temperature = 24.8672 Celsius


Smart Plug
Light: ADC1
Temperature: ADC2
Current: ADC3

Formulas:
Light: Lux = (ADC1 / 1023) * 1200
Temperature:  Temp_C = ( (ADC2/1023) * 1200) - 500 ) / 10
Current: ( ( ( (ADC3/1023) * 1200 ) * (156/47) - 520) / 180 *0.7071 )

Example: If we receive a sample with the following values: ADC1 = 0x0010, ADC2 = 0x02B9, and ADC3 = 0x01FE, the results would be:
Light = 18.79 Lux
Temperature = 31.6797 Celsius
Current = 5.74994 A


Analog Adapter (0 - 10V configuration)
Terminal 1: ADC0
Terminal 2: ADC1
Terminal 3: ADC2
Terminal 4: ADC3

Formula:
Voltage = ( (ADC * 1.2) / 1023 / (3.3 / 28.2) )

Example: If we receive a sample with the following values: ADC0 = 0x0096, ADC1 = 0x011, ADC2 = 0x000B, and ADC3 = 0x01F6, the results would be:
Terminal 1: 1.5V
Terminal 2: 170mV
Terminal 3: 110mV
Terminal 4: 5.03V

Notes for Specific Radios

XBee 802.15.4

• Series 1 XBees that are running the 802.15.4 firmware support Digital and Analog Line Passing. This feature allows a radio to take an input from one XBee and directly alter the output of another XBee. Essentially acting as a wire replacement for digital and analog signals instead of just UART data. This is unique to the 802.15.4 firmware and is not possible on any other XBee without using an external micro-controller or a programmable variant. For more information, please refer to the following KB articles:

Digital I/O Line Passing: https://www.digi.com/support/knowledge-base/xbee-802-15-4-digital-input-output-line-passing
Analog Line Passing: https://www.digi.com/support/knowledge-base/analog-to-digital-conversion-on-the-xbee-802-15-4

• 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.

Here is the structure and example of the various API frames you will encounter:

0x83 – 16-bit I/O Sample
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 Channel Mask is a bitfield mask, and indicates which I/O lines are set as a Digital Input or ADC:

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.

0x83 – 64-bit I/O Sample
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.

ZigBee

• 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.

DigiMesh 2.4, 900HP, 868LP, and 865LP

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.