frank/ruvnet--RuView
1
0
Fork 0
mirror of https://github.com/ruvnet/RuView synced 2026-07-24 17:43:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README with ADR-045–048, Observatory, adaptive classifier, AMOLED display

Browse Source 
- Update ADR count from 44 to 48
- Add adaptive classifier (ADR-048) to Intelligence features
- Add Observatory visualization (ADR-047) and AMOLED display (ADR-045) to Deployment features
- Update screenshot to v2-screen.png
- Add ADR-045 (AMOLED), ADR-046 (Android TV), ADR-047 (Observatory), DDD deployment model
- Add AMOLED display firmware (display_hal, display_task, display_ui, LVGL config)
- Add Observatory UI (13 Three.js modules, CSS, HTML entry point)
- Add trained adaptive model JSON
- Update .gitignore for managed_components, recordings, .swarm

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
2026-03-05 10:20:48 -05:00
parent 5fa61ba7ea
commit 8b57a6f64c
35 changed files with 8674 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/ADR-045-amoled-display-support.md
+110
View File
@@ -0,0 +1,110 @@
# ADR-045: AMOLED Display Support for ESP32-S3 CSI Node
## Status
Proposed
## Context
The ESP32-S3 board (LilyGO T-Display-S3 AMOLED) has an integrated RM67162 QSPI AMOLED display (536x240) and 8MB octal PSRAM that were unused by the CSI firmware. Users want real-time on-device visualization of CSI statistics, vital signs, and system health without relying on an external server.
### Constraints
- Binary was 947 KB in a 1 MB partition — needed 8MB flash + custom partition table
- SPIRAM was disabled in sdkconfig despite hardware having 8MB PSRAM
- Core 1 is pinned to DSP (edge processing) — display must use Core 0
- Existing CSI pipeline must not be affected
### Available APIs
Thread-safe edge APIs already exist (`edge_get_vitals()`, `edge_get_multi_person()`) — the display task only reads from these, no new synchronization needed.
## Decision
Add optional AMOLED display support with the following architecture:
### Hardware Abstraction Layer
- `display_hal.c/h`: RM67162 QSPI panel driver + CST816S capacitive touch via I2C
- Auto-detect at boot: probe RM67162 and check SPIRAM; log warning and skip if absent
### UI Layer
- `display_ui.c/h`: LVGL 8.3 with 4 swipeable views via tileview widget
- Dark theme (#0a0a0f) with cyan (#00d4ff) accent for three.js-like aesthetic
- Views: Dashboard (CSI amplitude chart + stats), Vitals (breathing + HR line graphs), Presence (4x4 occupancy grid), System (CPU, heap, PSRAM, WiFi, uptime, FPS)
### Task Layer
- `display_task.c/h`: FreeRTOS task on Core 0, priority 1 (lowest)
- LVGL pump loop at configurable FPS (default 30)
- Double-buffered draw buffers allocated in SPIRAM
### Compile-Time Control
- `CONFIG_DISPLAY_ENABLE=y` (default): compiles display code, auto-detects hardware at boot
- `CONFIG_DISPLAY_ENABLE=n`: zero-cost — no display code compiled
- `CONFIG_SPIRAM_IGNORE_NOTFOUND=y`: boots fine on boards without PSRAM
### Flash Layout
8MB partition table (`partitions_display.csv`):
- Dual OTA partitions: 2 x 2MB (supports larger binaries with LVGL)
- SPIFFS: 1.9MB (for future font/asset storage)
- NVS + otadata + phy: standard sizes
### Core/Task Layout
| Task | Core | Priority | Impact |
|------|------|----------|--------|
| WiFi/LwIP | 0 | 18-23 | unchanged |
| OTA httpd | 0 | 5 | unchanged |
| **display_task** | **0** | **1** | **NEW — lowest priority** |
| edge_task (DSP) | 1 | 5 | unchanged |
### Dependencies
- LVGL ~8.3 (via ESP-IDF managed components)
- espressif/esp_lcd_touch_cst816s ^1.0
- espressif/esp_lcd_touch ^1.0
## Consequences
### Positive
- Real-time on-device stats without network dependency
- Zero impact on CSI pipeline (display reads thread-safe APIs, runs at lowest priority)
- Graceful degradation: works on boards without display or PSRAM
- SPIRAM enabled for all boards (benefits WASM runtime too)
- 8MB flash + dual OTA 2MB partitions give headroom for future features
### Negative
- Binary size increase (~200-300 KB with LVGL)
- SPIRAM + 8MB flash config is specific to T-Display-S3 AMOLED boards
- Boards with only 4MB flash need `CONFIG_DISPLAY_ENABLE=n` and the old partition table
### Risks
- RM67162 init sequence is board-specific; other AMOLED panels may need different commands
- QSPI bus conflicts if other peripherals use SPI2_HOST (currently unused)
## New Files
| File | Purpose |
|------|---------|
| `main/display_hal.c/h` | RM67162 QSPI + CST816S touch HAL |
| `main/display_ui.c/h` | LVGL 4-view UI |
| `main/display_task.c/h` | FreeRTOS task, LVGL pump |
| `main/lv_conf.h` | LVGL compile config |
| `partitions_display.csv` | 8MB partition table |
| `idf_component.yml` | Managed component deps |
## Modified Files
| File | Change |
|------|--------|
| `sdkconfig.defaults` | 8MB flash, SPIRAM, custom partitions |
| `main/CMakeLists.txt` | Conditional display sources + deps |
| `main/main.c` | +1 include, +5 lines guarded init |
| `main/Kconfig.projbuild` | "AMOLED Display" menu |
docs/adr/ADR-046-android-tv-box-armbian-deployment.md
+263
View File
@@ -0,0 +1,263 @@
# ADR-046: Android TV Box / Armbian Deployment Target
## Status
Proposed
## Context
Issue [#138](https://github.com/ruvnet/wifi-densepose/issues/138) requests ESP8266 and mobile device support. The ESP8266 lacks CSI capability and sufficient resources, but the discussion revealed a compelling deployment target: **Android TV boxes** (Amlogic/Allwinner/Rockchip SoCs) running **Armbian** (Debian for ARM).
These devices cost $15–35, are always-on mains-powered, include 802.11ac WiFi, 2–4 GB RAM, quad-core ARM Cortex-A53/A55 CPUs, and HDMI output. They are widely available as consumer "IPTV boxes" (T95, H96 Max, X96, MXQ Pro, etc.) and can boot Armbian from SD card without modifying the factory Android installation.
### Current deployment model
```
[ESP32-S3 nodes] --UDP CSI--> [Laptop/PC running sensing-server] --browser--> [UI]
```
This requires a general-purpose computer ($300+) to run the Rust sensing server, NN inference, and web dashboard. For permanent installations (elder care, smart home, security), dedicating a laptop is impractical.
### Proposed deployment model
```
[ESP32-S3 nodes] --UDP CSI--> [TV Box running Armbian + sensing-server] --HDMI--> [Display]
$25, always-on, fanless
```
### Future: custom WiFi firmware for standalone operation
Many TV box WiFi chipsets (Realtek RTL8822CS, MediaTek MT7661, Broadcom BCM43455) can potentially be patched for CSI extraction when running under Linux with custom drivers. This would eliminate the ESP32 dependency entirely for basic sensing:
```
[TV Box with patched WiFi driver] --CSI extraction--> [sensing-server on same box] --HDMI--> [Display]
$25 total, single device
```
This ADR covers Phase 1 (TV box as aggregator) and Phase 2 (custom WiFi firmware for CSI). Phase 2 is speculative and requires per-chipset R&D.
## Decision
### Phase 1: TV Box as Aggregator (Armbian)
1. **Cross-compile the sensing server** for `aarch64-unknown-linux-gnu` using `cross` or Docker-based cross-compilation.
2. **Create an Armbian deployment package** containing:
- Pre-built `wifi-densepose-sensing-server` binary (aarch64)
- systemd service file for auto-start on boot
- Kiosk-mode Chromium configuration for HDMI dashboard display
- Network configuration for ESP32 UDP reception (port 5005)
- Optional: `hostapd` config to create a dedicated WiFi AP for the ESP32 mesh
3. **Define minimum hardware requirements:**
| Component | Minimum | Recommended |
|-----------|---------|-------------|
| SoC | Amlogic S905W (A53 quad) | Amlogic S905X3 (A55 quad) |
| RAM | 2 GB | 4 GB |
| Storage | 8 GB eMMC + 8 GB SD | 16 GB eMMC + 16 GB SD |
| WiFi | 802.11n 2.4 GHz | 802.11ac dual-band |
| Ethernet | 100 Mbps | Gigabit |
| USB | 1x USB 2.0 | 2x USB 3.0 |
| HDMI | 1.4 | 2.0 |
4. **Tested reference devices** (initial target list):
| Device | SoC | WiFi Chip | Price | Armbian Support |
|--------|-----|-----------|-------|-----------------|
| T95 Max+ | S905X3 | RTL8822CS | ~$30 | Good (meson-sm1) |
| H96 Max X3 | S905X3 | RTL8822CS | ~$35 | Good (meson-sm1) |
| X96 Max+ | S905X3 | RTL8822CS | ~$28 | Good (meson-sm1) |
| Tanix TX6S | H616 | MT7668 | ~$25 | Moderate (sun50i-h616) |
5. **New Rust compilation target** in workspace CI:
- Add `aarch64-unknown-linux-gnu` to cross-compilation matrix
- Binary size target: <15 MB stripped (fits easily in SD card)
- No GPU dependency — CPU-only inference using `candle` or ONNX Runtime for ARM
### Phase 2: Custom WiFi Firmware for CSI Extraction (Future)
1. **CSI extraction feasibility by chipset:**
| Chipset | Driver | CSI Support | Monitor Mode | Effort |
|---------|--------|-------------|--------------|--------|
| Broadcom BCM43455 | brcmfmac | **Proven** (Nexmon CSI) | Yes | Low — patches exist |
| Realtek RTL8822CS | rtw88 | **Moderate** — driver is open-source, CSI hooks need adding | Yes (patched) | Medium |
| MediaTek MT7661 | mt76 | **Unknown** — MediaTek has released CSI tools for some chips | Yes | Medium-High |
2. **CSI extraction architecture** (Linux kernel driver modification):
```
[WiFi chipset firmware] → [Modified kernel driver] → [Netlink/procfs CSI export]
↓
[userspace CSI reader]
↓
[sensing-server UDP input]
```
The CSI data would be reformatted into the existing ESP32 binary protocol (ADR-018 header, magic `0xC5100001`) so the sensing server treats it identically to ESP32 frames. This means zero changes to the ingestion context.
3. **Hybrid mode**: When the TV box has both patched WiFi CSI and ESP32 UDP input, the sensing server's multi-node architecture (already supporting multiple `node_id` values) handles both sources transparently. The TV box's own WiFi becomes an additional viewpoint in the multistatic array.
### Phase 3: Android Companion App (Optional)
For users who want mobile monitoring without Armbian:
1. **PWA (Progressive Web App)**: The sensing server already serves a web UI. Adding a PWA manifest with offline caching makes it installable on any Android device. No native app needed.
2. **Native Android app** (future): Only if PWA proves insufficient. Would use Kotlin + Jetpack Compose, consuming the existing REST API and WebSocket endpoints.
## Deployment Architecture
### Single-Room Deployment (Phase 1)
```
┌──────────────────────────────────────────────────────────────┐
│ Room │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ ESP32-S3 │ │ ESP32-S3 │ │ ESP32-S3 │ CSI sensor mesh │
│ │ Node 1 │ │ Node 2 │ │ Node 3 │ ($10 each) │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────────────┼──────────────┘ │
│ │ UDP port 5005 │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Android TV Box (Armbian) │ │
│ │ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ wifi-densepose-sensing- │ │ │
│ │ │ server (aarch64 binary) │ │ │
│ │ │ │ │ │
│ │ │ • CSI ingestion (UDP) │ │ │
│ │ │ • Feature extraction │ │ │
│ │ │ • NN inference (CPU) │ │ │
│ │ │ • WebSocket streaming │ │ │
│ │ │ • REST API │ │ │
│ │ │ • Web UI (:3000) │ │ │
│ │ └──────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────┐ │ │
│ │ │ Chromium Kiosk Mode │───│──→ HDMI out │
│ │ │ (localhost:3000) │ │ to display │
│ │ └──────────────────────────────┘ │ │
│ │ │ │
│ │ Cost: $25-35 │ │
│ │ Power: 5-10W (USB-C or barrel) │ │
│ │ Form: fits behind TV/monitor │ │
│ └──────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
Total system cost: $55-65 (3 ESP32 nodes + 1 TV box)
```
### Multi-Room Deployment
```
┌──────────────┐
│ Router │
│ (WiFi AP) │
└──────┬───────┘
│ LAN
┌──────────────┼──────────────┐
│ │ │
┌───────▼───────┐ ┌───▼────────┐ ┌──▼──────────┐
│ Room A │ │ Room B │ │ Room C │
│ TV Box + │ │ TV Box + │ │ TV Box + │
│ 3x ESP32 │ │ 3x ESP32 │ │ 3x ESP32 │
│ HDMI display │ │ HDMI │ │ HDMI │
└───────────────┘ └────────────┘ └─────────────┘
Each room: self-contained sensing + display
Central dashboard: aggregate all rooms via REST API
```
### Standalone Mode (Phase 2 — Custom WiFi FW)
```
┌──────────────────────────────────────┐
│ Android TV Box (Armbian) │
│ │
│ ┌────────────────────┐ │
│ │ Patched WiFi │ │
│ │ Driver │ │
│ │ (CSI extraction) │ │
│ └─────────┬──────────┘ │
│ │ CSI frames │
│ ▼ │
│ ┌────────────────────┐ │
│ │ sensing-server │──→ HDMI out │
│ │ (inference + │ │
│ │ dashboard) │ │
│ └────────────────────┘ │
│ │
│ Single device: $25 │
│ No ESP32 nodes needed │
└──────────────────────────────────────┘
```
## Consequences
### Positive
- **10x cost reduction** for aggregator: $25 TV box vs $300+ laptop/PC
- **Always-on deployment**: Mains-powered, fanless, designed for 24/7 operation
- **HDMI output**: Direct connection to TV/monitor for wall-mounted dashboards
- **Familiar hardware**: Available globally, no specialized ordering required
- **Armbian ecosystem**: Mature Debian-based distro with package management, systemd, SSH
- **Path to standalone**: Custom WiFi firmware could eliminate ESP32 dependency entirely
- **PWA for mobile**: No native app development needed for mobile monitoring
- **Multi-room scaling**: One TV box per room, each self-contained
### Negative
- **ARM cross-compilation**: Adds CI complexity; `candle`/ONNX Runtime ARM builds need testing
- **Armbian compatibility**: Not all TV boxes are well-supported; need a tested device list
- **Performance uncertainty**: ARM A53 cores are ~3-5x slower than x86 for NN inference; may need model quantization (INT8) for real-time operation
- **Phase 2 risk**: Custom WiFi firmware is chipset-specific, may require kernel patches per driver version, and CSI quality varies by chipset
- **Support burden**: Different hardware = more configurations to support
- **No GPU**: TV boxes lack discrete GPU; inference is CPU-only (but our models are small enough)
### Neutral
- **No changes to existing ESP32 firmware** — TV box receives the same UDP frames
- **No changes to sensing server protocol** — Phase 2 CSI output uses same binary format
- **Existing web UI works as-is** — Chromium kiosk mode or any browser on the LAN
## Implementation Plan
### Phase 1 (2-3 weeks)
1. Add `aarch64-unknown-linux-gnu` cross-compilation target using `cross`
2. Build and test sensing-server binary on reference TV box (T95 Max+ / S905X3)
3. Create systemd service + Armbian deployment script
4. Benchmark: measure inference latency, memory usage, thermal throttling
5. Create `docs/deployment/armbian-tv-box.md` setup guide
6. Add HDMI kiosk mode configuration (Chromium autostart)
### Phase 2 (4-8 weeks, R&D)
1. Acquire TV box with BCM43455 (proven Nexmon CSI support)
2. Build Armbian with Nexmon CSI patches for BCM43455
3. Write userspace CSI reader → ESP32 binary protocol converter
4. Test CSI quality comparison: ESP32 vs BCM43455
5. If viable: add RTL8822CS CSI extraction via rtw88 driver modification
### Phase 3 (1 week)
1. Add PWA manifest to sensing server web UI
2. Test on Android Chrome, iOS Safari
3. Add service worker for offline dashboard caching
## References
- [Nexmon CSI](https://github.com/seemoo-lab/nexmon_csi) — Broadcom WiFi CSI extraction (BCM43455, BCM4339, BCM4358)
- [Armbian](https://www.armbian.com/) — Debian/Ubuntu for ARM SBCs and TV boxes
- [rtw88 driver](https://github.com/torvalds/linux/tree/master/drivers/net/wireless/realtek/rtw88) — Mainline Linux driver for Realtek 802.11ac chips
- [mt76 driver](https://github.com/torvalds/linux/tree/master/drivers/net/wireless/mediatek/mt76) — Mainline Linux driver for MediaTek WiFi chips
- [cross](https://github.com/cross-rs/cross) — Zero-setup Rust cross-compilation
- [ADR-018: ESP32 CSI Binary Protocol](ADR-018-dev-implementation.md) — Binary frame format reused for Phase 2 CSI extraction
- [ADR-039: Edge Intelligence](ADR-039-esp32-edge-intelligence.md) — On-device processing tiers
- [ADR-043: Sensing Server](ADR-043-sensing-server-ui-api-completion.md) — Single-binary deployment target
docs/adr/ADR-047-psychohistory-observatory-visualization.md
+152
View File
@@ -0,0 +1,152 @@
# ADR-047: RuView Observatory — Immersive Three.js WiFi Sensing Visualization
## Status
Accepted (Implemented)
## Date
2026-03-04
## Context
The project has a functional tabbed dashboard UI (`ui/index.html`) with existing Three.js components (body model, gaussian splats, signal visualization, environment). While effective for monitoring, it lacks a cinematic, immersive visualization suitable for demonstrations and stakeholder presentations.
We need an immersive Three.js room-based visualization with practical WiFi sensing data overlays — human wireframe pose, dot-matrix body mass, vital signs HUD, signal field heatmap — powered by ESP32 CSI data (demo mode with live WebSocket path).
## Decision
### Standalone Page Architecture
`ui/observatory.html` is a standalone full-screen entry point, separate from the tabbed dashboard. Linked via "Observatory" nav tab in `ui/index.html`. No build step — vanilla JS modules with Three.js r160 via CDN importmap.
### Room-Based Visualization
Instead of abstract holographic panels, the observatory renders a practical room scene with:
| Element | Implementation | Data Source |
|---------|---------------|-------------|
| Human wireframe | COCO 17-keypoint skeleton, CylinderGeometry tube bones, SphereGeometry joints with glow halos | `persons[].position`, `vital_signs.breathing_rate_bpm` |
| Dot-matrix mist | 800 Points with per-particle alpha ShaderMaterial, body-shaped distribution | `persons[].position`, `persons[].motion_score` |
| Particle trail | 200 Points with age-based fade, emitted from moving person | `persons[].position`, `persons[].motion_score` |
| Signal field | 400 floor-level Points with green→amber color ramp | `signal_field.values` (20×20 grid) |
| WiFi waves | 5 wireframe SphereGeometry shells, AdditiveBlending, pulsing outward | Always-on animation from router position |
| Router | BoxGeometry body, 3 CylinderGeometry antennas, pulsing LED, PointLight | Static scene element |
| Room | GridHelper floor, BoxGeometry wireframe boundary, reflective MeshStandardMaterial floor, furniture (table, bed) | Static scene element |
### HUD Overlay
Glass-morphism HTML panels overlaid on the 3D canvas:
- **Left panel (Vital Signs):** Heart rate (BPM), respiration (RPM), confidence (%) with animated bars
- **Right panel (WiFi Signal):** RSSI, variance, motion power, person count, 2D RSSI sparkline, presence state badge, fall alert
- **Top-right:** Data source badge (DEMO/LIVE), scenario badge, FPS counter, settings gear
- **Bottom:** Capability bar (Pose Estimation, Vital Monitoring, Presence Detection)
- **Bottom-right:** Keyboard shortcut hints
### Settings Dialog (4 Tabs)
Full customization with localStorage persistence and JSON export:
| Tab | Controls |
|-----|----------|
| **Rendering** | Bloom strength/radius/threshold, exposure, vignette, film grain, chromatic aberration |
| **Wireframe** | Bone thickness, joint size, glow intensity, particle trail, wireframe color, joint color, aura opacity |
| **Scene** | Signal field opacity, WiFi wave intensity, room brightness, floor reflection, FOV, orbit speed, grid toggle, room boundary toggle |
| **Data** | Scenario selector (auto-cycle or fixed), cycle speed, data source (demo/WebSocket), WS URL, reset camera, export settings |
### Demo-First with Live Data Path
Four auto-cycling scenarios (30s default, configurable) with 2s cosine crossfade:
| Scenario | Description |
|----------|-------------|
| `empty_room` | Low variance, no presence, flat amplitude, stable RSSI -45dBm |
| `single_breathing` | 1 person, breathing 16 BPM, HR 72 BPM, sinusoidal subcarrier modulation |
| `two_walking` | 2 persons, high motion, Doppler-like shifts, moving signal field peaks |
| `fall_event` | 2s variance spike at t=5s, then stillness, fall flag, confidence drop |
Data contract matches `SensingUpdate` struct from the Rust sensing server. Live WebSocket connection configurable in settings dialog.
### Post-Processing Pipeline
EffectComposer chain: RenderPass → UnrealBloomPass → custom VignetteShader
- **UnrealBloom:** strength 1.0, radius 0.5, threshold 0.25 (configurable)
- **VignetteShader:** warm shadow shift, edge chromatic aberration, film grain
- **Adaptive quality:** Auto-degrades when FPS < 25, restores when FPS > 55
### RuView Foundation Color Palette
| Role | Color | Hex |
|------|-------|-----|
| Background | Deep dark | `#080c14` |
| Primary wireframe | Green glow | `#00d878` |
| Warm accent | Amber | `#ffb020` |
| Signal | Blue | `#2090ff` |
| Heart / joints | Red | `#ff4060` |
| Alert | Crimson | `#ff3040` |
### Technology Choices
| Decision | Rationale |
|----------|-----------|
| Standalone page vs tab | Full-screen immersion, independent loading |
| Room-based vs abstract panels | Practical spatial context for WiFi sensing data |
| Vanilla JS + CDN, no build step | Matches existing `ui/` pattern, served as static files by Axum |
| Custom ShaderMaterial for mist | Per-particle alpha, body-shaped distribution, AdditiveBlending |
| CylinderGeometry tube bones | Visible at any zoom vs thin Line geometry |
| COCO 17-keypoint skeleton | Standard pose format, 16 bone connections |
| localStorage settings | Persistent customization without server round-trip |
| Adaptive quality | 3 levels, auto-switches based on FPS measurement |
### Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `A` | Toggle autopilot orbit |
| `D` | Cycle demo scenario |
| `F` | Toggle FPS counter |
| `S` | Open/close settings |
| `Space` | Pause/resume data |
## Files
| File | Purpose |
|------|---------|
| `ui/observatory.html` | Full-screen entry point with HUD overlay + settings dialog |
| `ui/observatory/js/main.js` | Scene orchestrator (~1,100 lines): room, wireframe, mist, trails, settings, HUD, animation loop |
| `ui/observatory/js/demo-data.js` | 4 scenarios with cosine crossfade, setScenario/setCycleDuration API |
| `ui/observatory/js/nebula-background.js` | Procedural fBM nebula + star field background sphere |
| `ui/observatory/js/post-processing.js` | EffectComposer: UnrealBloom + VignetteShader (chromatic, grain, warmth) |
| `ui/observatory/css/observatory.css` | Foundation color scheme, glass-morphism panels, settings dialog, responsive |
| `ui/index.html` | Modified: added Observatory nav link |
## Consequences
### Positive
- Standalone page does not affect existing dashboard stability
- Demo-first allows offline presentations without hardware
- Same `SensingUpdate` contract enables seamless live WebSocket switch
- Room-based visualization provides intuitive spatial context for WiFi sensing
- Dot-matrix mist gives visual body mass without occluding wireframe
- Full settings customization without code changes (localStorage + JSON export)
- Adaptive quality ensures usability on weaker hardware
- ~20 draw calls keeps performance well within budget
### Negative
- Additional static files served by Axum (minimal overhead)
- Three.js r160 loaded from CDN (no build step, matches existing pattern)
- Settings persistence is per-browser (localStorage, not synced)
### Risks
- CDN dependency for Three.js (mitigated: can vendor locally if needed)
- Post-processing may not work on very old GPUs (mitigated: adaptive quality disables bloom)
## References
- ADR-045: AMOLED display support
- ADR-046: Android TV / Armbian deployment
- Existing `ui/components/scene.js` — Three.js scene pattern
- Existing `ui/components/gaussian-splats.js` — ShaderMaterial pattern
- Existing `ui/services/sensing.service.js` — WebSocket data contract
docs/ddd/deployment-platform-domain-model.md
+648
View File
@@ -0,0 +1,648 @@
# Deployment Platform Domain Model
The Deployment Platform domain covers everything from cross-compiling the sensing server for ARM targets to managing TV box appliances running Armbian: provisioning devices, deploying binaries, configuring kiosk displays, and coordinating multi-room installations. It bridges the gap between the Sensing Server domain (which produces the binary) and the physical hardware it runs on.
This document defines the system using [Domain-Driven Design](https://martinfowler.com/bliki/DomainDrivenDesign.html) (DDD): bounded contexts that own their data and rules, aggregate roots that enforce invariants, value objects that carry meaning, and domain events that connect everything.
**Bounded Contexts:**
| # | Context | Responsibility | Key ADRs | Code |
|---|---------|----------------|----------|------|
| 1 | [Appliance Management](#1-appliance-management-context) | Device inventory, provisioning, health monitoring, OTA updates for TV box deployments | [ADR-046](../adr/ADR-046-android-tv-box-armbian-deployment.md) | `scripts/deploy/`, `config/armbian/` |
| 2 | [Cross-Compilation](#2-cross-compilation-context) | Build pipeline for aarch64, binary packaging, CI/CD release artifacts | [ADR-046](../adr/ADR-046-android-tv-box-armbian-deployment.md) | `.github/workflows/`, `Cross.toml` |
| 3 | [Display Kiosk](#3-display-kiosk-context) | HDMI output management, Chromium kiosk mode, screen rotation, auto-start | [ADR-046](../adr/ADR-046-android-tv-box-armbian-deployment.md) | `config/armbian/kiosk/` |
| 4 | [WiFi CSI Bridge](#4-wifi-csi-bridge-context) | Custom WiFi driver CSI extraction, protocol translation to ESP32 binary format | [ADR-046](../adr/ADR-046-android-tv-box-armbian-deployment.md) | `tools/csi-bridge/` |
| 5 | [Network Topology](#5-network-topology-context) | ESP32 mesh ↔ TV box connectivity, dedicated AP mode, multi-room routing | [ADR-046](../adr/ADR-046-android-tv-box-armbian-deployment.md), [ADR-012](../adr/ADR-012-esp32-csi-sensor-mesh.md) | `config/armbian/network/` |
---
## Domain-Driven Design Specification
### Ubiquitous Language
| Term | Definition |
|------|------------|
| **Appliance** | A TV box running Armbian with the sensing server deployed, treated as a managed device in the fleet |
| **Fleet** | The set of all appliances across a multi-room or multi-site installation |
| **Deployment Package** | A self-contained archive containing the sensing-server binary, systemd unit, configuration, and setup script for a target architecture |
| **Kiosk Mode** | Chromium running in full-screen, no-UI mode pointing at `localhost:3000`, auto-started by systemd on HDMI-connected appliances |
| **CSI Bridge** | A userspace daemon that reads CSI data from a patched WiFi driver and re-encodes it as ESP32-compatible UDP frames for the sensing server |
| **Dedicated AP** | An optional `hostapd`-managed WiFi access point on the TV box that creates an isolated network for ESP32 nodes |
| **OTA Update** | Over-the-air binary replacement: download new sensing-server binary, validate checksum, swap via atomic rename, restart service |
| **Reference Device** | A TV box model that has been tested and validated for Armbian + sensing-server deployment (e.g., T95 Max+ / S905X3) |
| **Provisioning** | First-time setup of an appliance: flash Armbian to SD, deploy package, configure WiFi, start services |
| **Health Beacon** | Periodic JSON payload sent by each appliance to a central coordinator (if multi-room) containing uptime, CPU temp, memory usage, inference latency, connected ESP32 count |
---
## Bounded Contexts
### 1. Appliance Management Context
**Responsibility:** Track deployed TV box appliances, provision new devices, monitor health, and coordinate OTA updates across the fleet.
```
+------------------------------------------------------------+
| Appliance Management Context |
+------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | Device | | Provisioning | |
| | Registry | | Service | |
| | (fleet state) | | (first-time | |
| | | | setup) | |
| +-------+--------+ +-------+--------+ |
| | | |
| +----------+----------+ |
| v |
| +-------------------+ |
| | Health Monitor | |
| | (beacon receiver,| |
| | thermal alerts, | |
| | connectivity) | |
| +--------+----------+ |
| v |
| +-------------------+ |
| | OTA Updater | |
| | (binary swap, | |
| | rollback, | |
| | checksum verify)| |
| +-------------------+ |
| |
+------------------------------------------------------------+
```
**Aggregates:**
```rust
/// Aggregate Root: A managed TV box appliance in the fleet.
/// Identified by MAC address of the primary Ethernet interface.
pub struct Appliance {
/// Unique device identifier (Ethernet MAC address).
pub device_id: DeviceId,
/// Human-readable name (e.g., "living-room", "bedroom-1").
pub name: String,
/// Hardware model (e.g., "T95 Max+ S905X3").
pub hardware_model: HardwareModel,
/// Current deployment state.
pub state: ApplianceState,
/// Installed sensing-server version.
pub server_version: SemanticVersion,
/// Network configuration.
pub network: NetworkConfig,
/// Last received health beacon.
pub last_health: Option<HealthBeacon>,
/// Provisioning timestamp.
pub provisioned_at: DateTime<Utc>,
/// Connected ESP32 node IDs (from last beacon).
pub connected_nodes: Vec<u8>,
}
/// Lifecycle states for an appliance.
pub enum ApplianceState {
/// SD card prepared, not yet booted.
Provisioned,
/// Booted and running, health beacons received.
Online,
/// No health beacon for >5 minutes.
Unreachable,
/// OTA update in progress.
Updating,
/// Manual maintenance / stopped.
Offline,
/// Thermal throttling or hardware issue detected.
Degraded,
}
```
**Value Objects:**
```rust
/// Hardware model specification for a TV box.
pub struct HardwareModel {
/// Marketing name (e.g., "T95 Max+").
pub name: String,
/// SoC identifier (e.g., "Amlogic S905X3").
pub soc: String,
/// WiFi chipset (e.g., "RTL8822CS").
pub wifi_chipset: String,
/// Total RAM in MB.
pub ram_mb: u32,
/// eMMC storage in GB.
pub emmc_gb: u32,
/// Whether CSI bridge is supported for this WiFi chipset.
pub csi_bridge_supported: bool,
/// Armbian device tree name (e.g., "meson-sm1-sei610").
pub armbian_dtb: String,
}
/// Periodic health report from an appliance.
pub struct HealthBeacon {
pub device_id: DeviceId,
pub timestamp: DateTime<Utc>,
pub uptime_secs: u64,
pub cpu_temp_celsius: f32,
pub cpu_usage_percent: f32,
pub memory_used_mb: u32,
pub memory_total_mb: u32,
pub disk_used_percent: f32,
pub inference_latency_ms: f32,
pub connected_esp32_nodes: Vec<u8>,
pub server_version: SemanticVersion,
pub csi_frames_per_sec: f32,
pub websocket_clients: u32,
}
/// Network configuration for an appliance.
pub struct NetworkConfig {
/// Primary IP address (Ethernet or WiFi client).
pub ip_address: IpAddr,
/// Whether the appliance runs a dedicated AP for ESP32 nodes.
pub dedicated_ap: Option<DedicatedApConfig>,
/// UDP port for ESP32 CSI reception.
pub csi_udp_port: u16, // default: 5005
/// HTTP port for sensing server.
pub http_port: u16, // default: 3000
}
/// Configuration for a dedicated WiFi AP hosted by the appliance.
pub struct DedicatedApConfig {
/// SSID for the ESP32 mesh network.
pub ssid: String,
/// WPA2 passphrase.
pub passphrase: String,
/// Channel (1-11 for 2.4 GHz).
pub channel: u8,
/// DHCP range for connected ESP32 nodes.
pub dhcp_range: (IpAddr, IpAddr),
}
/// Unique device identifier (Ethernet MAC).
pub struct DeviceId(pub [u8; 6]);
/// Semantic version for tracking installed software.
pub struct SemanticVersion {
pub major: u16,
pub minor: u16,
pub patch: u16,
pub pre: Option<String>,
}
```
**Domain Services:**
- `ProvisioningService` — Generates Armbian SD card image with pre-configured deployment package, WiFi credentials, and systemd units
- `HealthMonitorService` — Listens for UDP health beacons from fleet appliances, triggers alerts on thermal throttling (>80°C), unreachable (>5 min), or high memory usage (>90%)
- `OtaUpdateService` — Downloads new binary from release URL, verifies SHA-256 checksum, performs atomic swap (`rename(new, current)`), restarts systemd service, rolls back if health beacon fails within 60s
**Invariants:**
- Device ID (MAC address) is immutable after provisioning
- OTA update refuses to proceed if current CPU temperature >75°C (thermal headroom)
- Rollback is automatic if no healthy beacon is received within 60 seconds of restart
- Dedicated AP SSID must not match the upstream WiFi SSID
---
### 2. Cross-Compilation Context
**Responsibility:** Build the sensing-server binary for ARM64 targets, package deployment archives, and manage CI/CD release artifacts.
```
+------------------------------------------------------------+
| Cross-Compilation Context |
+------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | Cross.toml | | GitHub Actions| |
| | (target cfg) | | CI Matrix | |
| +-------+--------+ +-------+--------+ |
| | | |
| +----------+----------+ |
| v |
| +-------------------+ |
| | Build Pipeline | |
| | (cross build | |
| | --target | |
| | aarch64-unknown-| |
| | linux-gnu) | |
| +--------+----------+ |
| v |
| +-------------------+ |
| | Binary Packager | |
| | (strip, compress,|---> .tar.gz artifact |
| | bundle assets, | |
| | systemd units) | |
| +-------------------+ |
| |
+------------------------------------------------------------+
```
**Value Objects:**
```rust
/// A packaged deployment archive for a target platform.
pub struct DeploymentPackage {
/// Target triple (e.g., "aarch64-unknown-linux-gnu").
pub target: String,
/// Sensing server binary (stripped).
pub binary: PathBuf,
/// Binary size in bytes.
pub binary_size: u64,
/// SHA-256 checksum of the binary.
pub checksum: String,
/// Systemd service unit file.
pub service_unit: String,
/// Static web UI assets directory.
pub ui_assets: PathBuf,
/// Armbian configuration files (kiosk, network, etc.).
pub config_files: Vec<PathBuf>,
/// Setup script (runs on first boot).
pub setup_script: PathBuf,
/// Version being packaged.
pub version: SemanticVersion,
}
/// Build target specification.
pub struct BuildTarget {
/// Rust target triple.
pub triple: String,
/// CPU architecture description.
pub arch: String,
/// Whether NEON SIMD is available.
pub has_neon: bool,
/// Cross-compilation Docker image.
pub cross_image: String,
/// Binary size limit in bytes.
pub size_limit: u64,
}
```
**Supported Targets:**
| Target Triple | Architecture | Use Case | Size Limit |
|---------------|-------------|----------|------------|
| `x86_64-unknown-linux-gnu` | x86-64 | PC/laptop (existing) | 30 MB |
| `aarch64-unknown-linux-gnu` | ARM64 | TV box (Armbian) | 15 MB |
| `armv7-unknown-linux-gnueabihf` | ARMv7 | Older TV boxes (32-bit) | 12 MB |
| `x86_64-pc-windows-msvc` | x86-64 | Windows (existing) | 30 MB |
**Invariants:**
- Stripped binary must be under size limit for target
- SHA-256 checksum is computed and included in every deployment package
- UI assets are embedded in binary via `include_dir!` or bundled alongside
- No native GPU dependencies — CPU-only inference (candle or ONNX Runtime)
---
### 3. Display Kiosk Context
**Responsibility:** Manage HDMI output on TV box appliances, running Chromium in kiosk mode to display the sensing dashboard full-screen on boot.
```
+------------------------------------------------------------+
| Display Kiosk Context |
+------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | systemd | | Chromium | |
| | autologin + | | Kiosk Launch | |
| | X11/Wayland | | (full-screen, | |
| | session | | no-UI bars) | |
| +-------+--------+ +-------+--------+ |
| | | |
| +----------+----------+ |
| v |
| +-------------------+ |
| | Display Manager | |
| | (resolution, | |
| | rotation, | |
| | overscan, | |
| | sleep/wake) | |
| +-------------------+ |
| |
+------------------------------------------------------------+
```
**Value Objects:**
```rust
/// Display configuration for kiosk mode.
pub struct KioskConfig {
/// URL to display (default: "http://localhost:3000").
pub url: String,
/// Screen rotation in degrees (0, 90, 180, 270).
pub rotation: u16,
/// Whether to hide the mouse cursor.
pub hide_cursor: bool,
/// Auto-refresh interval in seconds (0 = disabled).
pub auto_refresh_secs: u32,
/// Display sleep schedule (e.g., off 23:00-06:00).
pub sleep_schedule: Option<SleepSchedule>,
/// Overscan compensation percentage (0-10).
pub overscan_percent: u8,
}
/// Sleep schedule for display power management.
pub struct SleepSchedule {
/// Time to turn display off (HH:MM local time).
pub sleep_time: String,
/// Time to turn display on (HH:MM local time).
pub wake_time: String,
}
```
**Invariants:**
- Chromium kiosk starts only after sensing-server systemd unit is `active`
- If Chromium crashes, systemd restarts it within 5 seconds (`Restart=always`)
- Display sleep/wake uses CEC commands (HDMI-CEC) to control TV power when available
- No browser UI elements are visible (address bar, scrollbars, etc.)
---
### 4. WiFi CSI Bridge Context
**Responsibility:** Extract CSI data from patched WiFi drivers on the TV box and translate it into ESP32-compatible binary frames for the sensing server. This is the Phase 2 custom firmware path.
```
+------------------------------------------------------------+
| WiFi CSI Bridge Context |
+------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | Patched WiFi | | CSI Reader | |
| | Driver | | (Netlink / | |
| | (kernel space)| | procfs / | |
| | CSI hooks | | UDP socket) | |
| +-------+--------+ +-------+--------+ |
| | | |
| +----------+----------+ |
| v |
| +-------------------+ |
| | Protocol | |
| | Translator | |
| | (chipset CSI → | |
| | ESP32 binary | |
| | 0xC5100001) | |
| +--------+----------+ |
| v |
| +-------------------+ |
| | UDP Sender | |
| | (localhost:5005) |---> sensing-server |
| +-------------------+ |
| |
+------------------------------------------------------------+
```
**Value Objects:**
```rust
/// Raw CSI extraction from a WiFi chipset.
pub struct ChipsetCsiFrame {
/// Source chipset type.
pub chipset: WifiChipset,
/// Timestamp of extraction (kernel monotonic clock).
pub timestamp_us: u64,
/// Number of subcarriers (varies by chipset and bandwidth).
pub n_subcarriers: u16,
/// Number of spatial streams / antennas.
pub n_streams: u8,
/// Channel frequency in MHz.
pub freq_mhz: u16,
/// Bandwidth (20/40/80/160 MHz).
pub bandwidth_mhz: u16,
/// RSSI in dBm.
pub rssi_dbm: i8,
/// Noise floor estimate in dBm.
pub noise_floor_dbm: i8,
/// Complex CSI values (I/Q pairs) per subcarrier per stream.
pub csi_matrix: Vec<Complex<f32>>,
/// Source MAC address (BSSID of the AP being measured).
pub source_mac: [u8; 6],
}
/// Supported WiFi chipsets for CSI extraction.
pub enum WifiChipset {
/// Broadcom BCM43455 via Nexmon CSI patches.
BroadcomBcm43455,
/// Realtek RTL8822CS via modified rtw88 driver.
RealtekRtl8822cs,
/// MediaTek MT7661 via mt76 driver modification.
MediatekMt7661,
}
/// Translated frame in ESP32 binary protocol (ADR-018).
pub struct Esp32CompatFrame {
/// Magic: 0xC5100001
pub magic: u32,
/// Virtual node ID assigned to this WiFi interface.
pub node_id: u8,
/// Number of antennas / spatial streams.
pub n_antennas: u8,
/// Number of subcarriers (resampled to match ESP32 format).
pub n_subcarriers: u8,
/// Frequency in MHz.
pub freq_mhz: u16,
/// Sequence number (monotonic counter).
pub sequence: u32,
/// RSSI in dBm.
pub rssi: i8,
/// Noise floor in dBm.
pub noise_floor: i8,
/// Amplitude values (extracted from complex CSI).
pub amplitudes: Vec<f32>,
/// Phase values (extracted from complex CSI).
pub phases: Vec<f32>,
}
```
**Domain Services:**
- `CsiExtractionService` — Reads raw CSI from patched driver via Netlink socket (BCM43455), procfs (RTL8822CS), or UDP (MT7661)
- `SubcarrierResamplerService` — Resamples chipset-specific subcarrier counts to match ESP32 format (e.g., 256 → 128 via decimation or interpolation)
- `ProtocolTranslatorService` — Converts `ChipsetCsiFrame` to `Esp32CompatFrame` with ADR-018 binary encoding
- `CalibrationService` — Compensates for chipset-specific phase offsets, antenna spacing, and gain differences relative to ESP32 CSI
**Invariants:**
- Bridge assigns virtual `node_id` in range 200-254 (reserved for non-ESP32 sources) to avoid collision with physical ESP32 node IDs (1-199)
- Subcarrier resampling preserves frequency ordering (lowest to highest)
- Phase values are unwrapped before encoding (continuous, not wrapped to ±π)
- Bridge daemon starts only if a compatible patched driver is detected at boot
---
### 5. Network Topology Context
**Responsibility:** Manage network connectivity between ESP32 sensor nodes and TV box appliances, including optional dedicated AP mode and multi-room routing.
```
+------------------------------------------------------------+
| Network Topology Context |
+------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | hostapd | | DHCP Server | |
| | (dedicated AP | | (dnsmasq for | |
| | for ESP32 | | ESP32 nodes) | |
| | mesh) | | | |
| +-------+--------+ +-------+--------+ |
| | | |
| +----------+----------+ |
| v |
| +-------------------+ |
| | Topology Manager | |
| | (node discovery, | |
| | IP assignment, | |
| | route config) | |
| +--------+----------+ |
| v |
| +-------------------+ |
| | Firewall Rules | |
| | (iptables/nft: | |
| | allow UDP 5005, | |
| | block external | |
| | access to ESP32 | |
| | subnet) | |
| +-------------------+ |
| |
+------------------------------------------------------------+
```
**Value Objects:**
```rust
/// Network topology for a single-room deployment.
pub struct RoomTopology {
/// Appliance acting as the aggregator.
pub appliance: DeviceId,
/// Whether the appliance runs a dedicated AP.
pub dedicated_ap: bool,
/// Connected ESP32 nodes with their assigned IPs.
pub nodes: Vec<EspNodeConnection>,
/// Upstream network interface (Ethernet or WiFi client).
pub uplink_interface: String,
/// Sensing network interface (dedicated AP or same as uplink).
pub sensing_interface: String,
}
/// An ESP32 node's network connection to the appliance.
pub struct EspNodeConnection {
/// ESP32 node ID (from firmware NVS).
pub node_id: u8,
/// MAC address of the ESP32.
pub mac: [u8; 6],
/// Assigned IP address (via DHCP or static).
pub ip: IpAddr,
/// Last CSI frame received timestamp.
pub last_seen: DateTime<Utc>,
/// Average CSI frames per second from this node.
pub fps: f32,
}
```
**Domain Services:**
- `DedicatedApService` — Configures `hostapd` to create a WPA2 AP on the TV box's WiFi interface, assigns DHCP range via `dnsmasq`, sets up IP forwarding
- `NodeDiscoveryService` — Monitors UDP port 5005 for new ESP32 node IDs, registers them in the topology, alerts on node departure (no frames for >30s)
- `FirewallService` — Configures `nftables`/`iptables` to isolate the ESP32 subnet from the upstream LAN, allowing only UDP 5005 inbound and HTTP 3000 outbound
**Invariants:**
- Dedicated AP uses a separate WiFi interface or virtual interface (not the uplink)
- ESP32 subnet is isolated from upstream LAN by default (firewall rules)
- If dedicated AP is disabled, ESP32 nodes must be on the same LAN subnet as the appliance
- Node discovery does not require mDNS or any discovery protocol — ESP32 nodes are configured with the appliance's IP via NVS provisioning (ADR-044)
---
## Domain Events
| Event | Published By | Consumed By | Payload |
|-------|-------------|-------------|---------|
| `ApplianceProvisioned` | Appliance Mgmt | Fleet Dashboard | `{ device_id, name, hardware_model, ip }` |
| `ApplianceOnline` | Appliance Mgmt | Fleet Dashboard | `{ device_id, server_version, uptime }` |
| `ApplianceUnreachable` | Appliance Mgmt | Fleet Dashboard, Alerting | `{ device_id, last_seen, reason }` |
| `ApplianceDegraded` | Appliance Mgmt | Fleet Dashboard, Alerting | `{ device_id, cpu_temp, reason }` |
| `OtaUpdateStarted` | Appliance Mgmt | Fleet Dashboard | `{ device_id, from_version, to_version }` |
| `OtaUpdateCompleted` | Appliance Mgmt | Fleet Dashboard | `{ device_id, new_version, duration_secs }` |
| `OtaUpdateRolledBack` | Appliance Mgmt | Fleet Dashboard, Alerting | `{ device_id, attempted_version, rollback_version, reason }` |
| `BinaryBuilt` | Cross-Compilation | Release Pipeline | `{ target, version, binary_size, checksum }` |
| `DeploymentPackageCreated` | Cross-Compilation | Appliance Mgmt | `{ target, version, package_url }` |
| `KioskStarted` | Display Kiosk | Appliance Mgmt | `{ device_id, url, resolution }` |
| `KioskCrashed` | Display Kiosk | Appliance Mgmt | `{ device_id, exit_code, restart_count }` |
| `CsiBridgeStarted` | WiFi CSI Bridge | Appliance Mgmt, Sensing Server | `{ device_id, chipset, virtual_node_id }` |
| `CsiBridgeFailed` | WiFi CSI Bridge | Appliance Mgmt | `{ device_id, chipset, error }` |
| `EspNodeDiscovered` | Network Topology | Appliance Mgmt | `{ appliance_id, node_id, mac, ip }` |
| `EspNodeLost` | Network Topology | Appliance Mgmt, Alerting | `{ appliance_id, node_id, last_seen }` |
| `DedicatedApStarted` | Network Topology | Appliance Mgmt | `{ appliance_id, ssid, channel }` |
---
## Context Map
```
+-------------------+ +---------------------+
| Appliance |--------->| Fleet Dashboard |
| Management | events | (external UI for |
| (fleet state) | -------> | multi-room mgmt) |
+--------+----------+ +---------------------+
|
| provisions, monitors
v
+-------------------+ +---------------------+
| Cross-Compilation |--------->| GitHub Releases |
| (build pipeline) | uploads | (binary artifacts) |
+-------------------+ +---------------------+
|
| provides binary
v
+-------------------+ +---------------------+
| Display Kiosk |--------->| Sensing Server |
| (Chromium on | loads | (upstream domain, |
| HDMI output) | UI from | produces web UI) |
+-------------------+ +----------+----------+
^
+-------------------+ |
| WiFi CSI Bridge |-----UDP 5005------>|
| (patched driver) | ESP32 compat |
+-------------------+ frames |
|
+-------------------+ |
| Network Topology |-----UDP 5005------>|
| (ESP32 mesh | ESP32 frames |
| connectivity) | |
+-------------------+ |
```
**Relationships:**
| Upstream | Downstream | Relationship | Mechanism |
|----------|-----------|--------------|-----------|
| Cross-Compilation | Appliance Mgmt | Supplier-Consumer | Build produces binary; Appliance Mgmt deploys it |
| Appliance Mgmt | Display Kiosk | Customer-Supplier | Appliance Mgmt starts kiosk after server is healthy |
| WiFi CSI Bridge | Sensing Server (external) | Conformist | Bridge adapts its output to match ESP32 binary protocol (ADR-018) |
| Network Topology | Sensing Server (external) | Shared Kernel | Both depend on UDP port 5005 and ESP32 node ID scheme |
| Appliance Mgmt | Network Topology | Customer-Supplier | Appliance config determines whether dedicated AP is enabled |
---
## Anti-Corruption Layers
### ESP32 Protocol ACL (CSI Bridge)
The WiFi CSI Bridge translates chipset-specific CSI formats (Nexmon, rtw88, mt76) into the ESP32 binary protocol (ADR-018). The sensing server never knows whether frames came from a real ESP32 or a TV box WiFi chipset. Virtual node IDs (200-254) prevent collision with physical ESP32 IDs but are otherwise treated identically by the ingestion context.
### Armbian Platform ACL
Appliance Management abstracts over Armbian specifics (device tree names, boot configuration, dtb overlays) through the `HardwareModel` value object. Higher-level contexts (Cross-Compilation, Display Kiosk) depend only on the target triple (`aarch64-unknown-linux-gnu`) and systemd service interface, not on Amlogic/Allwinner/Rockchip kernel specifics.
### Fleet Coordination ACL
For multi-room deployments, each appliance is self-contained (runs its own sensing server, display, and network). The fleet dashboard reads health beacons but never controls individual appliances directly. OTA updates are pulled by each appliance (not pushed), maintaining the appliance as the authority over its own state.
---
## Related
- [ADR-046: Android TV Box / Armbian Deployment](../adr/ADR-046-android-tv-box-armbian-deployment.md) — Primary architectural decision
- [ADR-012: ESP32 CSI Sensor Mesh](../adr/ADR-012-esp32-csi-sensor-mesh.md) — ESP32 mesh network design
- [ADR-018: Dev Implementation](../adr/ADR-018-dev-implementation.md) — ESP32 binary CSI protocol
- [ADR-039: Edge Intelligence](../adr/ADR-039-esp32-edge-intelligence.md) — On-device processing tiers
- [ADR-044: Provisioning Tool](../adr/ADR-044-provisioning-tool-enhancements.md) — NVS provisioning for ESP32 nodes
- [Hardware Platform Domain Model](hardware-platform-domain-model.md) — Upstream domain (ESP32 hardware)
- [Sensing Server Domain Model](sensing-server-domain-model.md) — Upstream domain (server software)