diff --git a/exercises/07_SD_Startup_Watcher/README.md b/exercises/07_SD_Startup_Watcher/README.md new file mode 100644 index 0000000..494c6a0 --- /dev/null +++ b/exercises/07_SD_Startup_Watcher/README.md @@ -0,0 +1,51 @@ +## Exercise 07: SD Startup Watcher + +This exercise is derived from `Exercise 05` and keeps that original exercise intact. +The focus here is isolating reusable SD startup and hot-insert watcher logic into a library-style structure. + +This exercise now has two parts: + +1. A reusable SD startup/watcher library in `lib/startup_sd`. +2. A harness app in `src/main.cpp` that demonstrates how to use that library. + +Watcher behavior: + +1. Initializes PMU and enables SD power rail (AXP2101 BLDO1). +2. Polls for card changes with debounced state transitions. +3. Emits events only on change: + - `EVENT: card inserted/mounted` + - `EVENT: card removed/unavailable` + - `EVENT: no card detected` +4. On mount event, emits callback status (`SdEvent`) and runs SD write workflow. +5. Every 15 seconds while mounted, runs a periodic write/permission check. +6. Uses fast preferred probe (`HSPI @ 400k`) and occasional full fallback scan. + +Status callback usage: + +- `SdEvent::NO_CARD` -> show "Missing SD card / Please insert card to proceed" +- `SdEvent::CARD_MOUNTED` -> card ready +- `SdEvent::CARD_REMOVED` -> card removed, wait for insert + +Files used in this exercise: +- `/Exercise_07_test.txt` +- `/test/testsub1/testsubsub1/Exercise_07_test.txt` + +## Build + +```bash +source /home/jlpoole/rnsenv/bin/activate +pio run -e node_a +``` + +## Upload + +```bash +source /home/jlpoole/rnsenv/bin/activate +pio run -e node_a -t upload --upload-port /dev/ttyACM0 +``` + +## Monitor + +```bash +screen /dev/ttyACM0 115200 +``` diff --git a/exercises/07_SD_Startup_Watcher/lib/startup_sd/StartupSdManager.cpp b/exercises/07_SD_Startup_Watcher/lib/startup_sd/StartupSdManager.cpp new file mode 100644 index 0000000..5cc77ed --- /dev/null +++ b/exercises/07_SD_Startup_Watcher/lib/startup_sd/StartupSdManager.cpp @@ -0,0 +1,346 @@ +#include "StartupSdManager.h" + +#include +#include "driver/gpio.h" + +StartupSdManager::StartupSdManager(Print& serial) : serial_(serial) {} + +bool StartupSdManager::begin(const SdWatcherConfig& cfg, SdStatusCallback callback) { + cfg_ = cfg; + callback_ = callback; + + forceSpiDeselected(); + dumpSdPins("very-early"); + + if (!initPmuForSdPower()) { + return false; + } + + cycleSdRail(); + delay(cfg_.startupWarmupMs); + + bool warmMounted = false; + for (uint8_t i = 0; i < 3; ++i) { + if (mountPreferred(false)) { + warmMounted = true; + break; + } + delay(200); + } + + if (warmMounted) { + setStateMounted(); + } else { + setStateAbsent(); + } + return true; +} + +void StartupSdManager::update() { + const uint32_t now = millis(); + const uint32_t pollInterval = + (watchState_ == SdWatchState::MOUNTED) ? cfg_.pollIntervalMountedMs : cfg_.pollIntervalAbsentMs; + + if ((uint32_t)(now - lastPollMs_) < pollInterval) { + return; + } + lastPollMs_ = now; + + if (watchState_ == SdWatchState::MOUNTED) { + if (verifyMountedCard()) { + presentVotes_ = 0; + absentVotes_ = 0; + return; + } + + if (mountPreferred(false) && verifyMountedCard()) { + presentVotes_ = 0; + absentVotes_ = 0; + return; + } + + absentVotes_++; + presentVotes_ = 0; + if (absentVotes_ >= cfg_.votesToAbsent) { + setStateAbsent(); + absentVotes_ = 0; + } + return; + } + + bool mounted = mountPreferred(false); + if (!mounted && (uint32_t)(now - lastFullScanMs_) >= cfg_.fullScanIntervalMs) { + lastFullScanMs_ = now; + logf("Watcher: preferred probe failed, running full scan"); + mounted = mountCardFullScan(); + } + + if (mounted) { + presentVotes_++; + absentVotes_ = 0; + if (presentVotes_ >= cfg_.votesToPresent) { + setStateMounted(); + presentVotes_ = 0; + } + } else { + absentVotes_++; + presentVotes_ = 0; + if (absentVotes_ >= cfg_.votesToAbsent) { + setStateAbsent(); + absentVotes_ = 0; + } + } +} + +bool StartupSdManager::consumeMountedEvent() { + bool out = mountedEventPending_; + mountedEventPending_ = false; + return out; +} + +bool StartupSdManager::consumeRemovedEvent() { + bool out = removedEventPending_; + removedEventPending_ = false; + return out; +} + +void StartupSdManager::logf(const char* fmt, ...) { + char msg[196]; + va_list args; + va_start(args, fmt); + vsnprintf(msg, sizeof(msg), fmt, args); + va_end(args); + serial_.printf("[%10lu][%06lu] %s\r\n", + (unsigned long)millis(), + (unsigned long)logSeq_++, + msg); +} + +void StartupSdManager::notify(SdEvent event, const char* message) { + if (callback_ != nullptr) { + callback_(event, message); + } +} + +void StartupSdManager::forceSpiDeselected() { + pinMode(tbeam_supreme::sdCs(), OUTPUT); + digitalWrite(tbeam_supreme::sdCs(), HIGH); + pinMode(tbeam_supreme::imuCs(), OUTPUT); + digitalWrite(tbeam_supreme::imuCs(), HIGH); +} + +void StartupSdManager::dumpSdPins(const char* tag) { + if (!cfg_.enablePinDumps) { + (void)tag; + 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, gpio_get_level(cs), gpio_get_level(sck), gpio_get_level(miso), gpio_get_level(mosi)); +} + +bool StartupSdManager::initPmuForSdPower() { + if (!tbeam_supreme::initPmuForPeripherals(pmu_, &serial_)) { + logf("ERROR: PMU init failed"); + return false; + } + return true; +} + +void StartupSdManager::cycleSdRail(uint32_t offMs, uint32_t onSettleMs) { + if (!cfg_.enableSdRailCycle) { + return; + } + if (!pmu_) { + logf("SD rail cycle skipped: pmu=null"); + return; + } + + forceSpiDeselected(); + pmu_->disablePowerOutput(XPOWERS_BLDO1); + delay(offMs); + pmu_->setPowerChannelVoltage(XPOWERS_BLDO1, 3300); + pmu_->enablePowerOutput(XPOWERS_BLDO1); + delay(onSettleMs); +} + +bool StartupSdManager::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 (int 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)) { + if (verbose) { + logf("SD: mount failed"); + } + return false; + } + + if (SD.cardType() == CARD_NONE) { + SD.end(); + return false; + } + + sdSpi_ = &bus; + sdBusName_ = busName; + sdFreq_ = hz; + return true; +} + +bool StartupSdManager::mountPreferred(bool verbose) { + return tryMountWithBus(sdSpiH_, "HSPI", 400000, verbose); +} + +bool StartupSdManager::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: card detected and mounted"); + return true; + } + } + for (uint8_t i = 0; i < (sizeof(freqs) / sizeof(freqs[0])); ++i) { + if (tryMountWithBus(sdSpiF_, "FSPI", freqs[i], true)) { + logf("SD: card detected and mounted"); + return true; + } + } + + logf("SD: begin() failed on all bus/frequency attempts"); + return false; +} + +bool StartupSdManager::verifyMountedCard() { + File root = SD.open("/", FILE_READ); + if (!root) { + return false; + } + root.close(); + return true; +} + +const char* StartupSdManager::cardTypeToString(uint8_t type) { + switch (type) { + case CARD_MMC: + return "MMC"; + case CARD_SD: + return "SDSC"; + case CARD_SDHC: + return "SDHC/SDXC"; + default: + return "UNKNOWN"; + } +} + +void StartupSdManager::printCardInfo() { + uint8_t cardType = SD.cardType(); + uint64_t cardSizeMB = SD.cardSize() / (1024ULL * 1024ULL); + uint64_t totalMB = SD.totalBytes() / (1024ULL * 1024ULL); + uint64_t usedMB = SD.usedBytes() / (1024ULL * 1024ULL); + + logf("SD type: %s", cardTypeToString(cardType)); + logf("SD size: %llu MB", cardSizeMB); + logf("FS total: %llu MB", totalMB); + logf("FS used : %llu MB", usedMB); + logf("SPI bus: %s @ %lu Hz", sdBusName_, (unsigned long)sdFreq_); +} + +bool StartupSdManager::ensureDirRecursive(const char* path) { + String full(path); + if (!full.startsWith("/")) { + full = "/" + full; + } + + int start = 1; + while (start > 0 && start < (int)full.length()) { + int slash = full.indexOf('/', start); + String partial = (slash < 0) ? full : full.substring(0, slash); + if (!SD.exists(partial.c_str()) && !SD.mkdir(partial.c_str())) { + logf("ERROR: mkdir failed for %s", partial.c_str()); + return false; + } + if (slash < 0) { + break; + } + start = slash + 1; + } + + return true; +} + +bool StartupSdManager::rewriteFile(const char* path, const char* payload) { + if (SD.exists(path) && !SD.remove(path)) { + logf("ERROR: failed to erase %s", path); + return false; + } + + File f = SD.open(path, FILE_WRITE); + if (!f) { + logf("ERROR: failed to create %s", path); + return false; + } + + size_t wrote = f.println(payload); + f.close(); + if (wrote == 0) { + logf("ERROR: write failed for %s", path); + return false; + } + return true; +} + +void StartupSdManager::permissionsDemo(const char* path) { + logf("Permissions demo: FAT has no Unix chmod/chown, use open mode only."); + File r = SD.open(path, FILE_READ); + if (!r) { + logf("Could not open %s as FILE_READ", path); + return; + } + size_t writeInReadMode = r.print("attempt write while opened read-only"); + if (writeInReadMode == 0) { + logf("As expected, FILE_READ write was blocked."); + } else { + logf("NOTE: FILE_READ write returned %u (unexpected)", (unsigned)writeInReadMode); + } + r.close(); +} + +void StartupSdManager::setStateMounted() { + if (watchState_ != SdWatchState::MOUNTED) { + logf("EVENT: card inserted/mounted"); + mountedEventPending_ = true; + notify(SdEvent::CARD_MOUNTED, "SD card mounted"); + } + watchState_ = SdWatchState::MOUNTED; +} + +void StartupSdManager::setStateAbsent() { + if (watchState_ == SdWatchState::MOUNTED) { + logf("EVENT: card removed/unavailable"); + removedEventPending_ = true; + notify(SdEvent::CARD_REMOVED, "SD card removed"); + } else if (watchState_ != SdWatchState::ABSENT) { + logf("EVENT: no card detected"); + notify(SdEvent::NO_CARD, "Missing SD card / Please insert card to proceed"); + } + SD.end(); + watchState_ = SdWatchState::ABSENT; +} diff --git a/exercises/07_SD_Startup_Watcher/lib/startup_sd/StartupSdManager.h b/exercises/07_SD_Startup_Watcher/lib/startup_sd/StartupSdManager.h new file mode 100644 index 0000000..095f857 --- /dev/null +++ b/exercises/07_SD_Startup_Watcher/lib/startup_sd/StartupSdManager.h @@ -0,0 +1,87 @@ +#pragma once + +#include +#include +#include +#include +#include "tbeam_supreme_adapter.h" + +enum class SdWatchState : uint8_t { + UNKNOWN = 0, + ABSENT, + MOUNTED +}; + +enum class SdEvent : uint8_t { + NO_CARD, + CARD_MOUNTED, + CARD_REMOVED +}; + +using SdStatusCallback = void (*)(SdEvent event, const char* message); + +struct SdWatcherConfig { + bool enableSdRailCycle = true; + bool enablePinDumps = true; + uint32_t startupWarmupMs = 1500; + uint32_t pollIntervalAbsentMs = 1000; + uint32_t pollIntervalMountedMs = 2000; + uint32_t fullScanIntervalMs = 10000; + uint8_t votesToPresent = 2; + uint8_t votesToAbsent = 5; +}; + +class StartupSdManager { + public: + explicit StartupSdManager(Print& serial = Serial); + + bool begin(const SdWatcherConfig& cfg, SdStatusCallback callback = nullptr); + void update(); + + bool isMounted() const { return watchState_ == SdWatchState::MOUNTED; } + SdWatchState state() const { return watchState_; } + + bool consumeMountedEvent(); + bool consumeRemovedEvent(); + + void printCardInfo(); + bool ensureDirRecursive(const char* path); + bool rewriteFile(const char* path, const char* payload); + void permissionsDemo(const char* path); + + private: + void logf(const char* fmt, ...); + void notify(SdEvent event, const char* message); + void forceSpiDeselected(); + void dumpSdPins(const char* tag); + bool initPmuForSdPower(); + void cycleSdRail(uint32_t offMs = 250, uint32_t onSettleMs = 600); + bool tryMountWithBus(SPIClass& bus, const char* busName, uint32_t hz, bool verbose); + bool mountPreferred(bool verbose); + bool mountCardFullScan(); + bool verifyMountedCard(); + const char* cardTypeToString(uint8_t type); + void setStateMounted(); + void setStateAbsent(); + + Print& serial_; + SdWatcherConfig cfg_{}; + SdStatusCallback callback_ = nullptr; + + SPIClass sdSpiH_{HSPI}; + SPIClass sdSpiF_{FSPI}; + SPIClass* sdSpi_ = nullptr; + const char* sdBusName_ = "none"; + uint32_t sdFreq_ = 0; + XPowersLibInterface* pmu_ = nullptr; + + SdWatchState watchState_ = SdWatchState::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; +}; diff --git a/exercises/07_SD_Startup_Watcher/lib/startup_sd/library.json b/exercises/07_SD_Startup_Watcher/lib/startup_sd/library.json new file mode 100644 index 0000000..4978fdd --- /dev/null +++ b/exercises/07_SD_Startup_Watcher/lib/startup_sd/library.json @@ -0,0 +1,12 @@ +{ + "name": "startup_sd", + "version": "0.1.0", + "dependencies": [ + { + "name": "XPowersLib" + }, + { + "name": "Wire" + } + ] +} diff --git a/exercises/07_SD_Startup_Watcher/platformio.ini b/exercises/07_SD_Startup_Watcher/platformio.ini new file mode 100644 index 0000000..e760c56 --- /dev/null +++ b/exercises/07_SD_Startup_Watcher/platformio.ini @@ -0,0 +1,37 @@ +; 20260213 ChatGPT +; $Id$ +; $HeadURL$ + +[platformio] +default_envs = node_a + +[env] +platform = espressif32 +framework = arduino +board = esp32-s3-devkitc-1 +monitor_speed = 115200 +lib_deps = + lewisxhe/XPowersLib@0.3.3 + Wire + olikraus/U8g2@^2.36.4 + +; SD pins based on T-Beam S3 core pin mapping +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 ARDUINO_USB_MODE=1 + -D ARDUINO_USB_CDC_ON_BOOT=1 + +[env:node_a] +build_flags = + ${env.build_flags} + -D NODE_LABEL=\"A\" + +[env:node_b] +build_flags = + ${env.build_flags} + -D NODE_LABEL=\"B\" diff --git a/exercises/07_SD_Startup_Watcher/src/main.cpp b/exercises/07_SD_Startup_Watcher/src/main.cpp new file mode 100644 index 0000000..ccc9d88 --- /dev/null +++ b/exercises/07_SD_Startup_Watcher/src/main.cpp @@ -0,0 +1,135 @@ +// 20260215 ChatGPT +// $Id$ +// $HeadURL$ + +#include +#include +#include +#include "StartupSdManager.h" +#include "tbeam_supreme_adapter.h" + +#define STARTUP_SERIAL_DELAY_MS 5000 +#ifndef OLED_SDA +#define OLED_SDA 17 +#endif +#ifndef OLED_SCL +#define OLED_SCL 18 +#endif +#ifndef OLED_ADDR +#define OLED_ADDR 0x3C +#endif + +static const char* kRootTestFile = "/Exercise_07_test.txt"; +static const char* kNestedDir = "/test/testsub1/testsubsub1"; +static const char* kNestedTestFile = "/test/testsub1/testsubsub1/Exercise_07_test.txt"; +static const char* kPayload = "This is a test"; +static const uint32_t kPeriodicActionMs = 15000; + +static U8G2_SH1106_128X64_NONAME_F_HW_I2C g_oled(U8G2_R0, /* reset=*/U8X8_PIN_NONE); +static StartupSdManager g_sd(Serial); +static uint32_t g_lastPeriodicActionMs = 0; + +static void oledShow3(const char* l1, const char* l2 = nullptr, const char* l3 = nullptr) { + g_oled.clearBuffer(); + g_oled.setFont(u8g2_font_6x10_tf); + if (l1) g_oled.drawUTF8(0, 16, l1); + if (l2) g_oled.drawUTF8(0, 32, l2); + if (l3) g_oled.drawUTF8(0, 48, l3); + g_oled.sendBuffer(); +} + +static void onSdStatus(SdEvent event, const char* message) { + Serial.printf("[SD-STATUS] %s\r\n", message); + + if (event == SdEvent::NO_CARD) { + oledShow3("Missing SD card", "Please insert card", "to proceed"); + } else if (event == SdEvent::CARD_MOUNTED) { + oledShow3("SD card ready", "Mounted OK"); + } else if (event == SdEvent::CARD_REMOVED) { + oledShow3("SD card removed", "Please re-insert"); + } +} + +static void runCardWorkflow() { + g_sd.printCardInfo(); + + if (!g_sd.rewriteFile(kRootTestFile, kPayload)) { + Serial.println("Watcher action: root file write failed"); + return; + } + if (!g_sd.ensureDirRecursive(kNestedDir)) { + Serial.println("Watcher action: directory creation failed"); + return; + } + if (!g_sd.rewriteFile(kNestedTestFile, kPayload)) { + Serial.println("Watcher action: nested file write failed"); + return; + } + + g_sd.permissionsDemo(kRootTestFile); +} + +void setup() { + Serial.begin(115200); + Wire.begin(OLED_SDA, OLED_SCL); + g_oled.setI2CAddress(OLED_ADDR << 1); + g_oled.begin(); + oledShow3("Exercise 07", "SD startup watcher", "Booting..."); + + Serial.println("[WATCHER: startup]"); + Serial.printf("Sleeping for %lu ms to allow Serial Monitor connection...\r\n", + (unsigned long)STARTUP_SERIAL_DELAY_MS); + delay(STARTUP_SERIAL_DELAY_MS); + + Serial.println(); + Serial.println("=================================================="); + Serial.println("Exercise 07: SD Startup Watcher (Library Harness)"); + Serial.println("=================================================="); + Serial.printf("Pins: CS=%d SCK=%d MISO=%d MOSI=%d\r\n", + tbeam_supreme::sdCs(), tbeam_supreme::sdSck(), + tbeam_supreme::sdMiso(), tbeam_supreme::sdMosi()); + Serial.printf("PMU I2C: SDA1=%d SCL1=%d\r\n", + tbeam_supreme::i2cSda(), tbeam_supreme::i2cScl()); + Serial.println("Note: SD must be FAT16/FAT32 for Arduino SD library.\r\n"); + + SdWatcherConfig cfg; + cfg.enableSdRailCycle = true; + cfg.enablePinDumps = true; + cfg.startupWarmupMs = 1500; + cfg.pollIntervalAbsentMs = 1000; + cfg.pollIntervalMountedMs = 2000; + cfg.fullScanIntervalMs = 10000; + cfg.votesToPresent = 2; + cfg.votesToAbsent = 5; + + if (!g_sd.begin(cfg, onSdStatus)) { + Serial.println("ERROR: SD watcher init failed"); + } + + if (g_sd.isMounted()) { + runCardWorkflow(); + g_lastPeriodicActionMs = millis(); + } +} + +void loop() { + g_sd.update(); + + if (g_sd.consumeMountedEvent()) { + runCardWorkflow(); + g_lastPeriodicActionMs = millis(); + } + + if (g_sd.consumeRemovedEvent()) { + Serial.println("SD removed, waiting for re-insert..."); + } + + const uint32_t now = millis(); + if (g_sd.isMounted() && (uint32_t)(now - g_lastPeriodicActionMs) >= kPeriodicActionMs) { + Serial.println("Watcher: periodic mounted check action"); + runCardWorkflow(); + g_lastPeriodicActionMs = now; + } + + delay(10); +} diff --git a/exercises/README.md b/exercises/README.md index 900ac7d..a6b703a 100644 --- a/exercises/README.md +++ b/exercises/README.md @@ -41,6 +41,10 @@ Exercise 04: Replace ASCII payload with microR packets Exercise 05: SD provisioning with identity.bin, peer list, beacon +Exercise 06: RTC check (PCF8563) read/set and persistence validation + +Exercise 07: SD startup watcher library harness with hot-insert detection + Each exercise is self-contained: its own platformio.ini