The User Data Relay API frames are specialized API frames used in XBee devices to transmit data directly to specific interfaces of the XBee device and receive data from those interfaces. These interfaces are:

  • Bluetooth: The Bluetooth Low Energy (BLE) interface, enabling wireless communication with Bluetooth-enabled devices.

  • Serial port: The Universal Asynchronous Receiver-Transmitter (UART), typically used for serial communication with external microcontrollers or devices.

  • MicroPython: The internal interface used for executing and interacting with MicroPython scripts running on the XBee device.

A parameter within the frame indicates the target interface of the embedded data, making the User Data Relay frames essential for versatile and efficient communication in complex XBee configurations.

There are two User Data Relay API frames:

User Data Relay

The User Data Relay API frame is designed to transmit data to a specific interface on the XBee device, with the flexibility to designate the target interface.

The Frame data structure for this frame is as follows:

Field name Data type Field value Description

Frame type

Byte

0x2D

  • User Data Relay - 0x2D

Frame ID

Byte

<User defined>

  • Reference identifier used to match TX Status frames (type 0x89) sent for errors. A value of 0 disables the TX Status frame.

Destination interface

Byte

<User defined>

  • 0 = Serial port (SPI, or UART when in API mode)

  • 1 = Bluetooth

  • 2 = MicroPython

Data

Variable

<User defined>

  • The user data to send.
For detailed information about this frame, see User Data Relay Input - 0x2D.

User Data Relay Output

The User Data Relay Output API frame is the counterpart to the User Data Relay frame. It is used to receive data that has been transmitted to a specific interface on the XBee device. This frame allows the system to retrieve data from the MicroPython environment, UART, or Bluetooth interface, depending on where the data was originally sent.

The Frame data structure for this frame is as follows:

Field name Data type Field value Description

Frame type

Byte

0xAD

  • User Data Relay Output - 0xAD

Source interface

Byte

<User defined>

  • 0 = Serial port (SPI, or UART when in API mode)

  • 1 = Bluetooth

  • 2 = MicroPython

Data

Variable

<User defined>

  • The user data received.
For detailed information about this frame, see User Data Relay Output - 0xAD.

The following diagram displays a hosted solution where an XBee 3 BLU device configured in API mode communicates with a smartphone through the Bluetooth interface using User Data Relay frames:

diagram
Some XBee libraries provided by Digi for microcontroller application development include methods that abstract the use of these User Data Relay frames, allowing you to send data to the MicroPython or Bluetooth interfaces simply by calling a method.