WiFi-3D-Fusion

本地Wi‑Fi实时感知，利用信道状态信息（CSI）：实时运动检测与可视化，并可选桥接至：

• Person-in-WiFi-3D（基于Wi‑Fi的多人3D姿态）[CVPR 2024]。
• NeRF²（神经射频辐射场）。
• 3D Wi‑Fi扫描仪（RSSI体积映射）。

本单体仓库面向生产环境：从本地Wi‑Fi稳定获取CSI数据（通过ESP32‑CSI经UDP传输，或使用Nexmon结合tcpdump和csiread），配备实时运动检测器及3D可视化工具。

探索更多：DeepWiki页面提供了扩展的README，包含额外的安装指南、高级配置以及社区贡献。点击此处

---

🎥 演示

观看WiFi‑3D‑Fusion的实际运行效果：

🧩 架构

注意：图中的拼写错误（如“Wayelet CSi tensas”）正在修复中，请查看docs/img/以获取更新。

高层次运行流程

flowchart LR
  subgraph Capture
    A1(ESP32 UDP JSON):::node -->|csi_batch| B[esp32_udp.py]
    A2(Nexmon + tcpdump):::node -->|pcap| C[nexmon_pcap.py]
    A3(Monitor Radiotap):::node -->|RSSI stream| D[monitor_radiotap.py]
  end

  B & C & D --> E[realtime_detector.py]
  E --> F[fusion rf/rssi]
  F --> G[Open3D live viewer]

  classDef node fill:#0b7285,stroke:#083344,color:#fff;

模型训练

处理循环

sequenceDiagram
  participant SRC as CSI/RSSI源
  participant DET as 运动检测器
  participant FUS as 融合模块
  participant VIZ as Open3D查看器

  loop 帧
    SRC->>DET: (时间戳, 向量)
    DET-->>DET: 滑动窗口 / 阈值判断
    DET->>FUS: 事件 + 缓冲区
    FUS-->>VIZ: 点云 + 叠加层
    VIZ-->>用户: 交互式3D场景
  end

---

🚀 快速入门指南

硬件要求

• 单设备：使用配备瑞昱RTL8812AU芯片组的双频USB WiFi适配器（非常适合Nexmon）或带有CSI固件的ESP32开发板。
• Linux系统（推荐Ubuntu 22.04及以上版本）。
• 可选：支持CUDA的GPU，以加速训练过程。

方法1：基于Web的实时可视化（推荐）

# 安装依赖
bash scripts/install_all.sh

# 启动基于Web的实时可视化
source venv/bin/activate
python run_js_visualizer.py

# 打开浏览器访问 http://localhost:5000

方法2：传统流程

# ESP32-CSI UDP（默认端口5566）：
./scripts/run_realtime.sh --source esp32

# 或者使用Nexmon（需要处于监控模式的网络接口）
sudo ./scripts/run_realtime.sh --source nexmon

🎯 模型训练与持续学习

训练您自己的检测模型

# 使用当前配置进行基础训练
./train_wifi3d.sh

# 快速训练并启用持续学习
./train_wifi3d.sh --quick --continuous

# 针对特定设备来源进行训练
./train_wifi3d.sh --source esp32 --device cuda --epochs 200

# 启用持续学习（模型会自动优化）
./train_wifi3d.sh --continuous --auto-improve

# 高级训练，自定义参数
./train_wifi3d.sh \
    --source nexmon \
    --device cuda \
    --epochs 500 \
    --batch-size 64 \
    --lr 0.0005 \
    --continuous \
    --auto-improve

持续学习功能

• 实时模型优化：系统会根据新的检测结果自动学习。
• 自适应训练：模型会根据检测置信度和用户反馈不断更新。
• 自我改进：系统在人员检测方面会随着时间推移变得更好。
• 后台学习：训练过程会在不中断可视化的情况下持续进行。

📊 系统架构与特性

核心组件

1. CSI数据采集

   • ESP32-CSI通过UDP传输（初学者推荐）
   • Broadcom芯片上的Nexmon固件（高级用户）
   • 实时提取CSI幅值和相位信息

