📡 Protocol & Packet Specification

This technical reference defines the RF packet structures used over ESP-NOW and the JSON communication schema between the ESP32 Base Station Hub and the web browser.

1. ESP-NOW Binary Structs (Channel 1)

To minimize airtime to <1 millisecond, remotes and the hub exchange packed C structures.

Remote → Base Station Packet (`QuizBuzzPacket`, 13 Bytes):

QuizBuzzPacket C Struct

typedef struct __attribute__((packed)) {
    uint8_t  msg_type;      // 0x01 = BUZZ, 0x02 = PING / HEARTBEAT
    uint8_t  remote_id;     // 1 to 254 (Remote Identifier)
    char     button;        // 'A', 'B', 'C', 'D' (or 0 for ping)
    uint8_t  button_idx;    // 0=A, 1=B, 2=C, 3=D
    uint32_t press_count;   // Incrementing counter for loss/deduplication
    uint16_t vbat_mv;       // Battery voltage in millivolts (e.g. 3850 mV)
    uint32_t uptime_ms;     // Remote local uptime in milliseconds
} QuizBuzzPacket;

Base Station → Remotes Feedback Packet (`QuizFeedbackPacket`, 9 Bytes):

QuizFeedbackPacket C Struct

typedef struct __attribute__((packed)) {
    uint8_t  msg_type;      // 0x10 = ACK_BUZZ, 0x11 = GAME_STATE, 0x12 = RESET
    uint8_t  target_remote; // 0 = Broadcast to all, or specific remote_id (1-254)
    uint8_t  game_state;    // 0 = LOCKED, 1 = OPEN, 2 = ACTIVE
    uint8_t  winner_remote; // Remote ID that buzzed in first (0 if none)
    char     winner_button; // 'A', 'B', 'C', 'D'
    uint8_t  led_color_r;   // RGB feedback Red (0-255)
    uint8_t  led_color_g;   // RGB feedback Green (0-255)
    uint8_t  led_color_b;   // RGB feedback Blue (0-255)
    uint16_t duration_ms;   // Milliseconds to sustain LED illumination
} QuizFeedbackPacket;

2. Base Station Serial JSON Event Stream (115200 Baud)

The Base Station outputs newline-delimited JSON events over its USB-UART bridge to the browser:

Fastest Buzz Event (First to Buzz)

{"event":"buzz","remote_id":1,"button":"A","button_idx":0,"first":true,"delta_ms":0,"vbat_mv":3850,"seq":12,"timestamp_ms":45120}

Subsequent Buzz Event (During Open Window)

{"event":"buzz","remote_id":3,"button":"C","button_idx":2,"first":false,"delta_ms":142,"vbat_mv":3920,"seq":8,"already_buzzed":false}

Heartbeat / Battery Ping

{"event":"ping","remote_id":2,"vbat_mv":4100,"uptime_ms":120400}

Host Commands Sent to Base Station:

Command	Description
`OPEN\n` or `{"cmd":"open"}`	Opens buzz window, resets winner, broadcasts unlock to remotes
`LOCK\n` or `{"cmd":"lock"}`	Locks all buzzers, broadcasts lockout state
`RESET\n` or `{"cmd":"reset"}`	Clears round state and sends reset pulse
`MODE_FIRST\n`	Switches hub to "First to Buzz" lockout mode
`MODE_ALL\n`	Switches hub to "All-Answer" poll mode
`PING\n`	Requests hub status & uptime report