RuView 传感应用实战指南：presence / vitals / pose / sleep / MAT 全场景运行手册

RuView 传感应用实战指南：presence / vitals / pose / sleep / MAT 全场景运行手册

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView

RuView（WiFi-DensePose）将商用 WiFi 的 Channel State Information（CSI）转化为实时空间智能、生命体征监测与存在检测，全程无需任何摄像头像素。本指南以仓库内的/ruview-app运行指引为核心骨架，系统讲解如何在 RuView 中运行各类传感应用：从 presence、vitals、pose、environment 等实时感知服务，到 sleep 睡眠分析、MAT 灾难幸存者搜救、pointcloud 多模态空间融合，以及 passive-radar 等新型 RF 实验脚本。读完本文，你将掌握每种应用的选型依据、启动命令、关键配置参数及其底层 crate 实现，能够在有真实 ESP32 硬件或无硬件两种条件下快速跑通整套传感流水线。

一、应用选择：先回答"你要感知什么"

RuView 的运行入口是一个应用目录（catalogue）式指引：$ARGUMENTS参数决定启动哪一种应用。可选项包括presence、vitals、pose、sleep、environment、mat、pointcloud，或任意一个 novel-RF 应用名；若参数为空，则先展示目录并询问用户。选型本质上取决于三个问题：目标对象是否静止、是否需要骨架级输出、以及是否处于灾难搜救场景。

二、presence / vitals / pose / environment：wifi-densepose-sensing-server

这四类应用共用同一个 Rust 后端——wifi-densepose-sensing-server crate，它同时提供库（wifi_densepose_sensing_server）与二进制（sensing-server）。启动方式有两种：对接真实 ESP32 硬件，或使用 Docker 演示镜像（ruvnet/wifi-densepose:latest，端口 3000）跑模拟 CSI。

2.1 服务架构与数据流

从 README 的架构图可以看到完整数据流：

ESP32 ──UDP:5005──> [ CSI Receiver ] | [ Signal Pipeline ] (vital_signs, graph_transformer, sona) | [ WebSocket Broadcast ] | Browser <──WS:8765── [ Axum Server :8080 ] ──> Static UI files

• UDP CSI 接收：ESP32 通过 UDP 5005 端口发送 CSI 帧，服务端解析为内部CsiFrame表示；
• 信号流水线：依次经过vital_signs（生命体征）、graph_transformer（姿态估计）、sona（在线自适应）等模块；
• WebSocket 广播：处理结果实时推送到浏览器客户端，地址为ws://localhost:8765/ws/sensing；
• 静态文件服务：同一进程在 8080 端口托管感知 UI。

2.2 完整 CLI 参数说明

启动命令为：

cd v2 && cargo run -p wifi-densepose-sensing-server

结合 cli.rs 的clap参数定义，核心参数如下：

例如自定义端口并指定模型：

cd v2 && cargo run -p wifi-densepose-sensing-server -- \ --http-port 9000 \ --udp-port 5005 \ --ui-path ./ui \ --model model.rvf

此外，cli.rs 中还定义了三组集成参数：MQTT 发布器（--mqtt、--mqtt-host、--mqtt-port、--mqtt-rate-vitals等，支持 Home Assistant 自动发现，前缀默认homeassistant）、隐私模式（--privacy-mode，在任何 MQTT/Matter 发布前剥离 HR/BR/pose 等生物特征，对应 ADR-106 原始数据隔离契约）、以及Matter 桥（--matter、--matter-vendor-id默认0xFFF1）。这些由 cli.rs 中的mqtt_defaults_disabled、privacy_mode_defaults_off、matter_defaults_off_dev_vid等测试用例逐一锁定默认行为。

2.3 environment 模式：场模型与指纹索引

environment应用需要额外两个参数：

cd v2 && cargo run -p wifi-densepose-sensing-server -- --model model.rvf --build-index env

--model指定 RVF 格式的模型容器（64 字节对齐段的单一二进制格式，打包权重、元数据与配置，见 sensing-server README 中rvf_container/rvf_pipeline模块）；--build-index env则基于对比学习嵌入（ADR-024 的 SimCLR 风格自监督预训练 + InfoNCE 损失 + 投影头 + 指纹索引）构建环境指纹索引。空房间基线能力由 ADR-355 定义：服务会恢复安装绑定的空房间场模型快照（bootstrap_only权限），用于降低启动时的背景误报，但不能授权校准证据或数值化心呼吸率。