2. 高级检测流水线

   • 卷积神经网络用于人员检测
   • 实时骨骼估计与跟踪
   • 多人识别与重识别（ReID）
   • 自适应运动阈值调整

3. 3D可视化系统

   • 基于Three.js的Web渲染器，配备专业UI
   • 实时3D骨骼可视化
   • 地面平面上的CSI噪声图案动画
   • 交互式相机控制与HUD叠加层

4. 机器学习特性

   • 运行时持续学习
   • 基于反馈的自动模型优化
   • 自适应检测阈值
   • 跨会话的人员重识别

实时流程图

flowchart TD
    A[CSI数据源] --> B[信号处理]
    B --> C[神经网络检测]
    C --> D[3D可视化]
    
    A1[ESP32/Nexmon] --> B1[幅值/相位]
    B1 --> C1[CNN分类器]
    C1 --> D1[Three.js Web UI]
    
    A2[UDP/PCap] --> B2[运动检测]
    B2 --> C2[人员跟踪]
    C2 --> D2[骨骼渲染]
    
    A3[配置文件YAML] --> B3[自适应阈值]
    B3 --> C3[ReID系统]
    C3 --> D3[活动日志记录]

🛠️ 安装与设置

先决条件

• Linux系统（推荐Ubuntu 18.04及以上版本）
• Python 3.8+
• 支持监控模式的WiFi适配器（用于Nexmon）
• 带有CSI固件的ESP32开发板（用于ESP32模式）
• 支持CUDA的GPU（可选，可提升训练速度）

完整安装步骤

# 克隆仓库
git clone https://github.com/MaliosDark/wifi-3d-fusion.git
cd wifi-3d-fusion

# 安装所有依赖并设置环境
bash scripts/install_all.sh

# 激活Python虚拟环境
source venv/bin/activate

# 验证安装
python -c "import torch, numpy, yaml; print('✅ 所有依赖已安装')"

硬件设置

注意：请参阅[WiFi适配器、驱动程序及监控模式设置（RTL8812AU示例）]以获取详细的RTL8812AU配置说明。

选项A：ESP32-CSI设置

1. 为ESP32刷写CSI固件

   # 下载ESP32-CSI-Tool固件
   # 使用esptool或Arduino IDE将其刷入ESP32
   

2. 配置ESP32

   • 设置WiFi网络和密码
   • 配置UDP目标IP地址（即您的PC IP）
   • 将UDP端口设置为5566（或修改configs/fusion.yaml中的配置）

3. 更新配置文件

   # configs/fusion.yaml
   source: esp32
   esp32_udp_port: 5566
   

选项B：Nexmon设置

1. 安装Nexmon固件

   # 适用于搭载bcm43455c0芯片的树莓派4
   git clone https://github.com/seemoo-lab/nexmon_csi.git
   cd nexmon_csi
   # 按照针对您设备的安装说明进行操作
   

2. 启用监控模式

   sudo ip link set wlan0 down
   sudo iw dev wlan0 set type monitor
   sudo ip link set wlan0 up
   

3. 更新配置文件

   # configs/fusion.yaml  
   source: nexmon
   nexmon_iface: wlan0
   

🎮 系统运行

基于Web的可视化（推荐）

# 启动Web服务器并进行实时可视化
source venv/bin/activate
python run_js_visualizer.py

# 可选：指定设备来源
python run_js_visualizer.py --source esp32
python run_js_visualizer.py --source nexmon

# 访问Web界面
# 打开浏览器访问：http://localhost:5000

传统终端模式

# 使用默认配置运行
./run_wifi3d.sh

# 指定设备来源运行
./run_wifi3d.sh esp32
./run_wifi3d.sh nexmon

# 对于Nexmon，可启用自定义信道跳变
sudo IFACE=mon0 HOP_CHANNELS=1,6,11 python run_realtime_hop.py

训练模式

# 首先运行系统收集训练数据
python run_js_visualizer.py

# 利用收集的数据训练模型
bash train_wifi3d.sh --epochs 100 --device cuda

# 启用持续学习进行训练
bash train_wifi3d.sh --continuous --auto-improve

# 从检查点恢复训练
bash train_wifi3d.sh --resume env/weights/checkpoint_epoch_50.pth

