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/audio_test/README.md | 54 ++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 examples/device/audio_test/README.md (limited to 'examples/device/audio_test') diff --git a/examples/device/audio_test/README.md b/examples/device/audio_test/README.md new file mode 100644 index 000000000..735999098 --- /dev/null +++ b/examples/device/audio_test/README.md @@ -0,0 +1,54 @@ +# Audio Test Microphone + +A minimal USB Audio Class 2.0 (UAC2) microphone that streams a generated test signal, useful for verifying the audio device stack end to end. + +## What it does + +- Enumerates as a UAC2 microphone with 1 input channel at 48 kHz, 16-bit. +- An audio task fills a buffer with a continuously incrementing 16-bit ramp counter and writes it to the IN endpoint every 1 ms, simulating data from an I2S source. The counter resets when the streaming interface is closed. +- Handles UAC2 control requests: feature-unit mute/volume, clock-source sample-rate and clock-validity, and input-terminal connector. +- Blinks the on-board LED to indicate USB state (not mounted / mounted / suspended). + +## USB Descriptors + +| Interface | Class driver | +|-----------|--------------| +| 0–1 | UAC2 audio (control + streaming), 1-channel microphone input | + +## Configuration + +Notable `tusb_config.h` settings: + +```c +#define CFG_TUD_AUDIO 1 +#define CFG_TUD_AUDIO_FUNC_1_SAMPLE_RATE 48000 +#define CFG_TUD_AUDIO_ENABLE_EP_IN 1 +#define CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX 1 +#define CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX 2 // 16-bit +#define CFG_TUD_AUDIO_EP_SZ_IN TUD_AUDIO_EP_SIZE(TUD_OPT_HIGH_SPEED, CFG_TUD_AUDIO_FUNC_1_SAMPLE_RATE, CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX, CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX) +#define CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX CFG_TUD_AUDIO_EP_SZ_IN +``` + +## Building + +CMake: + +```bash +mkdir build && cd build +cmake -DBOARD=raspberry_pi_pico .. +cmake --build . +``` + +Make: + +```bash +make BOARD=raspberry_pi_pico all +``` + +## FreeRTOS variant + +A FreeRTOS build is in `examples/device/audio_test_freertos` — identical single-channel UAC2 test microphone, with the device, audio, and LED-blink work split across FreeRTOS tasks. + +## Try it + +The device appears as a single-channel USB microphone. On Linux, list it with `arecord -l` and capture with `arecord` (for example `arecord -D hw:CARD=MicNode -c 1 -f S16_LE -r 48000 test.wav`); the recorded samples form a rising ramp. The included `src/plot_audio_samples.py` records and plots the signal (requires `sounddevice` and `matplotlib`). -- cgit v1.3.1