API Overview

Reaction devices expose one custom BLE service plus the standard Device Information service.

Client applications normally do this:

1. Scan for Reaction_XXXXXX.
2. Connect.
3. Subscribe to notifications on the protocol characteristic.
4. Pair when write access is needed and the device is in pairing mode.
5. Send protobuf messages wrapped in SLIP frames to the protocol characteristic.
6. Decode notifications from the protocol characteristic.
7. Use the separate OTA data characteristic only for raw firmware blocks.

Protocol Layers

flowchart LR
  A[Reaction protobuf message] --> B[SLIP frame]
  B --> C[BLE protocol characteristic]
  D[Raw firmware block] --> E[uint32_le block index plus bytes]
  E --> F[BLE OTA data characteristic]

Control traffic uses:

Reaction protobuf -> SLIP -> protocol characteristic

Firmware block traffic uses:

uint32_le block_index + raw firmware bytes -> OTA data characteristic

Raw firmware blocks are not protobuf encoded and are not SLIP framed.

Implemented Client Operations

Operation	Client message	Device response
Query device info	Reaction{type=Query, queryType=DeviceInfo}	Reaction{type=Update, device_info=...}
Send quizbox/button/timer command	Reaction{type=Command, quizbox.event=...}	Usually derived event notifications, not an echo of the external command
Config get	Reaction{config.command=GET}	Reaction{type=Update, config.current=...}
Config set	Reaction{config.command=SET, config.patch=...}	Reaction{type=Update, config.result=..., config.current=...}
Config reset	Reaction{config.command=RESET}	Reaction{type=Update, config.result=..., config.current=...}
Firmware start/status/finalize/abort	Reaction{firmware_update.command=...}	Reaction{type=Update, firmware_update=...}
Firmware data block	Raw write to OTA data characteristic	No immediate response

Notifications

The device sends notifications for:

• internal quizbox events
• timer countdown events
• device info query responses
• config responses and config change notifications
• firmware update responses
• BLE access/write rejection status

Events caused by a BLE client command are marked as external internally. The BLE protocol handler does not re-notify external events directly; app-visible notifications usually come from the internal state changes that follow.