## 项目概述

RuView（π RuView）是一个将普通 WiFi 信号转化为空间智能的感知平台。它利用信道状态信息（CSI）技术，通过低成本的 ESP32 传感器捕捉人体对 WiFi 信号的扰动，实现穿墙人体检测、呼吸与心率监测、活动识别、姿态估计等功能，全程无需摄像头或穿戴设备。项目基于 Rust 开发，支持本地边缘部署，并可与 Home Assistant、Apple Home、Google Home 等智能家居生态集成。

## 核心功能

- **存在与占用检测**：穿墙检测人员，统计人数，追踪进出。
- **生命体征监测**：无接触测量呼吸频率和心率。
- **活动识别**：识别行走、坐下、手势、跌倒等动作。
- **环境映射**：通过 RF 指纹识别房间，检测家具移动或新物体。
- **睡眠质量分析**：整夜监测，睡眠阶段分类和呼吸暂停筛查。
- **无摄像头姿态估计**：从 WiFi CSI 估计 17 个身体关键点。
- **本地自动化**：提供 HOMECORE 状态、历史、自动化、签名 Wasm 插件、语音钩子和 HomeKit 支持。
- **统一 RF 世界模型**：融合 WiFi CSI、雷达、UWB 和蜂窝感知。
- **可治理证据**：为感知事件附加隐私政策、不确定性、来源和见证记录。
- **RuView MetaHarness**：AI 操作员辅助上线、校准、训练、验证和检查感知声明。

## 适用与不适用场景

**适用场景：**

- 智能家居自动化（存在触发、HVAC 优化）
- 老年人护理与辅助生活（跌倒检测、夜间活动监测）
- 医院病房监测（非关键床位连续呼吸/心率监测）
- 零售客流统计与占用分析
- 办公室空间利用率优化
- 酒店与餐饮业（房间占用、餐桌周转）
- 仓库与物流（安全区域、叉车接近警报）
- 灾难搜救（穿墙生命探测）
- 机器人空间感知（无视线遮挡的人体检测）

**不适用场景：**

- 需要高精度姿态估计的场合（当前单 ESP32 模型精度有限）
- 需要医疗级生命体征监测的场景（项目声明为研究原型，非医疗设备）
- 需要识别特定个人身份的场景（实验性，数据受限）
- 需要实时视频或图像的应用（项目明确不使用摄像头）

## 技术架构与依赖

- **语言**：Rust（主要）、C（ESP32 固件）、Python（部分工具）、TypeScript（前端）
- **硬件**：ESP32-S3、ESP32-C6、Intel 5300、Atheros AR9580 等支持 CSI 的设备
- **核心库**：RuVector、Cognitum Seed、Candle（机器学习推理）
- **框架**：Axum（HTTP 服务器）、Tokio（异步运行时）、Tauri（桌面应用）
- **模型**：基于 Hugging Face 的预训练模型（CSI 编码器、姿态估计模型）
- **协议**：MQTT、Matter、HAP（HomeKit）、WebSocket、UDP
- **其他**：Docker、ESP-IDF、PyO3、WASM

## 安装与快速开始

### 使用 Docker（模拟数据，无需硬件）

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

### 使用 Python 包

```bash
pip install ruview
# 或 pip install wifi-densepose
```

### 使用 ESP32 硬件（实时感知）

1. 烧录固件：
   ```bash
   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
   ```
2. 配置 WiFi：
   ```bash
   python firmware/esp32-csi-node/provision.py --port COM9 --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20
   ```

## 典型使用方法

### 运行感知服务器

```bash
cargo run -p wifi-densepose-sensing-server -- --source esp32 --udp-port 5005 --http-port 3000
```

### 使用预训练模型

```bash
huggingface-cli download ruvnet/wifi-densepose-pretrained --local-dir models/wifi-densepose-pretrained
```

### 使用 RuView MetaHarness

```bash
npx @ruvnet/ruview@0.4.0 doctor
npx @ruvnet/ruview@0.4.0 guidance --topic sensing --query "model loading"
```

### 与 Home Assistant 集成

使用 `--mqtt` 标志启动服务器，即可自动发现并集成到 Home Assistant。

## 配置与部署要点

- **硬件要求**：需要支持 CSI 的硬件（如 ESP32-S3）才能使用高级功能；普通 WiFi 仅支持 RSSI 级别的存在检测。
- **部署模式**：支持 Docker、本地编译、ESP32 固件烧录、Python 包等多种方式。
- **网络配置**：ESP32 节点通过 UDP 向服务器发送数据，需确保网络连通。
- **模型加载**：可通过 `--model` 参数指定模型文件（支持 RVF、safetensors、JSONL 格式）。
- **隐私与安全**：支持隐私模式、数据加密、见证链等安全特性。
- **性能调优**：可通过 API 调整去重因子等参数。

## 限制、风险与许可证

- **Beta 软件**：项目处于积极开发阶段，API 和固件可能变化。
- **硬件限制**：ESP32-C3 和原始 ESP32 不支持；单节点空间分辨率有限。
- **模型精度**：无摄像头姿态估计精度有限（PCK@20 约 3%），目标为 35%+。
- **医疗免责**：生命体征和姿态输出需独立验证，非医疗设备。
- **许可证**：MIT License。

## 官方链接

- [GitHub 仓库](https://github.com/ruvnet/RuView)
- [Hugging Face 模型](https://huggingface.co/ruvnet/wifi-densepose-pretrained)
- [PyPI 包](https://pypi.org/project/ruview/)
- [Docker Hub](https://hub.docker.com/r/ruvnet/wifi-densepose)
- [在线演示](https://ruvnet.github.io/RuView/)

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、文档、ADR 文件。
- 分析时间：2026-09-02。