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

RoleDevice
BLE centralGateway
BLE peripheralLeaf device
GATT clientGateway
GATT serverLeaf 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:

ItemUUID
Service UUID26530001-81E5-4861-82AE-2C92E6887922

The service exposes these characteristics:

NameUUID fragmentPropertiesDescription
Capabilities26530002-81E5-4861-82AE-2C92E6887922READProtocol version and supported features; see Capability discovery.
Device ID26530003-81E5-4861-82AE-2C92E6887922READDevice ID the gateway uses when connecting the device to Spotflow.
Session Metadata26530004-81E5-4861-82AE-2C92E6887922READCBOR-encoded Session Metadata message. The gateway forwards this payload to the ingest-cbor MQTT topic.
TX Stream26530005-81E5-4861-82AE-2C92E6887922NOTIFYDevice-to-gateway messages.
RX Stream26530006-81E5-4861-82AE-2C92E6887922WRITE without responseGateway-to-device messages.

Capability discovery

Protocol 1.1 retains the original service and characteristic UUIDs. Its Capabilities value contains:

Byte offsetRepresentationMeaning
0uint8Major version: 1.
1uint8Minor version: 1. Selects the OTA command and artifact-transfer format documented below.
2Bit fieldBit 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:

StreamDirectionBLE propertyUsed for
TX StreamDevice to gatewayNOTIFYTelemetry, reported configuration, OTA results, artifact requests and acknowledgements
RX StreamGateway to deviceWRITE without responseDesired 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 typeByte identifierFragmentedAllowed in
ACK0x00NoTX/RX
NACK0x01NoTX/RX
TELEMETRY0x02YesTX
REPORTED_CONFIGURATION0x03YesTX
DESIRED_CONFIGURATION0x04YesRX
OTA_D2C0x05YesTX
OTA_C2D0x06YesRX
ARTIFACT_REQUEST0x07YesTX
ARTIFACT_RESPONSE0x08YesRX

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+: Data

Fragmented 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 data

Continuation fragment:

Byte   0: Message type
Byte   1: Flags
Byte   2: Message sequence number, uint8
Bytes 3+: Fragment data

The pair of message type and sequence number identifies one fragmented message within a rolling window of 256 messages of that type.

Flags

BitNameMeaning
0IS_FIRSTFirst or only fragment of a message.
1IS_LASTLast or only fragment of a message.
2NEEDS_ACKRequest application acknowledgement. Set consistently in every fragment of the message.
3-7ReservedSet to 0. Receivers must not depend on these bits.

Gateway flow

A gateway connects a BLE leaf device to Spotflow with this flow:

  1. Scan for a device advertising the Spotflow GATT service.
  2. Connect to the device.
  3. Read the Capabilities characteristic and check protocol compatibility.
  4. Read the Device ID characteristic.
  5. Read the Session Metadata characteristic.
  6. Establish an MQTT connection to Spotflow using the device ID and the gateway-provided ingest key.
  7. Publish the Session Metadata payload to the ingest-cbor topic.
  8. Enable notifications on the TX Stream characteristic.
  9. Forward TELEMETRY messages from the TX Stream to the ingest-cbor MQTT topic.
  10. Forward REPORTED_CONFIGURATION messages from the TX Stream to the config-cbor-d2c MQTT topic.
  11. Forward MQTT messages from the config-cbor-c2d topic to the RX Stream as DESIRED_CONFIGURATION messages.

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 offsetFieldACK exampleNACK example
0Control message type0x000x01
1Acknowledged message type0x06 (OTA_C2D)0x06 (OTA_C2D)
2Acknowledged sequence numberSame as the commandSame 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:

  1. 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.
  2. 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.
  3. CLOSE: the device reports how many bytes it consumed and whether the transfer completed or was interrupted. The gateway acknowledges the close.
Spotflow sends an OTA command through the gateway. The device acknowledges delivery, opens the artifact, reads and consumes blocks one at a time, closes the transfer, then installs the firmware and reports its result through the gateway.
A successful main-firmware update through the existing TX/RX streams. Transfer completion precedes installation and firmware confirmation.

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:

OffsetBytesField
01Operation code from the table below.
14Nonzero transfer ID chosen by the device. Use a new ID when reopening a transfer.
54Request 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:

OperationDevice request codeGateway response code
OPEN0x010x81
READ0x020x82
CLOSE0x030x83

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):

OperationRequest bytes after the headerSuccessful response bytes after status
OPENURL length (uint16), secret length (uint8), UTF-8 URL bytes, UTF-8 secret bytes; no terminators.Positive artifact size in bytes (uint32).
READAbsolute offset (uint32), requested byte count (uint16, 1–4096). The range must fit within the artifact.Absolute offset (uint32), then exactly the requested bytes.
CLOSEConsumed 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:

StatusMeaning
0Success; operation-specific response fields follow.
1Invalid request or protocol error.
2Artifact access denied.
3Transient download failure; the device may retry.
4Artifact 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 bytes

Consumption 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.

On this page