📋 配置文件

主配置文件：configs/fusion.yaml

# CSI数据源
source: esp32                    # esp32、nexmon或模拟数据
esp32_udp_port: 5566            # ESP32使用的UDP端口
nexmon_iface: wlan0             # Nexmon使用的网络接口

# 检测参数  
movement_threshold: 0.002        # 运动检测灵敏度
debounce_seconds: 0.3           # 检测之间的最小时间间隔
win_seconds: 3.0                # CSI 分析窗口大小

# 3D 可视化
scene_bounds: [[-2,2], [-2,2], [0,3]]  # 3D 场景边界
rf_res: 64                      # RF 场分辨率
alpha: 0.6                      # 可视化透明度

# 机器学习
enable_reid: true               # 启用行人重识别
reid:
  checkpoint: env/weights/who_reid_best.pth
  seq_secs: 2.0                # 用于 ReID 的序列长度
  fps: 20.0                    # 处理帧率

# 高级功能  
enable_pose3d: false            # 3D 姿态估计（实验性）
enable_nerf2: false             # 神经 RF 场（实验性）

🔧 高级功能

持续学习系统

该系统包含一个先进的持续学习流水线，能够：

1. 实时监控检测置信度
2. 自动从高置信度检测中收集训练样本
3. 在后台更新模型，不影响可视化
4. 根据环境特征自适应调整检测阈值
5. 随时间不断提升行人重识别性能

模型训练流水线

# 示例：自定义训练脚本
from train_model import WiFiTrainer, TrainingConfig

# 配置训练
config = TrainingConfig(
    batch_size=64,
    learning_rate=0.001,  
    epochs=200,
    continuous_learning=True,
    auto_improvement=True
)

# 初始化训练器
trainer = WiFiTrainer('configs/fusion.yaml', args)

# 开始持续学习训练
trainer.train()

实时性能优化

• 多线程处理：分别使用独立线程进行数据采集、处理和可视化
• 自适应帧率：根据系统负载自动调整处理速度
• 内存管理：高效管理 CSI 缓冲区，支持长时间运行
• GPU 加速：支持 CUDA 进行神经网络推理和训练

🌐 Web 界面功能

响应式仪表盘

• 实时 CSI 指标：信号方差、幅度、活动水平
• 人员检测状态：人数、置信度、位置
• 骨骼可视化：带关节追踪的 3D 动画骨骼
• 系统性能：FPS、内存使用、处理时间
• 活动日志：带时间戳的实时事件记录

交互式 3D 场景

• 手动相机控制：鼠标可实现环绕、缩放、平移
• 地面噪声可视化：动画圆形波纹图案
• 骨骼渲染：为检测到的人员显示完整的 3D 人体骨骼
• 实时更新：以 10 FPS 的速率进行数据直播

仪表盘组件面板

系统性能指标（左）和CSI信号分析（右）

HUD 信息面板

验证模型性能

# 评估训练好的模型
python tools/eval_reid.py --checkpoint env/weights/best_model.pth

# 录制测试序列
python tools/record_reid_sequences.py --duration 60

# 模拟 CSI 数据用于测试
python tools/simulate_csi.py --samples 1000

📊 数据收集与管理

CSI 数据存储

env/
├── csi_logs/              # 原始 CSI 数据文件 (*.pkl)
├── logs/                  # 系统和训练日志  
├── weights/               # 训练好的模型检查点
└── visualization/         # Web 界面文件
    ├── index.html         # 主仪表盘
    ├── js/app.js         # 可视化逻辑
    └── css/style.css     # UI 样式

训练数据组织

data/
├── reid/                  # 行人重识别数据
│   ├── person_000/       # 单个行人的序列
│   ├── person_001/
│   └── ...
├── splits/               # 训练/验证划分
│   ├── train.txt
│   ├── val.txt  
│   └── gallery.txt
└── logs/                 # 训练历史和指标

🚨 故障排除

常见问题

1. 未收到 CSI 数据

# 检查 ESP32 连接
ping <ESP32_IP>

# 验证 UDP 端口
netstat -ulnp | grep 5566