2.4 vitals 的频段实现原理

vitals应用的呼吸与心率频段来自 wifi-densepose-vitals crate（对应 ADR-021），这是一个四阶段纯 Rust 流水线，#[forbid(unsafe_code)]，除tracing外零外部依赖：

1. 预处理（CsiVitalPreprocessor）：EMA 静态分量抑制，产生逐子载波残差；
2. 呼吸提取（BreathingExtractor）：0.1–0.5 Hz 带通滤波 + 过零分析，对应6–30 BPM；
3. 心率提取（HeartRateExtractor）：0.8–2.0 Hz 带通 + 自相关峰值检测 + 跨子载波相位相干加权，对应48–120 BPM；
4. 异常检测（VitalAnomalyDetector）：Welford 运行统计 + Z-score，实时触发呼吸暂停/心动过速/心动过缓警报。

breathing.rs 展示了核心实现：二阶谐振 IIR 带通滤波器状态机 + 滑窗零交叉分析，并包含一个"连续越界拒绝即重置"机制（STALE_RESET_REJECTIONS = 1，修复 issue #1422），确保受试者离开后不会持续回显过期估值。作为库使用时（示例见 vitals README）：

use wifi_densepose_vitals::{CsiVitalPreprocessor, BreathingExtractor, HeartRateExtractor, ...}; let mut preprocessor = CsiVitalPreprocessor::new(56, 0.05); let mut breathing = BreathingExtractor::new(56, 100.0, 30.0); let mut heartrate = HeartRateExtractor::new(56, 100.0, 15.0); // ... 逐帧处理 CSI，得到 VitalReading 并写入 VitalSignStore

2.5 pose：WiFi 驱动的 17 关键点骨架

pose应用输出 17 个 COCO 关键点，走 ADR-059 描述的实时 ESP32 CSI 流水线。底层由 sensing-server 中的 Graph Transformer 实现：天线空间 CSI 特征与 COCO 17 关键点人体图之间的交叉注意力瓶颈，再经 GCN 消息传递（ADR-023 Phase 2），纯std、无 ML 依赖。注意：姿态估计需要先训练模型以获得准确度，训练入口见/ruview-train（对应 wifi-densepose-train crate 及--train/--dataset/--epochs/--pretrain等 CLI 参数）。

三、sleep：睡眠分期与呼吸暂停筛查

sleep应用由两部分组成：

# 示例目录与筛查脚本 examples/sleep/ + node scripts/apnea-detector.js

仓库中的 apnea_screener.py 提供睡眠示例，配合 apnea-detector.js 实现睡眠分期分类与呼吸暂停筛查。睡眠监测依赖 vitals crate 的呼吸提取（0.1–0.5 Hz）与异常检测（Z-score 触发 apnea 警报）能力，可参见 ruview_live.py 中VitalAnomalyDetector的移植实现：当br == 0且基线均值 > 5 时触发 "Breathing stopped" 呼吸暂停事件。

四、mat：Mass Casualty Assessment 灾难搜救

mat（Mass Casualty Assessment，大规模伤亡评估）用于地震、建筑坍塌、雪崩等场景下瓦砾废墟中的幸存者探测，核心实现为 wifi-densepose-mat crate，完整操作手册见 docs/wifi-mat-user-guide.md。该模块是本文档涉及的功能面最广的应用：

• 生命体征检测：呼吸（0.1–0.5 Hz，4–60 次/分）、心跳（0.8–3.3 Hz 微多普勒，30–200 BPM）、运动分类（粗大/精细/震颤/周期）；
• 幸存者定位：3+ 传感器三角测量实现 2D 定位（±0.5 m）、深度估计（瓦砾下 ±0.3 m，最深 5 m）、Kalman 滤波位置融合；
• START 协议分诊：自动输出 Immediate（红）/ Delayed（黄）/ Minor（绿）/ Deceased（黑）分级并动态更新；
• 分级告警：Critical / High / Medium / Low 四级优先级，多通道分发（Audio / Visual / Push / Radio）。

核心入口类型为DisasterResponse+DisasterConfig（含disaster_type、sensitivity、confidence_threshold、max_depth、scan_interval_ms、continuous_monitoring、alert_config），完整 API 与 Rust 示例均收录于 wifi-mat-user-guide.md。该 crate 采用 DDD 事件溯源设计（detection / localization / alerting 三个限界上下文），并集成ruvector-solver完成三角测量数学、ruvector-temporal-tensor压缩 CSI 缓冲。域模型说明见 docs/ddd/wifi-mat-domain-model.md，设计动机见 ADR-001。

