API frame structure

The structured data packets in API mode are called frames. They are sent and received through the serial interface of the device and contain the wireless message itself as well as some extra information such as the destination/source of the data or the signal quality.

When a device is in API mode, all data entering and leaving the module through the serial interface is contained in frames that define operations or events within the device.

An API frame has the following structure:

Start delimiter	Length		Frame data								Checksum
1	2	3	4	5	6	7	8	9	...	n	n+1
0x7E	MSB	LSB	API-specific structure								Single byte

Note MSB represents the most significant byte, and LSB represents the least significant byte.

Any data received through the serial interface prior to the start delimiter is silently discarded by the XBee. If the frame is not received correctly, or if the checksum fails, the data is also discarded and the module indicates the nature of the failure by replying with another frame.

Start delimiter

The start delimiter is the first byte of a frame consisting of a special sequence of bits that indicate the beginning of a data frame. Its value is always 0x7E. This allows for easy detection of a new incoming frame.

Length

The length field specifies the total number of bytes included in the frame data field. Its two-byte value excludes the start delimiter, the length, and the checksum.

Frame data

This field contains the information received or to be transmitted. Frame data is structured based on the purpose of the API frame:

Start delimiter	Length		Frame data								Checksum
			Frame type	Data
1	2	3	4	5	6	7	8	9	...	n	n+1
0x7E	MSB	LSB	API frame type	Frame-type-specific data							Single byte

Note MSB represents the most significant byte, and LSB represents the least significant byte.

• Frame type is the API frame type identifier. It determines the type of API frame and indicates how the information is organized in the Data field.
• Data contains the data itself. The information included here and its order depends on the type of frame defined in the Frame type field.

Checksum

Checksum is the last byte of the frame and helps test data integrity. It is calculated by taking the hash sum of all the API frame bytes that came before it, excluding the first three bytes (start delimiter and length).

Calculate the checksum of an API frame

1. Add all bytes of the packet, excluding the start delimiter 0x7E and the length (the second and third bytes).
2. From the result, keep only the lowest 8 bits.
3. Subtract this quantity from 0xFF.

Verify the checksum of a given API frame

1. Add all bytes including the checksum (do not include the delimiter and length).
2. If the checksum is correct, the last two digits on the far right of the sum will equal FF.