Supporting Documentation Design Specifications

This document defines the required content for each traceable supporting documentation file. One SPEC element per chapter — specifying what each chapter must cover, not how it is written.

Document Version: 1.0 Last Updated: 2026-03-16

README.md

Design Specification: README Introduction and Project Link SPEC_DEV_README_INTRO

status: implemented tags: developer, documentation, readme links outgoing: REQ_DEV_README_1, SPEC_ARCH_LAYERS_1

Description: The README introduction section SHALL contain a short project description (≤3 sentences) and a prominent link to the GitHub Pages documentation site. Required content: Project name and one-line purpose statement What the device does (distance → LED feedback) Link to full documentation on GitHub Pages Explicitly excluded: Hardware specs, pin tables, build instructions, QEMU steps — these live in the Sphinx docs to avoid duplication. Traceability note: If SPEC_ARCH_LAYERS_1 changes the component structure, the project description in README SHALL be reviewed.

Design Specification: README Metadata Section SPEC_DEV_README_META

status: implemented tags: developer, documentation, readme links outgoing: REQ_DEV_README_1

Description: The README SHALL end with a metadata section covering project governance information. Required content: License statement with SPDX identifier Contributing pointer (link to CONTRIBUTING.md or inline note)

docs/01_overview/index.rst

Design Specification: Overview Index — Project Description SPEC_DEV_OV_INDEX_WHAT

status: implemented tags: developer, documentation, overview links outgoing: REQ_DEV_OV_INDEX_1, US_DISPLAY_1

Description: The “What Is This Project?” section SHALL describe the device purpose in plain language for a first-time reader. Required content: Core function: measures distance, shows result on LED strip Primary use case: parking aid Brief mention of key components (ESP32, ultrasonic sensor, LED strip)

Design Specification: Overview Index — Audience Section SPEC_DEV_OV_INDEX_WHO

status: implemented tags: developer, documentation, overview links outgoing: REQ_DEV_OV_INDEX_1, US_DEV_1, US_DEV_2

Description: The “Who Is This For?” section SHALL enumerate target audiences so readers can self-select relevant documentation. Required content: Garage user (end user) Maker / builder (hardware assembler) Developer (firmware / documentation contributor)

Design Specification: Overview Index — Navigation Section SPEC_DEV_OV_INDEX_NAV

status: implemented tags: developer, documentation, overview links outgoing: REQ_DEV_OV_INDEX_1

Description: The navigation / quick-links section SHALL provide a structured map of the documentation to reduce discovery friction. Required content: Links to key sections (overview, requirements, design, guides) Brief description of what each section contains

docs/01_overview/hardware.rst

Design Specification: Hardware Components Listing SPEC_DEV_OV_HW_COMPONENTS

status: implemented tags: developer, documentation, hardware links outgoing: REQ_DEV_OV_HW_1, REQ_SNS_1, REQ_LED_1

Description: The hardware components section SHALL list all required and optional components with specifications. Required content: ESP32 development board (type, flash size) HC-SR04 ultrasonic sensor (operating voltage, range) WS2812 LED strip (addressable, power requirements) Power supply notes Traceability note: SHALL be reviewed when REQ_SNS_1 or REQ_LED_1 change component specifications.

Design Specification: Hardware Pin Assignment Table SPEC_DEV_OV_HW_PINS

status: implemented tags: developer, documentation, hardware links outgoing: REQ_DEV_OV_HW_1, REQ_SNS_1, REQ_LED_1

Description: The pin configuration section SHALL provide a complete GPIO assignment table for the project. Required content: GPIO assignment table (pin number, signal name, connected component) Note on ESP32 strapping pins to avoid Wiring diagram reference or inline wiring notes

docs/01_overview/quick-start.rst

Design Specification: Quick Start — QEMU Path SPEC_DEV_OV_QS_QEMU

status: implemented tags: developer, documentation, quickstart, qemu links outgoing: REQ_DEV_OV_QS_1, REQ_SYS_SIM_1

Description: The QEMU emulation path section SHALL provide complete steps for a first-time run without hardware. Required content: Clone / open in Codespaces step Build command QEMU start command or VS Code task How to access the web interface from the host browser Traceability note: SHALL be reviewed when REQ_SYS_SIM_1 changes the emulation setup.

Design Specification: Quick Start — Hardware Path SPEC_DEV_OV_QS_HW

status: implemented tags: developer, documentation, quickstart, hardware links outgoing: REQ_DEV_OV_QS_1, REQ_SYS_HW_1

Description: The hardware path section SHALL provide complete steps for first-time flashing to physical hardware. Required content: Build command Flash command (idf.py flash monitor or web flasher reference) Initial WiFi AP setup step

docs/90_guides/qemu-emulator.rst

Design Specification: QEMU Guide — Starting QEMU SPEC_DEV_GUIDE_QEMU_START

