USB Mass Storage on SPI-SD boards, and a signal for the cable being pulled

[jpirnay]

Summary

USB Mass Storage was reachable only from the native-SDMMC backend, because detachFilesystemForRawAccess() lived behind FREEINK_SD_SDMMC. That kept the capability to the X4 Pro / de-link / Paper Mono class of board and locked out every SPI-SD board. This opens it to them, and adds the one signal an ESP32-S3 needs in order to notice that the cable was pulled.

Three additive commits. No board changes behaviour unless its own env sets FREEINK_CAP_USB_MSC.

1. The SPI path needs no second block-device driver

SdFat's SdCardInterface already derives from FsBlockDeviceInterface and implements the same readSector(s)/writeSector(s) contract SdmmcBlockDevice does — the card object is the block device. So the SPI path only has to drop the FsVolume while keeping the card session alive: FsVolume::end(), deliberately not SdFat::end(), which would also end the card session the USB host is about to read through. Remounting goes back through begin(), whose sd.begin() re-runs SdCard::begin() on the same factory-owned card object.

rawBlockDevice() now answers on both backends and returns the interface type rather than the SDMMC-specific one. It had no callers, so this is not a break.

2. USE_BLOCK_DEVICE_INTERFACE has to be on for that to compile

SdSpiCard derives from FsBlockDeviceInterface only when USE_BLOCK_DEVICE_INTERFACE (or HAS_SDIO_CLASS) is set; otherwise it is a plain concrete class and sd.card() cannot be returned as one. SdFat compiles as its own library, so the option has to be appended to every lib builder's env — which is exactly what the SDCardManager build hook already does for USE_UTF8_LONG_NAMES, so it grows a second, conditional define.

It is coupled to FREEINK_CAP_USB_MSC rather than turned on globally, to keep the vtable and the indirect sector calls off boards that would gain nothing — notably the C3, which has no USB-OTG peripheral and can never serve MSC at all. The raw-access functions are guarded to match and link as nullptr-returning stubs when the option is absent, so a board that never asked for USB Drive still builds unchanged.

3. An S3 device cannot see an unplug through TinyUSB

Arduino's tinyusb init passes otg_io_conf = NULL (cores/esp32/esp32-hal-tinyusb.c:140), so no VBUS line is routed to the OTG core through the GPIO matrix and IDF forces B-session-valid permanently on. The core never sees session end, no DCD_EVENT_UNPLUGGED is raised, and tud_mounted() stays true after the cable is gone — so UsbMassStorageState::Disconnected is unreachable and an MSC session has no way to end itself. Device-observed on a LilyGo T5 S3: transfers worked, then pulling the cable left the reader on its Connected screen forever.

Two signals, because no single one covers every board:

Signal	Source	Ambiguous?
UsbMassStorage::hostSuspended()	tud_suspended() — bus idle (no SOF >3 ms), detected by the core independently of VBUS, so it survives the forced B-valid	Yes — a host suspending an idle bus is identical. Exposed as a hint; callers are told to require persistence
BatteryMonitor::isExternalPowerPresent()	BQ25896 REG0B: VBUS_STAT[7:5] + PG_STAT[2], out of the same register readGaugeCharging() already reads for CHRG_STAT	No — a physical reading of the input rail

isExternalPowerPresent() is deliberately not isCharging(): a full battery stops charging with the cable still attached, so charge state reports "unplugged" while plugged in — the exact failure mode that makes charge-based USB inference wrong. There is deliberately no gauge fallback either: the BQ27220 measures the battery, not the input rail, so a board with a gauge but no charger IC genuinely cannot see this. It reports known = false and callers must branch on it, rather than have the SDK answer "no external power" from a sensor that cannot observe external power.

Also: a comment correction

