跳到主要内容
版本:1.0.0

用 EDK60 桥接 EDV163 吊装雷达——水位监测(水位 = 挂高 − 距离)

一句话:一块 EDK60_VA 开发板 + 一颗 EDV163 吊装雷达(天线朝下),不用 USB 转串口芯片、不用装驱动, 把雷达每秒上报的「到水面距离」(mm)经原生 USB 实时送到浏览器,用 水位 = 挂高 − 距离 画成水位曲线与水位柱。

本方案与人数统计版(EDV11P)的三处硬差异:波特率 256000(不是 921600)、帧尾固定 0x0A、 正文有转义(0x0A → 09 01、0x09 → 09 00)。这三处任何一处照抄旧方案,都会表现为 「一帧都收不到」或「帧全乱」。

:::warning ⚠️ 验证状态(读正文之前请先看这一块) 固件、网页、工具都已就绪,并且都通过了自测;但这套链路还没有在 EDV163 实物上跑过。

阻塞原因(如实记录,不修饰):手上这颗 EDV163 模组当前烧的是「挥手」固件,不是水位/测距版固件。 上板抓过 20 s / 29 KB 数据,字节只集中在 8 个值(F8 / 3E / FE / 00 / C6 / 06 / 38 / C0), 0x45 0x44 0x0A 一个都没有,GET 0x02 / GET 0x25 无任何应答。 所以要先把模组换成 EDV163 水位/测距版二进制固件,上板用例才能开始跑。 :::

维度现在的真实状态证据
固件demo radar_bridge_edv163(Kconfig 编号 5.3)已实现;合并固件 244,192 B、SHA256 72E600D0…07381B、烧 0x0仓库内《EDV163 水位监测 demo · 固件实现说明》
网页level.html 单文件、无外链、可离线;页内自测 10/10、桩环境 44/44、布局契约 32/32仓库内《网页水位工具自测报告》
工具tools/edv163_frame_check.py --selftest 通过(36 行对账表,含「数据里出现 0x0A/0x09」的用例)仓库内《帧完整性校验测试计划》T-FC-05
尚未做的所有上板用例:30 分钟静置采集、水位换算核对、卷尺标定、转义实况、静水面 presence 行为、近距盲区、启动峰值电流见本文第 8 节与附录 C
本文数字的性质凡没有标注来源的数字,都来自自测/构造/规格书二次来源,不是实测;正文逐处写明「已自测 / 待实测」—

所以请这样读这篇文档:

  1. 接线、烧录、协议、安装几何这几节可以照着做——它们要么是板上实测事实(H3 引脚、红灯、EN=IO14), 要么是协议与驱动的逐行核对结论。
  2. 凡是涉及「多少帧、多准、漂不漂」的量化结论,全部标着待实测,目前没有一个是实测值。 别把构造帧当成抓包。
  3. 你要复现,第一步不是插模组,而是确认模组固件是水位/测距版(见附录 C ①)。

1. 你能做出什么​

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

容器上方吊一颗 EDV163,天线面朝正下方。浏览器里能得到三样东西:

界面元素内容
大字读数当前水位,只显示整数 cm(例:76 cm)——受模组 8 cm 级距离分辨率限制,多给一位小数就是假精度
水位曲线近 10 分钟滚动时间窗,每 1 秒一个点(上报频率 0x17 = 10,单位 100 ms);注水上涨、排水下降、阶跃都能看出来
水位柱竖向柱 + 满量程百分比,一眼看出「离满罐还有多少」

外加一列诊断字段:target_distance(mm,原始距离)、每通道的 presence / target_state / motion_direction、 坏帧数、转义错误数、最后上报时刻。

:::tip 关键预期管理 静水面很可能被这颗模组判成**「无人」(它本质是人体存在检测算法的衍生品)。这类情况下距离仍然有效**, 页面不按 presence 过滤,水位照常更新——界面上会显示「判定:无人(静水面)」,这是正常现象,不是故障。 :::

1.2 你会得到什么​

  1. 一条完整链路:EDV163 →(UART 256000 8N1)→ 开发板 →(原生 USB,免驱)→ 浏览器
  2. 实测确认的接线表(含一处仍待万用表定论的悬念 T-01,本文照实标注)
  3. 两种烧录路径(线上网页烧录 / 本地 idf.py)+ 一个「烧 0x0」的单文件合并固件
  4. 一个网页水位工具——默认只读,写入必须你在确认框里点确定
  5. EDV163 帧协议的逐字节拆解:长度口径(转义前、含帧尾)、校验和、转义规则与手算示例、 0x81 载荷的 7 字节/通道口径(附协议文档「8 字节」笔误的勘误)
  6. 吊装几何与调参表,以及**「挂高必须显式下发」**这个必踩的坑(出厂 3000 mm)
  7. 水位标定步骤(卷尺量实际距离反算),以及三层排障法

2. 需要什么​

2.1 物料清单​

#项目型号 / 规格必备/可选说明
1开发板EDK60_VA V1.0(ESP32-C6-MINI-1-N4,4 MB Flash,无 PSRAM)必备板载 USB-C,无 USB 转串口芯片(走芯片原生 USB,免驱)
2雷达模组EDV163(二进制固件版,协议 V2.0,GET 0x02 应回 EDV163_VB)必备插在板子的 H3 排针上。见下方 ⚠️ 固件版本警告
3线缆USB-C 数据线必备必须能传数据;纯充电线会出现「灯亮但电脑认不到」
4容器水桶 / 水槽(1 m 内径量级)+ 可注水排水必备台架建议用静水桶(无进水扰动);有静水井/导波管更好
5量具卷尺(≥3 m)必备标定挂高、换算水位都靠它;没有它就无法验证水位准不准
6支架刚性吊装支架(可锁死角度)必备挂高是系统零点,机械松动 = 系统性偏差
7反射靶低密度浮子靶(泡沫板 / EPE,直径 ≥150 mm)可选(推荐)抑制水面波纹,同时在回波弱时提升反射
8PCWindows / macOS / Linux必备网页版需 Chrome / Edge 89+
9万用表—可选(建议)做 T-01 通断核对、量 H3-V 的 3.3 V
10电源USB-C 直连 PC 即可—不需要 DC-005 适配器(见下方供电提示)

