RuView WiFi 感知系统详细部署教程

RuView 是一个革命性的开源项目，能将普通的 WiFi 信号转化为实时的空间感知和生命体征监测系统。它通过分析信道状态信息（CSI），实现穿墙人体检测、姿态估计、呼吸和心率监测，且完全不需要摄像头，保护隐私。

本教程将指导您完成 RuView 的部署，您可以根据手头的硬件情况和目标，从以下三种路径中选择一种。

📋 目录

  1. RuView 是什么
  2. 工作原理
  3. 部署路径概览与硬件准备
  4. 路径一：Docker 快速体验（无需硬件）
  5. 路径二：ESP32 硬件部署（真实感知）
  6. 路径三：从源码编译（完整功能）
  7. 系统验证与使用
  8. 更新与卸载
  9. 常见问题排查

RuView 是什么

RuView 是一套基于 WiFi 信号（具体是信道状态信息 CSI）的感知系统。它利用 ESP32 等低成本硬件捕获 WiFi 信号在空间中因人体存在和活动而产生的细微变化，并通过本地运行的轻量化 AI 模型进行分析。

它的核心能力包括：

  • 存在与 occupancy 检测：穿墙探测室内是否有人，并区分静止和运动状态。
  • 生命体征监测：无接触地监测呼吸频率和心率。
  • 姿态估计：通过 WiFi 信号还原人体骨架（17 个关键点），精度可达 82.69%。
  • 活动识别：识别行走、坐姿、跌倒等行为模式。
  • 完全本地化：所有数据处理均在本地边缘设备（如 ESP32）完成，无需连接云端，无隐私泄露风险。

工作原理

  1. 信号发射：WiFi 路由器（或 ESP32 节点）向空间发射 2.4GHz 的无线信号。
  2. 信号扰动：人体会反射、散射和吸收 WiFi 信号，其呼吸引起的胸腔起伏也会造成微小的信号变化。
  3. CSI 采集：部署在空间内的 ESP32-S3 节点捕获这些包含人体信息的信道状态数据。
  4. 数据聚合与推理：节点将 CSI 数据通过 UDP 发送到中央服务器（运行 RuView 服务端）。服务器上的 AI 模型（如部署的预训练 RVF 模型）对这些数据进行实时推理。
  5. 结果输出：推理结果（如姿态骨架、呼吸波形）通过 Web 界面实时可视化显示。

部署路径概览与硬件准备

RuView 提供三种部署路径，您可以根据目标和资源选择：

路径 目标 硬件需求 具备功能
路径一：Docker 快速体验和界面预览 无（使用模拟数据） 浏览 UI、了解 API、查看模拟的传感效果
路径二：ESP32 硬件 真实环境感知 1-3 个 ESP32-S3/C6 节点 + 支持 2.4GHz 固定信道的路由器 存在检测、运动/静止判断、呼吸监测（基础功能）
路径三：源码编译 完整功能（姿态估计等） 上述硬件 + Rust 和 Python 开发环境 所有硬件功能 + 姿态估计、模型训练、高级融合功能

硬件准备（路径二、三）：

  • 核心节点：ESP32-S3 开发板（推荐，约 $9） 或 ESP32-C6。ESP32-C3 和原版 ESP32 不支持。
  • 路由器：支持 2.4GHz，且能固定信道（如固定为信道 6）。
  • 计算主机：运行 RuView 服务端的电脑（Linux 推荐），有 Docker 或 Rust 环境。

路径一：Docker 快速体验（无需硬件）

这是最快体验 RuView 的方式，适合评估其功能和界面。

1. 拉取并运行 Docker 镜像
在终端中执行以下命令：

1
2
docker pull ruvnet/wifi-densepose:latest
docker run -p 3000:3000 ruvnet/wifi-densepose:latest

2. 访问 Web 界面
打开浏览器，访问 http://localhost:3000。您将看到模拟的 CSI 数据和可视化效果。

路径二：ESP32 硬件部署（真实感知）

如需在真实环境中感知存在和呼吸，请按以下步骤部署。

步骤 1：配置路由器

  1. 仅开启 2.4GHz WiFi，关闭 5GHz 或分开 SSID。
  2. 将 WiFi 信道固定（如信道 6），禁止自动切换。
  3. 确保 DHCP 开启，并记录主机的 IP 地址。

