Router CSI Lab
ZH EN

Wi-Fi CSI 工具与数据集：GitHub 脚本、Python 分析和 OpenWrt 采集

作者 Wu Jun · 更新于 2026-11-02 · 约 7 分钟

这里汇总本项目实际使用与产出的工具。全部脚本都在真机跑过，配套 10 分钟长稳数据。

0. 先判断工具包是否适合你

你的状态 是否先下载工具包
路由器已经刷好 OpenWrt + mt76 CSI，daemon 能发 UDP 适合，从 10 秒快测开始
只想检查解析器或算法 先下载 10 秒 / 60 秒数据，不必刷机
尚未构建 CSI 固件 先完成复现教程
希望工具包含 Wi-Fi 固件或驱动补丁 不包含；固件与补丁需从对应上游获取
需要长期无人值守 先完成权限、日志、磁盘水位和回退演练

1. 采集与分析脚本

先用浏览器本地 CSI 抓包质量检查器做容器级验收： 检查外层分帧、chain_info 闭合组、链与子载波一致性、时间空档和 I/Q 是否为空。 CSI 文件不上传，检查后可导出 JSON 或 Markdown 报告。

以上脚本与解析工具以 MIT 许可开源，可直接在真机运行 [1]。

路由器稳定工具包 v0.1.3

压缩包包含采集、分析、watchdog、HE80/HE40 切换、vow_atf 开机调优脚本与数据格式文档。 不包含 Wi-Fi 固件、CSI 驱动补丁或环境特定的首启整机配置。脚本面向已刷好 OpenWrt + mt76 CSI 的研究设备， 运行前请先阅读包内 INSTALL.md，备份配置并确认接口名。

v0.1.3 把公开脚本中的站点链接统一到根域 okwujun.pw，并新增纯 Python 可复现打包器。 归档采用稳定的文件顺序、权限和时间元数据，同时排除 .git、缓存、凭据和环境专用首启配置； 连续两次构建的 tar.gz 字节一致。采集与分析行为沿用 v0.1.2 已修复的默认 UDP 8888 端口。 Software Heritage 已对 Git 仓库执行 full 归档；v0.1.3 快照 swh:1:snp:84d1d83e93b8ea9e197fea3b151b3f14113bef4c 同时固定了主分支提交、 发布分支和 tagged release。该独立存档只证明源码可追溯，不代表安全审计或性能背书。

# 下载后先校验，再解压
shasum -a 256 -c router-csi-toolkit-v0.1.3.tar.gz.sha256
tar -xzf router-csi-toolkit-v0.1.3.tar.gz

# 安装分析依赖
python3 -m pip install numpy matplotlib

# 典型流程：10 秒快测
router-csi-toolkit/scripts/csi_capture_session.sh 10

# 10 分钟长稳（会生成原始 bin + 分析图 + 摘要 txt）
router-csi-toolkit/scripts/csi_capture_session.sh 600

运行环境：macOS / Linux，Python 3.8+，numpy 与 matplotlib；抓包端需要 root 权限， 路由器端需已启用 mt76 CSI 并运行采集 daemon（见复现教程）。

输出文件：

