house-as-code: a resilient home network built from spare gear

house-as-code is a flagship homelab build: a monitored, reproducible home network assembled mostly from hardware that is already sitting around the house.

Three repurposed Google Wifi pucks provide the Wi-Fi backbone. An old laptop on a UPS acts as the brain. External storage, ESP32 boards, an old phone, power banks, and Meshtastic LoRa boards fill in the pieces the pucks should not handle: compute, storage, sensing, power resilience, and out-of-band messaging.

The goal is simple:

Every important node can be rebuilt from this repo, and every risky network change is observable, reversible, and documented.

Why This Exists

Most home networks are fragile, opaque, and manually configured. This project treats the house like small infrastructure:

• Network configuration lives in git.
• Router state is exported as metrics.
• Dashboards show Wi-Fi health, client quality, latency, and outage state.
• Automation is added only after observability and rollback exist.
• Recycled hardware is used deliberately, not as an afterthought.

This is not trying to replace mature OpenWrt controllers or enterprise NetOps tools. It is a practical, household-scale reference build for people who want a resilient home network without buying a rack of new gear.

System Shape

flowchart TB
  subgraph SENSE["Sensing and telemetry"]
    ESP["ESP32 CSI sensors"]
    RF["Puck RF scan"]
    TEL["Puck metrics"]
  end

  subgraph BACKBONE["Wi-Fi/IP backbone"]
    P1["Puck 1"]
    P2["Puck 2"]
    P3["Puck 3"]
    PL["Powerline backhaul"]
    SW["Old switch"]
    P1 --- P2
    P2 --- P3
    PL --- SW
    SW --- P1
    SW --- P2
    SW --- P3
  end

  subgraph BRAIN["Old laptop on UPS"]
    MQ["MQTT broker"]
    DB["Metrics historian"]
    DASH["Grafana / Home Assistant"]
    LOOP["Guarded control loop"]
    FILES["File relay / backup target"]
  end

  subgraph LORA["Outage layer"]
    MESH["Meshtastic LoRa mesh"]
  end

  PHONE["Wall display"]

  ESP -->|CSI events| MQ
  RF -->|RF observations| MQ
  TEL -->|network metrics| MQ
  MQ --> DB
  DB --> DASH
  DB --> LOOP
  LOOP -->|dry-run, then guarded changes| BACKBONE
  DASH --> PHONE
  MESH <-->|private MQTT bridge| MQ
  FILES --- DB

Loading

MQTT is the integration spine. Pucks, sensors, and LoRa nodes publish small events; the laptop stores, visualizes, and eventually acts on them.

Hardware Roles

Device	Role	Why it belongs there
Google Wifi pucks running OpenWrt	Access points, backbone nodes, RF telemetry, SQM, guarded actuators	Good radios; limited CPU, RAM, and storage
Old laptop on UPS	MQTT, metrics, dashboards, automation, CSI inference, file relay	Enough compute and memory for the brain layer
External drive	Backups, metrics retention, file share, datasets	Keeps storage off the pucks
Powerline adapters	Preferred puck backhaul	Avoids wireless mesh throughput loss where wiring is unavailable
Old switch	Wired ports and VLAN segmentation	Simple, reliable plumbing
ESP32 boards	CSI-based motion/presence experiments	Pucks should not be treated as CSI sensors
Old phone or monitor	Wall dashboard	Cheap always-on status display
Power banks, small solar, UPS	Outage resilience	Keeps critical nodes alive long enough to matter
Meshtastic LoRa boards	Local low-bandwidth messaging during outages	Survives ISP loss and can bridge beyond Wi-Fi range

Project Boundaries

The core project is the first five roadmap milestones:

1. Flash and provision one puck.
2. Build the three-puck backbone.
3. Stand up the laptop brain.
4. Add observability.
5. Add self-tuning only with guardrails.

CSI presence sensing, LoRa resilience, and full GitOps maturity are valuable expansions, but they should not block the first working release.

See ROADMAP.md for the build order, exit criteria, and recommendations.

Repo Layout

house-as-code/
|-- README.md
|-- ROADMAP.md
|-- docs/
|   |-- decisions/
|   |   `-- 0001-metrics-store.md
|   |-- hardware-inventory.md
|   |-- mqtt-topics.md
|   `-- runbooks/
|       `-- flash-puck.md
|-- pucks/
|   |-- shared/
|   |   `-- packages.txt
|   |-- node-1/
|   |-- node-2/
|   |-- node-3/
|   `-- provision.sh
|-- brain/
|   |-- mosquitto/
|   |-- influxdb/
|   |-- grafana/
|   |-- file-relay/
|   `-- control-loop/
|-- sensors/
|   `-- esp32-csi/
|-- lora/
|-- dashboards/
`-- ci/

Constraints To Keep Honest

• Pucks are backbone nodes and actuators, not general-purpose servers.
• Broker, dashboards, ML, and long-running jobs live on the laptop.
• Powerline backhaul is preferred; wireless mesh is the fallback.
• Self-tuning must start in dry-run mode and require rollback.
• LoRa is for short text/status messages, not files or dashboards.
• Off-grid claims require measured power budgets.

Standout Angle

The interesting part is not any single technology. It is the combination:

recycled hardware + OpenWrt + MQTT + observability + guarded automation + outage-aware design + reproducible configuration.

Done well, this becomes a useful reference build: a home network that can be inspected, rebuilt, improved, and recovered without tribal knowledge.

License

MIT. See LICENSE.