Storage: expose the SD card as a USB drive #1

New Issue

2026-10-05T09:28:01Z

twisla commented

2026-10-05 09:28:01 +00:00

Idea

Add a setting that makes the SD card appear as a USB drive (USB mass storage) when the Cardputer is plugged into a computer. You could then copy Saved Pages, Tracks, Notes and .ota files with a file manager instead of rdbg.py get/put or taking the card out.

Why

Copying files over Wi-Fi with the Debug Console works, but it's slow and needs a Debug Build. Taking the microSD card out of a Cardputer is fiddly.

What's known

The firmware currently builds with ARDUINO_USB_MODE=1 (platformio.ini:19). That uses the ESP32-S3's built-in USB serial/JTAG peripheral, which can only be a serial port and can't act as a drive. A USB drive needs ARDUINO_USB_MODE=0, where TinyUSB drives the chip's USB OTG peripheral, with Arduino's USBMSC class on top.
Switching to TinyUSB changes the serial console and flashing. The console becomes TinyUSB's CDC port, so it disappears if the firmware crashes early. Getting into download mode goes through a 1200-baud trick, or holding G0. This touches scripts/flash.sh.
A FAT card can't be mounted by the firmware and the computer at the same time. While it's exposed, StorageService has to unmount it, and everything on the card has to wait or say so: the Gemini cache and Saved Pages, recording Tracks, Notes, Update from SD, and the Debug Console's get/put.
The card shares its SPI bus with the LoRa radio (platform/shared_spi.h) at 20 MHz. Expect roughly 1 MB/s at best, and once M3 is in, the radio has to share the bus during transfers.

Questions for the design round

Should the drive be always on when plugged in, behind a Settings toggle, or a mode you start, like a "USB drive" screen that shows it's busy and what's paused?
Do we keep the hardware serial port for Debug Builds and offer the drive only in release builds, or switch everything to TinyUSB?
How does the firmware get the card back safely: when the computer ejects it, when the cable is unplugged, or on a key press with a warning?
While the card is exposed, should Tracks recording be refused, or paused and resumed afterwards?
Should the drive be read-only as an option, for safety?

## Idea Add a setting that makes the SD card appear as a USB drive (USB mass storage) when the Cardputer is plugged into a computer. You could then copy Saved Pages, Tracks, Notes and `.ota` files with a file manager instead of `rdbg.py get/put` or taking the card out. ## Why Copying files over Wi-Fi with the Debug Console works, but it's slow and needs a Debug Build. Taking the microSD card out of a Cardputer is fiddly. ## What's known - The firmware currently builds with `ARDUINO_USB_MODE=1` (`platformio.ini:19`). That uses the ESP32-S3's built-in USB serial/JTAG peripheral, which can only be a serial port and can't act as a drive. A USB drive needs `ARDUINO_USB_MODE=0`, where TinyUSB drives the chip's USB OTG peripheral, with Arduino's `USBMSC` class on top. - Switching to TinyUSB changes the serial console and flashing. The console becomes TinyUSB's CDC port, so it disappears if the firmware crashes early. Getting into download mode goes through a 1200-baud trick, or holding G0. This touches `scripts/flash.sh`. - A FAT card can't be mounted by the firmware and the computer at the same time. While it's exposed, StorageService has to unmount it, and everything on the card has to wait or say so: the Gemini cache and Saved Pages, recording Tracks, Notes, Update from SD, and the Debug Console's `get`/`put`. - The card shares its SPI bus with the LoRa radio (`platform/shared_spi.h`) at 20 MHz. Expect roughly 1 MB/s at best, and once M3 is in, the radio has to share the bus during transfers. ## Questions for the design round 1. Should the drive be always on when plugged in, behind a Settings toggle, or a mode you start, like a "USB drive" screen that shows it's busy and what's paused? 2. Do we keep the hardware serial port for Debug Builds and offer the drive only in release builds, or switch everything to TinyUSB? 3. How does the firmware get the card back safely: when the computer ejects it, when the cable is unplugged, or on a key press with a warning? 4. While the card is exposed, should Tracks recording be refused, or paused and resumed afterwards? 5. Should the drive be read-only as an option, for safety? ## Related `src/services/storage_service.cpp`, `platformio.ini`, `scripts/flash.sh`, `docs/milestones/OTA.md` (Update from SD).

twisla added the

kind

feature

area/storage area/build

labels 2026-10-05 09:28:01 +00:00

twisla referenced this issue

2026-10-05 09:34:31 +00:00

Storage: a file manager App with copy, rename, delete and viewers #3