Codex added unified library, all work

.gitignore

@@ -3,6 +3,7 @@
 /*.log
 .pio/
 .pio
+**/.pio/
 .vscode/
 *.elf
 *.bin
@@ -27,3 +28,5 @@ exercises/18_GPS_Field_QA/lib/field_qa/BatteryMonitor.cpp
 exercises/18_GPS_Field_QA/lib/field_qa/BatteryMonitor.h
 exercises/AMY.log
 exercises/AMY_purged.log
+
+exercises/examples/*

lib/tbeam_clock/library.json

@@ -0,0 +1,7 @@
+{
+  "name": "tbeam_clock",
+  "version": "0.1.0",
+  "description": "Reusable PCF8563 RTC service and UTC formatting helpers for LilyGO T-Beam Supreme exercises.",
+  "frameworks": "arduino",
+  "platforms": "espressif32"
+}

lib/tbeam_clock/src/TBeamClock.cpp

@@ -0,0 +1,291 @@
+#include "TBeamClock.h"
+
+#ifndef OLED_SDA
+#define OLED_SDA 17
+#endif
+
+#ifndef OLED_SCL
+#define OLED_SCL 18
+#endif
+
+namespace tbeam {
+
+TBeamClock::TBeamClock(TwoWire& wire) : wire_(wire) {}
+
+bool TBeamClock::begin(const ClockConfig& config) {
+  config_ = config;
+  clearError();
+
+  if (config_.sda < 0) {
+    config_.sda = OLED_SDA;
+  }
+  if (config_.scl < 0) {
+    config_.scl = OLED_SCL;
+  }
+
+  if (config_.beginWire) {
+    wire_.begin(config_.sda, config_.scl);
+  }
+
+  DateTime dt{};
+  bool lowVoltage = false;
+  ready_ = readRtc(dt, lowVoltage);
+  if (!ready_) {
+    setError("RTC read failed");
+    valid_ = false;
+    return false;
+  }
+
+  lowVoltage_ = lowVoltage;
+  lastRtc_ = dt;
+  valid_ = !lowVoltage && isValidDateTime(dt);
+  lastEpoch_ = valid_ ? toEpochSeconds(dt) : 0;
+  if (lowVoltage) {
+    setError("RTC low-voltage flag set");
+  } else if (!valid_) {
+    setError("RTC date/time invalid");
+  }
+  return true;
+}
+
+void TBeamClock::update() {
+  DateTime dt{};
+  bool lowVoltage = false;
+  if (!readRtc(dt, lowVoltage)) {
+    ready_ = false;
+    valid_ = false;
+    setError("RTC read failed");
+    return;
+  }
+
+  ready_ = true;
+  lowVoltage_ = lowVoltage;
+  lastRtc_ = dt;
+  valid_ = !lowVoltage && isValidDateTime(dt);
+  lastEpoch_ = valid_ ? toEpochSeconds(dt) : 0;
+  if (valid_) {
+    clearError();
+  } else if (lowVoltage) {
+    setError("RTC low-voltage flag set");
+  } else {
+    setError("RTC date/time invalid");
+  }
+}
+
+bool TBeamClock::readRtc(DateTime& out, bool& lowVoltageFlag) const {
+  wire_.beginTransmission(config_.rtcAddress);
+  wire_.write(0x02);
+  if (wire_.endTransmission(false) != 0) {
+    return false;
+  }
+
+  const uint8_t need = 7;
+  const uint8_t got = wire_.requestFrom((int)config_.rtcAddress, (int)need);
+  if (got != need) {
+    return false;
+  }
+
+  const uint8_t sec = wire_.read();
+  const uint8_t min = wire_.read();
+  const uint8_t hour = wire_.read();
+  const uint8_t day = wire_.read();
+  const uint8_t weekday = wire_.read();
+  const uint8_t month = wire_.read();
+  const uint8_t year = wire_.read();
+
+  lowVoltageFlag = (sec & 0x80U) != 0;
+  out.second = fromBcd(sec & 0x7FU);
+  out.minute = fromBcd(min & 0x7FU);
+  out.hour = fromBcd(hour & 0x3FU);
+  out.day = fromBcd(day & 0x3FU);
+  out.weekday = fromBcd(weekday & 0x07U);
+  out.month = fromBcd(month & 0x1FU);
+  const uint8_t yy = fromBcd(year);
+  out.year = (month & 0x80U) ? (1900U + yy) : (2000U + yy);
+  return true;
+}
+
+bool TBeamClock::readValidRtc(DateTime& out, int64_t* epochOut) const {
+  bool lowVoltage = false;
+  if (!readRtc(out, lowVoltage) || lowVoltage || !isValidDateTime(out)) {
+    return false;
+  }
+  if (epochOut) {
+    *epochOut = toEpochSeconds(out);
+  }
+  return true;
+}
+
+bool TBeamClock::writeRtc(const DateTime& dt) const {
+  if (!isValidDateTime(dt)) {
+    return false;
+  }
+
+  wire_.beginTransmission(config_.rtcAddress);
+  wire_.write(0x02);
+  wire_.write(toBcd(dt.second) & 0x7FU);
+  wire_.write(toBcd(dt.minute) & 0x7FU);
+  wire_.write(toBcd(dt.hour) & 0x3FU);
+  wire_.write(toBcd(dt.day) & 0x3FU);
+  wire_.write(toBcd(dt.weekday) & 0x07U);
+
+  uint8_t monthReg = toBcd(dt.month) & 0x1FU;
+  if (dt.year < 2000U) {
+    monthReg |= 0x80U;
+  }
+  wire_.write(monthReg);
+  wire_.write(toBcd((uint8_t)(dt.year % 100U)));
+  return wire_.endTransmission() == 0;
+}
+
+bool TBeamClock::isValidDateTime(const DateTime& dt) {
+  if (dt.year < 2000U || dt.year > 2099U) return false;
+  if (dt.month < 1U || dt.month > 12U) return false;
+  if (dt.day < 1U || dt.day > daysInMonth(dt.year, dt.month)) return false;
+  if (dt.hour > 23U || dt.minute > 59U || dt.second > 59U) return false;
+  return true;
+}
+
+int64_t TBeamClock::toEpochSeconds(const DateTime& dt) {
+  const int64_t days = daysFromCivil((int)dt.year, dt.month, dt.day);
+  return days * 86400LL + (int64_t)dt.hour * 3600LL + (int64_t)dt.minute * 60LL + (int64_t)dt.second;
+}
+
+bool TBeamClock::fromEpochSeconds(int64_t seconds, DateTime& out) {
+  if (seconds < 0) {
+    return false;
+  }
+
+  int64_t days = seconds / 86400LL;
+  int64_t remainder = seconds % 86400LL;
+  if (remainder < 0) {
+    remainder += 86400LL;
+    days -= 1;
+  }
+
+  out.hour = (uint8_t)(remainder / 3600LL);
+  remainder %= 3600LL;
+  out.minute = (uint8_t)(remainder / 60LL);
+  out.second = (uint8_t)(remainder % 60LL);
+
+  days += 719468;
+  const int era = (days >= 0 ? days : days - 146096) / 146097;
+  const unsigned doe = (unsigned)(days - era * 146097);
+  const unsigned yoe = (doe - doe / 1460U + doe / 36524U - doe / 146096U) / 365U;
+  int year = (int)yoe + era * 400;
+  const unsigned doy = doe - (365U * yoe + yoe / 4U - yoe / 100U);
+  const unsigned mp = (5U * doy + 2U) / 153U;
+  const unsigned day = doy - (153U * mp + 2U) / 5U + 1U;
+  const unsigned month = mp + (mp < 10U ? 3U : (unsigned)-9);
+  year += (month <= 2U);
+
+  out.year = (uint16_t)year;
+  out.month = (uint8_t)month;
+  out.day = (uint8_t)day;
+  out.weekday = 0;
+  return isValidDateTime(out);
+}
+
+void TBeamClock::formatIsoUtc(const DateTime& dt, char* out, size_t outSize) {
+  snprintf(out,
+           outSize,
+           "%04u-%02u-%02uT%02u:%02u:%02uZ",
+           (unsigned)dt.year,
+           (unsigned)dt.month,
+           (unsigned)dt.day,
+           (unsigned)dt.hour,
+           (unsigned)dt.minute,
+           (unsigned)dt.second);
+}
+
+void TBeamClock::formatCompactUtc(const DateTime& dt, char* out, size_t outSize) {
+  snprintf(out,
+           outSize,
+           "%04u%02u%02u_%02u%02u%02u",
+           (unsigned)dt.year,
+           (unsigned)dt.month,
+           (unsigned)dt.day,
+           (unsigned)dt.hour,
+           (unsigned)dt.minute,
+           (unsigned)dt.second);
+}
+
+void TBeamClock::makeRunId(const DateTime& dt, const char* boardId, char* out, size_t outSize) {
+  snprintf(out,
+           outSize,
+           "%04u%02u%02u_%02u%02u%02u_%s",
+           (unsigned)dt.year,
+           (unsigned)dt.month,
+           (unsigned)dt.day,
+           (unsigned)dt.hour,
+           (unsigned)dt.minute,
+           (unsigned)dt.second,
+           boardId ? boardId : "NODE");
+}
+
+bool TBeamClock::parseDateTime(const char* text, DateTime& out) {
+  if (!text) {
+    return false;
+  }
+  int y = 0;
+  int mo = 0;
+  int d = 0;
+  int h = 0;
+  int mi = 0;
+  int s = 0;
+  if (sscanf(text, "%d-%d-%d %d:%d:%d", &y, &mo, &d, &h, &mi, &s) != 6 &&
+      sscanf(text, "%d-%d-%dT%d:%d:%d", &y, &mo, &d, &h, &mi, &s) != 6) {
+    return false;
+  }
+
+  out.year = (uint16_t)y;
+  out.month = (uint8_t)mo;
+  out.day = (uint8_t)d;
+  out.hour = (uint8_t)h;
+  out.minute = (uint8_t)mi;
+  out.second = (uint8_t)s;
+  out.weekday = 0;
+  return isValidDateTime(out);
+}
+
+uint8_t TBeamClock::toBcd(uint8_t value) {
+  return (uint8_t)(((value / 10U) << 4U) | (value % 10U));
+}
+
+uint8_t TBeamClock::fromBcd(uint8_t value) {
+  return (uint8_t)(((value >> 4U) * 10U) + (value & 0x0FU));
+}
+
+bool TBeamClock::isLeapYear(uint16_t year) {
+  return ((year % 4U) == 0U && (year % 100U) != 0U) || ((year % 400U) == 0U);
+}
+
+uint8_t TBeamClock::daysInMonth(uint16_t year, uint8_t month) {
+  static const uint8_t kDays[12] = {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
+  if (month == 2U) {
+    return (uint8_t)(isLeapYear(year) ? 29U : 28U);
+  }
+  if (month >= 1U && month <= 12U) {
+    return kDays[month - 1U];
+  }
+  return 0;
+}
+
+int64_t TBeamClock::daysFromCivil(int year, unsigned month, unsigned day) {
+  year -= (month <= 2U);
+  const int era = (year >= 0 ? year : year - 399) / 400;
+  const unsigned yoe = (unsigned)(year - era * 400);
+  const unsigned doy = (153U * (month + (month > 2U ? (unsigned)-3 : 9U)) + 2U) / 5U + day - 1U;
+  const unsigned doe = yoe * 365U + yoe / 4U - yoe / 100U + doy;
+  return era * 146097 + (int)doe - 719468;
+}
+
+void TBeamClock::setError(const char* message) const {
+  strlcpy(lastError_, message ? message : "", sizeof(lastError_));
+}
+
+void TBeamClock::clearError() const {
+  lastError_[0] = '\0';
+}
+
+}  // namespace tbeam

lib/tbeam_clock/src/TBeamClock.h

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <Arduino.h>
+#include <Wire.h>
+
+namespace tbeam {
+
+struct DateTime {
+  uint16_t year = 0;
+  uint8_t month = 0;
+  uint8_t day = 0;
+  uint8_t hour = 0;
+  uint8_t minute = 0;
+  uint8_t second = 0;
+  uint8_t weekday = 0;
+};
+
+struct ClockConfig {
+  uint8_t rtcAddress = 0x51;
+  int sda = -1;
+  int scl = -1;
+  bool beginWire = true;
+};
+
+class TBeamClock {
+ public:
+  explicit TBeamClock(TwoWire& wire = Wire1);
+
+  bool begin(const ClockConfig& config = ClockConfig{});
+  void update();
+
+  bool readRtc(DateTime& out, bool& lowVoltageFlag) const;
+  bool readValidRtc(DateTime& out, int64_t* epochOut = nullptr) const;
+  bool writeRtc(const DateTime& dt) const;
+
+  bool ready() const { return ready_; }
+  bool valid() const { return valid_; }
+  bool lowVoltage() const { return lowVoltage_; }
+  const DateTime& lastRtc() const { return lastRtc_; }
+  int64_t lastEpoch() const { return lastEpoch_; }
+  const char* lastError() const { return lastError_; }
+
+  static bool isValidDateTime(const DateTime& dt);
+  static int64_t toEpochSeconds(const DateTime& dt);
+  static bool fromEpochSeconds(int64_t seconds, DateTime& out);
+  static void formatIsoUtc(const DateTime& dt, char* out, size_t outSize);
+  static void formatCompactUtc(const DateTime& dt, char* out, size_t outSize);
+  static void makeRunId(const DateTime& dt, const char* boardId, char* out, size_t outSize);
+  static bool parseDateTime(const char* text, DateTime& out);
+
+ private:
+  static uint8_t toBcd(uint8_t value);
+  static uint8_t fromBcd(uint8_t value);
+  static bool isLeapYear(uint16_t year);
+  static uint8_t daysInMonth(uint16_t year, uint8_t month);
+  static int64_t daysFromCivil(int year, unsigned month, unsigned day);
+
+  void setError(const char* message) const;
+  void clearError() const;
+
+  TwoWire& wire_;
+  ClockConfig config_{};
+  bool ready_ = false;
+  bool valid_ = false;
+  bool lowVoltage_ = false;
+  DateTime lastRtc_{};
+  int64_t lastEpoch_ = 0;
+  mutable char lastError_[128] = {};
+};
+
+}  // namespace tbeam

lib/tbeam_display/library.json

@@ -0,0 +1,14 @@
+{
+  "name": "tbeam_display",
+  "version": "0.1.0",
+  "description": "Reusable SH1106 OLED display service for LilyGO T-Beam Supreme exercises.",
+  "frameworks": "arduino",
+  "platforms": "espressif32",
+  "dependencies": [
+    {
+      "name": "U8g2",
+      "owner": "olikraus",
+      "version": "^2.36.4"
+    }
+  ]
+}

lib/tbeam_display/src/TBeamDisplay.cpp

@@ -0,0 +1,204 @@
+#include "TBeamDisplay.h"
+
+#ifndef OLED_SDA
+#define OLED_SDA 17
+#endif
+
+#ifndef OLED_SCL
+#define OLED_SCL 18
+#endif
+
+#ifndef OLED_ADDR
+#define OLED_ADDR 0x3C
+#endif
+
+namespace tbeam {
+
+TBeamDisplay::TBeamDisplay(TwoWire& wire) : wire_(wire) {}
+
+bool TBeamDisplay::begin(const DisplayConfig& config) {
+  config_ = config;
+  clearError();
+
+  if (config_.sda < 0) {
+    config_.sda = OLED_SDA;
+  }
+  if (config_.scl < 0) {
+    config_.scl = OLED_SCL;
+  }
+  if (config_.address == 0) {
+    config_.address = OLED_ADDR;
+  }
+
+  if (config_.beginWire) {
+    wire_.begin(config_.sda, config_.scl);
+  }
+
+  oled_.setI2CAddress(config_.address << 1);
+  if (!oled_.begin()) {
+    ready_ = false;
+    setError("OLED begin failed");
+    return false;
+  }
+
+  ready_ = true;
+  setPowerSave(config_.powerSave);
+  setFont(DisplayFont::NORMAL);
+  clear();
+  return true;
+}
+
+void TBeamDisplay::update() {
+}
+
+void TBeamDisplay::clear() {
+  if (!ready_) {
+    return;
+  }
+  oled_.clearBuffer();
+  oled_.sendBuffer();
+}
+
+void TBeamDisplay::clearBuffer() {
+  for (uint8_t i = 0; i < kMaxLines; ++i) {
+    lines_[i][0] = '\0';
+  }
+}
+
+void TBeamDisplay::setPowerSave(bool enabled) {
+  if (!ready_) {
+    return;
+  }
+  oled_.setPowerSave(enabled ? 1 : 0);
+  powerSave_ = enabled;
+}
+
+void TBeamDisplay::setFont(DisplayFont font) {
+  font_ = font;
+  if (ready_) {
+    oled_.setFont(fontFor(font_));
+  }
+}
+
+void TBeamDisplay::showLines(const char* l1,
+                             const char* l2,
+                             const char* l3,
+                             const char* l4,
+                             const char* l5,
+                             const char* l6) {
+  setLine(0, l1);
+  setLine(1, l2);
+  setLine(2, l3);
+  setLine(3, l4);
+  setLine(4, l5);
+  setLine(5, l6);
+  renderLines();
+}
+
+void TBeamDisplay::setLine(uint8_t index, const char* text) {
+  if (index >= kMaxLines) {
+    return;
+  }
+  strlcpy(lines_[index], text ? text : "", sizeof(lines_[index]));
+}
+
+void TBeamDisplay::renderLines(uint8_t lineCount) {
+  if (!ready_) {
+    return;
+  }
+
+  if (lineCount > kMaxLines) {
+    lineCount = kMaxLines;
+  }
+
+  oled_.clearBuffer();
+  oled_.setFont(fontFor(font_));
+
+  uint8_t yStart = 12;
+  uint8_t yStep = 12;
+  if (font_ == DisplayFont::SMALL) {
+    yStart = 10;
+    yStep = 10;
+  } else if (font_ == DisplayFont::LARGE) {
+    yStart = 15;
+    yStep = 16;
+    if (lineCount > 4) {
+      lineCount = 4;
+    }
+  }
+
+  for (uint8_t i = 0; i < lineCount; ++i) {
+    if (lines_[i][0] == '\0') {
+      continue;
+    }
+    oled_.drawUTF8(0, yStart + (i * yStep), lines_[i]);
+  }
+  oled_.sendBuffer();
+}
+
+void TBeamDisplay::appendLine(const char* text) {
+  for (uint8_t i = 0; i < kMaxLines - 1; ++i) {
+    strlcpy(lines_[i], lines_[i + 1], sizeof(lines_[i]));
+  }
+  setLine(kMaxLines - 1, text);
+  renderLines();
+}
+
+void TBeamDisplay::showBoot(const char* title, const char* subtitle, const char* detail) {
+  setFont(DisplayFont::NORMAL);
+  showLines(title ? title : "T-Beam", subtitle, detail);
+}
+
+void TBeamDisplay::showStatus(const char* title, const char* left, const char* right, const char* footer) {
+  if (!ready_) {
+    return;
+  }
+
+  oled_.clearBuffer();
+  oled_.setFont(u8g2_font_6x10_tf);
+  if (title) {
+    oled_.drawUTF8(0, 10, title);
+  }
+  oled_.drawHLine(0, 13, 128);
+
+  oled_.setFont(u8g2_font_7x14B_tf);
+  if (left) {
+    oled_.drawUTF8(0, 34, left);
+  }
+  if (right) {
+    const int width = oled_.getUTF8Width(right);
+    int x = 128 - width;
+    if (x < 0) {
+      x = 0;
+    }
+    oled_.drawUTF8(x, 34, right);
+  }
+
+  oled_.setFont(u8g2_font_6x10_tf);
+  if (footer) {
+    oled_.drawUTF8(0, 60, footer);
+  }
+  oled_.sendBuffer();
+}
+
+void TBeamDisplay::setError(const char* message) {
+  strlcpy(lastError_, message ? message : "", sizeof(lastError_));
+}
+
+void TBeamDisplay::clearError() {
+  lastError_[0] = '\0';
+}
+
+const uint8_t* TBeamDisplay::fontFor(DisplayFont font) const {
+  switch (font) {
+    case DisplayFont::SMALL:
+      return u8g2_font_5x8_tf;
+    case DisplayFont::LARGE:
+      return u8g2_font_7x14B_tf;
+    case DisplayFont::NORMAL:
+    default:
+      return u8g2_font_6x10_tf;
+  }
+}
+
+}  // namespace tbeam

lib/tbeam_display/src/TBeamDisplay.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <Arduino.h>
+#include <U8g2lib.h>
+#include <Wire.h>
+
+namespace tbeam {
+
+struct DisplayConfig {
+  int sda = -1;
+  int scl = -1;
+  uint8_t address = 0x3C;
+  bool beginWire = true;
+  bool powerSave = false;
+};
+
+enum class DisplayFont : uint8_t {
+  SMALL = 0,
+  NORMAL,
+  LARGE
+};
+
+class TBeamDisplay {
+ public:
+  static constexpr uint8_t kMaxLines = 6;
+  static constexpr uint8_t kLineBytes = 32;
+
+  explicit TBeamDisplay(TwoWire& wire = Wire);
+
+  bool begin(const DisplayConfig& config = DisplayConfig{});
+  void update();
+
+  bool ready() const { return ready_; }
+  bool powerSave() const { return powerSave_; }
+  const char* lastError() const { return lastError_; }
+
+  void clear();
+  void clearBuffer();
+  void setPowerSave(bool enabled);
+  void setFont(DisplayFont font);
+  void showLines(const char* l1,
+                 const char* l2 = nullptr,
+                 const char* l3 = nullptr,
+                 const char* l4 = nullptr,
+                 const char* l5 = nullptr,
+                 const char* l6 = nullptr);
+  void setLine(uint8_t index, const char* text);
+  void renderLines(uint8_t lineCount = kMaxLines);
+  void appendLine(const char* text);
+  void showBoot(const char* title, const char* subtitle = nullptr, const char* detail = nullptr);
+  void showStatus(const char* title, const char* left, const char* right = nullptr, const char* footer = nullptr);
+
+  U8G2& raw() { return oled_; }
+
+ private:
+  void setError(const char* message);
+  void clearError();
+  const uint8_t* fontFor(DisplayFont font) const;
+
+  TwoWire& wire_;
+  DisplayConfig config_{};
+  U8G2_SH1106_128X64_NONAME_F_HW_I2C oled_{U8G2_R0, U8X8_PIN_NONE};
+  bool ready_ = false;
+  bool powerSave_ = false;
+  DisplayFont font_ = DisplayFont::NORMAL;
+  char lines_[kMaxLines][kLineBytes] = {};
+  char lastError_[96] = {};
+};
+
+}  // namespace tbeam

lib/tbeam_logger/library.json

@@ -0,0 +1,13 @@
+{
+  "name": "tbeam_logger",
+  "version": "0.1.0",
+  "description": "Print-compatible logger that tees Arduino output to Serial and TBeamStorage.",
+  "frameworks": "arduino",
+  "platforms": "espressif32",
+  "dependencies": [
+    {
+      "name": "tbeam_storage",
+      "version": "0.1.0"
+    }
+  ]
+}

lib/tbeam_logger/src/TBeamLogger.cpp

@@ -0,0 +1,78 @@
+#include "TBeamLogger.h"
+
+namespace tbeam {
+
+bool TBeamLogger::begin(Print& serial, TBeamStorage* storage, const LoggerConfig& config) {
+  serial_ = &serial;
+  storage_ = storage;
+  config_ = config;
+  lastFlushMs_ = millis();
+  return true;
+}
+
+void TBeamLogger::update() {
+  if (!config_.autoFlush || !storage_) {
+    return;
+  }
+  const uint32_t now = millis();
+  if ((uint32_t)(now - lastFlushMs_) >= config_.flushIntervalMs) {
+    storage_->flush();
+    lastFlushMs_ = now;
+  }
+}
+
+bool TBeamLogger::openLog(const char* path) {
+  return storage_ && storage_->openLog(path);
+}
+
+bool TBeamLogger::openUniqueLog(const char* prefix, const char* extension) {
+  if (!storage_) {
+    return false;
+  }
+  char path[128];
+  if (!storage_->makeUniqueLogPath(prefix, extension, path, sizeof(path))) {
+    return false;
+  }
+  return storage_->openLog(path);
+}
+
+const char* TBeamLogger::currentLogPath() const {
+  return storage_ ? storage_->currentLogPath() : "";
+}
+
+bool TBeamLogger::storageReady() const {
+  return storage_ && storage_->ready() && storage_->isLogOpen();
+}
+
+void TBeamLogger::flush() {
+  if (storage_) {
+    storage_->flush();
+  }
+  if (serial_) {
+    serial_->flush();
+  }
+}
+
+void TBeamLogger::closeLog() {
+  if (storage_) {
+    storage_->closeLog();
+  }
+}
+
+size_t TBeamLogger::write(uint8_t value) {
+  return write(&value, 1);
+}
+
+size_t TBeamLogger::write(const uint8_t* buffer, size_t size) {
+  size_t serialWrote = 0;
+  size_t storageWrote = 0;
+  if (config_.echoSerial && serial_) {
+    serialWrote = serial_->write(buffer, size);
+  }
+  if (config_.echoStorage && storage_ && storage_->isLogOpen()) {
+    storageWrote = storage_->write(buffer, size);
+  }
+  return storageWrote > 0 ? storageWrote : serialWrote;
+}
+
+}  // namespace tbeam

lib/tbeam_logger/src/TBeamLogger.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include <Arduino.h>
+#include <TBeamStorage.h>
+
+namespace tbeam {
+
+struct LoggerConfig {
+  bool echoSerial = true;
+  bool echoStorage = true;
+  bool autoFlush = true;
+  uint32_t flushIntervalMs = 2000;
+};
+
+class TBeamLogger : public Print {
+ public:
+  TBeamLogger() = default;
+
+  bool begin(Print& serial, TBeamStorage* storage = nullptr, const LoggerConfig& config = LoggerConfig{});
+  void update();
+
+  bool openLog(const char* path);
+  bool openUniqueLog(const char* prefix, const char* extension = ".log");
+  const char* currentLogPath() const;
+  bool storageReady() const;
+  void flush();
+  void closeLog();
+
+  size_t write(uint8_t value) override;
+  size_t write(const uint8_t* buffer, size_t size) override;
+
+ private:
+  Print* serial_ = nullptr;
+  TBeamStorage* storage_ = nullptr;
+  LoggerConfig config_{};
+  uint32_t lastFlushMs_ = 0;
+};
+
+}  // namespace tbeam

lib/tbeam_storage/library.json

@@ -0,0 +1,14 @@
+{
+  "name": "tbeam_storage",
+  "version": "0.1.0",
+  "description": "Reusable SD mount/watch and file storage service for LilyGO T-Beam Supreme exercises.",
+  "frameworks": "arduino",
+  "platforms": "espressif32",
+  "dependencies": [
+    {
+      "name": "XPowersLib",
+      "owner": "lewisxhe",
+      "version": "0.3.3"
+    }
+  ]
+}

lib/tbeam_storage/src/TBeamStorage.cpp

@@ -0,0 +1,526 @@
+#include "TBeamStorage.h"
+
+#include <stdarg.h>
+#include "driver/gpio.h"
+
+namespace tbeam {
+
+TBeamStorage::TBeamStorage(Print& diagnostic) : diagnostic_(diagnostic) {}
+
+bool TBeamStorage::begin(const StorageConfig& config, SdEventCallback callback) {
+  config_ = config;
+  callback_ = callback;
+  clearError();
+
+  forceSpiDeselected();
+  dumpSdPins("early");
+
+  if (!initPmuForSdPower()) {
+    setStateAbsent();
+    return false;
+  }
+
+  cycleSdRail(config_.recoveryRailOffMs, config_.recoveryRailOnSettleMs);
+  delay(config_.startupWarmupMs);
+
+  bool mounted = false;
+  for (uint8_t i = 0; i < 3; ++i) {
+    if (mountPreferred(false)) {
+      mounted = true;
+      break;
+    }
+    delay(200);
+  }
+
+  if (!mounted) {
+    logf("SD: preferred mount failed, trying full scan");
+    cycleSdRail(400, 1200);
+    delay(config_.startupWarmupMs);
+    mounted = mountCardFullScan();
+  }
+
+  if (mounted) {
+    setStateMounted();
+  } else {
+    setError("SD mount failed");
+    setStateAbsent();
+  }
+  return mounted;
+}
+
+void TBeamStorage::update() {
+  const uint32_t now = millis();
+  const uint32_t pollInterval =
+      (state_ == SdState::MOUNTED) ? config_.pollIntervalMountedMs : config_.pollIntervalAbsentMs;
+
+  if ((uint32_t)(now - lastPollMs_) < pollInterval) {
+    return;
+  }
+  lastPollMs_ = now;
+
+  if (state_ == SdState::MOUNTED) {
+    if (verifyMountedCard()) {
+      presentVotes_ = 0;
+      absentVotes_ = 0;
+      return;
+    }
+
+    if (mountPreferred(false) && verifyMountedCard()) {
+      presentVotes_ = 0;
+      absentVotes_ = 0;
+      return;
+    }
+
+    ++absentVotes_;
+    presentVotes_ = 0;
+    if (absentVotes_ >= config_.votesToAbsent) {
+      closeLog();
+      setError("SD removed or unreadable");
+      setStateAbsent();
+      absentVotes_ = 0;
+    }
+    return;
+  }
+
+  bool mounted = mountPreferred(false);
+  if (!mounted && (uint32_t)(now - lastFullScanMs_) >= config_.fullScanIntervalMs) {
+    lastFullScanMs_ = now;
+    if (config_.recoveryRailCycleOnFullScan) {
+      cycleSdRail(config_.recoveryRailOffMs, config_.recoveryRailOnSettleMs);
+      delay(150);
+    }
+    mounted = mountCardFullScan();
+  }
+
+  if (mounted) {
+    ++presentVotes_;
+    absentVotes_ = 0;
+    if (presentVotes_ >= config_.votesToPresent) {
+      clearError();
+      setStateMounted();
+      presentVotes_ = 0;
+    }
+  } else {
+    ++absentVotes_;
+    presentVotes_ = 0;
+    if (absentVotes_ >= config_.votesToAbsent) {
+      setStateAbsent();
+      absentVotes_ = 0;
+    }
+  }
+}
+
+bool TBeamStorage::consumeMountedEvent() {
+  const bool out = mountedEventPending_;
+  mountedEventPending_ = false;
+  return out;
+}
+
+bool TBeamStorage::consumeRemovedEvent() {
+  const bool out = removedEventPending_;
+  removedEventPending_ = false;
+  return out;
+}
+
+bool TBeamStorage::forceRemount() {
+  closeLog();
+  presentVotes_ = 0;
+  absentVotes_ = 0;
+  lastPollMs_ = 0;
+  lastFullScanMs_ = millis();
+
+  cycleSdRail(config_.recoveryRailOffMs, config_.recoveryRailOnSettleMs);
+  delay(config_.startupWarmupMs);
+
+  if (mountCardFullScan()) {
+    clearError();
+    setStateMounted();
+    return true;
+  }
+
+  setError("manual SD remount failed");
+  setStateAbsent();
+  return false;
+}
+
+bool TBeamStorage::ensureDirRecursive(const char* path) {
+  if (!ready() || !path || path[0] == '\0') {
+    setError("ensureDirRecursive invalid state");
+    return false;
+  }
+
+  char normalized[128];
+  if (!normalizePath(path, normalized, sizeof(normalized))) {
+    setError("directory path too long");
+    return false;
+  }
+
+  char partial[128] = "/";
+  const char* p = normalized + 1;
+  while (*p) {
+    const char* slash = strchr(p, '/');
+    const size_t len = slash ? (size_t)(slash - normalized) : strlen(normalized);
+    if (len >= sizeof(partial)) {
+      setError("directory path too long");
+      return false;
+    }
+    memcpy(partial, normalized, len);
+    partial[len] = '\0';
+    if (!SD.exists(partial) && !SD.mkdir(partial)) {
+      setError("SD.mkdir failed");
+      return false;
+    }
+    if (!slash) {
+      break;
+    }
+    p = slash + 1;
+  }
+  clearError();
+  return true;
+}
+
+bool TBeamStorage::makeUniqueLogPath(const char* prefix, const char* extension, char* out, size_t outSize) {
+  if (!out || outSize == 0) {
+    return false;
+  }
+  out[0] = '\0';
+  if (!ready() && !forceRemount()) {
+    return false;
+  }
+  if (!ensureDirRecursive(config_.logDir)) {
+    return false;
+  }
+
+  const char* safePrefix = (prefix && prefix[0]) ? prefix : "log";
+  const char* safeExt = (extension && extension[0]) ? extension : ".log";
+  char base[80];
+  snprintf(base, sizeof(base), "%s_%lu", safePrefix, (unsigned long)(millis() / 1000UL));
+
+  for (uint16_t suffix = 0; suffix < 1000; ++suffix) {
+    const int n = suffix == 0
+                      ? snprintf(out, outSize, "%s/%s%s", config_.logDir, base, safeExt)
+                      : snprintf(out, outSize, "%s/%s_%03u%s", config_.logDir, base, (unsigned)suffix, safeExt);
+    if (n < 0 || (size_t)n >= outSize) {
+      setError("log path buffer too small");
+      out[0] = '\0';
+      return false;
+    }
+    if (!SD.exists(out)) {
+      clearError();
+      return true;
+    }
+  }
+
+  setError("could not allocate unique log path");
+  out[0] = '\0';
+  return false;
+}
+
+bool TBeamStorage::openLog(const char* path) {
+  closeLog();
+  if (!ready() && !forceRemount()) {
+    return false;
+  }
+  if (!path || path[0] == '\0') {
+    setError("openLog missing path");
+    return false;
+  }
+
+  char normalized[sizeof(currentLogPath_)];
+  if (!normalizePath(path, normalized, sizeof(normalized))) {
+    setError("log path too long");
+    return false;
+  }
+
+  const char* slash = strrchr(normalized, '/');
+  if (slash && slash != normalized) {
+    char dir[sizeof(currentLogPath_)];
+    const size_t len = (size_t)(slash - normalized);
+    memcpy(dir, normalized, len);
+    dir[len] = '\0';
+    if (!ensureDirRecursive(dir)) {
+      return false;
+    }
+  }
+
+  logFile_ = SD.open(normalized, FILE_APPEND);
+  if (!logFile_) {
+    logFile_ = SD.open(normalized, FILE_WRITE);
+  }
+  if (!logFile_) {
+    setError("SD.open log failed");
+    return false;
+  }
+
+  strlcpy(currentLogPath_, normalized, sizeof(currentLogPath_));
+  clearError();
+  return true;
+}
+
+size_t TBeamStorage::write(const uint8_t* data, size_t len) {
+  if (!data || len == 0 || !logFile_) {
+    return 0;
+  }
+  const size_t wrote = logFile_.write(data, len);
+  if (wrote != len) {
+    setError("SD log write short");
+  }
+  return wrote;
+}
+
+size_t TBeamStorage::print(const char* text) {
+  if (!text) {
+    return 0;
+  }
+  return write((const uint8_t*)text, strlen(text));
+}
+
+size_t TBeamStorage::println(const char* text) {
+  size_t wrote = print(text);
+  static const char newline[] = "\n";
+  wrote += write((const uint8_t*)newline, 1);
+  return wrote;
+}
+
+bool TBeamStorage::flush() {
+  if (!logFile_) {
+    return false;
+  }
+  logFile_.flush();
+  return true;
+}
+
+void TBeamStorage::closeLog() {
+  if (logFile_) {
+    logFile_.flush();
+    logFile_.close();
+  }
+  currentLogPath_[0] = '\0';
+}
+
+void TBeamStorage::listFiles(Print& out, const char* path, uint8_t depth) {
+  if (!ready()) {
+    out.println("SD not mounted");
+    return;
+  }
+
+  char normalized[128];
+  if (!normalizePath(path ? path : "/", normalized, sizeof(normalized))) {
+    out.println("path too long");
+    return;
+  }
+
+  File root = SD.open(normalized, FILE_READ);
+  if (!root) {
+    out.printf("open failed: %s\r\n", normalized);
+    return;
+  }
+  if (!root.isDirectory()) {
+    out.printf("%s %lu\r\n", normalized, (unsigned long)root.size());
+    root.close();
+    return;
+  }
+  listFilesRecursive(out, root, normalized, depth);
+  root.close();
+}
+
+bool TBeamStorage::removeFile(const char* path) {
+  if (!ready()) {
+    setError("SD not mounted");
+    return false;
+  }
+
+  char normalized[128];
+  if (!normalizePath(path, normalized, sizeof(normalized))) {
+    setError("remove path invalid");
+    return false;
+  }
+  if (!SD.exists(normalized)) {
+    setError("remove path missing");
+    return false;
+  }
+  if (!SD.remove(normalized)) {
+    setError("SD.remove failed");
+    return false;
+  }
+  clearError();
+  return true;
+}
+
+void TBeamStorage::logf(const char* fmt, ...) {
+  char msg[196];
+  va_list args;
+  va_start(args, fmt);
+  vsnprintf(msg, sizeof(msg), fmt, args);
+  va_end(args);
+  diagnostic_.printf("[%10lu][storage:%06lu] %s\r\n",
+                     (unsigned long)millis(),
+                     (unsigned long)logSeq_++,
+                     msg);
+}
+
+void TBeamStorage::notify(SdEvent event, const char* message) {
+  if (callback_) {
+    callback_(event, message);
+  }
+}
+
+void TBeamStorage::setError(const char* message) {
+  strlcpy(lastError_, message ? message : "", sizeof(lastError_));
+}
+
+void TBeamStorage::clearError() {
+  lastError_[0] = '\0';
+}
+
+void TBeamStorage::forceSpiDeselected() {
+  pinMode(tbeam_supreme::sdCs(), OUTPUT);
+  digitalWrite(tbeam_supreme::sdCs(), HIGH);
+  pinMode(tbeam_supreme::imuCs(), OUTPUT);
+  digitalWrite(tbeam_supreme::imuCs(), HIGH);
+}
+
+void TBeamStorage::dumpSdPins(const char* tag) {
+  if (!config_.enablePinDumps) {
+    return;
+  }
+  const gpio_num_t cs = (gpio_num_t)tbeam_supreme::sdCs();
+  const gpio_num_t sck = (gpio_num_t)tbeam_supreme::sdSck();
+  const gpio_num_t miso = (gpio_num_t)tbeam_supreme::sdMiso();
+  const gpio_num_t mosi = (gpio_num_t)tbeam_supreme::sdMosi();
+  logf("PINS(%s): CS=%d SCK=%d MISO=%d MOSI=%d",
+       tag ? tag : "?",
+       gpio_get_level(cs),
+       gpio_get_level(sck),
+       gpio_get_level(miso),
+       gpio_get_level(mosi));
+}
+
+bool TBeamStorage::initPmuForSdPower() {
+  if (!tbeam_supreme::initPmuForPeripherals(pmu_, &diagnostic_)) {
+    setError("PMU init failed");
+    return false;
+  }
+  return true;
+}
+
+void TBeamStorage::cycleSdRail(uint32_t offMs, uint32_t onSettleMs) {
+  if (!config_.enableSdRailCycle || !pmu_) {
+    return;
+  }
+  forceSpiDeselected();
+  pmu_->disablePowerOutput(XPOWERS_BLDO1);
+  delay(offMs);
+  pmu_->setPowerChannelVoltage(XPOWERS_BLDO1, 3300);
+  pmu_->enablePowerOutput(XPOWERS_BLDO1);
+  delay(onSettleMs);
+}
+
+bool TBeamStorage::tryMountWithBus(SPIClass& bus, const char* busName, uint32_t hz, bool verbose) {
+  SD.end();
+  bus.end();
+  delay(10);
+  forceSpiDeselected();
+
+  bus.begin(tbeam_supreme::sdSck(), tbeam_supreme::sdMiso(), tbeam_supreme::sdMosi(), tbeam_supreme::sdCs());
+  digitalWrite(tbeam_supreme::sdCs(), HIGH);
+  delay(2);
+  for (uint8_t i = 0; i < 10; ++i) {
+    bus.transfer(0xFF);
+  }
+  delay(2);
+
+  if (verbose) {
+    logf("SD: trying bus=%s freq=%lu Hz", busName, (unsigned long)hz);
+  }
+
+  if (!SD.begin(tbeam_supreme::sdCs(), bus, hz)) {
+    return false;
+  }
+  if (SD.cardType() == CARD_NONE) {
+    SD.end();
+    return false;
+  }
+
+  sdSpi_ = &bus;
+  clearError();
+  return true;
+}
+
+bool TBeamStorage::mountPreferred(bool verbose) {
+  return tryMountWithBus(sdSpiH_, "HSPI", 400000, verbose);
+}
+
+bool TBeamStorage::mountCardFullScan() {
+  const uint32_t freqs[] = {400000, 1000000, 4000000, 10000000};
+  for (uint8_t i = 0; i < sizeof(freqs) / sizeof(freqs[0]); ++i) {
+    if (tryMountWithBus(sdSpiH_, "HSPI", freqs[i], true)) {
+      logf("SD: mounted on HSPI");
+      return true;
+    }
+  }
+  for (uint8_t i = 0; i < sizeof(freqs) / sizeof(freqs[0]); ++i) {
+    if (tryMountWithBus(sdSpiF_, "FSPI", freqs[i], true)) {
+      logf("SD: mounted on FSPI");
+      return true;
+    }
+  }
+  return false;
+}
+
+bool TBeamStorage::verifyMountedCard() {
+  if (SD.cardType() == CARD_NONE) {
+    return false;
+  }
+  File root = SD.open("/", FILE_READ);
+  const bool ok = root && root.isDirectory();
+  root.close();
+  return ok;
+}
+
+void TBeamStorage::setStateMounted() {
+  if (state_ != SdState::MOUNTED) {
+    logf("SD: mounted");
+    mountedEventPending_ = true;
+    notify(SdEvent::CARD_MOUNTED, "SD mounted");
+  }
+  state_ = SdState::MOUNTED;
+}
+
+void TBeamStorage::setStateAbsent() {
+  if (state_ == SdState::MOUNTED) {
+    removedEventPending_ = true;
+    notify(SdEvent::CARD_REMOVED, "SD removed");
+  } else if (state_ == SdState::UNKNOWN) {
+    notify(SdEvent::NO_CARD, "SD not mounted");
+  }
+  state_ = SdState::ABSENT;
+}
+
+void TBeamStorage::listFilesRecursive(Print& out, File& dir, const char* parentPath, uint8_t depth) {
+  File entry = dir.openNextFile();
+  while (entry) {
+    const char* name = entry.name();
+    if (entry.isDirectory()) {
+      out.printf("%s/\r\n", name);
+      if (depth > 0) {
+        listFilesRecursive(out, entry, name, depth - 1);
+      }
+    } else {
+      out.printf("%s %lu\r\n", name, (unsigned long)entry.size());
+    }
+    entry.close();
+    entry = dir.openNextFile();
+  }
+  (void)parentPath;
+}
+
+bool TBeamStorage::normalizePath(const char* input, char* out, size_t outSize) const {
+  if (!input || !out || outSize < 2) {
+    return false;
+  }
+  const int n = input[0] == '/' ? snprintf(out, outSize, "%s", input) : snprintf(out, outSize, "/%s", input);
+  return n > 0 && (size_t)n < outSize;
+}
+
+}  // namespace tbeam

lib/tbeam_storage/src/TBeamStorage.h

@@ -0,0 +1,114 @@
+#pragma once
+
+#include <Arduino.h>
+#include <SD.h>
+#include <SPI.h>
+#include <Wire.h>
+#include <XPowersLib.h>
+#include "tbeam_supreme_adapter.h"
+
+namespace tbeam {
+
+enum class SdState : uint8_t {
+  UNKNOWN = 0,
+  ABSENT,
+  MOUNTED
+};
+
+enum class SdEvent : uint8_t {
+  NO_CARD = 0,
+  CARD_MOUNTED,
+  CARD_REMOVED
+};
+
+using SdEventCallback = void (*)(SdEvent event, const char* message);
+
+struct StorageConfig {
+  const char* logDir = "/logs";
+  bool enableSdRailCycle = true;
+  bool enablePinDumps = false;
+  bool recoveryRailCycleOnFullScan = true;
+  uint32_t recoveryRailOffMs = 250;
+  uint32_t recoveryRailOnSettleMs = 700;
+  uint32_t startupWarmupMs = 1500;
+  uint32_t pollIntervalAbsentMs = 1000;
+  uint32_t pollIntervalMountedMs = 2000;
+  uint32_t fullScanIntervalMs = 10000;
+  uint32_t defaultFlushIntervalMs = 2000;
+  uint8_t votesToPresent = 2;
+  uint8_t votesToAbsent = 5;
+};
+
+class TBeamStorage {
+ public:
+  explicit TBeamStorage(Print& diagnostic = Serial);
+
+  bool begin(const StorageConfig& config = StorageConfig{}, SdEventCallback callback = nullptr);
+  void update();
+
+  bool ready() const { return state_ == SdState::MOUNTED; }
+  bool mounted() const { return ready(); }
+  SdState state() const { return state_; }
+  const char* lastError() const { return lastError_; }
+  const char* logDir() const { return config_.logDir; }
+
+  bool consumeMountedEvent();
+  bool consumeRemovedEvent();
+  bool forceRemount();
+
+  bool ensureDirRecursive(const char* path);
+  bool makeUniqueLogPath(const char* prefix, const char* extension, char* out, size_t outSize);
+  bool openLog(const char* path);
+  bool isLogOpen() const { return (bool)logFile_; }
+  const char* currentLogPath() const { return currentLogPath_; }
+  size_t write(const uint8_t* data, size_t len);
+  size_t print(const char* text);
+  size_t println(const char* text);
+  bool flush();
+  void closeLog();
+
+  void listFiles(Print& out, const char* path = "/", uint8_t depth = 4);
+  bool removeFile(const char* path);
+
+ private:
+  void logf(const char* fmt, ...);
+  void notify(SdEvent event, const char* message);
+  void setError(const char* message);
+  void clearError();
+  void forceSpiDeselected();
+  void dumpSdPins(const char* tag);
+  bool initPmuForSdPower();
+  void cycleSdRail(uint32_t offMs, uint32_t onSettleMs);
+  bool tryMountWithBus(SPIClass& bus, const char* busName, uint32_t hz, bool verbose);
+  bool mountPreferred(bool verbose);
+  bool mountCardFullScan();
+  bool verifyMountedCard();
+  void setStateMounted();
+  void setStateAbsent();
+  void listFilesRecursive(Print& out, File& dir, const char* parentPath, uint8_t depth);
+  bool normalizePath(const char* input, char* out, size_t outSize) const;
+
+  Print& diagnostic_;
+  StorageConfig config_{};
+  SdEventCallback callback_ = nullptr;
+
+  SPIClass sdSpiH_{HSPI};
+  SPIClass sdSpiF_{FSPI};
+  SPIClass* sdSpi_ = nullptr;
+  XPowersLibInterface* pmu_ = nullptr;
+
+  SdState state_ = SdState::UNKNOWN;
+  uint8_t presentVotes_ = 0;
+  uint8_t absentVotes_ = 0;
+  uint32_t lastPollMs_ = 0;
+  uint32_t lastFullScanMs_ = 0;
+  uint32_t logSeq_ = 0;
+  bool mountedEventPending_ = false;
+  bool removedEventPending_ = false;
+
+  File logFile_;
+  char currentLogPath_[128] = {};
+  char lastError_[160] = {};
+};
+
+}  // namespace tbeam

lib/tbeam_web/library.json

@@ -0,0 +1,13 @@
+{
+  "name": "tbeam_web",
+  "version": "0.1.0",
+  "description": "Reusable WiFi AP web file service for LilyGO T-Beam Supreme SD logs.",
+  "frameworks": "arduino",
+  "platforms": "espressif32",
+  "dependencies": [
+    {
+      "name": "tbeam_storage",
+      "version": "0.1.0"
+    }
+  ]
+}

lib/tbeam_web/src/TBeamWeb.cpp

@@ -0,0 +1,358 @@
+#include "TBeamWeb.h"
+
+#include <SD.h>
+#include <stdarg.h>
+
+namespace tbeam {
+
+TBeamWeb* TBeamWeb::active_ = nullptr;
+
+TBeamWeb::TBeamWeb(Print& diagnostic) : diagnostic_(diagnostic), server_(80) {}
+
+bool TBeamWeb::begin(TBeamStorage& storage, const WebConfig& config) {
+  storage_ = &storage;
+  config_ = config;
+  clearError();
+
+  snprintf(ssid_, sizeof(ssid_), "%s-%s", config_.ssidPrefix ? config_.ssidPrefix : "TBEAM", config_.boardId ? config_.boardId : "NODE");
+
+  WiFi.mode(WIFI_AP);
+  WiFi.setSleep(false);
+
+  ip_ = IPAddress(192, 168, config_.ipOctet, 1);
+  const IPAddress gateway(192, 168, config_.ipOctet, 1);
+  const IPAddress netmask(255, 255, 255, 0);
+  if (!WiFi.softAPConfig(ip_, gateway, netmask)) {
+    setError("WiFi softAPConfig failed");
+    return false;
+  }
+
+  bool apOk = false;
+  if (config_.password && strlen(config_.password) >= 8) {
+    apOk = WiFi.softAP(ssid_, config_.password);
+  } else {
+    apOk = WiFi.softAP(ssid_);
+  }
+  if (!apOk) {
+    setError("WiFi softAP failed");
+    return false;
+  }
+  ip_ = WiFi.softAPIP();
+
+  active_ = this;
+  server_.on("/", HTTP_GET, handleRootThunk);
+  server_.on("/status", HTTP_GET, handleStatusThunk);
+  server_.on("/files", HTTP_GET, handleFilesThunk);
+  server_.on("/download", HTTP_GET, handleDownloadThunk);
+  server_.on("/delete", HTTP_POST, handleDeleteThunk);
+  server_.onNotFound(handleNotFoundThunk);
+  server_.begin(config_.port);
+
+  ready_ = true;
+  logf("web: AP started ssid=%s ip=%s port=%u", ssid_, ip_.toString().c_str(), (unsigned)config_.port);
+  return true;
+}
+
+void TBeamWeb::update() {
+  if (ready_) {
+    server_.handleClient();
+  }
+}
+
+void TBeamWeb::stop() {
+  if (ready_) {
+    server_.stop();
+    WiFi.softAPdisconnect(true);
+  }
+  ready_ = false;
+}
+
+uint8_t TBeamWeb::stationCount() const {
+  return (uint8_t)WiFi.softAPgetStationNum();
+}
+
+void TBeamWeb::handleRootThunk() {
+  if (active_) active_->handleRoot();
+}
+
+void TBeamWeb::handleStatusThunk() {
+  if (active_) active_->handleStatus();
+}
+
+void TBeamWeb::handleFilesThunk() {
+  if (active_) active_->handleFiles();
+}
+
+void TBeamWeb::handleDownloadThunk() {
+  if (active_) active_->handleDownload();
+}
+
+void TBeamWeb::handleDeleteThunk() {
+  if (active_) active_->handleDelete();
+}
+
+void TBeamWeb::handleNotFoundThunk() {
+  if (active_) active_->handleNotFound();
+}
+
+void TBeamWeb::handleRoot() {
+  String body;
+  body.reserve(2048);
+  body += F("<!doctype html><html><head><meta charset='utf-8'>");
+  body += F("<meta name='viewport' content='width=device-width,initial-scale=1'>");
+  body += F("<title>T-Beam Files</title></head><body>");
+  body += F("<h1>T-Beam Files</h1>");
+  body += F("<p>SSID: ");
+  body += htmlEscape(ssid_);
+  body += F("</p><p>IP: ");
+  body += htmlEscape(ip_.toString());
+  body += F("</p><p>SD: ");
+  body += (storage_ && storage_->ready()) ? F("mounted") : F("not mounted");
+  body += F("</p><p>Stations: ");
+  body += String(stationCount());
+  body += F("</p><p><a href='/files?path=/logs'>Files</a> ");
+  body += F("<a href='/status'>Status</a></p>");
+  body += F("</body></html>");
+  server_.send(200, "text/html", body);
+}
+
+void TBeamWeb::handleStatus() {
+  String body;
+  body.reserve(512);
+  body += F("{\"ready\":");
+  body += ready_ ? F("true") : F("false");
+  body += F(",\"ssid\":\"");
+  body += htmlEscape(ssid_);
+  body += F("\",\"ip\":\"");
+  body += ip_.toString();
+  body += F("\",\"stations\":");
+  body += String(stationCount());
+  body += F(",\"sd_ready\":");
+  body += (storage_ && storage_->ready()) ? F("true") : F("false");
+  body += F("}");
+  server_.send(200, "application/json", body);
+}
+
+void TBeamWeb::handleFiles() {
+  if (!storage_ || !storage_->ready()) {
+    server_.send(503, "text/plain", "SD not mounted\n");
+    return;
+  }
+
+  char path[128];
+  const String requested = server_.hasArg("path") ? server_.arg("path") : String("/logs");
+  if (!normalizePath(requested, path, sizeof(path))) {
+    server_.send(400, "text/plain", "invalid path\n");
+    return;
+  }
+
+  String body;
+  body.reserve(8192);
+  body += F("<!doctype html><html><head><meta charset='utf-8'>");
+  body += F("<meta name='viewport' content='width=device-width,initial-scale=1'>");
+  body += F("<title>SD Files</title></head><body>");
+  body += F("<h1>SD Files</h1><p>Path: ");
+  body += htmlEscape(path);
+  body += F("</p><p><a href='/'>Home</a> <a href='/files?path=/'>Root</a> <a href='/files?path=/logs'>Logs</a></p><ul>");
+  listDirectoryHtml(body, path, 4);
+  body += F("</ul></body></html>");
+  server_.send(200, "text/html", body);
+}
+
+void TBeamWeb::handleDownload() {
+  if (!storage_ || !storage_->ready()) {
+    server_.send(503, "text/plain", "SD not mounted\n");
+    return;
+  }
+  if (!server_.hasArg("path")) {
+    server_.send(400, "text/plain", "missing path\n");
+    return;
+  }
+
+  char path[128];
+  if (!normalizePath(server_.arg("path"), path, sizeof(path))) {
+    server_.send(400, "text/plain", "invalid path\n");
+    return;
+  }
+
+  File file = SD.open(path, FILE_READ);
+  if (!file || file.isDirectory()) {
+    file.close();
+    server_.send(404, "text/plain", "file not found\n");
+    return;
+  }
+
+  String filename(path);
+  const int slash = filename.lastIndexOf('/');
+  if (slash >= 0) {
+    filename.remove(0, slash + 1);
+  }
+  server_.sendHeader("Content-Disposition", String("attachment; filename=\"") + filename + "\"");
+  server_.streamFile(file, contentTypeFor(path));
+  file.close();
+}
+
+void TBeamWeb::handleDelete() {
+  if (!config_.enableDelete) {
+    server_.send(403, "text/plain", "delete disabled\n");
+    return;
+  }
+  if (!storage_ || !storage_->ready()) {
+    server_.send(503, "text/plain", "SD not mounted\n");
+    return;
+  }
+  if (!server_.hasArg("path")) {
+    server_.send(400, "text/plain", "missing path\n");
+    return;
+  }
+
+  char path[128];
+  if (!normalizePath(server_.arg("path"), path, sizeof(path))) {
+    server_.send(400, "text/plain", "invalid path\n");
+    return;
+  }
+
+  if (!storage_->removeFile(path)) {
+    server_.send(500, "text/plain", String("delete failed: ") + storage_->lastError() + "\n");
+    return;
+  }
+  server_.sendHeader("Location", "/files?path=/logs");
+  server_.send(303, "text/plain", "deleted\n");
+}
+
+void TBeamWeb::handleNotFound() {
+  server_.send(404, "text/plain", "not found\n");
+}
+
+void TBeamWeb::listDirectoryHtml(String& body, const char* path, uint8_t depth) {
+  File dir = SD.open(path, FILE_READ);
+  if (!dir) {
+    body += F("<li>open failed</li>");
+    return;
+  }
+
+  if (!dir.isDirectory()) {
+    body += F("<li>");
+    body += htmlEscape(path);
+    body += F(" ");
+    body += String((unsigned long)dir.size());
+    body += F(" bytes <a href='/download?path=");
+    body += urlEncode(path);
+    body += F("'>download</a></li>");
+    dir.close();
+    return;
+  }
+
+  File entry = dir.openNextFile();
+  while (entry) {
+    const String name = entry.name();
+    const int slash = name.lastIndexOf('/');
+    const String displayName = slash >= 0 ? name.substring(slash + 1) : (name.length() ? name : String("(unnamed)"));
+    String childPath;
+    if (name.startsWith("/")) {
+      childPath = name;
+    } else if (strcmp(path, "/") == 0) {
+      childPath = String("/") + name;
+    } else {
+      childPath = String(path) + "/" + name;
+    }
+    body += F("<li>");
+    if (entry.isDirectory()) {
+      body += F("<a href='/files?path=");
+      body += urlEncode(childPath);
+      body += F("'>");
+      body += htmlEscape(displayName);
+      body += F("/</a>");
+      if (depth > 0) {
+        body += F("<ul>");
+        listDirectoryHtml(body, childPath.c_str(), depth - 1);
+        body += F("</ul>");
+      }
+    } else {
+      body += htmlEscape(displayName);
+      body += F(" ");
+      body += String((unsigned long)entry.size());
+      body += F(" bytes <a href='/download?path=");
+      body += urlEncode(childPath);
+      body += F("'>download</a>");
+      if (config_.enableDelete) {
+        body += F(" <form method='post' action='/delete' style='display:inline'>");
+        body += F("<input type='hidden' name='path' value='");
+        body += htmlEscape(childPath);
+        body += F("'><button type='submit'>delete</button></form>");
+      }
+    }
+    body += F("</li>");
+    entry.close();
+    entry = dir.openNextFile();
+  }
+  dir.close();
+}
+
+bool TBeamWeb::normalizePath(const String& input, char* out, size_t outSize) const {
+  if (!out || outSize < 2 || input.length() == 0 || input.indexOf("..") >= 0) {
+    return false;
+  }
+  const int n = input[0] == '/' ? snprintf(out, outSize, "%s", input.c_str()) : snprintf(out, outSize, "/%s", input.c_str());
+  return n > 0 && (size_t)n < outSize;
+}
+
+String TBeamWeb::htmlEscape(const String& in) const {
+  String out;
+  out.reserve(in.length() + 8);
+  for (size_t i = 0; i < in.length(); ++i) {
+    const char c = in[i];
+    if (c == '&') out += F("&amp;");
+    else if (c == '<') out += F("&lt;");
+    else if (c == '>') out += F("&gt;");
+    else if (c == '"') out += F("&quot;");
+    else if (c == '\'') out += F("&#39;");
+    else out += c;
+  }
+  return out;
+}
+
+String TBeamWeb::urlEncode(const String& in) const {
+  String out;
+  char hex[4];
+  for (size_t i = 0; i < in.length(); ++i) {
+    const unsigned char c = (unsigned char)in[i];
+    if (isalnum(c) || c == '-' || c == '_' || c == '.' || c == '/' || c == '~') {
+      out += (char)c;
+    } else {
+      snprintf(hex, sizeof(hex), "%%%02X", c);
+      out += hex;
+    }
+  }
+  return out;
+}
+
+String TBeamWeb::contentTypeFor(const String& path) const {
+  if (path.endsWith(".html")) return "text/html";
+  if (path.endsWith(".csv")) return "text/csv";
+  if (path.endsWith(".json")) return "application/json";
+  if (path.endsWith(".txt") || path.endsWith(".log")) return "text/plain";
+  return "application/octet-stream";
+}
+
+void TBeamWeb::setError(const char* message) {
+  strlcpy(lastError_, message ? message : "", sizeof(lastError_));
+}
+
+void TBeamWeb::clearError() {
+  lastError_[0] = '\0';
+}
+
+void TBeamWeb::logf(const char* fmt, ...) {
+  if (!config_.enableSerialLog) {
+    return;
+  }
+  char msg[196];
+  va_list args;
+  va_start(args, fmt);
+  vsnprintf(msg, sizeof(msg), fmt, args);
+  va_end(args);
+  diagnostic_.printf("[%10lu][web] %s\r\n", (unsigned long)millis(), msg);
+}
+
+}  // namespace tbeam

lib/tbeam_web/src/TBeamWeb.h

@@ -0,0 +1,69 @@
+#pragma once
+
+#include <Arduino.h>
+#include <WebServer.h>
+#include <WiFi.h>
+#include <TBeamStorage.h>
+
+namespace tbeam {
+
+struct WebConfig {
+  const char* ssidPrefix = "TBEAM";
+  const char* boardId = "NODE";
+  const char* password = nullptr;
+  uint8_t ipOctet = 25;
+  uint16_t port = 80;
+  bool enableDelete = true;
+  bool enableSerialLog = true;
+};
+
+class TBeamWeb {
+ public:
+  explicit TBeamWeb(Print& diagnostic = Serial);
+
+  bool begin(TBeamStorage& storage, const WebConfig& config = WebConfig{});
+  void update();
+  void stop();
+
+  bool ready() const { return ready_; }
+  const char* ssid() const { return ssid_; }
+  IPAddress ip() const { return ip_; }
+  const char* lastError() const { return lastError_; }
+  uint8_t stationCount() const;
+
+ private:
+  static TBeamWeb* active_;
+  static void handleRootThunk();
+  static void handleStatusThunk();
+  static void handleFilesThunk();
+  static void handleDownloadThunk();
+  static void handleDeleteThunk();
+  static void handleNotFoundThunk();
+
+  void handleRoot();
+  void handleStatus();
+  void handleFiles();
+  void handleDownload();
+  void handleDelete();
+  void handleNotFound();
+
+  void listDirectoryHtml(String& body, const char* path, uint8_t depth);
+  bool normalizePath(const String& input, char* out, size_t outSize) const;
+  String htmlEscape(const String& in) const;
+  String urlEncode(const String& in) const;
+  String contentTypeFor(const String& path) const;
+  void setError(const char* message);
+  void clearError();
+  void logf(const char* fmt, ...);
+
+  Print& diagnostic_;
+  WebServer server_;
+  TBeamStorage* storage_ = nullptr;
+  WebConfig config_{};
+  bool ready_ = false;
+  IPAddress ip_{0, 0, 0, 0};
+  char ssid_[40] = {};
+  char lastError_[128] = {};
+};
+
+}  // namespace tbeam

shared/platformio/tbeam_supreme_units.ini

@@ -0,0 +1,113 @@
+; Shared LilyGO T-Beam Supreme PlatformIO unit environments.
+;
+; Include from an exercise/test platformio.ini with:
+;   extra_configs = ../../shared/platformio/tbeam_supreme_units.ini
+;
+; Projects may extend [tbeam_supreme_common] and override/add build_flags for
+; exercise-specific sensors, libraries, and feature switches.
+
+[tbeam_supreme_common]
+platform = espressif32
+framework = arduino
+board = esp32-s3-devkitc-1
+board_build.partitions = default_8MB.csv
+monitor_speed = 115200
+lib_extra_dirs =
+  ../../lib
+lib_deps =
+  Wire
+  olikraus/U8g2@^2.36.4
+  lewisxhe/XPowersLib@0.3.3
+build_flags =
+  -I ../../shared/boards
+  -I ../../external/microReticulum_Firmware
+  -D BOARD_MODEL=BOARD_TBEAM_S_V1
+  -D OLED_SDA=17
+  -D OLED_SCL=18
+  -D OLED_ADDR=0x3C
+  -D GPS_RX_PIN=9
+  -D GPS_TX_PIN=8
+  -D GPS_WAKEUP_PIN=7
+  -D GPS_1PPS_PIN=6
+  -D GPS_L76K
+  -D NODE_SLOT_COUNT=7
+  -D ARDUINO_USB_MODE=1
+  -D ARDUINO_USB_CDC_ON_BOOT=1
+
+[env:amy]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"AMY\"
+  -D NODE_LABEL=\"Amy\"
+  -D NODE_SHORT=\"A\"
+  -D NODE_SLOT_INDEX=0
+  -D LOG_AP_IP_OCTET=23
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:bob]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"BOB\"
+  -D NODE_LABEL=\"Bob\"
+  -D NODE_SHORT=\"B\"
+  -D NODE_SLOT_INDEX=1
+  -D LOG_AP_IP_OCTET=24
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:cy]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"CY\"
+  -D NODE_LABEL=\"Cy\"
+  -D NODE_SHORT=\"C\"
+  -D NODE_SLOT_INDEX=2
+  -D LOG_AP_IP_OCTET=25
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:dan]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"DAN\"
+  -D NODE_LABEL=\"Dan\"
+  -D NODE_SHORT=\"D\"
+  -D NODE_SLOT_INDEX=3
+  -D LOG_AP_IP_OCTET=26
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:ed]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"ED\"
+  -D NODE_LABEL=\"Ed\"
+  -D NODE_SHORT=\"E\"
+  -D NODE_SLOT_INDEX=4
+  -D LOG_AP_IP_OCTET=27
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:flo]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"FLO\"
+  -D NODE_LABEL=\"Flo\"
+  -D NODE_SHORT=\"F\"
+  -D NODE_SLOT_INDEX=5
+  -D LOG_AP_IP_OCTET=28
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:guy]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D BOARD_ID=\"GUY\"
+  -D NODE_LABEL=\"Guy\"
+  -D NODE_SHORT=\"G\"
+  -D NODE_SLOT_INDEX=6
+  -D LOG_AP_IP_OCTET=29
+  -D GNSS_CHIP_NAME=\"MAX-M10S\"
+  -D GPS_UBLOX

tests/01_storage_logger/platformio.ini

@@ -0,0 +1,91 @@
+; Repository-level hardware test for tbeam_storage and tbeam_logger.
+
+[platformio]
+default_envs = cy
+extra_configs = ../../shared/platformio/tbeam_supreme_units.ini
+
+[storage_logger_base]
+extends = tbeam_supreme_common
+lib_deps =
+  ${tbeam_supreme_common.lib_deps}
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D STORAGE_LOGGER_TEST=1
+
+[env:amy]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"AMY\"
+  -D NODE_LABEL=\"Amy\"
+  -D NODE_SHORT=\"A\"
+  -D NODE_SLOT_INDEX=0
+  -D LOG_AP_IP_OCTET=23
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:bob]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"BOB\"
+  -D NODE_LABEL=\"Bob\"
+  -D NODE_SHORT=\"B\"
+  -D NODE_SLOT_INDEX=1
+  -D LOG_AP_IP_OCTET=24
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:cy]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"CY\"
+  -D NODE_LABEL=\"Cy\"
+  -D NODE_SHORT=\"C\"
+  -D NODE_SLOT_INDEX=2
+  -D LOG_AP_IP_OCTET=25
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:dan]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"DAN\"
+  -D NODE_LABEL=\"Dan\"
+  -D NODE_SHORT=\"D\"
+  -D NODE_SLOT_INDEX=3
+  -D LOG_AP_IP_OCTET=26
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:ed]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"ED\"
+  -D NODE_LABEL=\"Ed\"
+  -D NODE_SHORT=\"E\"
+  -D NODE_SLOT_INDEX=4
+  -D LOG_AP_IP_OCTET=27
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:flo]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"FLO\"
+  -D NODE_LABEL=\"Flo\"
+  -D NODE_SHORT=\"F\"
+  -D NODE_SLOT_INDEX=5
+  -D LOG_AP_IP_OCTET=28
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:guy]
+extends = storage_logger_base
+build_flags =
+  ${storage_logger_base.build_flags}
+  -D BOARD_ID=\"GUY\"
+  -D NODE_LABEL=\"Guy\"
+  -D NODE_SHORT=\"G\"
+  -D NODE_SLOT_INDEX=6
+  -D LOG_AP_IP_OCTET=29
+  -D GNSS_CHIP_NAME=\"MAX-M10S\"
+  -D GPS_UBLOX

tests/01_storage_logger/src/main.cpp

@@ -0,0 +1,87 @@
+#include <Arduino.h>
+#include <TBeamLogger.h>
+#include <TBeamStorage.h>
+
+#ifndef BOARD_ID
+#define BOARD_ID "UNKNOWN"
+#endif
+
+#ifndef NODE_LABEL
+#define NODE_LABEL "Unknown"
+#endif
+
+namespace {
+
+tbeam::TBeamStorage storage(Serial);
+tbeam::TBeamLogger Log;
+
+uint32_t sampleSeq = 0;
+uint32_t lastSampleMs = 0;
+
+void onStorageEvent(tbeam::SdEvent event, const char* message) {
+  const char* label = "unknown";
+  if (event == tbeam::SdEvent::NO_CARD) label = "no_card";
+  if (event == tbeam::SdEvent::CARD_MOUNTED) label = "mounted";
+  if (event == tbeam::SdEvent::CARD_REMOVED) label = "removed";
+  Serial.printf("[storage-event] %s: %s\r\n", label, message ? message : "");
+}
+
+}  // namespace
+
+void setup() {
+  Serial.begin(115200);
+  delay(1500);
+  Serial.println();
+  Serial.printf("storage_logger test boot board=%s label=%s\r\n", BOARD_ID, NODE_LABEL);
+
+  tbeam::StorageConfig storageConfig;
+  storageConfig.logDir = "/logs/storage_logger";
+  storageConfig.enablePinDumps = false;
+
+  const bool mounted = storage.begin(storageConfig, onStorageEvent);
+  Log.begin(Serial, &storage);
+
+  if (mounted && Log.openUniqueLog(BOARD_ID, ".csv")) {
+    Log.printf("# test: storage_logger\r\n");
+    Log.printf("# board_id: %s\r\n", BOARD_ID);
+    Log.printf("# node_label: %s\r\n", NODE_LABEL);
+    Log.printf("# log_path: %s\r\n", Log.currentLogPath());
+    Log.println("seq,millis,sd_ready,free_heap");
+    Log.flush();
+    Serial.printf("Log opened: %s\r\n", Log.currentLogPath());
+  } else {
+    Serial.printf("Log open skipped: mounted=%s error=%s\r\n",
+                  mounted ? "yes" : "no",
+                  storage.lastError());
+  }
+
+  Serial.println("Initial SD listing:");
+  storage.listFiles(Serial, "/logs", 3);
+}
+
+void loop() {
+  storage.update();
+  Log.update();
+
+  if (storage.consumeMountedEvent() && !Log.storageReady()) {
+    if (Log.openUniqueLog(BOARD_ID, ".csv")) {
+      Log.println("seq,millis,sd_ready,free_heap");
+      Log.flush();
+      Serial.printf("Log reopened: %s\r\n", Log.currentLogPath());
+    }
+  }
+
+  if (storage.consumeRemovedEvent()) {
+    Serial.println("SD removed; continuing Serial-only logging");
+  }
+
+  const uint32_t now = millis();
+  if ((uint32_t)(now - lastSampleMs) >= 1000) {
+    lastSampleMs = now;
+    Log.printf("%lu,%lu,%s,%lu\r\n",
+               (unsigned long)sampleSeq++,
+               (unsigned long)now,
+               storage.ready() ? "yes" : "no",
+               (unsigned long)ESP.getFreeHeap());
+  }
+}

tests/02_clock/platformio.ini

@@ -0,0 +1,92 @@
+; Repository-level hardware test for tbeam_clock.
+
+[platformio]
+default_envs = cy
+extra_configs = ../../shared/platformio/tbeam_supreme_units.ini
+
+[clock_test_base]
+extends = tbeam_supreme_common
+lib_deps =
+  ${tbeam_supreme_common.lib_deps}
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D CLOCK_TEST=1
+  ;-D CLOCK_TEST_ALLOW_SET=1
+
+[env:amy]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"AMY\"
+  -D NODE_LABEL=\"Amy\"
+  -D NODE_SHORT=\"A\"
+  -D NODE_SLOT_INDEX=0
+  -D LOG_AP_IP_OCTET=23
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:bob]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"BOB\"
+  -D NODE_LABEL=\"Bob\"
+  -D NODE_SHORT=\"B\"
+  -D NODE_SLOT_INDEX=1
+  -D LOG_AP_IP_OCTET=24
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:cy]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"CY\"
+  -D NODE_LABEL=\"Cy\"
+  -D NODE_SHORT=\"C\"
+  -D NODE_SLOT_INDEX=2
+  -D LOG_AP_IP_OCTET=25
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:dan]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"DAN\"
+  -D NODE_LABEL=\"Dan\"
+  -D NODE_SHORT=\"D\"
+  -D NODE_SLOT_INDEX=3
+  -D LOG_AP_IP_OCTET=26
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:ed]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"ED\"
+  -D NODE_LABEL=\"Ed\"
+  -D NODE_SHORT=\"E\"
+  -D NODE_SLOT_INDEX=4
+  -D LOG_AP_IP_OCTET=27
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:flo]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"FLO\"
+  -D NODE_LABEL=\"Flo\"
+  -D NODE_SHORT=\"F\"
+  -D NODE_SLOT_INDEX=5
+  -D LOG_AP_IP_OCTET=28
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:guy]
+extends = clock_test_base
+build_flags =
+  ${clock_test_base.build_flags}
+  -D BOARD_ID=\"GUY\"
+  -D NODE_LABEL=\"Guy\"
+  -D NODE_SHORT=\"G\"
+  -D NODE_SLOT_INDEX=6
+  -D LOG_AP_IP_OCTET=29
+  -D GNSS_CHIP_NAME=\"MAX-M10S\"
+  -D GPS_UBLOX

tests/02_clock/src/main.cpp

@@ -0,0 +1,201 @@
+#include <Arduino.h>
+#include <TBeamClock.h>
+#include <TBeamLogger.h>
+#include <TBeamStorage.h>
+#include "tbeam_supreme_adapter.h"
+
+#ifndef BOARD_ID
+#define BOARD_ID "UNKNOWN"
+#endif
+
+#ifndef NODE_LABEL
+#define NODE_LABEL "Unknown"
+#endif
+
+#ifndef CLOCK_TEST_ALLOW_SET
+#define CLOCK_TEST_ALLOW_SET 0
+#endif
+
+namespace {
+
+tbeam::TBeamClock clockService(Wire1);
+tbeam::TBeamStorage storage(Serial);
+tbeam::TBeamLogger Log;
+
+XPowersLibInterface* pmu = nullptr;
+String commandBuffer;
+bool lastWasCr = false;
+uint32_t sampleSeq = 0;
+uint32_t lastSampleMs = 0;
+
+void printDateTime(Print& out, const tbeam::DateTime& dt) {
+  char iso[32];
+  tbeam::TBeamClock::formatIsoUtc(dt, iso, sizeof(iso));
+  out.print(iso);
+}
+
+void printHelp() {
+  Serial.println("Commands:");
+  Serial.println("  help");
+  Serial.println("  show");
+#if CLOCK_TEST_ALLOW_SET
+  Serial.println("  set YYYY-MM-DD HH:MM:SS");
+#else
+  Serial.println("  set disabled; build with CLOCK_TEST_ALLOW_SET=1 to enable writes");
+#endif
+}
+
+void showClock() {
+  clockService.update();
+  Serial.printf("rtc_ready=%s valid=%s low_voltage=%s error=%s\r\n",
+                clockService.ready() ? "yes" : "no",
+                clockService.valid() ? "yes" : "no",
+                clockService.lowVoltage() ? "yes" : "no",
+                clockService.lastError());
+  Serial.print("rtc_utc=");
+  printDateTime(Serial, clockService.lastRtc());
+  Serial.printf(" epoch=%lld\r\n", (long long)clockService.lastEpoch());
+}
+
+void handleCommand(const String& raw) {
+  String line = raw;
+  line.trim();
+  if (line.length() == 0) {
+    return;
+  }
+
+  if (line == "help") {
+    printHelp();
+    return;
+  }
+  if (line == "show") {
+    showClock();
+    return;
+  }
+  if (line.startsWith("set ")) {
+#if CLOCK_TEST_ALLOW_SET
+    tbeam::DateTime dt{};
+    if (!tbeam::TBeamClock::parseDateTime(line.c_str() + 4, dt)) {
+      Serial.println("set parse failed");
+      return;
+    }
+    if (!clockService.writeRtc(dt)) {
+      Serial.println("RTC write failed");
+      return;
+    }
+    Serial.println("RTC write succeeded");
+    showClock();
+#else
+    Serial.println("RTC set disabled in this build");
+#endif
+    return;
+  }
+
+  Serial.printf("Unknown command: %s\r\n", line.c_str());
+}
+
+void pollSerialCommands() {
+  while (Serial.available() > 0) {
+    const char c = (char)Serial.read();
+    if (c == '\r' || c == '\n') {
+      if ((c == '\n' && lastWasCr) || (c == '\r' && !lastWasCr && commandBuffer.length() == 0)) {
+        lastWasCr = (c == '\r');
+        continue;
+      }
+      handleCommand(commandBuffer);
+      commandBuffer = "";
+      lastWasCr = (c == '\r');
+    } else {
+      lastWasCr = false;
+      commandBuffer += c;
+      if (commandBuffer.length() > 120) {
+        commandBuffer = "";
+        Serial.println("Input line too long; buffer cleared");
+      }
+    }
+  }
+}
+
+void openClockLog() {
+  if (!storage.ready()) {
+    Serial.printf("Clock log skipped: storage error=%s\r\n", storage.lastError());
+    return;
+  }
+
+  bool opened = false;
+  if (clockService.valid()) {
+    char runId[64];
+    char path[112];
+    tbeam::TBeamClock::makeRunId(clockService.lastRtc(), BOARD_ID, runId, sizeof(runId));
+    snprintf(path, sizeof(path), "%s/%s.csv", storage.logDir(), runId);
+    opened = Log.openLog(path);
+  }
+  if (!opened) {
+    opened = Log.openUniqueLog(BOARD_ID, ".csv");
+  }
+
+  if (!opened) {
+    Serial.printf("Clock log open failed: %s\r\n", storage.lastError());
+    return;
+  }
+
+  Log.printf("# test: clock\r\n");
+  Log.printf("# board_id: %s\r\n", BOARD_ID);
+  Log.printf("# node_label: %s\r\n", NODE_LABEL);
+  Log.printf("# log_path: %s\r\n", Log.currentLogPath());
+  Log.printf("# rtc_valid_at_boot: %s\r\n", clockService.valid() ? "yes" : "no");
+  Log.println("seq,millis,rtc_ready,rtc_valid,low_voltage,epoch,iso_utc,free_heap");
+  Log.flush();
+  Serial.printf("Clock log opened: %s\r\n", Log.currentLogPath());
+}
+
+}  // namespace
+
+void setup() {
+  Serial.begin(115200);
+  delay(1500);
+  Serial.println();
+  Serial.printf("clock test boot board=%s label=%s\r\n", BOARD_ID, NODE_LABEL);
+
+  if (!tbeam_supreme::initPmuForPeripherals(pmu, &Serial)) {
+    Serial.println("PMU init failed; RTC read may fail");
+  }
+
+  tbeam::StorageConfig storageConfig;
+  storageConfig.logDir = "/logs/clock";
+  storageConfig.enablePinDumps = false;
+  storage.begin(storageConfig);
+  Log.begin(Serial, &storage);
+
+  clockService.begin();
+  showClock();
+  openClockLog();
+  printHelp();
+}
+
+void loop() {
+  pollSerialCommands();
+  storage.update();
+  Log.update();
+
+  const uint32_t now = millis();
+  if ((uint32_t)(now - lastSampleMs) >= 1000) {
+    lastSampleMs = now;
+    clockService.update();
+
+    char iso[32] = "";
+    if (clockService.ready()) {
+      tbeam::TBeamClock::formatIsoUtc(clockService.lastRtc(), iso, sizeof(iso));
+    }
+
+    Log.printf("%lu,%lu,%s,%s,%s,%lld,%s,%lu\r\n",
+               (unsigned long)sampleSeq++,
+               (unsigned long)now,
+               clockService.ready() ? "yes" : "no",
+               clockService.valid() ? "yes" : "no",
+               clockService.lowVoltage() ? "yes" : "no",
+               (long long)clockService.lastEpoch(),
+               iso,
+               (unsigned long)ESP.getFreeHeap());
+  }
+}

tests/03_display/platformio.ini

@@ -0,0 +1,92 @@
+; Repository-level hardware test for tbeam_display.
+
+[platformio]
+default_envs = cy
+extra_configs = ../../shared/platformio/tbeam_supreme_units.ini
+
+[display_test_base]
+extends = tbeam_supreme_common
+lib_deps =
+  ${tbeam_supreme_common.lib_deps}
+  olikraus/U8g2@^2.36.4
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D DISPLAY_TEST=1
+
+[env:amy]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"AMY\"
+  -D NODE_LABEL=\"Amy\"
+  -D NODE_SHORT=\"A\"
+  -D NODE_SLOT_INDEX=0
+  -D LOG_AP_IP_OCTET=23
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:bob]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"BOB\"
+  -D NODE_LABEL=\"Bob\"
+  -D NODE_SHORT=\"B\"
+  -D NODE_SLOT_INDEX=1
+  -D LOG_AP_IP_OCTET=24
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:cy]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"CY\"
+  -D NODE_LABEL=\"Cy\"
+  -D NODE_SHORT=\"C\"
+  -D NODE_SLOT_INDEX=2
+  -D LOG_AP_IP_OCTET=25
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:dan]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"DAN\"
+  -D NODE_LABEL=\"Dan\"
+  -D NODE_SHORT=\"D\"
+  -D NODE_SLOT_INDEX=3
+  -D LOG_AP_IP_OCTET=26
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:ed]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"ED\"
+  -D NODE_LABEL=\"Ed\"
+  -D NODE_SHORT=\"E\"
+  -D NODE_SLOT_INDEX=4
+  -D LOG_AP_IP_OCTET=27
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:flo]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"FLO\"
+  -D NODE_LABEL=\"Flo\"
+  -D NODE_SHORT=\"F\"
+  -D NODE_SLOT_INDEX=5
+  -D LOG_AP_IP_OCTET=28
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:guy]
+extends = display_test_base
+build_flags =
+  ${display_test_base.build_flags}
+  -D BOARD_ID=\"GUY\"
+  -D NODE_LABEL=\"Guy\"
+  -D NODE_SHORT=\"G\"
+  -D NODE_SLOT_INDEX=6
+  -D LOG_AP_IP_OCTET=29
+  -D GNSS_CHIP_NAME=\"MAX-M10S\"
+  -D GPS_UBLOX

tests/03_display/src/main.cpp

@@ -0,0 +1,154 @@
+#include <Arduino.h>
+#include <TBeamClock.h>
+#include <TBeamDisplay.h>
+#include <TBeamLogger.h>
+#include <TBeamStorage.h>
+
+#ifndef BOARD_ID
+#define BOARD_ID "UNKNOWN"
+#endif
+
+#ifndef NODE_LABEL
+#define NODE_LABEL "Unknown"
+#endif
+
+namespace {
+
+tbeam::TBeamDisplay display;
+tbeam::TBeamClock clockService(Wire1);
+tbeam::TBeamStorage storage(Serial);
+tbeam::TBeamLogger Log;
+
+uint32_t sampleSeq = 0;
+uint32_t lastSampleMs = 0;
+uint32_t lastPageMs = 0;
+uint8_t page = 0;
+
+void formatRtc(char* out, size_t outSize) {
+  if (!clockService.ready()) {
+    strlcpy(out, "RTC read fail", outSize);
+    return;
+  }
+  if (!clockService.valid()) {
+    strlcpy(out, clockService.lowVoltage() ? "RTC low voltage" : "RTC invalid", outSize);
+    return;
+  }
+  tbeam::TBeamClock::formatIsoUtc(clockService.lastRtc(), out, outSize);
+}
+
+void openDisplayLog() {
+  if (!storage.ready()) {
+    Serial.printf("Display log skipped: storage error=%s\r\n", storage.lastError());
+    return;
+  }
+
+  bool opened = false;
+  if (clockService.valid()) {
+    char runId[64];
+    char path[112];
+    tbeam::TBeamClock::makeRunId(clockService.lastRtc(), BOARD_ID, runId, sizeof(runId));
+    snprintf(path, sizeof(path), "%s/%s.csv", storage.logDir(), runId);
+    opened = Log.openLog(path);
+  }
+  if (!opened) {
+    opened = Log.openUniqueLog(BOARD_ID, ".csv");
+  }
+  if (!opened) {
+    Serial.printf("Display log open failed: %s\r\n", storage.lastError());
+    return;
+  }
+
+  Log.printf("# test: display\r\n");
+  Log.printf("# board_id: %s\r\n", BOARD_ID);
+  Log.printf("# node_label: %s\r\n", NODE_LABEL);
+  Log.printf("# log_path: %s\r\n", Log.currentLogPath());
+  Log.println("seq,millis,page,display_ready,rtc_valid,sd_ready,free_heap");
+  Log.flush();
+  Serial.printf("Display log opened: %s\r\n", Log.currentLogPath());
+}
+
+void drawCurrentPage() {
+  char line1[32];
+  char line2[32];
+  char line3[32];
+  char line4[32];
+  char line5[32];
+  char rtc[32];
+
+  formatRtc(rtc, sizeof(rtc));
+
+  if (page == 0) {
+    snprintf(line1, sizeof(line1), "Display Test");
+    snprintf(line2, sizeof(line2), "Board: %s", BOARD_ID);
+    snprintf(line3, sizeof(line3), "Node: %s", NODE_LABEL);
+    snprintf(line4, sizeof(line4), "OLED: %s", display.ready() ? "ready" : "fail");
+    snprintf(line5, sizeof(line5), "Seq: %lu", (unsigned long)sampleSeq);
+    display.showLines(line1, line2, line3, line4, line5);
+  } else if (page == 1) {
+    display.showStatus("Clock", rtc, clockService.valid() ? "OK" : "BAD", storage.ready() ? "SD mounted" : "SD missing");
+  } else if (page == 2) {
+    snprintf(line1, sizeof(line1), "Storage");
+    snprintf(line2, sizeof(line2), "SD: %s", storage.ready() ? "mounted" : "missing");
+    snprintf(line3, sizeof(line3), "Log: %s", Log.storageReady() ? "open" : "closed");
+    snprintf(line4, sizeof(line4), "Heap: %lu", (unsigned long)ESP.getFreeHeap());
+    snprintf(line5, sizeof(line5), "Millis: %lu", (unsigned long)millis());
+    display.showLines(line1, line2, line3, line4, line5);
+  } else {
+    display.setFont(tbeam::DisplayFont::SMALL);
+    snprintf(line1, sizeof(line1), "Services");
+    snprintf(line2, sizeof(line2), "clock: %s", clockService.valid() ? "valid" : "bad");
+    snprintf(line3, sizeof(line3), "storage: %s", storage.ready() ? "ready" : "bad");
+    snprintf(line4, sizeof(line4), "logger: %s", Log.storageReady() ? "file" : "serial");
+    snprintf(line5, sizeof(line5), "%s", rtc);
+    display.showLines(line1, line2, line3, line4, line5, "page 4/4");
+    display.setFont(tbeam::DisplayFont::NORMAL);
+  }
+}
+
+}  // namespace
+
+void setup() {
+  Serial.begin(115200);
+  delay(1500);
+  Serial.println();
+  Serial.printf("display test boot board=%s label=%s\r\n", BOARD_ID, NODE_LABEL);
+
+  const bool displayReady = display.begin();
+  Serial.printf("display_begin=%s error=%s\r\n", displayReady ? "ok" : "fail", display.lastError());
+  display.showBoot("Display Test", BOARD_ID, "starting services");
+
+  tbeam::StorageConfig storageConfig;
+  storageConfig.logDir = "/logs/display";
+  storageConfig.enablePinDumps = false;
+  storage.begin(storageConfig);
+  Log.begin(Serial, &storage);
+
+  clockService.begin();
+  openDisplayLog();
+  drawCurrentPage();
+}
+
+void loop() {
+  storage.update();
+  clockService.update();
+  Log.update();
+
+  const uint32_t now = millis();
+  if ((uint32_t)(now - lastSampleMs) >= 1000) {
+    lastSampleMs = now;
+    Log.printf("%lu,%lu,%u,%s,%s,%s,%lu\r\n",
+               (unsigned long)sampleSeq++,
+               (unsigned long)now,
+               (unsigned)page,
+               display.ready() ? "yes" : "no",
+               clockService.valid() ? "yes" : "no",
+               storage.ready() ? "yes" : "no",
+               (unsigned long)ESP.getFreeHeap());
+  }
+
+  if ((uint32_t)(now - lastPageMs) >= 2500) {
+    lastPageMs = now;
+    page = (uint8_t)((page + 1U) % 4U);
+    drawCurrentPage();
+  }
+}

tests/04_web_files/platformio.ini

@@ -0,0 +1,89 @@
+; Repository-level hardware test for tbeam_web.
+
+[platformio]
+default_envs = cy
+extra_configs = ../../shared/platformio/tbeam_supreme_units.ini
+
+[web_files_base]
+extends = tbeam_supreme_common
+build_flags =
+  ${tbeam_supreme_common.build_flags}
+  -D WEB_FILES_TEST=1
+
+[env:amy]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"AMY\"
+  -D NODE_LABEL=\"Amy\"
+  -D NODE_SHORT=\"A\"
+  -D NODE_SLOT_INDEX=0
+  -D LOG_AP_IP_OCTET=23
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:bob]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"BOB\"
+  -D NODE_LABEL=\"Bob\"
+  -D NODE_SHORT=\"B\"
+  -D NODE_SLOT_INDEX=1
+  -D LOG_AP_IP_OCTET=24
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:cy]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"CY\"
+  -D NODE_LABEL=\"Cy\"
+  -D NODE_SHORT=\"C\"
+  -D NODE_SLOT_INDEX=2
+  -D LOG_AP_IP_OCTET=25
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:dan]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"DAN\"
+  -D NODE_LABEL=\"Dan\"
+  -D NODE_SHORT=\"D\"
+  -D NODE_SLOT_INDEX=3
+  -D LOG_AP_IP_OCTET=26
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:ed]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"ED\"
+  -D NODE_LABEL=\"Ed\"
+  -D NODE_SHORT=\"E\"
+  -D NODE_SLOT_INDEX=4
+  -D LOG_AP_IP_OCTET=27
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:flo]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"FLO\"
+  -D NODE_LABEL=\"Flo\"
+  -D NODE_SHORT=\"F\"
+  -D NODE_SLOT_INDEX=5
+  -D LOG_AP_IP_OCTET=28
+  -D GNSS_CHIP_NAME=\"L76K\"
+
+[env:guy]
+extends = web_files_base
+build_flags =
+  ${web_files_base.build_flags}
+  -D BOARD_ID=\"GUY\"
+  -D NODE_LABEL=\"Guy\"
+  -D NODE_SHORT=\"G\"
+  -D NODE_SLOT_INDEX=6
+  -D LOG_AP_IP_OCTET=29
+  -D GNSS_CHIP_NAME=\"MAX-M10S\"
+  -D GPS_UBLOX

tests/04_web_files/src/main.cpp

@@ -0,0 +1,132 @@
+#include <Arduino.h>
+#include <TBeamClock.h>
+#include <TBeamDisplay.h>
+#include <TBeamLogger.h>
+#include <TBeamStorage.h>
+#include <TBeamWeb.h>
+
+#ifndef BOARD_ID
+#define BOARD_ID "UNKNOWN"
+#endif
+
+#ifndef NODE_LABEL
+#define NODE_LABEL "Unknown"
+#endif
+
+#ifndef LOG_AP_IP_OCTET
+#define LOG_AP_IP_OCTET 25
+#endif
+
+namespace {
+
+tbeam::TBeamClock clockService(Wire1);
+tbeam::TBeamDisplay display;
+tbeam::TBeamStorage storage(Serial);
+tbeam::TBeamLogger Log;
+tbeam::TBeamWeb web(Serial);
+
+uint32_t sampleSeq = 0;
+uint32_t lastSampleMs = 0;
+uint32_t lastDisplayMs = 0;
+
+void openWebLog() {
+  if (!storage.ready()) {
+    Serial.printf("Web log skipped: storage error=%s\r\n", storage.lastError());
+    return;
+  }
+
+  bool opened = false;
+  if (clockService.valid()) {
+    char runId[64];
+    char path[112];
+    tbeam::TBeamClock::makeRunId(clockService.lastRtc(), BOARD_ID, runId, sizeof(runId));
+    snprintf(path, sizeof(path), "%s/%s.csv", storage.logDir(), runId);
+    opened = Log.openLog(path);
+  }
+  if (!opened) {
+    opened = Log.openUniqueLog(BOARD_ID, ".csv");
+  }
+  if (!opened) {
+    Serial.printf("Web log open failed: %s\r\n", storage.lastError());
+    return;
+  }
+
+  Log.printf("# test: web_files\r\n");
+  Log.printf("# board_id: %s\r\n", BOARD_ID);
+  Log.printf("# node_label: %s\r\n", NODE_LABEL);
+  Log.printf("# log_path: %s\r\n", Log.currentLogPath());
+  Log.println("seq,millis,web_ready,stations,sd_ready,rtc_valid,free_heap");
+  Log.flush();
+  Serial.printf("Web log opened: %s\r\n", Log.currentLogPath());
+}
+
+void drawStatus() {
+  char ipLine[32];
+  char webLine[32];
+  char sdLine[32];
+  char logLine[32];
+
+  snprintf(ipLine, sizeof(ipLine), "%s", web.ip().toString().c_str());
+  snprintf(webLine, sizeof(webLine), "AP: %s", web.ssid());
+  snprintf(sdLine, sizeof(sdLine), "SD:%s STA:%u", storage.ready() ? "ok" : "bad", (unsigned)web.stationCount());
+  snprintf(logLine, sizeof(logLine), "Log:%s", Log.storageReady() ? "open" : "serial");
+
+  display.showLines("Web Files", webLine, ipLine, sdLine, logLine, BOARD_ID);
+}
+
+}  // namespace
+
+void setup() {
+  Serial.begin(115200);
+  delay(1500);
+  Serial.println();
+  Serial.printf("web files test boot board=%s label=%s\r\n", BOARD_ID, NODE_LABEL);
+
+  display.begin();
+  display.showBoot("Web Files", BOARD_ID, "starting services");
+
+  tbeam::StorageConfig storageConfig;
+  storageConfig.logDir = "/logs/web";
+  storageConfig.enablePinDumps = false;
+  storage.begin(storageConfig);
+  Log.begin(Serial, &storage);
+
+  clockService.begin();
+  openWebLog();
+
+  tbeam::WebConfig webConfig;
+  webConfig.ssidPrefix = "GPSQA";
+  webConfig.boardId = BOARD_ID;
+  webConfig.ipOctet = LOG_AP_IP_OCTET;
+  webConfig.enableDelete = true;
+  web.begin(storage, webConfig);
+
+  Serial.printf("Web UI: http://%s/\r\n", web.ip().toString().c_str());
+  Serial.printf("SSID: %s\r\n", web.ssid());
+  drawStatus();
+}
+
+void loop() {
+  storage.update();
+  clockService.update();
+  web.update();
+  Log.update();
+
+  const uint32_t now = millis();
+  if ((uint32_t)(now - lastSampleMs) >= 1000) {
+    lastSampleMs = now;
+    Log.printf("%lu,%lu,%s,%u,%s,%s,%lu\r\n",
+               (unsigned long)sampleSeq++,
+               (unsigned long)now,
+               web.ready() ? "yes" : "no",
+               (unsigned)web.stationCount(),
+               storage.ready() ? "yes" : "no",
+               clockService.valid() ? "yes" : "no",
+               (unsigned long)ESP.getFreeHeap());
+  }
+
+  if ((uint32_t)(now - lastDisplayMs) >= 2500) {
+    lastDisplayMs = now;
+    drawStatus();
+  }
+}