简介：基于STM32F103与VL53L0X的红外测距工程，面向嵌入式学习者和物联网开发者，展示了如何通过I2C总线驱动激光测距传感器，实现基于TOF原理的高精度近距离测距。资源包含完整工程源码与编译产物，共239个文件，以C源文件、H头文件、O目标文件、CRF编译中间文件为主，另有UVProj/UVOpt工程配置、HEX/AXF烧录文件及MAP映射文件等，包体仅6.55MB，结构清晰，适合对照学习移植与调试流程。目前已有1548人学习下载。工程内容覆盖STM32F103的I2C初始化、VL53L0X寄存器配置与驱动编写、距离数据读取及滤波校准等关键环节，同时提供了错误处理与稳定性调试思路。通过学习可举一反三，为机器人避障、智能家居等场景快速搭建红外测距方案。 把VL53L0X接到STM32F103上之前，我以为它就是个高级点的红外测距传感器，I2C读一下就能拿到距离。真正开始调试才发现，“红外测距”这四个字虽然好记，但它描述的原理和传统红外反射式测距真不是一回事。这颗芯片是意法半导体自己的ToF（Time of Flight）方案，用一个940nm的VCSEL激光发射器加SPAD接收阵列，本质上就是一颗微型激光雷达，封装在4.9mm x 2.5mm的小体积里。这篇文章我会从选型、接线、驱动、校准到低功耗设计，把基于STM32F103驱动VL53L0X的完整过程和踩过的坑位梳理一遍，适合正在做机器人避障、液位检测、距离触发这类项目的朋友参考。
1. 从“红外测距”这个叫法说起：VL53L0X到底怎么测距离
1.1 先纠正一个称呼误区
很多人在选型时会拿VL53L0X和夏普GP2Y0A21那类传感器比较。GP2Y0A21是靠红外LED发射光，接收端检测反射光的强度或者三角测距的角度变化来估算距离，这是真正意义上的“红外测距”。这类传感器有一个很要命的特性：目标颜色越深，吸收红外光越多，同样距离下读到的ADC值越偏，而且环境光一强，整个测量值都会飘。
VL53L0X不太一样，它属于ToF方案，虽然也工作在红外波段（940nm），但它测的不是光强，而是光的飞行时间。也就是说，它看的是“光子从发射到反射回来花了多少时间”，而不是“反射回来还剩多少能量”。这就是为什么它在漆黑环境里能正常工作，测深色物体和浅色物体时的读数也不像红外反射式那样剧烈漂移。
1.2 ToF原理与“为什么说它是微型激光雷达”
ToF的原理你可以类比成站在山前喊一声，听回声来计算山离你多远。光速是恒定的，测出光子从发射到返回的时间t，距离就是 c×t/2。但问题是光速太快，一毫米的距离差对应的往返时间只有大概6.7皮秒，普通电路根本测不了这么短的时间，所以VL53L0X内部的做法不是什么单光子计时器，而是用SPAD阵列统计大量光子的到达时间分布，再做直方图分析，从噪声中把回波峰找出来。
这颗芯片的激光器功率很低，属于Class 1级，人眼安全，所以不需要像大功率激光雷达那样做复杂的安全屏蔽。它的视场角（FOV）大概是25度，官方标称量程最远2米，实际用下来白色墙面在室内接近2米没问题，深色亚光物体建议按1米左右规划。精度方面，传感器本身可以做到毫米级偏差，但受环境、目标材质和安装方式影响，实际项目里能稳定到正负3%以内已经算不错了。
1.3 为什么我用STM32F103而不是更高端的MCU
STM32F103算是一颗非常经典但又不会过时的芯片，主频72MHz，有硬件I2C，有足够的GPIO，加上价格非常便宜，资料铺天盖地。VL53L0X的常规测量频率在几十赫兹，每次测量需要几十毫秒，这个负载对F103来说完全不是问题，没有必要为了一个I2C传感器去上F4或者更高端的型号。
不过这里要单独提醒一下：F103的硬件I2C外设出了名的难伺候，后面我会专门展开说。很多工程师在F103上驱动这类I2C传感器时会直接用GPIO模拟I2C，这个选择并不可耻，反而是实践中很务实的一条路。
2. 接线上容易被忽略的三个坑
2.1 模块供电与5V兼容性
VL53L0X芯片本身供电范围是2.6V到3.5V，所以绝大多数模块都是3.3V供电。市面上一些模块为了方便用户，会在板上加一个LDO，允许VCC接5V，输出电压给传感器用。问题就出在这个“LDO版本”和“纯3.3V版本”的区分上：如果买的是带LDO的模块，VCC接5V没问题，I2C引脚的电平一般也被LDO拉到了3.3V；但如果你拿的是裸片或者无LDO模块，VCC一接5V，芯片可能当场烧掉。
STM32F103的GPIO虽然有一部分引脚标称耐5V（FT引脚），但VL53L0X并不是5V逻辑器件，I2C信号电平以上拉到3.3V最为稳妥。我见过有人把模块和F103开发板直接排针对接，模块VCC接5V，然后I2C上拉不知道接到了模块的VCC上，结果就是SCL/SDA电平长期在3.3V以上飘，I2C通信时好时坏。排查了很久才发现是电平匹配问题。所以在接线前一定要先看自己手头模块的原理图，搞清楚VCC是直连传感器还是经过LDO，I2C上拉电阻接到了哪个电源。
2.2 I2C上拉电阻
I2C总线必须有上拉电阻，这是协议的基本要求。VL53L0X模块大多在PCB上已经焊了4.7K或者10K上拉，但也有部分模块为了节省成本或方便用户自定义，没有上拉电阻。如果你用杜邦线把传感器和F103开发板连起来，又恰好模块没有上拉，那就会遇到非常讨厌的偶发性问题：有时能读到设备ID，有时读到的全是0xFF，有时初始化到一半就卡住。
我的建议是，无论模块有没有上拉，用I2C连接VL53L0X时都先用万用表确认一下SCL和SDA对地的电阻值。如果没有上拉，就在MCU侧外接两个4.7K电阻到3.3V。另外杜邦线不要拖太长，超过20厘米后信号边沿会变差，尤其I2C工作在400kHz快速模式下更容易出问题。短连线、加上拉、共地，这三件事做到位，I2C通信的稳定性会大幅提升。
2.3 XSHUT引脚：既是复位也是电源开关
XSHUT是VL53L0X的一个关键引脚，低电平时传感器被关闭（类似硬复位），高电平时正常工作。很多初学者只把它当成复位的工具，上电后直接拉高不管了。实际上，XSHUT在低功耗设计和多传感器组网中扮演着非常重要的角色。
先说低功耗：XSHUT拉低后，整个传感器进入近乎关机状态，电流可以降到微安级。相比让传感器一直待在待机模式，用XSHUT控制系统睡眠和唤醒要彻底得多。
再说多传感器：如果一条I2C总线上挂了多个VL53L0X，默认地址都是0x29，直接挂上去会冲突。正确做法是先把所有传感器的XSHUT拉低，然后逐个唤醒，每唤醒一个就通过I2C修改它的地址，改完再唤醒下一个。这个流程是官方手册明确推荐的，没有XSHUT管理，多传感器方案基本没法玩。
3. 驱动代码不能跳过的一步：从Boot到SPAD校准的初始化时序
3.1 硬件I2C还是软件I2C
F103的硬件I2C外设是个口碑两极分化的东西。有人用标准库的I2C驱动写得很流畅，也有人被主从模式切换、BUSY标志卡死等问题折磨到怀疑人生。如果你赶项目进度，或者不想跟硬件I2C的各种状态机纠缠，直接上GPIO软件模拟I2C是性价比非常高的选择。VL53L0X的I2C最高支持400kHz，F103用GPIO翻转模拟400kHz完全没问题，代码还更容易移植和排查问题。
软件I2C的核心就是按I2C时序把START、STOP、ACK、字节读写用GPIO实现出来：
void I2C_Soft_Init(void) { GPIO_InitTypeDef gpio; RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOB, ENABLE); gpio.GPIO_Pin = GPIO_Pin_6 | GPIO_Pin_7; gpio.GPIO_Mode = GPIO_Mode_Out_OD; gpio.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOB, &gpio); I2C_SCL_H(); I2C_SDA_H(); } void I2C_Soft_Start(void) { I2C_SDA_H(); I2C_SCL_H(); delay_us(2); I2C_SDA_L(); delay_us(2); I2C_SCL_L(); } void I2C_Soft_Stop(void) { I2C_SDA_L(); I2C_SCL_H(); delay_us(2); I2C_SDA_H(); delay_us(2); } uint8_t I2C_Soft_WriteByte(uint8_t data) { uint8_t i, ack; for (i = 0; i < 8; i++) { if (data & 0x80) I2C_SDA_H(); else I2C_SDA_L(); data <<= 1; I2C_SCL_H(); delay_us(1); I2C_SCL_L(); } I2C_SDA_H(); // 释放SDA，准备读ACK I2C_SCL_H(); delay_us(1); ack = I2C_SDA_READ(); I2C_SCL_L(); return ack; }写成这样之后，读和写寄存器就变成了打包操作。注意GPIO要配置成开漏输出，这样在外接上拉的情况下才能正确处理总线电平。
3.2 初始化流程里的关键节点
VL53L0X上电之后不是直接就能读距离的，初始化流程如果跳过了某几步，后面测距要么不启动，要么精度非常差。我梳理一下自己项目的初始化顺序：
- XSHUT先拉低，确保传感器处于复位状态，然后拉高，等至少2ms让芯片完成Boot。
- 通过I2C写0x80寄存器为0x01，触发软件复位，延时10ms后再写0x80为0x00。
- 读0xC0寄存器，确认设备ID为0xEE，这一步可以快速判断I2C通信是否正常，以及芯片是不是正品。
- 执行DataInit，读取NVM里出厂时写入的校准数据，这些数据每颗芯片都不同，API内部会把它加载到运行参数里。
- 执行参考SPAD校准（PerformRefSpadManagement），动态检查SPAD阵列中有效的像素，关掉坏点并调整接收灵敏度。
- 设置DistanceMode（短距离或长距离模式）和TimingBudget（测量耗时预算）。
- 如果是单次测量，每次测完再发启动命令；如果是连续测量，调用StartMeasurement后传感器会持续工作。
很多人觉得官方API太复杂，想跳过SPAD校准直接读寄存器。我这里直接说结论：不建议。SPAD校准做不好，远处目标测不到，近距离测量值跳变，官方API之所以把流程设计得这么繁琐，就是因为每颗芯片都有制造差异，出厂校准数据必须在运行时被正确使用。
3.3 单次测距的代码骨架
我用ST官方的API封装了底层I2C读写之后，读取一次距离的流程大概是这样的：
VL53L0X_Dev_t dev; VL53L0X_RangingMeasurementData_t result; // 这里需要把I2C读写函数挂到dev结构体的回调上 dev.I2cDevAddr = 0x29; // 初始化，包含DataInit、SPAD校准、模式配置 VL53L0X_DataInit(&dev); VL53L0X_SetDeviceMode(&dev, VL53L0X_DEVICEMODE_SINGLE_RANGING); VL53L0X_SetMeasurementTimingBudgetMicroSeconds(&dev, 33000); VL53L0X_SetVcselPulsePeriod(&dev, VL53L0X_VCSEL_PERIOD_VCSEL_PULSE_PERIOD_PRE_RANGE, 18); VL53L0X_SetVcselPulsePeriod(&dev, VL53L0X_VCSEL_PERIOD_VCSEL_PULSE_PERIOD_FINAL_RANGE, 14); // 启动单次测量并等待结果 VL53L0X_PerformSingleRangingMeasurement(&dev, &result); if (result.RangeStatus == 0) { uint16_t distance_mm = result.RangeMilliMeter; }如果你不用官方API，想完全自己写寄存器驱动，那要面对的就是一大串内部状态寄存器、校准数据加载、结果解析逻辑，代价远高于直接把API理顺。我的建议是初期一定要站在官方API的肩膀上，先把方案跑通，等充分理解流程后再决定要不要精简到裸寄存器。
4. 读到的数值总差几毫米？三步校准到位
4.1 误差不是恒定值：来源拆解
VL53L0X的测距误差不是简单的“固定偏大几毫米”或者“固定偏小几毫米”，它包含几个不同性质的误差分量。第一类是安装带来的系统性偏移，比如传感器没有完全垂直于被测表面，光路倾斜之后往返路径变长，读数会整体偏大。第二类是目标材质带来的反射率差异，黑色亚光材料回波信号弱，距离越远信噪比越差，表现为“测量值在一定范围内漂移”。第三类是环境光噪声，户外强阳光下，SPAD接收到大量背景光光子，直方图里的噪声底线抬高，误差会变大。第四类是视场角内多目标问题：FOV有25度，如果视场里有前景物体遮挡，后面又有一个较强的反射目标，传感器返回的目标不一定是你想要的那个“最近物体”，读数可能跳变。
所以排查误差时，先别急着改代码，应该用一个已知反射率的目标（比如白墙）在固定距离下反复测量，观察偏差是固定的还是随机跳的。固定偏差走校准流程，随机跳变就要考虑目标材质和视场环境的问题了。
4.2 单点偏移校准和十字串扰校准
最常用的校准是单点偏移校准（Offset Calibration）。方法是让传感器正对一个白色目标，距离设为100mm（官方标准流程用的距离），记录下实际测量值，计算偏移量offset，之后每次测距结果都减去这个偏移量。如果现场环境允许，可以多测几组取平均值，减少随机噪声影响。
还有一种情况是传感器安装在亚克力或者玻璃面板后面，发射光透过面板时会产生反射，这个额外光脉冲在传感器看来就像是一个近距离的固定目标，会让读数稳定地偏离真实值。这属于十字串扰（CrossTalk），需要做专门的CrossTalk校准。官方API里提供了对应函数，流程大致是：选择一个已知反射率的标准目标，放在已知距离上，运行校准函数，得到串扰补偿值。凡是加了保护面板的设备，这一步不能省，否则近距离精度会差很多。
4.3 校准结果掉电保存：用STM32片内Flash
问题来了：如果每次上电都执行一遍完整的校准流程，不仅耗时，还需要现场有标准目标。解决办法是把校准结果保存到STM32F103的片内Flash，下次上电直接加载。F103的Flash有大容量和中容量之分，大容量版本页大小是2KB，可以把最后一页用来存校准参数。定义一个绝对定位变量：
#define CALIB_ADDR 0x0807F800 // 512KB版本的最后2KB typedef struct { uint32_t magic; int16_t offset_mm; uint16_t xtalk_value; } CalibData_t; #define CALIB_MAGIC 0x564C5331在代码初始化时读取这个地址，检查magic是否匹配。匹配就直接使用校准参数；不匹配则执行一次完整校准，然后写入Flash。写Flash之前必须先擦除整个页，因为STM32的Flash只能把1写成0。这个操作会阻塞CPU一小段时间，不要在测量循环里触发。另外校准数据写入频率一定要低，因为Flash的擦写寿命通常在1万次左右，每次修改都写Flash的话，用不了几年就磨损了。
5. 低功耗场景：STM32停机模式下传感器该怎么配合
5.1 三个功耗层级
很多项目做的是电池供电的便携测距设备，这时候低功耗就变成绕不开的话题。先看VL53L0X的功耗层级：测量工作时动态电流通常在几十毫安，待机模式能降到微安级，而XSHUT拉低后可以到接近关机状态。STM32F103这边也有对应的几个工作模式，其中最常用的是Stop模式，功耗可以降到几微安级别。
低功耗系统的正确组合是：常态下F103进Stop，VL53L0X被XSHUT拉低或者干脆断电；需要测距时，用定时器或者外部事件唤醒MCU，启动传感器做一次单次测量，拿到结果后立刻关掉传感器，再让MCU回到Stop。这样整个系统的平均功耗可以控制得很低，而不是让传感器一直处于连续测量状态。
5.2 单次测量+停机唤醒的配合时序
这里有个容易掉进去的坑：很多人把VL53L0X配置成连续测量模式，然后让MCU进Stop，以为传感器会自己测完自己待机。实际上连续测量模式下传感器内部一直在跑测距循环，功耗不可能降下来。低功耗方案必须用单次测量模式。
我的代码流程是：RTC定时唤醒或者外部触发唤醒后，先把XSHUT拉高，等2ms让传感器完成Boot，然后执行精简初始化（如果校准数据已经保存在Flash里，这步很快），下发单次测量命令，用轮询或GPIO1中断等数据就绪，读取距离，马上把XSHUT拉低，最后调用F103的PWR_EnterSTOPMode进入Stop。从唤醒到拿到数据的整体时间通常在50ms以内，人基本感知不到延迟。
5.3 传感器电源彻底断电的硬件方案
XSHUT拉低虽然功耗已经很低，但毕竟传感器还是接在电源轨上的，LDO和内部部分模拟电路仍可能有微小漏电。如果项目对静态功耗要求极其苛刻，可以考虑用一颗P-MOSFET把传感器整个电源轨切断。控制逻辑是GPIO输出高电平关闭MOS管，输出低电平导通给传感器供电。代价是每次测量前都要等电源稳定和传感器Boot，唤醒时间会比只用XSHUT更长一些。
实际项目里，如果传感器模块本身带LDO，我更推荐XSHUT方案而不是断电方案。因为模块上的LDO在上电瞬间可能有一个较长的建立时间，而且反复热插拔电源轨对传感器内部的VDDA域并不友好。用XSHUT做开关，既可以保留模块结构，又能拿到接近关机级的功耗，性价比最高。
最后再分享几个我在调试过程中总结的小心得。多片VL53L0X挂同一条I2C总线时，XSHUT逐个唤醒配置地址是唯一靠谱的办法，千万别指望传感器自己能改地址。如果STM32用内部HSI时钟跑I2C，SCL频率会偏离标称值，初始化偶尔会失败，我建议要么用外部晶振，要么在初始化代码里加一次失败重试。还有，校准数据一定要想方设法存下来，每次上电都搬白板校准的做法，在实验室里能跑，到现场就成灾难了。这些细节在数据手册里其实都有，但往往要自己踩过坑，才会理解手册为什么反复强调那些时序和流程。
本文还有配套的精品资源，点击获取
