Title: USB SD Passthrough
Description: Use your device as a USB SD card reader
URL: /latest/usb/sd-passthrough/
Version: latest
Section: USB
Search index: /search-index.json

# USB SD Passthrough

> Use your device as a USB SD card reader

## On this page

- [How It Works](#how-it-works)
- [Usage](#usage)
- [Via CLI](#via-cli)
- [From the Display Menu](#from-the-display-menu)
- [Saved Preference](#saved-preference)
- [Requirements and Limitations](#requirements-and-limitations)

---

USB SD Passthrough exposes the device’s SD card to a host PC as a USB mass-storage drive, turning the board into a USB SD card reader. Requires an ESP32-S3 board with a physical SD card.
## How It Works
When started, the firmware releases the SD card from its own filesystem, hands the card to the TinyUSB mass-storage class, and enumerates on the host PC as a USB drive. The card stays owned by the USB host until passthrough is stopped, at which point the card is remounted and the serial console restored.
While active:
- The firmware cannot access the SD card (captures, logging, and other SD writes fail cleanly until passthrough stops).
- The USB serial console is unavailable — use WiFi or the WebUI terminal to run usbsd off.
- WiFi and the WebUI stay up.
## Usage
### Via CLI
usbsd on # start passthrough (card becomes a USB drive)
usbsd off # stop passthrough and remount the card
usbsd toggle # start if stopped, stop if active
usbsd status # show passthrough state and saved preference
### From the Display Menu
Navigate to Settings → Power → USB SD Passthrough and toggle it on. Toggling off stops passthrough and remounts the card.
### Saved Preference
The toggle state is remembered across reboots (settings get/set usb_msc), but passthrough never auto-starts at boot — the device always boots with a normal console and mounted SD card.
## Requirements and Limitations
- ESP32-S3 board with an SD card (Cardputer, Cardputer ADV, T-Deck, TEmbed C1101, T-Dongle-S3, and other S3 builds with SD support).
- Cannot run at the same time as BadUSB, USB Keyboard Mode, or USB host keyboard — stop those first.
- Boards whose SD card is wired to GPIO19/20 (the native USB pins) are unsupported.
- The disk identifies itself to the host with test vendor strings from the TinyUSB stack; the USB device itself shows as “Ghost ESP SD”.
- Always eject the drive on the host PC before running usbsd off.