Reaction Device API

This site documents the BLE protocol used by Reaction/Quizbox devices.

The intent is practical client implementation: how to connect, how messages are framed, which protobuf payloads are sent, and what each event means when an app receives it.

Source Of Truth

These docs were written against the current repository implementation:

Area	Source files
Wire schema	reaction_protos/*.proto
BLE service, characteristics, advertising	main/Source/BleTransport.cpp
Pairing and write authorization	main/Tasks/BleTask.cpp, main/Source/BleSessionManager.cpp, main/Source/BleSessionPolicy.cpp
Message routing	main/Source/BleProtocolHandler.cpp
Event to protobuf conversion	main/Source/EventConverter.cpp
Quizzer behavior	main/Source/QuizzerHandler.cpp
Timer behavior	main/Source/TimerHandler.cpp, main/Tasks/TimerTask.hpp
Config behavior	reaction_protos/Config.proto, main/Source/ConfigService.cpp, main/Source/DeviceConfig.cpp
Firmware update behavior	reaction_protos/FirmwareUpdate.proto, main/Source/FirmwareUpdateHandler.cpp
Python test client behavior	tools/reaction_ble_protocol.py, tools/ble_test_client.py

If this site and those files disagree, treat the source files as authoritative and update the docs in the same pull request as the protocol change.

Hosting

The repository includes mkdocs.yml, so this site can be hosted with GitHub Pages, Read the Docs, or any static web host.

Local preview:

python3 -m pip install -r docs/requirements.txt
python3 -m mkdocs serve

Static build:

python3 -m mkdocs build

Important Accuracy Note

Some older engineering notes remain in docs/ for history and implementation context. The pages under API Guide are the client-facing reference. See Known Gaps for places where older specs or comments implied behavior that current firmware does not appear to implement.