Add a generic SD card service with live-configurable pins

[TouchMyLight]

add microSD read/write support, shaped as a chip-capability service rather than a board-specific firmware variant: pins are runtime configuration like AudioService's mic, and no new Kconfig option or sdkconfig fragment is needed.
Core

• platform::hasSdCard is now a chip-capability flag (CONFIG_SOC_SDMMC_HOST_SUPPORTED), not a per-board Kconfig gate; sdMount() takes pins as a runtime SdPinConfig argument (clk/cmd/d0-d3/pwr) instead of hardcoded GPIOs, with bus width derived from which data lines are set. New platform::feedWatchdog() and platform::sdFormat() calls.
• New SdCardModule (Services child): pin controls hidden where the chip has no SDMMC host, a usage gauge, and a hidden format button. Mounting lives in prepare()/affectsPrepare(), not setup(), so a pin edit unmounts and remounts live, the same contract I2cBusModule's sda/scl have; release() unmounts. This was a real bug caught by bench testing a first version that only wired setup().
• HttpServerModule: /api/sddir + /api/sdfile routes mirroring the flash File Manager's, with an SD-sized Content-Length ceiling (FAT32's 4 GiB − 1) and overflow-safe parsing on this 32-bit target.

UI

• New SD Card panel (renderSdCardManager), sharing the File Manager's tree/toolbar machinery over an apiKind parameter. A 💾 Format button, SD-panel only, press-twice armed like the existing delete/restore buttons, wipes and reformats the card as FAT32.

Catalog

• Waveshare ESP32-P4-ETH: SdCardModule wired with its schematic pins (clk 43, cmd 44, d0-d3 39-42, pwr 45), "SD card" moved to supported.
• check_devices.py: "SD card" added to the supported-capability vocabulary.

Tests: unit_SdCardModule.cpp — hidden pin controls on a hardware-less build, the Service role, prepare()'s "no SD hardware"/pin-live-reconfiguration contracts, release() safety, the format button's hidden declaration and its refusal while unmounted.

Docs: gpio-usage.md and core/system.md carry minimal SD mentions; the full per-board pin table belongs on docs/reference/hardware/esp32-p4-eth.md, which doesn't exist on this branch (it's part of the still-unmerged esp32-p4-eth_ar/PR #130 branch) — not duplicated here.

Bench-verified end to end on the Waveshare ESP32-P4-ETH (plain esp32p4rev1-eth firmware, flashed over OTA): mount survives reboot with persisted pins, mkdir/upload/read/delete round-trip, live pin-remount without a reboot, and — with the product owner's explicit go-ahead to wipe the card's real content — a live Format that emptied the card and left it fully writable afterward.

docs/reference/metrics/docgen.md is deliberately NOT included in this commit: regenerating it surfaces a pre-existing, unrelated error in src/light/drivers/Hub75Slots.h (a 2-line code comment, from a prior commit that never re-ran the generator) that this change did not introduce and does not fix. Warnings are otherwise flat against the committed baseline, net of one untraced +1 in the over-wide-comment-lines rule after exhaustive searching across every touched file.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: MoonModules/MoonLight/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 2661ec76-a368-4c4b-aa43-1889bd04d450

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[TouchMyLight]

this is bigger feature introduction. let me know if it should be changed to better be integrated into this project.
maybe a bit of context would help: I used MoonLights (v4.0.0) for an installation with 8000 LEDs over 20 outputs as a 20x20x20 cube (not easily supported by WLED, and nicer to use for others than raw fastLED). It ran stable for 4 days with DDP over Ethernet.
this first PR is to support the SD interface on the board (to be able to read large files), and another will follow up for a FSEQ 3D animation player. This way my installation can run without requiring a computer to send the animation over network.

[ewowi]

All of this is supercool !

I am currently working on this project: https://moonmodules.org/MoonLight/how-to/multi-board-installation.html

But exactly 20x20x20 is my next project. This is my old setup running on old MoonLight:

trim.B4A063AA-7068-43F6-87E8-2DBCB01DD1D3.MOV

So I will look at your work with great interest.

Coming back to this soon !

[TouchMyLight]

more information about the installation and the hardware sources are available here: https://git.touchmylight.info/TouchMyLight/chandeLED

[ewowi]

more information about the installation and the hardware sources are available here: https://git.touchmylight.info/TouchMyLight/chandeLED

That's a beauty! Where can I buy 🙂

Regarding :

1x16 using PARLIO
2x8 using SPI
1x4 using RMT

You know the P4 also has lcd_cam, which give you another 16 pins to drive 🙂

And if you want even more, MoonLight supports "pinExpander" based on @hpwit his virtual clockless driver using 595 shift registers, giving you up to 120 more pins 👻

[TouchMyLight]

I actually used the LCD driver for the cube. The readme was outdated, but this is fixed now.
I did not know about the 595 support though. Thanks for pointing it out. It might come in handy for pin limited boards. For the chandeLED I probably don't need more output than 24, and don't have lots of board space for more connectors
I stopped selling the boards I make because the distribution aspect does not excite me that much. I prefer spending my time designing new boards. But you can find the hardware manufacturing files in the releases and can send them to you board house. There are some improved planned for v2, but the v1 works and can be used.

[ewowi]