status: implemented tags: developer, documentation, qemu links outgoing: REQ_DEV_GUIDE_QEMU_1, REQ_SYS_SIM_1, SPEC_ARCH_QEMU_1

Description: The QEMU start section SHALL document all methods for launching the emulator. Required content: Shell script invocation (run_qemu.sh / run_qemu_debug.sh) VS Code task alternative What the scripts do automatically (network bridge, etc.)

Design Specification: QEMU Guide — Accessing the Web Interface SPEC_DEV_GUIDE_QEMU_WEB

status: implemented tags: developer, documentation, qemu links outgoing: REQ_DEV_GUIDE_QEMU_1, REQ_SYS_SIM_2, REQ_WEB_1

Description: The web interface access section SHALL explain how to reach the running firmware’s HTTP server from the host browser. Required content: Host URL and port HTTP proxy requirement note (QEMU network architecture) Troubleshooting pointer if connection fails

Design Specification: QEMU Guide — Stopping QEMU SPEC_DEV_GUIDE_QEMU_STOP

status: implemented tags: developer, documentation, qemu links outgoing: REQ_DEV_GUIDE_QEMU_1, REQ_SYS_SIM_1

Description: The QEMU stop section SHALL document how to cleanly terminate the emulator. Required content: Shell script invocation (stop_qemu.sh) VS Code task alternative

docs/90_guides/switching-dev-modes.rst

Design Specification: Dev Modes Guide — How to Switch SPEC_DEV_GUIDE_MODES_HOW

status: implemented tags: developer, documentation, devmodes links outgoing: REQ_DEV_GUIDE_MODES_1, REQ_SYS_SIM_1

Description: The switching procedure section SHALL document all supported methods for changing between QEMU and hardware build targets. Required content: idf.py menuconfig method (recommended) Direct sdkconfig edit method One-liner command-line method Rebuild requirement after switching

Design Specification: Dev Modes Guide — What Changes Between Modes SPEC_DEV_GUIDE_MODES_DIFF

status: implemented tags: developer, documentation, devmodes links outgoing: REQ_DEV_GUIDE_MODES_1, REQ_SYS_SIM_1, REQ_NETIF_TUNNEL_5

Description: The behavioural differences section SHALL explain what the build system does differently in each mode. Required content: Which components are swapped (simulator vs. real driver) Network stack difference (UART tunnel vs. WiFi) CONFIG_IDF_TARGET_ESP32_QEMU / CONFIG_TARGET_EMULATOR guard explanation

docs/90_guides/debugging.rst

Design Specification: Debugging Guide — Quick Start in QEMU SPEC_DEV_GUIDE_DEBUG_START

status: implemented tags: developer, documentation, debugging links outgoing: REQ_DEV_GUIDE_DEBUG_1, REQ_SYS_SIM_1

Description: The quick-start section SHALL provide the minimal steps to attach a GDB debugger via VS Code. Required content: Launch QEMU debug mode (run_qemu_debug.sh / VS Code task) Start VS Code debug session (F5 / Run menu) What VS Code does automatically (attach, load symbols)

Design Specification: Debugging Guide — Debugging Features SPEC_DEV_GUIDE_DEBUG_FEATURES

status: implemented tags: developer, documentation, debugging links outgoing: REQ_DEV_GUIDE_DEBUG_1, SPEC_ARCH_LAYERS_1

Description: The debugging features section SHALL document the GDB capabilities available in the VS Code integration. Required content: Breakpoints (how to set, conditional breakpoints) Step-through (step over, into, out) Variable inspection (watch window, hover) Call stack navigation Debug console (direct GDB commands)

docs/90_guides/web-flasher.rst

Design Specification: Web Flasher Guide — Overview and Browser Requirements SPEC_DEV_GUIDE_FLASH_OVERVIEW

status: implemented tags: developer, documentation, flasher links outgoing: REQ_DEV_GUIDE_FLASH_1, REQ_SYS_NET_1

Description: The overview section SHALL explain what the web flasher is and what browser / hardware prerequisites are needed. Required content: What the web flasher does (browser-based, no Python/esptool needed) Supported browsers and Web Serial API requirement Hardware prerequisites (physical USB connection)

Design Specification: Web Flasher Guide — Flash Procedure SPEC_DEV_GUIDE_FLASH_STEPS

status: implemented tags: developer, documentation, flasher links outgoing: REQ_DEV_GUIDE_FLASH_1, REQ_SYS_NET_1

Description: The usage guide section SHALL provide step-by-step instructions for flashing firmware via the web flasher. Required content: Step 1: Build the firmware (idf.py build) Step 2: Start the web server (start-web-flasher.sh) Step 3: Open browser and connect device Step 4: Select firmware files and flash Troubleshooting pointer