五、pointcloud：CSI + mmWave + 深度相机的统一空间模型

pointcloud应用追求"最佳空间精度"，运行：

python scripts/mmwave_fusion_bridge.py

它融合三路感知源：相机深度（MiDaS 单目深度估计）+ WiFi CSI + mmWave 雷达，输出统一空间模型，单帧约 22 ms、每帧 19K+ 点（性能数据来自原运行指引，具体实现可查看 mmwave_fusion_bridge.py 源码）。该方向与 ADR-094 的点云部署方案对应。

六、novel RF：实验性射频应用脚本

若需要探索新型射频感知应用，scripts/目录提供了一系列可直接运行的实验脚本：

这些脚本分别对应 ADR-077（新型射频感知应用）与 ADR-078（多频网格应用）的研究方向。

七、无硬件环境：Docker 演示与 Python 仿真

没有 ESP32 硬件时，有两条降级路径：

7.1 Docker 演示镜像

docker run -p 3000:3000 ruvnet/wifi-densepose:latest

该镜像对应 docker-compose.yml 中的sensing-server服务：REST API 映射127.0.0.1:3000:3000，WebSocket 映射127.0.0.1:3001:3001，ESP32 UDP 映射5005:5005/udp。数据源由CSI_SOURCE环境变量控制（默认auto）：auto会探测 ESP32 UDP 与主机 WiFi，两者皆无时以 exit 78 硬失败（不再静默回退到合成数据，须显式选择）；esp32接收真实 CSI 帧；wifi使用主机 WiFi RSSI/扫描数据；simulated显式生成合成 CSI 用于演示。模型目录通过MODELS_DIR（默认data/models）挂载。注意 Windows Docker Desktop 下多源 UDP 会在 WSL/Hyper-V 边界被合并为单一源 IP，需改为5006:5005/udp并运行python scripts/udp-relay.py --listen-port 5005 --forward-port 5006中继（详见 docs/TROUBLESHOOTING.md）。

7.2 Python 实时演示

python examples/ruview_live.py --csi COM7 --mmwave COM4

ruview_live.py 是"Ambient Intelligence Dashboard"，融合 ESP32-S3 WiFi CSI + 60 GHz mmWave（MR60BHA2），其中的信号处理算法直接移植自 RuView Rust crate（wifi-densepose-vitals的 BreathingExtractor / HeartRateExtractor / VitalAnomalyDetector、ruvsense 的纵向漂移检测与相干性评分）。它额外提供了 HRV 分析（SDNN / RMSSD / pNN50 / LF/HF）、血压估计、压力分级与幸福度评分，并可通过--seed参数将幸福度向量推送到 Cognitum Seed（每 5 秒一次，见 ADR-066 相关桥接）。--mode happiness切换为幸福度仪表盘模式。同类的轻量环境监测示例见 room_monitor.py（占用变化、光照异常、活动模式与房间 RF 指纹漂移检测）。

八、可视化工具

无论硬件还是仿真模式，两个可视化脚本可辅助观察信号：

node scripts/csi-spectrogram.js # CSI 频谱图 node scripts/csi-graph-visualizer.js # CSI 信号图可视化

sensing-server 自身也托管了完整感知 UI（HTTP 8080 端口静态服务 + WebSocket 实时流），浏览器直接访问即可看到实时感知画面。

九、应用选型决策指南

综合原指引最后一段的选型逻辑，决策树如下：

• 穿越墙体（≤5 m 深度）→presence/ 活动检测；
• 静止受试者→vitals/sleep；
• 需要骨架输出→pose（务必先训练模型）；
• 搜救与灾难场景→mat；
• 追求最佳空间精度→ 2 个以上 ESP32 节点 + 跨视角融合（见 wifi-densepose-ruvector crate 的 viewpoint 模块），可选配 Cognitum Seed 增强。

仓库还提供了丰富的场景示例目录可供对照学习：examples/environment、examples/medical、examples/sleep、examples/stress、examples/happiness-vector。通过本文的选型表、CLI 参数表与底层 crate 分析，你可以根据手头硬件与业务目标，快速确定并启动对应的 RuView 传感应用。

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView