MSC File Explorer¶

Example source: examples/host/msc_file_explorer

This host example implements an interactive command-line file browser for USB Mass Storage devices. When a USB flash drive is connected, the device is automatically mounted using FatFS and a shell-like CLI is presented over the board’s serial console.

Features¶

Automatic mount/unmount of USB storage devices
FAT12/16/32 filesystem support via FatFS
Interactive CLI with command history
Read speed benchmarking with dd
Support for up to 4 simultaneous USB storage devices (via hub)

Supported Commands¶

Command	Usage	Description
help	`help`	Print list of available commands
cat	`cat <file>`	Print file contents to the console
cd	`cd <dir>`	Change current working directory
cp	`cp <src> <dest>`	Copy a file
dd	`dd [count]`	Read sectors and report speed (default 1024 sectors)
ls	`ls [dir]`	List directory contents
pwd	`pwd`	Print current working directory
mkdir	`mkdir <dir>`	Create a directory
mv	`mv <src> <dest>`	Rename/move a file or directory
rm	`rm <file>`	Remove a file

Configuration¶

Notable tusb_config.h settings:

#define CFG_TUH_ENABLED       1
#define CFG_TUH_HUB           1
#define CFG_TUH_MSC           1
#define CFG_TUH_DEVICE_MAX    (3*CFG_TUH_HUB + 1)
#define CFG_TUH_MSC_MAXLUN    4

Build¶

CMake:

mkdir build && cd build
cmake -DBOARD=raspberry_pi_pico ..
cmake --build .

Make:

make BOARD=raspberry_pi_pico all

FreeRTOS variant¶

A FreeRTOS build is in examples/host/msc_file_explorer_freertos — identical MSC FatFS file-explorer CLI, running the host stack and CLI as FreeRTOS tasks.

Usage¶

Flash the firmware to your board.
Open a serial terminal (e.g. minicom, screen, PuTTY) at 115200 baud.
Plug a USB flash drive into the board’s USB host port.
The device is auto-mounted and the prompt appears:

TinyUSB MSC File Explorer Example

Device connected
  Vendor  : Kingston
  Product : DataTraveler 2.0
  Rev     : 1.0
  Capacity: 1.9 GB

0:/> _

Browsing Files¶

0:/> ls
----a    1234  readme.txt
d----       0  photos
d----       0  docs

0:/> cd photos
0:/photos> ls
----a  520432  vacation.jpg
----a  312088  family.png

0:/> cat readme.txt
Hello from USB drive!

Copying and Moving Files¶

0:/> cp readme.txt backup.txt
0:/> mv backup.txt docs/backup.txt

Measuring Read Speed¶

0:/> dd
Reading 1024 sectors...
  Data speed: 823 KB/s

Multiple Devices¶

When using a USB hub, multiple drives are mounted as 0:, 1:, etc. Use the drive prefix to navigate between them:

0:/> cd 1:
1:/> ls

Testing¶

This example is part of the TinyUSB HIL (Hardware-in-the-Loop) test suite. The HIL test automatically flashes, runs the example, and verifies MSC enumeration and file operations against a known USB drive.