Ruview/examples/happiness-vector

Happiness Vector — WiFi CSI Guest Sentiment Sensing

Contactless hotel guest happiness scoring using WiFi Channel State Information (CSI) from ESP32-S3 nodes, coordinated by a Cognitum Seed edge intelligence appliance.

No cameras. No microphones. No PII. Just radio waves.

How It Works

Guest walks through lobby
        |
        v
  ESP32-S3 Node (WiFi CSI at 20 Hz)
        |
        v
  Tier 2 Edge DSP (Core 1)
  - Phase rate-of-change --> gait speed
  - Step interval variance --> stride regularity
  - Phase 2nd derivative --> movement fluidity
  - 0.15-0.5 Hz oscillation --> breathing rate
  - Amplitude spread --> posture
  - Presence duration --> dwell time
        |
        v
  8-dim Happiness Vector
  [happiness, gait, stride, fluidity, calm, posture, dwell, social]
        |
        v
  Cognitum Seed (Pi Zero 2 W)
  - kNN similarity search
  - Concept drift detection (13 detectors)
  - Ed25519 witness chain (tamper-proof audit)
  - Reflex rules (trigger actuators on patterns)

The 8 Dimensions

Dim	Name	Source	Happy	Unhappy
0	Happiness Score	Weighted composite of dims 1-6	0.7-1.0	0.0-0.3
1	Gait Speed	Phase Doppler shift	Fast (0.8+)	Slow (0.2)
2	Stride Regularity	Step interval CV (inverted)	Regular (0.9)	Erratic (0.3)
3	Movement Fluidity	Phase acceleration (inverted)	Smooth (0.8)	Jerky (0.2)
4	Breathing Calm	0.15-0.5 Hz phase oscillation	Slow/deep (0.8)	Rapid (0.2)
5	Posture Score	Amplitude spread across subcarriers	Upright (0.7)	Slouched (0.3)
6	Dwell Factor	Presence frame ratio	Lingering (0.8)	Rushing (0.2)
7	Social Energy	Motion + dwell + HR proxy	Animated group (0.8)	Solitary (0.2)

Weights: gait 25%, fluidity 20%, calm 20%, stride 15%, posture 10%, dwell 10%.

Hardware

Component	Model	Role	Cost
ESP32-S3	QFN56 (4MB flash, 2MB PSRAM)	CSI sensing node	~$4
Cognitum Seed	Pi Zero 2 W	Swarm coordinator	~$20
WiFi Router	Any 2.4 GHz	CSI signal source	existing

One Seed manages up to 20 ESP32 nodes. Each node covers ~10m radius through walls.

Quick Start

1. Flash and Provision an ESP32 Node

# Build firmware (from repo root)
cd firmware/esp32-csi-node
idf.py build

# Flash to device
idf.py -p COM5 flash

# Provision with WiFi + Seed credentials
python provision.py \
  --port COM5 \
  --ssid "YourWiFi" \
  --password "yourpassword" \
  --node-id 1 \
  --seed-url "http://10.1.10.236" \
  --seed-token "YOUR_SEED_TOKEN" \
  --zone "lobby"

2. Pair the Seed (first time only)

# Via USB (link-local, no token needed)
curl -X POST http://169.254.42.1/api/v1/pair/window
curl -X POST http://169.254.42.1/api/v1/pair -H "Content-Type: application/json" \
  -d '{"name":"esp32-swarm"}'
# Save the token from the response

3. Run the Dashboard

# Happiness mode with Seed bridge
python examples/ruview_live.py \
  --mode happiness \
  --csi COM5 \
  --seed http://10.1.10.236 \
  --duration 300

# Output:
#    s             Happy   Gait   Calm  Social  Pres   RSSI    Seed   CSI#
#   2s  [====------] 0.43   0.00   0.64    0.00    no    -59      OK   1800
#  10s  [=======---] 0.72   0.65   0.80    0.45   YES    -55      OK   4200

4. Query the Seed

# Status
python examples/happiness-vector/seed_query.py \
  --seed http://10.1.10.236 --token YOUR_TOKEN status

# Live monitor vectors flowing in
python examples/happiness-vector/seed_query.py \
  --seed http://10.1.10.236 --token YOUR_TOKEN monitor

# Happiness report
python examples/happiness-vector/seed_query.py \
  --seed http://10.1.10.236 --token YOUR_TOKEN report

# Witness chain audit
python examples/happiness-vector/seed_query.py \
  --seed http://10.1.10.236 --token YOUR_TOKEN witness

Multi-Node Swarm

Deploy multiple ESP32 nodes across zones. The Seed aggregates all vectors and detects cross-zone patterns.

# Provision all nodes at once
bash examples/happiness-vector/provision_swarm.sh

# Or manually per node
python provision.py --port COM5  --node-id 1 --zone lobby      ...
python provision.py --port COM6  --node-id 2 --zone hallway    ...
python provision.py --port COM8  --node-id 3 --zone restaurant ...

Each node independently:

• Collects CSI at ~100 fps
• Runs Tier 2 DSP on Core 1 (presence, vitals, fall detection)
• Pushes happiness vectors to Seed every 5 seconds (when presence detected)
• Sends heartbeats every 30 seconds

The Seed provides:

• kNN search across all zones ("which room is happiest right now?")
• Drift detection (13 detectors monitoring mood trends over time)
• Witness chain (Ed25519-signed, tamper-proof audit trail)
• Reflex rules (trigger alarms, lights, or alerts on swarm-wide patterns)

WASM Edge Modules

The happiness scoring algorithm also exists as a WASM module for on-device execution:

# Build the happiness scorer WASM
cd v2/crates/wifi-densepose-wasm-edge
cargo build --bin ghost_hunter --target wasm32-unknown-unknown --release --no-default-features

# Output: target/wasm32-unknown-unknown/release/ghost_hunter.wasm (5.7 KB)

Event IDs emitted by the WASM module:

ID	Event	Rate
690	HAPPINESS_SCORE	Every frame (20 Hz)
691	GAIT_ENERGY	Every 4th frame (5 Hz)
692	AFFECT_VALENCE	Every 4th frame
693	SOCIAL_ENERGY	Every 4th frame
694	TRANSIT_DIRECTION	Every 4th frame

Privacy

This system is designed to be privacy-preserving by construction:

• No images — WiFi CSI captures RF signal patterns, not visual data
• No audio — radio waves only
• No facial recognition — physically impossible with CSI
• No individual identity — cannot distinguish Bob from Alice
• Aggregate only — 8 floating-point numbers per observation
• Works in the dark — RF sensing needs no lighting
• Through-wall — single sensor covers adjacent rooms without line-of-sight
• GDPR-friendly — no personal data collected; happiness scores are anonymous statistical aggregates

Files

File	Description
seed_query.py	CLI tool: status, search, witness, monitor, report
provision_swarm.sh	Batch provisioning for multi-node deployment
happiness_vector_schema.json	JSON Schema for the 8-dim vector format
README.md	This file

Related

• ADR-065 — Happiness scoring pipeline architecture
• ADR-066 — ESP32 swarm with Seed coordinator
• exo_happiness_score.rs — WASM edge module (Rust)
• swarm_bridge.c — ESP32 firmware swarm bridge
• ruview_live.py — RuView Live dashboard with --mode happiness