mirror of https://github.com/hathach/tinyusb.git synced 2026-08-18 11:02:16 +00:00

Files

hathach 4b1c8d16f7 docs: add build-doc tooling and a README for every example

Documentation tooling:
- Add the `build-doc` skill and `tools/build_doc.py` wrapper for local
  Sphinx builds (clean / -W / open).
- Enable Markdown (MyST) in conf.py and auto-collect
  examples/{device,host,dual}/*/README.md into a 3-level Examples nav
  (Examples > Device/Host/Dual > example), noting each page's source
  location and normalizing headings to a single H1.
- Remove the stale `.claude/commands/build-doc.md`; point the AGENTS.md
  Documentation section at the skill.

Example docs:
- Add a README.md for every device/host/dual example: what it does, USB
  interface table, notable tusb_config.h settings, generic CMake + Make
  build steps, and how to try it.
- Fold each *_freertos variant into its base README, noting the FreeRTOS
  source path and any RTOS-specific behavior.

Generated docs/examples/ output is git-ignored. Builds clean with
`sphinx-build -W`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-29 10:16:25 +07:00

3.3 KiB

Raw Blame History

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.

3.3 KiB Raw Blame History