Skip to main content
Version: Next

用 EDK60 桥接 EDV163 挥手识别模组——手扫(挥手方向 + 距离触发)

一句话:一块 EDK60_VA 开发板 + 一颗烧了挥手识别固件(163_action_20260901)的 EDV163 模组, 不用 USB 转串口芯片、不用装驱动,把模组上报的一行文本(实测 40~43 ms 一行) (GESTURE: target=… x=… y=… z=… action=…)经原生 USB 实时送到浏览器, 页面上显示挥手方向大字 + 目标坐标 + 距离触发 + X-Z/X-Y 两个位置视图。

这套方案与之前两套(EDV11P 人数统计 / EDV163 水位)最不一样的一件事: 本方案没有厂商协议文档。格式、编码、容错策略全部是从厂商上位机源码 gesture_monitor.py(774 行)+ 同目录 README 逆推出来的。 本文每一处协议结论都标了源码行号;凡是源码没写、也没实测过的,本文一律写「待实测」,不猜。

:::warning ✅ 验证状态(读正文之前请先看这一块) 已上板跑通(2026-10-23):EDK60 桥 + EDV163 挥手固件,USB 直连浏览器与本机工具均可用。

本文里的「行率 / 坏行率 / 方向映射 / 动作轴映射 / 坐标范围 / 距离触发」已是实测值; 「点云帧占比 / ±3 极性 / target=0 时延 / 长时稳定性 / 浏览器像素级目检」仍未验证,如实标着「待实测」。 模组固件必须是 163_action_20260901 挥手识别版——水位版没有 GESTURE 行。

实测条件:2026-10-23,EDK60_VA V1.0 + 模组自报 EDV163_VB_ID0xFFFF_V101(设备 ID 未写入),115200 8N1, USB 直连;三次采集 25 s / 50 s / 75 s(570 / 1,322 / 1,826 行)。 :::

已实测(2026-10-23)仍未验证(待实测)
上板跑通:USB 直连浏览器 + 本机工具均可用0x4544 点云帧的真实存在与占比(三次采集 0 帧)
行率 24.3~26.5 行/秒(中位行间隔 40~43 ms)±3(靠近/远离)的出现频率与极性(三次采集从未出现)
坏行率 0.00%~0.35%(唯一坏行 = 模组开机 2 行 banner)target=1 → 0 的精确时延(未做专项计时)
action 四条码 -2 / -1 / 1 / 2 均实测出现;±3 未出现长时稳定性(最长 75 s,未做 30 min)
动作轴映射:±1 ↔ X 轴(水平)、2 ↔ Y 轴(垂直)浏览器像素级目检(1280×720 / 1920×1080;动画层已目检)
方向映射:现场目视核对通过(显示方向与实际挥手方向一致)—
坐标范围:x ∈ [−1.21, +0.20]、y ∈ [−0.28, +0.57]、z ∈ [0.06, 1.14] m—
距离触发:阈值 20 cm 时实测触发 12 次(z 小于 0.20 m 时)—
单次检测:一次挥手触发连续 6 行相同 action(约 0.23 s),随后回落 action=0—
维度现在的真实状态证据
固件demo radar_bridge_edv163_gesture(Kconfig 编号 5.4,工程共 19 个 demo)已实现;-fsyntax-only 10 个用例全绿(含断言反向验证 exit 1);2026-10-23 已上板跑通仓库内《EDV163 挥手识别透传桥固件实现说明》 + 上板抓包
网页gesture.html,90,641 字节单文件、零外链、可离线;在原 65 项自测基础上新增「挥手动画 + 锁定期」用例,网页自测 98/98仓库内《网页版工具自测报告》
工具tools/edv163_gesture_check.py --selftest → 8 个分节、110 项逐项对账全部 OK、退出码 0(2026-10-23 复跑确认);上板实测三次采集跑通仓库内《流校验测试计划》T-GS-05 + 上板记录
模组自报开机输出两行:EasyDetek 与 EDV163_VB_ID0xFFFF_V101(设备 ID = 0xFFFF,未写入;版本 V101)2026-10-23 上板抓包
固件合并包244,192 B / SHA256 2D1E122A9FC9B3FDC5549F714C7E12D738606D9FA22BE9A4080DF7B93FCFFF76,烧 0x0发布包 manifest.json
本次上板顺手修掉的缺陷首次上板 I (115) esp_image: segment 3: ... 混进 USB 流 → 根因 bootloader 阶段日志不受 CONFIG_LOG_DEFAULT_LEVEL 管;加 CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y 后复测通过上板抓包对比
本文数字的性质本文数字分三档并逐处标注:实测(标 2026-10-23)/ 已自测 / 源码推导;没有第四种—

所以请这样读这篇文档:

  1. 接线、烧录、协议、网页操作这几节可以照着做——H3 引脚、红灯、EN=IO14 是板上实测事实, 协议是对厂商源码逐行核对的结论,而行为面的关键数字已被 2026-10-23 上板实测背书(见上表)。
  2. 涉及「多少行、坏行多少、方向对不对、准不准」的结论已有实测值;仍然标着「待实测」的那几项是真的没测, 不要当成已验证(清单见附录 C)。
  3. 你要复现,第一步不是插模组,而是确认模组烧的是挥手识别固件(见第 2 节与附录 C): 水位版 / 二进制版固件不会输出 GESTURE: 文本行。

1. 你能做出什么​

1.1 做好之后你会看到什么​

把手放在雷达正前方 0.2~0.8 m 处挥手,浏览器里能得到四样东西:

界面元素内容
挥手动作大字「左挥手 / 右挥手 / 上挥手 / 下挥手 / 无挥手」,颜色随动作变化(与厂商界面同一套配色)
目标位置卡片x / y / z 三个坐标(单位米、3 位小数、带符号);target=0 时整组显示 — 并标「目标位置未就绪」
距离触发卡片「触发 / 未触发」大字 + 阈值输入(0~100 cm,默认 20.0);target=1 且 z 严格小于阈值才触发
两张位置图X-Z 俯视图(雷达在下方中心,z 向前 0~1 m)与 X-Y 正视图(x>0 在左、y>0 向上,±0.40 m)

外加一排诊断字段:行率(实测 24.3~26.5 行/秒)、有效行、坏行、跳过二进制帧、重同步次数、最后一行时间、收字节数, 以及 action 直方图(-2/-1/0/1/2 五行;±3 靠近/远离单独计数、不计入挥手方向)。

:::tip 关键预期管理 这套模组输出的是文本行,不是二进制帧协议。好处是「人能直接看懂、能 grep」, 代价是没有任何长度字段与校验——被污染后不会给你「校验失败」这种明确信号, 现场只表现为「挥手方向偶尔不显示」。所以第 6 节花了很大篇幅讲混流与洁净,那不是洁癖,是功能正确性。 :::

