How to request a sample from a remote XBee 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.
- Click Add Frame.
- 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.
- 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.
Last updated:
Aug 23, 2018