Antriksh69/voltix-home

Voltix Home

Smart-home automation with face-recognition gate access, MQTT device control, ESP32 firmware, and a real-time Next.js dashboard.

This repository is private. It contains biometric data (face embeddings and camera snapshots of identifiable people) and device firmware. Access is restricted to invited team members. Do not make it public — see SECURITY.md.

Stack

Layer	Technology
Dashboard / API	Next.js (App Router), TypeScript, Socket.io
Realtime bus	Aedes MQTT broker (embedded, port 1884)
Database	PostgreSQL + Prisma
Vision service	Python, FastAPI, OpenCV, ONNX Runtime
Face recognition	SFace (ONNX) + YuNet detection
Anti-spoof	MiniFASNet deepfake detector
Firmware	ESP32-CAM (gate), ESP32 8-relay, ESP32 gas sensor

Architecture

┌─────────────────┐   HTTP POST /frame    ┌──────────────────────────────┐
│   ESP32-CAM     │ ────────────────────▶ │  Next.js Server (Node)       │
│  Gate + Stream  │ ◀──────────────────── │  ├─ API Routes (REST)        │
└─────────────────┘   {authorized, name}  │  ├─ Socket.io Gateway        │
                                          │  ├─ Aedes MQTT Broker :1884  │
┌─────────────────┐                       │  ├─ Face Engine Bridge       │
│ ESP32 8-Relay   │ ◀────MQTT──▶─────────▶│  │   (Python face-recognition│
│ x8 Appliances   │  voltix/devices/#     │  │    microservice :8000)    │
└─────────────────┘                       │  └─ Prisma → PostgreSQL      │
      ▲ physical buttons                  └──────────┬───────────────────┘
                                                     │ WebSocket (<100ms)
                                              ┌──────▼──────┐
                                              │  Dashboard  │
                                              │ Next.js App │
                                              └─────────────┘

Repository layout

voltix-home/
├── voltixhome-main/          # the application
│   ├── app/                  # Next.js App Router pages + API routes
│   │   └── api/              # REST: accesslogs, appliances, cam, gate, internal/
│   ├── components/           # Dashboard UI (GatePanel, ApplianceGrid, StatsRow)
│   ├── lib/                  # prisma, auth, env, mqtt-handlers, face-bridge
│   ├── hooks/                # useVoltixSocket — realtime client
│   ├── prisma/               # schema.prisma, migrations, seed
│   ├── services/vision/      # FastAPI face recognition microservice
│   ├── engine/               # Face engine library + ONNX models
│   │   ├── src/              # face_engine.py, anti_spoof.py, gate_controller.py
│   │   ├── models/           # sface_2021dec.onnx, face_detection_yunet_2023mar.onnx
│   │   └── database/         # embeddings.pkl  ← BIOMETRIC, do not redistribute
│   ├── firmware/             # ESP32 sketches (Arduino/C++)
│   │   ├── esp32cam_gate/    # gate camera + MJPEG stream
│   │   ├── VoltixGateCam/    # gate camera (alt sketch)
│   │   ├── esp32_relay8/     # 8-channel relay board
│   │   ├── VoltixRelayGas/   # relay + gas sensor variant
│   │   ├── esp32_gas_sensor/ # standalone gas/sensor node
│   │   └── CamTest/          # minimal camera bring-up test
│   ├── public/
│   │   ├── images/           # product renders
│   │   ├── fonts/            # self-hosted webfonts
│   │   └── snapshots/        # ACCESS SNAPSHOTS ← contains identifiable faces
│   ├── docs (root)           # SYNOPSIS, FLASH-GUIDE, audit
│   └── new_degign/           # static Woblo export used as design reference
├── firmware/.gitignore       # keeps secrets.local.h out of git
├── LICENSE                   # MIT
├── SECURITY.md               # threat model, known limitations, secret policy
├── CONTRIBUTING.md           # branch/commit/PR conventions
├── .gitattributes            # Git LFS rules for binaries, models, images
└── .gitignore

Quick start

npm --prefix voltixhome-main install
cp voltixhome-main/.env.example voltixhome-main/.env
# edit .env: DATABASE_URL, VOLTIX_DEVICE_KEY, ADMIN_EMAIL, ADMIN_PASSWORD
npx --prefix voltixhome-main prisma migrate deploy
npx --prefix voltixhome-main prisma db seed

Run the three services in separate terminals:

npm --prefix voltixhome-main run dev        # dashboard + MQTT broker :3000
pip install -r voltixhome-main/services/vision/requirements.txt
npm --prefix voltixhome-main run vision     # face engine :8000

Windows convenience wrappers live at the repo root: start-voltix-dashboard.bat, start-voltix-everywhere.bat, start-face-gate.bat, start-enroll.bat.

Firmware setup: edit voltixhome-main/firmware/<sketch>/secrets.h with your Wi-Fi SSID/password, PC LAN IP, and the device key (must match VOLTIX_DEVICE_KEY in .env), then flash from the Arduino IDE. See voltixhome-main/FLASH-GUIDE.md.

MQTT protocol

Topic	Direction	Payload
voltix/devices/{deviceId}/set	Broker → Device	{"state":"ON","key":"SECRET"}
voltix/devices/{deviceId}/state	Device → Broker	{"deviceId":"RELAY-01","relay":3,"state":"ON","rssi":-52}
voltix/devices/{deviceId}/online	LWT	{"online":true}
voltix/gate/authorize	Backend → Gate	{"decision":"GRANTED","person":"Alice","confidence":0.93}
voltix/gate/set	Dashboard → Relay	{"state":"OPEN"}

Latency profile

• ESP32 → broker: ~5 ms on LAN
• Broker → Socket.io fan-out: ~2 ms
• UI toggle: optimistic, instant
• Device confirmation via retained state echo: ~30–80 ms

Documentation

• voltixhome-main/README.md — full technical readme, deployment checklist
• voltixhome-main/FLASH-GUIDE.md — firmware flashing walkthrough
• voltixhome-main/SYNOPSIS_VOLTIX_HOME.md / SOFTWARE_SYNOPSIS_VOLTIX.md — project synopsis
• voltixhome-main/SYNOPSIS-AUDIT.md — code audit notes
• SECURITY.md — threat model and known limitations (read before deploying)
• CONTRIBUTING.md — how to branch, commit, and open a PR

License

MIT — see LICENSE.

Third-party model weights (SFace, YuNet, MiniFASNet) remain under their own upstream licences; see THIRD_PARTY_LICENSES.md.