1.2 你会得到什么​

  1. 一条完整链路:EDV163(挥手固件)→(UART 115200 8N1)→ 开发板 →(原生 USB,免驱)→ 浏览器
  2. 实测确认的接线表(H3 引脚来自上板实测)
  3. 两种烧录路径(线上网页烧录 / 本地 idf.py)+ 一个「烧 0x0」的单文件合并固件
  4. 一个网页手势工具——完全没有写入路径(不取 port.writable、无 .write(), 因为厂商上位机本身只收不发(源码全文无 .write()
  5. 从源码逆推出来的协议全貌:6 条正则(含旧格式与 DBG: 兼容)、action 编码表(含 ±3)、 0x4544 二进制点云帧的整帧跳过算法(含「校验失败只丢 1 字节」这条关键容错)
  6. 站位与调参指引(推荐 0.2~0.8 m、正对、动作幅度)
  7. 三层排障法 + 三条专属判据(0 行 / 全是坏行 / 行率对但方向反)

2. 需要什么​

2.1 物料清单​

#项目型号 / 规格必备/可选说明
1开发板EDK60_VA V1.0(ESP32-C6-MINI-1-N4,4 MB Flash,无 PSRAM)必备板载 USB-C,无 USB 转串口芯片(走芯片原生 USB,免驱)
2雷达模组EDV163,烧「挥手识别」固件 163_action_20260901必备插在板子的 H3 排针上。见下方固件版本警告
3线缆USB-C 数据线必备必须能传数据;纯充电线会出现「灯亮但电脑认不到」
4PCWindows / macOS / Linux + Chrome / Edge 89+必备网页工具用 Web Serial,只在 Chromium 内核浏览器可用
5卷尺 / 地面标尺≥1 m可选(推荐)做 15 / 20 / 25 cm 三档触发对照时需要
6手机录像可选(推荐)挥 10 次左挥、10 次右挥……凭录像核对方向,比凭记忆靠谱

:::danger 必须用「挥手识别固件」的 EDV163 同一颗 EDV163 硬件可以烧不同固件,输出完全不同:

模组固件输出形态本方案能用吗
挥手识别版 163_action_20260901文本行 GESTURE: target=… x=… y=… z=… action=…(实测 40~43 ms 一行)能——本文用的就是它
水位 / 测距版(二进制)45 44 开头的二进制帧(op/type/TLV)不能:不会出现 GESTURE: 文本行
其它分支(ASCII 命令式等)#set / #get 一类文本命令与应答不能:没有 action 字段

拿到模组第一件事:用串口助手以文本模式看一眼有没有 GESTURE: 行。 如果看到的是满屏二进制乱码,说明这颗烧的是二进制固件,需要换固件(附录 C ①)。 :::

:::info 供电提示 EDV163 是低功耗模组(水位版规格为典型 11 mA 量级、综合 < 0.1 W),PC 的 USB-C 口足够, 不需要 DC-005、不需要外部适配器。 但本方案早期上板时阻塞点恰好出现在 USB 链路(板子 USB 掉线、设备管理器留幽灵设备; 2026-10-23 换环境后已跑通), 所以遇到枚举异常时优先怀疑线材 / USB 口 / 主机,而不是模组功耗(见第 9 节第①层)。 :::

2.2 软件环境​

软件本文涉及版本用途
ESP-IDFv6.1.0(target esp32c6)本地编译烧录(走预置合并固件则不需要)
Python3.x(用 py -3 启动器)跑流校验工具
pyserial3.x只有 --port 实时采集需要;--selftest / --file 不需要
Chrome / Edge89+网页手势工具(Web Serial)
Node.js20.x只有想在命令行复核 gesture.html 的页内自测时才需要

2.3 不需要的东西​

  • 不需要 USB 转串口模块(CH340 / CP2102 等)
  • 不需要 装任何驱动(原生 USB Serial/JTAG,设备管理器直接认成「USB 串行设备」,VID 0x303A)
  • 不需要 电平转换(模组是 3.3 V TTL UART,与 ESP32-C6 同电平)
  • 不需要 在固件里写协议解析(固件只搬字节;切行、跳二进制帧、action 映射、触发判定全在网页侧)
  • 不需要 任何「下发配置」的步骤——这条链路本身没有命令接口(厂商上位机源码里一个 .write( 都没有)

3. 接线​

3.1 先认清 H3 的丝印顺序(本链路最容易搞错的一处)​

板上有两个 8 pin 排针,同一物料、同一信号集合、顺序完全相反:

脚位(自上而下)12345678
H3(雷达插槽,用这个)RESARTGVPRES
H4(禁止插)RESPVGTRARES
  • 证据:SCH_EDK60_VA.pdf 文本对象逐脚还原 + 仓库内引脚定义文档 §二 的上板实测结论 「模组必须插 H3,H4 会导致电源与数据互扰」。
  • H3 的第 1、8 脚(RES)在 EDV163 模组上没有对应引脚(模组只有 P/V/G/T/R/A 六脚),保持空置。

3.2 信号表(本 demo 实际用到 4 个电气信号 + 2 个电源脚)​

信号EDK60 侧模组侧(H3 脚)方向本 demo 用不用
模组 TX → MCU RXIO4T(第 4 脚)模组 → MCU用:GESTURE: 数据入口,全靠这条线
模组 RX ← MCU TXIO5A(第 2 脚)MCU → 模组不用:本代模组无命令接口(固件的 USB→UART 通路保留但常态空闲)
雷达电源使能 ENIO14(高有效)—MCU → 电源用:上电后常驻高,运行期不碰
电源 / 地3.3V_RADAR / GNDV、P(6、7 脚)/ G(5 脚)—用:3.3 V 单电源,无需电平转换
橙色指示灯IO15(丝印 L)——不碰:只是普通指示灯,与雷达供电无关

3.3 为什么必须插 H3​

H3 的 T(第 4 脚)落在 IO4、A(第 2 脚)落在 IO5;H4 把顺序镜像过来, T 与雷达电源使能处在同一侧的网络关系上。插 H4 不会冒烟,但会出现 「红灯亮着、却一个字节都没有」或「偶发丢字节」这类最难查的现象。

认准丝印 H3,按 RES A R T G V P 的方向对齐。

:::warning 插拔纪律 禁止在 EN = 1(雷达已上电、红灯亮)时插拔模组——VCC/GND 上电顺序不可控,容易经 IO 反灌。 插拔前先断电,确认丝印 RADAR 红灯灭。 :::

3.4 上电自检:只看一个灯​

灯丝印含义能不能判断雷达供电
绿ON主板 3.3 V 正常不能
橙L(IO15 驱动)只是普通指示灯,与雷达电源无关不能(最容易误判的一个)
红RADAR直接挂在 3.3V_RADAR 轨上能——红灯亮 = 雷达已上电

电源使能是 IO14,高有效,且板上 LDO 的 EN 经 10 kΩ 下拉到地 → 上电默认是关的, 固件启动后主动拉高才给雷达供电(这个顺序是安全的:MCU 复位时雷达一定先掉电)。

① MCU 启动(主 3.3 V + USB 枚举稳定)
↓
② IO14 拉高 → LDO 使能 → 3.3V_RADAR 建立 → 丝印 RADAR 红灯亮
↓
③ 模组内部上电复位 / 自检(固件不延时等待:UART 缓冲已在收,等待只会白丢数据)
↓
④ 模组开始输出 GESTURE: 文本(**实测 40~43 ms 一行**,即 24.3~26.5 行/秒)

失败先查:

现象先查什么
一个灯都不亮USB 线是不是充电线;换 USB 口(台式机优先机箱后面);换一根线
绿灯亮、红灯不亮模组没插紧 / 插到了 H4 / 固件没把 IO14 拉高(确认烧的是 radar_bridge_edv163_gesture)
红灯亮、一个字节都没有进第 9 节第②层;首先怀疑波特率不是 115200,其次怀疑模组固件不是挥手版
端口在、点开报错 / 反复掉枚举这是早期上板遇到过的现象(USB 掉线留幽灵设备;2026-10-23 已跑通)→ 换线、换口、换主机

4. 烧录​

固件 demo 名:radar_bridge_edv163_gesture(Kconfig 里是 5.4,工程共 19 个 demo)。 它的全部工作就是:把 IO4 收到的字节原样写到 USB,把 USB 收到的字节原样写到 IO5。 不解析 GESTURE:、不切行、不跳过 0x4544 帧、不映射 action、不算触发、不打印任何日志字符。

4.1 路径①:线上烧录页(零基础,推荐)​

在 Chrome / Edge 里打开网页烧录页(Web Serial,需要 https 或 localhost):

⚡ 网页烧录页 · 挥手识别固件(EDV163)

这个页面内置的就是本节要用的那份合并固件(edk60_edv163_gesture.bin,烧 0x0), 插上 USB 点几下就能烧完,不需要装 ESP-IDF。

ℹ️ 若打开是 404,说明这三份静态资源(flash.html、gesture.html、edk60_edv163_gesture.bin) 还没部署到站点——此时走 4.2(本地编译)或 4.3(合并固件 + esptool)即可。

操作顺序与验证点(与之前两套同一套交互):

步骤你会看到你要做什么 / 期望结果
1「连接设备」按钮点击 → 浏览器弹出串口设备列表
2列表里有一项带 USB / JTAG 字样选中它 → 连接
3进度条什么都不做,等 10~20 秒
4「完成 / Done」成功
5—拔掉 USB,等 2 秒,再插回(让新固件重新启动)
6板载丝印 RADAR 红灯亮上电成功,进第 5 节看数据

失败先查:设备列表是空的 → 换数据线(最常见)→ 换 USB 口 → 按住 BOOT 再插 USB 后松开 → 关掉其它占用串口的软件。

4.2 路径②:本地编译烧录(开发者)​

# ① 激活 ESP-IDF(每次新开终端都要做一次)
. C:\Espressif\tools\Microsoft.v6.1.PowerShell_profile.ps1

# ② 进工程根(切到你本机的 ed_edk60_demos 目录)
cd C:\path\to\ed_edk60_demos

# ③ 选 demo + 编译(build_all.ps1 会自动管理该 demo 的 sdkconfig)
.\build_all.ps1 -Demo radar_bridge_edv163_gesture

radar_bridge_edv163_gesture 已在 build_all.ps1 的 $DemoMap 里注册(-List 会打印「共 19 个」)。 如果你想完全用 idf.py,就是两条命令(先在 idf.py menuconfig → EDK60 Demo → 选 5.4 radar_bridge_edv163_gesture 保存):

idf.py -B build-radar_bridge_edv163_gesture build
idf.py -B build-radar_bridge_edv163_gesture -p COM8 flash

期望现象:

检查点期望输出
单独构建成功,0 error / 0 warning(-Werror 下 10 个 -fsyntax-only 用例已全绿)
全量回归.\build_all.ps1 -Size → 19/19 通过
关键宏生效build-radar_bridge_edv163_gesture\config\sdkconfig.h 里有 CONFIG_APP_EDK60_DEMO_RADAR_BRIDGE_EDV163_GESTURE 与 CONFIG_APP_EDK60_EDV163_GESTURE_BAUD=115200
波特率不是「上一版」若看到 256000(水位)或 921600(人数统计),说明改错了 demo

:::danger 两条红线(有编译期断言兜着,都只对 5.4 生效)

  1. 不要用 CONFIG_ESP_CONSOLE_SECONDARY_NONE=y 来「让 USB 上只有数据」—— 实测(2026-10-15)会让 C6 启动卡死、USB 不枚举、必须断电重插。正确做法是保留控制台但不产生字符。
  2. 不要把波特率调高却把 APP_EDK60_EDV163_GESTURE_UART_RX_BUF 留在 1024 B: 源码里有断言 UART_RX_BUF×1000÷(BAUD/10) ≥ 120 ms,不满足构建直接失败并给出算式 (默认 16384 B ÷ 11520 B/s = 1422 ms,与 60 ms 的 USB 写预算相比余量 23.7×)。 在 115200 下 1024 B 只有 88 ms < 120 ms ⇒ 直接构建失败,最小可用值是 2048 B(177 ms)。 :::

为什么这个小 demo 里有一堆「静默」讲究:前两套方案里日志污染还只是让上位机跳过几帧(二进制协议有帧头可重新同步); 本方案里一条 printf 会直接吃掉文本行的完整性:多一个字符该行就匹配不上,少一个字符就和下一行粘连, 而文本协议没有任何校验能发现这种错误。 做法是五道保险 + 一道门禁:日志级别编译期消失、启动横幅/引脚表关闭、源码零 printf、 运行期 esp_log_level_set("*", ESP_LOG_NONE),再加编译期分派表里整块跳过横幅—— 以及第五道(2026-10-23 上板实测补上的)CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y: 首次上板时 USB 流里混进了 I (115) esp_image: segment 3: ... 这样的行,被解析器计为坏行, 根因是 bootloader 阶段的日志不受 CONFIG_LOG_DEFAULT_LEVEL 管,前四道全都拦不住它; 补上这一项后复测通过(坏行率回到 0.00%~0.35%,残留的 2 行来自模组开机 banner,属模组侧,见第 10 节第 18 条)。

4.3 合并固件:一个文件,烧 0x0​

不想装工具链、又暂时没有线上烧录页时,用这份「单文件」固件:

⬇ 下载合并固件 edk60_edv163_gesture.bin

项值
文件edk60_edv163_gesture.bin(即工程里 idf.py merge-bin 的产物,原名 merged-binary.bin)
体积244,192 B
SHA2562D1E122A9FC9B3FDC5549F714C7E12D738606D9FA22BE9A4080DF7B93FCFFF76
烧录偏移0x0(文件已含 bootloader + 分区表 + app,所以只有一个地址)

烧法(二选一):

  • Flash Download Tool(乐鑫官方 GUI):选 ESP32-C6;文件填 edk60_edv163_gesture.bin,地址 0x0; 端口选那个「USB 串行设备」,BAUD 460800 → START。工具版本必须 ≥ 3.9.5(旧版不认 ESP32-C6)。
  • 命令行(esptool,随 IDF 一起装):
esptool --chip esp32c6 -p COM8 -b 460800 write_flash 0x0 edk60_edv163_gesture.bin

:::warning 先自己核一次哈希 上表的体积与 SHA256 已回填(不再是占位),但请仍以你手上这份文件算出的哈希为准: Get-FileHash .\edk60_edv163_gesture.bin -Algorithm SHA256。 不要拿「别人截图上的一串哈希」当依据。 若看到让你填三个文件、三个地址(bootloader / 分区表 / app 分开烧)的说明,那是没合并的产物,不适用于本文件。 :::

4.4 烧完的验证点​

检查点期望状态
拔插一次 USB红灯仍亮;USB 枚举成「USB 串行设备」,浏览器与本机工具都能直连已实测(2026-10-23 上板跑通,USB 直连浏览器与本机工具均可用)
用串口助手(文本模式)看实测 24.3~26.5 行/秒 GESTURE: target=… 文本;ESP 侧日志 0 行已实测(25 s/570 行、50 s/1,322 行、75 s/1,826 行三次采集;模组开机 2 行 banner 见第 10 节第 18 条)
用十六进制模式看混有 45 44 开头的二进制帧(正常数据,必须原样到达)已实测(负结果):三次采集 0 帧(第 10 节第 3 条与 U1)
反过来(本 demo 的纪律)固件不会主动发任何字节;上位机也不会发(链路只读)已自测(固件源码零写入路径)

5. 看数据​

5.1 网页版手势演示(本方案唯一的图形上位机)​

👋 网页手势演示(EDV163 手扫)

  • 单文件 HTML,用 Chrome / Edge 打开即可,不用装任何软件;
  • 也可以把这一页另存为本地文件,在保存目录起一个静态服务(py -3 -m http.server 8771), 然后访问 http://127.0.0.1:8771/gesture.html;
  • 整个页面无外链、不写 localStorage / IndexedDB / Cookie,刷新即清空。

操作顺序与验证点:

步骤你会看到你要做什么 / 期望结果
1顶栏「连接串口」按钮点击 → 浏览器弹出串口设备列表
2列表里有一项带 USB / JTAG 字样选中它 → 连接(板上没有 CH340/CP2102,只有这一个)
3右列「连接参数」波特率下拉选 115200(默认就是 115200;USB CDC 本身不受波特率限制,填一致只为与线速对齐)
4状态条连接状态变绿;行率实测 24.3~26.5 行/秒(判据 24.3 ±20% → 19.4~29.2);「最后一行时间」约每 40~43 ms 跳一次
5三张卡片手在雷达前挥手 → 「挥手动作」大字在左/右/上/下/无之间变化;坐标开始跳动
6两张位置图红点 + 十字线跟随目标;目标离开视野 → 两图显示「目标位置未就绪」
7距离触发卡片手从 0.3 m 慢慢靠近到 0.15 m → 文字从「未触发」(灰)变「触发」(绿)

它是「完全只读」的(比水位版更彻底):

行为说明
连接后自动发的字节0 个。源码里没有 .write(,也没有 getWriter() / port.writable
会不会改你的设备不会。这条链路本来就没有命令接口(厂商上位机也只收不发)
调试 APIObject.freeze(window.GESTURE):将来若有人往里挂「发字节」的方法,严格模式下直接 TypeError
本地存储 / 网络无 localStorage、无 fetch、无外链资源

不接硬件也能先确认渲染管线:勾「模拟演示(无需硬件)」——按网页内部节拍(原 200 ms,与真机行率无关)合成一段真实字节流 (含合法 0x4544 帧与故意改坏校验的帧),回灌与串口完全相同的解析器,不是「直接改界面」的假演示。 模拟剧本里 z 周期约 7 s 穿过 20 cm 阈值,所以触发卡片会真的在「触发/未触发」之间跳。

实测现象(2026-10-23 上板,25 s / 50 s / 75 s 三次采集):

观察点实测(或期望)异常含义
行率实测 24.3~26.5 行/秒,中位行间隔 40~43 ms远低于 19.4 行/秒:波特率不对 / 固件节拍不同 / 丢行
坏行实测 0.00%~0.35%;唯一的坏行是模组开机那 2 行 banner持续增长 → 流里混了非协议文本(固件 printf?),见第 9 节第②层
跳过二进制帧实测 0 帧(三次采集均无 0x4544)→ 该分支目前是防御性代码若出现且重同步同时暴涨 → 帧格式/长度域理解有偏差
重同步0 或很小与「跳过二进制帧」同量级暴涨 → 帧格式/长度域理解有偏差
遥测超时不断流时永不出现;断流 1.5 s 后出现,坐标变 —出现即断流(USB 掉线会直接表现成这个)

:::caution 同一时刻只能有一个程序占用这个 COM 口 网页工具与命令行流校验脚本同时跑会互相抢端口。演示用网页,采集用工具。 :::

5.2 命令行流校验工具(给出 PASS/FAIL 结论)​

网页工具是「看」,这个工具是「量化 + 裁定」:它把同一条字节流做字节守恒统计,输出 P0~P9 九条判据与退出码。

cd C:\path\to\ed_edk60_demos

# ① 准入:无硬件自测(1 分钟,证明工具本身没写错;不需要 pyserial)
py -3 tools\edv163_gesture_check.py --selftest

# ② 主证据:10 分钟持续挥手(需要 pyserial;工具只读,不发任何字节)
py -3 tools\edv163_gesture_check.py --port COM6 --baud 115200 --duration 600 `
--expect-hand present --threshold-cm 20 --save-raw logs\edv163-gesture\wave10.bin `
--csv logs\edv163-gesture\wave10_lines.csv --raw-dump

# ③ 离线复算(不接硬件、不需要 pyserial)
py -3 tools\edv163_gesture_check.py --file logs\edv163-gesture\wave10.bin --duration 600 --expect-hand present
退出码含义
0PASS(--selftest 时 = 110 项逐项对账全部通过)
1FAIL
2参数或环境错误(阈值越界、文件不存在、串口打不开、缺 pyserial)

5.3 挥手动画与锁定期(2026-10-23 新增)​

网页在「挥手动作大字」之外加了一层手掌滑动动画,并用「动画锁定期」保证一次检测只播一次。 动画层已用无头浏览器按四个方向逐一截图目检(工程仓 docs/project/edv163-gesture/figures/ 下的 anim-left-right.png、anim-right-left.png、anim-up-down.png、anim-down-up.png)。

项规则
四个方向的动画左挥 → 掌从左到右;右挥 → 右到左;上挥 → 下到上;下挥 → 上到下
时长2.5 s(含最后 300 ms 淡出)
动画期间(锁定期)的展示冻结动作展示:不重启动画、不切换动作名
锁定期内解析与统计照常进行:行率 / 有效行 / 坏行 / 坐标 / 日志 / 直方图全部继续累计,一帧不丢
锁定期内被抑制的动作单独计数,页面显示「动画期忽略 N」
同一次检测的去重相邻行间隔 ≤300 ms 且 action 同值 ⇒ 视为同一次检测的残留帧,不重复播放
无障碍prefers-reduced-motion 时退化为静态手掌 + 800 ms 淡入淡出,不做位移动画
自测网页自测 98/98(含动画与锁定期用例)

为什么必须有锁定期:实测一次挥手会触发连续 6 行相同 action(约 0.23 s),随后回落到 action=0。 若每一行都驱动一次动画,一次挥手会被播成 6 次、界面抖成幻灯片。 锁定期把「一次检测」压成「一次动画」,同时不牺牲统计——这正是它只冻结「展示层」、不冻结「解析层」的原因。


6. 协议要点(本文最重要的一章)​

这一节是全文唯一的事实来源。固件一行协议代码都没有——切行、跳二进制帧、action 映射、触发判定, 全部在网页侧。因为没有厂商协议文档,下面每一条都标了厂商上位机源码 gesture_monitor.py(774 行)的行号。 换一代固件就可能改格式,届时以新固件对应的源码为准,不要相信任何二手转述(包括本文)。

6.1 文本行格式(唯一主路径)​

固件输出节拍实测为 4043 ms 一行(24.326.5 行/秒)。 厂商源码模块 docstring 第 5-7 行与 README 第 61 行写的是「每 200 ms 一行(5 行/秒)」, 与实测不符,一律以实测为准:

GESTURE: target=1 x=0.012 y=-0.034 z=0.156 action=1
字段类型含义源码位置
target0 或 11 = 目标位置有效;0 = 10 帧位置窗尚未形成,此时 x/y/z 全为 0第 69-70 行;README 第 69 行
x米(float)目标横向坐标第 64 行
y米(float)目标纵向坐标第 64 行
z米(float)目标前向距离(触发判定与两张图都靠它)第 64 行
action整数(-2..2,另见 ±3)挥手结果编码第 65 行;第 123 行夹取

数字口径(源码第 61 行 NUMBER,网页与工具逐字照抄):

NUM = [-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?

即:普通小数、+ 前缀、前导小数点(.5)、科学计数法(1.2e-2 / 3.4E-2)全部接受。

正式行的正则(源码第 62-66 行,锚点 ^ 与 $ 都保留):

^GESTURE:\s*target=(?P<target>[01])\s+x=(?P<x>NUM)\s+y=(?P<y>NUM)\s+z=(?P<z>NUM)\s+action=(?P<action>-?\d+)\s*$

解析前对整行做 trim()(源码第 115 行 line.strip());行尾允许 \r(先剥掉所有 \r)。

6.2 action 编码表(源码第 104-110 行,逐字照抄)​

action显示名配色网页行为
-2下挥手#0284c7动作大字 + 直方图
-1右挥手#2563eb动作大字 + 直方图
0无挥手#64748b动作大字 + 直方图
1左挥手#16a34a动作大字 + 直方图
2上挥手#ea580c动作大字 + 直方图
±3靠近 / 远离—(界面不显示)只进内部计数,动作大字回落为「无挥手」
其它(理论上不出现)未知挥手#b91c1c与源码第 661-663 行的兜底一致

关于 ±3(靠近/远离)——三件事必须讲清:

  1. 它不是挥手方向。厂商 README 第 71 行明确写「action 编码只用于串口传输,不在图形界面显示」, 且界面「不显示靠近/远离结果」(README 第 11 行)。
  2. 源码对正式行会把 ±3 抹成 0:第 123 行 wave_action = action if -2 <= action <= 2 else 0, 并把 depth_action 固定为 0 —— 即厂商在正式行上丢掉了 ±3 的信息。 本方案的网页保留同一显示语义(动作大字落 0),但额外记录 rawAction / depthAction, 以便统计里出现「靠近 N · 远离 M」的小字。这是增量信息,不改变任何显示判定。
  3. ±3 的极性仍是推断:按「z 减小 = 靠近」定为 +3 靠近 / −3 远离,源码里没有物理验证; 2026-10-23 三次采集里 ±3 一次都没出现(U3,仍待实测)。

:::tip action 符号约定已实测核对(2026-10-23) 左=1、右=−1、上=2、下=−2 这套映射,已通过现场目视核对——页面显示方向与实际挥手方向一致。 动作轴映射同样实测确认:±1 ↔ X 轴(水平)、2 ↔ Y 轴(垂直)(按每段 Δx/Δy 统计)。 实测里 -2 / -1 / 1 / 2 四条码全部出现过,±3(靠近/远离)一次都没出现。

若将来换模组固件后出现四个方向全反,那是固件/协议层的问题,不要在网页端改映射—— 改了会与厂商界面语义分叉,还会让后面所有对照实验失去意义(见第 9 节判据③)。 :::

6.3 流里还混着 0x4544 二进制点云帧(必须整帧跳过)​

厂商模块 docstring 第 9-10 行、README 第 73 行:串口里同时存在文本行与 0x4544 点云二进制帧。 若只按 \n 切行,二进制载荷里的任意 0x0A 都会被当成行尾,把后面的 GESTURE 行撕碎。

帧格式(源码第 178-236 行):

偏移 0 1 : 0x45 0x44 ← 帧头(ASCII "ED")
偏移 2 3 : 长度大端 (total) ← 含帧头与校验字节的总长,合法 11~4096
偏移 4 .. total-2: 载荷
偏移 total-1 : 校验 = sum(前面 total-1 字节) & 0xFF

常量:MIN_BINARY_FRAME = 11、MAX_BINARY_FRAME = 4096、MAX_TEXT_BUFFER = 16384(第 187-189 行)。

跳过算法(源码 MixedStreamParser.feed,第 194-236 行;网页与工具逐判定照抄):

每一轮循环取两个位置:headerAt = 缓冲里第一个 45 44;newlineAt = 缓冲里第一个 0x0A

循环 while 缓冲非空:
① newlineAt ≥ 0 且 (headerAt < 0 或 newlineAt < headerAt):
取 [0, newlineAt) 为一整行,去掉行尾所有 \r,消费到 newlineAt+1;非空则交付为一条文本行
② 否则 headerAt ≥ 0:
先把 headerAt 之前的字节当噪声丢掉
不足 4 字节 → 等下一批
total = buf[2]<<8 | buf[3]
total 不在 [11,4096] → 丢 1 字节、重同步
不足 total 字节 → 等下一批
sum(buf[0..total-2]) & 0xFF ≠ buf[total-1] → 丢 1 字节、重同步
否则:整帧 total 字节丢弃,不参与文本解析
③ 既无帧头也无换行:
缓冲超过 16384 字节则只保留尾部 16384 字节;退出等下一批

为什么「校验失败只丢 1 字节」而不是整帧跳过:源码 docstring(第 178-183 行)写得很明确—— 「疑似帧头但校验失败时仅丢弃一个字节重新同步,避免错误长度吞掉后续 GESTURE 文本」。 这条细节是本协议最容易被实现错的地方:如果按 total 整段跳过,一个假帧头就会把后面几秒的数据一起吃光。

本方案唯一一处功能性增强(网页侧,正则一个字都没改):校验失败的帧丢 1 字节后,残留字节会粘在下一行前面 (形如 44 00 0E …GESTURE: target=1 …)。厂商实现里这一行因 ^GESTURE: 锚点直接失败、这行就废了。 网页在整行匹配失败时,若行内出现 GESTURE: / DBG: 前缀且下标大于 0,就从该下标处再匹配一次: 成功则照常驱动界面并记 trimmedLines,失败才记坏行。前缀必须真实存在、且前缀之后必须完整匹配正则, 所以它不会从垃圾里造出数据。

6.4 为什么「文本协议」比二进制协议更脆弱​

前两套方案的流是纯二进制帧,帧头 0x4544 自带同步:桥上多吐一两个字符,上位机最多丢一帧就能重新对上, 属局部可恢复。本方案的流是「文本行 + 偶发二进制帧」,脆弱性完全不同:

#事实(来自厂商源码 / 实现)如果桥上或工具里做一点点「顺手处理」会怎样
①文本行没有长度字段、也没有校验;上位机的锚点是行首 ^GESTURE: 与行尾 \n多插一个字符(哪怕只是 \r 或空格)⇒ 该行匹配失败;少一个字符 ⇒ 与后续字符粘成一行。没有任何校验能发现这种错误
②解析器遇到认不出的行直接返回 None(静默丢弃)一旦被污染,现场只会看到「挥手方向偶尔不显示」,绝不会看到「校验失败」这种明确信号——最难查的一类故障
③厂商的切流规则是「找 \n 与 0x4544 谁先出现」+「长度范围 11~4096」+「累加校验」+「校验失败只丢 1 字节」四件事一起做桥上若「顺手过滤 0x4544 帧」:文本里出现该字节序列无法与真帧头区分;载荷里也常有 0x4544,删掉的是真数据;而且这四条规则合起来已经是一个完整解析器,搬进固件等于协议知识复制两份,两份必然漂移
④模组固件可升级(水位 256000 二进制 → 挥手 115200 文本,就是一次真实换型)桥上开始「理解」后,模组换固件就必须连带改桥、重烧、重新验证。而现在桥只搬字节,模组换固件不需要动 ESP32——本次换型只改了波特率一行宏

设计铁律:桥只允许改变「字节到达的时刻」,不允许改变「字节本身」。 任何「顺手做个文本处理」的念头都必须回到这一条上否掉。

由此推出洁净要求升级:前几套方案里「日志污染」只是让上位机跳过几帧; 本方案里它直接吃掉文本行的完整性。所以固件侧必须零字符输出, 而工具侧只能检测污染、不能预防(坏行率 / 重同步次数 / 垃圾段里的日志特征串)。

6.5 兼容的旧格式(读得到就行,不要当成主路径)​

源码第 69-89 行还有五条兼容正则,网页与工具都实现了,匹配顺序与源码 parse_telemetry_line(第 112-175 行)一致: GESTURE: … wave=N depth=N(上一版双通道)、以及四种 DBG: 行(target=1 带 pos_m=( x y z )、 target=0 不带坐标,各自又有 wave/depth 与 action [lock=M] 两个变体)。

这五条在当前固件上可能全是死代码(未确认)。看到它们出现就说明模组在打调试行—— 那本身是个信号(调试行也占带宽、也可能被弄脏),记下来,别当常态。

:::note lock=N(动作锁)本方案不显示 与厂商界面一致(README 第 11 行明确「界面不显示内部动作编码、动作锁状态」)。 如果产品需要,应作为一个只读小标签后加,而不是改解析逻辑。 :::

6.6 位置语义(两张图照着厂商抄,不要「想当然」)​

源码 TargetPositionPlot(第 239-349 行)+ README 第 84-88 行:

图量程映射关键语义
X-Z 俯视图X_LIMIT = 0.40 m、Z_MAX = 1.00 mpx = cx − (x/0.40)·(W/2−12);py = bottom − (z/1.00)·(bottom−top)雷达在下方中心,z 向前(图上向上)
X-Y 正视图X_LIMIT = 0.40 m、Y_LIMIT = 0.40 mpx = cx − (x/0.40)·(W/2−12);py = cy − (y/0.40)·(h/2)中心十字 = 雷达原点;y>0 向上

最反直觉的一条:雷达坐标 x>0 显示在图的左侧(源码第 306 行注释、第 342 与 347 行的坐标变换; README 第 86-87 行同样写明)。所有「目标往右边移动,红点应该往右走」的直觉在这里都是错的——照厂商语义实现,不要改。

  • 越界一律 clamp 到 ±1(源码第 268-270 行)。
  • 目标标记 = 红点 + 十字线 + 坐标文字(源码第 283-290 行;标签两位小数)。
  • 无目标时显示「目标位置未就绪」(源码第 335-338 行)。

6.7 距离触发(一行判定)​

源码第 681-712 行:

阈值输入 cm ──(0.0~100.0,默认 20.0)──► 阈值(米) = cm × 0.01
触发 = (阈值合法) 且 (target=1) 且 (z < 阈值米) ← 严格小于,等于不触发
规则源码位置网页实现
输入范围 0.0~100.0 cm、默认 20.0第 373 行、第 518-527 行三个输入框(顶栏 / 触发卡片 / 右列)共用同一份状态
cm → m 换算第 688 行同上
非数字 → 回退默认 20.0第 693-695 行normalizeThreshold()
越界 → 夹到 0~100第 697 行同上(150 → 100、−5 → 0)
z 严格小于阈值第 708-710 行自测钉死:z = 0.200、阈值 20 cm 时不触发
显示一位小数第 698 行三个输入框都写回 toFixed(1)

:::note 一处有意的视觉偏离 厂商触发时用红色 #dc2626,本方案用绿色 #15803d(任务书要求「触发=绿 / 未触发=灰」)。 action 配色、位置图语义、阈值口径都没有偏离,只此一处。 :::

6.8 一次典型的「从字节到界面」流程​

串口字节流: [45 44 00 11 …(完整点云帧)…] "GESTURE: target=1 x=0.012 y=-0.034 z=0.156 action=1\r\n"
│
├─ 第 1 层:MixedStreamParser(对应源码 194-236 行)
│ 见到 45 44 + 长度合法 + 校验通过 → 整帧丢弃(计「跳过二进制帧」)
│ 见到 \n → 切出一行文本并交付
│
├─ 第 2 层:6 条正则按序匹配(对应源码 112-175 行)
│ 命中正式行 → target=1 / x=0.012 / y=-0.034 / z=0.156 / action=1 → 左挥手
│ 都不命中 → 坏行 +1(正常应恒为 0)
│
├─ 第 3 层:触发判定(对应源码 701-712 行)
│ 阈值 20 cm = 0.20 m;z = 0.156 < 0.20 → 触发
│
└─ 第 4 层:渲染
动作大字「左挥手」/ 坐标 +0.012 −0.034 +0.156 / 触发(绿)
X-Z 俯视:z 0.156 → 偏下;x +0.012 → 略偏左(x>0 在左)

7. 站位与调参​

7.1 推荐站位(决定「能不能识别到」的第一因素)​

项建议理由
距离 z0.2 ~ 0.8 m挥手识别依赖点云的运动轨迹;太远点云稀、太近容易出视场。厂商界面量程是 z 0~1.00 m
角度站/坐在雷达正前方,手掌大致朝向模组x/y 显示量程只有 ±0.40 m,偏太多就出图
动作幅度手掌整臂水平/垂直划过 20~30 cm,速度均匀,别只抖手腕识别的是运动方向;幅度太小容易被判「无挥手」
节奏每次挥手间隔 1~2 s,挥完停一下让位置窗(10 帧)重新形成,便于逐次核对
环境1 m 内不要有持续晃动的大反射面(风扇、窗帘)会产生杂点,干扰 target

7.2 用「距离触发」卡片判断自己在不在有效区(不用卷尺的土办法)​

步骤操作期望
1手伸到雷达前约 0.3 m,停住target=1,z ≈ 0.30,卡片显示「未触发」(阈值 20 cm)
2手慢慢靠近到约 0.15 m卡片变「触发」(绿),z 读数同步变小
3把手退回到 0.4 m回到「未触发」
4把手拿开(离开视野)target 变 0,坐标全变 —,两图都显示「目标位置未就绪」

四步都对 ⇒ 你的站位、z 读数、触发逻辑三件事同时被验证了。 第 4 步不对(一直 target=1 且坐标乱跳)⇒ 视野里有静止反射物,先清场。

有卷尺时做严格版:地面标 15 / 20 / 25 cm 三条线,每档停不少于 5 s 各 3 轮, 逐行核对「z 严格小于阈值才触发」,并用 --threshold-cm 18 / 22 复算做灵敏度对照。

7.3 target=0 是什么意思(不要当成故障)​

target=0 = 10 帧位置窗尚未形成(README 第 69 行),此时 x/y/z 全为 0。 典型出现在:刚上电、手刚进视野、手离开视野、动作太快导致轨迹断帧。

  • 网页在 target=0 时把坐标显示成 — 并标「目标位置未就绪」,不显示 0.000(显示 0 会被误读成「目标就在原点」)。
  • target=0 时不参与触发判定(即使阈值调很大也不会触发)。
  • 另外网页有一条遥测超时兜底:距最后一条有效行超过 1.5 s(厂商是 1.0 s)判「遥测超时」, 坐标置 —、触发置「未触发」、两图回「目标位置未就绪」。 1.5 s 这个参数本次不动:按厂商 README 的 200 ms/行,1.0 s 只容 5 行; 按实测 40~43 ms/行推算,1.5 s 约为 35~38 行余量(推算值),偶发丢几行不会再闪「超时」。

7.4 想改参数时改哪里​

想改的东西改哪里注意
距离触发阈值网页上直接改(三个输入框任一,0~100 cm)只影响显示判定,不影响雷达;这是唯一天然可调的参数
波特率固件 APP_EDK60_EDV163_GESTURE_BAUD(默认 115200)+ 网页下拉两边必须一致;改高要同步加大 UART_RX_BUF(否则编译期断言直接失败)
行率(实测 40~43 ms/行)改不了:这是模组固件行为,没有命令接口桥只能透传,不能调速(这也是「只读」的代价)
action 映射不要改(见 6.2 与第 9 节判据③)与厂商语义分叉,后续对照实验全部失效
超时时间 / 日志行数上限网页 CFG 常量(staleMs、logMaxLines)观感/内存参数,改完刷新即生效

8. 验证清单​

从插模组到看到挥手方向,逐项打勾。每一项都标了状态: 已实测 = 2026-10-23 在真实 EDK60 + 挥手固件模组上跑过; 已自测 = 无硬件验证通过; 待实测 = 仍未验证(清单见本文开头的验证状态块与附录 C)。

8.1 环境与链路​

#步骤期望现象状态✅
1确认模组是挥手识别固件:串口助手文本模式能看到 GESTURE: 行实测 24.3~26.5 行/秒文本;开机两行 banner 为 EasyDetek / EDV163_VB_ID0xFFFF_V101已实测 ✅☑
2模组插 H3(RES A R T G V P 方向),USB-C 连 PC绿灯 ON 常亮已实测 ✅☑
3丝印 RADAR 红灯亮亮(= IO14 拉高、3.3V_RADAR 建立)已实测 ✅☑
4设备管理器「USB 串行设备 (COMx)」,VID 0x303A;不出现幽灵设备、不反复掉枚举已实测 ✅(USB 直连浏览器与本机工具均可用)☑
5烧录固件(4.1 / 4.2 / 4.3)Hash of data verified;烧 0x0 时体积见 manifest.json已确认(合并包 244,192 B / SHA256 2D1E122A9FC9B3FDC5549F714C7E12D738606D9FA22BE9A4080DF7B93FCFFF76,烧 0x0;本次上板用的是本地构建产物)☐
6固件规格自测-fsyntax-only 10 用例全绿(含断言反向验证 exit 1)已自测 ✅☐
7流校验工具准入--selftest → 110 项逐项对账全 OK、退出码 0已自测 ✅(2026-10-23 复跑确认)☐
8网页页内自测点「运行帧解析自测」→ 自测结果:13/13 通过已自测 ✅(桩环境 98/98,含动画与锁定期用例)☐

8.2 流完整性(本方案的验收核心,2026-10-23 已实测前 4 条)​

#判据阈值状态
9有效 GESTURE 行数(P0 前提)≥ 1(= 0 时整份采集无效)已实测 ✅ 570 / 1,322 / 1,826 行
10文本行率(P1)24.3 ±20% → 19.4~29.2 行/秒(原按 README 假设的 5.0 ±20% 已作废)已实测 ✅ 24.3~26.5 行/秒
11坏行率(P2)< 1%(实测 0.00%~0.35%,唯一坏行 = 模组开机 2 行 banner)已实测 ✅
12二进制帧校验通过率(P3)= 100%(纯文本流记 N/A)已实测 ✅ 三次采集 0 帧 → 记 N/A
13长度非法帧数(P4)= 0已实测 ✅ 无二进制帧,0
14行间隔超过 1 s 的空档次数(P5)= 0(40~43 ms/行 下等于连丢约 23~25 行)待实测(未单独统计空档次数)
15字节守恒:收字节 = 文本行字节 + 帧跳过字节 + 无法归属字节差额 = 0待实测(坏行只有开机 2 行,但工具差额未单独记录)

本次实测顺带修正了两处判据口径:① 行率判据从 README 假设的「5.0 ±20%」改为 24.3 ±20%; ② 坐标护栏从 ±1.00 m 放宽到 ±1.50 m(实测 x 到 −1.21 m,原护栏会把正常数据判成 FAIL)。

8.3 功能与语义(方向/轴映射/坐标/触发已实测,时延与目检待实测)​

#检查期望状态
16向左挥 10 次每次都显示「左挥手」,计数 = 10/10已实测 ✅(现场目视核对通过)
17向右挥 / 向上挥 / 向下挥 各 10 次分别「右挥手」/「上挥手」/「下挥手」已实测 ✅(-2 / -1 / 1 / 2 四条码均出现)
18停手 3 s回「无挥手」(灰)已实测 ✅(单次检测报文结束后回落到 action=0)
19手掌沿 Z 轴靠近/远离(不是挥手)动作大字不变(仍「无挥手」),「靠近/远离」小字计数增长待实测(U3:三次采集 ±3 从未出现)
20直方图-2/-1/0/1/2 五行计数与实际次数对得上;±3 两行不在挥手方向里已实测 ✅(±3 两行均为 0)
21目标位置有人进检测区 → 三坐标跳动,tag 变 target=1;离开 → 两图「目标位置未就绪」已实测 ✅ 坐标范围 x ∈ [−1.21, +0.20]、y ∈ [−0.28, +0.57]、z ∈ [0.06, 1.14] m(U4 时延仍待实测)
22X-Z 俯视图方向目标往雷达右侧移动 → 红点向图左移动(x>0 在左);z 变大红点上移已实测 ✅(±1 ↔ X 轴,按每段 Δx 统计)
23X-Y 正视图方向手抬高 → 红点上移(y>0);手向左 → 红点向左已实测 ✅(2 ↔ Y 轴,按每段 Δy 统计)
24距离触发(阈值 20 cm)手停 0.30 m → 未触发;前移到 0.15 m → 触发(绿);退回 → 未触发已实测 ✅(z 小于 0.20 m 时触发 12 次)
25阈值边界z 恰好等于阈值时不触发已自测 ✅
26阈值归一化150 → 100、−5 → 0、空/non-numeric → 回退 20.0,三框同步已自测 ✅(5/5)
27只读不变量连接后发出字节 = 0;无 getWriter / .write( / port.writable已自测 ✅(30/30 + 页内只读断言)
28浏览器目检(1280×720 / 1920×1080)整页无纵向滚动、顶栏吸顶、两张图不被压扁、日志可折叠部分:动画层已目检(无头浏览器四方向截图,工程仓 docs/project/edv163-gesture/figures/anim-*.png);整页像素级目检仍待做
29挥手动画与锁定期四方向动画正确、2.5 s(含 300 ms 淡出)、锁定期只冻结展示不冻结统计、动画期忽略计数、reduced-motion 降级已自测 ✅(网页自测 98/98)

:::tip 第 1015 项是本方案的验收标准 它们由 tools\edv163_gesture_check.py 输出的 JSON checks[] 与退出码直接给出。 2026-10-23 已实测 913 项;14、15 仍无实测数值——补测时请把条件(日期、端口、波特率、站位、模组固件版本)一起写进去。 :::


9. 故障排查​

9.1 三层法:电源 → 流完整性 → 协议语义​

照顺序走,不要跳层。 前一层的现象会伪装成后一层的问题,这是 95% 现场问题的根因。

第①层 电源与 USB 枚举(看灯 + 看设备管理器)​

现象判据处置
RADAR 红灯不亮3.3V_RADAR 没建立量 H3 的 V/P 对 G 是否 3.3 V ±5%(3.14~3.47 V);确认插的是 H3;确认固件在启动后拉了 IO14
红灯亮但设备管理器没有串口USB 链路(线/口/主机)换数据线(最常见)→ 换 USB 口(台式机用机箱后面)→ 换主机;按住 BOOT 再插 USB 后松开
端口还在、设备不在(幽灵设备)早期上板遇到过(2026-10-23 已跑通,换环境后未复现)① 拔线等 5 s 再插;② 设备管理器「查看 → 显示隐藏的设备」清掉幽灵项再枚举;③ 换线换口;④ 仍不行换主机/加有源 HUB 排除供电;⑤ 记录主板与口位,便于判断是不是特定主机/线材问题
打开端口瞬间板子复位DTR/RTS 硬件行为(正常)上位机应重试,1~2 s 恢复;不要用「一打开必须立刻有数据」做判据

第②层 流完整性(PC 侧看行率与坏行)​

现象判据处置
一行都收不到见 9.2 判据①① 波特率是否 115200(不是 256000/921600);② 模组是否上电(红灯);③ 是否插 H4;④ 是否烧的 radar_bridge_edv163_gesture;⑤ 模组固件是不是挥手版;⑥ 网页是否连的是那个「USB 串行设备」
有字节但全是坏行见 9.2 判据②先怀疑「流里混了非协议文本」(固件 printf / 别的程序占了端口 / 波特率临界错)。用 --raw-dump 把坏行落盘看内容
行率明显偏低(如 1~2 行/秒)丢行或固件节拍不同看诊断通道 uart_rx_overflows / usb_tx_dropped;先换线换口排除 USB 问题
「跳过二进制帧」暴涨 + 重同步暴涨帧格式/长度域理解有偏差,或流里有假帧头用 --raw-dump 取一段原始字节手工核 45 44 位置与长度字段
出现超过 1 s 的空档成段断流(USB 重枚举、固件卡顿、解析吞行)平均行率能把一次断流摊平,所以空档次数比平均行率更灵敏,以它为准

第③层 协议语义(target / action / 触发)​

现象判据处置
坐标恒为 —、tag 恒 target=0位置窗一直没形成目标是否真在视场内(±0.40 m / 0~1.00 m);视野里是否有静止强反射面;是否动作太快
挥了手但 action 一直是 0模组没识别出方向幅度加大到 2030 cm、确认正对、距离收到 0.20.6 m
行率正常、方向却相反见 9.2 判据③属固件/协议问题,不要在网页端改映射
触发判定与 z 对不上阈值单位/严格小于语义确认阈值是 cm(默认 20.0);z 恰好等于阈值时不触发是正确行为
出现「未知挥手」action 值超出 -2..2 且不是 ±3记下当时的 action= 原始值(编码表可能要补),并核对模组固件版本

9.2 三条专属判据(照着认就行)​

判据现象组合结论处置
①「0 行」收字节 > 0 或 = 0,但有效 GESTURE 行 = 0,坏行也 = 0(没有文本可判)根本没有文本行进来:波特率错、模组固件不是挥手版、烧错 demo、插错排针按第①→②层顺序查;不要先怀疑解析器(解析器有 110 项自测兜着)
②「全是坏行」有大量文本行,但几乎全部匹配不上(坏行率接近 100%)字节到了但格式不对:波特率临界错(能出可打印字符但错位)、流里混了别的设备日志、模组发的是另一种文本格式--raw-dump 看坏行原文:像 I (123) wifi: … 或 I (115) esp_image: … ⇒ 固件日志污染(2026-10-23 的真实案例就是这一类轻症,根因是 bootloader 日志不受 CONFIG_LOG_DEFAULT_LEVEL 管,加 CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y 修掉,见 9.3 第 11 条);像乱码 ⇒ 波特率;像 #get xxx ⇒ 换错固件
③「行率对但方向反」有效行正常、target/z/触发都对,只有左/右(或上/下)对调action 符号约定与源码映射表不一致——源码只有映射表、没有物理验证不要在网页端改映射:先确认模组固件版本与源码是否同一代;把「动作 → 实测 action 值」逐条记下来,交固件/协议侧定论后统一改

:::tip 三句话记住区别 0 行 = 链路/固件版本问题;全是坏行 = 流被污染或格式不对;方向反 = 编码语义问题。 三者的责任人和处置完全不同,混着查会浪费一整天。 :::

9.3 本方案特有的坑(按杀伤力排序)​

#现象根因处置
1照抄水位版配置,一行都收不到波特率仍是 256000(本方案是 115200)核对 APP_EDK60_EDV163_GESTURE_BAUD=115200;网页下拉也选 115200
2以为「没有 GESTURE: 行就是坏了」,实际模组烧的是水位固件看到的是满屏二进制乱码,不是文本换挥手固件;串口助手文本模式看不到 GESTURE: 就先别往下查
3为了「让 USB 上只有数据」关掉 USB 第二控制台,结果启动卡死、USB 不枚举该选项连带关掉 USB Serial/JTAG绝对不要关(源码有编译期断言直接拦住);用「不产生字符」实现洁净
4流里混进可打印文本,坏行率飙高固件打了日志——文本协议没有任何校验能发现,只表现为丢行零 printf:日志级别 + 横幅 + 引脚表 + 源码 + 门禁,五处一起关
5桥上「顺手过滤 0x4544 帧」,结果点云没了、文本也乱载荷里也有 0x4544;按帧头解析会删真数据桥不做任何过滤;跳过规则只在上位机侧
6自己写的上位机按 total 整段跳过校验失败的帧,后面几秒的数据全丢没照抄「校验失败只丢 1 字节」改成丢 1 字节重同步
7目标往右移,红点却往左走,以为画反了厂商语义就是 x>0 显示在左不要改;对着 README 第 86-87 行读一遍,或把模组插厂商上位机做 A/B
8挥手方向与显示相反action 符号约定未实测见 9.2 判据③:不要在网页端改,先取证再统一
9打开网页显示「不支持 Web Serial」用了 Firefox/Safari,或 file:// 被策略禁换 Chrome/Edge;或起本地静态服务
10网页与命令行工具同时跑,两边都时断时续同一个 COM 口只能一个程序占用先断开一个;采集用工具,演示用网页
11首次上板 USB 流里混进 I (115) esp_image: segment 3: ...,坏行率不为 0bootloader 阶段日志不受 CONFIG_LOG_DEFAULT_LEVEL 管,只在引导阶段打印,日志级别/横幅/引脚表/源码/门禁五道都拦不住加 CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y 后复测通过(坏行率回到 0.00%~0.35%;残留 2 行属模组侧,见第 10 节第 18 条)

10. 已知边界​

诚实列出这个方案没有做到的地方——照着做之前请先看这一节。

#边界说明
1仍有 5 项未验证(已上板的部分见本文开头的验证状态块)2026-10-23 已上板跑通,行率/坏行率/方向/动作轴映射/坐标/触发均为实测;但 0x4544 点云帧的真实存在与占比(三次采集 0 帧)、±3 的出现频率与极性(从未出现)、target=1→0 的精确时延(未做专项计时)、长时稳定性(最长 75 s,未做 30 min)、浏览器像素级目检(动画层已目检,整页未逐像素核对) 这 5 项仍无证据
2没有厂商协议文档格式、编码、容错全部是从厂商上位机源码(774 行)+ README 逆推的。源码换版本,格式就可能变 → 解析器同时支持正式格式/旧格式/四种 DBG: 行,坏行率超过 1% 立即告警
30x4544 帧只跳过、不解析不做点云可视化:帧内容一律没解读,只验证「帧边界与校验」。2026-10-23 三次采集一帧都没出现(0 帧)→ 该分支目前是防御性代码,从未被真实数据走过(U1 仍待实测)
4lock=N(动作锁)不显示与厂商界面一致;产品若要,应作为只读标签后加
5action 方向符号已实测核对左=1/右=−1/上=2/下=−2 已于 2026-10-23 现场目视核对通过;动作轴映射亦确认 ±1 ↔ X 轴、2 ↔ Y 轴。换固件后若全反,属固件/协议侧问题,仍不要在网页端改映射
6±3(靠近/远离)仍然未验证极性仍按「z 减小 = 靠近」推断;三次采集里 ±3 一次都没出现,所以「靠近 N · 远离 M」这行小字目前没有任何真实数据(U3)
7文本协议对污染零容忍工具只能检测(坏行率/重同步/垃圾段特征串),不能预防;根治在固件侧(零字符输出)
8行率不可调实测 4043 ms/行(24.326.5 行/秒),是模组固件行为,链路没有命令接口;桥只能透传。厂商 README 写的「200 ms/行」与实测不符
9坐标只做 3 位小数显示打印的是设备给的浮点值,不代表定位精度;真实精度需另设工装与多点标定
10位置图不是等比例俯视图 X ±0.40 m 铺满半宽、Z 0~1.00 m 铺满全高;长宽比随窗口变 → 看图要结合坐标读数
11遥测超时 1.5 s(厂商 1.0 s)参数本次不动:按厂商 README 的 200 ms/行,1.0 s 只容 5 行;按实测 40~43 ms/行推算,1.5 s 约为 35~38 行余量(推算值)
12触发卡片配色是绿(厂商红)任务书要求,唯一一处视觉偏离
13网页不落盘、不导出不写本地存储(硬约束),日志只在内存、400 行上限,刷新即清;要留证据请用命令行工具 --save-raw / --csv
14离线分析没有真实时间戳--file 模式配 --duration 才算行率/行间隔,且「时刻」按字节位置线性插值,不代表真实到达时刻;大点云帧会在这条插值轴上占掉成比例的时长 → 离线模式下「空档」结论只作参考,定论必须用 --port 实测
15浏览器限制Web Serial 只在 Chrome / Edge 89+ 可用,需 https 或 localhost;Firefox / Safari 不支持
16不做手势自定义 / 多设备不做训练、不做手势库扩展、不做多模组同时接入(单串口 + 单目标)
17不承担安全/控制责任挥手方向与距离触发未经功能安全评估,不可直接用于门禁、医疗、机械控制等有安全后果的场景
18模组开机固定吐 2 行 banner每次上电,模组自己会输出 EasyDetek 与 EDV163_VB_ID0xFFFF_V101 两行,会被解析器计为坏行——这是坏行率 0.00%~0.35% 的唯一来源。ESP 侧 bootloader 与 app 日志已全部静默,但这 2 行属模组侧,改不了;判读坏行率时先把这 2 行扣掉
19模组设备 ID 是 0xFFFF(未写入)自报版本串 EDV163_VB_ID0xFFFF_V101 说明设备 ID 位仍是出厂未写状态(0xFFFF)、固件版本 V101。多模组场景不要拿它当唯一标识;量产前需请厂商写号

附录 A · 帧格式速查 + 一行期望样例​

A.1 文本行(主路径)​

GESTURE: target=<0|1> x=<米> y=<米> z=<米> action=<-2..2>
字段取值备注
target0 / 10 ⇒ 位置窗未形成,x/y/z 全 0,不参与触发
x y z浮点(米)支持科学计数法;z 是触发与俯视图的主变量
action-2..2,另有 ±3见 6.2 编码表;±3 不显示为方向

一行「真实期望样例」(取自厂商 README.md 的协议示例,不是本次实测抓包; 2026-10-23 上板已确认这类行真实存在、行率与字段都对,但本文不重贴含模组 banner 的原始日志):

GESTURE: target=1 x=0.012 y=-0.034 z=0.156 action=1

按本方案解析结果应为:target=1(位置有效)、坐标 +0.012 / −0.034 / +0.156 m、 action=1 → 左挥手、阈值 20 cm 时 z = 0.156 小于 0.20 → 触发。 若你在真机上抓到第一行真实数据,请把它替换到此处并注明日期与端口(样例行已由 2026-10-23 上板证实可用)。

A.2 兼容行(可能不会出现)​

GESTURE: target=1 x=… y=… z=… wave=<N> depth=<N>
DBG: … target=1 … pos_m=( x y z ) … action=<N> [lock=<M>]
DBG: … target=0 … action=<N> [lock=<M>]

A.3 0x4544 二进制帧(只跳过、不解析)​

+--------+--------+------------------+--------+
| 45 44 | total | 载荷 | 校验 |
| 2 B | 2 B BE | total-5 B | 1 B |
+--------+--------+------------------+--------+
total ∈ [11, 4096];校验 = sum(前 total-1 字节) & 0xFF
校验失败 → 丢 1 字节重同步(不是整帧跳过)

A.4 关键常量(网页 / 工具一致)​

常量值来源
波特率115200(8N1,无流控)源码 DEFAULT_BAUDRATE 第 35 行 + README 第 26 行
输出节奏实测 4043 ms/行(24.326.5 行/秒);厂商源码 docstring 第 5-7 行 + README 第 61 行写的「约 200 ms/行」与实测不符2026-10-23 三次采集(25/50/75 s:570 / 1,322 / 1,826 行)
行率判据24.3 ±20% → 19.4~29.2 行/秒(原按 README 假设的 5.0 ±20% 已作废)2026-10-23 实测后修正
坐标护栏±1.50 m(原 ±1.00 m)2026-10-23 实测 x 到 −1.21 m 后放宽
二进制帧长度范围11 ~ 4096源码第 187-188 行
文本缓冲上限16384 B源码第 189 行
触发阈值0~100 cm,默认 20.0;z 严格小于才触发源码第 373、697、708-710 行
遥测超时网页 1.5 s(厂商 1.0 s)设计决策
判据条数P0 前提 + 9 条硬判据(P1~P9)仓库内《流校验测试计划》

附录 B · 与水位版 / 人数统计版的差异(照抄旧方案会踩的坑)​

维度EDV11P(人数统计,已上板)EDV163(水位,未上板)EDV163(手扫 / 挥手,已上板实测)
波特率921600256000115200(错一档 = 一个字节都收不到)
数据形态二进制帧(0x70 上报)二进制帧(0x81 上报,帧尾 0x0A、有转义)文本行 GESTURE: … + 0x4544 点云帧(混流;2026-10-23 三次采集 0 帧)
协议来源协议文档 + 驱动源码协议文档 + 驱动源码无协议文档,只有厂商上位机源码 + README
解析难点帧同步、zone/目标字段帧尾冲突 + 字节转义 + 7 B/通道口径文本正则 + 整帧跳过二进制帧(更简单,但对"串里混日志"更脆弱)
写入需求需要下发配置需要下发配置(挂高、上报频率…)完全只读:厂商源码无 .write(,模组无命令接口
上位机track.html + 厂商桌面端level.htmlgesture.html(零写入路径,连 port.writable 都不取)
视图语义平面轨迹图水位曲线 + 水位柱X-Z 俯视 + X-Y 正视(x>0 显示在左,照厂商)
日志污染后果跳过几帧(可恢复)切断当前帧(严重)直接吃掉文本行完整性(最严重:没有任何校验信号)
判据条数P0 + 6P0 + 8P0 + 9(新增 target 比例、未知 action、触发事件)
上板状态已上板实测被模组固件阻塞已上板实测(2026-10-23):行率/坏行率/方向/动作轴映射/坐标/触发均实测;点云帧与 ±3 三次采集未出现(见本文开头的验证状态块)

一句话记住三套的差别:人数统计看「轨迹」、水位看「距离换算」、手扫看「方向 + 触发」; 而只有手扫这套的协议是逆推来的、数据是文本、链路只读——这三点决定了本文的写法。


附录 C · 待补清单(仍未验证的 5 项)​

2026-10-23 上板跑通后,真实抓包、动作四向符号核对、行率 / 坏行率、坐标范围 等项已完成并从本表移除。 下面只剩真的还没测的 5 项。填上之后请把「待实测」改成实测值,并在本表标记日期。

#待补项影响怎么补
①0x4544 点云帧的真实存在与占比(U1)决定「跳过二进制帧」是活路径还是死代码三次采集(25/50/75 s)均为 0 帧 → 长时(≥10 min)采集再看 binary.frames_ok;为 0 也要记录
②±3(靠近/远离)的出现频率与极性(U3)决定「靠近 N · 远离 M」这行小字有没有意义手掌沿 Z 轴靠近/远离各 10 次,看计数与符号;本次三次采集一次都没出现
③target=1 → 0 的精确时延(U4)影响「目标位置未就绪」的观感与触发是否频繁闪断目标离开视野,用 --csv 对同一段做专项计时(「10 帧位置窗」对应的时延仍无实测数)
④长时稳定性目前最长只跑过 75 s,没有 30 min 级证据按仓库内测试计划跑 30 min 静置 + 10 min 挥手,看行率漂移、空档次数(P5)、坏行率
⑤浏览器像素级目检(1280×720 / 1920×1080)布局只做了静态契约;动画层已目检(工程仓 docs/project/edv163-gesture/figures/anim-*.png),整页未逐像素核对有桌面的机器上两档各截一次图,核对「整页无纵向滚动、两图不被压扁、日志折叠后图变高」

(原表里「是否需要显示动作锁 lock」属产品需求问题、不属实测项,已随其余已完成项一并移出本清单。)


许可与署名​

本项目代码与文档以 MIT License 发布,作者 @fuhua817。

协议部分(GESTURE: 行格式、action 编码、0x4544 帧与跳过规则、位置图语义、触发判定) 均以厂商上位机源码 gesture_monitor.py(774 行)与其 README.md 为准,版权归原厂所有; 本项目没有拿到任何厂商协议文档,文中所有协议结论都是对源码的逐行核对,并标注了源码行号。 若厂商后续发布正式协议文档且与本文冲突,以正式文档与新一代固件对应的源码为准。

:::danger 免责声明 本项目是技术演示与方案验证用途。挥手方向识别与距离触发未经功能安全评估, 受站位、动作幅度、环境反射与模组固件版本影响,不可用于门禁控制、医疗设备、机械安全联锁 或任何有安全后果的场景。用于实际项目前,请按目标市场的无线电、数据与安全法规完成相应合规评估。 :::