Reaction game: an LED cue, button, and OLED score

#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

constexpr uint8_t LED_PIN = 25;
constexpr uint8_t BUTTON_PIN = 27;
constexpr uint8_t SDA_PIN = 21;
constexpr uint8_t SCL_PIN = 22;
constexpr uint8_t OLED_ADDRESS = 0x3C;
constexpr uint32_t DEBOUNCE_MS = 30;
constexpr uint32_t REACTION_WINDOW_MS = 3000;
Adafruit_SSD1306 display(128, 64, &Wire, -1, 100000UL, 100000UL);
// Each event is accepted once after 30 ms of stable input.
// If held during reset, a stable release is required before the first press.
struct DebouncedButton {
  bool rawHigh = true;
  bool stableHigh = true;
  bool armed = true;
  bool pressed = false;
  bool released = false;
  uint32_t rawChangedAt = 0;
  uint32_t pressStartedAt = 0;
  void begin(uint32_t now) {
    rawHigh = stableHigh = digitalRead(BUTTON_PIN) == HIGH;
    armed = rawHigh;
    rawChangedAt = now;
    pressed = released = false;
  }
  void update(uint32_t now) {
    pressed = released = false;
    const bool readingHigh = digitalRead(BUTTON_PIN) == HIGH;
    if (readingHigh != rawHigh) {
      rawHigh = readingHigh;
      rawChangedAt = now;
    }
    if (rawHigh != stableHigh && static_cast<uint32_t>(now - rawChangedAt) >= DEBOUNCE_MS) {
      stableHigh = rawHigh;
      if (stableHigh) {
        armed = true;
        released = true;
      } else if (armed) {
        pressed = true;
        pressStartedAt = rawChangedAt;
      }
    }
  }
};
DebouncedButton button;

enum GameState { IDLE, RELEASE_TO_START, WAITING, GO, RESULT, FALSE_START, TIMEOUT };
GameState state = IDLE;
bool ready = false;
bool hasBest = false;
uint32_t stateSince = 0;
uint32_t waitDuration = 0;
uint32_t goAt = 0;
uint32_t reactionMs = 0;
uint32_t bestMs = 0;
void finishTrial(GameState outcome, uint32_t score);

void scanI2CBus() {
  Serial.println("I2C scan: ACK identifies an address, not the display controller.");
  uint8_t found = 0;
  for (uint8_t address = 1; address < 127; ++address) {
    Wire.beginTransmission(address);
    if (Wire.endTransmission() == 0) {
      Serial.print("ACK at 0x"); Serial.println(address, HEX);
      ++found;
    }
  }
  if (found == 0) Serial.println("No I2C device acknowledged.");
}

bool initializeDisplay() {
  if (!Wire.begin(SDA_PIN, SCL_PIN)) {
    Serial.println("OLED ERROR: I2C initialization failed; reset to retry.");
    return false;
  }
  Wire.setClock(100000);
  Wire.setTimeOut(50);
  scanI2CBus();
  Wire.beginTransmission(OLED_ADDRESS);
  if (Wire.endTransmission() != 0) {
    Serial.println("OLED ERROR: configured address did not ACK; check wiring/address and reset.");
    return false;
  }
  if (!display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS, false, false)) {
    Serial.println("OLED ERROR: buffer initialization failed; reset to retry.");
    return false;
  }
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setTextWrap(false);
  return true;
}

void renderScreen() {
  display.clearDisplay();
  display.setCursor(0, 0); display.print("Reaction game");
  display.setCursor(0, 14);
  if (state == IDLE) display.print("Press to start");
  else if (state == RELEASE_TO_START) display.print("Release the button");
  else if (state == WAITING || state == GO) {
    display.print("Watch the LED");
    display.setCursor(0, 26); display.print("Press when lit");
  } else if (state == RESULT) {
    display.print("Reaction: "); display.print(reactionMs); display.print(" ms");
  } else if (state == FALSE_START) display.print("FALSE START");
  else display.print("TIMEOUT");
  display.setCursor(0, 40);
  if (hasBest) { display.print("Best: "); display.print(bestMs); display.print(" ms"); }
  else display.print("Best: --");
  if (state == RESULT || state == FALSE_START || state == TIMEOUT) {
    display.setCursor(0, 54); display.print("Press for next round");
  }
  display.display();
}

void startWaiting() {
  randomSeed(micros());
  waitDuration = static_cast<uint32_t>(random(2000L, 5001L));
  digitalWrite(LED_PIN, LOW);
  state = WAITING;
  renderScreen();  // Complete this transfer before starting the timing window.
  stateSince = millis();
}

void finishTrial(GameState outcome, uint32_t score) {
  digitalWrite(LED_PIN, LOW);
  state = outcome;
  stateSince = millis();
  if (state == RESULT) {
    reactionMs = score;
    if (!hasBest || score < bestMs) { bestMs = score; hasBest = true; }
    Serial.print("Reaction_ms="); Serial.print(reactionMs);
    Serial.print(" best_ms="); Serial.println(bestMs);
  } else Serial.println(state == FALSE_START ? "FALSE START" : "TIMEOUT");
  renderScreen();
}

void setup() {
  Serial.begin(115200);
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  button.begin(millis());
  ready = initializeDisplay();
  if (!ready) return;
  stateSince = millis();
  renderScreen();
}

void loop() {
  if (!ready) return;
  const uint32_t now = millis();
  button.update(now);
  if (state == IDLE || state == RESULT || state == FALSE_START || state == TIMEOUT) {
    if (button.pressed) {
      state = RELEASE_TO_START;
      stateSince = now;
      renderScreen();
    }
    return;
  }
  if (state == RELEASE_TO_START) {
    if (button.released) startWaiting();
    return;
  }
  if (state == WAITING) {
    if (button.pressed) { finishTrial(FALSE_START, 0); return; }
    if (static_cast<uint32_t>(now - stateSince) >= waitDuration) {
      digitalWrite(LED_PIN, HIGH);
      goAt = millis();
      state = GO;
    }
    return;
  }
  // During WAITING and GO, no display transfer or Serial output is performed.
  // pressStartedAt is the first observed LOW of the final stable debounce interval.
  if (button.pressed) {
    const int32_t signedReaction = static_cast<int32_t>(button.pressStartedAt - goAt);
    if (signedReaction < 0) finishTrial(FALSE_START, 0);
    else if (static_cast<uint32_t>(signedReaction) <= REACTION_WINDOW_MS) {
      finishTrial(RESULT, static_cast<uint32_t>(signedReaction));
    } else finishTrial(TIMEOUT, 0);
    return;
  }
  // A press beginning at exactly 3000 ms still receives its 30 ms qualification time.
  if (static_cast<uint32_t>(now - goAt) >= REACTION_WINDOW_MS + DEBOUNCE_MS) {
    finishTrial(TIMEOUT, 0);
  }
}