Documentation
Everything here also lives in the box you downloaded — the hub serves these very pages, so docs and product can't drift apart.
Quickstart
- Plug your nodes into USB power, anywhere in the house.
- On any computer that stays home, run python3 hub.py (from the unzipped folder: ./start.sh).
- Open http://localhost:9090 and click Set up your home. Your nodes propose their own arrangement — rotate it to match your room, accept, done.
Principles (why the UI says what it says)
- No fabricated precision. A tracked device shows a zone (the node it's nearest), never an invented dot on the map. Floor-level presence is a state, not a coordinate. If the system can't tell, it says so.
- Local-first, actually. All sensing data lives on your hub, on your LAN. This app is a static shell; there is no account and no server of ours holding your data — not as a promise, as an architecture.
- One name per node. However a node is referred to — colour, MAC, beacon address — it resolves to one identity, and identify makes the physical unit blink so the name and the object never drift apart.
Hub API
| GET /api/state | nodes, tracked devices (zones), presence, timestamps |
| GET /api/layout | live self-location: each node's relative position + link count + quality |
| POST /api/identify | {"node": "GREEN"} — blink that physical node for 20 s |
| POST /api/place | {"node", "x", "y"} — persist one node's position (feet) |
| POST /api/place_all | {"placements": {id: [x, y]}} — persist a whole arrangement |
| GET /api/health | liveness |
All endpoints CORS-open on your LAN. The dashboard is just a client of this API — build your own automations against it freely.
Troubleshooting
The hub must run on a computer in the same house/network. Check the terminal where you started it; the address in Settings must match that machine (e.g. http://192.168.1.20:9090 from your phone, not localhost).
Give them ~1 minute after power-up. Still nothing: the node may be out of range of any listener — move it closer to another node and watch the tray. A node that appears then vanishes is usually a power problem; USB wall adapters beat laptop ports.
Transmit and receive are separate radio roles — a node can beacon fine while its listener is stuck. Power-cycle it; if it persists, that unit still helps the map as a beacon, and identify still finds it.
Expected: radio recovers the shape of your constellation, not its orientation — that's physics, not a bug. Use rotate and mirror in Setup, then drag individual nodes to fine-tune. The map tightens on its own as nodes listen longer.