RuView ESP32 CSI 节点 NVS 配置实战：provision.py 单节点配网与 generate_nvs_matrix.py 固件矩阵

RuView ESP32 CSI 节点 NVS 配置实战provision.py 单节点配网与 generate_nvs_matrix.py 固件矩阵【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView本篇技术指南聚焦 RuView 仓库中 ESP32 CSI 传感节点的免重编译配置Provisioning链路通过 firmware/esp32-csi-node/provision.py 把 WiFi 凭据、汇聚端Sink地址、信道策略与边缘智能参数写入设备 NVS 分区并通过 scripts/generate_nvs_matrix.py 批量生成固件测试矩阵。读完本文你将掌握每个--参数的含义与取值边界、NVS 键名与固件读取端的对应关系、刷写前如何用--dry-run/--state安全预览以及配网后如何通过串口与 Rust 汇聚端双向验证整条 CSI 数据链路。一、Provisioning 解决什么问题RuView 的 ESP32 传感节点固件位于 firmware/esp32-csi-node负责采集 WiFi 信道状态信息CSI并经由 UDP 上报。对于已经烧录好固件二进制的板子若要修改它所连接的 WiFi、上报目标主机、监听信道等运行参数重新编译固件成本高昂。Provisioning 的思路是把运行期配置单独写入设备的 NVSNon-Volatile Storage分区固件启动时从 NVS 读取从而实现烧录一次固件、随时改配置。NVS 分区在源码中的布局为NVS_PARTITION_OFFSET 0x9000分区起始地址NVS_PARTITION_SIZE 0x6000分区大小 24 KiB见 provision.py。所有配置统一存放在名为csi_cfg的 NVS namespace 下。固件侧由 main/nvs_config.c 读取这些键值包括csi_channel、filter_mac、hop_count/chan_list/dwell_ms、tdm_slot、seed_url、zone_name等见 nvs_config.c因此写入的键名必须与固件约定严格一致这正是 provision 脚本的价值所在——它替你生成合法的 NVS CSV 与二进制。二、环境准备与权威参数清单2.1 依赖安装provision 脚本通过esptool完成烧录通过 NVS 分区生成器生成二进制pip install esptool5.0 nvs-partition-gen生成器有多个可用来源脚本会按顺序自动探测见 provision.pypython -m esp_idf_nvs_partition_gen generate csv bin size子进程方式跨版本最稳python -m nvs_partition_gen generate ...ESP-IDF 自带脚本$IDF_PATH/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py。若三者都不可用脚本会报错并把生成的 NVS CSV 落盘为nvs_config.csv同时打印手工生成与烧录的命令供你结合 ESP-IDF 环境手动完成见 provision.py。2.2 获取权威参数清单官方文档明确建议先执行--help拿到当前版本的真实参数定义不要凭记忆拼命令。python firmware/esp32-csi-node/provision.py --help在 Windows 上由于帮助文本包含非 ASCII 字符在 cp1252 代码页下会直接崩溃必须显式指定 UTF-8PYTHONUTF81 PYTHONIOENCODINGutf-8 python firmware/esp32-csi-node/provision.py --help脚本默认串口为COM8--port为必填参数见 provision.py。三、单节点配网命令全解官方 prompt 给出的标准完整命令如下覆盖 WiFi、汇聚端、节点身份、信道策略、边缘智能、Swarm 桥接六大类配置python firmware/esp32-csi-node/provision.py --port COM8 \ --ssid SSID --password PW --target-ip SINK_IP --target-port 5005 --node-id 0-255 \ [--channel N] [--filter-mac AA:BB:CC:DD:EE:FF] [--hop-channels 1,6,11 --hop-dwell 200] \ [--tdm-slot i --tdm-total n] [--edge-tier 0|1|2] [--pres-thresh 50] [--fall-thresh 15000] \ [--vital-win 300] [--vital-int 1000] [--subk-count 32] \ [--seed-url http://10.1.10.236 --seed-token bearer --zone lobby] [--swarm-hb 30] [--swarm-ingest 5] [--dry-run]其中--port为必填Linux 下通常为/dev/ttyUSB0。脚本还会自动探测芯片型号--chip默认auto可显式指定esp32s3/esp32c6默认烧录波特率 460800--baud。3.1 参数总表默认值与取值边界以下取值边界与默认值均来自 provision.py 的 argparse 定义参数默认值取值/格式说明--port必填如COM8、/dev/ttyUSB0串口--chipautoesp32s3/esp32c6等esptool 目标芯片--baud460800整数烧录波特率--ssid—字符串WiFi SSID--password—字符串WiFi 密码--target-ip—IP 字符串汇聚端Sink主机 IP--target-port5005整数u16汇聚端 UDP 端口--node-id10–255u8节点 ID--channel自动1–142.4G或 36–1775G固定 CSI 信道覆盖 AP 自动探测--filter-mac关闭AA:BB:CC:DD:EE:FF只采集指定发射端 MAC 的 CSI--hop-channels—逗号分隔如1,6,11多频跳频信道表ADR-073--hop-dwell200整数 ms每个信道驻留时长--tdm-slot—0 起整数TDM 时隙号与--tdm-total成对--tdm-total—整数网格节点总数--edge-tier—0/1/2边缘处理层级0关1统计2生命体征--pres-thresh50整数u16存在检测阈值--fall-thresh15000整数u16跌倒检测阈值毫单位值/1000 rad/s²--vital-win300帧数u16相位历史窗口--vital-int1000msu16生命体征包发送间隔--subk-count32整数u8Top-K 子载波数--seed-url—URL如http://10.1.10.236Cognitum Seed 基址ADR-066--seed-token—Bearer 字符串Seed 配对令牌--zone—字符串节点区域名如lobby、hallway--swarm-hb30秒u16Swarm 心跳间隔--swarm-ingest5秒u16Swarm 向量摄取间隔--dry-run关开关只生成 NVS 二进制不烧录--force-partial关开关允许无 WiFi 凭据刷写#391/#574 后已基本不需要--reset关开关清空本机该端口的合并状态文件后全新配置--state关开关打印将要烧录的合并结果并退出--state-dir用户配置目录路径覆盖状态文件目录3.2 参数取舍原则官方要点固定信道 vs 跳频--channel N把节点钉在 AP 所在信道上单信道、简单稳定省略它并改用--hop-channels 1,6,11则启用固件的多频跳频调度ADR-073感知带宽更大且可借用邻居 AP 作为照射源--hop-dwell控制每个信道的驻留毫秒数。MAC 过滤--filter-mac MAC把 CSI 采集限定到单一发射端信号更干净省略则采集所有发射端数据更多但噪声也更多。从源码看过滤发生在 main/csi_collector.c 的 WiFi CSI 回调里且使用防御性拷贝的s_filter_mac避免 NVS 配置被wifi_init_sta破坏的已知问题。边缘层级--edge-tier取0/1/2分别对应 关/统计/生命体征见 ADR-039/ADR-041 的 on-device 处理管线。TDM 网格--tdm-slot/--tdm-total为多节点网格分配发送时隙两者必须成对出现。跌倒阈值--fall-thresh 15000约等于15.0 rad/s²人流大的区域可调高以降低误报。3.3 脚本侧校验规则provision 脚本在写盘前会做严格参数校验见 provision.py--tdm-slot与--tdm-total必须同时给出且slot total--channel必须落在 1–142.4GHz或 36–1775GHz--filter-mac必须是 6 组十六进制字节的AA:BB:CC:DD:EE:FF格式且每个字节在 0x00–0xFF 内合并状态后若--ssid/--password/--target-ip仍缺失且未加--force-partial脚本会拒绝执行并给出明确错误提示。校验通过后脚本会打印将要写入的配置摘要SSID、目标 IP、节点 ID、边缘层级描述、信道、MAC 过滤等随后才生成 NVS 二进制并烧录。四、NVS 键名映射CLI 参数与固件读取端的对应provision 脚本通过build_nvs_csv()把 CLI 参数编码为csi_cfgnamespace 下的键值对见 provision.py键名、类型与固件侧读取代码一一对应CLI 参数NVS 键类型/编码固件读取位置--ssidssidstringnvs_config.c--passwordpasswordstring同上--target-iptarget_ipstring同上--target-porttarget_portu16同上--node-idnode_idu8同上--tdm-slottdm_slotu8nvs_config.c--tdm-totaltdm_nodesu8同上注意键名是tdm_nodes--edge-tieredge_tieru8同上--pres-threshpres_threshu16同上--fall-threshfall_threshu16同上--vital-winvital_winu16同上--vital-intvital_intu16同上--subk-countsubk_countu8同上--channelcsi_channelu8nvs_config.c--filter-macfilter_machex2bin6 字节nvs_config.c--hop-channelshop_countchan_listu8 hex2bin blobnvs_config.c--hop-dwelldwell_msu32nvs_config.c--seed-urlseed_urlstringnvs_config.c--seed-tokenseed_tokenstring同上--zonezone_namestringnvs_config.c--swarm-hbswarm_hbu16同上--swarm-ingestswarm_ingestu16同上其中--hop-channels 1,6,11会被拆解为hop_count3、chan_list字节序列[1,6,11]的 hex2bin blob、dwell_mshop-dwell固件端按chan_list的 blob 长度读取见 nvs_config.c。MAC 过滤键则以 6 字节 blob 形式存储供 CSI 回调按字节比对。五、刷写机制从整命名空间覆盖到按端口增量合并官方 prompt 中明确警告了Issue #391历史上每次烧录都会重写整个csi_cfgNVS 命名空间任何未在命令行给出的键都会被抹掉导致只改一个参数却丢掉了其它全部配置。因此 prompt 要求完整传递你想要的全部参数重新配置一个正在运行的节点前务必确认。当前仓库中的 provision.py 已经实现了 #391/#574 阶段一的修复——按端口增量合并Additive-by-Default机制如下见 provision.py读取本机该串口对应的历史状态文件JSON存放于用户配置目录默认 Windows 为%APPDATA%其它平台为$XDG_CONFIG_HOME或~/.config子目录wifi-densepose/esp32-provision-state文件名按端口名转义把本次 CLI 参数叠加到历史状态之上CLI 显式值优先用合并结果生成并烧录 NVS把合并结果写回状态文件。这意味着局部改配按用户预期工作例如只传--pres-thresh 100WiFi 凭据等历史值会自动保留。配套的运维参数--reset清空状态文件与设备 NVS用于回收旧板做首次全新配置--state打印将要烧录的合并结果后退出是排查哪些键会落在设备上的调试利器--state-dir覆盖状态目录例如 CI 或团队共享机场景--dry-run只生成 NVS 二进制默认落盘nvs_provision.bin不烧录并同样持久化合并状态方便先预览再执行python -m esptool --chip auto --port COM8 write_flash 0x9000 nvs_provision.bin残留注意事项源码注释明确说明状态文件存在控制机上如果换一台机器配置同一块板子会从空状态开始——此时必须显式传递所有想保留的键或预置状态文件。设备权威的 USB-CDC NVS 导出方案仍在后续规划#574。--force-partial在 #391/#574 之后已基本废弃脚本默认合并历史状态该标志只作为明知无 WiFi 凭据也要刷的逃生门。六、固件矩阵批量配置generate_nvs_matrix.py单节点之外scripts/generate_nvs_matrix.py 面向批量测试场景对应 ADR-061一次生成 14 种 NVS 测试配置的二进制可注入 QEMU 闪存镜像 0x9000 偏移做自动化固件测试。# 生成全部 14 个配置 python3 scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix # 只生成部分配置 python3 scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix --only default,full-adr060 # 查看所有可用配置名 python3 scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix --list # 只导出 CSV跳过二进制生成 python3 scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix --csv-only14 个预置配置定义见 generate_nvs_matrix.py配置名用途default空 NVS固件走 Kconfig 默认值输出 0xFF 填充的擦除态分区wifi-only仅 WiFi 凭据full-adr060信道覆盖 MAC 过滤 完整基础配置edge-tier0原始 CSI 透传无片上 DSPedge-tier1基本存在/运动检测edge-tier2-custom完整管线 自定义阈值tdm-3node3 节点 TDM 网格本节点 slot 0wasm-signedWASM 运行时启用 Ed25519 签名校验wasm-unsignedWASM 运行时关闭签名校验5ghz-channel5GHz 信道 36 覆盖boundary-max各数值字段固件校验上限如vital_win256、subk_count32boundary-min各数值字段固件校验下限如fall_thresh100≈0.1 rad/s²power-save10% 占空比省电模式power_duty10empty-strings空 SSID/密码验证 Kconfig 回退该脚本复用了与 provision 相同的 NVS 生成逻辑子进程优先调用esp_idf_nvs_partition_gen/nvs_partition_gen随后尝试直接 import、最后回退 ESP-IDF 自带脚本并额外提供了--csv-only与--list便于调试与文档化。七、配网后验证与排障7.1 串口侧验证用 pyserial 打开串口监控COM8115200 波特。正常运行时固件会周期性打印两类关键日志adaptive_ctrl前缀的节拍信息——来自 main/adaptive_controller.c 的 ADR-081 自适应感知控制器默认三档循环fast 200ms / medium 1000ms / slow 30000mscsi_collector: CSI cb #… len128 rssi… ch…行——来自 main/csi_collector.c 的 CSI 回调日志打印回调序号、帧长、RSSI 与信道。该回调内置约 50Hz 的速率门限CSI_MIN_PROCESS_INTERVAL_US防止 ISR 中 SPI flash cache 崩溃UDP 发送同样做了限速20–50Hz。7.2 汇聚端Sink验证如果--target-ip指向当前主机Rust 汇聚端应开始收到 UDP 帧cd v2 cargo run -p wifi-densepose-sensing-server对应 crate 位于 v2/crates/wifi-densepose-sensing-server是 RuView 感知服务端的 UDP/CSI 入口。7.3 常见故障排查清单官方 prompt 给出的定位顺序按--target-ip已指向本机为前提信道不对节点监听的信道与 AP/发射端不一致CSI 回调无数据MAC 过滤过紧--filter-mac指定的发射端不在覆盖范围内或地址抄写错误target-ip 并非本机UDP 发到了别的地址检查网络与防火墙WiFi 凭据错误节点根本没连上网。修正参数后重新运行 provision 即可增量合并机制保证只改需要改的键。八、延伸阅读配网脚本完整实现firmware/esp32-csi-node/provision.py固件 NVS 读取端firmware/esp32-csi-node/main/nvs_config.cCSI 采集与限速firmware/esp32-csi-node/main/csi_collector.c自适应感知控制firmware/esp32-csi-node/main/adaptive_controller.c固件矩阵生成器scripts/generate_nvs_matrix.py汇聚端服务v2/crates/wifi-densepose-sensing-server相关决策记录ADR-039边缘智能、ADR-041WASM 可编程感知与边缘层级、ADR-060信道覆盖与 MAC 过滤、ADR-061NVS 测试矩阵、ADR-066Swarm Seed 协调、ADR-073多频跳频、ADR-081自适应感知控制器【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考