:::danger ⚠️ 必须用「二进制固件版」的 EDV163 EDV163 有两条协议固件线:二进制(本文用的这条,op/type/TLV 帧、带 target_distance) 和 ASCII 文本(#set / #get 一类文本命令)。 ASCII 版没有 target_distance 字段,本方案的水位换算无从谈起——拿到模组第一件事是 GET 0x02 确认回的是 EDV163_VB,而不是别的型号/分支。 :::

:::info 供电提示(本方案与人数统计版最大的不同) 人数统计版(EDV11P)启动峰值 < 1200 mA,是那套方案的头号风险;EDV163 典型电流 11 mA ± 2 mA、 综合功耗 < 0.1 W,量级差约 40 倍。板上雷达那一路 LDO 是 AP7362-33SP-13(额定 1.5 A), 按小于 30 mA 的上限算余量 ≥ 50 倍。所以PC 的 USB-C 口(USB2 500 mA / USB3 900 mA)就够, 不需要 DC-005、不需要 470 µF 电容、不需要改板。 唯一残留未知项是启动峰值未标注(T-05),工程上用「EN 拉高后等 ≥200 ms 再读串口」兜住。

反之,若你真要走 DC-005:板上是 LM2596 降压,适配器要给 7~12 V / ≥1 A, 不要照抄别处的「DC-005 接 5 V/2 A」——5 V 直入会掉到 4.5 V 附近。 :::

2.2 软件环境​

软件本文涉及版本用途
ESP-IDFv6.1.0(target esp32c6)本地编译烧录(走线上烧录页则不需要)
Python3.13(用 py -3 启动器)跑帧校验脚本
pyserial3.5只有 --port 实时抓包模式需要;--selftest / --file 不需要
Chrome / Edge89+网页水位工具(Web Serial)
Node.js20.x只有想在命令行复核网页工具的页内自测时才需要

2.3 不需要的东西​

  • 不需要 USB 转串口模块(CH340 / CP2102 等)
  • 不需要 装任何驱动(原生 USB Serial/JTAG,设备管理器直接认成「USB 串行设备」,VID 0x303A)
  • 不需要 电平转换(模组是 3.3 V TTL UART,与 ESP32-C6 同电平;也不要串电阻分压,会破坏 256 k 波形上升沿)
  • 不需要 你在固件里写协议解析(固件只搬字节,0x81 解析、转义还原、水位换算全在网页侧)
  • 不需要 外部供电(见 2.1 供电提示)

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 H3 引脚表(EDV163 ↔ EDK60)​

H3 脚丝印EDV163 脚板上网络 / GPIO信号方向电平需要电平转换吗
1RES—(模组无此脚)复位网络(与 H4 共用)——空置
2AA(GPIO 状态输出,高 = 有人)实测:IO5 所在网络(MCU TX 发 get_version 能收到应答)输出(模组→MCU)3.3 V否
3RR(UART RX,← MCU)读图:IO1 方向输入(MCU→模组)3.3 V否
4TT(UART TX,→ MCU)IO4(MCU 的 UART RX)输出(模组→MCU)3.3 V否
5GG(GND)GND共地0 V否
6VV(VCC 3.3 V)3.3V_RADAR(U4 = AP7362-33SP-13 输出)电源入3.3 V DC否
7PP(DC Input 3.3 V)3.3V_RADAR(与 V 同网络)电源入3.3 V DC否
8RES—(模组无此脚)复位网络——空置

本方案只用 4 个电气信号 + 2 个电源脚:数据入 T(IO4)、数据出 A(IO5)、电源 V/P、地 G。 A 脚在 EDV163 上是「有人/无人」的 GPIO 输出,本 demo 不用它—— target_distance / target_state 全部从 UART 上报帧里取。

:::caution T-01:接线上的唯一 P0 悬念(插模组前 3 分钟用万用表定论) 读图与上板实测在 H3 的 A / R 两脚归属上不一致:实测证明 IO4 = 模组 TX(收得到合法帧)、 IO5 = 模组 RX(发 get_version 收到应答);而读图给出 A → IO0、R → IO1、T → IO4。

风险:若 EDV163 的 A 脚(GPIO 输出)真的和 MCU 的 IO5(UART TX 输出)同网络, 插上就是输出对输出顶牛,可能拉大电流、串噪声。

处置:① 断电,万用表通断:H3 第 2 脚 ↔ IO5 / IO0 各测一次;② 只上电(EN 保持低、3.3V_RADAR 不输出), 把 IO5 当 GPIO 输出高/低,量 H3 第 2 脚是否跟随;③ 结论回填后再插满脚。 本条尚未定论,本文照实标注为「待实测」。 :::

3.3 为什么必须插 H3​

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

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

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

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

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

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

① MCU 启动(主 3.3 V + USB 枚举稳定)
↓
② IO14 拉高 → U4 使能 → 3.3V_RADAR 建立 → 丝印 RADAR 红灯亮
↓
③ 模组内部上电复位 / 自检 / 射频校准(固件按 ≥200 ms 冗余等待,T-05 待实测)
↓
④ 模组开始主动上报 45 44 帧

失败先查:

现象先查什么
一个灯都不亮USB 线是不是充电线;换 USB 口(台式机优先机箱后面)
绿灯亮、红灯不亮模组没插紧 / 插到了 H4 / 固件没把 IO14 拉高
红灯亮、一个字节都没有进第 9 节第②层;首先怀疑模组固件不是水位版(见文首验证状态)
橙灯亮但红灯不亮正常也可能发生,橙灯与电源无关,不要用它判断

4. 烧录​

固件 demo 名:radar_bridge_edv163(Kconfig 里是 5.3,工程共 18 个 demo)。 它的全部工作就是:把 IO4 收到的字节原样写到 USB,把 USB 收到的字节原样写到 IO5。 不解析协议、不组帧、不做转义/反转义、不下发任何命令、不算水位、不打印任何日志字符。

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

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

⚡ 网页烧录页 · 水位监测固件(EDV163)

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

ℹ️ 这几份静态资源已就位:flash.html、level.html、manifest.json、edk60_edv163_level.bin (244,192 B,偏移 0x0,发布页标注版本 0.9.0)。若打开是 404,说明站点还没重新部署 (部署由推送触发),此时走 4.2(本地编译)或 4.3(合并固件 + esptool)即可。

操作顺序与验证点(与人数统计版同一套交互):

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

失败先查:设备列表是空的 → 换数据线(90% 是这个)→ 换 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

radar_bridge_edv163 在 build_all.ps1 的 $DemoMap 里已有映射。如果你想直接用 idf.py, 就是两条命令(先在 idf.py menuconfig → EDK60 Demo → 选 5.3 radar_bridge_edv163 保存):

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

期望现象:

检查点期望输出
单独构建成功,0 error / 0 warning(-Werror 下 9 个 -fsyntax-only 用例已全绿)
全量回归.\build_all.ps1 -Size → 18/18 通过
关键宏生效build-radar_bridge_edv163\config\sdkconfig.h 里有 CONFIG_APP_EDK60_DEMO_RADAR_BRIDGE_EDV163 与 CONFIG_APP_EDK60_EDV163_BAUD=256000
烧录偏移app 本体正常烧在 0x10000

:::danger 两条红线(有编译期断言兜着)

  1. 不要用 CONFIG_ESP_CONSOLE_SECONDARY_NONE=y 来「让 USB 上只有数据」—— 实测(2026-10-15)会让 C6 启动卡死、USB 不枚举、必须断电重插。正确做法是保留控制台但不产生字符。
  2. 不要把 APP_EDK60_EDV163_BAUD 调到 3 Mbps 却把 APP_EDK60_EDV163_UART_RX_BUF 留在 1024 B: 源码里有断言 UART_RX_BUF×1000÷(BAUD/10) ≥ 120 ms,不满足构建直接失败并给出算式 (默认 16384 B ÷ 25600 B/s = 640 ms,余量 10.67×)。 :::

为什么这个小 demo 里有一堆「静默」讲究:EDV163 的帧尾就是 0x0A,而任何文本日志的换行都含 0x0A。 一行日志不只是「插在帧之间」,它会直接把当前帧切断(判成「帧中途裸 0x0A」)。 所以零日志输出不是洁癖,是功能前提。做法是四道保险 + 一道门禁:日志级别编译期消失、启动横幅/引脚表关闭、 源码零 printf、运行期 esp_log_level_set("*", ESP_LOG_NONE),再加编译期分派表里整块跳过横幅。

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

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

⬇ 下载合并固件 edk60_edv163_level.bin

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

烧法(二选一):

  • Flash Download Tool(乐鑫官方 GUI):选 ESP32-C6;文件填 edk60_edv163_level.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_level.bin

⚠️ 先自己核一次哈希:Get-FileHash .\edk60_edv163_level.bin -Algorithm SHA256。 以你实际下载(或自行构建)的这份为准;下载文件、发布清单、本文三处应当是同一份。 若看到让你填三个文件、三个地址(bootloader / 分区表 / app 分开烧)的说明,那是没合并的产物,不适用于本文件。 想从源码自己生成:先完成 4.2 的编译,再执行 idf.py -B 你的构建目录 merge-bin, 产物是 merged-binary.bin——发布包里的 edk60_edv163_level.bin 就是它改名后的同一份文件。

4.4 烧完的验证点​

检查点期望
拔插一次 USB红灯仍亮,COM 口号不变(打开串口可能触发一次复位,属 DTR/RTS 硬件行为,1~2 s 恢复)
用 --raw-dump 看原始字节出现 45 44 开头的帧,帧尾 0A;没有任何中文/ASCII 日志文本
反过来(本 demo 的纪律)固件不会主动发任何字节:上位机不发 GET,流里就只有雷达自己的上报帧

状态:以上全部「待实测」——合并固件的体积与 SHA256 已由构建核实,但烧到板子上跑这一步还没做。


5. 看数据​

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

📈 网页水位演示(EDV163 吊装)

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

它是「默认只读」的(本项目的一条硬约束):

行为说明
连接后自动发的帧只有 8 条 op=0xA0(GET):0x01 产品信息 → 0x02 模块信息 → 0x11 检测延时 → 0x17 上报频率 → 0x18 工作模式 → 0x25 挂高 → 0x26 检测高度 → 0x27 检测范围,时序 100 ms + i×60 ms
会不会改你的设备配置不会。所有「设备回报」栏的数值都只来自设备真实应答
什么时候才会写只有你点「下发配置…(需确认)」或「演示用一键配置(同样需确认)」,并在确认框点确定之后;且逐条发送、逐条等应答(0xA2 或 0xA9 ACK),单条 500 ms 超时即中止、后续一条都不发
取消确认框一帧都不发
兜底监控确认流程之外若出现 op=0xA1(SET),状态条「未确认 SET」会计数告警(正常恒为 0)

不接硬件也能先确认渲染管线:勾「模拟演示」——每 500 ms 合成一条 0xA3/0x81 帧回灌同一个解析器, 水位剧本是 120 s 一循环(注水上涨 → 满水位 → 排水下降 → 低水位,叠加偶发排水凹口与水面波动)。 模拟设备的初始挂高取出厂 3000 mm,专门用来演示「回读 → 自动校正页内挂高」这条路径。

期望现象(连真机后):

观察点期望
状态条串口 = 你的 COM;连接状态「已连接」;波特率 256000;帧率开始跳动(默认 1 帧/秒)
帧日志每行 = 时间戳 + 方向 + 线上十六进制(含转义) + 解析摘要(摘要里的长度/校验和是还原后结果,标注「N 处转义」)
大字读数整数 cm;主视图口径行常显「换算用挂高 = XXXX mm」
挂高一致性若「设备回报 → 挂高」与页内设定不一致 → 配置区标红提示水位将整体偏移多少 mm
坏帧 / 转义错误常态应为 0;「转义错误」持续增长说明设备侧转义或长度口径与协议不符(见 9.1 第②层)

手动验一条算术:水位 = 挂高 − target_distance。拿通道表里的 target_distance(mm)手算一次, 和界面的 cm 数对一眼(例:挂高 2000 mm、距离 1234 mm → 水位 766 mm = 76 cm)。

5.2 桌面端为什么本方案没有​

人数统计版有一个厂商的 PySide6 桌面端,本方案不能拿它替代,原因有三条:

原因说明
协议不同那个桌面端解析的是 EDV11P 的 0x70(zone + x/y/z 坐标);EDV163 是 0x81(count + 每通道 7 B + target_distance),字段完全不同,拿过来只会解出错值
本方案没有 EDV163 桌面端工具EDV163 的规格书与上位机工具在现有发布/规格目录中均未找到;本 demo 的上位机交付物只有网页版
固件是纯透传谁都能写自己的上位机(协议见第 6 节),但要自己实现转义还原与 7 B 步长,直接用旧解析器必然踩坑

想看统计而不是曲线,用 9.4 的命令行工具:它能出 level.csv(水位时间序列,可用 Excel 画曲线)与 JSON 报告(坏帧率、帧完整率、转义还原对数、0x81 帧数与载荷自洽率),但它不是实时界面,也不画图。

⚠️ 同一时刻只能有一个程序占用这个 COM 口。 网页工具与帧校验脚本同时跑会互相抢端口。


6. 协议要点​

这一节够你从零写出自己的上位机。固件一行协议代码都没有——帧头、长度、校验和、转义、0x81 解析、 水位换算,全部在上位机侧。

6.1 帧结构​

0 2 4 6 7 8 10 N+10 N+11
+--------+--------+--------+----+----+--------+------------+----------+--------+
|45 44 | 长度 | msg id | op |type| TLV长度| 数据区 N | 校验和 | 0x0A |
| 2B | 2B BE | 2B BE |1B |1B | 2B BE | N B | 1B | 帧尾 |
+--------+--------+--------+----+----+--------+------------+----------+--------+
长度 = 12 + N(**含帧尾**,按【转义前】计算);校验和 = Σ(帧头 .. 数据区末) & 0xFF
组包顺序:算长度/校验和 → 追加校验和 → 对「帧头 .. 校验和」整段转义 → 最后追加帧尾 0x0A
字段偏移长度编码说明
帧头020x45 0x44固定(ASCII "ED")
长度22uint16 大端12 + 数据区长度,最小 12、最大 256,含帧尾、按转义前算
msg id42uint16 大端递增;应答回显请求的 id(驱动容差 ±1)
op61uint8见 6.2
type71uint8见 6.2
TLV 长度82uint16 大端必须 = 长度 − 12
数据区10N视 type载荷
校验和10+N1uint8Σ(帧头 .. 数据区末) & 0xFF,按还原后字节算
帧尾11+N10x0A固定,永不转义

:::caution 与人数统计版最容易被忽略的一处 那个方案的长度是 11 + N、没有帧尾;这里长度是 12 + N,把帧尾算进去了。 照抄旧解析器 → 校验和位置差一位(应在倒数第 2 字节,末字节是 0x0A)→ 每帧都判坏。 :::

6.2 op / type 速查​

op含义谁发
0xA0GET,参数获取上位机
0xA1SET,参数设置上位机
0xA2REPORT,对 GET/SET 的回复(回显 msg id)雷达
0xA3STATUS,主动状态上报雷达
0xA4透传(预留)—
0xA9ACK(含 1 B 状态码 01 = 成功)雷达
type名称SET 载荷本方案用不用
0x01产品信息—(GET)连上后 GET
0x02模块信息—(GET,ASCII:设备 ID / 固件版本…)连上后 GET(确认 EDV163_VB)
0x04波特率1 B 枚举 0~5(9600…256000)排障时 GET 确认是 5
0x11检测延时2 B 大端,秒,最小 2一键配置写 5 s
0x12闭锁时间2 B 大端,秒默认即可
0x17上报频率2 B 大端,单位 100 ms一键配置写 10(= 1 s)
0x18工作模式1 B:0 关闭 / 1 正常一键配置写 1(为 0 会完全没有 0x81)
0x1B触发使能1 B 0/1默认即可
0x1C无人后持续存在检测2 B 大端,秒水位场景不用(写 0)
0x1D30 min 强制无人开关1 B 0/1必须关(写 0)——静止水面会被判「无人」
0x25挂高2 B 大端,mm,1200~5000必下发(见 7.3)
0x26检测高度4 B:min(2B) + max(2B) 大端,mm一键配置写 0 ~ max(2000, 挂高)
0x27检测范围16 B:运动区 x/y + 存在区 x/y 各 min/max(2 B 有符号大端),mm一键配置写 ±400 mm
0x28自动测高—(触发雷达自行标定挂高)本版不发(会自动改设备挂高)
0x29屏蔽区1 B 数量 N + N×13 B,最多 10 个本版不解析
0x81上报数据—(主动上报)主数据源,水位就靠它

上报是异步的:发一条 SET 之后必须等应答(0xA2 / 0xA9)再发下一条。 驱动侧节奏:单次超时 233 ms、重试 3 次、命令间隔 233 ms; 网页工具用的是「单条 500 ms 超时即中止」的保守策略。

6.3 转义规则(本方案最核心的一段)​

方向规则
发送(转义)正文中 0x0A → 0x09 0x01、0x09 → 0x09 0x00;帧尾 0x0A 不转义
接收(还原)0x09 0x01 → 0x0A、0x09 0x00 → 0x09;0x09 后跟其它字节 = 非法转义
作用范围帧头 … 校验和(共 长度-1 字节);帧尾在转义之后追加
长度 / 校验和一律按转义前(= 还原后)的字节序列计算,与线上字节数无关

接收侧必须按这个顺序处理:先还原 → 再按「转义前长度」切帧 → 再验校验和。 直接用线上字节数去切帧,一旦正文里出现 0x0A / 0x09 就会整体错位。

怎么区分「转义序列 09 01」和「真帧尾 0x0A」(接收侧唯一的技巧):

  • 逐「线上」字节推进,同时累积还原后的缓冲;
  • 只有当前字节是 0x0A 且它前面没有 0x09 引导时,才是真帧尾;
  • 0x09 后面的字节一定是 00/01(否则判非法转义,只 skip 1 字节重同步);
  • 任何非法形态都只丢 1 个字节,不整段 flush——这样截断帧、坏校验和、非法转义之后都能重新捕获下一条好帧。

6.4 手算示例:一条 0x81 上报帧(构造帧,非实测)​

:::warning 这条帧是自测/构造数据,不是设备抓包 它取自帧校验工具自测合成流里 msgid = 0x0106 的那一帧(测试计划 T-FC-05 第 35 项), 目的就是把「正文里出现 0x0A / 0x09 怎么办」讲透。真实抓包待补(附录 C ③)。 :::

载荷(还原后):01 00 01 02 01 0A 09 FD —— 即 count=1,通道 0, delay_presence=1(有人)、target_state=2(运动)、motion_direction=1(靠近)、 target_distance = 0x0A09 = 2569 mm、target_angle = 0xFD = −3°。

第一步:按转义前算长度 N = 8 → 长度 = 12 + 8 = 20 = 0x0014;tlv_len = 0x0008(= 1 + 7×1)。

第二步:算校验和(帧头 → 数据区末,逐字节求和 & 0xFF)

45 44 00 14 01 06 A3 81 00 08 01 00 01 02 01 0A 09 FD
= 69+68+0+20+1+6+163+129+0+8+1+0+1+2+1+10+9+253
= 741
741 mod 256 = 229 = 0xE5 ✅ 校验和 = 0xE5

第三步:对「帧头 … 校验和」整段转义 正文里有两个命中:0x0A(距离高字节)→ 09 01;0x09(距离低字节)→ 09 00。

线上字节(22 B):
45 44 00 14 01 06 A3 81 00 08 01 00 01 02 01 09 01 09 00 FD E5 0A
└─┬─┘ └─┬─┘ └─ 帧尾,不转义
0x0A 0x09

第四步:读数

  • 声明长度 20 B,线上 22 B —— 差 2 字节就是两处转义各膨胀 1 字节。这就是「长度按转义前算」的直接证据。
  • 接收侧还原后得到 20 字节,取 data = 01 00 01 02 01 0A 09 FD, 按 7 B/通道解出 target_distance = 0x0A09 = 2569 mm、target_angle = 0xFD = −3°。
  • 若挂高设 2000 mm:水位 = 2000 − 2569 = −569 mm(负值 = 水面比「零点」还远,说明超出量程或挂高设小了, 这正是本用例故意造的越界值,用来验证换算与符号)。

为什么转义不是「偶发情况」:target_distance 是高/低两个字节,落在 0x09 / 0x0A 上很常见 (2569 mm = 0x0A09、1497 mm = 0x05D9…),校验和字节本身也可能是 0x09 / 0x0A。 自测合成流里 16 帧有 4 帧含转义。所以「转义错误 = 0」不是理论要求,是每一帧都在被检验的判据。

一个不起眼但会咬人的例子:SET 0x17 = 10(上报频率 1 s)——value 就是 0x000A, 所以这条 SET 帧本身必须转义:声明长度 14 B,线上 15 B(… 00 09 01 5C 0A)。 手工拼帧时忘了这一步,设备会按「帧中途裸 0x0A」把它当成一条截断帧丢掉。

6.5 0x81 上报载荷:每通道 7 字节(附协议文档笔误勘误)​

count(1B) + count × { channel:1, delay_presence:1, target_state:1, motion_direction:1,
target_distance:2 (大端, mm), target_angle:1 (int8, 有符号) } ← 7 B/通道
tlv_len 必须 = 1 + 7 × count (count=1 → 8;count=2 → 15;count=3 → 22)
偏移(通道首字节起)长度字段类型说明
01channeluint8通道号
11delay_presenceuint80 无人 / 1 有人
21target_stateuint80 无人 / 1 静止 / 2 运动
31motion_directionuint80 静止 / 1 靠近 / 2 远离
42target_distanceuint16 大端mm,水面距离——水位就靠它
61target_angleint8度,有符号(0xFD = −3)

:::danger 勘误:协议文档「每通道 8 字节」是笔误,实际是 7 字节

项内容
矛盾点《EDV163 串口通用协议》§3 正文写「每个通道 8 字节」,但同一段紧接着列出的字段只有 6 项、合计 7 字节;驱动里 edv163_channel_data_t 是 packed,sizeof = 7
实现证据radar/edv163.c L372-390:读到 channel_count 后按 7 字节/通道顺序 index++ 读取
推导结论tlv_len = 1 + 7 × count(1 通道 → 0x0008、2 通道 → 0x000F、3 通道 → 0x0016)
若按 8 B 实现会怎样2 通道帧(tlv_len = 0x000F)整体错位 1 字节,距离与角度全错;而单通道帧(0x0008)恰好不报错——所以这个 bug 会在「多通道才暴露」,非常阴
本方案口径网页与帧校验工具一律按 7 B 实现;tlv_len ≠ 1 + 7×count 时显式判载荷异常,绝不按 tlv_len/8 反推通道数(猜错就是静默渲染垃圾)
取证方式上板后看帧校验工具 JSON 里 report_0x81.channel_stride:锁定 7 = 正常、8 = 告警(说明固件按文档口径发)
:::

另外两条容易踩的实现细节:

  1. 载荷第一字节就是 channel_count——驱动里的 data_changed 是固件本地标志,不在串口载荷里。
  2. 驱动的接收路径不做转义还原、也不太校验 tlv_len(按在线长度直接切帧)。 所以「设备上报帧到底有没有转义」只能由 PC 侧证明——这正是网页工具与帧校验工具的核心职责(见附录 C ③)。

6.6 校验和与组帧的规矩​

cs = sum(帧头 .. 数据区末) & 0xFF # 从 0x45 开始,一个字节都不能漏

规矩:

  • 永远用程序组帧,不要手抄别人的 hex、不要心算(本项目有「手算校验和差 4 导致 GET 完全无应答」的历史教训)。
  • 发送前把 CS 打印出来对一眼;接收侧用同一份代码算,不要拿两套实现互相对照后就假定自己是对的。
  • 组帧后先转义、最后贴帧尾;不要「先加帧尾再整段转义」——那样帧尾会被转义成 09 01,设备永远等不到帧尾。

7. 安装与调参​

7.1 吊装几何(水位场景专属,和侧装人数统计完全不同)​

项要求理由
姿态天线面朝正下方,与水面法线夹角 ≤ ±5°60 GHz(λ ≈ 5 mm)以镜面反射为主,倾斜超过 5° 就把回波瓣偏出接收视场 → 距离丢失或被动读到壁面
水平位置容器几何中心正上方,距罐壁 ≥ 100 mm减小罐壁多径与爬壁水膜反射
避免位置正对进水口、溢流口、曝气/搅拌、排水漩涡水面强扰动 + 飞溅(水膜糊天线罩)
支架必须刚性、可锁死;预留 10~20 mm 天线罩净空挂高是系统零点,机械松动直接变成系统性偏差
天线罩ABS / PP / PE 等低损耗塑料,厚度 ≤ 2 mm;禁止金属罩正对波束60 GHz 金属全反射;塑料损耗小
量程协议挂高 1200~5000 mm;本方案推荐 2000 mm(两侧各留 ≥800 mm 余量)落在协议区间中段
设计水位工作带0~1500 mm(对应距离 500~2000 mm)预留 ≥500 mm 近距余量,避开未标注的近场/盲区(T-03)
#现象机理缓解
G-1罐壁/支架多径 → 读到「假水面」±50° 在 2 m 处光斑半径约 2380 mm(直径约 4.8 m),远大于 1 m 内径的容器①0x27 检测范围收到 ±400 mm;②0x29 屏蔽区(本版不解析,需自行下发);③容器中心安装 + 非金属挡圈收窄;④软件取「最小稳定距离」+ 5 点中值
G-2水面波纹/泡沫 → 距离跳变、丢帧镜面判据(Rayleigh)Δh < λ/(8·cosθ) ≈ 0.63 mm;波纹超过 0.6 mm 即进入漫反射区①静水桶/导波管(最有效);②水面放浮子反射靶(泡沫/EPE,直径 ≥150 mm);③避开进水口;④中值 + 异常值剔除
G-3结露/蒸汽/水膜 → 距离偏短、间歇无目标60 GHz 对液态水吸收极强,天线罩内表面 0.1 mm 水膜即可明显衰减①罩朝下、外凸、带滴水沿;②罩内干燥剂 + 疏水涂层;③水汽重的场合加微加热或透气膜;④传感器装在水汽源上方 ≥300 mm
G-4平静水面被判**「无人」**,若上位机按 presence 过滤 → 水位断流模组是人体存在检测算法(目标 RCS 按人体设计),水面目标可能 delay_presence = 0上位机一律直接读 target_distance,不看 presence / target_state(网页工具已按此实现,自测用例 C9 锁死);presence 只作展示
G-5量程边界:满罐时读数卡死/为 0近距离受盲区限制(未标注,T-03 待实测)设计水位工作带 0~1500 mm;超范围时「保持上一条 + 标记 invalid」;满罐溢流必须先于「距离 < 500 mm」发生
G-6挂高设错 → 全量程系统性偏差水位 = 挂高 − 距离;挂高错 100 mm ⇒ 全量程错 100 mm。驱动默认 3000 mm 是个现成的坑首次上电必发 SET 0x25 + 回读核对;页面标红提示;按 7.4 标定;定期满罐复核

7.2 参数初始值(按 1 m 内径、2 m 挂高的容器)​

命令名称建议值为什么
0x25挂高2000(mm,标定后改成卷尺实测值)驱动/出厂默认 3000 mm,必须显式改,否则水位整体偏 1 m
0x26检测高度min 0 / max 2000(mm)水面必然落在 0~挂高 之间;max 绝不能小于挂高,否则会把水面本身过滤掉
0x27检测范围运动区/存在区 x,y = ±400 mm±(容器内半径 − 100 mm);作用是把罐壁/支架挡在区域外(本协议无波束角设置,这是唯一的软件手段)
0x11检测延时5 s(最小 2)抑制「波纹抖动导致有人/无人反复跳」
0x12闭锁时间2 s默认即可
0x17上报频率10(单位 100 ms = 1 s)水位变化慢,1 s 够用,且利于中值滤波
0x18工作模式1(正常)0 = 关闭射频 → 完全没有 0x81 帧
0x1C无人后持续存在检测0水位场景不需要
0x1D30 min 强制无人0(必须关)水面长期「静止」会被判无人
0x1B触发使能1默认即可
0x28自动测高不发会自动改设备挂高,绕过你的标定
0x29屏蔽区可选覆盖进水口/支架投影区;每块 13 B,最多 10 块

网页「演示用一键配置」发的就是 6 条 SET:0x25 → 0x26 → 0x27 → 0x11 → 0x17 → 0x18 (先写参数再切模式,避免设备用旧参数按新模式上报),并且走同一套「确认框 + 逐条等应答」流程。

7.3 挂高必须显式下发(本方案最容易静默错 1 m 的地方)​

事实后果处置
出厂/驱动默认 0x25 = 3000 mm你若按 2000 mm 换算却不下发,水位整体偏 1 m,而且没有任何报错① 连上后先 GET 0x25 回读;② 再 SET 0x25 = 页内设定;③ 页面把「回读 ≠ 设定」标红
换算始终用页内设定值主视图常显「使用挂高 XXXX mm」+ 口径行「换算用挂高 = …」,避免误读要让设备也改,必须点「下发配置」
用户尚未手动改过挂高时,页面首次回读会自动采用设备值出厂 3000 与默认 2000 差 1 m,静默偏 1 m 比误改更糟曲线会清空(口径变了)并在日志里写一行;用户改过之后就不再自动改,只标红 + 提供「采用设备回读值」按钮(该按钮不发任何帧)

7.4 水位标定(首次安装必做,约 5 分钟)​

换算:水位_mm = 挂高_mm − target_distance_mm, 其中挂高 = 天线罩下沿 → 水位零点(空罐水面/罐底零点)的垂直距离。

符号约定:空罐 → 距离 ≈ 挂高、水位 ≈ 0;水位 h → 距离 ≈ 挂高 − h。

步操作记录
S1容器空罐,卷尺量「天线罩下沿 → 水面」垂直距离 H0(精确到 5 mm)H0 = ____ mm
S2EN = 1,等 5 s,读 30 帧 target_distance,取中值 D0D0 = ____ mm
S3系统偏差 offset = D0 − H0(模组测距 vs 卷尺)。offset 绝对值 > 20 mm 时先查 G-3 结露、装歪,再考虑软件补偿offset = ____ mm
S4下发 0x25 = round(H0)——用卷尺真值,不要用 D0(避免把模组偏差写进挂高)回读确认
S5注水到满罐刻度 h_full,卷尺量 H1,检查 H1 + h_full ≈ H0(差 < 20 mm 视为合格)H1 = ____ mm
S6页面读数核对:水位显示 应 ≈ h_full,偏差记为本底精度判据:偏差绝对值 ≤ 1 个分辨率单元(≈80 mm)
S7(推荐)再取 1/3、2/3 两个水位点,线性拟合 水位 = a·D + b,检查 a ≈ −1(即 a 与 −1 之差 ≤ 0.05);不满足说明波束内有第二个反射面 → 回 G-1拟合结果归档

:::warning 口径提醒 不要把「挂高」设成「传感器到容器口」或「传感器到当前水面」的临时值——挂高是零点。 换容器、移位、改支架后必须重标。

精度预期:EDV163 距离分辨率约 8 cm,水位绝对精度按 ±1 个分辨率单元(≈80 mm) 预期。 所以判据是「同量级一致 + 重复性/相对变化」,不是「绝对准到 2 cm」—— 本方案不是计量级液位计,水位只显示整数 cm。 :::


8. 验证清单​

从插模组到看到水位曲线,逐项打勾。每一项都标了状态:已自测 表示无硬件验证已通过; 待实测 表示需要在 EDV163 实物上跑(当前全部未做,原因是模组固件不是水位版)。

#步骤期望现象状态✅
1确认模组是二进制固件版(GET 0x02 回 EDV163_VB)回显设备 ID 与固件版本待实测☐
2模组插 H3(RES A R T G V P 方向),USB-C 连 PC绿灯 ON 常亮待实测☐
3丝印 RADAR 红灯亮亮(= IO14 拉高、3.3V_RADAR 建立)待实测(板级灯行为已在人数统计版上实测,EDV163 模组下未复验)☐
4设备管理器「USB 串行设备」,VID 0x303A待实测☐
5烧录固件(4.1 / 4.2 / 4.3)「完成」或 Hash of data verified;烧 0x0 时体积 244,192 B待实测(体积与 SHA256 已由构建核实)☐
6帧校验工具自测py -3 tools\edv163_frame_check.py --selftest → 36 行对账全过、退出码 0已自测 ✅☐
7--raw-dump 看原始字节出现 45 44 开头、0A 结尾的帧;无任何日志文本待实测☐
8网页工具连接状态条波特率 256000,帧率 > 0待实测☐
9默认只读连接后只发 8 条 op=0xA0;op=0xA1 出现次数 = 0,「未确认 SET」= 0已自测 ✅(桩环境 44/44)☐
10页内「运行帧解析自测」10/10 通过(含 C3 转义、C8 旧 8B 口径、C9 静水面)已自测 ✅☐
11挂高回读 / 不一致标红回读有值;与设定不一致时配置区标红并提示偏移量已自测 ✅(模拟);真机 待实测☐
12下发配置:取消一条帧都不发(日志写「已取消」)已自测 ✅☐
13下发配置:确认逐条发、逐条等应答;3 条(0x25/0x17/0x18)全收到 0xA2/ACK已自测 ✅(模拟应答);真机 待实测☐
14一键配置 6 条0x25/0x26/0x27/0x11/0x17/0x18 全部收到应答;0x27 = 16 B、0x26 的 max ≥ 挂高已自测 ✅(模拟);真机 待实测☐
15收到 op=0xA3 / type=0x81 上报能完整解出 target_distance(mm);载荷自洽率 = 100%待实测☐
16转义实况日志里出现「N 处转义」标注;「转义错误」= 0待实测(自测里是构造帧)☐
17静水面水位持续更新;若显示「判定:无人(静水面)」而水位照常更新 → 正常待实测(自测用例 C9 已锁逻辑)☐
18手在模组下方 1 m 处移动距离读数随之变化约 1 m(定性验证测距链路通)待实测☐
19空罐distance ≈ H0(卷尺值 ±1 分辨率单元)待实测☐
20注水到已知刻度水位 = 挂高 − 距离 与刻度一致(判据见 7.4 S6)待实测☐
21静置 10 min距离漂移 < 2 个分辨率单元;无「突然归零/丢帧」待实测☐
2230 分钟静置采集坏帧率 < 0.1%、帧完整率 ≥ 99.9%、未归属字节率 = 0、转义错误 = 0、0x81 帧数 ≥ 1待实测☐
23浏览器目检(1280×720 / 1920×1080)整页无纵向滚动、顶栏吸顶、曲线自适应、收起日志后曲线变高未做(本轮环境禁止启动 Chromium,只做了 32 项静态布局契约)☐

第 22 项是本方案的验收标准。它现在没有数值——填表时请把条件(日期、端口、挂高、水位、固件版本)一起写进去。


9. 故障排查​

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

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

第①层 电源(看红灯 + 量电平)​

现象判据处置
RADAR 红灯不亮3.3V_RADAR 没建立量 H3 的 V/P 对 G 是否 3.3 V ±5%(3.14~3.47 V);确认插的是 H3;确认固件在启动后拉了 IO14
红灯亮但一点数据都没有供电 OK,问题在数据通路或模组固件进第②层;并先确认模组不是「挥手」等其他固件
红灯亮、拉低 EN 后不灭EN 极性/下拉异常断电排查,别带着问题插模组
USB 反复掉枚举供电能力不足(本方案几乎不会:雷达 < 0.1 W)换 USB 口/换线;长时采集优先用 5 V/≥1 A 充电器

第②层 帧完整性(PC 侧看字节)​

现象判据处置
一个字节都收不到没有数据到 PC① 波特率是否 256000(不是 921600);② 模组是否上电(红灯);③ 是否插 H4;④ 是否烧的 radar_bridge_edv163;⑤ 工作模式 0x18 是否 = 1;⑥ 模组固件是否是水位版
有字节、但找不到 45 44波特率不对 / 电平异常用已知可用的 USB-TTL 直连模组做 A/B 对照,先证明模组在发
有 45 44,帧长字段离谱(如 0x4B36)假同步:文本里出现了 "ED"(0x45 0x44)数据通路必须零文本输出;见 4.2 的静默做法
转义错误计数 > 0见下方「转义错误的三种症状」先修转义,其他判据都会被它带偏
帧头对、校验大面积失败字节被插入或丢失若同时混着可打印文本 → 日志污染;否则怀疑接触不良、线太长

转义错误的三种症状(EDV163 独有,必须能认出来):

症状线上发生什么计数器
帧中途裸 0x0A该帧还没收够声明长度就遇到 0x0A → 判截断帧、按帧尾处理、丢掉这半帧「坏帧」上升;日志出现「帧尾 0x0A 提前出现」
非法转义序列(09 后跟的不是 00/01)可能是误码打在转义对上,或发送侧漏转义「转义错误」上升
按线上字节数切帧长度域按转义前算,线上字节更多 → 长度非法 / 校验和错「坏帧·长度非法」或「坏帧·校验和」上升

:::tip 一句话记住区别 转义错 = 「帧被切错位」(能看到 45 44、但帧结构乱);波特率错 = 「整段丢字节」(一个字节都看不到)。 这两类现象的处置完全不同。 :::

第③层 协议语义(工作模式 / 上报频率 / 挂高 / presence)​

现象判据处置
有应答、没有 0x81工作模式 = 0,或上报频率 = 0GET 0x18 是否 = 1;GET 0x17 是否 = 0;必要时下发
0x81 有但 distance 恒 0无回波:水面太远/太近、镜面被破坏、罩上有水膜查 G-2/G-3/G-5;用平板做目标先排除水面问题
看到「判定:无人(静水面)」正常现象:静止水面被判无人(人体存在算法)不要按 presence 过滤;网页已直接读距离。若自研上位机按 presence 过滤 → 水位会长期断流(G-4)
水位整体偏固定值挂高设错(出厂 3000 mm 的坑)按 7.3 回读 + 重下发 + 按 7.4 标定
水位跳变 / 读到「假水面」罐壁/支架多径收窄 0x27 到 ±400 mm;加屏蔽区/挡圈(G-1)
载荷自洽率 < 100%tlv_len ≠ 1 + 7×count → 步长口径不对看帧校验工具 channel_stride:锁定 8 = 固件按旧文档口径(6.5 勘误)

9.2 ⚠️ 串口助手看到「乱码」是正常现象​

用串口助手(SSCOM / XCOM / Arduino 串口监视器)以文本模式打开这个端口,你会看到满屏乱码、 方块、?,偶尔蹦出 ED 两个字母——这不是故障,这是二进制协议帧。

你看到的真相
一片乱码每帧是 45 44 … 的二进制,含大量不可打印字节(\x00、\x09、\x0a…)
偶尔出现 ED帧头 0x45 0x44 正好是 ASCII "E" "D"
看起来「重复的怪符号」每 1 s 一帧,文本模式下一屏几百帧堆在一起
满屏空白/只有换行帧尾 0x0A 在每个帧末尾,文本模式把它当换行 —— EDV163 比人数统计版更容易让人误判

怎么正确看:切到 HEX / 十六进制模式;或者干脆别用串口助手——用 5.1 的网页工具(它懂协议), 想统计帧质量就用 9.4 的命令行工具(它给 PASS/WARN/FAIL 结论)。

同理:不要用「串口助手能看到字」判断链路正常。能不能收数据,只看 HEX 模式里有没有合法帧。

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

#现象根因处置
1照抄人数统计版配置,一帧都收不到波特率仍是 921600(本方案是 256000)核对 GET 0x04 枚举 = 5;固件 APP_EDK60_EDV163_BAUD = 256000
2帧头能对上,但校验和/长度全错用了「长度 = 11 + N」的旧口径(本方案是 12 + N,含帧尾),校验和位置也差一位长度按 12+N、校验和在 总长−2、帧尾是末字节
3数据里出现 0x0A 后帧就断了,坏帧持续增长没做转义还原(或先加帧尾再整段转义)先还原 → 再按转义前长度切帧 → 再验校验和(6.3)
4单通道帧正常、双通道帧全错按「8 字节/通道」解析(协议文档笔误)改成 7 字节/通道(6.5 勘误)
5水位整体偏 1 m,且没有任何报错出厂挂高 3000 mm,忘记下发 0x25 = 2000连上先 GET 0x25 回读,再 SET,再按 7.4 标定
6静水面长时间没有水位自研上位机按 presence = 1 才取距离直接读 target_distance(G-4)
7水面正对着进水口,读数乱跳水面扰动 + 飞溅水膜移位、静水桶、浮子靶、中值滤波
8数据流里混进可打印文本,解析器不停重同步固件打了日志——本项目名 EDK60 前两字节就是帧头,且换行 0x0A 就是帧尾零 printf:日志级别 + 横幅 + 引脚表 + 源码四处一起关
9为了「让 USB 上只有数据」关掉 USB 第二控制台,结果启动卡死、USB 不枚举该选项连带关掉 USB Serial/JTAG绝对不要关;用「不产生字符」实现洁净
10合上盖子后距离突然变短,开盖恢复天线罩内表面结露水膜(G-3)罩朝下外凸、干燥剂、疏水涂层;装在蒸汽源上方
11以为「插上就能测水位」,GET 0x02 却回别的型号/无应答模组固件不是水位/测距版(当前阻塞项)换固件(附录 C ①)

9.4 可复现的验证与取证(第三方照做即可)​

工程里带了零第三方依赖的帧校验脚本 tools/edv163_frame_check.py:

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

# ② 主证据:30 分钟静置采集(需要 pyserial;工具默认只读,不发任何 SET)
py -3 tools\edv163_frame_check.py --port COM6 --baud 256000 --duration 1800 `
--save-raw capture.bin --csv level.csv --raw-dump --mount-mm 2000 --out evidence

判据(P0 + 8 条硬指标):有效帧数 ≥ 1(P0,否则其余 SKIP 并判 FAIL); 转义错误 = 0(P1);未归属字节率 = 0(P2,0~0.1% 记 WARN 但必须点名来源); 重同步 ≤ 3 次/30 min(P3);坏帧率 < 0.1%(P4);帧完整率 ≥ 99.9%(P5); msgid 跳号率 < 0.1%(P6);0x81 载荷自洽率 = 100%(P7);0x81 帧数 ≥ 1(P8)。 退出码 0 = PASS、1 = FAIL。

读报告时特别看这三行(它们是 EDV163 独有的):

行期望为什么
转义错误数0转义一错,后面的长度/校验统计都建立在错误切分上
还原的转义对 / 含转义的帧都 > 0若两者都是 0,说明这 30 分钟里根本没有 0x09/0x0A 数据字节,转义路径等于没被检验——必须在验收记录里注明,并用边界点位补测
report_0x81.channel_stride7锁定 8 = 固件按旧文档口径发,与驱动 7 字节解析冲突(6.5)

工具只读不写:它不主动发 SET,工作模式/上报频率/挂高需要由网页工具事先设好, 并在开测前一次性设完(避免测试中途的 SET 应答混进统计)。


10. 已知边界​

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

#边界说明
1未实机验证(最大边界)固件、网页、工具都已就绪并通过自测,但没有一条上板用例被跑过。所有「帧率、坏帧率、精度、漂移」类结论目前都不存在,本文一处都没编。
2精度只有 8 cm 级距离分辨率约 8 cm,水位绝对精度按 ±1 个分辨率单元(≈80 mm) 预期。适合趋势/相对变化(注水、排水、阶跃),不是计量级液位计。页面因此只显示整数 cm。
3静水面可能被判「无人」模组本质是人体存在检测算法。页面已绕开 presence 过滤,但「距离仍然有效」这件事本身也待实测确认(T-02)。
4波纹/泡沫/结露/多径波纹 > 0.6 mm 即破坏镜面回波;0.1 mm 水膜即明显衰减;±50° 在 2 m 处覆盖半径 2.4 m,远大于 1 m 容器 → 罐壁多径。三者都只能缓解(静水桶/浮子靶/挡圈/中值),不能根除。
5近距盲区未知最小可测距离(近场/盲区)没有规格标注也未实测(T-03)→ 满罐水位上限不敢写死,只能用「设计水位工作带 0~1500 mm、预留 ≥500 mm 近距余量」这种保守说法。
6通道语义待确认0x81 带 channel 字段,count 可为 1~3;本 demo 在实测前只能按「单通道」假设设计。多通道各自对应哪路天线、通道号与实际安装位置的关系待上板确认。本方案与目标 ID 无关:不追踪、不合并、不做多通道融合/平均。
70x28 / 0x29 未使用0x28(自动测高)不发——它会自动改设备挂高,绕过你的标定;0x29(屏蔽区)只在协议里认类型名,不解析 13 B×N 结构,也不做图形化编辑。
8设备侧是否真的转义,待证驱动接收路径不还原转义(按在线长度切帧),所以「上报帧到底有没有 0x0A/0x09」只能由 PC 侧证明。若设备不转义而正文恰好含 0x0A,页面会把该字节当真帧尾 → 只丢这一帧并重同步(不污染后续),此时「坏帧」计数会上升。
9协议文档 8B 笔误已按驱动源码定为 7 B/通道;文档在组件库仓库,本项目只提供证据,不改他人文件。若将来遇到真按 8 B 发的固件,解析器会显式失败并点明口径,不会静默出垃圾数据。
10T-01 接线悬念未定论H3 的 A/R 两脚网络「读图 vs 实测」不一致,尚未用万用表定论。定论前不要插满脚。
11只验证了「USB-C 直连 PC」这条路未实测电流/浪涌(T-05);未使用 DC-005。若走 DC-005,必须 7~12 V(板上是 LM2596 降压)。
12未做长期老化计划里的最长用例是 30 分钟(另有 60 分钟加分项),没有 24 h / 7 天数据,也没有温漂、结露环境的量化结论。
13浏览器与页面限制Web Serial 只在 Chrome / Edge 89+ 可用,需 https 或 localhost;Firefox / Safari 不支持。页面不写本地存储、不采集数据、不提供 CSV/截图导出(数据全在内存,近 10 分钟窗,刷新即清空)。
14不承担计量/安全结论这是技术演示:水位是「挂高 − 雷达距离」的换算结果,未经计量标定,不可用于结算、报警、防洪等有责任后果的场景。

附录 A · 参数与命令帧速查​

下表所有帧按本文 6.1 / 6.3 / 6.6 的组包规则(长度 12+N、逐字节求和 &0xFF、正文转义、帧尾 0x0A) 程序化生成并逐字节复核,msgid = 0x0001。它们是按规则生成的帧,不是设备抓包; 发送前仍建议用你自己的脚本现算一遍。

只读帧(GET,安全,先跑通通道再用):

用途type帧(含帧尾)线上长度
产品信息0x0145 44 00 0C 00 01 A0 01 00 00 37 0A12 B
模块信息(主验证)0x0245 44 00 0C 00 01 A0 02 00 00 38 0A12 B
检测延时0x1145 44 00 0C 00 01 A0 11 00 00 47 0A12 B
上报频率0x1745 44 00 0C 00 01 A0 17 00 00 4D 0A12 B
工作模式0x1845 44 00 0C 00 01 A0 18 00 00 4E 0A12 B
挂高(必查)0x2545 44 00 0C 00 01 A0 25 00 00 5B 0A12 B
检测高度0x2645 44 00 0C 00 01 A0 26 00 00 5C 0A12 B
检测范围0x2745 44 00 0C 00 01 A0 27 00 00 5D 0A12 B

写入帧(SET,会改设备配置,逐条等应答):

用途帧(含帧尾)备注
检测延时 = 5 s45 44 00 0E 00 01 A1 11 00 02 00 05 51 0A最小 2
上报频率 = 10(1 s)45 44 00 0E 00 01 A1 17 00 02 00 09 01 5C 0Avalue = 0x000A 被转义成 09 01,声明 14 B / 线上 15 B
工作模式 = 1(正常)45 44 00 0D 00 01 A1 18 00 01 01 52 0A为 0 会完全没有 0x81
挂高 = 2000 mm45 44 00 0E 00 01 A1 25 00 02 07 D0 37 0A出厂 3000,必须显式下发
检测高度 0~2000 mm45 44 00 10 00 01 A1 26 00 04 00 00 07 D0 3C 0Amax 不得小于挂高
检测范围 x,y = ±400 mm45 44 00 1C 00 01 A1 27 00 10 FE 70 01 90 FE 70 01 90 FE 70 01 90 FE 70 01 90 7A 0A16 B:运动区 x/y + 存在区 x/y(FE70 = −400、0190 = +400)
30 min 强制无人 = 045 44 00 0D 00 01 A1 1D 00 01 00 56 0A静止水面场景必关

网页「演示用一键配置」实际下发的 6 条是:0x25 → 0x26 → 0x27 → 0x11 → 0x17 → 0x18(顺序不可颠倒)。 若某条 SET 收不到 0xA2/ACK,先退回发一条 GET 确认通道,不要反复重试。


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

维度人数统计版(EDV11P,已跑通)水位版(EDV163,未实测)照抄旧方案的后果
波特率921600256000一个字节都收不到(帧错误让驱动整体丢字节,不是乱码)
帧尾无固定 0x0A切帧逻辑缺一层;且日志换行 = 帧尾 → 日志污染后果升级
转义无有:0x0A→09 01、0x09→09 00(帧尾不转义)正文含 0x0A/0x09 时全帧错位,长度/校验连带错
长度口径11 + N(无帧尾)12 + N(含帧尾)校验和位置差一位 → 每帧判坏
上报载荷0x70:zone + 目标 x/y/z0x81:count + 每通道 7 B(含 target_distance mm)解析器必须重写;字段位置完全不同
单通道字节数每区 2 B 头 + 每目标 7 B每通道 7 B(协议文档写 8 B 是笔误)多通道帧整体错位 1 字节
业务换算无(直接画坐标)水位 = 挂高 − target_distance需要标定与参数管理;挂高错 → 全量程偏
安装姿态侧装、绕 +y 倾斜 60°、挂高 200 cm吊装、天线朝正下方、与法线 ≤ ±5°姿态语义完全不同,坐标/角度不可互推
目标特性人体(有微动,存在检测友好)水面(静止、镜面、易被波纹/结露破坏)本方案最大的技术不确定性
算法假设面向人体 RCS 设计水面目标可能被判「无人」(delay_presence = 0)按 presence 过滤 → 水位长期断流
供电启动峰值 < 1200 mA(头号风险,需 DC-005 ≥2 A)典型 11 mA、< 0.1 W本方案供电无忧(LDO 余量 ≥50×),但不要照抄「DC-005 接 5 V」(板上是 LM2596 降压,要 7~12 V)
上位机网页版 track.html + 厂商桌面端只有网页版(本方案无 EDV163 桌面端)拿旧桌面端读 0x81 会解出错值
帧校验判据条数P0 + 6 条P0 + 8 条(新增转义、载荷自洽、0x81 帧数;坏帧由 4 类扩到 6 类)引用验收判据时要写清用的是水位版

附录 C · 随仓库提供的工具与待补清单​

C.1 随仓库提供的工具​

下面这些随 demo 仓库一起提供(按仓库相对路径使用;本页不提供下载):

工具用途依赖
tools/edv163_frame_check.py帧校验与验收:无硬件自测(36 行对账)+ 实时采集 + 判据报告(转义错误 / 未归属字节率 / 帧完整率 / 0x81 载荷自洽率),退出码 0 = PASS无;实时采集需 pyserial
release/level.html网页水位工具:水位曲线 + 水位柱 + 大字读数,默认只读Chrome / Edge 89+
固件源码(demo radar_bridge_edv163)纯字节透传桥需要源码包请发邮件到 support@easydetek.com

C.2 待补清单(需要实测回填的 10 项)​

按影响从大到小。填上之后请把「待实测」改成实测值,并在本表标记日期。

#待补项影响怎么补
①EDV163 水位/测距版二进制固件(当前手持模组是「挥手」固件,0x45 0x44 一帧没有)阻塞全部上板验证——没有它,②~⑦ 都做不了向雷达固件负责人索取该版本固件并烧到模组;烧后 GET 0x02 应回 EDV163_VB
②30 分钟静置采集的判据值(坏帧率 / 帧完整率 / 未归属字节率 / 重同步次数 / 0x81 帧数)文首验证状态表与第 8 节第 22 项的验收结论都是空的按 9.4 跑 --duration 1800 --save-raw --csv,把报告里 P0~P8 抄进来
③真实含转义的上报帧原始字节(6.4 用的是自测构造帧)读者无法对照真机字节;也无法证明「设备确实做转义」采集时加 --save-raw,从 capture.bin 里截一条含「N 处转义」的帧贴进 6.4 / 6.5
④卷尺标定与本底精度(H0/D0/offset、满罐偏差、三点线性拟合斜率)无法量化「水位准不准」;7.4 的 S3/S6/S7 三格都空着按 7.4 S1~S7 走一遍,记录每次卷尺读数与 30 帧中值
⑤presence=0 时 target_distance 是否有效(T-02)决定「静水面能否长期出水位」这个核心假设静水面静置 10 min,统计帧内 distance 与 presence 的组合分布
⑥最小可测距离 / 近场盲区(T-03)决定满罐水位上限(当前只能保守写 0~1500 mm 工作带)模组朝下,用平板从 2000 mm 每 100 mm 移到 100 mm,每点停 10 s 看距离
⑦启动峰值电流与 3.3V_RADAR 上升时间(T-05)决定「EN 后等 200 ms」能否缩短串 0.1 Ω 采样电阻 + 示波器;或按 200→100→50 ms 缩短等待看何时开始丢首帧
⑧出厂波特率枚举与 0x25 出厂值(T-07)确认「出厂 3000 mm」是否也存在于模组侧GET 0x04 看是否 = 5(256000);GET 0x25 看回读值
⑨T-01 接线定论(H3 的 A/R 究竟落在 IO5 还是 IO0/IO1)关系到「输出对输出顶牛」的硬件风险断电万用表通断 + IO5 输出跟随测试(3.2 的三步)
⑩浏览器像素级目检两张截图(1280×720 / 1920×1080)+ 部署后对本页三个静态链接做一次可达性自检布局只做了 32 项静态契约;静态资源虽已就位,但站点需重新部署才对外可见在有桌面的机器上按第 8 节第 23 项目检并截图;部署后逐个点开 flash.html / level.html / .bin 确认可达

许可与署名​

本项目代码以 MIT License 发布,作者 @fuhua817。 EDV163 串口协议部分参考组件库内的《EDV163 串口通用协议》,版权归原厂所有; 本文与实现以驱动源码为准(协议文档 §3 的「每通道 8 字节」为笔误,见 6.5)。

:::danger 免责声明 本项目是技术演示与方案验证用途。水位是「挂高 − 雷达距离」的换算结果,未经计量标定, 不可用于防溢流保护、防洪预警、贸易结算或任何有责任后果的决策场景。 用于实际项目前,请按目标市场的无线电、数据与安全法规完成相应合规评估。 :::