RuView 项目分析报告

分析日期：2026-07-09

---

一、项目介绍

1.1 项目概述

RuView（又称 WiFi DensePose）是一个开源的 WiFi 空间感知平台，其核心使命是将普通商用 WiFi 路由器转化为实时空间智能系统。它利用 WiFi 信道状态信息（CSI）实现无摄像头、无穿戴设备的室内感知能力，包括人员存在检测、呼吸/心率监测、人体姿态估计（17 关键点）、穿墙检测、活动识别、环境映射和睡眠质量分析等 [1]。

RuView 的设计理念是"把 WiFi 信号变成雷达"——当人体移动、呼吸甚至静坐时，都会改变无线电波的传播路径，项目通过 ESP32 采集 CSI 数据，再经信号处理和 AI 模型还原空间感知信息 [1]。

1.2 项目信息

项目	详情
项目名称	RuView（WiFi DensePose）
项目地址	https://github.com/ruvnet/RuView
项目官网	https://Cognitum.One/RuView
在线 Demo	https://ruvnet.github.io/RuView/（Live Observatory、Pose Fusion、3D Point Cloud、three.js Demo）
作者	ruvnet（由 ruvnet 和 claude 共同维护）
Stars	78,500+（截至 2026 年 7 月）
当前版本	v0.8.3-esp32（2026 年 6 月 27 日发布）
开源协议	MIT License
主要语言	Rust、TypeScript、Python、JavaScript/Node.js
仓库创建	2025 年 6 月 7 日

1.3 项目示意图

• README 展示了两张核心图片：RuView 的"WiFi DensePose"主图与 Cognitum Seed 产品图
• 实时姿态骨架图：标注为"Real-time pose skeleton from WiFi CSI signals — no cameras, no wearables"
• 官方 Live Observatory Demo、Pose Fusion Demo、3D Point Cloud Demo 和 three.js Demo 均托管在 GitHub Pages 上 [1]

---

二、项目亮点

2.1 无摄像头 WiFi 感知——核心创新

RuView 的核心思路是复用普通 WiFi 信号实现空间感知。当人体移动、呼吸甚至静坐时，都会改变无线电波传播路径，项目通过 ESP32 采集 CSI 数据，再经信号处理和 AI 模型还原空间感知信息。完全无需摄像头和穿戴设备，在隐私敏感场景（养老院、医院、家庭）具有独特优势 [1]。

2.2 ESP32 + 多频段 Mesh 架构

方案	硬件	成本	能力
推荐方案	ESP32-S3 + Cognitum Seed	~$140	完整 CSI、17 关键点姿态、呼吸/心率、跌倒检测、多人计数、105-cog 目录、持久化向量存储、kNN 搜索、见证链、MCP 代理
ESP32 Mesh	3-6× ESP32-S3 + WiFi 路由器	~$54	与推荐方案相近，缺少 persistent-memory 功能
研究节点	ESP32-C6-DevKit	~$10	Wi-Fi 6 / 802.15.4 研究支持
研究 NIC	Intel 5300 / Atheros AR9580	$50-100	3x3 MIMO 完整 CSI
普通 WiFi	笔记本	$0	RSSI-only：粗粒度存在和运动检测

多节点 mesh 使用 6 个 WiFi 频段，通过 TDM 时隙调度实现 3 倍感知带宽 [1]。

2.3 边缘 AI 与 Cog 模块体系

RuView 围绕 Cognitum / Cog 生态，包含 105 个边缘模块，覆盖 11 个类别 [1][5]：

类别	说明
健康	呼吸、心率、跌倒检测、睡眠分析
安全	入侵检测、异常行为告警
建筑	空间占用、能源管理
零售	客流统计、停留区域分析
工业	危险区域占用、人员接近告警
研究	信号处理、模型训练
AI	姿态估计、活动识别
Swarm	多节点协同
信号	CSI 采集与处理
网络	Mesh 通信
开发者	API、SDK

2.4 Hugging Face 预训练模型

模型	用途	性能
ruvnet/wifi-densepose-pretrained	对比学习编码器	12.2M 训练步骤、60K 帧、610K contrastive triplets，v2 encoder 在 held-out temporal-triplet 上达 82.3%
ruvnet/wifi-densepose-mmfi-pose	17 关键点姿态估计	torso-PCK@20 为 82.69%，ensemble 为 83.59%

