RuView 源码原理与实现技术过程

RuView 将 WiFi 无线信道从“通信链路”变成“空间传感器”。ESP32 读取每个 OFDM 子载波的 Channel State Information（CSI），人体移动、呼吸、姿态变化会改变多径传播路径，使复数信道响应 H(k,t) 的幅度与相位随时间产生可测扰动。

2.1 CSI 是什么

OFDM WiFi 会把带宽拆成多个子载波。每个子载波都有一个复数信道响应：

H(k,t) = A(k,t) · exp(j · φ(k,t))

A = √(I² + Q²)            # 幅度
φ = atan2(Q, I)           # 相位

人体出现后，直达路径、反射路径和绕射路径一起变化。结果不是“看到图像”，而是观察到 一组高维、随时间变化的无线通道特征。

4.1 Raw CSI 帧（ADR-018）

0..3    u32  magic = 0xC5110001
4       u8   node_id
5       u8   n_antennas
6..7    u16  n_subcarriers
8..11   u32  channel/frequency metadata
12..15  u32  sequence
16      i8   RSSI
17      i8   noise floor
18..19       flags / reserved
20..N        I/Q pairs

最小实现最重要的不是“复杂算法”，而是让 帧格式、字节序、序列号、采样节奏稳定，否则后面所有信号算法都会被脏数据拖垮。

4.2 为什么固件要双核

CSI callback 位于 WiFi 路径，不能做重计算。RuView 将采集和 DSP 解耦：Core 0 只采集/入环形缓冲区，Core 1 处理 phase、variance、filter。这种结构避免 WiFi 任务因为 DSP 阻塞而丢包。

Core 0: WiFi CSI callback
    ↓  enqueue
SPSC Ring Buffer
    ↓
Core 1: phase → stats → filters → events

5.1 数据模型

wifi-densepose-signal::CsiData 将原始数据统一成 amplitude[antenna, subcarrier] 与 phase[antenna, subcarrier]，然后所有算法围绕同一数据结构运行。

5.2 相位为什么必须 sanitize

atan2 输出被限制在 [-π, π]，真实连续相位跨过边界时会突然跳 2π。如果不 unwrap，速度、呼吸频率、相位加速度都会出现伪峰值。

raw:       2.9, 3.0, 3.1, -3.1, -3.0
unwrap:    2.9, 3.0, 3.1,  3.18, 3.28

6.1 Presence

最简单可靠的学习版本可以只做“空房校准 + 相位方差”。RuView 的 Edge Pipeline 使用 Welford 在线统计维护均值/方差，并采用约 1200 帧、3σ 的自适应阈值。

# 空房标定
μ0, σ0 = running_stats(phase_variance)

# 在线
score = current_variance
presence = score > μ0 + 3 * σ0

这不是“识别人”，而是“检测 RF 场相对空房基线是否出现明显扰动”。风扇、门、微波炉、AP 发射功率变化都可能产生误报。

6.4 Rust vitals crate 四阶段

1. CsiVitalPreprocessor：EMA 去除静态分量；
2. BreathingExtractor：0.1–0.5 Hz 带通 + 零交叉；
3. HeartRateExtractor：0.8–2.0 Hz 带通 + 自相关 + 子载波相干性加权；
4. VitalAnomalyDetector：Welford Z-score 做趋势/异常检测。

v2/crates/wifi-densepose-sensing-server/src/main.rs 是单二进制部署面。它用 Axum + Tokio 把底层 CSI、模型、训练、状态和 UI 统一起来。

Pose 的目标是学习映射：

CSI time window
    ↓
Encoder / embedding
    ↓
spatial-temporal representation
    ↓
17 keypoints / pose state

但真正难点是 监督数据：需要 WiFi CSI 与摄像头/动作捕捉标签严格时间对齐。单房间、单 AP、单人的训练数据通常会产生很强的域过拟合。

推荐阅读顺序

