User Data Relay Input - 0x2D
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), BLE, or the serial port. 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 BLE, see Communicate with a Micropython application in the XBee Mobile SDK user guide.
Use cases
- You can use this frame to send data to an external processor through the XBee UART/SPI via the BLE connection. Use a cellphone to send the frame with UART interface as a target. Data contained within the frame is sent out the UART contained within an Output Frame. The external processor then receives and acts on the frame.
- Use an external processor to output the frame over the UART with the BLE interface as a target. This outputs the data contained in the frame as the Output Frame over the active BLE connection via indication.
- An external processor outputs the Frame over the UART with the Micropython interface as a target. Micropython operates over the data and publishes the data to mqtt topic.
Format
The following table provides the contents of the frame. For details on frame structure, see API frame format.
| 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. |
| 5 | 8-bit | Destination Interface |
The intended interface for the payload data: 0 = Serial port—SPI, or UART when in API mode |
| 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. |
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" |
PDF