# 使用模拟数据测试
python run_js_visualizer.py --source dummy

2. 监控模式问题（Nexmon）

# 重置网卡接口
sudo ip link set wlan0 down
sudo iw dev wlan0 set type managed  
sudo ip link set wlan0 up

# 重新启用监控模式
sudo ip link set wlan0 down
sudo iw dev wlan0 set type monitor
sudo ip link set wlan0 up

3. 训练失败

# 检查 GPU 是否可用
python -c "import torch; print(torch.cuda.is_available())"

# 在内存有限的情况下降低批量大小
bash train_wifi3d.sh --batch-size 16

# 使用 CPU 训练
bash train_wifi3d.sh --device cpu

4. Web 界面问题

# 检查服务器是否运行
curl http://localhost:5000/data

# 清除浏览器缓存并刷新页面
# 检查浏览器控制台是否有 JavaScript 错误（按 F12）

# 重启服务器
pkill -f run_js_visualizer.py
python run_js_visualizer.py

调试日志

启用详细日志以进行故障排除：

# 设置调试模式
export WIFI3D_DEBUG=1

# 以详细输出运行
python run_js_visualizer.py --verbose

# 查看日志文件
tail -f env/logs/wifi3d_*.log

---

可选桥接模块（默认禁用）

1) Person-in-WiFi-3D（3D 姿态）

• 仓库：third_party/Person-in-WiFi-3D-repo

• 在 configs/fusion.yaml 中启用：enable_pose3d: true

• 将兼容的检查点放置于 env/weights/pwifi3d.pth。

• 按照仓库预期的结构准备测试数据（data/wifipose/test_data/...），然后运行：

  python -m src.bridges.pwifi3d_runner \
    third_party/Person-in-WiFi-3D-repo config/wifi/petr_wifi.py env/weights/pwifi3d.pth
  

  (我们调用仓库内 OpenMMLab 的 tools/test.py。)

2) NeRF²（RF 场）

• 仓库：third_party/NeRF2

• 在 configs/fusion.yaml 中启用：enable_nerf2: true

• 训练：

  python -m src.bridges.nerf2_runner
  

3) 3D Wi-Fi 扫描仪（RSSI 体积）

• 仓库：third_party/3D_wifi_scanner
• 使用该工具生成体积 RSSI 数据集；如有需要，可将其集成到您自己的融合管道中。

---

配置

编辑 configs/fusion.yaml：

• source: esp32 | nexmon
• esp32_udp_port, nexmon_iface 等。
• 检测器阈值：movement_threshold, win_seconds, debounce_seconds。

---

Docker

docker compose build
docker compose run --rm fusion

---

注意事项

• 对于 Nexmon，您需要 tcpdump 权限。Dockerfile 中已包含该工具；在主机上，请安装并以 root 或 sudo 权限运行。
• 对于 Person-in-WiFi-3D，请遵循该仓库的要求（PyTorch、MMCV/MMDet）。我们的 scripts/install_all.sh 脚本会安装兼容版本。
• 对于 ESP32-CSI，支持与常见分叉兼容的 UDP JSON 数据包。

---

使用方法（超简）

自适应监听模式流水线（推荐用于 RTL8812AU、Nexmon 或任何监听模式接口）

sudo -E env PATH="$PWD/venv/bin:$PATH" IFACE=mon0 HOP_CHANNELS=1,6,11 python3 run_realtime_hop.py

这将启动上述自学习流水线。

如果您想使用 Docker 方式：

docker compose build
docker compose run --rm fusion

---

🔧 系统要求与依赖

• 操作系统: Ubuntu 22.04 及以上版本（已测试内核 6.14）

• Python: 3.12（由 scripts/install_all.sh 脚本管理的 venv 环境）

• GPU: 可选（仅用于 Pose3D/NeRF² 桥接）

• 自动安装的软件包：

  • 基础包：numpy, pyyaml, loguru, tqdm, open3d, opencv-python, einops, watchdog, pyzmq, matplotlib, csiread==1.4.1
  • 可选 Pose3D 包：torch + torchvision（cu118/cu121 或 CPU 版本）、openmim, mmengine, mmcv, mmdet

