Reference

This page is a compact reference for the current protobuf schema. The .proto files remain authoritative.

Root Reaction

Field	Number	Type	Notes
`type`	1	optional `MESSAGE_TYPE`	`Query`, `Command`, `Update`
`queryType`	2	optional `QUERY_TYPE`	currently `Unset` or `DeviceInfo`
`sequenceNumber`	3	`uint32`	present but not currently used for correlation
`timestamp`	4	`uint32`	root timestamp field; quizbox events also carry `timestamp_us`
`quizbox`	10	`QuizboxMessage`	event payloads and quizbox device info
`device_info`	11	`DeviceInfo`	response to `DeviceInfo` query
`firmware_update`	12	`FirmwareUpdate`	OTA control messages
`config`	13	`ConfigMessage`	runtime config
`ble_access`	14	`BleAccessMessage`	access status/write rejections

Event Type Values

Name	Value
`TIMER_EXPIRED`	0
`QUIZZER_ACTION`	1
`BUTTON_ACTION`	2
`TIMER_STARTED`	3
`TIMER_CLEARED`	4
`QUIZZER_CLEARED`	5
`QUIZZER_DISPLAYED`	6
`QUIZZER_ACTIVE`	7
`TIMER_COUNTDOWN`	8
`QUIZZERS_LIT_UP`	9
`PAIRING_ACTIVE`	10
`PAIRING_INACTIVE`	11
`END`	12

Button ID Values

Name	Value	Notes
`RED_4`	0	quizzer
`RED_3`	1	quizzer
`RED_2`	2	quizzer
`RED_1`	3	quizzer
`GREEN_1`	4	quizzer
`GREEN_2`	5	quizzer
`GREEN_3`	6	quizzer
`GREEN_4`	7	quizzer
`TIMER_530`	8	control
`TIMER_RESET`	9	control
`QUIZZER_RESET`	10	control
`TIMER_60`	11	control
`TIMER_120`	12	control
`CONTEST`	13	control
`ENDER`	14	enum value exists; current hardware map does not include it

Event Payloads

message QuizzerEvent {
  ButtonID quizzer_id = 1;
  bool is_pressed = 2;
}

message ButtonEvent {
  ButtonID button_id = 1;
  bool is_pressed = 2;
}

message TimerEvent {
  int32 seconds_remaining = 1;
}

message ActiveQuizzers {
  bool is_active = 1;
  repeated ButtonID active_quizzers = 2;
}

DeviceInfo

Field	Type
`bootloaderVersion`	`string`
`firmwareVersion`	`string`
`idfVersion`	`string`
`macAddress`	`string`
`boardRevision`	`BOARD_REV`
`bankId`	`string`
`deviceType`	`DEVICE_TYPE`

Current firmware populates firmware version, IDF version, Bluetooth MAC address, board revision Rev2, and device type Main.

FirmwareUpdate Results

Result	Value
`SUCCESS`	0
`ERROR_INVALID_STATE`	1
`ERROR_NO_MEMORY`	2
`ERROR_INVALID_SIZE`	3
`ERROR_WRITE_FAILED`	4
`ERROR_VALIDATION_FAILED`	5
`ERROR_INVALID_SIGNATURE`	6
`ERROR_FLASH_FAILED`	7
`ERROR_NO_UPDATE_PARTITION`	8
`ERROR_ALREADY_IN_PROGRESS`	9
`ERROR_BLOCK_OUT_OF_RANGE`	10
`ERROR_NOT_IN_PROGRESS`	11

BLE Access

message BleAccessMessage {
  enum Status {
    NO_CONNECTION = 0;
    READ_ONLY = 1;
    WRITE_AUTHORIZED = 2;
    PAIRING_MODE = 3;
  }

  enum WriteRejectReason {
    WRITE_REJECT_UNKNOWN = 0;
    WRITE_REJECT_NOT_AUTHORIZED = 1;
    WRITE_REJECT_NOT_PAIRED = 2;
    WRITE_REJECT_NOT_ENCRYPTED = 3;
    WRITE_REJECT_NOT_AUTHENTICATED = 4;
  }

  Status status = 1;
  bool write_rejected = 2;
  WriteRejectReason reject_reason = 3;
  uint32 conn_handle = 4;
}

Tooling

Python helpers live in tools/reaction_ble_protocol.py.

Useful helper functions:

Function	Purpose
`encode_reaction`	protobuf to SLIP frame
`decode_reaction`	protobuf bytes to `Reaction`
`build_device_info_query`	build DeviceInfo query
`build_button_command`	build button or quizzer event command
`build_config_get`, `build_config_set`, `build_config_reset`	config requests
`build_firmware_start`, `build_firmware_status`, `build_firmware_finalize`, `build_firmware_abort`	OTA control requests