简介：这套VL53L1X激光测距模块开发实例覆盖STM32F103、C51与Arduino三大平台，面向单片机/嵌入式学习者，重点解决多平台移植与底层驱动编写难题。所有例程均经过实战检验，代码中已定义模块接线方式，并涉及IIC、USART等通信配置，可直接参考。资源包共311个文件，以C语言源码与头文件为主，配合Keil工程文件、汇编文件、链接脚本、十六进制固件、Arduino的.ino源文件及PDF说明文档，其中不同芯片的例程均单独成目录，压缩包仅2.27MB，结构清晰便于检索。更重要的是，包内还包含STM32F10x定时器与Flash等标准外设驱动，以及重置Keil编译的批处理脚本，可显著减少环境配置时间；每个例程都包含初始化、距离读取、串口输出等完整函数，并给出关键注释，方便二次开发。目前已有457人学习下载，适合需要快速验证激光测距功能、对比多平台代码或进行课程设计的硬件开发者。
1. VL53L1X 到底比 VL53L0X 强在哪，项目选型先看这一章
做单片机测距方案，很多人在 VL53L0X 和 VL53L1X 之间纠结过。VL53L0X 最长测距 2 米，VL53L1X 直接拉到 4 米，而且 VL53L1X 的测距区域可以编程为多区域——通过 I2C 寄存器配置，它能把视野分成四个独立区域分别测距，实现类似于"多路激光雷达"的效果。对智能小车避障、机器人壁障、无人机定高这类场景来说，4 米量程意味着更早发现障碍物，留给控制逻辑更充裕的反应时间。
从开发角度看，VL53L1X 的驱动比 VL53L0X 复杂一截。VL53L0X 只需要初始化后连续读结果寄存器，而 VL53L1X 内部有完整的状态机，需要先发送测距命令，等待数据就绪，再读取结果。如果直接拿 VL53L0X 的代码改，多半会卡在状态轮询上。这篇博文针对 STM32F103（标准库 + Keil）、C51（STC89C52）和 Arduino 三个平台，给出可抄的驱动代码和寄存器配置说明，手头有 VL53L1X 模块的可以直接对着调。
2. VL53L1X 的寄存器地图与驱动流程，先弄清状态机再写代码
2.1 核心寄存器地址与 I2C 交互字节序
VL53L1X 的 I2C 地址默认是 0x52（8 位写地址），7 位地址是 0x29。模块支持最高 400kHz 的 I2C 时钟，但很多国产模块在 400kHz 下不稳定，STM32F103 上建议先把 I2C 时钟设为 100kHz 或 200kHz，等调通了再提速。这个模块的操作方式和普通传感器不同：寄存器访问不用指定寄存器长度，直接用 16 位地址 + 数据，写寄存器时先发高字节地址再发低字节地址，然后跟数据字节。
最关键的两个寄存器段是 0x00-0x1F 的控制区和 0x80-0xFF 的结果区。读测距结果时，必须一次性读取 17 个字节（从 0x00 开始），其中前 4 个字节的 bit 位标记了数据是否就绪，第 11-14 个字节是 16 位测距值。每次测距完成后，这些状态位会被硬件自动清掉，所以同一帧数据只能读一次，如果读两次，第二次会拿到 0。
2.2 一次完整测距的状态转移顺序
VL53L1X 的正常测距流程大致是：先写 0x80 寄存器为 0x01 开启测距，然后不断读取 0x00 寄存器的最低位判断数据是否就绪。数据就绪后，从 0x00 开始的 17 字节数据里提取测距值，最后写 0x80 寄存器为 0x00 停止测距。这个流程看起来和 VL53L0X 一样，但细节上有差别：VL53L1X 的 0x00 寄存器最低位是 GPIO 中断状态位，不是数据就绪位本身，必须配合状态寄存器一起判断。
除了测距状态，还要关注一个容易被忽略的寄存器：0x01-0x02 的测量间隔寄存器。上电默认值是 0x0064（100ms），意味着即使单次测距只有 10ms 完成，下一次测距也要等满 100ms 才会启动。对需要快速测距的应用，比如小车避障，建议把这个值改小。改法是把 0x01 写 0x00，把 0x02 写 0x14，这样间隔变成 20ms，测距频率能到 50Hz。
2.3 芯片 ID 校验，代码移植前先做这步
拿到一个来源不明的 VL53L1X 模块，先读 0x010F（芯片 ID 高字节）和 0x0110（芯片 ID 低字节），这两个寄存器地址是 16 位的，读的时候要先发 0x01 再发 0x0F。ST 官方文档声明 VL53L1X 的 ID 值固定为 0xEACC，但实际工程中发现部分批次模块读出来是 0xEACC 或 0xEBAC，后者也能正常工作。代码里判断 ID 时不要用严格相等，最好允许这两个值都通过校验。
读 ID 的 I2C 时序是：先发设备地址 + 写方向，接着发 16 位寄存器地址高字节 0x01、低字节 0x0F，然后重新发送设备地址 + 读方向，连续读两个字节。收到的高字节先存到 buf[0]，低字节存到 buf[1]，最终 ID 是 (uint16_t)buf[0] << 8 | buf[1]。如果读出来的值和 0xEACC、0xEBAC 都不符，可以先检查模块的 XSHUT 引脚是否拉高，这个引脚低电平时芯片处于完全关断状态，I2C 不响应任何命令。
3. STM32F103 标准库驱动，Keil5 工程下的最小可运行代码
3.1 硬件连接与初始化配置
STM32 和 VL53L1X 的连接只需要 4 根线：VCC 接 3.3V、GND 接地、SDA 和 SCL 分别接 PB7 和 PB6。VL53L1X 的 I2C 是开漏输出，必须外接 4.7kΩ 上拉电阻到 3.3V，很多模块板上已经集成了上拉电阻，但如果你用杜邦线延长超过 10cm，建议额外在模块端再并联一个 4.7kΩ 电阻，否则波形边缘太缓，通信会偶发失败。
使用 STM32 标准库时，I2C 初始化的代码基本一致，关键是时钟配置。把 I2C2 的时钟设为 100kHz，用下面这段代码配置：
void I2C2_Init(void) { GPIO_InitTypeDef GPIO_InitStructure; I2C_InitTypeDef I2C_InitStructure; RCC_APB1PeriphClockCmd(RCC_APB1Periph_I2C2, ENABLE); RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOB, ENABLE); GPIO_InitStructure.GPIO_Pin = GPIO_Pin_10 | GPIO_Pin_11; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_AF_OD; GPIO_InitStructure.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOB, &GPIO_InitStructure); I2C_InitStructure.I2C_Mode = I2C_Mode_I2C; I2C_InitStructure.I2C_DutyCycle = I2C_DutyCycle_2; I2C_InitStructure.I2C_OwnAddress2 = 0x00; I2C_InitStructure.I2C_Ack = I2C_Ack_Enable; I2C_InitStructure.I2C_AcknowledgedAddress = I2C_AcknowledgedAddress_7bit; I2C_InitStructure.I2C_ClockSpeed = 100000; I2C_Init(I2C2, &I2C_InitStructure); I2C_Cmd(I2C2, ENABLE); }上面的代码里用了 PB10/PB11 作为 I2C2 引脚，这是 STM32F103ZET6 的默认映射。如果用的是 STM32F103C8T6 最小系统板，同样支持 I2C2，引脚复用也是 PB10/PB11，不需要重映射。I2C_ClockSpeed参数设为 100000 表示 100kHz，这个值在调试阶段足够了，等稳定运行后再改成 200000 或 400000。
3.2 软件模拟 I2C 还是硬件 I2C
STM32 标准库的硬件 I2C 口碑两极分化，FTF（Fault Tolerance Feature）机制在某些芯片版本上会卡死在 BUSY 状态。很多熟练工程师在 VL53L1X 这种对时序不敏感的传感器上选择软件模拟 I2C，这样代码可移植性更好，从 STM32 移植到 C51 只需要改引脚宏定义。软件 I2C 的核心是两个延迟函数，分别对应高低电平的保持时间，当时钟设为 100kHz 时，一个时钟周期是 10μs，半周期是 5μs。
下面是一个典型的软件 I2C 写寄存器函数，可以直接用在 STM32F103 上：
void VL53L1X_WriteReg(uint16_t reg, uint8_t data) { I2C_Start(); I2C_SendByte(0x52); // 设备写地址 I2C_WaitAck(); I2C_SendByte((reg >> 8) & 0xFF); // 寄存器高字节 I2C_WaitAck(); I2C_SendByte(reg & 0xFF); // 寄存器低字节 I2C_WaitAck(); I2C_SendByte(data); // 写入数据 I2C_WaitAck(); I2C_Stop(); }I2C_SendByte里要循环 8 次，从最高位开始逐位发送，每次拉高或拉低 SDA 后都要延迟 5μs。I2C_WaitAck实现方式是拉高 SCL，然后读 SDA 引脚，如果读到低电平说明从机应答，读到高电平说明无应答，通常超时 100μs 后返回错误。
3.3 初始化序列与测距函数
VL53L1X 上电后不能直接开始测距，必须先执行一组初始化寄存器写入。ST 官方的初始化序列大约有 48 个寄存器要写，但实际上其中大部分是保留位，不写也能工作。工程上最稳妥的做法是执行完整初始化，这里给一个精简版，只写必要的寄存器：
void VL53L1X_Init(void) { // 软件复位 VL53L1X_WriteReg(0x0014, 0x00); // SOFT_RESET 位置0 HAL_Delay(10); VL53L1X_WriteReg(0x0014, 0x01); // 释放复位 HAL_Delay(100); // 配置 I2C 地址为默认值，确保总线无冲突 VL53L1X_WriteReg(0x0001, 0x29); // I2C 地址重载 VL53L1X_WriteReg(0x0002, 0x00); // 清除地址保存标志位 // 设置测距模式为单次测距 VL53L1X_WriteReg(0x001C, 0x00); // 停止连续的测距模式 VL53L1X_WriteReg(0x001D, 0x01); // 启动单次测距 }初始化后读测距值，完整代码如下：
uint16_t VL53L1X_GetDistance(void) { uint8_t buf[17]; uint16_t distance = 0; uint16_t timeout = 0; // 开启测距 VL53L1X_WriteReg(0x0080, 0x01); // 等待数据就绪，超时 100ms while (timeout < 1000) { VL53L1X_ReadRegs(0x0000, buf, 1); if (buf[0] & 0x07) { // 低3位为1表示数据就绪 break; } delay_ms(1); timeout++; } if (timeout >= 1000) { return 0xFFFF; // 超时返回错误码 } // 读取测距结果 VL53L1X_ReadRegs(0x0000, buf, 17); distance = (uint16_t)((buf[11] << 8) | buf[12]); // 停止测距，准备下一次 VL53L1X_WriteReg(0x0080, 0x00); return distance; }这段代码里有两个关键点。一是buf[0] & 0x07的判断：VL53L1X 的 0x00 寄存器低三位分别是 GPIO 中断状态、测距完成标志和测距错误标志，只要最低位为 1 就说明测距完成，中间位为 0 表示无错误。二是 17 字节结果的取值位置：buf[11] 是距离高字节，buf[12] 是距离低字节，这个布局和 VL53L0X 不同，VL53L0X 的距离值在 buf[13] 和 buf[14]，移植时特别容易搞混。返回的单位是毫米，不需要额外换算。测距异常时返回 0xFFFF，主调函数判断这个值后可以选择重测或丢弃数据。
3.4 Keil5 下的常见编译错误与处理
在 Keil5 里编译 VL53L1X 驱动时，uint16_t和uint8_t这些类型需要包含stdint.h头文件，否则会报 "unknown type name" 错误。标准库工程里加#include "stdint.h"即可。另一个问题是 Keil 的 C99 模式默认关闭，如果在函数中间声明变量会报错，可以在 C/C++ 选项卡的 Misc Controls 里加--c99开启。工程里如果同时有 C51 和 STM32 的代码，注意不要混用sbit和GPIO_SetBits两种风格，Keil5 可以同时安装 C51 和 MDK 组件，但同一个工程文件里不能混合编译两种架构的代码，建议分开建工程。
4. C51 平台移植要点，KEIL C51 下的时序重构与内存限制
4.1 C51 上 I2C 时序的重新测定
把 STM32 的驱动代码移植到 C51（以 STC89C52 为例）时，最核心的问题不是寄存器配置，而是时序。STM32 主频 72MHz，一条空指令延迟约 13ns，而 STC89C52 在 12MHz 晶振下，一个机器周期是 1μs，两者相差两个数量级。原本在 STM32 上写的 5μs 延迟函数，在 C51 上要重新用for循环计算。
void I2C_Delay(void) { unsigned char i; for (i = 0; i < 20; i++); }这个函数在 12MHz 晶振下大约产生 40μs 的延迟，用来做 100kHz 时钟的一半周期刚好合适。如果你的板子晶振是 11.0592MHz，i的值要改到 22 左右，因为两者的机器周期不同。有个简单的验证方法：用逻辑分析仪抓 SCL 引脚，测量高低电平宽度，半周期应该在 4.5μs 到 5.5μs 之间，低于 3μs 可能导致 VL53L1X 识别不了，高于 10μs 则测距频率会明显下降。
C51 的 I2C 引脚定义用sbit实现，比 STM32 的 GPIO 操作简洁很多：
sbit SDA = P1^0; sbit SCL = P1^1; void I2C_Start(void) { SDA = 1; I2C_Delay(); SCL = 1; I2C_Delay(); SDA = 0; I2C_Delay(); SCL = 0; I2C_Delay(); }I2C_Delay放在电平翻转之间，保证建立时间和保持时间满足 I2C 协议要求。VL53L1X 的 I2C 从机接口对建立时间要求是 100ns 以上，C51 的指令周期远大于这个值，所以只要延迟函数不是 0，顺序发送就能保证时序合法。
4.2 C51 内存模型选择，PDATA 还是 XDATA
STC89C52 的内部 RAM 只有 256 字节，而 VL53L1X 读取测距结果需要 17 字节的缓冲区，加上 I2C 函数的局部变量和多级函数调用压栈，很容易突破 256 字节的限制。在 Keil C51 里，这个问题的解决方案是显式指定变量的存储类型：
uint8_t xdata vl53l1x_buf[17];xdata关键字把数组放到外部 RAM（STC89C52 片内扩展了 1KB xdata），不占内部 data 空间。还有人用pdata（分页寻址的外部 RAM），速度比 xdata 快，但寻址范围只有 256 字节，17 字节数组刚好放得下。如果编译后报DATA SEGMENT TOO LARGE，优先检查有没有大数组没加xdata，其次是减少函数参数传递，用全局变量代替局部变量。
C51 上还有一个隐形的坑是中断函数和主循环共用 I2C 总线。如果在测距过程中有定时器中断，而中断服务函数里也操作 I2C，需要加临界区保护。C51 没有现成的临界区函数，用EA = 0;和EA = 1;包住 I2C 操作的完整序列即可。这类 bug 极其难查，建议工程前期先屏蔽所有中断，确认测距功能正常后再逐个打开。
4.3 C51 下 VL53L1X 的测距主循环
C51 的主循环结构如下：
void main(void) { uint16_t distance; UART_Init(); // 串口输出距离值 I2C_Init_Pins(); delay_ms(200); // 等待 VL53L1X 上电稳定 VL53L1X_Init(); while (1) { distance = VL53L1X_GetDistance(); if (distance != 0xFFFF) { printf("Distance: %u mm\n", distance); } delay_ms(50); // 测距间隔控制 } }C51 的printf会占用较多代码空间和栈空间，如果 flash 空间紧张，建议改用串口直接发送字节，配合上位机解析。另外 C51 的 Keil 工程里默认启用启动代码（STARTUP.A51），这段代码会清除所有 xdata，所以在main函数入口处 VL53L1X 模块已经上电，但没必要额外加延时，传感器自身的上电初始化需要的时间大约在 1ms 以内，delay_ms(200)已经足够保守。
5. Arduino 快速验证方案，Wire 库读数与参数调优
5.1 Arduino 上的最小代码，避开第三方库
Arduino 平台上跑 VL53L1X 有两种方式：用 Pololu 的 VL53L1X 库，或者用 Wire 库裸写。从学习和排查问题的角度，我推荐先裸写一遍，理解寄存器操作后再引入库，这样出了问题知道去哪层查。
#include <Wire.h> #define VL53L1X_ADDR 0x29 void vl53l1x_write_reg(uint16_t reg, uint8_t data) { Wire.beginTransmission(VL53L1X_ADDR); Wire.write((reg >> 8) & 0xFF); Wire.write(reg & 0xFF); Wire.write(data); Wire.endTransmission(); } uint8_t vl53l1x_read_reg(uint16_t reg) { Wire.beginTransmission(VL53L1X_ADDR); Wire.write((reg >> 8) & 0xFF); Wire.write(reg & 0xFF); Wire.endTransmission(false); Wire.requestFrom(VL53L1X_ADDR, (uint8_t)1); return Wire.read(); } void setup() { Serial.begin(115200); Wire.begin(); delay(200); // 软件复位 vl53l1x_write_reg(0x0014, 0x00); delay(10); vl53l1x_write_reg(0x0014, 0x01); delay(100); } void loop() { uint16_t distance = 0; uint8_t buf[17]; // 开启测距 vl53l1x_write_reg(0x0080, 0x01); // 轮询 100ms 超时 unsigned long start = millis(); while (millis() - start < 100) { uint8_t status = vl53l1x_read_reg(0x0000); if (status & 0x07) { break; } delay(1); } // 读取结果 Wire.beginTransmission(VL53L1X_ADDR); Wire.write(0x00); Wire.write(0x00); Wire.endTransmission(false); Wire.requestFrom(VL53L1X_ADDR, (uint8_t)17); for (int i = 0; i < 17; i++) { buf[i] = Wire.read(); } distance = (buf[11] << 8) | buf[12]; Serial.print("Distance: "); Serial.print(distance); Serial.println(" mm"); // 停止测距 vl53l1x_write_reg(0x0080, 0x00); delay(20); }这个代码里endTransmission(false)是 Arduino Wire 库的一个关键参数：false 表示不发停止位，这样后面调用requestFrom时能直接进入读模式。如果这里写成endTransmission()或者endTransmission(true)，I2C 总线上会多一个 STOP 条件，VL53L1X 会认为本次通信结束，下次读取前需要重新发送寄存器地址，代码逻辑仍然正确，但时序上多了一次总线操作。Arduino Uno 的 Wire 库默认时钟是 100kHz，不需要额外配置。
5.2 测距模式选择与参数调整
VL53L1X 支持 Short、Medium、Long 三种测距模式，区别在于测距能力和环境光抑制能力。Short 模式最远 1.3 米，但抗环境光最好，室外强光下能稳定工作；Long 模式最远 4 米，但环境光强时测距值会在远距离跳动。切换模式需要改三个寄存器：
void vl53l1x_set_distance_mode(uint8_t mode) { // mode: 0-Short, 1-Medium, 2-Long vl53l1x_write_reg(0x001C, mode); vl53l1x_write_reg(0x001D, 0x00); vl53l1x_write_reg(0x001E, 0x00); }工程上常见的做法是：室内机器人用 Medium，室外小车用 Short，需要最大量程且光照稳定才用 Long。这个选择对测距稳定性影响非常大，很多用户反映"距离超过 2 米读数乱跳"，通常就是因为默认 Long 模式在室内荧光灯下信号噪声过大。修改模式后，模块内部会自动调整信号阈值和时序参数，不需要额外校准。
5.3 用串口绘图器观察测距波形
Arduino IDE 自带串口绘图器（Serial Plotter），用Serial.println(distance)直接输出数值，就能在工具菜单里打开绘图器观察连续测距的波形。这个工具对调试很有用：静止状态下，波形应该是一条平直的线，波动范围在 ±20mm 以内。如果波形出现周期性的尖峰，说明测距值偶发错误，可能是电源纹波或者 I2C 通信错误，优先检查模块供电，VL53L1X 的 AVDD 引脚对纹波敏感，建议在模块电源脚并联 10μF 电容。如果波形整体下移且波动大，先尝试切到 Short 模式，多半是环境光干扰导致的信号质量下降。
6. 从数据手册逆向配置，四个易错寄存器位的修正技巧
VL53L1X 的数据手册有 700 多页，绝大多数工程开发不需要全部精读，但有几个寄存器位的含义必须搞清楚，踩过的坑基本都集中在这四个地方。
0x0083 和 0x0084 是 SPAD 使能寄存器，SPAD 是 VL53L1X 内部的单光子雪崩二极管阵列，这两个寄存器控制哪些 SPAD 参与测距。有些模块出厂时没有写入校准数据，SPAD 使能值全为 0，导致测距始终返回 0。检查方法是读 0x0083，正常值应该非零，如果为 0，需要往 0x0083 写入 0x00、往 0x0084 写入 0x80，这对应推荐的中心 SPAD 组，然后在 0x0085 写入 0x06 开启 SPAD 校准，延迟 50ms 后再恢复正常测距。
0x0014 的 bit0 是软件复位控制位，复位后必须等待模块重新初始化完成，时间约 10ms。如果复位后立即写配置寄存器，I2C 操作会返回 NACK，因为芯片还在启动状态。排查这类问题时，读 0x010F 的 ID 高字节，如果读不到 0xEA，说明芯片还没从复位中恢复。
测距值误差一致性是另一个高频问题。VL53L1X 出厂时在 0x0090-0x0097 这 8 个寄存器里烧录了校准系数，但部分代工模块没有完整烧录，导致测距值系统性偏移 10% 左右。验证方法是对着 1 米处的白色墙面测距，如果读数稳定在 850-870mm 之间，说明校准数据缺失。修正方法可以在应用层做线性补偿：real_dist = (uint32_t)raw_dist * 100 / 87，通过标定两个距离点的实际值和测量值，算出补偿系数。
最后一个技巧是使用 0x0001 寄存器重新配置 I2C 地址，这在多模块并联时很有用。每个 VL53L1X 的 XSHUT 引脚分别接到单片机的不同 GPIO，逐个拉高 XSHUT 并写新的地址，就能在同一
本文还有配套的精品资源，点击获取
