Function bodies 879 total

  void playRandomTone(int semitoneShift = 0, uint32_t durationMs = 150) override {
    static constexpr int scale[] = {60, 62, 64, 65, 67, 69, 71};
    int      midi = scale[random(0, 7)] + semitoneShift;
    uint16_t freq = (uint16_t)(440.0 * pow(2.0, (double)(midi - 69) / 12.0));
    tone(freq, durationMs);
  }

  void playWin() override {
    if (_taskHandle) return;
    _seq[0] = {523, 120, 50};
    _seq[1] = {659, 120, 50};
    _seq[2] = {784, 200, 0};
    _seqLen = 3;
    xTaskCreate(_seqTask, "spkseq", 1024, this, 2, &_taskHandle);
  }

  void playLose() override {
    if (_taskHandle) return;
    _seq[0] = {392, 120, 50};
    _seq[1] = {330, 120, 50};
    _seq[2] = {262, 200, 0};
    _seqLen = 3;
    xTaskCreate(_seqTask, "spkseq", 1024, this, 2, &_taskHandle);
  }

  void playCorrectAnswer() override {
    if (_taskHandle) return;
    _seq[0] = {523, 180, 100};
    _seq[1] = {784, 120, 0};
    _seqLen = 2;
    xTaskCreate(_seqTask, "spkseq", 1024, this, 2, &_taskHandle);
  }

  void playWrongAnswer() override {
    if (_taskHandle) return;
    _seq[0] = {1109, 150, 100};
    _seq[1] = {1109, 150, 0};
    _seqLen = 2;
    xTaskCreate(_seqTask, "spkseq", 1024, this, 2, &_taskHandle);
  }

  void _stopTask() {
    if (_taskHandle) {
      vTaskDelete(_taskHandle);
      _taskHandle = nullptr;
      ledcWrite(_ch, 0);
    }
  }

  void _playTone(uint16_t freq) {
    if (freq == 0 || _duty == 0) { ledcWrite(_ch, 0); return; }
    ledcSetup(_ch, freq, 8);
    ledcWrite(_ch, _duty);
  }

  static void _toneTask(void* arg) {
    auto* self = static_cast<SpeakerBuzzer*>(arg);
    self->_playTone(self->_freq);
    vTaskDelay(pdMS_TO_TICKS(self->_duration));
    ledcWrite(_ch, 0);
    self->_taskHandle = nullptr;
    vTaskDelete(nullptr);
  }

  static void _seqTask(void* arg) {
    auto* self = static_cast<SpeakerBuzzer*>(arg);
    for (uint8_t n = 0; n < self->_seqLen; n++) {
      const Note& note = self->_seq[n];
      self->_playTone(note.freq);
      vTaskDelay(pdMS_TO_TICKS(note.durationMs));
      ledcWrite(_ch, 0);
      if (note.delayMs > 0) vTaskDelay(pdMS_TO_TICKS(note.delayMs));
    }
    self->_taskHandle = nullptr;
    vTaskDelete(nullptr);
  }

Device* Device::createInstance() {
  pinMode(ADC_EN, OUTPUT);
  digitalWrite(ADC_EN, HIGH);
  delay(100); // Wait for power to stabilize
  pinMode(LCD_BL, OUTPUT);
  digitalWrite(LCD_BL, HIGH);

  storageLFS.begin();

  return new Device(display, power, &navigation, nullptr,
                    nullptr, &storageLFS, nullptr, nullptr);
}

class DisplayImpl : public IDisplay
{
public:
  void setBrightness(uint8_t pct) override {
    if (pct > 100) pct = 100;

    static bool _ready = false;
    if (!_ready) {
      ledcSetup(LCD_BL_CH, 256, 8);
      ledcAttachPin(LCD_BL, LCD_BL_CH);
      _ready = true;
    }

    uint8_t brightness = (uint8_t)((uint32_t)pct * 255 / 100);
    ledcWrite(LCD_BL_CH, brightness);
  }
};

public:
  void setBrightness(uint8_t pct) override {
    if (pct > 100) pct = 100;

    static bool _ready = false;
    if (!_ready) {
      ledcSetup(LCD_BL_CH, 256, 8);
      ledcAttachPin(LCD_BL, LCD_BL_CH);
      _ready = true;
    }

    uint8_t brightness = (uint8_t)((uint32_t)pct * 255 / 100);
    ledcWrite(LCD_BL_CH, brightness);
  }

