Bluetooth Low Energy
The Spotflow BLE protocol for telemetry, configuration and OTA updates through a gateway.
Bluetooth Low Energy support uses a gateway architecture. A leaf device exposes the Spotflow Observability Service over BLE, and a gateway connects to that service, reads device context, receives framed messages, and forwards them to Spotflow over MQTT.
This page describes the protocol and the expected behavior of devices and gateways, including OTA command delivery and artifact transfer. A gateway can be a dedicated application or the Spotflow Web App's BLE gateway.
To connect a device and send telemetry through the Spotflow Web App gateway, start with the Bluetooth Low Energy setup guide.
Roles
| Role | Device |
|---|---|
| BLE central | Gateway |
| BLE peripheral | Leaf device |
| GATT client | Gateway |
| GATT server | Leaf device |
The leaf device produces telemetry and handles configuration and OTA commands. The gateway bridges the BLE stream to Spotflow MQTT topics and downloads OTA artifacts on the device's behalf.
GATT service
The Spotflow BLE protocol uses the following UUID layout:
| Item | UUID |
|---|---|
| Service UUID | 26530001-81E5-4861-82AE-2C92E6887922 |
The service exposes these characteristics:
| Name | UUID fragment | Properties | Description |
|---|---|---|---|
| Capabilities | 26530002-81E5-4861-82AE-2C92E6887922 | READ | Protocol version and supported features; see Capability discovery. |
| Device ID | 26530003-81E5-4861-82AE-2C92E6887922 | READ | Device ID the gateway uses when connecting the device to Spotflow. |
| Session Metadata | 26530004-81E5-4861-82AE-2C92E6887922 | READ | CBOR-encoded Session Metadata message. The gateway forwards this payload to the ingest-cbor MQTT topic. |
| TX Stream | 26530005-81E5-4861-82AE-2C92E6887922 | NOTIFY | Device-to-gateway messages. |
| RX Stream | 26530006-81E5-4861-82AE-2C92E6887922 | WRITE without response | Gateway-to-device messages. |
Capability discovery
Protocol 1.1 retains the original service and characteristic UUIDs. Its Capabilities value contains:
| Byte offset | Representation | Meaning |
|---|---|---|
| 0 | uint8 | Major version: 1. |
| 1 | uint8 | Minor version: 1. Selects the OTA command and artifact-transfer format documented below. |
| 2 | Bit field | Bit 0 advertises OTA commands and artifact transfer. Other bits are reserved. |
For example, 01 01 01 advertises protocol 1.1 with OTA support. Older devices may expose only the major version, or the major and minor versions without a feature byte.
Enable OTA only when the gateway recognizes the advertised version and the OTA feature bit is set. Otherwise, keep the connection telemetry/configuration-only and do not subscribe the device to OTA commands. Artifact messages have no separate version field.
Streams
The protocol uses one stream in each direction:
| Stream | Direction | BLE property | Used for |
|---|---|---|---|
| TX Stream | Device to gateway | NOTIFY | Telemetry, reported configuration, OTA results, artifact requests and acknowledgements |
| RX Stream | Gateway to device | WRITE without response | Desired configuration, OTA commands and artifact responses |
The gateway controls device-to-gateway traffic through the Client Characteristic Configuration Descriptor (CCCD) on the TX Stream characteristic. When the gateway enables notifications in the CCCD, the device may send TX Stream notifications. When notifications are disabled, the device must stop sending TX Stream notifications.
Both streams use the same frame format. Framing is required because messages may be larger than the negotiated ATT MTU, which can be as low as 23 bytes. Each frame must fit within the ATT MTU minus its three-byte header, up to the 512-byte GATT value limit. Capabilities do not advertise a frame size; determine it for each connection and use 20-byte frames when a larger size is not known to be supported.
Because there is a single stream in each direction, multiplexing is handled by the message type in each frame rather than by separate GATT characteristics.
Message types
The first byte of each frame identifies the message type. The receiver reads this byte before parsing the rest of the frame.
| Message type | Byte identifier | Fragmented | Allowed in |
|---|---|---|---|
ACK | 0x00 | No | TX/RX |
NACK | 0x01 | No | TX/RX |
TELEMETRY | 0x02 | Yes | TX |
REPORTED_CONFIGURATION | 0x03 | Yes | TX |
DESIRED_CONFIGURATION | 0x04 | Yes | RX |
OTA_D2C | 0x05 | Yes | TX |
OTA_C2D | 0x06 | Yes | RX |
ARTIFACT_REQUEST | 0x07 | Yes | TX |
ARTIFACT_RESPONSE | 0x08 | Yes | RX |
TELEMETRY messages carry Spotflow telemetry payloads, including core dump chunks, metrics, and logs. When multiple telemetry payloads are pending, the device sends them in this priority order: core dump chunks first, then metrics, then logs.
OTA_C2D delivery uses application acknowledgements, as described in Delivery guarantees. Artifact requests and responses use their own request/response exchange.
Frame format
Every frame starts with the message type byte:
Byte 0: Message type
Byte 1+: DataFragmented message types use the following frame layouts.
First fragment:
Byte 0: Message type
Byte 1: Flags
Byte 2: Message sequence number, uint8
Bytes 3-4: Total message byte length, uint16 little-endian
Bytes 5+: Fragment dataContinuation fragment:
Byte 0: Message type
Byte 1: Flags
Byte 2: Message sequence number, uint8
Bytes 3+: Fragment dataThe pair of message type and sequence number identifies one fragmented message within a rolling window of 256 messages of that type.
Flags
| Bit | Name | Meaning |
|---|---|---|
| 0 | IS_FIRST | First or only fragment of a message. |
| 1 | IS_LAST | Last or only fragment of a message. |
| 2 | NEEDS_ACK | Request application acknowledgement. Set consistently in every fragment of the message. |
| 3-7 | Reserved | Set to 0. Receivers must not depend on these bits. |
Gateway flow
A gateway connects a BLE leaf device to Spotflow with this flow:
- Scan for a device advertising the Spotflow GATT service.
- Connect to the device.
- Read the Capabilities characteristic and check protocol compatibility.
- Read the Device ID characteristic.
- Read the Session Metadata characteristic.
- Establish an MQTT connection to Spotflow using the device ID and the gateway-provided ingest key.
- Publish the Session Metadata payload to the
ingest-cbortopic. - Enable notifications on the TX Stream characteristic.
- Forward
TELEMETRYmessages from the TX Stream to theingest-cborMQTT topic. - Forward
REPORTED_CONFIGURATIONmessages from the TX Stream to theconfig-cbor-d2cMQTT topic. - Forward MQTT messages from the
config-cbor-c2dtopic to the RX Stream asDESIRED_CONFIGURATIONmessages.
The gateway forwards complete message payloads between BLE and MQTT. It does not need to interpret Spotflow telemetry payloads to route them.
Delivery guarantees
NOTIFY and WRITE without response provide best-effort delivery at the application level. Messages without NEEDS_ACK, including SDK telemetry, receive no application acknowledgement.
For reliable OTA command delivery, the gateway sets NEEDS_ACK in every fragment of an OTA_C2D message. The device responds after reassembly with one unfragmented control frame:
| Byte offset | Field | ACK example | NACK example |
|---|---|---|---|
| 0 | Control message type | 0x00 | 0x01 |
| 1 | Acknowledged message type | 0x06 (OTA_C2D) | 0x06 (OTA_C2D) |
| 2 | Acknowledged sequence number | Same as the command | Same as the command |
ACK means that the complete payload was delivered to its handler. For OTA, this confirms handoff to the OTA core; manifest validation, installation and firmware confirmation are reported separately through the OTA protocol.
For supported inbound messages requesting acknowledgement, the device sends NACK if it cannot reassemble or deliver the message, including an inconsistent NEEDS_ACK flag, invalid length or orphan continuation. Unsupported types and frames too short to identify their sequence receive no ACK/NACK.
The sender waits for ACK before sending the next message of that type. On NACK or timeout, it retransmits the complete message with the same sequence and payload, using backoff between retries. Complete retransmissions are delivered and acknowledged again, so handlers must tolerate duplicates. OTA attempt IDs provide this duplicate handling independently of BLE sequence numbers.
OTA commands and results
For devices advertising OTA, the gateway forwards ota-cbor-c2d MQTT payloads unchanged as OTA_C2D, and publishes OTA_D2C payloads unchanged to ota-cbor-d2c. It must be ready to forward commands when subscribing: the cloud can send the current manifest immediately. Use the device's MQTT connection established in Gateway flow.
The gateway does not parse manifests. The device selects each artifact and asks the gateway to download it through the artifact-transfer protocol below. Both automatic main-firmware updates and application-managed artifacts use this path. See the OTA MQTT protocol for command and result schemas.
Artifact transfer
The device controls the transfer of each artifact:
- OPEN: the device sends the artifact URL and download secret. The gateway obtains the artifact over HTTPS using
Authorization: OtaSecret <secret>and returns its total size. - READ: the device requests a block by byte offset and length. The gateway returns that offset and exactly the requested bytes. The device consumes the block before requesting the next one.
- CLOSE: the device reports how many bytes it consumed and whether the transfer completed or was interrupted. The gateway acknowledges the close.
OPEN, READ and CLOSE are application messages, rather than GATT read/write operations. Requests travel as ARTIFACT_REQUEST (0x07) on TX Stream; responses travel as ARTIFACT_RESPONSE (0x08) on RX Stream. Both use the ordinary stream framing, with NEEDS_ACK omitted because the response acknowledges the request.
The gateway may cache or stream the HTTPS download; a BLE READ does not require a separate HTTP request. Repeated requests must return the same artifact bytes. Gateway storage strategy and artifact-size limits are implementation choices.
Message layout
The following offsets are relative to the reassembled artifact-message payload, excluding BLE frame headers. All integers are unsigned and little-endian. Artifact offsets count bytes from the beginning of the complete downloaded file, including any signed container headers.
Every request and response starts with this 9-byte header:
| Offset | Bytes | Field |
|---|---|---|
| 0 | 1 | Operation code from the table below. |
| 1 | 4 | Nonzero transfer ID chosen by the device. Use a new ID when reopening a transfer. |
| 5 | 4 | Request ID chosen by the device for each exchange within the transfer. Preserve it when retransmitting. |
A response copies the request's transfer ID and request ID and uses the corresponding response operation code:
| Operation | Device request code | Gateway response code |
|---|---|---|
| OPEN | 0x01 | 0x81 |
| READ | 0x02 | 0x82 |
| CLOSE | 0x03 | 0x83 |
For example, a READ request starts with 0x02, and its response starts with 0x82. These are payload operation codes; the outer BLE message types remain 0x07 for requests and 0x08 for responses.
Every response adds a one-byte status at offset 9. Operation-specific fields follow the header in requests (offset 9) and the status in successful responses (offset 10):
| Operation | Request bytes after the header | Successful response bytes after status |
|---|---|---|
| OPEN | URL length (uint16), secret length (uint8), UTF-8 URL bytes, UTF-8 secret bytes; no terminators. | Positive artifact size in bytes (uint32). |
| READ | Absolute offset (uint32), requested byte count (uint16, 1–4096). The range must fit within the artifact. | Absolute offset (uint32), then exactly the requested bytes. |
| CLOSE | Consumed offset (uint32), reason (uint8): 0 complete, 1 interrupted or canceled. | None. |
The URL is at most 128 bytes and the nonempty secret at most 24 bytes. The secret is a printable ASCII token without whitespace. Both come from the OTA manifest; the gateway uses the secret only to authorize the artifact download.
Status values are:
| Status | Meaning |
|---|---|
0 | Success; operation-specific response fields follow. |
1 | Invalid request or protocol error. |
2 | Artifact access denied. |
3 | Transient download failure; the device may retry. |
4 | Artifact exceeds the gateway's supported size. |
Error responses contain only the common header and status (10 bytes total). A successful CLOSE response also has no further fields.
For example, this READ response returns four bytes at artifact offset 512 for transfer ID 1, request ID 3. The BLE fragmentation headers are omitted:
82 | 01 00 00 00 | 03 00 00 00 | 00 | 00 02 00 00 | DE AD BE EF
op | transfer ID | request ID | status | offset | artifact bytesConsumption and retries
Only one block is outstanding at a time. The device accepts a response only when its operation, transfer ID and request ID match the pending request; a READ response must also match the requested offset and exact length. Stale or duplicate responses cannot advance consumption.
The next READ offset acknowledges consumption of the previous block. CLOSE with reason 0 acknowledges consumption of the final block and must report the full artifact size. The device advances this offset only after processing the block; durability depends on the firmware backend or delegated handler. Successful transfer alone does not establish that installation or confirmation succeeded.
If a reply is lost, the device repeats the pending request with the same IDs. The gateway must tolerate repeated OPEN, READ and CLOSE requests. On timeout or disconnect, the device retries with backoff, opens a new transfer and resumes at the last consumed offset. The artifact bytes and total size must remain unchanged across retries. If only the final CLOSE response was lost, the device can reopen and close at the total size without consuming the final block again. SDK timeout and buffer settings are documented in the OTA Kconfig reference.
Disconnects, resets, and cancellation
After a BLE reconnect, repeat capability discovery and device/session setup before resuming forwarding. After an MQTT reconnect, republish session metadata and restore subscriptions, including OTA for supported devices. Subscribing again causes the cloud to replay an attempt whose results are incomplete.
A live device downloader can resume from its consumed offset; the gateway may need to download the artifact again. After a device reset, the SDK retains completed artifact results and restarts the unfinished artifact from zero once the cloud replays the manifest. OTA cancellation uses the same commands as direct MQTT; an interrupted transfer closes with reason 1 when the link is available.
Security
The gateway holds both the workspace ingest key and artifact download credentials, so it is part of the trust boundary. Protect the BLE link with encryption and restrict pairing to authorized gateways. Firmware signature checks remain the responsibility of the bootloader or delegated handler; they do not authorize a gateway to initiate updates. Do not log OPEN payloads, secrets or credential-bearing URLs.
Sample
The Spotflow device SDK includes a Zephyr BLE sample. Follow the BLE setup guide to use it with the Web App gateway, including its OTA configuration and development limitations.