2.5 智能家居生态深度集成

RuView 可接入 Home Assistant、Apple Home/HomePod、Google Home、Amazon Alexa、SmartThings。通过 Home Assistant 接入时，每个节点提供 21 个 entities：11 个原始信号 + 10 个推理语义状态，包括 someone-sleeping、possible-distress、room-active、elderly-inactivity-anomaly、fall-risk-elevated 等，并附带 3 个 starter HA Blueprints [1]。

2.6 边缘推理极低延迟

能力	延迟/性能
Presence detection	< 1 ms
Fall detection	< 200 ms
17-keypoint pose estimation (cold-start)	~8.4 ms（Pi 5）
128-dim contrastive encoder embeddings	164,183 emb/s（M4 Pro）
4-bit quantized 模型大小	8 KB（可装入 Raspberry Pi）

2.7 密码学证明与可信执行

基于 RuVector 和 Cognitum Seed，支持 Ed25519 witness chain 对测量结果进行密码学证明。Cog binary 的 binary_sha256 与 binary_signature 是安装信任链的一部分 [1][5]。

2.8 与同类项目的差异化优势

维度	RuView	ESPectre
核心目标	人体姿态 + 生命体征 + 存在检测	人体运动/静止检测
AI 依赖	RuVector + 神经网络，输出 17 关键点、呼吸、心率	传统信号处理，输出有人/无人、运动/静止
硬件规模	多节点 mesh，推荐 3-6× ESP32-S3	单节点即可
输出粒度	姿态、呼吸、心率、房间指纹、漂移告警	存在、活动、运动分数
隐私性	本地处理、无图像、密码学认证	本地处理、无图像
工程化	Docker、Rust 高性能、Web UI、智能家居集成	ESPHome 原生集成、HA 即插即用

---

三、项目运行环境

3.1 硬件要求

级别	硬件	成本	能力范围
入门	普通 WiFi 笔记本	$0	RSSI-only：粗粒度存在和运动检测
研究	ESP32-C6-DevKit	~$10	Wi-Fi 6 / 802.15.4 研究
Mesh 部署	3-6× ESP32-S3 + WiFi 路由器	~$54	完整 CSI 感知
推荐方案	ESP32-S3 + Cognitum Seed	~$140	完整能力 + 持久化 + 见证链
研究 NIC	Intel 5300 / Atheros AR9580	$50-100	3x3 MIMO 完整 CSI

3.2 操作系统支持

• Docker 镜像支持 amd64 + arm64，适合 x86_64 和 ARM 平台
• 前端 demo 通过浏览器访问，属 Web 可视化层
• ESP32 固件通过 ESP-IDF 构建，目标平台为 ESP32-S3 / ESP32-C6

3.3 软件依赖

依赖	版本/说明
Rust	1.85+（核心感知服务器、信号处理、WASM 边缘）
Python	pip install ruview 或 pip install wifi-densepose
Node.js	脚本（rf-scan、snn-csi-processor、mincut-person-counter）
Docker	docker pull ruvnet/wifi-densepose:latest
ESP-IDF	v5.4+（ESP32 固件编译）
Hugging Face	预训练模型下载

3.4 安装步骤

Docker 快速体验（模拟数据）：

docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest
# 打开 http://localhost:3000

ESP32-S3 实时感知：

python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
  write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \
  0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin

python firmware/esp32-csi-node/provision.py --port COM9 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

ESP32-C6 研究节点：

cd firmware/esp32-csi-node
idf.py set-target esp32c6 && idf.py build
idf.py -p COM6 flash

Python 包安装：

pip install ruview           # 或 pip install wifi-densepose
pip install "ruview[client]"  # 客户端功能

下载预训练模型：

pip install huggingface_hub
huggingface-cli download ruvnet/wifi-densepose-pretrained \
  --local-dir models/wifi-densepose-pretrained

---

四、项目代码介绍

4.1 代码架构图

