Skip to content

feat: happiness scoring + ESP32 swarm with Cognitum Seed #285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ruvnet merged 2 commits into from
Mar 20, 2026
Merged

feat: happiness scoring + ESP32 swarm with Cognitum Seed #285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a2d1739
feat: happiness scoring pipeline with ESP32 swarm + Cognitum Seed coo…
ruvnet Mar 20, 2026
2f55877
ci: raise firmware binary size gate to 1100 KB for HTTP client stack
ruvnet Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/firmware-ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,16 +27,16 @@ jobs:
idf.py set-target esp32s3
idf.py build

- name: Verify binary size (< 950 KB gate)
- name: Verify binary size (< 1100 KB gate)
working-directory: firmware/esp32-csi-node
run: |
BIN=build/esp32-csi-node.bin
SIZE=$(stat -c%s "$BIN")
MAX=$((950 * 1024))
MAX=$((1100 * 1024))
echo "Binary size: $SIZE bytes ($(( SIZE / 1024 )) KB)"
echo "Size limit: $MAX bytes (950 KB — includes Tier 3 WASM runtime)"
echo "Size limit: $MAX bytes (1100 KB — includes WASM runtime + HTTP client for Seed swarm bridge)"
if [ "$SIZE" -gt "$MAX" ]; then
echo "::error::Firmware binary exceeds 950 KB size gate ($SIZE > $MAX)"
echo "::error::Firmware binary exceeds 1100 KB size gate ($SIZE > $MAX)"
exit 1
fi
echo "Binary size OK: $SIZE <= $MAX"
Expand Down
234 changes: 234 additions & 0 deletions docs/adr/ADR-065-happiness-scoring-seed-bridge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,234 @@
# ADR-065: Hotel Guest Happiness Scoring -- WiFi CSI + Cognitum Seed Bridge

**Status:** Proposed
**Date:** 2026-03-20
**Deciders:** @ruvnet
**Related:** ADR-040 (WASM edge modules), ADR-039 (edge intelligence), ADR-042 (CHCI), ADR-064 (multimodal ambient intelligence), ADR-060 (multi-node aggregation)

## Context

Hotels lack objective, privacy-preserving methods to measure guest satisfaction in real time. Current approaches (post-stay surveys, NPS scores) are delayed, biased toward extremes, and capture less than 10% of guests. Meanwhile, ambient RF sensing can infer behavioral cues that correlate with comfort and well-being -- without cameras, wearables, or any guest interaction.

### Hardware

Two ESP32-S3 variants are deployed:

| Device | Flash | PSRAM | MAC | Port | Notes |
|--------|-------|-------|-----|------|-------|
| ESP32-S3 (QFN56 rev 0.2) | 4 MB | 2 MB | 1C:DB:D4:83:D2:40 | COM5 | Budget node, uses `sdkconfig.defaults.4mb` + `partitions_4mb.csv` |
| ESP32-S3 | 8 MB | 8 MB | -- | COM7 | Full-featured node, existing deployment |

Both run the Tier 2 DSP firmware with presence detection, vitals extraction, fall detection, and gait analysis.

### Cognitum Seed Device

A Cognitum Seed unit is deployed on the same network segment:

- **Address:** 169.254.42.1 (link-local)
- **Hardware:** Raspberry Pi Zero 2 W
- **Firmware:** 0.7.0
- **Vector store:** 398 vectors, dim=8
- **API endpoints:** 98 (REST, fully documented)
- **Sensors:** PIR, reed switch (door), vibration, ADS1115 ADC (4-ch analog), BME280 (temp/humidity/pressure)
- **Security:** Ed25519 custody chain with tamper-evident witness log

The Seed's 8-dimensional vector store and drift detection engine make it a natural aggregation point for behavioral feature vectors extracted from CSI data.

### Existing WASM Edge Modules

The following modules already run on-device and produce features relevant to happiness scoring:

| Module | Event IDs | Outputs |
|--------|-----------|---------|
| `exo_emotion_detect.rs` | 610-613 | Arousal level, stress index |
| `med_gait_analysis.rs` | 130-134 | Cadence, stride length, regularity |
| `ret_customer_flow.rs` | 410-413 | Entry/exit count, direction |
| `ret_dwell_heatmap.rs` | 420-423 | Dwell time per zone |

## Decision

### 1. New WASM Module: `exo_happiness_score.rs`

Create a new WASM edge module that fuses outputs from existing modules into an 8-dimensional happiness vector, matching the Seed's vector dimensionality (dim=8).

**Event ID registry (690-694):**

