From c53bd96cc8f80ce6e5b30a91b5407d3a3851a3ba Mon Sep 17 00:00:00 2001 From: jedarden Date: Fri, 3 Jul 2026 00:42:11 -0400 Subject: [PATCH] docs: add root README.md (repo standard, GitHub mirror landing page) Covers Spaxel overview, realistic CSI capabilities, privacy framing, the go.work multi-module repo layout, docker-compose quickstart with key env vars, and pointers to docs/plan, docs/notes, docs/research, and the dashboard README. Accurate to the current tree (image ronaldraygun/spaxel); no secrets or host paths. Co-Authored-By: Claude --- README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d564b08 --- /dev/null +++ b/README.md @@ -0,0 +1,97 @@ +# Spaxel + +**WiFi CSI-based indoor positioning for self-hosted homes.** + +Spaxel detects and localizes people in a home using WiFi Channel State Information — no cameras, no microphones, no cloud. A single Docker container (the "mothership") runs on a home server and manages a fleet of ESP32-S3 nodes that capture and stream CSI over WiFi. The mothership fuses CSI from all links to detect presence, follow motion, and — with enough nodes — estimate 2D/3D position, rendered on a Three.js floor-plan dashboard. + +Everything runs locally on hardware you own. There is no cloud relay, no account, and no RF beyond the 2.4 GHz WiFi already in your home. + +## What it can realistically do + +Based on physics and the research in [`docs/research/`](docs/research/) (see [`docs/research/06-accuracy-and-limits.md`](docs/research/06-accuracy-and-limits.md)): + +- **Presence detection** — reliably, with 2+ nodes on opposite sides of a space +- **Approximate 2D position** — ±0.5–1.0 m with 4+ nodes +- **Motion / trajectory tracking** — follows moving people +- **Rough person count** — distinguishes 1 vs. 2+ (degrades at 3+) +- **Rough Z-axis** — ±1–2 m with mixed-height node placement (enables fall detection) +- **Stationary-person detection** — via breathing micro-motion (0.1–0.5 Hz) + +**Not achievable** with 2.4 GHz CSI: sub-10 cm accuracy, skeletal pose, reliable 5+ person tracking. + +### Privacy by design + +Spaxel is CSI-only — it never captures camera images or audio. Detection is local: data stays on the mothership, there is no cloud relay or remote access, and no user accounts are required (a single PIN protects the dashboard). See the *Non-Goals* section of [`docs/plan/plan.md`](docs/plan/plan.md). + +## Repository layout + +Spaxel is a [Go workspace](go.work) of three modules, plus ESP32 firmware and a static frontend: + +| Path | Description | +|------|-------------| +| [`mothership/`](mothership/) | Go backend — ingestion, signal pipeline, localizer, fleet manager, REST/WebSocket API, dashboard server (`github.com/spaxel/mothership`) | +| [`cmd/sim/`](cmd/sim/) | `spaxel-sim` — CSI/node simulator CLI for hardware-free development and integration tests (`github.com/spaxel/sim`) | +| [`test/acceptance/`](test/acceptance/) | Acceptance-test module (AS-1 … AS-7), driven by the simulator | +| [`firmware/`](firmware/) | ESP-IDF (C) firmware for the ESP32-S3 node fleet | +| [`dashboard/`](dashboard/) | Vanilla JS + Three.js single-page UI (see [`dashboard/README.md`](dashboard/README.md)) | +| [`docs/`](docs/) | Plan, notes, and research (see [Documentation](#documentation) below) | +| [`Dockerfile`](Dockerfile), [`docker-compose.yml`](docker-compose.yml) | Single-container packaging | +| [`PROGRESS.md`](PROGRESS.md), [`VERSION`](VERSION) | Implementation status and current version | + +## Quickstart + +The mothership ships as a single container, published as `ronaldraygun/spaxel`. The bundled [`docker-compose.yml`](docker-compose.yml) builds from source by default and exposes one port (8080). + +```bash +git clone https://github.com/jedarden/spaxel.git +cd spaxel +docker compose up -d # builds the mothership image, host networking +# …or skip the build and use the published image: +# docker pull ronaldraygun/spaxel +``` + +Then open `http://:8080`, set a dashboard PIN, and use **Add Node** (Chrome/Edge Web Serial) to provision an ESP32-S3 over USB. The node discovers the mothership via mDNS and begins streaming CSI — zero manual IP configuration. + +> `network_mode: host` is required for mDNS multicast to reach ESP32 nodes on your LAN. If host networking isn't available, set `SPAXEL_MDNS_ENABLED=false` and provision nodes with a manual mothership IP (see [`docs/notes/mdns-override.md`](docs/notes/mdns-override.md)). + +### Key environment variables + +| Variable | Default | Purpose | +|----------|---------|---------| +| `SPAXEL_BIND_ADDR` | `0.0.0.0:8080` | Listen address (set to `127.0.0.1:8080` behind a local reverse proxy) | +| `SPAXEL_DATA_DIR` | `/data` | Persistent storage: SQLite, baselines, floor plans, CSI replay buffer, firmware | +| `SPAXEL_MQTT_BROKER` | *(unset)* | Optional MQTT broker URL for Home Assistant integration (e.g. `mqtt://homeassistant.local:1883`) | +| `TZ` | `UTC` | Timezone for diurnal baselines, briefings, and quiet hours (IANA name) | +| `SPAXEL_MDNS_ENABLED` | `true` | Disable when not using host networking | + +The full list is in the *Deployment* section of [`docs/plan/plan.md`](docs/plan/plan.md). + +## Building & developing + +```bash +# Mothership backend +cd mothership && go test ./... && go vet ./... + +# CSI / node simulator +go build -o spaxel-sim ./cmd/sim + +# Hardware-free acceptance suite (no ESP32 needed) +cd test/acceptance && go test ./... + +# Dashboard unit + accessibility tests +cd dashboard && npm test && npm run test:a11y +``` + +Firmware is built with ESP-IDF 5.2.x — see the *Firmware Build System* section of the plan. + +## Documentation + +- [`docs/plan/plan.md`](docs/plan/plan.md) — the complete design: architecture, components, schema, deployment, phases +- [`docs/notes/`](docs/notes/) — implementation notes (recovery mechanisms, mDNS override, simulation testing, UX) +- [`docs/research/`](docs/research/) — CSI fundamentals, physics, algorithms, accuracy limits, prior-art papers +- [`dashboard/README.md`](dashboard/README.md) — dashboard test setup (Jest, axe-core + Playwright) +- [`PROGRESS.md`](PROGRESS.md) — phase-by-phase implementation status + +--- + +*Spaxel is self-hosted, CSI-only, and cloud-free by design.*