ruvnet/RuView/
├── v2/                               # v2 核心代码，Rust 编译单元
├── python/                           # Python 相关代码
├── ui/                               # Web 前端与 demo 页面
├── dashboard/                        # 仪表盘前端
├── firmware/                         # ESP32 固件（ESP-IDF）
│   └── esp32-csi-node/               # CSI 采集节点固件
├── docs/                             # 文档与 ADR
│   └── adr/                          # 架构决策记录
├── plugins/ruview/                   # RuView 插件
├── harness/ruview/                   # 测试/验证
├── examples/                         # 示例
├── benchmarks/                       # 基准测试
├── aether-arena/                     # 评测/验证
├── wifi_densepose/                   # Python 包目录
├── archive/                          # 旧版归档
├── docker/                           # Docker 配置
├── scripts/                          # Node.js 脚本
│   ├── rf-scan.js                    # 射频扫描
│   ├── snn-csi-processor.js          # SNN CSI 处理器
│   └── mincut-person-counter.js      # 最小割人员计数
├── tests/                            # 测试代码
├── tools/                            # 工具脚本
├── references/                       # 参考资料
├── monitoring/                       # 监控相关
├── logging/                          # 日志相关
├── plans/                            # 规划文档
├── data/                             # 数据文件
├── assets/                           # 资源文件
├── releases/desktop/                 # 桌面发布制品
├── vendor/                           # 第三方依赖
├── LICENSE                           # MIT
├── README.md
├── CHANGELOG.md
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── install.sh
├── deploy.sh
├── Makefile
└── PROOF.md

4.2 核心模块介绍

模块	语言	职责	测试规模
wifi-densepose-sensing-server	Rust	感知服务器核心，提供 API、WebSocket 与可视化能力，EdgeRegistry 解析 Cog 目录	677 passed
wifi-densepose-signal	Rust	CSI 信号处理（幅度、相位、运动带能量），硬件标准化，多静态融合前处理	501 passed
wifi-densepose-wasm-edge	Rust/WASM	约 70 个模块的 WASM 边缘 crate，将感知能力放到 WASM 边缘运行环境	672 passed
wifi-densepose-occworld-candle	Rust	世界模型预测（OccWorld TransVQVAE），15 帧未来占用预测，3.4 GB VRAM	29/29 pass
ESP32 固件	C/ESP-IDF	ESP32-S3/C6 CSI 采集节点固件，支持多频段 mesh	—
Python 包	Python	ruview / wifi-densepose PyPI 包，提供客户端 API	—
Web 前端	TypeScript/React	Live Observatory、Pose Fusion、3D Point Cloud、three.js Demo	—

4.3 核心代码解析

4.3.1 EdgeRegistry 边缘模块注册中心（Rust）

// v2/ 中的 EdgeRegistry 实现
pub struct EdgeRegistry {
    cached: RwLock<Option<CachedEntry>>,
    ttl: Duration,
    upstream_url: String,
}

struct CachedEntry {
    payload: serde_json::Value,
    fetched_at: Instant,
    upstream_sha256: String,
}

impl EdgeRegistry {
    /// 按需获取 app-registry.json，在进程内缓存
    /// 通过 /api/v1/edge/registry 暴露
    /// 缓存 TTL 默认 3600 秒，支持 ?refresh=1 强制刷新
    /// 上游失败时：若有缓存返回 stale: true 的旧数据，若无缓存返回 503
    pub async fn get_registry(&self, force_refresh: bool) -> Result<RegistryResponse> {
        if !force_refresh {
            if let Some(entry) = self.cached.read().unwrap().as_ref() {
                if entry.fetched_at.elapsed() < self.ttl {
                    return Ok(RegistryResponse {
                        payload: entry.payload.clone(),
                        stale: false,
                    });
                }
            }
        }
        // 从上游获取最新数据...
        match self.fetch_upstream().await {
            Ok((payload, sha256)) => {
                *self.cached.write().unwrap() = Some(CachedEntry {
                    payload: payload.clone(),
                    fetched_at: Instant::now(),
                    upstream_sha256: sha256,
                });
                Ok(RegistryResponse { payload, stale: false })
            }
            Err(e) => {
                // 回退到缓存
                if let Some(entry) = self.cached.read().unwrap().as_ref() {
                    Ok(RegistryResponse {
                        payload: entry.payload.clone(),
                        stale: true,
                    })
                } else {
                    Err(e)
                }
            }
        }
    }
}

