RuView开源项目Docker+ESP32完整部署手册

RuView (WiFi DensePose) 是一个基于 ESP32-S3 的 WiFi CSI 感知开源项目，主打无摄像头、非接触式的人体姿态估计、生命体征监测与穿墙检测。

GitHub 仓库：https://github.com/ruvnet/RuView
WiFi-CSI感知开源项目RuView (WiFi DensePose)

一、总体部署说明

1、网络拓扑结构

2、设备与参数规划

|------------|-----------------|--------------|--------------------------------------|
| 设备 | IP 地址 | 角色 | 关键配置 |
| WiFi 路由器 | 192.168.199.1 | AP、网关 | 2.4GHz、信道 6、固定 SSID、密码 |
| Linux 主机 | 192.168.199.190 | 数据聚合 + AI 推理 | Docker、UDP 5005、HTTP 3000 |
| ESP32 节点 1 | 动态分配 | CSI 采集节点 | Node ID=1，信道 6，目标 IP：192.168.199.190 |
| ESP32 节点 2 | 动态分配 | CSI 采集节点 | Node ID=2，其余同上 |
| ESP32 节点 3 | 动态分配 | CSI 采集节点 | Node ID=3，其余同上 |

3、路由器配置步骤

仅开启 2.4GHz WiFI，关闭 5GHz（或分开 SSID）
信道设置为 固定 6，禁止自动切换
设置 WiFi 名称（SSID）和密码
确保 DHCP 开启，自动分配内网 IP
关闭 AP 隔离、允许设备互通

二、ESP32 节点部署

3 个 ESP32 节点部署步骤（统一模板）

1、编译环境与步骤

ESP-IDF
芯片：ESP32-S3

1. 安装 ESP-IDF v5.2

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

2. 克隆 RuView

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

3. 配置

idf.py set-target esp32s3
idf.py menuconfig

→ WiFi SSID / 密码 / 聚合服务器IP / 节点ID

4. 编译烧录

idf.py build flash monitor

2、menuconfig 统一配置

（3 个节点仅修改 Node ID）

进入 CSI Node Configuration：

复制代码

Node ID:                     1        # 第2个设2，第3个设3
Aggregator IP address:       192.168.199.190
Aggregator UDP port:         5005
WiFi SSID:                   你的WiFi名(2.4G)
WiFi Password:               WiFi密码
WiFi Channel:                6

|---------------------|---------------------|----------------------|
| 参数 | 示例配置 | 说明 |
| Node ID | 1 | 第一个节点，多节点依次递增 |
| Aggregator IP | 192.168.1.100 | 你运行docker服务主机的局域网 IP |
| Aggregator UDP port | 5005 | 保持默认 |
| WiFi SSID | MyHomeWiFi | 你的 2.4GHz WiFi 名称 |
| WiFi Password | MyWiFiPassword123 | WiFi 密码 |
| WiFi Channel | 6 | 和路由器固定信道一致 |

按 S 键保存配置
按 Q 键退出 menuconfig
配置会自动保存到 sdkconfig 文件，后续编译会自动读取

3、编译 & 烧录

复制代码

idf.py build flash monitor

4、验证 ESP32 正常输出

复制代码

I: Connected to WiFi
I: Got IP: 192.168.199.xxx
I: stream_sender: UDP sender initialized: 192.168.199.190:5005
I: csi_collector: CSI cb #xxx: len=128 rssi=-33 ch=6

出现 CSI cb 代表正在采集并发送数据。

三、Docker 服务端部署

docker镜像部署：多架构镜像（amd64 + arm64）。包含 Rust 感知服务器、Three.js 用户界面以及所有信号处理功能。

数据源选择： 使用CSI_SOURCE环境变量来选择传感模式：

|-------------|---------------------------------------|
| 值 | 描述 |
| auto | （默认）通过 UDP 5005 端口探测 ESP32，失败则切换为模拟模式 |
| esp32 | 通过UDP接收来自ESP32设备的真实CSI帧 |
| simulated | 生成合成CSI帧（无需硬件） |
| wifi | 主机 Wi-Fi 信号强度（容器内不可用） |

示例：docker run -e CSI_SOURCE=esp32 -p 3000:3000 -p 5005:5005/udp ruvnet/wifi-densepose:latest

1、数据源说明

--source 标志控制 CSI 数据的来源。

ESP32-S3（完整信道状态信息）

20赫兹下的真实信道状态信息，支持56-192个子载波。适用于姿态估计、生命体征检测及穿墙感知场景。

复制代码

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

