Hardware research

Standalone repository: developing-today/hardware-doc.

Device and component research, decomposed to primary evidence — netlists parsed from vendor EDA files, firmware images unpacked, datasheets mined — with every claim carrying its source and evidence status.

How this repo is used

It is normally checked out beside the repo that consumes it and symlinked into place:

<repo-parent>/
├── code/                        consuming repo (config, infra, …)
│   └── doc/hardware  ───────────┐ symlink, created by scripts/hardware-doc-init.sh
├── hardware-doc/         ←──────┘ THIS REPO
└── repo-archive/        bulk artifacts moved out of here (separate repo, usually unpublished)

It is not a submodule and not vendored into the consuming repo: at ~440 MB it would make every clone of that repo roughly 6.5× larger. Consumers clone it on demand.

git clone https://github.com/developing-today/hardware-doc.git
./scripts/init.sh        # only needed if the archive is not already a sibling

scripts/init.sh points archive/ and scratch/ at the sibling artifact archive. A fresh clone usually needs nothing — the symlinks are committed relative, so they already resolve when repo-archive/ sits beside this repo. Run it when the archive is elsewhere, newly added, or this repo is a linked worktree. It never clones and never deletes.

Resolving the sibling archive

../repo-archive is a sibling of the real repository root — not of your working directory, and not ~. Under a git worktree resolve it via the common dir:

ARCHIVE="$(dirname "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")")/repo-archive"

--git-common-dir rather than --show-toplevel: inside a linked worktree the toplevel is the worktree, whose parent is the wrong directory. The archive holds bulky derived artifacts moved out of this repo; every one leaves a *.ARCHIVED.md placeholder here carrying size, SHA-256, upstream commit/author/licence and multiple recovery URLs, so the archive is optional — its absence costs you convenience, not information.

repo-archive is itself a git repository, but it is normally unpublished or private — at multiple gigabytes it is impractical to host alongside this one. Treat it as a local companion: if you have it, placeholders resolve to real bytes; if you do not, they resolve to recovery URLs.

The archive/ symlink

When the archive is present locally it is reachable at ./archive/ — a tracked symlink to ../repo-archive. That gives *.ARCHIVED.md placeholders a stable in-repo path to point at.

Both tracked symlinks in this project (archive here, doc/hardware in a consuming repo) are committed relative, and hardware-doc-init.sh swaps in an absolute path only where the relative form cannot resolve — then marks the path --skip-worktree, because .gitignore has no effect on tracked files. See AGENTS.md § Symlinks and --skip-worktree for the caveat that matters: while the flag is set, git will not update that path.

See AGENTS.md for working conventions and .agents/skills/hardware-device-research/SKILL.md for the research method.

• Devices
• Components and interfaces
• Vendor documentation-sourcing guides
• Cross-cutting guides — Espressif · hardware subsystems · markets and sourcing · reverse engineering · research technique · NixOS host
• Artifact manifest
• Inventory
• Verification report
• Component download failures

All research in this initial set was retrieved 2026-08-21. Downloaded files are checksummed from local bytes; see each device/component record for provenance and caveats. Relative-link validation covers authored Markdown outside artifacts/; bundled upstream Markdown is preserved as supplied and is not claimed to be link-clean.

• Size audit — where the 442 MB is, what is reproducible, what must stay

Research passes

Pass	Date	Scope
Waveshare ESP32-S3-Knob-Touch-LCD-1.8	2026-08-21 → 2026-08-23	One device, decomposed into ~22 component records; Espressif and Waveshare vendor guides created
Framework-guide extraction and archival	2026-08-24	Distilled ESP-IDF (×5 target builds), ESP-ADF, ESP-IoT-Solution and esp-dev-kits PDFs into guides/espressif/, then archived the ~219 MB of regenerable framework PDFs out of the repository. Chip datasheets, TRMs, errata, hardware-design guidelines and board design files were all retained. Per-directory archive records with SHA-256 and verified download URLs: u4wdh · s3r8 · p4 · P4 boards
Espressif ESP32-P4 and its official development boards	2026-08-21	ESP32-P4 component record plus five board records under devices/espressif/. Established the real P4 board lineup (no Korvo board exists on P4); corrected three claims in the Espressif vendor guide
Cross-link completion, vendor guides and market docs	2026-08-24	17 new vendor sourcing guides (10 for manufacturers whose parts we document, 7 anticipatory), each with product lines, part-numbering conventions, distribution channels, URL patterns verified by live probe with negative controls, and an explicit evidence boundary. Added manufacturer back-links to every manufacturer-specific component record. New markets and sourcing guides and the Espressif ecosystem map. Corrected a WCH finding: the downloads/<PART>DS1_PDF.html URLs return an identical 4,305-byte SPA shell for every path, existing or not
Host toolchain: NixOS embedded development	2026-08-30	New guides/nixos/ covering ESP-IDF on NixOS (5.5.2 and 6.0.1 side by side, and why installing the package alone yields no idf.py), package availability in the locked nixpkgs with dated absences, and why LVGL/sensor libraries are project dependencies. New SquareLine vendor guide — the Linux build is a ZIP, not an AppImage, and the CDN returns HTTP 206 for non-existent paths. The 172 MiB proprietary editor ZIP is archived out of the repository with a reacquisition record. ⚠ Nothing in this pass was built or rebuilt

Quick entry points

• How do I build firmware from this machine? — NixOS as an embedded development host

• Which Espressif chip should this be? — ecosystem and product lines

• Which of these boards should I use? — device comparison matrix — all fourteen documented devices side by side

• How many PCNT units / DMA channels / UARTs does this chip have? — SoC peripheral reference

• How do I drive this display? — display interfaces · e-paper specifically — e-paper displays

• Where should I buy this, and will the docs survive? — vendor and marketplace comparison

• Is this board a clone, and what differs? — clones, siblings and variants

• How do I recover a pinout the vendor never published? — netlists from vendor EDA files

• Espressif ESP32-P4 — chip · board index · shared board artifacts

• Espressif ESP32-S3 — ESP32-S3R8, including the Bluetooth Classic limitation

• How to obtain any Espressif document — vendor guide

• Espressif framework knowledge — ESP-IDF peripheral capabilities · ESP-ADF audio pipelines · ESP-IoT-Solution components

Verification reports

• Seeed XIAO ESP32S3 Sense — 2026-08-24: 1,092 files, 42 artifacts validated, 0 broken links, 0 hardware-tested claims.