BLE Hybrid Home Tracker

This project is now a hybrid tracking scaffold:

• Browser BLE scanner and GATT explorer UI.
• Shared event schema/adapters for BLE, Wi-Fi emitter/probe, ESP-NOW, and heartbeat events.
• Local gateway API with SQLite append-only event store.
• Recurring-device and dwell-time analytics endpoints.
• Floor-plan view with receiver anchors and live placements.
• Floor-plan differentiates BLE vs Wi-Fi emitters.
• ESP32 receiver firmware prototype for passive BLE + heartbeat packets.

Project structure

• index.html, app.js, style.css - frontend scanner/explorer/history/analytics/floor-plan.
• shared/observation-schema.js - canonical event contracts + source adapters.
• gateway/src/server.js - ingest/query API.
• gateway/src/db.js - SQLite storage and receiver registry.
• gateway/src/analytics.js - recurring/dwell/floor placement analytics.
• firmware/esp32_receiver/esp32_receiver.ino - receiver node prototype.

Run locally

1. Install dependencies:
   • npm install
2. Start gateway + static web server:
   • npm run dev
3. Open the web app (http://localhost:5500 if using default serve settings).
4. In the app, keep gateway URL as http://localhost:8787.

Optional: run stdin bridge for ESP-NOW forwarder

• Command: npm run start:bridge:stdin
• Environment variables:
  • GATEWAY_URL (default http://localhost:8787)
  • GATEWAY_API_KEY (if enabled on gateway)
  • BRIDGE_FLUSH_MS (default 1200)
  • BRIDGE_MAX_BATCH (default 50)
• Input format: one JSON packet per line on stdin. Packets are forwarded to POST /api/ingest/espnow.

Windows: stream ESP32 serial directly to gateway

Use this helper script to read JSON lines from ESP32 serial and feed them into the bridge automatically:

powershell -ExecutionPolicy Bypass -File ".\scripts\windows-esp32-serial-forward.ps1" `
  -ComPort "COM6" `
  -GatewayUrl "https://your-render-service.onrender.com" `
  -GatewayApiKey "your-ingest-api-key" `
  -BaudRate 115200

Notes:

• Firmware must emit one JSON packet per line on serial (current esp32_receiver.ino does this).
• Non-JSON serial noise is ignored.

Core API endpoints

• GET /api/health
• POST /api/events
• POST /api/events/batch
• POST /api/ingest/espnow
• GET /api/events
• GET /api/events/by-stable-key?stableKey=...&minutes=...&limit=...
• GET /api/devices
• GET /api/analytics/recurring
• GET /api/analytics/dwell
• POST /api/receivers/register
• POST /api/receivers/:receiverId/room
• GET /api/receivers
• GET /api/floorplan/live

Gateway API key protection

• Write endpoints (POST /api/events, /api/events/batch, /api/ingest/espnow, receiver register/update) can be protected with an API key.
• Set environment variable INGEST_API_KEY on the gateway service.
• Send key in x-api-key header (or Authorization: Bearer <key>).
• Frontend supports this in Gateway Connection via Gateway API key input.

Receiver anchor persistence

• Receiver anchors are managed in a server-side cache and persisted to:
  • gateway/data/receiver-cache.json
• On startup, gateway loads that snapshot and also merges receiver rows from DB.
• Receiver cache writes are debounced to reduce disk churn.
• For restart-safe persistence on Render, attach a persistent disk or move to external DB/KV.

Gateway read caching

• Expensive read endpoints (/api/devices, recurring, dwell, by-stable-key trends) use short TTL response caching to reduce repeated compute cost under frequent polling.

Next implementation targets

• Add ESP-NOW bridge process from gateway radio/serial to /api/ingest/espnow.
• Add Wi-Fi probe packet emit support in firmware (where hardware/SDK supports monitor capture).
• Add robust time sync and offline buffering on receivers.
• Replace simple floor placement heuristic with calibrated multi-receiver solver.