FREEINK_CAP_USB_MSC's comment said the capability forces the build into USB-OTG mode (ARDUINO_USB_MODE=0). It does not have to: a firmware can keep ARDUINO_USB_MODE=1, so USB Serial/JTAG stays the board's normal personality for monitoring and flashing, and switch the shared PHY to OTG at runtime for the duration of a transfer. Both X4 Pro and LilyGo T5 S3 ship that way in CrossPoint. The real build requirement — which was not documented — is the platform's prebuilt Arduino core, whose TinyUSB component carries CONFIG_TINYUSB_MSC_ENABLED; an env that rebuilds the core from source (custom_sdkconfig / custom_component_remove) drops that component and USBMSC will not link.

Testing

• LilyGo T5 S3 (SPI backend): validated on hardware, 2026-09-03. The host mounts the card, transfers work over the raw-block-device path, and pulling the cable now ends the session and returns the reader to Home.
• X4 Pro (SDMMC backend): builds, not run on hardware. Its behaviour is unchanged by this PR except for the rawBlockDevice() return type and the guard restructure, but I want to be explicit that I have not exercised the SDMMC path.
• Builds clean for x4pro, lilygo_t5s3 and the C3 default env (the last is the one that must not pick up USE_BLOCK_DEVICE_INTERFACE).

Branched from main; the work originally sat on top of #51 and was rebased off it, so this PR carries no LilyGo board changes and is independent of that one.

Attribution

Builds on the USB-MSC work by @uxjulia (#36 feat/x4-pro-usb-support, #53, #57) and @itsthisjustin (79a82d5, the capability flag). Co-authored-by trailers are on the commits.

AI usage

PARTIALLY. An AI coding assistant was used for the investigation, for drafting the code comments, and for this description. The hardware bring-up and the device validation on the LilyGo were done by hand on the board.

[itsthisjustin]

Interesting. Will this allow it to work on the sticky or no?

[itsthisjustin]

Interesting. Will this allow it to work on the sticky or no?

[jpirnay]

Interesting. Will this allow it to work on the sticky or no?

I don't have a sticky device to check, but I am doubting it would support it: looking at the schematics :

• The Type-C connector's only D+/D− pair (USB_DP/USB_DN) goes to the CH343P, pins UD+/UD−; its TXD/RXD land on UART0.
• GPIO19/20 — the S3's native USB pins — are spent on the PDM microphone (PDM_CLK / PDM_DATA). So there's nothing to reconnect even in principle.
• One USB connector, and the pogo pins carry no USB nets.

[itsthisjustin]

@jpirnay can you solve conflicts? I ended up having an issue I think maybe you also fixed here but maybe we fixed it differently? I'd like to get this in. I had to trigger disconnect on suspend after we upgraded to the latest TinyUSB

[jpirnay]

Sure, will look at it tonight

[jpirnay]

@itsthisjustin conflicts resolved — rebased onto main at 48f5949.

Both conflicts were in UsbMassStorage, and both were exactly the overlap you described: you landed the same fix independently in 4837c11 after hitting it on the newer TinyUSB, converging on the same hostSuspended() name.

Resolution:

• Code takes yours: _active && tud_mounted() && tud_suspended(). On the ESP32-S3 tud_mounted() is always true — B-session-valid is forced on, which is the whole reason the hint has to exist — so the extra term costs nothing there. On a board that can see an unplug it stops a never-mounted session reporting "suspended" while state() already answers Disconnected. Strictly better than what this branch had.
• The declaration keeps this branch's comment, which records why tud_mounted() cannot answer the question on the S3 (Arduino's tinyusb init passes otg_io_conf = NULL, so no VBUS line reaches the OTG core and IDF forces B-session-valid on) and why the result is a hint callers must require to persist rather than a verdict.

One follow-up commit on top: the merge left hostSuspended() declared twice in the no-capability stub class, because both sides declared it in different positions relative to disconnectHost() and the textual merge kept both. That broke every build without FREEINK_CAP_USB_MSC; caught it on an ESP32-C3 env and dropped the duplicate.

Re-validated on a LilyGo T5 S3 after the merge: the host still mounts the card over the SPI raw-block-device path, and pulling the cable still ends the session and returns the reader to Home. Also builds clean for the X4 Pro (SDMMC backend) and a C3 env, which is the one that must not pick up USE_BLOCK_DEVICE_INTERFACE.