| Event ID | Name | Description |
|----------|------|-------------|
| 690 | `HAPPINESS_VECTOR` | Full 8-dim happiness vector emitted per scoring window |
| 691 | `HAPPINESS_TREND` | Windowed trend (rising/falling/stable) over last N vectors |
| 692 | `HAPPINESS_ALERT` | Score crossed a configured threshold (low satisfaction) |
| 693 | `HAPPINESS_GROUP` | Aggregate score for multi-person zone |
| 694 | `HAPPINESS_CALIBRATION` | Baseline recalibration event (new guest check-in) |

### 2. Happiness Vector Schema (8 Dimensions)

Each dimension is normalized to [0.0, 1.0] where 1.0 = maximal positive signal:

| Dim | Name | Source | Derivation |
|-----|------|--------|------------|
| 0 | `gait_speed` | `med_gait_analysis` (130) | Normalized walking velocity. Brisk = positive. |
| 1 | `stride_regularity` | `med_gait_analysis` (131) | Low stride-to-stride variance = relaxed gait. |
| 2 | `movement_fluidity` | CSI phase jerk (d3/dt3) | Low jerk = smooth, unhurried movement. |
| 3 | `breathing_calm` | Vitals BR extraction | BR 12-18 at rest = calm. Deviation penalized. |
| 4 | `posture_openness` | CSI subcarrier spread | Wide phase spread across subcarriers = open posture. |
| 5 | `dwell_comfort` | `ret_dwell_heatmap` (420) | Moderate dwell in amenity zones = engagement. |
| 6 | `direction_entropy` | `ret_customer_flow` (410) | Low entropy = purposeful movement. Wandering penalized. |
| 7 | `group_energy` | Multi-target CSI clustering | Synchronized movement of 2+ people = social engagement. |

The composite scalar happiness score is the weighted L2 norm:

```
score = sum(w[i] * v[i] for i in 0..7) / sum(w[i])
```

Default weights are uniform (all 1.0), configurable via NVS or Seed API.

### 3. ESP32 to Seed Bridge

```
ESP32-S3 (CSI) Cognitum Seed (169.254.42.1)
+------------------+ +----------------------------+
| Tier 2 DSP | | |
| + WASM modules | UDP 5555 | /api/v1/store/ingest |
| exo_happiness |──────────────| (POST, 8-dim vector) |
| _score.rs | | |
| | | /api/v1/drift/check |
| |◄─────────────| (drift alerts via webhook) |
| | | |
| | | /api/v1/witness/append |
| | | (Ed25519 audit trail) |
+------------------+ +----------------------------+
```

**Data flow:**

1. ESP32 runs CSI capture at 20+ Hz and feeds subcarrier data through existing WASM modules.
2. `exo_happiness_score.rs` collects outputs from emotion, gait, flow, and dwell modules every scoring window (default: 30 seconds).
3. The 8-dim happiness vector is packed as a 32-byte payload (8x float32) and sent via UDP to port 5555 on 169.254.42.1.
4. A lightweight bridge task on the Seed receives the UDP packet and POSTs it to `/api/v1/store/ingest` with metadata (room ID, timestamp, MAC).
5. The Seed's drift detection engine monitors the happiness vector stream and flags anomalies (sudden drops, sustained low scores).
6. Every ingested vector is appended to the Seed's Ed25519 witness chain, providing a tamper-proof audit trail.

### 4. Seed Drift Detection for Happiness Trends

The Seed's built-in drift detection compares incoming vectors against a rolling baseline:

- **Check-in calibration:** When a new guest checks in, event 694 resets the baseline.
- **Drift threshold:** Configurable (default: cosine distance > 0.3 from baseline triggers alert).
- **Trend window:** Last 20 vectors (~10 minutes at 30s intervals).
- **Alert routing:** Seed webhook notifies hotel management system when happiness trend is declining.

### 5. RuView Live Dashboard Update

`ruview_live.py` gains a `--seed` flag:

```bash
python ruview_live.py --port COM5 --seed 169.254.42.1 --mode happiness
```

This mode displays:
- Real-time 8-dim radar chart of the happiness vector
- Scalar happiness score (0-100) with color coding (red/yellow/green)
- Trend sparkline over the last hour
- Seed witness chain status (last hash, chain length)
- Room-level aggregate when multiple ESP32 nodes report

### 6. Architecture