文件 说明
csi_udp_*.bin 原始 UDP 流（含时间戳与 I/Q），可用于二次分析
*_summary.txt 记录数、时长、平均帧率、断流检测结果
analysis/*_heatmap.png 256 子载波幅度热图
analysis/*_motion.png 1 秒滚动运动指标

1.1 最短验收路径

  1. 确认 UDP 端口可达：tcpdump -ni any udp port 8888；
  2. 抓 10 秒，确认 bin 文件非空；
  3. 运行 analyze_csi_capture.py，确认记录数、时长与矩阵形状；
  4. 若数据正常，再跑 10 分钟；
  5. 检查最大空档、文件增长、RSSI/SNR 和 daemon 内存；
  6. 保存命令、固件版本、信道与带宽，不要只保存一张热图。

如果 10 秒文件为空，先检查 frame-type/MAC 过滤、接口名和目标客户端流量；不要直接跑 10 分钟。

2. 实测数据（本次公开）

文件 内容 规模
60 秒演示源（脱敏） 60 秒原始 UDP 流；347 个完整测量组 + 1 条尾部残片 2,777 条链记录，2.8MB
csi_udp_*_10m.bin 10 分钟原始 UDP 流 57,293 条链记录，约 58MB [2]
analysis/csi_amplitude_heatmap.png 幅度热图（256 子载波 × 时间） —
analysis/csi_mean_amplitude_motion.png 1 秒滚动运动指标 —

数据格式见复现教程第 6 节（24 字节头 + int16 I/Q 交错）。 60 秒演示源可按 SHA-256 校验：SHA256SUMS / manifest。 完整 10 分钟数据集已发布到 Zenodo（DOI：https://doi.org/10.5281/zenodo.23434789）， 含 8 个分片、manifest、重组说明与两张分析图。 另见10 分钟 CSI 质量审计：无需训练分类器，即可复跑时间轴报告、 JSON 摘要与脚本。 长空档频谱代价进一步比较插值 Welch 与原始时间戳周期图， 并发布可复现脚本、频率扫描 CSV 和四面板图。 CSI 链健康审计则量化 8 链与 4 链组、逐链时间变异和 RSSI/SNR 的共享语义， 并公开 analyze_csi_chain_health.py、chain_metrics.csv、JSON 摘要与 SVG 图。 CSI 子载波冗余审计用两段抓包计算 256-bin 相关矩阵和 PCA： 6 个主成分解释 90% 方差，公开逐 bin CSV、256 个特征值、摘要、脚本和图。该结果不把统计维度 等同于物理传感器数量。

注意单位：95.5 是链记录/秒，不是 95.5Hz 独立快照。按 chain_info bit15 分组后，599.924 秒内有 7,609 个闭合测量组，约 12.68Hz；简单选链得到约 7,608 × 256 矩阵，再剔除 25 个异常组后使用 7,583 次测量， 对应约 12.64Hz。

CSI 幅度热图

3. 实时可视化平台（开源骨架）

配套的 platform/ 目录提供一套可自建的实时观测台：

部署前按 platform/README 配置数据源地址、监听端口与存储路径；容器只依赖 Docker， 不需要在宿主机安装数据库或 Python 运行时。

本项目曾在一台较旧的 i5-2430M / 8GB 内网服务器上部署该平台，但这不是跨配置容量承诺。 上线前应根据自己的记录率、解析窗口和保留期做 10 秒 / 10 分钟 / 24 小时压测。

3.1 平台接口与边界

接口 用途
GET /api/health UDP 摄取是否存活、错误计数
GET /api/stations 在线设备、present、motion_db
GET /api/stats / /api/config 统计与公开配置
WebSocket /ws 实时图表推送
/api/sessions/* 录制、下载、删除会话

平台当前没有内置 MQTT publisher，也不提供 /api/csi/status。Home Assistant 接入应使用 /api/stations REST，或单独实现 MQTT bridge。

4. 可直接复用的开源项目

项目 用途
espressif/esp-csi [3] ESP32 官方 CSI 应用，入门首选
StevenMHernandez/ESP32-CSI-Tool [4] ESP32 采集工具
Gi-z/CSIKit [5] Python CSI 解析/可视化（多平台）
citysu/csiread [6] 高速 Cython 解析
xyanchen/WiFi-CSI-Sensing-Benchmark（SenseFi）[7] 深度学习模型库
francescopace/espectre [8] ESP32 + ESPHome 运动感知
seemoo-lab/nexmon_csi [9] Broadcom 固件补丁，树莓派 80MHz CSI
ruvnet/RuView [10] Wi-Fi 空间智能（社区项目，宣传语未经同行评审，仅作线索）
NTUMARS/Awesome-WiFi-CSI-Sensing [11] 论文与资源清单
清华 WST 教程 [12] 高校发布的 Wi-Fi 感知动手讲义

5. 硬件（购买参考）

用途 推荐 说明
入门 CSI ESP32 开发板 ￥20 起，20MHz/30–64 子载波
路由器形态 GL-MT6000（MT7986） 本站实测平台，80MHz/256 子载波
高带宽科研 Nexmon CSI + 树莓派 / PicoScenes 灵活但成本更高

以上为硬件参考清单，不含推广链接；如未来加入推广链接，会在对应位置明确标注。

6. 安全、许可与停止条件

参考与数据来源

本文的每条外部结论都标注来源与证据等级（分级标准）；标注 E 级的是本项目可复现的实测数据。

  1. E 级 · 本项目实测 Router CSI Toolkit — 采集/分析/守护脚本（MIT，公开仓库）
    Router CSI Lab · 2026
    github.com/jjjwu/router-csi-toolkit · 核实: GitHub API 于 2026-11-02 核实公开仓库、抓包质量预检、成功 CI 与 v0.1.3 Release；归档 SHA-256 为 59f144c0…adea7 · 公开版含无第三方依赖的抓包质量预检；网页端检查器使用同一容器定义和边界口径。
  2. E 级 · 本项目实测 本项目 10 分钟实测抓包（57,293 条 / 600.0 s，SHA-256 00373f83…95e2）
    Router CSI Lab · 2026
    okwujun.pw/zh/datasets/ · 核实: 分片重组逐字节校验通过（2026-10-11） · 本地原始母片 SHA-256 为 00373f83…95e2；公开下载的是去标识派生文件，SHA-256 为 527466ce…a440，两者不可混用。
  3. C 级 · 官方资料 espressif/esp-csi — Applications based on Wi-Fi CSI
    Espressif Systems
    github.com/espressif/esp-csi · 核实: GitHub API 2026-10-29 (stars 1,723; README confirms the complete ESP32 series list and three sender/receiver routes) · 官方 README 原文：“All ESP32 series support CSI, including ESP32 / ESP32-S2 / ESP32-C3 / ESP32-S3 / ESP32-C5 / ESP32-C6 / ESP32-C61.”
  4. C 级 · 官方资料 StevenMHernandez/ESP32-CSI-Tool — active/passive CSI extraction for ESP32
    S. M. Hernandez
    github.com/StevenMHernandez/ESP32-CSI-Tool · 核实: GitHub API 2026-10-11 (stars 571, MIT, last push 2024-07-16)
  5. C 级 · 官方资料 Gi-z/CSIKit — Python CSI parsing and visualisation
    G. Zhang
    github.com/Gi-z/CSIKit · 核实: GitHub API 2026-10-11 (stars 307, MIT, last push 2025-02-19) · 支持 Atheros / Intel / Nexmon / ESP32 / FeitCSI / PicoScenes 多种格式。
  6. C 级 · 官方资料 citysu/csiread — fast Cython CSI parser
    S. Zhu
    github.com/citysu/csiread · 核实: GitHub API 2026-10-11 (stars 142, MIT, last push 2024-10-12)
  7. C 级 · 官方资料 xyanchen/WiFi-CSI-Sensing-Benchmark (SenseFi) — deep-learning benchmark
    X. Chen, et al.
    github.com/xyanchen/WiFi-CSI-Sensing-Benchmark · 核实: GitHub API 2026-10-11 (stars 638, MIT, last push 2023-11-06)
  8. C 级 · 官方资料 francescopace/espectre — Wi-Fi CSI motion sensing for ESP32 (ESPHome)
    F. Pace
    github.com/francescopace/espectre · 核实: GitHub API and official README fetched 2026-10-29 (stars 9,700; GPLv3; ESPHome source path, Direct API port 62587 and supported chips documented) · 官方项目提供 ESPHome、Native MQTT、Matter 与浏览器烧录路线；同一块 ESP32 覆盖一个区域，不识别身份或人数。
  9. C 级 · 官方资料 seemoo-lab/nexmon_csi — CSI extraction on various Broadcom Wi-Fi chips
    SEEMOO Lab, TU Darmstadt
    github.com/seemoo-lab/nexmon_csi · 核实: GitHub API 2026-10-29 (stars 479, last push 2026-09-30; README lists bcm43455c0 on Raspberry Pi 3B+/4B/5)
  10. D 级 · 预印本/百科 ruvnet/RuView — community Wi-Fi spatial-intelligence project
    r. u. v. (community maintainer) · 2026
    github.com/ruvnet/RuView · 核实: GitHub API 2026-10-11 (stars 97,237; created 2025-06-07) · 社区项目，非同行评审：宣传语（实时“空间智能/体征监测”）未见于独立复现，仅作线索、不作结论。
  11. C 级 · 官方资料 NTUMARS/Awesome-WiFi-CSI-Sensing — curated papers and resources
    NTU MARS Lab
    github.com/NTUMARS/Awesome-WiFi-CSI-Sensing · 核实: GitHub API 2026-10-11 (stars 1129, MIT, last push 2025-07-19)
  12. C 级 · 官方资料 WST — Hands-on Wireless Sensing with Wi-Fi (Tsinghua tutorial)
    Tsinghua University TNS group
    tns.thss.tsinghua.edu.cn/wst/ · 核实: tns.thss.tsinghua.edu.cn HTTP 200, 2026-10-11 · 高校发布的 Wi-Fi 感知动手教程（含讲义与数据集），非同行评审论文。
  13. E 级 · 本项目实测 Router CSI Lab — GL-MT6000 (MT7986) Wi-Fi CSI dataset, 10 s sample + 10 min capture
    Router CSI Lab · 2026
    doi:10.5281/zenodo.23434789 · 核实: CC BY 4.0；SHA-256 已发布；Zenodo DOI 10.5281/zenodo.23434789 · 数据集已获 Zenodo DOI（10.5281/zenodo.23434789），可直接引用。
  14. E 级 · 本项目实测 CSI subcarrier redundancy and effective-dimensionality audit (script, metrics, PCA spectrum)
    Router CSI Lab · 2026
    okwujun.pw/zh/csi-subcarrier-redundancy/ · 核实: From the public 10-minute and 60-second captures with input SHA-256 527466ce…a440 and 41c35d9d…87a6; script, JSON, CSVs and figure published together (2026-11-01) · 只证明这两段幅度抓包中的相关结构与有效维度，不把数组索引映射为物理频率，也不提供人体真值。