Developer Documentation Requirements

This document specifies requirements for the Developer stakeholder role, covering firmware extensibility and traceable supporting documentation.

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

Overview

These requirements derive from Modular Firmware Extensibility (US_DEV_1) and Traceable Supporting Docume... (US_DEV_2). They govern:

• The modular component structure that allows firmware extension

• Traceable links between each supporting documentation file and the design specifications it describes

Governing Principle

Requirement: Supporting Documentation Traceability REQ_DEV_DOC_1

status: implemented tags: developer, documentation, traceability priority: mandatory links outgoing: US_DEV_2 links incoming: US_DEV_2, REQ_DEV_README_1, REQ_DEV_OV_INDEX_1, REQ_DEV_OV_HW_1, REQ_DEV_OV_QS_1, REQ_DEV_GUIDE_QEMU_1, REQ_DEV_GUIDE_MODES_1, REQ_DEV_GUIDE_DEBUG_1, REQ_DEV_GUIDE_FLASH_1, REQ_DEV_ENV_1, REQ_DEV_LIMITS_1

Description: The project SHALL maintain traceable links between supporting documentation files and the design specifications they describe, so that a spec change automatically brings the related documentation into the change impact scope. Acceptance Criteria: AC-1: Each in-scope file SHALL have a dedicated design spec AC-2: Each file-level spec SHALL define what content the file must cover (not how it is written) AC-3: A change to a linked spec SHALL list the corresponding doc file in its change impact analysis

Overview Documentation Requirements

Requirement: README Content Scope REQ_DEV_README_1

status: implemented tags: developer, documentation, readme priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_README_INTRO, SPEC_DEV_README_META

Description: README.md SHALL be intentionally minimal — a single entry point that orients the reader and points to the full documentation. It SHALL NOT duplicate content that lives in the Sphinx docs. Acceptance Criteria: AC-1: README SHALL contain a short project description (≤3 sentences) AC-2: README SHALL link to the GitHub Pages documentation site AC-3: README SHALL contain a license statement AC-4: README SHALL contain a contributing pointer AC-5: README SHALL NOT contain detailed hardware specs, pin tables, or step-by-step build instructions (those live in the Sphinx docs)

Requirement: Overview Index Content REQ_DEV_OV_INDEX_1

status: implemented tags: developer, documentation, overview priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_OV_INDEX_WHAT, SPEC_DEV_OV_INDEX_WHO, SPEC_DEV_OV_INDEX_NAV

Description: docs/01_overview/index.rst SHALL serve as the project portal page, providing orientation and navigation for all audiences. Acceptance Criteria: AC-1: SHALL describe what the project does in plain language AC-2: SHALL list the target audiences (garage user, maker, developer) AC-3: SHALL provide a section navigation map for the documentation AC-4: Overlap with README intro is acceptable; detail beyond README is expected here

Requirement: Hardware Specifications Content REQ_DEV_OV_HW_1

status: implemented tags: developer, documentation, hardware priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_OV_HW_COMPONENTS, SPEC_DEV_OV_HW_PINS

Description: docs/01_overview/hardware.rst SHALL document all hardware components and wiring required to build the device. Acceptance Criteria: AC-1: SHALL list required components with specifications AC-2: SHALL provide GPIO pin assignment table AC-3: SHALL reflect the component specs in docs/12_design/ (distance sensor, LED controller) AC-4: SHALL be updated when hardware-related design specs change

Requirement: Quick Start Content REQ_DEV_OV_QS_1

status: implemented tags: developer, documentation, quickstart priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_OV_QS_QEMU, SPEC_DEV_OV_QS_HW

Description: docs/01_overview/quick-start.rst SHALL provide a working first-run experience for both QEMU and hardware paths. Acceptance Criteria: AC-1: SHALL cover the QEMU emulation path (no hardware required) AC-2: SHALL cover the hardware flashing path AC-3: SHALL be updated when REQ_SYS_SIM_1 or the build process changes