README → user-guide → ADR-018 → firmware README → csi_collector → csi_frame → phase_sanitizer → features → vitals → sensing-server。

不要先读 100+ Cogs、World Model、Matter、Agent、HomeKit 等外围模块。那会稀释对核心 RF sensing pipeline 的理解。

10.1 无硬件：Docker / 模拟数据

docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 -p 5005:5005/udp \
  -e CSI_SOURCE=simulated \
  ruvnet/wifi-densepose:latest

目标不是验证“WiFi 能看人”，而是先理解 UI、API、WebSocket 消息、状态结构和完整软件链。

10.2 Rust 源码运行

git clone https://github.com/ruvnet/RuView.git
cd RuView/v2

cargo build --release
cargo test --workspace --no-default-features

cargo run -p wifi-densepose-sensing-server -- \
  --http-port 3000 \
  --source simulate

10.3 ESP32-S3 实机

# 1. ESP-IDF 构建
cd firmware/esp32-csi-node
idf.py set-target esp32s3
idf.py build

# 2. flash
idf.py -p /dev/ttyUSB0 flash

# 3. 写入 WiFi 与 server IP
python provision.py \
  --port /dev/ttyUSB0 \
  --ssid "YOUR_WIFI" \
  --password "YOUR_PASS" \
  --target-ip 192.168.1.20

# 4. server
cd ../../v2
cargo run -p wifi-densepose-sensing-server -- \
  --source esp32 \
  --udp-bind 0.0.0.0 \
  --udp-allow 192.168.1.0/24

11.1 Mini-RuView 最小目录

mini-ruview/
├── firmware/
│   └── esp32/
│       ├── main.c
│       ├── csi.c
│       └── udp.c
├── server/
│   ├── protocol.rs
│   ├── csi.rs
│   ├── phase.rs
│   ├── presence.rs
│   ├── vitals.rs
│   └── main.rs
├── simulator/
│   └── synth_csi.py
├── ui/
│   └── index.html
└── tests/
    ├── protocol/
    └── signals/

11.2 MVP 的核心 Rust 逻辑

// 伪代码
loop {
    let packet = udp.recv().await?;
    let frame = parse_adr018(packet)?;

    let amp = iq_to_amplitude(&frame.iq);
    let phase = iq_to_phase(&frame.iq);
    let clean = unwrap_and_smooth(phase);

    baseline.update_if_calibrating(&clean);
    let score = phase_variance(&clean);

    let presence = score > baseline.mean + 3.0 * baseline.std;

    ws.broadcast(json!({
        "type": "sensing_update",
        "node": frame.node_id,
        "presence": presence,
        "score": score
    }));
}

必须记录的工程指标

推荐的产品化优先级

Presence → Motion → Room Activity → Breathing Trend → Fall Risk → Multi-room → Pose。

这是按“可验证性 / 数据需求 / 泛化难度”排序，而不是按视觉炫酷程度排序。

• RF sensing 不是稳定成像。房型、家具、AP、节点朝向都会改变多径场。
• 训练集 benchmark ≠ 现场准确率。必须给出数据集、split、环境与硬件条件。
• 多人的可分离性明显更难。单天线/少节点情况下尤其受限。
• 生命体征需要参考设备验证。不要把实验性 BPM 输出当医疗结论。
• 隐私风险是真实的。无需摄像头不等于无需授权；部署应明确告知、限制采集范围、最小化原始 CSI 保存，并优先本地处理。

GitHub · ruvnet/RuView

docs/user-guide.md — 安装、运行、数据源与训练入口

firmware/esp32-csi-node — ESP32 CSI 采集与 Edge DSP

ADR-018 — CSI 二进制协议与实现顺序

ADR-039 — ESP32 Edge Intelligence

wifi-densepose-signal — CSI / phase / features

wifi-densepose-vitals — 呼吸与心率

wifi-densepose-sensing-server — 运行时中枢