简介：面向嵌入式开发者的VL53L4CD液位检测方案，适用于智能水杯、工业储罐及环境监测等高精度非接触测量场景。资源基于STM32G431平台，完整涵盖传感器驱动移植、非线性校正算法与不同液体/容器条件下的实测分析，并附带可运行的Keil工程、烧录固件和PDF说明文档。包内共303个文件，以C源码（61个c）与头文件（134个h）为主，分别承担HAL驱动、寄存器配置和数据结构定义；另有HAL库配置、链接脚本、Python辅助脚本，以及uvprojx/ioc等Keil工程文件，方便直接编译和调试；PDF文档提供原理图、调试指南及实验数据分析，压缩包整体约109MB。目前已有169人学习，适合中高级嵌入式开发者及电子竞赛备赛者参考。借助这份资料可快速掌握VL53L4CD的I2C驱动集成、ToF测距参数调优，以及针对不同液位场景的非线性误差修正方法，有效缩短智能水杯等液位检测产品的开发周期。
1. VL53L4CD液位监测的现实约束比测距更难
VL53L4CD是ST的ToF激光测距传感器，摊开数据手册，标称测量范围1mm到1300mm，一个I2C接口加几行配置就能读到距离。很多人第一反应是拿它做水罐、油箱或冷却液容器的液位监测，觉得“不过是量一下到液面的距离”。真正落地时会发现，读距离只是第一步，确定“哪一次读数才是液面”才是「液位检测」四个字的实际分量。水面会波动，水泵启动会翻起浪花，水在940nm近红外波段吸收强、反射回波微弱，而容器底部的金属或泥沙回波反而可能比液面更强，于是算法要在几十毫秒内决定：保留这帧距离、把它放进平滑窗口、还是直接丢弃。这篇就写从VL53L4CD的数据读取到液位状态判定完整走通的实现方法，适合要接手车载尿素箱、农业储水罐、工程机械液压油箱这类场景的工程师。
2. VL53L4CD测距原理里决定液位成败的3个特征
2.1 ToF测半透明液面时，回波特点与白墙完全不同
VL53L4CD用飞行时间测距，不是三角反射，而是发射一个红外光脉冲、统计光子从传感器到目标再返回的时间。940nm这个波长在水的吸收带上，入射光大部分被水吸收，真正从气液界面反射回来的分量远低于白墙或者金属。于是水面回波的典型表现是：距离值能出来，但信号幅值比常见固体目标低一个量级，同时距离估计的抖动明显变大。
ToF和超声波方案在液位场景里的差异也在这里。超声波看的是声波阻抗差，液体和空气的界面反射清晰；ToF看的是光强统计，弱回波下每一帧测量结果附带的不确定度都不同。VL53L4CD内部会把所有SPAD收到的光子统计成直方图，估算出一个距离值，同时给出Sigma，也就是这一帧距离估计的标准差，单位mm。Sigma比距离值更能表达“当前帧能不能信”。这里要先建立一个概念：后面所有液位检测算法处理的不是单个距离数，而是“距离、信号强度、Sigma”三元组。
2.2 Timing Budget、Distance Mode与更新率的取舍
VL53L4CD允许配置Timing Budget，即每一帧测距的累计时间预算。预算越长，芯片采到的光子数越多，弱回波下的精度越高，但单帧耗时也越长。液面变化是慢变量，一秒更新10次已经非常充裕，所以不要为了“看起来反应快”把Timing Budget压到10ms。我一般做液位场景给20ms到50ms，更新率大约在20Hz到50Hz之间，既保证弱回波下的有效帧率，又不会让滤波窗口过于敏感。
距离模式要选Long Distance Mode。长距离模式会提高远端灵敏度，对液面这种弱回波目标更有利。但代价是近端精度略微下降，加上SPAD阵列在近距离下会有饱和效应，实际可靠的起始距离通常从10mm到30mm才开始。这就是液位监测里的“近距盲区”，安装尺寸设计时必须预留，不能等装到设备上再发现满罐状态测不准。
下面是一份我在液位项目里常用的初始参数表：
| 参数项 | 推荐值 | 说明 |
|---|---|---|
| Timing Budget | 20000~50000us | 水面波动大时取50ms，波动小时可降到20ms |
| Distance Mode | Long | 提升弱回波目标的检测概率 |
| Sigma合格线 | 40mm | 超过即认为该帧质量不可信 |
| 最小有效距离 | 30mm | 近端盲区，小于此值一律按满罐处理 |
| 单帧更新周期 | 66ms | 配合Timing Budget预留一定余量 |
2.3 Signal Rate是把水回波和底部回波分开的第一道门
VL53L4CD每帧结果里带Signal Rate，单位MCPS，也就是每秒接收到的光电子计数率。白墙回波通常能做到1到2 MCPS以上，透明水面的回波可能只有几百kCPS，甚至更低。所以用固定阈值判断“有没有被测到目标”，会误杀掉正常的水面数据；反过来，如果完全不看Signal Rate，金属罐底和泥沙层的强回波又会把距离值稳定吸引过去。
常见做法是标定时采集一段空罐和半罐数据，看Signal Rate的分布区间。比如空罐时读到的底部回波是1200kCPS，半罐时水面回波是300kCPS，那么阈值放在400kCPS左右，既保留水面帧又不会把底部强回波当成液面。这个标定过程不能省，因为水质、罐体颜色、安装角度都会明显改变回波强度。
3. VL53L4CD读取液位距离的最小驱动实现
3.1 初始化与单帧读数的驱动骨架
这里贴一段基于ST ULD API风格的C代码，底层I2C读写函数按你自己的平台封装即可。重点看初始化和结果读取的处理逻辑。
#include "vl53l4cd_api.h" VL53L4CD_Dev_t dev = {0}; void liquid_level_init(I2C_HandleTypeDef *hi2c) { dev.I2cHandle = hi2c; dev.I2cDevAddr = 0x52; // 7位地址0x29左移一位成8位地址 uint8_t id = 0; VL53L4CD_ReadID(&dev, &id); if (id != VL53L4CD_ID) { // I2C地址错误或传感器未就绪，需要在这里处理，不能继续往下走 return; } VL53L4CD_SetDistanceMode(&dev, VL53L4CD_DISTANCEMODE_LONG); VL53L4CD_SetTimingBudget(&dev, 50000); // 单位us，50ms VL53L4CD_SetInterMeasurement(&dev, 66); // 两次自动测距间隔66ms VL53L4CD_StartRanging(&dev); }初始化顺序有讲究：先读传感器ID，确认I2C链路和传感器上电状态正常，再配置距离模式和Timing Budget。SetTimingBudget参数单位是微秒，50000就是50ms。SetInterMeasurement设置的是连续测距模式下两次测量的间隔，必须大于Timing Budget，否则设备内部会产生欠时错误。VL53L4CD一旦StartRanging之后就会按周期自动出数，主控只需要定时去取。
每帧取数代码：
VL53L4CD_Result_t res; VL53L4CD_GetResult(&dev, &res); if (res.Status == VL53L4CD_STATUS_OK) { current_range_mm = res.Distance; current_signal_mcps = res.SignalRate; current_sigma_mm = res.Sigma; } else { // 当前帧不可信，直接丢弃，保留上一次有效值 }Status非0时表示这一帧测量无效，比如Sigma超限、信号过低或没有检测到目标。这里容易犯的错是把单帧失败当严重故障处理，实际上弱回波场景下偶发丢帧是正常现象，真正的判定逻辑要放在后级滤波里。
3.2 多路液位传感器共用I2C总线时的地址枚举
工程设备往往不止一个液位测点，比如液压油箱的油位和补油桶的液位同时监测。多颗VL53L4CD出厂默认地址一样，直接挂同一条I2C总线必然冲突，需要利用XSHUT引脚逐个上电并修改地址。
#define MAX_DEV 4 void enable_sensor(int index) { // 先把所有传感器shutdown，保证总线上只有一颗设备 for (int i = 0; i < MAX_DEV; i++) { set_xshut(i, 0); } delay_ms(2); // 只唤醒目标传感器 set_xshut(index, 1); delay_ms(5); dev.I2cDevAddr = 0x52; uint8_t id = 0; VL53L4CD_ReadID(&dev, &id); if (id != VL53L4CD_ID) { return; } // 把当前设备地址改到新地址，例如0x54、0x56…… uint8_t new_addr = 0x52 + (index + 1) * 2; VL53L4CD_SetDeviceAddress(&dev, new_addr); }XSHUT拉低进入shutdown，拉高重新上电。每颗传感器唤醒后先读ID确认在线，再写入新地址。注意传感器地址改变后，当前I2C事务结束即刻生效，后续读写都必须用新地址。另外XSHUT掉电后内部配置全部丢失，所以每次枚举完成都要重新执行距离模式和Timing Budget配置。
3.3 距离到液位的换算和安装盲区处理
液位不是直接等于测距结果，而是按安装几何关系换算的。设传感器安装位置到容器底部的高度为H，实测距离为d，液位深度就是：
L = H - d - offsetoffset是传感器有效测量零点到传感器外壳底面的机械间距，不同支架和镜窗结构取值不一样，最好用卡尺量完后在固件里存成可标定参数。满罐状态下d等于盲区深度，所以液位上限要钳位在H减去30mm左右，避免近距饱和值参与控制逻辑。
我一般在设备上电时做一次空罐自检：如果读到的d接近H，正常；如果明显大于H，说明安装高度配置错了，或者传感器视窗被污染。这个自检逻辑简单但能避免大量现场误报警。
4. VL53L4CD液位检测的滤波、状态机与标定
4.1 中值滤波与均值平滑的组合
水面不可能绝对静止，水泵运行时液位每秒波动几十毫米很常见。直接拿瞬时距离算液位，结果会在真实液位附近大幅跳变。我为液位场景做的是两段式处理：先中值滤波剔除离群帧，再做滑动平均压缩高频抖动。中值滤波窗口取15帧，大约覆盖1秒数据。
#define WINDOW 15 int32_t history[WINDOW] = {0}; int32_t median_value = 0; void update_median(int32_t new_sample) { // 环形缓冲保存最近WINDOW帧 for (int i = 0; i < WINDOW - 1; i++) { history[i] = history[i + 1]; } history[WINDOW - 1] = new_sample; int32_t tmp[WINDOW]; memcpy(tmp, history, sizeof(tmp)); // 冒泡排序找中值，数据量小可以直接用 for (int i = 0; i < WINDOW - 1; i++) { for (int j = 0; j < WINDOW - 1 - i; j++) { if (tmp[j] > tmp[j + 1]) { int32_t t = tmp[j]; tmp[j] = tmp[j + 1]; tmp[j + 1] = t; } } } median_value = tmp[WINDOW / 2]; }这段代码里，每次只移出最老的一帧，移入最新一帧，然后对拷贝数组排序取中值。WINDOW取15，如果要更快的响应可以减到9，要更稳可以增到21。注意只有通过上一章有效帧判定的距离才能送进这个窗口，失败帧不能顶替正常帧，否则会把离群点引入统计。
中值滤波输出后接均值平滑，比如维护最近5个中值的平均。液位检测不是高带宽伺服，通常不用做得很复杂，两级处理之后，液位输出已经相当稳定。
4.2 Signal Rate和Sigma的有效帧把关
有效帧判定是整个液位检测算法的前闸门。有两类帧必须被拦截：一类是有距离读数但回波其实来自噪声的假帧，另一类是液面回波太弱导致测距质量严重下降的帧。
#define SIGMA_LIMIT_MM 40.0f #define SIGNAL_LIMIT_KCPS 400.0f #define RANGE_LIMIT_MM 1200 int is_valid_frame(VL53L4CD_Result_t *res) { if (res->Status != VL53L4CD_STATUS_OK) { return 0; } if (res->Sigma > SIGMA_LIMIT_MM) { return 0; } if (res->SignalRate < SIGNAL_LIMIT_KCPS) { return 0; } if (res->Distance > RANGE_LIMIT_MM) { return 0; } return 1; }Signal Rate阈值按现场标定结果填写，透明清水的回波可能只有白墙的十分之一。Sigma阈值取40mm是经验值，静止液面正常情况下Sigma在5到15mm之间，如果超过40mm说明液面波动剧烈，输出的距离值已经不适合参与液位计算。Range Limit上限用于排除容器底部以外的杂散目标。
4.3 液面丢失与底部强回波的状态机判定
滤波层只能处理噪声，不能处理原理性误判。液位监测里最常见的误判是这个场景：液面已经降到很低，传感器主回波信号变弱，这时容器底部的强反射成为最大回波，设备输出“液位正常偏高”，实际罐里快空了。
面对这种情况，我采用一个不多余的状态机，把有效帧和无效帧组织成工程语义：
| 状态 | 进入条件 | 输出 |
|---|---|---|
| IDLE | 初始化 | 不输出有效液位 |
| MEASURE | 连续1s存在有效帧 | 输出滤波后液位 |
| LOST | 0.5s无有效帧 | 保持上一次液位，标记低置信 |
| FAULT | LOST持续超过5s | 输出无效液位并产生维护信号 |
这个状态机解决的核心问题是：单帧或多帧失败时，不立刻变化输出，给重建测量留出缓冲；只有持续丢帧达到5秒，才判定液位信号真正不可用。在MEASURE状态里还会做一次“回波归属”检查，比对当前Signal Rate和底部参考值，如果发现信号强度明显高于液面特征，而距离又接近标定的空罐距离，就判定当前读数来自底部而非液面，强制转入LOST。
状态迁移的判定周期可以放在主循环里完成，也可以用定时器实现。核心是所有迁移条件都基于一段连续时间统计，不要因为一帧数据而跳变。
4.4 空罐、满罐两点标定
液位检测最终输出不是距离，而是百分比或体积。常规做法是两点标定加线性插值：把容器清空，记录有效滤波距离d_empty；再注入到设计满位，记录d_full。液位百分比就是：
level_percent = (d_empty - d) / (d_empty - d_full) * 100%这套换算没有乘上液面截面积，因为液位监测关注的是“高度量”，体积还需要另外引入容器容积表。两点标定能部分补偿安装倾斜带来的系统误差，但不能完全消除，所以安装时仍然要尽量让传感器光轴垂直于液面。
标定操作上，我建议固件保留一段标定模式，通过串口发送指令进入，自动记录50帧稳定数据的均值作为端点值，写入Flash。现场可以反复执行，不需要重新编译固件。
5. VL53L4CD安装与实测时的3个关键技巧
5.1 直接限制最大测距范围，排除底部假回波
VL53L4CD驱动中允许限制最大测量距离。把Range Limit设置成比空罐距离稍大的值，比如空罐时实测1000mm，就把限制放在1050mm，超出部分直接不予响应。这样做的好处是让传感器从硬件层忽略容器底部以后的一切回波，即使液面处于低液位、回波很弱，也不会跳到更远的真实底部。我的习惯是在完成空罐标定后回写这个参数。
5.2 用Signal Rate曲线诊断视窗污染
液位容器安装在潮湿环境里，传感器视窗凝露、挂水珠或结冰都会让光路衰减，表现是最终计算出的液位正常但Signal Rate随时间整体下降。在固件里把每次上电前10分钟的信号强度均值记录下来，后续实时Signal Rate降到参考值50%以下时，主动输出“传感器视窗污染提示”。这个技巧能比距离异常更早发现故障。
5.3 调试时输出四元组，不只看液位
最后给一个小习惯：调试串口按固定报文输出时间戳、Distance、SignalRate、Sigma和滤波后液位，一行一帧。水桶实测升降液面时，观察这组数据可以看到真实液面下降时Signal Rate的单调变化，滤除的杂散回波也会被看到。液位算法合不合适，不要只看最终百分比，四元组完整记录现场运行数据，后续排查问题会省掉大量“猜测式”工作。
本文还有配套的精品资源，点击获取