Guide Documentation Requirements

Requirement: QEMU Emulator Guide Content REQ_DEV_GUIDE_QEMU_1

status: implemented tags: developer, documentation, qemu priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1, REQ_SYS_SIM_1 links incoming: SPEC_DEV_GUIDE_QEMU_START, SPEC_DEV_GUIDE_QEMU_WEB, SPEC_DEV_GUIDE_QEMU_STOP

Description: docs/90_guides/qemu-emulator.rst SHALL document how to start, use, and stop the QEMU emulator for this project. Acceptance Criteria: AC-1: SHALL cover starting QEMU (script and VS Code task) AC-2: SHALL cover accessing the web interface from the host AC-3: SHALL cover stopping QEMU AC-4: SHALL be updated when the QEMU setup (REQ_SYS_SIM_1) changes

Requirement: Switching Dev Modes Guide Content REQ_DEV_GUIDE_MODES_1

status: implemented tags: developer, documentation, devmodes priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1, REQ_SYS_SIM_1 links incoming: SPEC_DEV_GUIDE_MODES_HOW, SPEC_DEV_GUIDE_MODES_DIFF

Description: docs/90_guides/switching-dev-modes.rst SHALL explain how and when to switch between QEMU emulation and real hardware targets. Acceptance Criteria: AC-1: SHALL document the menuconfig / sdkconfig approach AC-2: SHALL document what changes between modes AC-3: SHALL be updated when the QEMU/hardware build split changes

Requirement: Debugging Guide Content REQ_DEV_GUIDE_DEBUG_1

status: implemented tags: developer, documentation, debugging priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_GUIDE_DEBUG_START, SPEC_DEV_GUIDE_DEBUG_FEATURES

Description: docs/90_guides/debugging.rst SHALL document how to debug the firmware in QEMU using VS Code and GDB. Acceptance Criteria: AC-1: SHALL cover GDB attach via VS Code launch config AC-2: SHALL cover breakpoints, step-through, variable inspection AC-3: SHALL be updated when the dev container or debug config changes

Requirement: Web Flasher Guide Content REQ_DEV_GUIDE_FLASH_1

status: implemented tags: developer, documentation, flasher priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_GUIDE_FLASH_OVERVIEW, SPEC_DEV_GUIDE_FLASH_STEPS

Description: docs/90_guides/web-flasher.rst SHALL document how to flash firmware to hardware using the browser-based web flasher. Acceptance Criteria: AC-1: SHALL list browser requirements (Web Serial API) AC-2: SHALL cover the full flash procedure (build → start server → flash) AC-3: SHALL list hardware prerequisites AC-4: SHALL be updated when the web flasher tool changes

Development Environment Requirements

Requirement: Supported Development Environments REQ_DEV_ENV_1

status: implemented tags: developer, devcontainer, codespaces priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_ENV_OPTIONS, SPEC_DEV_ENV_USAGE

Description: docs/90_guides/devcontainer.rst SHALL document which development environments are officially supported and which are not. Acceptance Criteria: AC-1: Devcontainer (VS Code + Docker) SHALL be listed as supported AC-2: GitHub Codespaces SHALL be listed as supported AC-3: Native Windows SHALL be explicitly listed as not supported, with rationale (ESP-IDF toolchain complexity requires container) AC-4: Container setup steps SHALL be documented

Requirement: Known Limitations Documentation REQ_DEV_LIMITS_1

status: implemented tags: developer, limitations, known-issues priority: mandatory links outgoing: US_DEV_2, REQ_DEV_DOC_1 links incoming: SPEC_DEV_LIMITS_STRUCTURE

Description: docs/90_guides/known-issues.rst SHALL provide a maintained record of known limitations with traceable origins. Acceptance Criteria: AC-1: Known issues SHALL be organised into categories AC-2: Each entry SHALL reference the relevant spec or component AC-3: The file’s structure and maintenance process SHALL be governed by a design spec (not the issues themselves)