Commander1024
ab6a8010ba
Separate operator guides from development contracts, relocate implementation notes under `docs/devel/`, and update cross-references and hardware tooling paths. Add getting-started, user administration, and firmware update guides while preserving firmware behavior.
89 lines
5.5 KiB
Markdown
89 lines
5.5 KiB
Markdown
# Developer documentation
|
|
|
|
This directory collects implementation contracts, research, design decisions,
|
|
regression procedures, and historical acceptance evidence. It is not the operator
|
|
manual: start with the [project README](../../README.md) for user documentation,
|
|
the [command reference](../command_reference.md) for commands, and the
|
|
[security operations checklist](../security_operations.md) for safe operation.
|
|
[Wiring](../wiring.md) and [electrical tests](../electrical_tests.md) remain beside
|
|
the user documentation because hardware safety and bring-up need that context.
|
|
|
|
## Firmware contracts and evidence
|
|
|
|
- [Flash partition layout](flash_layout.md): storage allocation, reserved partitions, and update boundaries.
|
|
|
|
- [Roadmap and acceptance record](roadmap.md): completed phases, retained scope,
|
|
historical evidence, and limits of acceptance.
|
|
- [Web administration contracts](web_administration.md): contributor-facing API,
|
|
ownership, lifecycle, and recovery details.
|
|
- [User/administration regression procedures](user_administration_tests.md):
|
|
reusable checks, including historical baselines explicitly marked as superseded.
|
|
- [HTTPS idle cleanup](https_idle_cleanup.md): HTTPD owner, SDK, and lifecycle contract.
|
|
- [Web admission diagnostics](web_admission_diagnostics.md): instrumentation and interpretation limits.
|
|
- [Web throughput diagnostics](web_throughput_diagnostics.md): counters, capture procedures, and evidence limits.
|
|
- Display design references: [Phase 7 display mockup](phase7_display_mockup.svg)
|
|
and [Phase 7C icon mockup](phase7c_icon_mockup.svg), not promises of current UI appearance.
|
|
|
|
Source code is authoritative for current behavior. A checklist is not a test result;
|
|
host doubles do not prove target timing, flash durability, power-loss recovery, or
|
|
physical electrical safety. Preserve dates, revisions, workload details, and explicit
|
|
limitations when recording new evidence. Overall user acceptance does not establish
|
|
that every proposed regression procedure was executed.
|
|
|
|
Markdown links are document-relative. Unless explicitly stated otherwise, source,
|
|
build, and test paths in code spans and commands are repository-root-relative.
|
|
Hardware notes identify retained artifact paths and any different command directory.
|
|
|
|
## Tests and asset provenance stay with their artifacts
|
|
|
|
Test fixtures, scripts, and contextual READMEs remain under [tests](../../tests/).
|
|
Examples include the [HTTPD idle suite](../../tests/web_httpd_idle/README.md),
|
|
[admission diagnostics suite](../../tests/web_diagnostics/README.md),
|
|
[web administration suite](../../tests/web_admin_transport/README.md), and
|
|
[browser UI suite](../../tests/web_ui_session/README.md). Read each suite's scope,
|
|
prerequisites, and execution instructions rather than assuming a single host-test command.
|
|
These links are navigation, not claims that tests ran during documentation cleanup.
|
|
|
|
[Web asset provenance and generation policy](../../web_assets/SOURCES.md) remains
|
|
with the web assets. Do not hand-edit generated embedded assets or regenerate them
|
|
as a side effect of documentation changes; preserve upstream licenses and attribution.
|
|
|
|
## Hardware research and design notes
|
|
|
|
The [contextual PCB README](../../hardware/PCB/README.md) stays with the editable
|
|
KiCad project, CAD, libraries, exports, and scripts. The board remains a draft,
|
|
not fabrication-ready. Development notes preserve the hardware-relative substructure:
|
|
|
|
- [Adafruit MAX3243 research](hardware/PCB/adafruit-research.md)
|
|
- [Button selection and evidence](hardware/PCB/button-notes.md)
|
|
- [DE-9 mechanical research](hardware/PCB/db9-mechanical-notes.md)
|
|
- [Module footprint notes](hardware/PCB/footprint-notes.md)
|
|
- [RS-232 reference footprint notes](hardware/PCB/rs232-footprint-notes.md)
|
|
- [PCB draft design and release gates](hardware/PCB/pcb-draft-notes.md)
|
|
- [Routing validation and historical evidence](hardware/PCB/validation/pcb-routing-summary.md)
|
|
|
|
Original reference/provenance READMEs remain beside their sources:
|
|
[Adafruit Eagle reference](../../hardware/PCB/reference/README.md) and
|
|
[DE-9 CAD reference](../../hardware/PCB/reference/db9-cad/README.md).
|
|
Relocation does not change licenses, validate provisional male-module assumptions,
|
|
or qualify the board for manufacture. Do not casually rerun destructive generators;
|
|
use the retained hardware README and each script's documented safeguards.
|
|
|
|
## Security maintenance and evidence
|
|
|
|
Contributor maintenance includes reviewing relevant ESP-IDF, wolfSSL/wolfSSH, and
|
|
bundled web-library upstream release/security notes, especially before an update.
|
|
A relevant issue needs a separate upgrade/mitigation decision and scoped validation;
|
|
this is not an ongoing CVE audit or a claim that the firmware is vulnerability-free.
|
|
Dependency patches, crypto upgrades, secure boot, encrypted NVS, and eFuse changes
|
|
are outside the accepted lightweight operating-checklist scope, not implicit work
|
|
items or properties of a deployed device. See the [Phase 9 record](roadmap.md#phase-9--security-and-production-hardening).
|
|
|
|
The original security checklist's commands and limits were source-reviewed against
|
|
application sources and the command reference at `f40c09c`. That provenance is not
|
|
a new build, device test, security audit, or verification of flash/eFuse settings;
|
|
verify current implementation when behavior changes. Keep the operator checklist
|
|
focused on actionable use and recovery rather than contributor dependency work.
|
|
Never put passwords, cookies, tickets, Wi-Fi secrets, private keys, or verifier
|
|
material in routine logs, documentation captures, or status output.
|