• 捕获用系统工具（可选）： tcpdump, tshark/wireshark, aircrack-ng, iw

安装脚本会将 Torch/openmim 保持在 默认 PyPI 上（避免 PyTorch 索引污染），并将 csiread 锁定为与 Python 3.12 兼容的 wheel 包。

---

🛠️ WiFi 适配器、驱动程序及监听模式设置（RTL8812AU 示例）

支持的适配器

本项目基于一款 双频 USB WiFi 适配器，搭载 Realtek RTL8812AU 芯片组 开发，该适配器同时支持 2.4 GHz 和 5 GHz 频段、监听模式以及数据包注入功能。这款适配器广泛应用于 WiFi 安全研究领域，并且与 Ubuntu、Kali、Parrot 等 Linux 发行版兼容。其他 Nexmon 兼容适配器或配备 CSI 固件的 ESP32 也均受支持。

驱动程序安装（RTL8812AU）

默认内核驱动可能无法完全支持监听模式。为获得最佳效果，建议从 aircrack-ng/rtl8812au 仓库安装最新驱动：

sudo apt update
sudo apt install dkms git build-essential
git clone https://github.com/aircrack-ng/rtl8812au.git
cd rtl8812au
sudo make dkms_install

这将为当前内核构建并安装驱动程序，从而实现可靠的监听模式和数据包捕获。

启用监听模式

安装驱动后，连接您的 RTL8812AU 适配器并确认其接口名称（例如 wlx...）：

iw dev
iwconfig

要启用监听模式并创建 mon0 接口：

sudo airmon-ng check kill
sudo airmon-ng start <your-interface>
# 或者手动操作：
sudo ip link set <your-interface> down
sudo iw dev <your-interface> set type monitor
sudo ip link set <your-interface> up

验证监听模式是否生效：

iwconfig

您应能看到 mon0 或您选择的接口显示“Mode:Monitor”。

验证数据包捕获

为确认您的接口正在监听模式下捕获 WiFi 数据包：

sudo airodump-ng mon0
sudo tcpdump -i mon0

如果一切正常，您应该能够看到网络和数据包。若未显示，请确保周围环境中存在活跃的 WiFi 流量。

其他工具

为了调试和生成流量，您还可以安装以下工具：

sudo apt install aircrack-ng tcpdump tshark

---

🧑‍💻 运行监听模式下的实时流水线

前提条件

1. WiFi 适配器处于监听模式（参见上述设置说明）
2. 虚拟环境已激活
3. 所有依赖项已安装

步骤执行

1. 激活虚拟环境：

source venv/bin/activate

2. 设置监听接口（如尚未完成）：

sudo bash scripts/setup_monitor.sh

3. 验证监听模式是否正常工作：

sudo iwconfig mon0
sudo tshark -i mon0 -c 5

4. 运行实时流水线：

# 基本监听模式运行
sudo -E env PATH="$PWD/venv/bin:$PATH" IFACE=mon0 python run_js_visualizer.py --source monitor

# 高级：多信道跳转
sudo -E env PATH="$PWD/venv/bin:$PATH" IFACE=mon0 HOP_CHANNELS=1,6,11 python run_realtime_hop.py

# 带有监听模式的 Web 界面
sudo python run_js_visualizer.py --source monitor

5. 打开 Web 界面：

# 在浏览器中访问：
http://localhost:5000

功能说明：

• ✅ 实时 CSI/RSSI 捕获：从监听接口进行实时数据包分析
• ✅ 自动训练：持续学习并优化模型
• ✅ 3D 可视化：基于 Three.js 的 Web 查看器，支持骨骼渲染
• ✅ 信道扫描：自适应地在活跃的 WiFi 信道间切换
• ✅ 人员检测：实时跟踪与识别人员
• ✅ 日志记录：完整的调试与状态信息

---

🧑‍💻 运行实时自适应 Python 流水线

当您的适配器处于监听模式并开始捕获数据包后，运行以下命令：

sudo -E env PATH="$PWD/venv/bin:$PATH" IFACE=mon0 HOP_CHANNELS=1,6,11 python3 run_realtime_hop.py

这将：

