用途
RuView Hardware Setup 用于把一块 RuView 感知节点从零带到上线，流程为：编译固件 → 烧录 → 配置 WiFi → 确认 CSI 数据流。适用于搭建物理硬件、烧录 ESP32 固件、配置 WiFi 以及监控串口输出的场景。
支持的设备
- ESP32-S3（8MB）：Xtensa 双核，默认的 WiFi CSI 感知节点。
- ESP32-S3 SuperMini（4MB）：Xtensa 双核，紧凑型 CSI 节点，需使用 sdkconfig.defaults.4mb。
- ESP32-C6 + Seeed MR60BHA2：RISC-V + 60 GHz FMCW，用于毫米波心率/呼吸/存在检测。
不支持：原始 ESP32、ESP32-C3（单核）。
烧录前需先确认板型。如果用户使用的是硬币大小的克隆板（如 ESP32-S3-Zero、SuperMini 或类似产品，而非带真实 USB 接口和可见稳压器的完整 DevKitC/XIAO 风格板），应提前警告：该固件会持续运行 WiFi 射频（WIFI_PS_NONE）并执行完整 DSP 流水线（edge_tier=2），属于持续高电流消耗，全尺寸开发板可以承受，但铜层和稳压器预算有限的微型克隆板可能不行。至少有一例现场报告：板子在正常会话中发热，之后无法再次开机（疑似稳压器损坏）。应告知用户保持板子通风（不要堆叠或封闭），并在任何新部署的前几分钟内通过触摸检查温度。
主要能力
- 编译固件（Windows — 使用 Python 子进程，而非直接 bash）。ESP-IDF v5.4 不支持 MSYS2/Git Bash。需使用 Espressif Python venv 作为子进程，并剥离 MSYSTEM* 环境变量。已验证的命令位于 CLAUDE.local.md，可复现该命令。
8MB 构建：使用 sdkconfig.defaults.template（无 mock — 真实 WiFi CSI）。
4MB 构建：先执行 cp firmware/esp32-csi-node/sdkconfig.defaults.4mb firmware/esp32-csi-node/sdkconfig.defaults，再构建。
构建产物：firmware/esp32-csi-node/build/{bootloader/bootloader.bin, partition_table/partition-table.bin, esp32-csi-node.bin, ota_data_initial.bin}。
- 烧录到设备。使用相同的子进程模式，将 [python, idf_py, 'build'] 替换为 [python, idf_py, '-p', 'COM8', 'flash']。或直接使用 esptool：
python -m esptool --chip esp32s3 --port COM8 --baud 460800
write_flash 0x0 firmware/esp32-csi-node/build/bootloader/bootloader.bin
0x8000 firmware/esp32-csi-node/build/partition_table/partition-table.bin
0xf000 firmware/esp32-csi-node/build/ota_data_initial.bin
0x20000 firmware/esp32-csi-node/build/esp32-csi-node.bin
（此工作区默认设备端口为 COM8。部分文档提到 COM9 — 需与用户确认。）
- 配置 WiFi 与接收端地址。可直接运行，无需 ESP-IDF 环境：
python firmware/esp32-csi-node/provision.py --port COM8
--ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20 --target-port 5005 --node-id 1
可选的 ADR-060 覆盖项：
python firmware/esp32-csi-node/provision.py --port COM8 --channel 6 --filter-mac AA:BB:CC:DD:EE:FF
--help 会列出完整参数集（TDM mesh 时隙、edge tier、检测阈值、生命体征窗口、跳频信道、Cognitum Seed、swarm 间隔）— 参见 ruview-configure 技能中的表格。注意（issue #391）：烧录会替换整个 csi_cfg NVS 命名空间 — 任何未出现在 CLI 上的键都会被擦除；请传入你想要的完整参数集。在 Windows 上，provision.py --help 需要 PYTHONUTF8=1 才能打印（帮助文本含非 ASCII 字符）。
- 确认 CSI 数据流。串口监控（使用 pyserial — idf.py monitor 在子进程中会挂起）：
/c/Espressif/tools/python/v5.4/venv/Scripts/python.exe -c " import serial, time ser = serial.Serial('COM8', 115200, timeout=1); start = time.time() while time.time() - start < 15: line = ser.readline() if line: print(line.decode('utf-8', errors='replace').strip()) ser.close() "
然后启动接收端并观察帧到达：
cd v2 && cargo run -p wifi-densepose-sensing-server # 监听 ESP32 UDP CSI
常见问题
- “MSys/Mingw is no longer supported”：ESP-IDF 检测到 Git Bash。使用上述剥离 MSYSTEM* 的 Python 子进程命令。
- “cmd.exe /C hangs”：来自 Git Bash 的交互式提示。不要使用 cmd.exe /C — 使用 Python 子进程。
- “cmake not found”：路径错误。应为 cmake\3.30.2\cmake-3.30.2-windows-x86_64\bin，而非 cmake\3.30.2\bin。
- “python_env not found”：缺少环境变量。设置 IDF_PYTHON_ENV_PATH=C:\Espressif\tools\python\v5.4\venv。
- “No CSI frames at the sink”：WiFi 未配置、信道错误或 MAC 过滤过严。重新运行 provision.py；尝试 --channel 匹配你的 AP；去掉 --filter-mac。
- “False fall alerts”：旧的 fall_thresh 默认值。Issue #263 已将其提高到 15.0 rad/s² 并加入去抖 — 重新烧录最新固件。
固件发布流程（供维护者）
- 从 sdkconfig.defaults.template 构建 8MB（无 mock）。
- 从 sdkconfig.defaults.4mb 构建 4MB（无 mock）。
- 保存 6 个二进制文件：esp32-csi-node.bin、bootloader.bin、partition-table.bin、ota_data_initial.bin、esp32-csi-node-4mb.bin、partition-table-4mb.bin。
- git tag v0.X.Y-esp32 && git push origin v0.X.Y-esp32。
- gh release create v0.X.Y-esp32 <binaries> --title "..." --notes-file ...。
- 发布前在真实硬件（COM8）上验证 — 始终使用真实 WiFi CSI 测试，而非 mock 模式（mock 模式曾漏掉 Kconfig 阈值 bug）。
参考
- CLAUDE.local.md — 确切的 ESP-IDF 构建环境、路径、QEMU CI 说明。
- firmware/esp32-csi-node/ — C 固件（跳频、NVS 配置、TDM 协议）。
- docs/adr/ADR-028-esp32-capability-audit.md、docs/build-guide.md、docs/TROUBLESHOOTING.md。
限制
不支持原始 ESP32 与 ESP32-C3（单核）。ESP-IDF v5.4 不支持 MSYS2/Git Bash，Windows 下必须使用 Python 子进程方式。烧录会替换整个 csi_cfg NVS 命名空间，未在 CLI 中传入的键会被擦除。微型克隆板可能因持续高电流而发热甚至损坏稳压器。