关键设计：服务按需获取 app-registry.json，在进程内缓存并通过 REST API 暴露。缓存 TTL 默认 3600 秒，支持 ?refresh=1 强制刷新。上游失败时优雅降级到缓存数据，无缓存时返回 503。这是 105 个 Cog 边缘模块的发现和分发枢纽 [5]。

4.3.2 硬件标准化与多静态融合（Rust）

// wifi-densepose-signal 中的硬件标准化
// 修复前：混合 ESP32 mesh 中，multistatic_bridge.rs 直接把
// 未标准化的每节点原始 CSI 喂给 MultistaticFuser，导致 DimensionMismatch

// 修复后：新增 HardwareNormalizer::resample_to_canonical
impl HardwareNormalizer {
    /// 将不同长度的 CSI 帧重新采样到统一的 56-tone 网格
    pub fn resample_to_canonical(
        &self,
        raw_csi: &[Complex32],
        node_id: NodeId,
    ) -> Result<Vec<Complex32>> {
        // 1. 查询节点硬件特征（天线数、子载波数）
        let profile = self.node_profiles.get(&node_id)?;
        // 2. 插值到标准 56-tone 网格
        let canonical = interpolate_to_grid(raw_csi, profile.n_subcarriers, 56)?;
        // 3. 应用硬件校准（幅度/相位偏移校正）
        let calibrated = self.apply_calibration(&canonical, profile)?;
        Ok(calibrated)
    }
}

关键设计：在 ESP32 mesh 多节点部署中，不同节点的 CSI 帧长度可能不同（取决于天线配置和 WiFi 协议）。HardwareNormalizer 通过插值到统一网格 + 硬件校准，确保不同节点的 CSI 数据可以无缝融合到多静态感知管道中 [4]。

4.3.3 WASM 边缘浮点数安全校验（Rust/WASM）

// wifi-densepose-wasm-edge 中的安全修复
// 问题：主机传入的 IEEE-754 float 没有有限性检查，
// NaN 可能被累积到 EMA、Welford、phasor sums、anomaly baselines
// 等长生命周期状态中，导致检测器降级

/// 将非有限值映射为 0.0，防止 NaN 污染长生命周期状态
#[inline]
pub fn sanitize_host_f32(value: f32) -> f32 {
    if value.is_finite() {
        value
    } else {
        0.0
    }
}

// 在 EMA 更新中应用
pub fn update_ema(state: &mut EmaState, raw_value: f32) {
    let safe_value = sanitize_host_f32(raw_value);
    state.current = state.alpha * safe_value + (1.0 - state.alpha) * state.current;
}

// 在 Welford 统计算子中应用
pub fn update_welford(state: &mut WelfordState, raw_value: f32) {
    let safe_value = sanitize_host_f32(raw_value);
    state.count += 1;
    let delta = safe_value - state.mean;
    state.mean += delta / state.count as f32;
    state.m2 += delta * (safe_value - state.mean);
}

关键设计：在 WASM 边缘环境中，主机传入的浮点数不受信任。sanitize_host_f32() 将非有限值（NaN、Inf）映射为 0.0，防止这些值污染 EMA、Welford 统计算子、phasor sums、anomaly baselines 等长生命周期状态，避免检测器持续降级 [4]。

4.3.4 智能家居状态实体映射

# RuView 通过 Home Assistant 集成暴露 21 个 entities
# 每个节点提供 11 个原始信号 + 10 个推理语义状态

HA_ENTITIES = {
    # 原始信号（11 个）
    "rssi": "signal_strength",
    "csi_amplitude": "csi_amplitude",
    "csi_phase": "csi_phase",
    "motion_band_energy": "motion_energy",
    "breathing_band_energy": "breathing_energy",
    "heart_rate_band_energy": "heart_rate_energy",
    "subcarrier_variance": "subcarrier_variance",
    "doppler_spread": "doppler_spread",
    "delay_spread": "delay_spread",
    "spatial_streams": "spatial_streams",
    "mesh_link_quality": "mesh_quality",

    # 推理语义状态（10 个）
    "presence": "someone_present",
    "count": "person_count",
    "activity": "current_activity",
    "sleeping": "someone_sleeping",
    "distress": "possible_distress",
    "room_active": "room_active",
    "elderly_inactivity": "elderly_inactivity_anomaly",
    "fall_risk": "fall_risk_elevated",
    "breathing_rate": "breathing_rate_bpm",
    "heart_rate": "heart_rate_bpm",
}