```
+------------------------------------------+
| Hotel Room |
| |
| [ESP32-S3] [Cognitum Seed] |
| COM5 or COM7 169.254.42.1 |
| 4MB or 8MB flash Pi Zero 2 W |
| | | |
| | WiFi CSI | PIR, reed, |
| | 20+ Hz | BME280, |
| v | vibration |
| +-----------+ | |
| | Tier 2 DSP| v |
| | presence | +-------------+ |
| | vitals | | Seed API | |
| | gait | | 98 endpoints| |
| | fall det | | 398 vectors | |
| +-----------+ | dim=8 | |
| | +-------------+ |
| v ^ |
| +-----------+ UDP 5555 | |
| | WASM edge |─────────────┘ |
| | happiness | |
| | score | Drift alerts |
| | (690-694) |◄────────────── |
| +-----------+ /api/v1/drift/check |
| |
+------------------------------------------+
|
| MQTT / HTTP
v
+------------------+
| Hotel Management |
| System / RuView |
| Live Dashboard |
+------------------+
```

### 7. 4MB Flash Support

The 4MB ESP32-S3 variant (COM5) is officially supported for happiness scoring. The existing `partitions_4mb.csv` and `sdkconfig.defaults.4mb` from ADR-265 provide dual OTA slots (1.856 MB each), sufficient for the full Tier 2 DSP firmware plus `exo_happiness_score.wasm` (estimated < 40 KB).

Build for 4MB variant:

```bash
cp sdkconfig.defaults.4mb sdkconfig.defaults
idf.py build
```

The WASM module loader selects which modules to instantiate based on available heap. On the 4MB/2MB PSRAM variant, happiness scoring runs with a reduced scoring window (60s instead of 30s) to conserve memory.

### 8. Privacy Considerations

- **No cameras.** All sensing is RF-based (WiFi subcarrier amplitude/phase).
- **No facial recognition.** Happiness is inferred from movement patterns, not expressions.
- **No audio capture.** Breathing rate is extracted from chest wall displacement via RF, not microphone.
- **No PII stored on device.** Vectors are anonymous; room-to-guest mapping lives only in the hotel PMS.
- **Seed witness chain** provides auditable proof of what data was collected and when, satisfying GDPR Article 30 record-keeping requirements.
- **Guest opt-out:** A physical switch on the ESP32 node (GPIO connected to a toggle) disables CSI capture entirely. The Seed's reed switch can also serve as a "privacy mode" trigger (door-mounted magnet removed = sensing paused).
- **Data retention:** Vectors are retained on the Seed for the duration of the stay plus 24 hours, then purged. The witness chain retains hashes (not vectors) indefinitely for audit.

### 9. API Integration

Key Cognitum Seed endpoints used:

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/v1/store/ingest` | POST | Ingest 8-dim happiness vector |
| `/api/v1/store/query` | POST | Retrieve vectors by room/time range |
| `/api/v1/drift/check` | GET | Check if current vector drifts from baseline |
| `/api/v1/drift/configure` | PUT | Set drift threshold and window size |
| `/api/v1/witness/append` | POST | Append event to Ed25519 custody chain |
| `/api/v1/witness/verify` | GET | Verify chain integrity |
| `/api/v1/sensors/bme280` | GET | Room temperature/humidity (comfort correlation) |
| `/api/v1/sensors/pir` | GET | PIR presence (cross-validate with CSI) |

## Consequences

### Positive

- Provides real-time, objective guest satisfaction measurement without surveys or wearables.
- Reuses four existing WASM modules -- the happiness module is a fusion layer, not a rewrite.
- The Seed's 8-dim vector store is a natural fit; no schema changes needed.
- Ed25519 witness chain satisfies hospitality industry audit requirements and GDPR record-keeping.
- Both 4MB and 8MB ESP32-S3 variants are supported, enabling low-cost deployment at scale (~$8 per room for the 4MB node).
- Seed's environmental sensors (BME280, PIR) provide complementary context (room temperature, humidity) that can be correlated with happiness scores.
- No cloud dependency -- all processing is local (ESP32 edge + Seed link-local network).

### Negative

- Happiness inference from movement patterns is a proxy, not a direct measurement. Correlation with actual guest satisfaction must be validated empirically.
- The 4MB variant has reduced scoring frequency (60s vs 30s) due to memory constraints.
- UDP transport between ESP32 and Seed is unreliable; packets may be lost. Mitigation: sequence numbers and a small retry buffer on the ESP32 side.
- Link-local addressing (169.254.x.x) limits the Seed to the same network segment as the ESP32. Multi-room deployments need one Seed per subnet or a routed bridge.
- Drift detection thresholds require per-property tuning; a luxury resort has different movement patterns than a budget hotel.
- The system cannot distinguish between guests in a multi-occupancy room without additional multi-target CSI clustering, which is experimental (ADR-064, Tier 3).
Loading
Loading