ssmithxandClaude Sonnet 5
a9dd08ac4d
pciutils/usbutils aren't guaranteed present, especially on minimal or live-boot systems — exactly the kind of environment someone testing Archipelago compatibility is likely to be running. Rewrote WiFi/ethernet detection to read /sys/class/net/$iface/device directly first (vendor, device, driver via uevent — always available, no package needed), the same approach as manually finding a chip by hand: enumerate interfaces, read vendor/device IDs from sysfs, get the driver from uevent/modalias. Only reaches for lspci/lsusb, when installed, to turn a hex ID into a friendly name; falls back to a small built-in vendor-ID table (Intel, Broadcom, Realtek, Atheros, MediaTek, Ralink) plus the raw ID + driver name otherwise. Also now handles USB and SDIO wifi chips, not just PCI. Found and fixed a real bug while testing this against actual hardware (this box's virtio NIC): the naive `basename` of the resolved device path breaks for drivers like virtio-net that wrap the real PCI function one level deeper in sysfs (.../0000:00:12.0/virtio2) — basename alone grabs "virtio2", which lspci -s rejects as "Invalid slot number". Fixed by extracting the last domain:bus:device.function-shaped path component instead of trusting the final one. Verified for real, not just written: ran with lspci installed (gets the friendly "Red Hat, Inc. Virtio network device" name), then genuinely removed lspci/lsusb from the system (moved the binaries aside, restored after) and reran — falls back correctly to vendor ID + driver name instead of erroring or going blank. Passes shellcheck clean both times. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
ArchyHCL
A community hardware compatibility list for Archipelago — what physical devices people have actually installed it on, what worked, what didn't, and why. Model, CPU, RAM, storage, and WiFi chip for every report, since WiFi chipsets are consistently the thing most likely to bite someone doing an install on repurposed hardware.
Why this exists
Archipelago runs on whatever hardware people have lying around — old laptops, mini PCs, SBCs — and that's a much wider, messier compatibility surface than a project that only targets its own reference hardware. Before building this, I looked at how a few existing communities solve the same problem:
- OpenWrt's Table of Hardware — a
searchable table of routers, generated nightly from structured wiki
pages into a
toh.jsonfile the site reads. Good model for the browsing UX (sortable/filterable table of CPU/RAM/flash/WiFi chip), but the underlying wiki pages are free-text and only loosely structured, which the maintainers themselves have called out as a maintenance problem over the years. - postmarketOS's device list —
tiers devices into
main/community/testingsupport levels, each with a per-device page describing exactly what works and what doesn't. Good model for the status field: a single working/broken flag loses the "boots fine but WiFi is flaky" middle ground that's actually the most common and most useful case to document. - RaspiBlitz (closest project to Archipelago in spirit — a Bitcoin/Lightning node OS for repurposed hardware) — hardware feedback mostly lives scattered across GitHub issues with no consistent fields, which makes it hard to search or compare reports. Useful as a negative example: this is what we're trying to avoid by using structured data files instead of free-form issue threads.
The model this repo uses: one small YAML file per report
(data/reports/*.yml), validated against a JSON Schema, built into a
single data.json a plain static site reads — OpenWrt's browsable-table UX,
postmarketOS's tiered status field, and RaspiBlitz's actual subject matter
(node-OS-on-repurposed-hardware), on top of git-native, PR-reviewable data
instead of a wiki or a scattered issue tracker.
Repo layout
data/
schema.json — the report schema (source of truth for what fields exist)
reports/*.yml — one file per hardware report
scripts/
build.py — validates every report and builds site/data.json
site/
index.html/.css/.js — the static site (no framework, no build step — just fetches data.json)
.gitea/issue_template/hardware-report.yml — structured issue form for reporting without git
Contributing a report
See CONTRIBUTING.md — either open an issue with the structured form, or add a YAML file directly and open a PR.
Building the site locally
pip install pyyaml jsonschema
python3 scripts/build.py # writes site/data.json
python3 -m http.server 8000 --directory site
Deployment
Live at https://hcl.archipelago-foundation.org — a static site (site/)
served by nginx, cert via certbot certonly --webroot (same pattern as
regress.atobitcoin.io and this project's other nginx-fronted sites).
Deployment is fully automatic: .gitea/workflows/deploy.yml runs on every
push to main on a repo-scoped self-hosted runner (hcl-local-deploy,
label hcl-deploy) living on the same box that serves the site — it runs
scripts/build.py and rsyncs site/ straight into the docroot, so
data.json can never drift from the source reports. No SSH keys or remote
credentials involved; the runner has local filesystem access since it's on
the same machine. .gitea/workflows/ci.yml runs the same build/validate
step on pull requests, on the (separate, shared) vps2-runner, so bad data
gets caught before merge rather than at deploy time.
Runner setup, for reference (repo-scoped registration token from Settings → Actions → Runners → Create new Runner):
gitea-runner register --no-interactive \
--instance <gitea-url> --token <token> \
--name hcl-local-deploy --labels "hcl-deploy:host" \
--config /etc/gitea-runner-hcl/config.yaml
running as a systemd service (gitea-runner-hcl.service) under a user that
owns the docroot directly — deliberately not root, and no sudo needed for
the deploy step itself.
License
MIT — see LICENSE.