关键设计：语义状态实体（如 someone-sleeping、possible-distress、fall-risk-elevated）可直接用作 Home Assistant 自动化的触发条件，无需用户手动编写复杂的阈值逻辑。附带 3 个 starter HA Blueprints 进一步降低使用门槛 [1]。

---

五、项目应用与评价

5.1 应用场景

领域	场景
医疗与健康	养老院跌倒检测、夜间活动监测、睡眠呼吸监测、医院非关键床位患者监测、睡眠阶段分类和 apnea screening
零售与商业	客流统计与动线分析、停留区域分析、队伍长度检测、餐桌占用率追踪、洗手间占用率
智能家居与建筑	房间级存在检测触发灯光/空调/音乐、酒店入住状态、空房间节能管理、办公空间利用率
公共安全与灾害	灾害救援穿墙检测被困人员、公共厕所占用、地铁站台拥挤、避难所人数统计
仓储与工业	工人安全区域、叉车接近告警、危险区域占用状态、受限空间监测
隐私敏感场景	教育、托育、宗教场所等不适合摄像头但需要空间感知的场景

5.2 项目优点

1. 无摄像头、无穿戴设备：核心优势是不依赖视频和穿戴硬件，适合隐私敏感场景，不要求用户安装手机 App。
2. 穿墙感知能力：通过 Fresnel-zone geometry + multipath modeling 实现穿墙感知，最远约 5 米，在灾害救援场景具有独特价值。
3. 极低成本：单 ESP32 节点最低约 $9，3-6 节点 mesh 约 $54，推荐完整方案约 $140，远低于摄像头 + AI 服务器方案。
4. 智能家居原生集成：支持 Home Assistant、Apple Home/HomePod、Google Home、Alexa、SmartThings，每个节点提供 21 个 entities（11 个原始信号 + 10 个语义状态）。
5. 边缘推理极低延迟：Presence detection < 1 ms，Fall detection < 200 ms，17-keypoint pose cold-start ~8.4 ms，4-bit quantized 模型仅 8 KB。
6. 模型开源与可复现：预训练权重发布在 Hugging Face（12.2M 训练步骤），提供量化模型和训练说明。
7. 密码学证明：Ed25519 witness chain 对测量结果进行密码学证明，确保感知数据的可信性和不可篡改性。
8. MIT 协议：商业友好，无 copyleft 限制。

5.3 项目不足

1. CSI 硬件依赖：Presence、vital signs、through-wall sensing 等高级能力需要 ESP32-S3 或研究 NIC 提供完整 CSI；普通 WiFi 笔记本仅提供 RSSI-only，只能做粗粒度存在和运动检测。
2. 部署复杂度较高：相比 ESPectre 等单节点简单传感器，RuView 通常涉及多节点 mesh、WiFi 信道同步、边缘服务和可视化平台，部署和调试门槛较高。
3. 边缘推理对节点要求更高：ESP32 更适合轻量任务，17-keypoint pose、OccWorld 等复杂任务通常需要树莓派、Cognitum Seed 或本地 GPU 支持。
4. 环境敏感：穿墙感知、呼吸/心率检测、姿态估计会受墙体、家具、多径和路由器信号强度影响，不同环境需要重新校准。
5. 依赖完整 CSI 采集：如果硬件只支持 RSSI，高级感知能力会下降，不能达到 README 中列出的完整能力。
6. 成熟度需结合场景验证：项目已有大量测试（677+501+672+29 = 1879 个测试通过）、CHANGELOG 修复、预训练模型和智能家居集成，但实际部署仍需考虑房间布局、噪声、设备数量和长期稳定性。
7. 文档分散：文档分布在 README、CHANGELOG、ADR 和多个子目录中，缺乏统一的结构化文档入口。
8. Cognitum Seed 依赖：推荐方案需要 Cognitum Seed 硬件，而该硬件可能尚未大规模量产，获取渠道有限。

---

参考来源

• RuView GitHub 仓库
• RuView 项目官网
• RuView CHANGELOG
• ADR-102 Edge Module Registry
• RuView 项目分析 - CSDN