class NavigationImpl : public INavigation
{
public:
  void begin() override {
    pinMode(BTN_UP, INPUT_PULLUP);
    pinMode(BTN_B,  INPUT_PULLUP);
  }

  void update() override
  {
    bool btnUp   = (digitalRead(BTN_UP) == LOW);
    bool btnDown = (digitalRead(BTN_B)  == LOW);
    uint32_t now = millis();

    if (btnUp) {
      _waitDblClick = false;
      updateState(DIR_UP);
      return;
    }

    // Synthetic single-click: emit DIR_DOWN for one cycle then DIR_NONE
    if (_syntheticDown) {
      _syntheticDown = false;
      updateState(DIR_NONE);
      return;
    }

    if (btnDown && !_btnBWasDown) {
      _btnBWasDown = true;

      if (_waitDblClick && (now - _lastDownTime) <= DBL_CLICK_MS) {
        _waitDblClick = false;
        _heldDir = DIR_PRESS;
        updateState(DIR_PRESS);
      } else {
        _waitDblClick = true;
        _lastDownTime = now;
        _heldDir = DIR_NONE;
        updateState(DIR_NONE);
      }
    } else if (btnDown) {
      if (_waitDblClick

public:
  void begin() override {
    pinMode(BTN_UP, INPUT_PULLUP);
    pinMode(BTN_B,  INPUT_PULLUP);
  }

  void update() override
  {
    bool btnUp   = (digitalRead(BTN_UP) == LOW);
    bool btnDown = (digitalRead(BTN_B)  == LOW);
    uint32_t now = millis();

    if (btnUp) {
      _waitDblClick = false;
      updateState(DIR_UP);
      return;
    }

    // Synthetic single-click: emit DIR_DOWN for one cycle then DIR_NONE
    if (_syntheticDown) {
      _syntheticDown = false;
      updateState(DIR_NONE);
      return;
    }

    if (btnDown && !_btnBWasDown) {
      _btnBWasDown = true;

      if (_waitDblClick && (now - _lastDownTime) <= DBL_CLICK_MS) {
        _waitDblClick = false;
        _heldDir = DIR_PRESS;
        updateState(DIR_PRESS);
      } else {
        _waitDblClick = true;
        _lastDownTime = now;
        _heldDir = DIR_NONE;
        updateState(DIR_NONE);
      }
    } else if (btnDown) {
      if (_waitDblClick) {
        if ((now - _lastDownTime) > DBL_CLICK_MS) {
          _waitDblClick = false;
          _heldDir = DIR_DOWN;
          updateState(DIR_DOWN);

class PowerImpl : public IPower
{
public:
  void begin() override {
    pinMode(ADC_EN, OUTPUT);
    digitalWrite(ADC_EN, HIGH);
    pinMode(ANALOG_BAT_PIN, INPUT);
  }

  uint8_t getBatteryPercentage() override {
    float mv = (float)analogReadMilliVolts(ANALOG_BAT_PIN) * 2.0f;
    float pct = (mv - 3300.0f) / (4150.0f - 3350.0f) * 100.0f;
    if (pct < 0.0f)   pct = 0.0f;
    if (pct > 100.0f) pct = 100.0f;
    return (uint8_t)pct;
  }

  bool isCharging() override {
    return false;
  }

  void powerOff() override {
    esp_deep_sleep_start();
  }
};

public:
  void begin() override {
    pinMode(ADC_EN, OUTPUT);
    digitalWrite(ADC_EN, HIGH);
    pinMode(ANALOG_BAT_PIN, INPUT);
  }

  uint8_t getBatteryPercentage() override {
    float mv = (float)analogReadMilliVolts(ANALOG_BAT_PIN) * 2.0f;
    float pct = (mv - 3300.0f) / (4150.0f - 3350.0f) * 100.0f;
    if (pct < 0.0f)   pct = 0.0f;
    if (pct > 100.0f) pct = 100.0f;
    return (uint8_t)pct;
  }

  bool isCharging() override {
    return false;
  }

  void powerOff() override {
    esp_deep_sleep_start();
  }

Device* Device::createInstance() {
  pinMode(LCD_BL, OUTPUT);
  digitalWrite(LCD_BL, HIGH);
  const uint8_t share_spi_bus_devices_cs_pins[] = { NFC_CS, LORA_CS, SD_CS, LORA_RST };
  for (auto pin : share_spi_bus_devices_cs_pins) {
    pinMode(pin, OUTPUT);
    digitalWrite(pin, HIGH);
  }
  Wire.begin(GROVE_SDA, GROVE_SCL);  // I2C: keyboard, RTC, sensor, audio
  sharedSpi.begin(SPI_SCK_PIN, SPI_MISO_PIN, SPI_MOSI_PIN, -1);
  storageLFS.begin();
  storageSD.begin(SD_CS, sharedSpi);

  return new Device(display, power, &navigation, &keyboard,
                    &storageSD, &storageLFS, &sharedSpi, &speaker);
}

class DisplayImpl : public IDisplay
{
public:
  void setBrightness(uint8_t pct) override {
    if (pct > 100) pct = 100;

    static bool _ready = false;
    if (!_ready) {
      // GPIO42 backlight, ch7, 1kHz, 8-bit
      ledcSetup(7, 1000, 8);
      ledcAttachPin(LCD_BL, 7);
      _ready = true;
    }

    // Map 0-100% → 0-255
    ledcWrite(7, pct == 0 ? 0 : (uint8_t)((uint32_t)pct * 255 / 100));
  }
};

public:
  void setBrightness(uint8_t pct) override {
    if (pct > 100) pct = 100;

    static bool _ready = false;
    if (!_ready) {
      // GPIO42 backlight, ch7, 1kHz, 8-bit
      ledcSetup(7, 1000, 8);
      ledcAttachPin(LCD_BL, 7);
      _ready = true;
    }

    // Map 0-100% → 0-255
    ledcWrite(7, pct == 0 ? 0 : (uint8_t)((uint32_t)pct * 255 / 100));
  }

class KeyboardImpl : public IKeyboard, public Adafruit_TCA8418
{
public:
  void begin() override {
    Wire.begin(GROVE_SDA, GROVE_SCL);
    Wire.setClock(400000);

    if (!Adafruit_TCA8418::begin(TCA8418_DEFAULT_ADDR, &Wire)) return;

    this->matrix(KB_ROWS, KB_COLS);
    this->flush();

    pinMode(KB_BL, OUTPUT);
    analogWrite(KB_BL, 127);

    _fnPressed = false;
    _shiftHeld = false;
    _capsLock  = false;
    _key       = 0;
    _available = false;
  }

  void update() override {
    if (Adafruit_TCA8418::available() == 0) return;

    int raw = this->getEvent();
    if (raw == 0) return;

    bool pressed = (raw & 0x80) != 0;
    uint8_t k    = (raw & 0x7F) - 1;

    if (k / KB_COLS >= KB_ROWS) return;

    // ── special keys ──────────────────────────────────────
    if (k == KB_KEY_FN) {
      _fnPressed = pressed;
      return;
    }

    if (k == KB_KEY_SHIFT) {
      _shiftHeld = pressed;
      if (_fnPressed && pressed) _capsLock = !_capsLock;
      return;
    }

public:
  void begin() override {
    Wire.begin(GROVE_SDA, GROVE_SCL);
    Wire.setClock(400000);

    if (!Adafruit_TCA8418::begin(TCA8418_DEFAULT_ADDR, &Wire)) return;

    this->matrix(KB_ROWS, KB_COLS);
    this->flush();

    pinMode(KB_BL, OUTPUT);
    analogWrite(KB_BL, 127);

    _fnPressed = false;
    _shiftHeld = false;
    _capsLock  = false;
    _key       = 0;
    _available = false;
  }

  void update() override {
    if (Adafruit_TCA8418::available() == 0) return;

    int raw = this->getEvent();
    if (raw == 0) return;

    bool pressed = (raw & 0x80) != 0;
    uint8_t k    = (raw & 0x7F) - 1;

    if (k / KB_COLS >= KB_ROWS) return;

    // ── special keys ──────────────────────────────────────
    if (k == KB_KEY_FN) {
      _fnPressed = pressed;
      return;
    }

    if (k == KB_KEY_SHIFT) {
      _shiftHeld = pressed;
      if (_fnPressed && pressed) _capsLock = !_capsLock;
      return;
    }

    if (!pressed) return;

    // ── resolve character ──────────────────────────────────
    uint8_t row = k / KB_COLS;
    uint8_t col = k % KB_COLS;

    char c;
    if (_fnPressed)                  c = _kb_map[row][col].fn;
    else if (_shiftHeld ^ _capsLock) c = _kb_map[row][col].shifted;
    else                             c = _kb_map[row][col].normal;

    if (c == '\0') return;

    _key       = c;
    _available = true;
  }

  uint8_t modifiers() override {
    uint8_t m = MOD_NONE;
    if (_shiftHeld ^ _capsLock) m |= MOD_SHIFT;
    if (_fnPressed)             m |= MOD_FN;
    if (_capsLock)              m |= MOD_CAPS;
    return m;
  }

  char getKey() override {
    char k     = _key;
    _key       = 0;
    _available = false;
    return k;
  }

class NavigationImpl : public INavigation
{
public:
  NavigationImpl(IKeyboard* kb = nullptr) : _kb(kb) {}

  void begin() override;
  void update() override;

private:
  static constexpr unsigned long BTN_DEBOUNCE_MS = 150;
  static constexpr int           SCROLL_THRESH   = 2;

  RotaryEncoder* _encoder        = nullptr;
  IKeyboard*     _kb             = nullptr;
  int            _lastPos        = 0;
  int            _posDiff        = 0;

  // Button debounce
  bool          _btnRaw          = false;
  bool          _btnStable       = false;
  unsigned long _btnChangedAt    = 0;
};

void IRAM_ATTR checkPosition() {
  if (_encoderPtr) _encoderPtr->tick();
}

void NavigationImpl::begin() {
  pinMode(ROTARY_C, INPUT_PULLUP);

  _encoder    = new RotaryEncoder(ROTARY_A, ROTARY_B, RotaryEncoder::LatchMode::FOUR3);
  _encoderPtr = _encoder;

  attachInterrupt(digitalPinToInterrupt(ROTARY_A), checkPosition, CHANGE);
  attachInterrupt(digitalPinToInterrupt(ROTARY_B), checkPosition, CHANGE);

  _lastPos = 0;
  _posDiff = 0;
}

void NavigationImpl::update() {
  if (!suppressKeys() && _kb && _kb->available()) {
    char c = _kb->peekKey();
    if (c == '\b') { _kb->getKey(); updateState(DIR_BACK);  return; }
    if (c == '\n') { _kb->getKey(); updateState(DIR_PRESS); return; }
  }

  int newPos = _encoder->getPosition();
  if (newPos != _lastPos) {
    _posDiff += (newPos - _lastPos);
    _lastPos  = newPos;
  }

  // ── Button debounce ────────────────────────────────────────────────────────
  bool rawBtn = (digitalRead(ROTARY_C) == LOW);
  unsigned long now = millis();
  if (rawBtn != _btnRaw) {
    _btnRaw       = rawBtn;
    _btnChangedAt = now;
  }
  if (now - _btnChangedAt >= BTN_DEBOUNCE_MS) {
    _btnStable = _btnRaw;
  }

  // ── Direction ──────────────────────────────────────────────────────────────
  if (_btnStable) {
    updateState(DIR_PRESS);
  } else if (_posDiff <= -SCROLL_THRESH) {
    updateState(DIR_UP);
    _posDiff = 0;
  } else if (_posDiff >= SCROLL_THRESH) {
    updateState(DIR_DOWN);

class PowerImpl : public IPower
{
public:
  void begin() override
  {
    Wire.begin(GROVE_SDA, GROVE_SCL);
    Wire.setClock(400000);

    // reset to defaults + enable ADC continuous measure
    _writeReg(BQ25896_ADDR, 0x14, 0x80);
    delay(10);
    _writeReg(BQ25896_ADDR, 0x02, 0x1D);

    // charge target voltage 4288mV
    _writeReg(BQ25896_ADDR, 0x06, 0x70);

    // charge current 704mA
    _writeReg(BQ25896_ADDR, 0x04, 0x0B);
  }

  uint8_t getBatteryPercentage() override
  {
    uint16_t soc = _readReg16(BQ27220_ADDR, BQ27220_REG_SOC);
    if (soc > 100) soc = 100;
    return (uint8_t)soc;
  }

  bool isCharging() override
  {
    uint8_t status = _readReg8(BQ25896_ADDR, BQ25896_REG_STATUS);
    uint8_t chrg = (status >> 3) & 0x03;
    return (chrg == 0x01 || chrg == 0x02);
  }

  void powerOff() override
  {
    uint8_t val = _readReg8(BQ25896_ADDR, BQ25896_REG_PON);
    _writeReg(BQ25896_ADDR, BQ25896_REG_PON, val | 0x20);
  }

private:
  uint16_t _readReg16(uint8_t addr, u

public:
  void begin() override
  {
    Wire.begin(GROVE_SDA, GROVE_SCL);
    Wire.setClock(400000);

    // reset to defaults + enable ADC continuous measure
    _writeReg(BQ25896_ADDR, 0x14, 0x80);
    delay(10);
    _writeReg(BQ25896_ADDR, 0x02, 0x1D);

    // charge target voltage 4288mV
    _writeReg(BQ25896_ADDR, 0x06, 0x70);

    // charge current 704mA
    _writeReg(BQ25896_ADDR, 0x04, 0x0B);
  }

  uint8_t getBatteryPercentage() override
  {
    uint16_t soc = _readReg16(BQ27220_ADDR, BQ27220_REG_SOC);
    if (soc > 100) soc = 100;
    return (uint8_t)soc;
  }

  bool isCharging() override
  {
    uint8_t status = _readReg8(BQ25896_ADDR, BQ25896_REG_STATUS);
    uint8_t chrg = (status >> 3) & 0x03;
    return (chrg == 0x01 || chrg == 0x02);
  }

  void powerOff() override
  {
    uint8_t val = _readReg8(BQ25896_ADDR, BQ25896_REG_PON);
    _writeReg(BQ25896_ADDR, BQ25896_REG_PON, val | 0x20);
  }

private:
  uint16_t _readReg16(uint8_t addr, uint8_t reg)
  {
    Wire.beginTransmission(addr);
    Wire.write(reg);
    Wire.endTransmission(false);
    Wire.requestFrom((uint8_t)addr, (uint8_t)2);
    if (Wire.available() < 2) return 0;
    uint16_t lo = Wire.read();
    uint16_t hi = Wire.read();
    return (hi << 8) | lo;
  }

  uint8_t _readReg8(uint8_t addr, uint8_t reg)
  {
    Wire.beginTransmission(addr);
    Wire.write(reg);
    Wire.endTransmission(false);
    Wire.requestFrom((uint8_t)addr, (uint8_t)1);
    return Wire.available() ? Wire.read() : 0;
  }

  void _writeReg(uint8_t addr, uint8_t reg, uint8_t val)
  {
    Wire.beginTransmission(addr);
    Wire.write(reg);
    Wire.write(val);
    Wire.endTransmission();
  }

class SpeakerLoRa : public SpeakerI2S {
public:
  void begin() override {
    SpeakerI2S::begin();

    // Re-apply pin config with MCLK (T-Lora has dedicated MCLK output on GPIO 10)
    i2s_pin_config_t pins = {};
    pins.mck_io_num   = SPK_MCLK;
    pins.bck_io_num   = SPK_BCLK;
    pins.ws_io_num    = SPK_WCLK;
    pins.data_out_num = SPK_DOUT;
    pins.data_in_num  = I2S_PIN_NO_CHANGE;
    i2s_set_pin((i2s_port_t)SPK_I2S_PORT, &pins);

    delay(10);
    _initES8311();
    _enableAmp();
  }

private:
  static constexpr uint8_t _ES8311_ADDR = 0x18;
  static constexpr uint8_t _XL9555_ADDR = 0x20;

  void _writeReg(uint8_t addr, uint8_t reg, uint8_t val) {
    Wire.beginTransmission(addr);
    Wire.write(reg);
    Wire.write(val);
    Wire.endTransmission();
  }

  void _initES8311() {
    // Enhance I2C noise immunity (write twice per datasheet)
    _writeReg(_ES8311_ADDR, 0x44, 0x08);
    _writeReg(_ES8311_ADDR, 0x44, 0x08);

    // Clock and format setup
    _writeReg(_ES8311_ADD

public:
  void begin() override {
    SpeakerI2S::begin();

    // Re-apply pin config with MCLK (T-Lora has dedicated MCLK output on GPIO 10)
    i2s_pin_config_t pins = {};
    pins.mck_io_num   = SPK_MCLK;
    pins.bck_io_num   = SPK_BCLK;
    pins.ws_io_num    = SPK_WCLK;
    pins.data_out_num = SPK_DOUT;
    pins.data_in_num  = I2S_PIN_NO_CHANGE;
    i2s_set_pin((i2s_port_t)SPK_I2S_PORT, &pins);

    delay(10);
    _initES8311();
    _enableAmp();
  }

  void _writeReg(uint8_t addr, uint8_t reg, uint8_t val) {
    Wire.beginTransmission(addr);
    Wire.write(reg);
    Wire.write(val);
    Wire.endTransmission();
  }

  void _initES8311() {
    // Enhance I2C noise immunity (write twice per datasheet)
    _writeReg(_ES8311_ADDR, 0x44, 0x08);
    _writeReg(_ES8311_ADDR, 0x44, 0x08);

    // Clock and format setup
    _writeReg(_ES8311_ADDR, 0x01, 0x30);
    _writeReg(_ES8311_ADDR, 0x02, 0x00);
    _writeReg(_ES8311_ADDR, 0x03, 0x10);
    _writeReg(_ES8311_ADDR, 0x16, 0x24);  // ADC HPF
    _writeReg(_ES8311_ADDR, 0x04, 0x10);
    _writeReg(_ES8311_ADDR, 0x05, 0x00);
    _writeReg(_ES8311_ADDR, 0x0B, 0x00);
    _writeReg(_ES8311_ADDR, 0x0C, 0x00);
    _writeReg(_ES8311_ADDR, 0x10, 0x1F);
    _writeReg(_ES8311_ADDR, 0x11, 0x7F);

    // CSM Power ON — 0x80 = 0b10000000, bit 6 (master) already 0 = slave mode
    _writeReg(_ES8311_ADDR, 0x00, 0x80);

    // Use external MCLK
    _writeReg(_ES8311_ADDR, 0x01, 0x3F);

    // Power up analog circuitry + DAC
    _writeReg(_ES8311_ADDR, 0x0D, 0x01);  // power up analog
    _writeReg(_ES8311_ADDR, 0x12, 0x00);  // power-up DAC
    _writeReg(_ES8311_ADDR, 0x13

  void _enableAmp() {
    // Configure ONLY bit EXPANDS_AMP_EN as output — leave KB_RST and all other bits as inputs.
    // Setting all port 0 as output then writing only AMP_EN=1 would drive KB_RST=0,
    // resetting the TCA8418 keyboard and breaking Wire.requestFrom.
    _writeReg(_XL9555_ADDR, 0x06, ~(1u << EXPANDS_AMP_EN) & 0xFF);
    // Drive AMP_EN high to enable NS4150B amplifier
    _writeReg(_XL9555_ADDR, 0x02, 1u << EXPANDS_AMP_EN);
  }

static int max(int a, int b) {
    return (a > b) ? a : b;
}

static int abs(int value) {
    if (value < 0) { return -value; }
    return value;
}

static int8_t getAlphanumeric(char c) {

    if (c >= '0' && c <= '9') { return (c - '0'); }
    if (c >= 'A' && c <= 'Z') { return (c - 'A' + 10); }

    switch (c) {
        case ' ': return 36;
        case '$': return 37;
        case '%': return 38;
        case '*': return 39;
        case '+': return 40;
        case '-': return 41;
        case '.': return 42;
        case '/': return 43;
        case ':': return 44;
    }

    return -1;
}

static bool isAlphanumeric(const char *text, uint16_t length) {
    while (length != 0) {
        if (getAlphanumeric(text[--length]) == -1) { return false; }
    }
    return true;
}

static bool isNumeric(const char *text, uint16_t length) {
    while (length != 0) {
        char c = text[--length];
        if (c < '0' || c > '9') { return false; }
    }
    return true;
}