VL53L0X默认I²C地址为0x29，但部分模块可能被改写（如0x30），需用逻辑分析仪或i2cdetect确认；初始化失败典型表现为readReg(0x14)返回0或乱码，主因是I²C通信未通或XSHUT上电时序错误——必须先拉低XSHUT≥100μs再拉高并等待>1ms才能发命令。
VL53L0X 的 I²C 地址和初始化失败的典型表现
直接读不到距离，readReg(0x14) 返回 0 或乱码，大概率是 I²C 通信没通。VL53L0X 默认 I²C 地址是 0x29，但部分模块出厂前被改过（比如写成 0x30），用逻辑分析仪或 i2cdetect -y 1（Linux）确认真实地址比硬编码更可靠。
初始化失败还常因上电时序：必须先拉低 XSHUT 引脚至少 100 μs，再拉高并等待 > 1 ms，之后才能发 I²C 命令。跳过这步，芯片处于复位态，所有寄存器读写都无效。
- 别依赖库自动探测地址——手动用
writeReg(0x80, 0x01)+readReg(0x80)测通断更稳 -
VL53L0X::init()内部调用的VL53L0X::setAddress()必须在 XSHUT 释放后执行，否则地址写不进 - Arduino 环境下若用
Wire.begin()太晚（比如放在setup()后半段），可能错过芯片上电握手窗口
如何用 API 设置 VL53L0X 进入高精度单次测距模式
“高精度”在这里指亚毫米级（官方标称 ±3 mm @ 1 m），但默认的 VL53L0X::startContinuous() 是为功耗优化的连续模式，测量窗口窄、噪声大。真要精度，得切到 VL53L0X::performSingleRanging() 并配对调整以下三处：
- 把
VL53L0X::setMeasurementTimingBudgetMicroSeconds(33000)设为 ≥33 ms（默认仅 20 ms），延长激光发射+回波采样时间，信噪比直接提升 - 调用
VL53L0X::setVCSELPulsePeriod(VL53L0X::VcselPeriodPreRange, 18)和VL53L0X::setVCSELPulsePeriod(VL53L0X::VcselPeriodFinalRange, 14)—— 脉宽加大会增强回波强度，但超过 20 会触发内部限流保护 - 必须在每次
performSingleRanging()前调用VL53L0X::clearInterruptMask()，否则中断未清会导致后续读取卡死在while(!ioTimeout())
读出的距离值为什么总偏大？校准 offset 的实操要点
原始 VL53L0X::getDistance() 返回的是 uint16_t 毫米值，但出厂未校准的模块在 0–10 cm 区间普遍存在 +2~+5 mm 系统性正向偏差。这不是噪声，是光学结构导致的固定 offset。
立即学习“C++免费学习笔记（深入）”；
校准不能靠软件加减一个固定数——因为 offset 随温度/电压漂移。正确做法是启用芯片内置的 Xtalk（串扰）补偿，并用已知距离（如 50.0 mm 块规）跑一次 VL53L0X::performOffsetCalibration()，它会把修正值写入 0x00F8–0x00FB 寄存器。
- 校准前确保目标板为哑光黑色（反射率
-
performOffsetCalibration()必须在最终安装位置进行（含外壳、PCB 邻近器件），否则结构应力会影响结果 - 校准后仍需每 5 分钟调用一次
VL53L0X::getSpadRateMeasurement()监控 SPAD 活性，低于 0.8 表示激光衰减，需重新校准
多传感器共用 I²C 总线时的冲突与隔离方案
两个 VL53L0X 接同一 I²C 总线，即使改了地址，performSingleRanging() 仍可能互相干扰——因为它们内部定时器不同步，激光脉冲在总线上产生电磁耦合，导致对方接收端误判回波时间。
硬件上最简方案是给每个模块的 XSHUT 接独立 GPIO，用软件分时使能：只让当前要测距的模块 XSHUT=HIGH，其余全拉低（进入硬件复位态，I²C 完全断开）。这样总线真正“独占”，无协议层冲突。
- 切换
XSHUT后必须等 > 1 ms 才能发命令，不能紧接着调用init() - 若用 Fast Mode Plus（1 Mbps）I²C，线长超过 10 cm 就要加 1 kΩ 上拉，否则边沿畸变引发地址识别错误
- 别用软件模拟 I²C（bit-banging）驱动 VL53L0X——其内部状态机依赖精确的 SCL 时序，抖动超 50 ns 就会锁死
高精度不是靠堆参数，而是每个物理环节的确定性：电源纹波要