• 开始实时 CSI/RSSI 捕获与分析
• 自动训练检测模型
• 启动 Open3D 查看器（稳定可靠，不会出现空白画面）
• 自适应扫描并聚焦于最活跃的 WiFi 信道
• 以英文展示检测结果及所有调试/状态信息

---

🛡️ 故障排除

• Open3D 窗口空白 确保数据正在传输：

  • ESP32: sudo tcpdump -n -i any udp port 5566
  • Nexmon: sudo tcpdump -i wlan0 -s 0 -vv -c 20
  • 监控模式: sudo tshark -I -i mon0 -a duration:5 -T fields -e radiotap.dbm_antsignal | head 如有需要，安装 GL 库：sudo apt-get install -y libgl1

• 未找到 openmim / Torch 索引问题 使用提供的 install_all.sh 脚本（仅从 PyTorch 索引安装 Torch，openmim 从 PyPI 安装）。 对于 Pose3D： WITH_POSE=true TORCH_CUDA=cu121 bash scripts/install_all.sh

• csiread 轮子版本不匹配 Python 3.12 → 锁定到 csiread==1.4.1（已在依赖流程中）。

• 监控接口无法捕获 终止网络管理器，重新创建 mon0，并修复信道： sudo airmon-ng check kill && bash scripts/setup_monitor.sh

---

🌌 为什么构建 WiFi-3D-Fusion

我构建了 WiFi-3D-Fusion,因为我无法忍受沉默。
这个世界充满了看不见的信号，每秒钟都有海量信息穿过我们身边，但大多数人甚至从未察觉。研究人员发表论文，公司许下承诺，然而几乎没有人揭示真相。

我想揭开这层面纱。

该项目不仅仅是一套软件。它证明了我们所说的“空气”其实充满着数据，那些无形的信息可以被塑造成形态、运动和存在感。
这不是关于监视，也不是关于控制。
而是展示技术可以在不侵犯隐私的情况下揭示信息，在不监控的前提下感知事物，在没有束缚的情况下保护人们。

为什么？因为在某些地方，摄像头会失效——黑暗的房间、燃烧的大楼、坍塌的隧道、深埋地下的空间。而在这些地方，像这样的系统可能意味着生与死的差别。

我进行实验，是因为我拒绝接受“不可能”。
我建造，是因为这个世界需要看到那些它否认存在的东西。
WiFi-3D-Fusion 不是一个产品，而是一束在黑暗中闪耀的信号弹。

局限性：WiFi 感知面临信号干扰和分辨率限制等挑战（2.4GHz：约 12.5cm，5GHz：约 6cm）。这是一个研究项目，未经验证不得用于关键应用。

🔏 法律/研究声明

伦理与隐私

• 仅在您拥有或控制的网络和环境中，经过明确授权后方可操作。
• 尽可能使用非识别性的感知模式；避免存储个人数据。
• 在公共场合进行现场演示时，请提前告知参与者。
• 始终遵守当地法律法规。

免责声明

╔══════════════════════════════════════════════════════════════════════════╗
║                              🔏 免责声明                               ║
╚══════════════════════════════════════════════════════════════════════════╝

本项目 WiFi-3D-Fusion 仅用于研究、教育和实验目的。
您必须仅在获得明确许可和授权的网络、设备和环境中使用本项目。
────────────────────────────────────────────────────────────────────────────
⚠️  法律提示：

未经授权的使用可能违反当地法律、隐私法规以及窃听相关法律。
作者绝不纵容或支持任何形式的监视、间谍活动或侵犯隐私的行为。
您需对合法合规及道德操作承担全部责任。

────────────────────────────────────────────────────────────────────────────
⚠️  责任限制：

作者（MaliosDark）不对因滥用本软件、非法行为或由此产生的任何损害承担责任。
下载、编译或执行本项目即表示您完全同意遵守所有适用法律，并自行承担相应责任。

────────────────────────────────────────────────────────────────────────────
✔️  安全使用建议：

仅在您自己的 Wi‑Fi 网络或经授权的测试环境中使用。
在公开场合展示时，优先选择演示或模拟模式。
在实际环境中操作时，请务必告知相关人员。
请勿尝试对他人进行隐蔽监控。

