Mount a microSD card at /sd, addressing ewowi's PR #134 review

CMakeLists.txt

@@ -140,6 +140,7 @@ add_library(mm_core STATIC
     src/core/system/HttpServerModule.cpp
     src/core/system/FilesystemModule.cpp
     src/core/system/FileManagerModule.cpp
+    src/core/system/SdCardModule.cpp
     src/core/system/MqttModule.cpp
     src/core/util/sha256.cpp
     src/core/module/Scheduler.cpp

docs/moonmodules/core/system.md

@@ -245,6 +245,22 @@ Known renames from [MIGRATING.md](../../reference/MIGRATING.md) apply before upl
 
 Detail: [technical](moxygen/FileManagerModule.md)
 
+<a id="sd-card"></a>
+
+### SD Card
+
+A board's microSD slot, where one is wired: pins, a usage gauge and a format button. No panel of its own; mounted, its files appear under `/sd` in the one File Manager tree above. Behavior: ⌄ details.
+
+<img src="../../assets/core/SdCardModule.png" width="300" alt="SD Card module controls">
+
+- `clkPin` / `cmdPin` / `d0Pin`-`d3Pin` / `pwrPin`: the SDMMC pins, −1 for unused.
+- `d1Pin`-`d3Pin` left unset drop the bus to 1-bit mode.
+- `format`: a button, press twice; erases and reformats the card as FAT32 in place.
+- `card (KiB)`: read-only usage bar, used / total KiB.
+- KiB rather than bytes, so a card past 4 GiB still reports correctly.
+
+Detail: [technical](moxygen/SdCardModule.md)
+
 <a id="i2c-bus"></a>
 
 ### I2C bus
@@ -483,3 +499,9 @@ The panel is a lazy folder **tree** (each folder loads its children on first exp
 - Create / delete are HTTP calls (`POST` / `DELETE /api/dir?path=`), not controls, the path rides the request, so nothing is stored on the device per op.
 
 Last-modified dates (needs an NTP time source + LittleFS mtime), binary/large + folder upload, folder-as-zip download, and `.ml` syntax highlighting are backlogged ([backlog-core § File Manager follow-ups](../../work/future/backlog-core.md#file-manager-follow-ups)).
+
+## SD Card, details
+
+Mounts live, in `prepare()` rather than `setup()`: editing a pin unmounts and remounts on the new wiring, no reboot needed, the same contract I2C bus's `sda`/`scl` have below. A missing or unreadable card shows its own status instead of retrying every tick; reinsert it and touch a pin field (or reboot) to try again.
+
+The card is FAT32 only (ESP-IDF's FatFs ships with exFAT compiled out); `format` reformats one to FAT32 in place rather than requiring a second device. Once mounted, its content is reached through the File Manager above exactly like the internal flash, under an `sd` folder; this module never duplicates that tree.

docs/reference/hardware/esp32-p4-eth.md

@@ -42,7 +42,7 @@ The board uses the `P4 RMII` preset, shared with the Waveshare P4-NANO: MDC 31,
 
 ## microSD slot
 
-Wired on the board; MoonLight does not mount it:
+Wired on the board and mounted by [SdCardModule](../../moonmodules/core/system.md#sd-card):
 
 | Signal | GPIO |
 |---|---|

docs/reference/hardware/gpio-usage.md

@@ -70,7 +70,7 @@ For **LED output** specifically — the pins a WS2812-class strand data line can
 | Role-conflict | **34-38** | Strapping pins (boot mode). Don't drive at reset; the first LED-driver default wrongly landed here (see [lessons.md](../../work/past/lessons.md)). |
 | Role-conflict | **37, 38** | UART0 console on the P4-NANO (`CONFIG_ESP_CONSOLE_UART_DEFAULT`) — the runtime `ESP_LOGI` lines come out here, not over USB. |
 | Board-wired (P4-NANO) | **Ethernet RMII** 28-31 / 49-52, **C6 SDIO** 14-19 / 54, **I2C** 7-8 | Consumed by the NANO's on-board Ethernet PHY, the C6 WiFi co-processor, and the I2C bus. |
-| Board-wired (P4-ETH) | **Ethernet RMII** 28-31 / 34-35 / 49-52, **ES8311 audio** 7-13, **USB D-/D+** 24-25, **microSD** (unimplemented) 39-45 | The [Waveshare ESP32-P4-ETH](esp32-p4-eth.md) has no C6/WiFi. It carries its own onboard ES8311 codec, a native USB-C port, and a microSD slot; that page has the full per-signal map. |
+| Board-wired (P4-ETH) | **Ethernet RMII** 28-31 / 34-35 / 49-52, **ES8311 audio** 7-13, **USB D-/D+** 24-25, **microSD** 39-45 | The [Waveshare ESP32-P4-ETH](esp32-p4-eth.md) has no C6/WiFi. It carries its own onboard ES8311 codec, a native USB-C port, and a microSD slot. That page has the full per-signal map. |
 
 **Clear on the P4-NANO:** 20-27, 32-33, 39-48 (the LED-driver default is `pins="20,21,22,23,24,25,26,27"`). Exact free set is board-specific; the NANO's is the reference. A carrier board changes what's exposed and how. The [MHC-WLED ESP32-P4 shield](mhc-wled-esp32-p4-shield.md) routes every terminal through level shifters, RS-485 transceivers, or protected inputs, with no bare GPIO. A direct loopback jumper fails on it for that reason. Its full terminal map is on that page.
 

docs/reference/metrics/code.md

@@ -4,19 +4,19 @@ Generated by [`moondeck/check/check_code.py`](../../../moondeck/check/check_code
 
 Every function, block and file over a limit the [coding standards](../../contributing/coding-standards.md#static-checks) set. Current state only: the trend is this file's git history. The list only shrinks, per rule and in total, and a touched file clears its own rows.
 
-**1620 finding(s)** across 318 file(s). 2.88% of all lines are duplicated, 3733 lines.
+**1629 finding(s)** across 320 file(s). 2.88% of all lines are duplicated, 3733 lines.
 
 ## By rule
 
 | Rule | Findings |
 |---|---:|
 | duplicated block | 768 |
-| complex function | 283 |
-| blocking call on the render path | 189 |
+| complex function | 289 |
+| blocking call on the render path | 195 |
 | deeply nested | 113 |
 | module type in the UI | 71 |
 | long function | 49 |
-| large stack frame | 38 |
+| large stack frame | 35 |
 | long parameter list | 34 |
 | raw allocation in light | 28 |
 | large file | 25 |
@@ -46,11 +46,11 @@ Each rule is a code smell with a named move from the refactoring catalog, the ta
 |---|---:|
 | `test` | 570 |
 | `light` | 421 |
-| `core` | 351 |
-| `platform` | 173 |
+| `core` | 352 |
+| `platform` | 182 |
 | `ui` | 74 |
 | `moondeck` | 24 |
-| `src` | 5 |
+| `src` | 4 |
 | `mooninstaller` | 2 |
 
 ## By file
@@ -59,23 +59,23 @@ The next function worth simplifying is at the top of each file's list.
 
 | File | Findings | Worst |
 |---|---:|---|
-| `src/core/system/HttpServerModule.cpp` | 44 | `HttpServerModule::handleConnection`, complex function 121 |
+| `src/platform/desktop/platform_desktop.cpp` | 46 | `platform::getMacAddress, line 1379`, large stack frame 5240 |
+| `src/core/system/HttpServerModule.cpp` | 44 | `HttpServerModule::handleConnection`, complex function 123 |
 | `src/ui/migrate.js` | 43 | `line 29: 'I2cBusModule'`, module type in the UI 1 |
-| `src/platform/desktop/platform_desktop.cpp` | 41 | `platform::spawnEncoderProcess`, complex function 58 |
 | `src/core/system/MqttModule.cpp` | 31 | `MqttModule::routePublish`, complex function 29 |
-| `src/ui/app.js` | 29 | `app.js`, large file 9033 |
+| `src/ui/app.js` | 29 | `app.js`, large file 9076 |
 | `src/core/moonlive/MoonLiveCompiler.cpp` | 27 | `moonlive::Parser::parseCall`, complex function 59 |
 | `src/light/drivers/ParallelLedDriver.h` | 27 | `ParallelLedDriver::reinit`, complex function 36 |
 | `src/light/drivers/PreviewDriver.h` | 27 | `PreviewDriver::buildCoordTable`, complex function 37 |
 | `test/unit/core/unit_FilesystemModule_persistence.cpp` | 24 | `lines 181-194, also in test/unit/core/unit_FilesystemModule_persistence.cpp:146`, duplicated block 14 |
-| `src/light/drivers/RtspDriver.h` | 23 | `RtspDriver::serveControl, line 185`, large stack frame 1680 |
+| `src/light/drivers/RtspDriver.h` | 23 | `RtspDriver::serveControl, line 185`, large stack frame 1608 |
 | `test/unit/light/unit_I80Peripheral.cpp` | 23 | `lines 151-170, also in test/unit/light/unit_ParlioPeripheral.cpp:214`, duplicated block 20 |
 | `test/unit/light/unit_PanelCardDriver.cpp` | 22 | `lines 22-39, also in test/unit/light/unit_NdiDriver.cpp:29`, duplicated block 18 |
 | `test/unit/light/unit_RainbowEffect.cpp` | 22 | `lines 69-85, also in test/unit/light/unit_ParticlesEffect.cpp:32`, duplicated block 17 |
 | `src/light/powerfunctions/draw.h` | 21 | `draw::scroll`, complex function 28 |
 | `src/core/system/NetworkModule.h` | 20 | `NetworkModule in 25 files`, name spread 25 |
 | `test/unit/light/unit_ParallelLedDriver_ring.cpp` | 20 | `lines 486-503, also in test/unit/light/unit_ParallelLedDriver_ring.cpp:432`, duplicated block 18 |
-| `src/light/drivers/HueDriver.h` | 19 | `HueDriver::pollPairing, line 297`, large stack frame 1184 |
+| `src/light/drivers/HueDriver.h` | 19 | `HueDriver::pollPairing, line 297`, large stack frame 1112 |
 | `src/platform/esp32/platform_esp32.cpp` | 19 | `platform::httpRequest`, complex function 30 |
 | `test/unit/core/unit_HttpServerModule_apply.cpp` | 19 | `lines 536-547, also in test/unit/core/unit_HttpServerModule_apply.cpp:122`, duplicated block 12 |
 | `src/platform/esp32/platform_esp32_moon_i80.cpp` | 18 | `platform::createRingState`, complex function 32 |
@@ -121,6 +121,7 @@ The next function worth simplifying is at the top of each file's list.
 | `src/core/system/SystemModule.h` | 7 | `SystemModule in 31 files`, name spread 31 |
 | `src/core/util/JsonUtil.h` | 7 | `json::parseString`, complex function 34 |
 | `src/light/effects/FishTankEffect.h` | 7 | `lines 244-258, also in src/light/effects/PacmanEffect.h:243`, duplicated block 15 |
+| `src/platform/esp32/platform_esp32_fs.cpp` | 7 | `lines 227-237, also in src/platform/esp32/platform_esp32_fs.cpp:174`, duplicated block 11 |
 | `src/platform/esp32/platform_esp32_hub75.cpp` | 7 | `platform::hub75Init`, complex function 32 |
 | `src/platform/esp32/platform_esp32_parlio.cpp` | 7 | `lines 277-286, also in src/platform/esp32/platform_esp32_i80.cpp:425`, duplicated block 10 |
 | `test/js/ui-ws-scheme.test.mjs` | 7 | `lines 10-22, also in test/js/ui-render-guard.test.mjs:13`, duplicated block 13 |
@@ -129,11 +130,11 @@ The next function worth simplifying is at the top of each file's list.
 | `test/unit/light/unit_PlasmaEffect.cpp` | 7 | `lines 24-39, also in test/unit/light/unit_MetaballsEffect.cpp:22`, duplicated block 16 |
 | `src/core/moonlive/moonlive_lower.h` | 6 | `moonlive::lowerWith`, complex function 82 |
 | `src/core/system/FirmwareUpdateModule.h` | 6 | `FirmwareUpdateModule in 13 files`, name spread 13 |
+| `src/core/util/JsonSink.h` | 6 | `JsonSink::writeJsonString`, deeply nested 8 |
 | `src/light/drivers/FixtureProfilesModule.h` | 6 | `lines 245-252, also in src/core/system/WiFiModule.h:352`, duplicated block 8 |
-| `src/light/drivers/NetworkSendDriver.h` | 6 | `NetworkSendDriver::tick, line 190`, large stack frame 1760 |
+| `src/light/drivers/NetworkSendDriver.h` | 6 | `NetworkSendDriver::tick, line 190`, large stack frame 1640 |
 | `src/light/layers/BlendMap.h` | 6 | `blendMap`, complex function 35 |
 | `src/platform/desktop/moonlive_asm_x86_64.cpp` | 6 | `lines 557-564, also in src/platform/desktop/moonlive_asm_x86_64.cpp:515`, duplicated block 8 |
-| `src/platform/esp32/platform_esp32_fs.cpp` | 6 | `lines 211-221, also in src/platform/esp32/platform_esp32_fs.cpp:161`, duplicated block 11 |
 | `src/platform/esp32/platform_esp32_improv.cpp` | 6 | `platform::improvTask`, complex function 22 |
 | `test/unit/core/unit_AccessPointModule.cpp` | 6 | `lines 340-348, also in test/unit/core/unit_AccessPointModule.cpp:311`, duplicated block 9 |
 | `test/unit/core/unit_ImprovFrame.cpp` | 6 | `lines 179-187, also in test/unit/core/unit_ImprovFrame.cpp:152`, duplicated block 9 |
@@ -147,7 +148,6 @@ The next function worth simplifying is at the top of each file's list.
 | `src/core/services/AnalogService.h` | 5 | `lines 105-123, also in src/core/services/InfraredService.h:117`, duplicated block 19 |
 | `src/core/services/AudioBands.h` | 5 | `magnitudesToBands`, complex function 19 |
 | `src/core/util/InputMapping.h` | 5 | `setInputActionField`, complex function 22 |
-| `src/core/util/JsonSink.h` | 5 | `JsonSink::writeJsonString`, deeply nested 8 |
 | `src/core/util/noise.h` | 5 | `lines 304-310, also in src/core/util/noise.h:288`, duplicated block 7 |
 | `src/light/drivers/PinList.h` | 5 | `assignCounts`, complex function 30 |
 | `src/light/effects/FluidEffect.h` | 5 | `FluidEffect::data`, deeply nested 5 |
@@ -156,6 +156,7 @@ The next function worth simplifying is at the top of each file's list.
 | `src/light/layouts/CarLightsLayout.h` | 5 | `lines 49-65, also in src/light/layouts/TorontoBarGourdsLayout.h:52`, duplicated block 17 |
 | `src/light/layouts/RingLayout.h` | 5 | `lines 85-100, also in src/light/layouts/CarLightsLayout.h:95`, duplicated block 16 |
 | `src/light/layouts/TorontoBarGourdsLayout.h` | 5 | `lines 52-68, also in src/light/layouts/CarLightsLayout.h:49`, duplicated block 17 |
+| `src/platform/desktop/main_desktop.cpp` | 5 | `main`, deeply nested 5 |
 | `src/platform/esp32/platform_esp32_h264.cpp` | 5 | `platform::hlsSegment`, complex function 26 |
 | `test/unit/light/unit_Drivers_rendersplit.cpp` | 5 | `(static local variable) in tick`, blocking call on the render path 1 |
 | `test/unit/light/unit_FireEffect.cpp` | 5 | `lines 29-42, also in test/unit/light/unit_RainbowEffect.cpp:69`, duplicated block 14 |
@@ -181,8 +182,6 @@ The next function worth simplifying is at the top of each file's list.
 | `src/light/layers/MappingLUT.h` | 4 | `MappingLUT::allocateDestinations`, complex function 12 |
 | `src/light/powerfunctions/particles.h` | 4 | `particles::Pool::collide`, complex function 16 |
 | `src/light/util/RtspSession.h` | 4 | `rtsp::parseTransport`, complex function 28 |
-| `src/main.cpp` | 4 | `mm_main`, complex function 27 |
-| `src/platform/desktop/main_desktop.cpp` | 4 | `main`, deeply nested 5 |
 | `src/platform/esp32/moonlive_asm_riscv.cpp` | 4 | `lines 297-303, also in src/platform/esp32/moonlive_asm_xtensa.cpp:481`, duplicated block 7 |
 | `test/js/ui-mooncloud.test.mjs` | 4 | `lines 6-17, also in test/js/installer-s31-webflash.test.mjs:11`, duplicated block 12 |
 | `test/unit/light/unit_BlurzEffect.cpp` | 4 | `lines 137-155, also in test/unit/light/unit_GEQEffect.cpp:159`, duplicated block 19 |
@@ -208,6 +207,7 @@ The next function worth simplifying is at the top of each file's list.
 | `src/light/effects/PongEffect.h` | 3 | `PongEffect::render`, complex function 15 |
 | `src/light/effects/SolidEffect.h` | 3 | `SolidEffect::static_cast<lengthType>`, complex function 36 |
 | `src/light/layouts/GridLayout.h` | 3 | `GridLayout in 86 files`, name spread 86 |
+| `src/main.cpp` | 3 | `mm_main`, complex function 27 |
 | `src/platform/desktop/moonlive_asm_arm64.cpp` | 3 | `lines 35-40, also in src/platform/esp32/moonlive_asm_riscv.cpp:34`, duplicated block 6 |
 | `test/unit/core/unit_NetworkModule_ethernet.cpp` | 3 | `lines 276-285, also in test/unit/core/unit_NetworkModule_ethernet.cpp:193`, duplicated block 10 |
 | `test/unit/light/unit_AuroraEffect.cpp` | 3 | `lines 40-48, also in test/unit/light/unit_PolarLut_equivalence.cpp:40`, duplicated block 9 |
@@ -229,9 +229,8 @@ The next function worth simplifying is at the top of each file's list.
 | `src/core/services/MidiService.h` | 2 | `MidiService::serveShare in tick20ms`, blocking call on the render path 1 |
 | `src/core/system/DevicePlugin.h` | 2 | `lines 94-100, also in src/core/system/DevicePlugin.h:75`, duplicated block 7 |
 | `src/core/system/HttpServerModule.h` | 2 | `HttpServerModule in 17 files`, name spread 17 |
-| `src/core/system/I2cBusModule.h` | 2 | `I2cBusModule::scan`, complex function 18 |
 | `src/core/system/MqttPacket.h` | 2 | `buildMqttConnect`, complex function 31 |
-| `src/core/system/Sha1.h` | 2 | `sha1, line 21`, large stack frame 944 |
+| `src/core/system/Sha1.h` | 2 | `sha1, line 21`, large stack frame 920 |
 | `src/core/util/ModuleFactory.h` | 2 | `ModuleFactory::create`, deeply nested 4 |
 | `src/core/util/PinList.h` | 2 | `parsePinList`, complex function 15 |
 | `src/light/drivers/DriverBase.h` | 2 | `line 167: if (!wire_) wire_ = static_cast<uint8_t*>(platform::alloc(by`, raw allocation in light 1 |
@@ -259,6 +258,7 @@ The next function worth simplifying is at the top of each file's list.
 | `src/platform/esp32/moonlive_asm_riscv.h` | 2 | `lines 74-91, also in src/platform/esp32/moonlive_asm_xtensa.h:79`, duplicated block 18 |
 | `src/platform/esp32/moonlive_asm_xtensa.cpp` | 2 | `lines 481-487, also in src/platform/esp32/moonlive_asm_riscv.cpp:297`, duplicated block 7 |
 | `src/platform/esp32/moonlive_emit_riscv.cpp` | 2 | `lines 52-57, also in src/platform/esp32/moonlive_emit_riscv.cpp:25`, duplicated block 6 |
+| `src/platform/esp32/platform_esp32_sdmmc.cpp` | 2 | `platform::sdMount`, complex function 22 |
 | `test/js/ui-midi-bridge.test.mjs` | 2 | `lines 4-16, also in test/js/ui-gamepad-bridge.test.mjs:4`, duplicated block 13 |
 | `test/unit/core/unit_AudioService_sync.cpp` | 2 | `lines 313-322, also in test/unit/core/unit_AudioService_sync.cpp:269`, duplicated block 10 |
 | `test/unit/core/unit_DevicesModule_hue.cpp` | 2 | `lines 63-69, also in test/unit/core/unit_DevicesModule_hue.cpp:42`, duplicated block 7 |
@@ -304,6 +304,8 @@ The next function worth simplifying is at the top of each file's list.
 | `src/core/services/Services.h` | 1 | `Services in 12 files`, name spread 12 |
 | `src/core/system/FileManagerModule.cpp` | 1 | `platform::filesystemUsed in tick1s`, blocking call on the render path 1 |
 | `src/core/system/FilesystemModule.h` | 1 | `FilesystemModule in 24 files`, name spread 24 |
+| `src/core/system/I2cBusModule.h` | 1 | `I2cBusModule::scan`, complex function 18 |
+| `src/core/system/SdCardModule.cpp` | 1 | `SdCardModule::refreshGauge in tick1s`, blocking call on the render path 1 |
 | `src/core/util/Addressing.h` | 1 | `sendAddressed`, complex function 11 |
 | `src/core/util/CaptivePortal.h` | 1 | `captive::dnsReply`, complex function 21 |
 | `src/core/util/ImprovFrame.h` | 1 | `ImprovFrameParser::feed`, complex function 22 |
@@ -339,14 +341,14 @@ The next function worth simplifying is at the top of each file's list.
 | `src/light/moonlive/MoonLivePalette.h` | 1 | `moonlive::MoonLive::runValue in tick`, blocking call on the render path 1 |
 | `src/light/powerfunctions/fluid.h` | 1 | `Fluid::resize`, complex function 14 |
 | `src/light/util/E131Packet.h` | 1 | `parseE131Packet`, complex function 17 |
-| `src/module_types.cpp` | 1 | `registerModuleTypes`, long function 149 |
+| `src/module_types.cpp` | 1 | `registerModuleTypes`, long function 150 |
 | `src/platform/desktop/moonlive_asm_host.h` | 1 | `lines 36-43, also in src/platform/esp32/moonlive_asm_riscv.h:36`, duplicated block 8 |
-| `src/platform/desktop/platform_config.h` | 1 | `lines 71-85, also in src/platform/esp32/platform_config.h:236`, duplicated block 15 |
+| `src/platform/desktop/platform_config.h` | 1 | `lines 71-85, also in src/platform/esp32/platform_config.h:241`, duplicated block 15 |
 | `src/platform/esp32/moonlive_asm_xtensa.h` | 1 | `lines 79-96, also in src/platform/esp32/moonlive_asm_riscv.h:74`, duplicated block 18 |
-| `src/platform/esp32/platform_config.h` | 1 | `lines 236-250, also in src/platform/desktop/platform_config.h:71`, duplicated block 15 |
+| `src/platform/esp32/platform_config.h` | 1 | `lines 241-255, also in src/platform/desktop/platform_config.h:71`, duplicated block 15 |
 | `src/platform/esp32/platform_esp32_i2s.cpp` | 1 | `platform::audioMicInit`, complex function 11 |
 | `src/platform/esp32/platform_esp32_tasks.cpp` | 1 | `platform::taskSnapshot`, complex function 12 |
-| `src/platform/platform.h` | 1 | `platform.h`, large file 1301 |
+| `src/platform/platform.h` | 1 | `platform.h`, large file 1350 |
 | `src/ui/install-picker.js` | 1 | `install-picker.js`, large file 1048 |
 | `src/ui/preview3d.js` | 1 | `preview3d.js`, large file 1431 |
 | `test/js/installer-eth-only.test.mjs` | 1 | `lines 13-23, also in test/js/ui-mooncloud.test.mjs:6`, duplicated block 11 |