# Docker (use CSI_SOURCE environment variable)
docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest

ESP32 节点通过 UDP 向 5005 端口传输二进制 CSI 帧。有关烧录说明，请参见硬件设置。

ESP32 多静态网格（高级版）

为了实现更高精度的穿墙定位，请以多静态网状网络配置部署 3-6 个 ESP32-S3 节点。每个节点同时充当发射器和接收器，在环境中构建多条感知路径。

复制代码

# Start the aggregator with multistatic mode
./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001

该网格采用**时分复用（TDM）**协议，节点轮流传输，避免了自干扰。主要特性：

|----------|-----------------------------------|
| 功能 | 描述 |
| 时分复用协调 | 节点在发送/接收时隙间循环（可配置保护间隔） |
| 跳频 | 自动在2.4GHz/5GHz频段间切换以实现多频段融合 |
| QUIC 传输层 | 聚合器节点上的 TLS 1.3 加密流（ADR-032a） |
| 手动加密回退 | 受限 ESP32-S3 节点上的 HMAC-SHA256 信标认证 |
| 注意力加权融合 | 带几何多样性偏置的跨视角注意力 |

2、Linux 主机部署步骤

（1）拉取docker镜像

复制代码

sudo docker pull ruvnet/wifi-densepose:latest

（2）启动服务端（标准端口）

复制代码

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

（3）防火墙放行端口

复制代码

sudo ufw allow 3000/tcp
sudo ufw allow 3001/tcp
sudo ufw allow 5005/udp
sudo ufw reload

（4）查看运行状态 & 日志

复制代码

docker ps
docker logs -f ruview

出现以下内容即为成功：

复制代码

UDP listening on 0.0.0.0:5005 for ESP32 CSI
WebSocket server listening on 0.0.0.0:3001
HTTP server listening on 0.0.0.0:3000

（5）访问网页

复制代码

http://192.168.199.190:3000/ui/index.html

四、功能说明（Docker 版本）

无需模型、无需训练，直接可用：

人体存在检测：PRESENT / ABSENT
静止 / 运动判断：PRESENT_STILL / PRESENT_MOTION
呼吸信号监测：Breathing Band 波形随呼吸起伏
环境感知：Variance、Motion Band、Spectral Power

姿态估计（骨架）需要 额外模型文件，公开 Docker 镜像默认不带。

参数说明：

SIGNAL FEATURES

Variance → 信号波动强度

Motion Band → 运动强度

Breathing Band → 呼吸强度（你要的功能）

Spectral Power → 信号总能量

CLASSIFICATION

PRESENT_STILL → 有人静止

PRESENT_MOTION → 有人运动

ABSENT → 没人

1、人体存在检测（Presence Detection）

位置： CLASSIFICATION 里

显示结果：

PRESENT_STILL → 有人静止

PRESENT_MOTION → 有人运动

ABSENT → 没人

原理：

WiFi 信号被人体遮挡 / 反射 → 系统自动判断有没有人

2、静止 / 运动判断（Motion / Still）

同样在 CLASSIFICATION 里

PRESENT_STILL = 静止（坐着 / 站着不动）

PRESENT_MOTION = 运动（挥手、走路、转身）

系统自动判断，不需要训练、不需要模型。

3、呼吸信号监测（Breathing Monitoring）

位置：SIGNAL FEATURES → Breathing Band

数值会随着你的呼吸一起起伏！

怎么看：

数值规律波动 = 正在检测呼吸

数值稳定不动 = 没呼吸 / 环境太吵

RuView 会从 WiFi 信号里提取胸腔起伏引起的微小波动。

RuView开源项目Docker+ESP32完整部署手册

一、总体部署说明

1、网络拓扑结构

2、设备与参数规划

3、路由器配置步骤

二、ESP32 节点部署

1、编译环境与步骤

1. 安装 ESP-IDF v5.2

2. 克隆 RuView

3. 配置

→ WiFi SSID / 密码 / 聚合服务器IP / 节点ID

4. 编译烧录

2、menuconfig 统一配置

3、编译 & 烧录

4、验证 ESP32 正常输出

三、Docker 服务端部署

1、数据源说明

2、Linux 主机部署步骤

（1）拉取docker镜像

（2）启动服务端（标准端口）

（3）防火墙放行端口

（4）查看运行状态 & 日志

（5）访问网页

四、功能说明（Docker 版本）

1、人体存在检测（Presence Detection）

2、静止 / 运动判断（Motion / Still）

3、呼吸信号监测（Breathing Monitoring）