步骤 2：编译并烧录 ESP32 固件

  1. 安装 ESP-IDF（以 v5.2 为例）：

    1
    2
    git clone --recursive https://github.com/espressif/esp-idf.git
    cd esp-idf && ./install.sh esp32s3 && . ./export.sh

  2. 克隆 RuView 源码并进入固件目录：

    1
    2
    git clone https://github.com/ruvnet/RuView.git
    cd RuView/firmware/esp32-csi-node

  3. 配置工程：

    1
    2
    idf.py set-target esp32s3
    idf.py menuconfig

    进入 CSI Node Configuration，配置以下参数（每个节点需修改 Node ID）：

    • Node ID：第一个节点设为 1，依次递增。
    • Aggregator IP address：运行 Docker 服务端的主机 IP。
    • Aggregator UDP port：5005（保持默认）。
    • WiFi SSID：您的 2.4G WiFi 名称。
    • WiFi Password：WiFi 密码。
    • WiFi Channel：与您设置的路由器信道一致（如 6）。

  4. 编译并烧录：

    1
    idf.py build flash monitor

    若终端持续输出 CSI cb #... 信息，则表明固件工作正常，正在采集数据。

步骤 3：启动 Docker 服务端

使用 CSI_SOURCE=esp32 环境变量启动 Docker，以接收 ESP32 发来的真实 CSI 数据：

1
2
3
4
5
6
7
8
sudo docker run -d \
  --name ruview \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 5005:5005/udp \
  -e CSI_SOURCE=esp32 \
  ruvnet/wifi-densepose:latest

步骤 4：验证

在浏览器中访问 http://<您的主机IP>:3000。在 CLASSIFICATION 区域，您应能看到 PRESENT_STILL（有人静止）或 PRESENT_MOTION（有人运动）的状态变化。

路径三：从源码编译（完整功能）

如需使用姿态估计等高级功能，必须从源码编译 Rust 服务端。

步骤 1：准备开发环境

  1. 安装 Rust：

    1
    2
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    source $HOME/.cargo/env

  2. 安装系统依赖（Ubuntu/Debian）：

    1
    2
    3
    sudo apt-get install build-essential gfortran libopenblas-dev pkg-config \
         libglib2.0-dev libgtk-3-dev libsoup-3.0-dev libwebkit2gtk-4.1-dev \
         libgirepository1.0-dev libcairo2-dev libssl-dev

步骤 2：下载源码与模型

  1. 克隆仓库：

    1
    2
    3
    git clone https://github.com/ruvnet/RuView.git
    cd RuView
    git submodule update --init --recursive

  2. 下载预训练模型：

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

    若需姿态模型，可下载 ruvnet/wifi-densepose-mmfi-pose。

步骤 3：编译并运行服务端

  1. 进入 Rust 工作空间：cd v2。

  2. 编译服务端：

    1
    cargo build --release --bin sensing-server

    注：若编译过程中遇到依赖缺失问题，通常源于 wifi-densepose-sensing-server crate 自身的 Cargo.toml 未正确声明所有依赖。请参考项目 Issue 或社区解决方案手动添加缺失的依赖项，例如运行 cargo add ruvector-mincut --package wifi-densepose-sensing-server 并清理重编译。

  3. 运行服务端：

    1
    ./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001

  4. 加载模型进行姿态估计：
    若需姿态估计，需在命令中加载模型文件：

    1
    ./target/release/sensing-server --model ../models/your-model.rvf --source esp32

系统验证与使用

  • 确定性信号验证：运行以下命令，可验证信号处理管线是否正确，输出应为 VERDICT: PASS：

    1
    python archive/v1/data/proof/verify.py

  • Claude Code / Codex 插件：项目提供了方便的 AI 助手插件，可通过 /ruview-start 等命令辅助部署、配置和运行。

更新与卸载

  • 更新：重新 git pull 并执行编译步骤，或拉取最新的 Docker 镜像。
  • 卸载：
    • Docker：docker stop ruview && docker rm ruview。
    • 源码编译：删除 RuView 目录即可。

常见问题排查

ESP32 无法连接 WiFi
检查路由器是否只开启了 2.4G，且 SSID/密码正确。信道必须固定。

Docker 收不到 CSI 数据
检查 CSI_SOURCE 是否设为 esp32。确认防火墙已放行 UDP 5005 端口。

编译 Rust 项目失败
Ubuntu/Debian 系统需确保所有开发依赖包（如 libopenblas-dev）已安装。若提示依赖缺失，参考上文步骤 3 中的方法手动添加并清理重编译。

通过以上步骤，您应能成功部署 RuView。从保护隐私的居家老人监护，到智能空间的人员管理，这项技术正将 WiFi 变为无处不在的传感器。