Response frame: Transmit Status - 0x89

Output frame: User Data Relay Output - 0xAD

Description

This frame type is used to relay user data between local interfaces:

  • MicroPython (internal interface)

  • Bluetooth® Low Energy (LE)

  • Serial port (SPI/UART). Data relayed to the serial port—while in API mode—will be output as a User Data Relay Output - 0xAD frame.

For information and examples on how to relay user data using MicroPython, see Send and receive User Data Relay frames in the MicroPython Programming Guide.

For information and examples on how to relay user data using Bluetooth® LE, see Communicate with a Micropython application in the XBee Mobile SDK user guide.

Use cases

You can exchange data with mobile applications over a Bluetooth® LE connection.

Send data from a mobile application to an external processor

  • A mobile app sends a frame over Bluetooth® LE with the UART interface as the target.

  • The XBee 3 BLU receives the frame and outputs its contents through the UART or SPI interface, encapsulated in an Output Frame.

  • The external processor receives the frame and processes it.

Send data from an external processor to a mobile application

  • The external processor sends a frame over UART or SPI with the Bluetooth® LE interface as the target.

  • The XBee 3 BLU forwards the frame contents to the mobile application over Bluetooth® LE via an Output Frame using indication.

You can exchange application-level data between a MicroPython application running on the XBee 3 BLU and an external processor over UART or SPI.

Send data from MicroPython to an external processor

  • A MicroPython application running on the XBee 3 BLU constructs a frame targeting the UART interface.

  • The XBee 3 BLU sends the frame contents through UART or SPI, encapsulated in an Output Frame.

  • The external processor receives and processes the data.

Send data from an external processor to MicroPython

  • The external processor sends a frame over UART or SPI with the MicroPython interface as the target.

  • The XBee 3 BLU routes the frame to the MicroPython interpreter.

  • The MicroPython application processes the data and may perform actions such as publishing it to an MQTT topic.

Format

The following table provides the contents of the frame. For details on frame structure, see API frames.

Offset Size Frame Field Description

0

8-bit

Start Delimiter

Indicates the start of an API frame.

1

16-bit

Length

Number of bytes between the length and checksum.

3

8-bit

Frame type

User Data Relay Input - 0x2D

4

8-bit

Frame ID

Identifies the data frame for the host to correlate with a subsequent response.
If set to 0, the device will not emit a response frame.

5

8-bit

Destination interface

The intended interface for the payload data:

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

  • 1 = Bluetooth® LE

  • 2 = MicroPython

6-n

variable

Data

The user data to be relayed

EOF

8-bit

Checksum

0xFF minus the 8-bit sum of bytes from offset 3 to this byte (between length and checksum).

Error cases

Errors are reported in a Transmit Status - 0x89 frame that corresponds with the Frame ID of the Relay Data frame:

Error code Error Description

0x7C

Invalid Interface

The user specified a destination interface that does not exist or is unsupported.

0x7D

Interface not accepting frames

The destination interface is a valid interface, but is not in a state that can accept data.
For example: UART not in API mode, Bluetooth® LE does not have a GATT client connected, or buffer queues are full.

If the message was relayed successfully, no status will be generated.

Examples

Each example is written without escapes (AP = 1) and all bytes are represented in hex format. For brevity, the start delimiter, length, and checksum fields have been excluded.

Relay to MicroPython

A host device needs to pass the message "Relay Data" to a MicroPython application running on a local XBee device via the serial port.

A corresponding Transmit Status - 0x89 response with a matching Frame ID will indicate if there was a problem with relaying the data.

If successful, the XBee MicroPython application can call relay.receive() to retrieve the data.

7E 00 0D 2D 3D 02 52 65 6C 61 79 20 44 61 74 61 FC
Frame type Frame ID Destination interface Data

0x2D

0x3D

0x02

0x52656C61792044617461

Input

Matches response

MicroPython

"Relay Data"