Repository analysis · 2026-09-15
RuView 技术学习手册
从 Wi‑Fi 信道状态信息（CSI）出发，理解 RuView 如何完成无摄像头的在场检测、动作分析、呼吸/心率估计、多节点融合与自动化输出；同时区分已经落地的代码、公开数据集结果和仍处于实验阶段的能力。
Rust 主链路
ESP32-S3 / C6
CSI + I/Q
Axum + WebSocket
Python PyO3
MIT License
一句话理解：RuView 不是“让路由器拍照”，而是测量人体对多径无线信道造成的微小扰动，再把幅度、相位、频谱与多节点一致性转换成概率性状态。它更接近“无线雷达 + 信号处理平台”，不是视觉摄像头的等价替代品。
3,407仓库文件（快照统计）
63v2 Rust crate 清单
265ADR 架构决策文件
结论先行
| 问题 | 结论 | 证据级别 |
|---|---|---|
| CSI 采集与解析是否真实存在？ | 存在。ESP-IDF 回调采集 I/Q，ADR-018 二进制协议经 UDP 传输，Rust 端严格解析。 | 代码已实现 |
| 在场、动作、呼吸、心率是否有算法？ | 存在。包括阈值/统计、EMA、带通滤波、过零与自相关等链路。 | 代码已实现 |
| Docker 演示是否等于真实硬件效果？ | 不等于。Docker 默认是模拟数据，用于体验 UI 与接口。 | 模拟环境 |
| 单 ESP32 能否稳定输出高质量 17 点姿态？ | 当前不能这样承诺。本地首版模型精度低，缺模型时运行时返回居中骨架且置信度为 0。 | 能力未成熟 |
| 能否直接用于医疗、救援或安全停机？ | 不应直接使用。必须针对硬件、房间、人群和失败条件进行独立验证与认证。 | 不可直接生产 |
02
CSI 感知原理：人体改变的是“信道”
Wi‑Fi 接收端不仅能得到 RSSI，还可以在支持的芯片上获得各个 OFDM 子载波的复数信道响应。每个子载波可写成：
Hk(t) = Ik(t) + jQk(t) = Ak(t)ejφk(t)
代码按 A = √(I² + Q²) 计算幅度，按 φ = atan2(Q, I) 计算相位。人体进入、移动或呼吸时，不同传播路径的距离和反射系数变化，导致一组子载波上的幅度/相位随时间产生结构化变化。
Hk(t) = Σp ap(t)e−j2πfkτp(t)
空间维度
不同子载波、天线、频道和收发链路对人体位置的敏感度不同。多节点从多个视角观察相同空间，可提高定位和抗遮挡能力。
时间维度
走动表现为较强、较快的变化；呼吸通常位于约 0.1–0.5 Hz；心搏相关微动位于约 0.8–2.0 Hz。滤波器从混合扰动中分离不同频带。
关键前提：普通笔记本通常只能读 RSSI，无法提供完整 CSI。高级能力需要 ESP32-S3/C6、Intel 5300、Atheros 等能够导出 CSI 的硬件；“已有 Wi‑Fi”不代表“不需要 CSI 采集设备”。
03
端到端链路：从无线帧到房间状态
1. 采集ESP32 CSI callback 获取 I/Q、RSSI、噪声底、频道与序号
2. 传输ADR-018 二进制帧；UDP 5005；同端口可复用 vitals/feature 包
3. DSP去噪、窗口、归一化、相位清洗、频谱与统计特征
4. 感知在场/动作、呼吸/心率、人数、姿态或语义状态
5. 多节点融合按一致性加权，检测节点矛盾、漂移与网络分裂风险
6. 治理校准 ID、模型版本、隐私等级、来源与 witness 进入结果
7. 服务Axum 提供 REST、WebSocket、静态 UI 与训练/配置接口
8. 集成Python SDK、MQTT/Home Assistant、Matter/HomeKit 等消费状态
ADR-018 原始 CSI 帧
| 偏移 | 字段 | 作用 |
|---|---|---|
| 0–3 | Magic 0xC5110001 | 识别原始 CSI 包，避免把其它边缘包误当作 CSI。 |
| 4–7 | 节点、天线数、子载波数 | 建立数据维度并进行边界检查。 |
| 8–15 | 频率、序列号 | 区分频道，检测丢包与排序问题。 |
| 16–19 | RSSI、噪声底、PPDU、flags | 信号质量与 HT/HE、带宽、STBC/LDPC 等上下文。 |
| 20+ | I/Q pairs | 按天线 × 子载波排列的有符号 8 位复数样本。 |
固件对高频回调做早期限流，默认把主处理/UDP 发送约束在 50 Hz 上限附近，边缘 DSP 还有独立采样节奏，以降低 Wi‑Fi 中断、内存和网络缓冲压力。
04
代码架构：主干是 Rust，硬件与接口围绕它展开
RuView/
firmware/esp32-csi-node/ ESP-IDF 采集、边缘 DSP、UDP、OTA
v2/crates/ 现代 Rust 工作区（63 个 crate）
wifi-densepose-hardware 协议、硬件适配、帧解析
wifi-densepose-signal CSI 预处理与特征算法
wifi-densepose-vitals 呼吸、心率、异常状态
wifi-densepose-engine 融合、质量、隐私、来源与 witness
wifi-densepose-sensing-server UDP / REST / WebSocket / UI
wifi-densepose-calibration 空房基线与房间专用模型
cog-* / homecore-* 边缘模块与家庭自动化
python/ PyO3 绑定、客户端与示例
ui/ 实时可视化、训练和设置面板
archive/v1/ 旧 Python 线，仅保留验证与历史参考
docs/adr/ 架构决策；需与当前代码交叉核对
| 模块 | 职责 | 建议关注 |
|---|---|---|
csi_collector.c | ESP-IDF CSI 回调、速率门、ADR-018 序列化、UDP 发送 | 真实数据入口与时间节奏 |
esp32_parser.rs | 严格解析帧头、I/Q、HT/HE 与带宽；错误时不生成假数据 | 协议边界和输入可信度 |
csi_processor.rs | 幅度阈值去噪、Hamming 窗、标准差归一化、历史缓冲 | DSP 基础链路 |
phase_sanitizer.rs | 相位展开、异常值移除、平滑和噪声过滤 | 相位稳定性 |
motion.rs | 融合幅度方差、相关性、相位与 Doppler；EMA 与自适应阈值 | 规则型在场检测 |
breathing.rs / heartrate.rs | 呼吸带通 + 过零；心搏带通 + 自相关；输出置信度和状态 | 生命体征是估计值 |
sensing-server | 接入多种帧、特征、平滑、分类、路由、WebSocket、MQTT | 系统集成中心，main.rs 很大 |
engine | 多节点一致性融合、漂移/分裂风险、隐私降级、来源与 witness | “可信输出”控制面 |
维护性观察：
sensing-server/src/main.rs 在快照中超过 13,000 行，是功能集中与耦合风险最高的入口；学习时应从小 crate 向服务端汇合，不建议从该文件第一行顺读。05
核心算法：规则 DSP、时序统计与模型并存
5.1 预处理
幅度处理
- 转 dB：
20·log10(A + ε) - 低于噪声阈值的幅度置零
- 对子载波施加 Hamming 窗降低频谱泄漏
- 用全阵列标准差归一化
相位处理
- 把
−π/π跳变展开为连续相位 - 移除异常点
- 滑动平滑与噪声过滤
- 提取相位方差、梯度与相干性
5.2 动作与在场
MotionDetector 不是单一神经网络分类器，而是把多个可解释指标合成分数：幅度方差越偏离基线、相关矩阵越偏离静态结构、相位方差越高/相干性越低、Doppler 能量越大，运动分数越高。
motion = wv·variance + wc·correlation + wφ·phase + wd·doppler
在场置信度再由幅度、相位、运动三个二值指标按默认 0.4 / 0.3 / 0.3 加权，经过 EMA 抑制闪烁。开启自适应阈值后，阈值取近期运动分数的 均值 + 1σ，并限制在 0.3–0.95。
理解重点：这类检测依赖“与房间基线相比发生了什么变化”，并不直接证明变化由人产生。宠物、风扇、门、窗帘、家具移动和邻近无线干扰都可能影响结果。
5.3 呼吸估计
多个子载波残差先按权重融合成单通道信号，再通过 0.1–0.5 Hz 二阶 IIR 带通。历史窗口达到最低样本数后统计过零次数：
fresp ≈ crossings / (2T) ； BPM = 60fresp
置信度来自估计周期上的归一化自相关，输出分为 Valid、Degraded、Unreliable。这里的状态是软件质量标签，不是临床认证。
5.4 心率估计
心率链路使用相邻子载波的相位相干性为幅度残差加权，经过 0.8–2.0 Hz 带通，然后在允许频带对应的 lag 范围内寻找最大自相关峰：
fheart = fs / lagpeak ； BPM = 60fheart
置信度综合自相关峰强度与有效子载波数量。运动伪影、采样率错误、单链路信噪比低都会让结果退化。
5.5 多节点融合与可信输出
StreamingEngine::process_cycle 对多节点帧做一致性评分与加权融合，检查节点校准 ID 是否一致、阵列是否矛盾、耦合图是否接近分裂；不可靠时降低可发布信息的隐私/信任等级，并把模型版本、校准版本、证据引用和隐私决定写入确定性 witness。
工程价值：RuView 的特色不只在“识别”，还在于尝试让每个感知结论带上质量、来源和降级路径。这使下游自动化有机会区分“检测到”与“检测到但证据不足”。
06
模型与成熟度：不要把三条模型线混为一谈
| 模型/路径 | 可证明的结果 | 正确解读 |
|---|---|---|
| CSI 对比学习编码器 + presence head | 项目报告 82.3% held-out temporal-triplet accuracy；128 维 embedding；有 4-bit 版本 | 这是表征/三元组任务结果，不应直接写成“真实家庭在场准确率 82.3%”。 |
| MM-Fi 17 点姿态模型 | 项目报告 random_split 下 82.69% torso-PCK@20，集成 83.59% | 公开数据集与特定协议结果；不能直接迁移成单 ESP32、陌生房间的现场准确率。 |
仓库内 pose_v1.safetensors | 模型说明给出 PCK@20 约 3.0%、PCK@50 18.5% | 首版边缘模型，明显低于 ≥35% 目标；只能作为接线与训练流程样例。 |
| 无权重 fallback | 运行时返回居中骨架，confidence = 0 | 保证接口可用，不代表获得了真实姿态。 |
archive/v1 DensePoseHead | 只有架构和随机初始化，无可用 checkpoint | 历史线，不能用于宣称姿态能力。 |
必须保留的限定：同一 README 的不同段落对低精度 camera-free pose 写有约 2.5% 与 3.0% 两种数字，说明文档仍在快速演进。稳妥表述应为“约 2.5–3.0%，远低于目标，现场链路尚未成熟”，并固定代码提交与评测协议。
为什么公开榜单高，现场单节点低？
- 数据集使用的天线阵列、子载波布局、采样率和人物/房间分布与 ESP32-SISO 不同。
random_split可能让训练集与测试集共享人物或环境统计特征；跨主体、跨房间更难。- 姿态估计需要细粒度空间信息，单天线 56 子载波 × 20 帧窗口的信息量有限。
- 模型权重、解码器结构、预处理参数和实际采集协议必须完全兼容。
07
校准为何必要：每个房间都有自己的多径指纹
墙体、家具、路由器位置、天线方向和硬件增益都会形成固定多径。RuView 先学习空房状态，再把运行时观测转换成相对残差；房间变化后，旧基线可能失效。
Stage 1空房基线 — 默认 30 秒，至少 600 帧；不足时明确失败。
Stage 2引导式 enrollment — empty、站立、坐、躺、慢呼吸、正常呼吸、小动作、睡姿等 8 个 anchor。
Stage 3质量门 — 每个 anchor 检查帧数、presence z-score 和动作比例；失败可重试。
Stage 4房间 specialist bank — 针对 presence、异常、restlessness、posture 等任务分别训练。
Stage 5运行与重校准 — 低一致性、环境变化点或网格风险触发重校准建议。
wifi-densepose calibrate --port <PORT>
wifi-densepose enroll --room <NAME>
wifi-densepose train-room --room <NAME>
wifi-densepose room-status --room <NAME>
wifi-densepose room-watch --room <NAME>现实约束：校准指南说明，完整
baseline → enroll → train-room → infer 流程主要由确定性合成 CSI 测试证明，真实房间的端到端充分性仍需现场验证；宠物也没有被代码可靠地区分。08
使用与部署：按目标选择入口
A. 先体验 UI 与接口：Docker 模拟模式
docker pull ruvnet/wifi-densepose:latest
docker run --rm -p 3000:3000 ruvnet/wifi-densepose:latest
# 浏览器打开 http://localhost:3000适合确认界面和事件结构；不能用于判断真实精度。
B. 真实 CSI：ESP32 + Rust sensing-server
git clone https://github.com/ruvnet/RuView.git
cd RuView
# 烧录官方 release_bins 中与板型匹配的固件后进行配网
python firmware/esp32-csi-node/provision.py \
--port /dev/ttyUSB0 \
--ssid "YOUR_WIFI" \
--password "YOUR_PASSWORD" \
--target-ip 192.168.1.20
cd v2
cargo run -p wifi-densepose-sensing-server --release -- \
--source esp32 \
--udp-bind 0.0.0.0 \
--udp-allow 192.168.1.0/24 \
--ui-path ../ui服务端默认 HTTP 8080、WebSocket 8765、UDP 5005。开放 UDP 到局域网时应配置来源 IP/CIDR 白名单，避免未经认证的 UDP 数据污染结果。
C. Python 集成：调用编译后的 DSP
pip install ruview
# 需要 WebSocket / MQTT 客户端时：
pip install "ruview[client]"from ruview import BreathingExtractor
extractor = BreathingExtractor.esp32_default()
for residuals, weights in your_csi_source:
estimate = extractor.extract(residuals=residuals, weights=weights)
if estimate and estimate.confidence >= 0.7:
print(estimate.value_bpm)Python 包提供 DSP/客户端，不会让不支持 CSI 的电脑自动获得完整 CSI；调用者仍需提供真实残差流。
D. 阅读和验证核心代码
cd RuView/v2
cargo test -p wifi-densepose-hardware --no-default-features
cargo test -p wifi-densepose-signal --no-default-features
cargo test -p wifi-densepose-vitals --no-default-features
cargo build -p wifi-densepose-sensing-server --release完整 workspace 含子模块、桌面和可选 ML 后端，首次学习更适合从三个小 crate 开始。
采样率陷阱：Python extractor 的 ESP32 默认示例是 100 Hz，而当前固件网络/DSP 可能以 8–50 Hz 工作。带通和 BPM 计算必须使用实际数据节奏；采样率配置错误会直接把频率映射错位。
09
使用场景：按风险与成熟度分层
| 层级 | 适合场景 | 价值 | 落地条件 |
|---|---|---|---|
| 优先尝试 | 智能家居房间占用、灯光/HVAC 非关键自动化 | 无摄像头、黑暗可用、可穿墙 | 2+ 节点、空房校准、超时回退、允许偶发误触发 |
| 优先尝试 | 办公室/教室/展馆利用率研究 | 统计区域活跃度，不采集画面 | 只做聚合趋势；现场标注验证；明确告知使用者 |
| 优先尝试 | Wi‑Fi 感知算法、边缘 AI、无线协议教学 | 从固件、DSP 到 API 的完整工程样本 | 固定 commit，复现实验，区分模拟与真实数据 |
| 需验证 | 睡眠呼吸趋势、静息心率趋势 | 非接触、连续观察 | 与认证设备同步对照；仅作趋势；运动/多人时降级 |
| 需验证 | 零售客流、排队长度、多人计数 | 降低摄像头依赖 | 多节点布局、分时标注、密度边界测试、宠物/物体干扰测试 |
| 需验证 | 跨房间动作/姿态研究、机器人感知补充 | 在遮挡、暗光下提供额外信号 | 多天线/多节点、兼容模型、房间微调，与视觉/雷达融合 |
| 不应直用 | 医疗诊断、呼吸暂停诊断、心律失常判定 | 风险过高 | 需要临床研究、法规审批和故障安全设计；项目本身不是医疗器械 |
| 不应直用 | 救援定位、工业安全停机、老人跌倒唯一报警源 | 漏报后果严重 | 只能作为冗余传感器，不能取代认证系统和人工流程 |
| 不应直用 | 隐蔽人员监控、身份识别或无告知行为分析 | 存在严重伦理与合规风险 | 必须有合法依据、透明告知、最小化采集和严格访问控制 |
最佳首个项目：选择一个房间，用 2 个 ESP32 做“有人 / 无人 / 移动”三态识别，并把结果发布到 Home Assistant；先测 7 天误报/漏报、房门/HVAC/宠物影响，再决定是否继续生命体征或多人任务。
10
能力边界与工程风险
物理边界
- 墙体材质、距离、天线姿态和遮挡会改变可观测性。
- 多人信号叠加是欠定问题，人数增加后可分离性迅速下降。
- 呼吸/心搏微动容易被走动和环境振动淹没。
- 单节点缺少几何视角，定位与姿态分辨率有限。
工程边界
- 仓库处于 Beta，API、固件与文档变化快。
- README、构建指南和当前 workspace 规模存在版本差异。
- UDP 原始数据面默认无认证，应限制绑定地址与来源。
- 完整 workspace 依赖多个 Git submodule 与可选后端。
模型边界
- 数据集成绩不等同于陌生房间、陌生人群的现场成绩。
- 权重格式、解码器、输入形状和预处理必须兼容。
- 置信度可能是固定验证常数，不一定是逐帧校准概率。
- 没有模型时的占位输出必须在 UI 中清晰标记。
隐私与合规边界
- 没有视频会降低视觉隐私风险，但不会自动免除隐私法规。
- 在场、行为和生命体征仍可能构成敏感个人数据。
- 应最小化原始 CSI 留存，限制用途、访问和保存期限。
- 安全关键动作必须采用多传感器与人工确认。
“宣传语”转成“可验收需求”
| 不要只写 | 改写为 |
|---|---|
| 穿墙检测 | 在指定墙体、距离、节点位置、人数和无线干扰条件下，presence F1 ≥ X，连续 7 天。 |
| 实时心率 | 静息单人、固定姿态下，与 ECG/胸带对齐后 MAE ≤ X BPM；运动时输出 unavailable。 |
| 多人计数 | 0–N 人、不同站位的混淆矩阵；明确超过 N 时的降级行为。 |
| 隐私安全 | 列出采集字段、推断字段、保存期限、访问者、删除方式与 consent 流程。 |
11
学习路线：按一条真实数据流推进
Day 1运行模拟版 — 观察 UI、WebSocket 消息和传感状态，但标记为 synthetic。
Day 2–3读协议与硬件 — 从
csi_collector.c 到 esp32_parser.rs，手工解析一帧 ADR-018。Day 4–5读 DSP — 复现 I/Q→幅相、去噪、Hamming、归一化、相位展开。
Week 2在场与生命体征 — 对合成正弦与噪声做单元实验，检查频带、窗口、置信度。
Week 3接真实 ESP32 — 空房/有人/移动各采集数据，记录 fps、丢包、RSSI 与误报。
Week 4校准和多节点 — 比较 1/2/3 节点；故意移动家具、开关 HVAC，观察漂移。
Week 5系统集成 — 把可信度、stale、unavailable 一并接入 Home Assistant，而非只传布尔值。
Week 6模型实验 — 固定数据集 split 与 PCK 定义，区分公共基准、房间内和跨房间结果。
推荐代码阅读顺序
- firmware/.../csi_collector.c：数据怎样进入系统。
- hardware/esp32_parser.rs：线协议怎样变成类型。
- signal/csi_processor.rs 与 phase_sanitizer.rs：清洗。
- signal/motion.rs：可解释检测逻辑。
- vitals/breathing.rs 与 heartrate.rs：时序频率估计。
- sensing-server/csi.rs：特征、平滑与分类怎样进入服务。
- engine/lib.rs：融合、质量和 provenance。
- cog-pose-estimation/inference.rs：权重与 fallback 的真实边界。
12
项目评估清单
| 维度 | 最少记录 | 通过标准示例 |
|---|---|---|
| 数据真实性 | source、设备、固件、频道、fps、丢包率、是否 synthetic | 真实与模拟消息不可混淆 |
| 可复现性 | commit、配置、模型 hash、校准 ID、数据 split | 同输入可复算；变更有版本记录 |
| 检测效果 | precision、recall、F1、延迟、连续 7 天误报 | 在目标房间达到预先定义阈值 |
| 生命体征 | 与参考设备时间同步后的 MAE、覆盖率、unavailable 比例 | 运动/低质量时拒绝输出，不伪造稳定值 |
| 泛化能力 | 跨主体、跨房间、家具变化、HVAC、宠物 | 分别报告，不用 random_split 代替跨域测试 |
| 安全 | UDP allowlist、凭证、TLS、升级签名、日志脱敏 | 默认局部绑定；不接受任意 LAN 注入 |
| 隐私 | 原始/派生数据字段、用途、保留期、删除与权限 | 数据最小化；敏感推断可关闭 |
| 失败策略 | 节点离线、低 SNR、校准过期、模型缺失、多人超限 | 输出 degraded/unavailable；安全动作不单点触发 |
13
术语表
CSI
Channel State Information，各子载波/天线的复数信道响应。
I/Q
复数信号的同相与正交分量，可转换为幅度和相位。
OFDM 子载波
把宽带信道划分成多个窄带频率单元，提供频率维度观测。
Multipath
信号经墙、家具和人体形成多条传播路径后叠加。
PCK@20
关键点预测误差小于某个归一化阈值的比例；必须说明归一化定义。
EMA
指数移动平均，用历史置信度抑制瞬时抖动。
Calibration ID
标识一轮环境基线/校准，使结果可追溯到使用的房间状态。
Provenance / witness
记录结果来自哪些证据、模型、校准与隐私决策。
14
代码依据与版本快照
分析快照：
33a9e90896a691a3f98de042b463e5945178b87c（main，提交时间 2026-09-11 UTC）。仓库持续更新，命令、数字和目录应以使用时的固定提交为准。- RuView repository — 项目入口、README、许可与最新代码。
- README.md — 功能定位、快速开始、硬件、模型成熟度与 Beta 限制。
- Proof of Capabilities — 可复现性说明、历史争议、撤回指标与能力边界。
- Calibration & Room Training Guide — 600 帧门槛、8 个 anchor、房间训练和已知缺口。
- v2 Rust crates — 硬件、信号、vitals、engine、server、模型与自动化代码。
- ESP32 CSI firmware — 采集、序列化、边缘处理、配网与 release binaries。
- Python bindings — PyO3 API、客户端、类型与使用示例。
统计口径来自该快照的递归 Git tree：4,158 个条目、3,407 个文件、907 个 Rust 文件、275 个 Python 文件、66 个 C 文件、334 个测试相关文件。数量只反映仓库结构，不等同于功能完整度或测试通过数。
返回顶部 ↑