From 4b1c8d16f72bb5d8f2eb8a2e8dde35abdd2f2a88 Mon Sep 17 00:00:00 2001 From: hathach Date: Mon, 29 Jun 2026 10:16:25 +0700 Subject: 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) --- examples/device/midi2_device/README.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'examples/device/midi2_device') diff --git a/examples/device/midi2_device/README.md b/examples/device/midi2_device/README.md index 1731dba57..3d140fce8 100644 --- a/examples/device/midi2_device/README.md +++ b/examples/device/midi2_device/README.md @@ -14,29 +14,40 @@ native UMP (Universal MIDI Packet) format with full MIDI 2.0 expression. - Program Change with Bank Select - JR Timestamps -## USB Descriptor +## USB Descriptors The device exposes both USB-MIDI 1.0 (Alt Setting 0) and USB-MIDI 2.0 (Alt Setting 1) as required by the USB-MIDI 2.0 specification. A MIDI 2.0 capable host (e.g. Windows MIDI Services) will select Alt Setting 1 for native UMP transport. Legacy hosts use Alt Setting 0 with automatic MIDI 1.0 fallback. -## Hardware +| Interface | Class driver | +|-----------|--------------| +| 0–1 | MIDI 2.0 (audio control + MIDI streaming) | -- Any RP2040 board with USB (e.g. Raspberry Pi Pico) -- LED on GPIO 25: steady = playing, slow blink = waiting for host +## Configuration + +Notable `tusb_config.h` settings: + +```c +#define CFG_TUD_MIDI2 1 +``` ## Building +CMake: + ```bash mkdir build && cd build -cmake -DBOARD=raspberry_pi_pico -DPICO_SDK_FETCH_FROM_GIT=on -G Ninja .. +cmake -DBOARD=raspberry_pi_pico .. cmake --build . ``` -## Flashing +Make: -Hold BOOTSEL, connect USB, drag `midi2_device.uf2` to the RPI-RP2 drive. +```bash +make BOARD=raspberry_pi_pico all +``` ## Testing -- cgit v1.3.1