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 · NFC · LoRa · 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
Seven-session sweep: Xteink, M5Stack DinMeter / Cardputer / LoRa expansions, LilyGO K230 and T-Display-S3, LoRa generations	2026-09-04 → 2026-09-07	~40 device records and ~90 component records across seven parallel sessions, indexed here on 2026-09-07. New device families: Xteink pocket e-readers (6), LilyGO (16, including the repository's first RISC-V device, the K230), and the expanded M5Stack family — DinMeter ×2, five Cardputers and eight Cardputer radio expansions. Three new vendor guides (Canaan, LilyGO, Semtech) and three cross-cutting guides (LoRa radio generations, parallel 8080 LCD buses, RISC-V and vendor-SDK toolchains on NixOS). ⚠ Nothing in this pass was verified on physical hardware, and each session was forbidden from editing shared indexes — the merge, its deferrals and its parked corrections are recorded in research/passes/index-merge/README.md
Round two: Xteink re-survey, schematic net-tracing, certification and market	2026-09-11	Three parallel sessions, integrated the same day. ⭐ Overturned the sweep's Xteink certification finding: Xteink holds five FCC Original Equipment grants under grantee code 2BTR9, and enumerating that code surfaced a sixth device the vendor has never announced — the X4 Light. Dated the X4 Classic launch (2026-09-06, USD 79) and the X4's withdrawal. 291 schematic PDFs assessed and five boards net-traced from PDF alone — Altium exports embed CO/PI/NL tokens at item coordinates, which is what made it possible (guide). 32 device records gained a certification-and-compliance.md, each carrying its positive and negative controls. 174 FCC exhibits split: 59 retained in-repo (57.8 MiB — internal photographs, including the first public teardown of the Xteink X4), 106 archived with self-sufficient placeholders (130.6 MiB); FCC exhibits are US Government public records, redistribution allowed. New guides: finding certification records, tracing nets from schematic PDFs; new Xteink vendor guide. ⚠ Still nothing verified on physical hardware. ⚠ devices/m5stack/papermono/** was owned by a live session throughout and was not touched — its deferrals are in research/passes/index-merge/deferred-round2.md

| Preprint repositories and the wider literature | 2026-09-01 → 2026-09-11 | All 78 entries on Wikipedia's List of preprint repositories plus what that list omits, in research/preprint-repositories/ — 40 records, ~23,000 lines. Deep records for the servers carrying hardware/software/systems work (arXiv, Cryptology ePrint, HAL, Zenodo, TechRxiv, ECSarXiv); grouped records for the rest. 160 landmark papers and theses individually verified by fetching each identifier and machine-checking its title — collected by field. ⭐ Corrected six Wikipedia claims by measurement (OSF Preprints >1,000,000 → 200,519 hosted; ScienceOpen → ~3,584; Synthical hosts nothing at all). Extended beyond preprints to the lawful full-text ladder (USENIX has been paywall-free since 2008 — the real home of the systems literature), government and university technical reports (the RISC-V ISA specs are six Berkeley EECS reports, verified), the computing servers Wikipedia omits (ECCC, OpenReview), theses and dissertations (the global ETD discovery layer collapsed in 2025–26; EThOS is metadata-only since the British Library cyberattack), dead-site recovery (the DEC SRC/WRL/CRL series survives only as a 2007 bitsavers mirror), and bulk libraries and their copyright status. ⚠ No artifacts retained; no shadow-library service probed and no mirror domains recorded anywhere |

Quick entry points

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

• Where is the paper for this, and can I trust it? — preprint repositories · landmark papers by field · reliability and durability

• I have a citation and want the PDF, legally — open-access full-text ladder

• A vendor doc portal or datasheet host has died — recovering dead technical sites

• 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

• How do I bring up an NFC reader, and why does it read nothing? — NFC guide — standards, antenna matching, and symptom-to-cause debugging

• What do SF, BW and CR actually cost me? — LoRa guide — airtime, battery and duty-cycle arithmetic, LoRa vs LoRaWAN vs Meshtastic, and honest range estimation

• 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

• Which LoRa chip is this, and what breaks if I swap it? — LoRa radio generations — the four generations of Semtech silicon, and the migration cost. ⚠ The LLCC68 is pin-compatible with the SX1262 and 19 dB worse; the SX1268 cannot reach 868/915 MHz at all

• My display is black and the library says it initialised — parallel Intel-8080 LCD buses on ESP32 — why the display-library choice matters more than the board, and a debugging checklist

• How do I build for a RISC-V board with a vendor SDK? — RISC-V and vendor-SDK toolchains on NixOS — why pkgsCross.riscv64-* is not a substitute for XuanTie GCC

• I want a cheap pocket e-reader I can reflash — Xteink family — six products, four ESP32-based. ⚠ The X4 Pro is not an enhanced X4; firmware for one will not run on the other

• Which LilyGO T-Display-S3 is this actually? — LilyGO family index — one name covering eleven boards, eight display controllers and four chargers. Sourcing: LilyGO vendor guide

• How do I add LoRa, sub-GHz or NFC to a Cardputer? — M5Stack Cardputer expansions — and note that only the ADV + Cap LoRa-1262 combination has an upstream Meshtastic variant

• How do I obtain a Semtech, Canaan or LilyGO document? — Semtech · Canaan · LilyGO vendor guides

• Is this thing certified, and how would I even check? — finding certification records — FCC grantee-code enumeration, which regulatory databases are actually reachable, and the positive/negative controls that make an absence finding mean anything. ⚠ fccid.io serves 403 to a Chrome UA and 200 to curl — the honest user agent is the one that works

• The vendor published a schematic PDF and nothing else — tracing nets from schematic PDFs — Altium exports embed invisible CO/PI/NL tokens at item coordinates, which is what makes a net list recoverable with poppler alone. ⚠ KiCad and EAGLE exports often outline their text to vector paths and are then untraceable — but a usable second export often sits in the same directory

• What has this vendor certified that it never announced? — Xteink vendor guide — the worked example: enumerating grantee code 2BTR9 surfaced the X4 Light, a device with no announcement, no listing and no price

Verification reports

• Preprint and scholarly-literature repositories — 2026-09-11 re-probe of a 2026-09-01 → 07 pass: 40 records, 78/78 list coverage, 160 identifiers verified, 0 broken links. Five findings corrected (Berkeley EECS restored at a new path; Anubis answers HTTP 200 not 403; CERN CDS and ETH no longer walled; OpenReview's API block was transient; CogPrints' recovery route degraded) and one dating error flagged.
• Seeed XIAO ESP32S3 Sense — 2026-08-24: 1,092 files, 42 artifacts validated, 0 broken links, 0 hardware-tested claims.
• M5Stack PaperMono — 2026-09-01: 50 authored files (~14,700 lines), 23 artifacts validated, 0 broken links, 0 hardware-tested claims; 5 hypotheses refuted, 10 conflicts left open.
• Seven-session device sweep — 2026-09-04 → 2026-09-07: the umbrella report for the whole pass. 469 authored files, 10 387 relative links checked / 1 broken (pre-existing, in a vendored upstream README), 61 artifacts magic-byte validated / 0 mismatches, 0 device-record orphans, 0 deletions on any shared file, HEAD unchanged. ⚠ Zero on-device claims.
• Xteink device family — 2026-09-04: Xteink X3, X4, X4 Pro, X4 Classic, S4 and Nano.
• M5Stack DinMeter — 2026-09-04: DinMeter (K134) and DinMeter v1.1 (K134-V11).
• M5Stack Cardputer family — 2026-09-04: 48 authored files, 331/331 links, 6/6 artifact hashes, 0 protected files touched.
• LilyGO T-Display K230 — 2026-09-04: T-Display K230 and K230 Kit, the repository's first RISC-V device.
• Xteink family, round two — 2026-09-11: the X4 Classic launch at USD 79 and the X4's withdrawal, the undocumented X4 Light found by FCC grantee enumeration, and three new custodians for the X4 Pro.
• Certification, market and adjudication pass — 2026-09-11: closes two of the 2026-09-04 sweep §6 gaps and overturns its Xteink certification finding. 26 FCC filings, 174 exhibits, with positive and negative controls.
• Schematic net-tracing pass — 2026-09-11: 291 schematic PDFs assessed, five boards fully traced from PDF alone; per-file verdicts in traceability-census.md.
• Scratch relocation — 2026-09-20: scratch/ emptied. Every subject moved by mv to the archive tier at its owning record's repo-relative path, verified by file count and tree digest, with a README.md written at each destination. Two authored pass reports were promoted into this repository (research/passes/) because 33 records cite them. 116 MB turned out not to be hardware material at all — swept indiscriminately out of /tmp by earlier passes — and is preserved, unfiled and clearly labelled, in repo-archive/scratch-foreign/. ⚠ Use the relocation table to resolve any scratch/… path you meet in an older record.