Skip to content

Quizzer Events

Quizzer event naming is subtle. The same physical buzz can produce several events, each with a different meaning.

The Short Version

Event Payload Meaning
QUIZZER_ACTION quizzer_event Raw quizzer press/release input
QUIZZER_ACTIVE active_quizzers The system considers one or more quizzers buzzed/active
QUIZZER_DISPLAYED active_quizzers A quizzer was written to the device display
QUIZZER_CLEARED none Quizzer state/display was cleared when returning idle
QUIZZERS_LIT_UP active_quizzers Active quizzer LEDs were restored/lit after reset handling

QUIZZER_ACTION is input. The others are derived state or UI events.

Raw Input: QUIZZER_ACTION

Payload:

quizzer_event {
  quizzer_id: RED_1
  is_pressed: true
}

This is the edge-level input from a quizzer button. It can represent press or release.

Hardware quizzer events are published by the UART receiver after decoding the coprocessor button code. The UART receiver also updates SystemData with the current pressed/buzzed state for quizzer buttons.

BLE clients with write authorization can also send QUIZZER_ACTION commands to simulate quizzer input.

Logical State: QUIZZER_ACTIVE

Payload:

active_quizzers {
  is_active: true
  active_quizzers: [RED_1]
}

This means the firmware considers the quizzer active after handling the raw input.

When the quizzer handler is idle and receives a QUIZZER_ACTION, it publishes QUIZZER_ACTIVE before updating LEDs and sound.

QUIZZER_ACTIVE can be emitted even when the quizzer is not displayed on the physical display.

Physical Display: QUIZZER_DISPLAYED

Payload:

active_quizzers {
  is_active: true
  active_quizzers: [RED_1]
}

This means the quizzer name was written to the device display.

The firmware only publishes QUIZZER_DISPLAYED when it actually calls the display write path for the quizzer. If a timer is running, the quizzer can become active without being displayed because the timer owns the display.

LED Restore: QUIZZERS_LIT_UP

Payload:

active_quizzers {
  is_active: true
  active_quizzers: [RED_1, GREEN_2]
}

This event is emitted from reset-button handling when the firmware restores/lights LEDs for quizzers that are still considered buzzed.

It is not the same as a raw quizzer press and it is not proof that the display changed.

Clear: QUIZZER_CLEARED

No additional payload.

The quizzer handler publishes this when it enters idle. Timer handling uses it to clear internal quizzerDisplayed and quizzerActive flags.

Clients should clear active quizzer UI when they receive QUIZZER_CLEARED.

Normal Lifecycle

sequenceDiagram
  participant Q as Quizzer
  participant D as Device firmware
  participant C as BLE client

  Q->>D: Press RED_1
  D->>C: QUIZZER_ACTION { RED_1, pressed }
  D->>C: QUIZZER_ACTIVE { [RED_1] }
  alt timer is not running
    D->>C: QUIZZER_DISPLAYED { [RED_1] }
  end

Buzz While Timer Is Running

sequenceDiagram
  participant Q as Quizzer
  participant D as Device firmware
  participant C as BLE client

  Q->>D: Press RED_1
  D->>C: QUIZZER_ACTION { RED_1, pressed }
  D->>C: QUIZZER_ACTIVE { [RED_1] }
  Note over D,C: No QUIZZER_DISPLAYED because the timer display is preserved.

Client State Guidance

Use QUIZZER_ACTION if you need a raw press/release log.

Use QUIZZER_ACTIVE, QUIZZER_CLEARED, and QUIZZERS_LIT_UP to maintain current active indicators.

Use QUIZZER_DISPLAYED only when your UI specifically cares that the physical device display changed.

Do not treat QUIZZER_ACTIVE and QUIZZER_DISPLAYED as duplicates. They represent different facts.