Operate in API mode
API frame format
Digi XBee® 3 802.15.4 RF Module User Guide
186
Any data received prior to the start delimiter is silently discarded. If the frame is not received correctly
or if the checksum fails, the XBee replies with a radio status frame indicating the nature of the failure.
API operation with escaped characters (AP parameter = 2)
Setting API to 2 allows escaped control characters in the API frame. Due to its increased complexity,
we only recommend this API mode in specific circumstances. API 2 may help improve reliability if the
serial interface to the device is unstable or malformed frames are frequently being generated.
When operating in API 2, if an unescaped 0x7E byte is observed, it is treated as the start of a new API
frame and all data received prior to this delimiter is silently discarded. For more information on using
this API mode, see the
Escaped Characters and API Mode 2
in the Digi Knowledge base.
API escaped operating mode works similarly to API mode. The only difference is that when working in
API escaped mode, the software must escape any payload bytes that match API frame specific data,
such as the start-of-frame byte (0x7E). The following table shows the structure of an API frame with
escaped characters:
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
Start delimiter field
This field indicates the beginning of a frame. It is always 0x7E. This allows the device to easily detect a
new incoming frame.
Escaped characters in API frames
If operating in API mode with escaped characters (
AP
parameter = 2), when sending or receiving a
serial 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 (XORed with 0x20).
The following data bytes need to be escaped:
n
0x7E: start delimiter
n
0x7D: escape character
n
0x11: XON
n
0x13: XOFF
To escape a character:
1. Insert 0x7D (escape character).
2. Append it with the byte you want to escape, XORed with 0x20.
In API mode with escaped characters, the length field does not include any escape characters in the
frame and the firmware calculates the checksum with non-escaped data.
