An API frame is a structured data packet used for communication between an external device and an XBee device configured in API operating mode, typically found in hosted and hybrid architectures.

In scenarios where there is no external microcontroller (hostless setups), communication with the XBee device isn’t necessary, as the MicroPython application running on the XBee handles all wireless data transmission.

API frames are transmitted and received through the serial interface of the XBee and contain not only the wireless message but also additional metadata, such as the destination and source addresses, signal quality, and command types.

Each API frame is designed to define specific operations or events within the module, enabling more advanced and controlled communication compared to simpler modes. This structured approach allows for features like addressing, acknowledgments, and remote configuration, making API mode particularly powerful for complex solutions.

XBee Studio includes an embedded tool called API Frames that helps you to generate and decode any kind of API frame. See XBee Studio User Guide for more information.

Structure

An API frame has the following structure:

api-frame-structure
Figure 1. API frame structure.
Any data received through the serial interface prior to the start delimiter is silently discarded by the XBee device.

Start delimiter

The first byte of a frame consists of a special sequence of bits, which indicate the beginning of an API frame. Its value is always 0x7E. This allows for easy detection of new incoming frames.

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 to be sent to the XBee device or received from it. Frame data is structured based on the purpose of the API frame:

api-frame-structure-data
Figure 2. Frame data structure.

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

Frames sent through the serial interface with incorrect checksums will never be processed by the XBee device and the data will be ignored.

What API frames can I use?

Depending on the purpose of the communication with your XBee device, there are multiple API frames that allow you to perform different tasks:

  • Configure the XBee.

  • Discover XBee devices in the network.

  • Exchange data with XBee devices in the network.

  • Communicate with Bluetooth devices.

  • Update the XBee device firmware.

For a complete list of API frames supported by the XBee 3 BLU device, see API frames.

The XBee 3 BLU device is not a mesh device and, therefore, does not support any networking API frames. Since the primary purpose of this device is to communicate with other Bluetooth devices or send data to the MicroPython application running on the XBee, you will need to use special API frames called User Data Relay frames.