────────────────────────────────────────────────────────────────────────────
📌 使用 WiFi-3D-Fusion 即表示您确认：

您已充分理解本声明内容。
您将对使用结果承担全部责任。
作者免于任何法律诉讼或损害赔偿。

╔══════════════════════════════════════════════════════════════════════════╗
║         免责声明结束 – 请负责任地使用，否则请勿使用         ║
╚══════════════════════════════════════════════════════════════════════════╝

---

星标历史

📚 引用/上游项目

1. 基于 WiFi 的端到端多人 3D 姿态估计（CVPR 2024）
2. GitHub - aiotgroup/Person-in-WiFi-3D-repo
3. NeRF2：神经无线电频率辐射场（MobiCom 2023）
4. GitHub - XPengZhao/NeRF2
5. GitHub - Neumi/3D_wifi_scanner
6. Hackaday - 用改装的 3D 打印机可视化 WiFi
7. GitHub - StevenMHernandez/ESP32-CSI-Tool
8. GitHub - citysu/csiread

---

WiFi-3D-Fusion 快速上手指南

WiFi-3D-Fusion 是一个基于本地 Wi-Fi 信道状态信息（CSI）的实时 3D 运动感知与可视化工具。它支持通过 ESP32 或 Nexmon 固件采集数据，利用深度学习模型实现实时人员检测、骨架估计及 3D 可视化。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 22.04+)
• Python 版本: 3.8+
• 硬件设备 (二选一):
  • 方案 A (推荐新手): 刷写了 CSI 固件的 ESP32 开发板。
  • 方案 B (进阶): 支持监控模式 (Monitor Mode) 的 USB Wi-Fi 适配器 (如搭载 Realtek RTL8812AU 芯片的网卡，需配合 Nexmon 固件)。
• 可选加速: 支持 CUDA 的 NVIDIA GPU (用于加速模型训练)。

前置依赖

确保系统已安装基础构建工具：

sudo apt update
sudo apt install -y git python3-pip python3-venv build-essential
# 若使用 Nexmon 方案，还需安装 tcpdump 和 libpcap-dev
sudo apt install -y tcpdump libpcap-dev

2. 安装步骤

克隆项目

git clone https://github.com/MaliosDark/wifi-3d-fusion.git
cd wifi-3d-fusion

一键安装依赖

项目提供了自动化脚本安装所有 Python 依赖并配置虚拟环境。

国内加速提示: 如果下载依赖缓慢，可先配置 pip 国内镜像源（如清华源）： pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

执行安装脚本：

bash scripts/install_all.sh

激活环境

安装完成后，激活 Python 虚拟环境：

source venv/bin/activate

验证安装

python -c "import torch, numpy, yaml; print('✅ 所有依赖安装成功')"

3. 基本使用

硬件配置简述

在运行前，请确保已完成以下任一硬件配置：

• ESP32 模式: 将 ESP32 刷入 CSI 固件，配置其连接 Wi-Fi，并将 UDP 目标 IP 设为本机 IP，端口设为 5566。
• Nexmon 模式: 确保网卡已进入监控模式 (Monitor Mode)，并能通过 tcpdump 抓取数据包。

启动方式一：Web 实时可视化 (推荐)

此模式启动基于浏览器的 3D 可视化界面，交互性更好。

# 确保已在虚拟环境中
source venv/bin/activate

# 启动 Web 可视化服务
python run_js_visualizer.py

启动后，打开浏览器访问 http://localhost:5000 即可看到实时 3D 运动感知画面。

启动方式二：传统命令行管道

根据数据来源选择对应的启动命令：

使用 ESP32 数据源 (默认 UDP 端口 5566):

./scripts/run_realtime.sh --source esp32

使用 Nexmon 数据源 (需要 sudo 权限抓取数据包):

sudo ./scripts/run_realtime.sh --source nexmon

简易模型训练 (可选)

如果需要针对特定环境优化检测模型，可运行以下命令进行快速训练：

# 使用当前配置进行基础训练
./train_wifi3d.sh

# 开启持续学习模式（模型会根据新数据自动优化）
./train_wifi3d.sh --quick --continuous