RuView ESP32 节点 NVS 配网配置指南使用 provision.py 写入 WiFi 凭据与 CSI 传感参数【免费下载链接】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/RuViewRuView 将普通 WiFi 信号转化为空间智能、生命体征监测与存在检测能力而这一切的起点是让每个 ESP32 传感节点知道连哪个 WiFi、把 CSI 数据发到哪里、以何种模式工作。本篇技术指南围绕plugins/ruview/commands/ruview-provision.md展开完整讲解基于provision.py的 NVSNon-Volatile Storage非易失存储配网流程覆盖全部命令行参数、TDM 组网、边缘智能分级、信道跳频、MAC 过滤、Cognitum Seed 桥接等运行时配置项并深入剖析脚本底层实现与固件读取逻辑使读者可以像运行ruview-provision技能一样为任何一台预编译固件的 ESP32-S3 / ESP32-C6 节点完成免重编译的运行时配置与验证。一、为什么需要 NVS 配网免重编译的运行时配置RuView 的 ESP32 传感节点固件采用一份二进制、多种配置的设计哲学。固件在编译时通过 Kconfig 写入一组默认值而在运行时通过 NVS 键值覆盖这些默认值因此同一个esp32-csi-node.bin可以被批量烧录到多块开发板上再由provision.py按设备单独写入 WiFi 凭据、汇聚端 IP、节点 ID 等配置——完全不需要重新编译固件。从固件源码 main/nvs_config.h 可以看到运行时配置被装载进一个nvs_config_t结构体覆盖网络设置WiFi SSID/密码、汇聚端 IP/端口、节点 ID信道跳频与 TDMADR-029跳频信道列表、驻留时间、时分多址槽位边缘智能ADR-039处理分级、存在/跌倒阈值、生命体征窗口WASM 可编程传感ADR-040模块槽位与 Ed25519 签名校验信道覆盖与 MAC 过滤ADR-060显式 CSI 信道、发射端 MAC 过滤Swarm 桥接ADR-066Cognitum Seed 地址、令牌、区域名、心跳与向量摄入间隔。main/nvs_config.c 中的nvs_config_load()逐键执行nvs_get_str/nvs_get_u8/nvs_get_u16/nvs_get_blob任一键缺失即回退到 Kconfig 编译期默认值例如ssid键缺失时回退到wifi-denseposetarget_ip缺失时回退到192.168.1.100。这意味着空 NVS 的设备依然可以按默认配置启动写入部分键不会破坏未涉及的默认值唯一例外是下文要重点警示的整命名空间重写问题issue #391。二、ruview-provision 技能与 provision.py 的定位plugins/ruview/commands/ruview-provision.md是一个面向 Agent 的命令文档它把为 ESP32 节点写入 WiFi 凭据、汇聚端 IP 及可选的信道 / MAC 过滤覆盖这一任务封装为/ruview-provision技能。文档强调权威选项清单以provision.py --help为准。# Linux / macOS python firmware/esp32-csi-node/provision.py --help # Windows帮助文本含非 ASCII 字符强制 UTF-8 编码避免 cp1252 崩溃 PYTHONUTF81 PYTHONIOENCODINGutf-8 python firmware/esp32-csi-node/provision.py --help脚本位于 firmware/esp32-csi-node/provision.py其顶部 docstring 明确声明适用目标为 ESP32-S3、ESP32-C6 等芯片工作方式是把 WiFi 凭据与汇聚端目标写入 NVS 分区让用户无需重新编译即可配置预编译固件。前置依赖pip install esptool5.0 esp-idf-nvs-partition-genesptool用于串口烧写esp-idf-nvs-partition-gen提供 NVS 分区镜像生成能力脚本同样支持回退到 ESP-IDF 自带的nvs_partition_gen.py。串口与芯片参数参数默认值说明--port必填串口设备如COM8/COM7//dev/ttyUSB0--chipautoesptool 目标芯片auto默认、esp32s3、esp32c6等必须与连接的芯片匹配--baud460800烧写波特率--chip默认auto对 esptool v5 可自动探测若自动探测失败例如 C6 板显式传入--chip esp32c6。三、完整命令示例从最小配网到全功能配置原文档给出的核心命令骨架如下这是 /ruview-provision 技能的主流程python firmware/esp32-csi-node/provision.py --port PORT \ --ssid SSID --password PW --target-ip IP --target-port 5005 --node-id 0-255 \ [--channel N] [--filter-mac MAC] [--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://… --seed-token … --zone lobby] [--swarm-hb 30] [--swarm-ingest 5] [--dry-run]最小配网单节点连入 WiFi 并上报汇聚端python firmware/esp32-csi-node/provision.py --port COM8 \ --ssid MyWiFi --password secret \ --target-ip 192.168.1.20 --target-port 5005 \ --node-id 1这一组参数足以让节点连接指定 AP、以 UDP 方式向192.168.1.20:5005上报 CSI 帧并以node_id1标识自己。全功能配网示例覆盖所有参数组python firmware/esp32-csi-node/provision.py --port /dev/ttyUSB0 \ --ssid RuViewNet --password change-me \ --target-ip 192.168.1.20 --target-port 5005 --node-id 7 \ --channel 6 --filter-mac AA:BB:CC:DD:EE:FF \ --hop-channels 1,6,11 --hop-dwell 200 \ --tdm-slot 0 --tdm-total 3 \ --edge-tier 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注意--tdm-slot与--tdm-total必须成对出现且--tdm-slot必须小于--tdm-total脚本在 provision.py 中做了显式校验二者缺一会直接报错。四、参数详解每个配置项写入了哪个 NVS 键provision.py的build_nvs_csv()函数把每个 CLI 参数映射为csi_cfg命名空间下的具体 NVS 键下表依据 provision.py 源码与 firmware/esp32-csi-node/README.md 的 NVS Key Reference 整理参数NVS 键类型默认值说明--ssidssidstringwifi-denseposeWiFi SSID--passwordpasswordstring(空)WiFi 密码--target-iptarget_ipstring192.168.1.100汇聚端sinkIP--target-porttarget_portu165005汇聚端 UDP 端口--node-idnode_idu81节点 ID0-255--tdm-slottdm_slotu80本节点 TDM 槽位索引0 基--tdm-totaltdm_nodesu81TDM 调度中的节点总数--edge-tieredge_tieru820raw1stats2vitals--pres-threshpres_threshu16auto存在检测阈值×10000自动校准--fall-threshfall_threshu1615000跌倒阈值毫单位15000→15.0 rad/s²--vital-winvital_winu16300相位历史窗口帧--vital-intvital_intu161000生命体征包发送间隔ms--subk-countsubk_countu832跟踪的 Top-K 子载波数--channelcsi_channelu80自动检测显式 CSI 信道1-142.4GHz或 36-1775GHz--filter-macfilter_machex2bin(无)过滤 MACAA:BB:CC:DD:EE:FF 六字节 blob--hop-channelshop_countchan_listu8 blob[6]跳频信道列表如1,6,11--hop-dwelldwell_msu32200每信道驻留时间ms--seed-urlseed_urlstring(空禁用)Cognitum Seed 基础 URL如http://10.1.10.236--seed-tokenseed_tokenstring(空)Seed Bearer 令牌来自配对--zonezone_namestring(空)节点区域名如lobby--swarm-hbswarm_hbu1630Swarm 心跳间隔秒--swarm-ingestswarm_ingestu165向量摄入间隔秒几个值得注意的实现细节--channel的写入键是csi_channel固件中csi_channel为 0 表示自动检测跟随所连 AP 的信道非 0 则强制指定脚本对取值做了校验只接受 1-14 或 36-177。--filter-mac以hex2binblob 存储脚本将AA:BB:CC:DD:EE:FF拆分为 6 个十六进制字节后以十六进制字符串写入 NVS固件侧nvs_get_blob读取并校验长度为 6见 main/nvs_config.c。MAC 格式校验失败非 6 段或含非十六进制字节会直接报错。--hop-channels会展开为三个键hop_count信道数量、chan_list信道字节 blob、dwell_ms驻留时间。测试 firmware/esp32-csi-node/tests/test_provision.py 验证了--hop-channels 1,6,11会生成hop_count3、chan_list01060b、dwell_ms250的 CSV 行。--tdm-total写入的键是tdm_nodes固件中以tdm_node_count字段读取。--edge-tier的语义脚本注释为0off (raw CSI), 1stats, 2vitals固件 README 的描述是0raw, 1basic DSP, 2full pipeline——两者描述的是同一分级的不同侧重原文档以 off/stats/vitals 表述。五、关键权衡channel 固定 vs 跳频、filter-mac 过滤 vs 全捕获原文档要求 Agent 向用户解释三组关键取舍这里结合固件实现展开1.--channel固定信道 vs--hop-channels多频跳频--channel N固定模式节点钉在 AP 当前使用的信道上采集 CSI数据流稳定、单信道速率约 20 HzTier 0 直通模式适合对某一 RF 链路的持续观测。--hop-channels 1,6,11跳频模式ADR-061 多频跳频节点按dwell_ms驻留时间在多个信道间轮换可覆盖 2.4GHz 的三个常用非重叠信道获取更丰富的频谱视角代价是每个信道的驻留时间被切分。chan_list上限为 6 个信道固件NVS_CFG_HOP_MAX见 main/nvs_config.h。两者互斥使用想跳频就**省略--channel**并给出--hop-channels。2.--filter-mac限定单一发射端 vs 省略捕获全部设置--filter-mac只采集来自指定 MAC例如某台与节点直连的发射端的 CSI 帧数据更干净、目标明确适合单链路实验。省略捕获所有可见发射端的 CSI 帧——数据量更大、信噪比更低但视野更广适合多链路观测与环境感知。固件中filter_mac_set标志见 main/nvs_config.h指示该过滤是否生效。3.--edge-tier0/1/2从裸数据到板载生命体征固件实现了分级处理流水线详见 firmware/esp32-csi-node/README.md 的 Firmware Architecture 章节分级可在编译期Kconfig或运行期NVS选择无需重刷Tier 0raw裸 CSI 直通以 ADR-018 二进制格式经 UDP 上传约 20 Hz/信道单节点约 5 KB/s64 子载波 × 1 天线。Tier 1stats板载相位解卷、Welford 运行统计、Top-K 子载波跟踪降低上行带宽并改善信号质量。Tier 2vitals生命体征BPM、存在检测、跌倒检测阈值由--pres-thresh/--fall-thresh/--vital-win/--vital-int/--subk-count调节。--fall-thresh默认15000即 15.0 rad/s²脚本帮助文本建议高人流区域调高该值以减少误报跌倒对应 issue #263 的经验。六、⚠️ 核心警告NVS 命名空间整段重写issue #391原文档特别标红警示烧写会重写整个csi_cfgNVS 命名空间——所有未在 CLI 中传入的键都会被擦除。因此务必一次性传入你想要的完整参数集对已在运行的节点重新配网前先向用户说明风险不确定当前设备上有哪些键时先从串口启动日志读取adaptive_ctrl/csi_collector行会打印当前配置--force-partial可以有意识地绕过 WiFi 凭据三件套--ssid/--password/--target-ip的必填校验——设备烧录后将无法连接 WiFi需明确知晓后果--dry-run只构建 NVS 二进制而不烧写是验证参数组合的安全手段。从源码看--force-partial与状态合并机制值得注意的是当前版本 provision.py 已经实现了additive-by-default默认增量合并机制issue #391 / #574 phase 1脚本会在用户配置目录下按串口保存一份每端口状态文件Windows 为%APPDATA%\wifi-densepose\esp32-provision-state\port.json其他平台为~/.config/wifi-densepose/esp32-provision-state/port.json可用--state-dir覆盖、--state查看读取该端口的先前状态文件不存在则视为空用新的 CLI 参数覆盖叠加由合并结果生成并烧写 NVS将合并结果写回状态文件。因此在同一台电脑上对同一端口反复执行部分参数更新是安全的——未传的参数会回退到上次写入的值。但状态文件位于控制机本地换一台电脑配同一个设备会从空状态开始此时必须显式传入想保留的全部键或预先播种状态文件真正的以设备为准合并USB-CDC NVS 导出仍在规划中#574。--reset可同时清空状态文件与设备 NVS用于回收旧板首次配置。七、批量配网generate_nvs_matrix.py 与 QEMU 测试矩阵对于多节点部署ADR-061无需逐台手工执行可使用 scripts/generate_nvs_matrix.py 生成一批 NVS 分区镜像python scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix # 只看配置清单 python scripts/generate_nvs_matrix.py --list # 只生成特定配置 python scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix --only default,full-adr060 # 仅生成 CSV 不生成二进制 python scripts/generate_nvs_matrix.py --output-dir build/nvs_matrix --csv-only该脚本内置 14 种命名配置覆盖default空 NVS走 Kconfig 默认、wifi-only、full-adr060信道 MAC 过滤、edge-tier0/1/2-custom、tdm-3node、wasm-signed/unsigned、5ghz-channel、boundary-max/min固件校验边界值、power-save10% 占空比、empty-strings等场景。生成的二进制可注入 QEMU 闪存镜像的 0x9000 偏移用于自动化固件测试。boundary-max配置中的注释给出了固件校验范围参考vital_win32-256、top_k1-32、power_duty10-100。八、验证配网结果串口日志与汇聚端收包配网完成后按原文档流程验证1. 串口监视器115200 波特率在端口上开启 pyserial 监视如python -m serial.tools.miniterm PORT 115200应看到adaptive_ctrl标签的周期性 tick 日志源码位置 firmware/esp32-csi-node/main/adaptive_controller.cTAG即adaptive_ctrlcsi_collector: CSI cb #…: len128 …形式的 CSI 回调日志源码位于 firmware/esp32-csi-node/main/csi_collector.c打印帧号、长度、RSSI、信道。2. 汇聚端sensing server收包确认在目标主机上启动 UDP 汇聚服务确认能收到节点发来的帧cd v2 cargo run -p wifi-densepose-sensing-server只要--target-ip指向本机服务端应能看到来自节点的 UDP 帧。更多服务端运行模式训练、嵌入、建索引等可参考 plugins/ruview/skills/ruview-configure/SKILL.md。3. 故障排查速查症状常见原因处理WiFi 连不上SSID/密码错误用正确凭据重跑provision.py无 CSI 帧汇聚端 IP/端口不对核对--target-ip/--target-port是否指向运行中服务端跌倒误报多fall_thresh过低调高--fall-thresh高人流区域WASM 上传被拒签名校验开启开发环境用wasm_verify0或改用 Ed25519 签名九、延伸从单节点到 Mesh 与 Cognitum Seed多节点 MeshTDM两个及以上节点指向同一--target-ip汇聚端即可获得真实空间分辨率。每个节点通过--tdm-slot/--tdm-total分配时隙信道跳频由wifi-densepose-hardwarecrate 的v2/crates/wifi-densepose-hardware/src/esp32/协调跨视角融合见ruview-advanced-sensing技能。Cognitum Seed 集成ESP32 通过--seed-url/--seed-token/--zone把 CSI 流转发给 Seed用于持久化 RVF 记忆、环境 kNN 检索与 Ed25519 见证链--swarm-hb/--swarm-ingest控制心跳与向量摄入节奏。宿主侧可用node scripts/rf-scan.js --port 5006、node scripts/snn-csi-processor.js --port 5006镜像边缘模块逻辑做调参。十、总结/ruview-provision技能与 firmware/esp32-csi-node/provision.py 构成了 RuView 传感节点免重编译、按设备配置的运行时控制面一条命令即可完成 WiFi 凭据、UDP 汇聚端、节点 ID、信道策略、边缘处理分级、TDM 组网与 Seed 桥接的写入。配网前的关键决策是理解三组权衡固定信道 vs 跳频、MAC 过滤 vs 全捕获、边缘分级 0/1/2配网中的红线是 NVS 命名空间整段重写当前版本已通过每端口状态文件实现默认增量合并配网后的验证以串口adaptive_ctrl/csi_collector日志与汇聚端收包为准。更多运行时配置项sdkconfig 变体、sensing server 参数、边缘模块阈值可继续阅读 plugins/ruview/skills/ruview-configure/SKILL.md 与 firmware/esp32-csi-node/README.md。【免费下载链接】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），仅供参考