API frame format
The firmware supports two API operating modes: without escaped characters and with escaped characters. Use the AP command to enable either mode. To configure a device to one of these modes, set the following AP parameter values:
- AP = 1: API operation.
- AP = 2: API operation (with escaped characters—only possible on UART).
The API data frame structure differs depending on what mode you choose.
API operation (AP parameter = 1)
The following table shows the data frame structure when you enable AP = 1:
| Frame fields | Byte | Description |
|---|---|---|
| Start delimiter | 1 | 0x7E |
| Length | 2 - 3 | Most Significant Byte, Least Significant Byte |
| Frame data | 4 - n | API-specific structure |
| Checksum | n + 1 | 1 byte |
The firmware silently discards any data it receives prior to the start delimiter. If the device does not receive the frame correctly or if the checksum fails, the device replies with a device status frame indicating the nature of the failure.
API operation-with escaped characters (AP parameter = 2)
| Frame fields | Byte | Description | |
|---|---|---|---|
| Start delimiter | 1 | 0x7E | |
| Length | 2 - 3 | Most Significant Byte, Least Significant Byte | Characters escaped if needed |
| Frame data | 4 - n | API-specific structure | |
| Checksum | n + 1 | 1 byte | |
Escape characters
When you are sending or receiving a UART data frame, specific data values must be escaped (flagged) so they do not interfere with the data frame sequencing. To escape an interfering data byte, insert 0x7D and follow it with the byte to be escaped XOR’d with 0x20.
Data bytes that need to be escaped:
| Byte | Description |
|---|---|
| 0x7E | Frame Delimiter |
| 0x7D | Escape |
| 0x11 | XON |
| 0x13 | XOFF |
Example: Raw serial data before escaping interfering bytes:
0x7E 0x00 0x02 0x23 0x11 0xCB
0x11 needs to be escaped which results in the following frame:
0x7E 0x00 0x02 0x23 0x7D 0x31 0xCB
Note In the previous example, the length of the raw data (excluding the checksum) is 0x0002 and the checksum of the non-escaped data (excluding frame delimiter and length) is calculated as:
0xFF - (0x23 + 0x11) = (0xFF - 0x34) = 0xCB.
Length
The length field specifies the total number of bytes included in the frame's data field. Its two-byte value excludes the start delimiter, the length, and the checksum.
Frame data
This field contains the information that a device receives or transmits. The structure of frame data depends on the purpose of the API frame:
|
Start delimiter |
Length |
Frame data |
Checksum |
||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
API identifier |
Identifier-specific Data | ||||||||||
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | n | n+1 |
| 0x7E | MSB | LSB |
cmdID |
cmdData |
Single byte |
||||||
The cmdID frame (API-identifier) indicates which API messages contains the cmdData frame (Identifier-specific data). The device sends multi-byte values big endian format.
The XBee/XBee-PRO Zigbee RF Module supports the following API frames:
| API frame names | API ID |
|---|---|
| AT Command | 0x08 |
| AT Command - Queue Parameter Value | 0x09 |
| Zigbee Transmit Request | 0x10 |
| Explicit Addressing Zigbee Command Frame | 0x11 |
| Remote Command Request | 0x17 |
| Create Source Route | 0x21 |
| AT Command Response | 0x88 |
| Modem Status | 0x8A |
| Zigbee Transmit Status | 0x8B |
| Zigbee Receive Packet (AO=0) | 0x90 |
| Zigbee Explicit Rx Indicator (AO=1) | 0x91 |
| Zigbee I/O Data Sample Rx Indicator | 0x92 |
| XBee Sensor Read Indicator (AO=0) | 0x94 |
| Node Identification Indicator (AO=0) | 0x95 |
| Remote Command Response | 0x97 |
| Extended Modem Status | 0x98 |
| Over-the-Air Firmware Update Status | 0xA0 |
| Route Record Indicator | 0xA1 |
| Many-to-One Route Request Indicator | 0xA3 |
PDF