Thanks a lot for this, and for testing it end to end on the P4-ETH, including a live format. Your plan behind it is exactly the kind of thing MoonLight should do: an FSEQ player that runs an installation like your 20×20×20 cube without a computer. Other uses the card opens up:

• Show playback without a computer: FSEQ sequences from xLights, frame by frame from the card (your next PR).
• Recording a show: capture what arrives over DDP, Art-Net or E1.31, and replay it standalone.
• Media for effects: video or image sequences larger than the internal flash.
• Libraries: many MoonLive scripts, palettes and presets, swapped per show.
• Backups and logs: device backups, and a log of an unattended night.

The platform side (platform_esp32_sdmmc.cpp) is the strongest part: pins as runtime settings with the bus width derived from the wired lines, live remounting through prepare(), and the power pin, LDO domain and NO_CD/NO_WP handled with their reasons. The changes below are about how it joins the rest of MoonLight.

1. The card as a mount point in the File Manager. If the platform's file layer sends every path under /sd to the card, the existing /api/file and /api/dir routes, upload streaming, delete and the File Manager all work unchanged, and the card shows as an sd folder next to the internal flash. That removes the six *Sd* handlers and removeRecursiveSd (main moved that walk to FilesystemModule::removeTree), the separate panel and the mod.type === "SdCardModule" check in app.js (check_code counts type names in src/ui, and that count may only fall). Format becomes controls_.addButton("format", /*confirm*/ true) on the SdCardModule card, which already gives the press-twice confirmation.

2. Flash: only in images with room. Measured on the classic ESP32 image, same base commit: +81.2 KB (FatFs 26.1, SD protocol 16.0, SD host driver 14.3, C stdio file functions 15.2, the module, routes and UI 9.6). On a 4 MB board that is a quarter of the app slot's remaining room, and the classic ESP32's SD host only works on its fixed pins (2, 4, 12, 13, 14, 15). Please build the SD card into the images that have room (P4, S31, the 16 MB S3) and leave it out of the 4 MB ones, the same way the S3-Zero image leaves out the USB host. Using FatFs directly (f_open, f_read, f_write) rather than fopen/fread saves most of the stdio part.

3. Large transfers off the render thread. HTTP requests are served from tick20ms, so a multi-GB upload freezes the LEDs, the preview and OSC for its whole length, and platform::feedWatchdog() silences the check that reports exactly that. Please drop feedWatchdog and move a large file a chunk per tick, the way the server already sends long replies. Your FSEQ player needs the same per-frame streaming (a 20×20×20 cube at 40 fps reads about 1 MB/s), so this work pays twice. Until then, a size cap on SD uploads keeps the render thread safe.

4. Card sizes past 4 GB. size_t and the uint32_t gauge are 32-bit on the ESP32, so a 32 GB card reports a total of 0 and a 48 GB card reports 16 GB. Report KiB or uint64_t from the platform.

5. One open file per download. sdReadAt reopens and seeks for every 1 KB chunk; on FAT a seek walks the cluster chain from the start, so large downloads slow down badly. One handle per stream, like fsWriteStream on the write side.

6. Smaller items.

• sdRead, sdExists and sdWriteAtomic have no caller; please remove them.
• 1ULL << pins.pwr with a pin above 63 is undefined behavior: check GPIO_IS_VALID_OUTPUT_GPIO first.
• Docs: system.md says the card mounts once in setup() and needs a reboot, while it remounts live in prepare(). It also references SdCardModule.png, which isn't in the PR, and a file browser control that doesn't exist. gpio-usage.md already has a microSD cell (39-45, "unimplemented") and esp32-p4-eth.md says MoonLight doesn't mount the card: please edit those rather than adding a paragraph. Headings in positive form ("Built field by field" rather than "Not SDMMC_SLOT_CONFIG_DEFAULT()").

7. Tests. Map /sd to a folder on the computer in the desktop build, the way the desktop already maps the internal flash. Then the tests can cover mount and remount on a pin change, format, the usage gauge, and the routes under /sd (path traversal, 413 too large, 507 card full), as unit_FileManagerModule does for flash.

8. Start again from current main. 17 of the 21 files changed on main since this branched: HttpServerModule.cpp is largely rewritten, app.js's File Manager grew, and esp32-p4-eth.md now exists. A plain git rebase would stop on nearly every file, and points 1 to 3 rewrite those parts anyway, so it is easier to put the branch on today's main and bring back what carries over. With upstream pointing at MoonModules/MoonLight and origin at your fork:

git fetch upstream
git switch sdcard
git reset --hard upstream/main      # the branch now starts from today's main
git checkout ade3f71f -- src/platform/esp32/platform_esp32_sdmmc.cpp src/core/system/SdCardModule.h src/core/system/SdCardModule.cpp test/unit/core/unit_SdCardModule.cpp
# rework along points 1 to 7, then commit
git push --force-with-lease origin sdcard

The force-push keeps this PR and its discussion, and your first version stays reachable as ade3f71f to copy anything else from. If you prefer to keep the commit history, git rebase upstream/main works too: at each conflict, keep both your change and main's, git add the file and git rebase --continue.

Locally, uv run moondeck/check/check_code.py, uv run moondeck/check/check_prose.py and uv run moondeck/docs/build_docs.py --strict catch most of the above. SPI cards (esp_vfs_fat_sdspi_mount, which would bring the card to the C3 and the cheap breakout boards) can come later as a bus choice on the same module.

Looking forward to the FSEQ player!