ASER-NAV/App/VL53L0X_API/MIGRATION_NOTES.md

VL53L0X_API Notes

本文档只说明 VL53L0X_API 目录里我们自己写的兼容层分别负责什么，方便后续在旧工程里继续集成。

目录分层

core/

这是 ST 官方 API 核心层，主要负责：

• 设备初始化
• 寄存器访问逻辑
• 测距流程
• 官方校准函数
  • PerformRefSpadManagement
  • PerformRefCalibration
  • PerformOffsetCalibration
  • PerformXTalkCalibration

这部分一般不要随便改，除非明确要修改 ST 官方行为。

platform/

这是我们自己写的兼容层，负责把 ST API 接到 STM32 工程里。

我们自己写的兼容层文件说明

platform/vl53l0x_platform.h

平台适配层头文件。

主要作用：

• 声明和 STM32 平台相关的接口
• 给 ST API 提供底层读写函数声明
• 提供总线、GPIO、延时、地址切换相关接口声明

platform/vl53l0x_platform.c

平台适配层实现。

主要作用：

• 对接 STM32 的 HAL I2C
• 实现 VL53L0X 所需的寄存器读写
• 绑定每颗传感器的 I2C 句柄和地址
• 控制 XSHUT
• 支持运行时改 I2C 地址

简单说，这一层负责把 ST API 的“平台无关接口”落到我们实际板子上。

platform/vl53_board.h

板级管理层头文件。

主要作用：

• 定义多颗 VL53 共用的管理结构体
• 定义快照结构 Vl53BoardSnapshot_t
• 定义硬件配置结构 Vl53BoardHwCfg_t
• 对外暴露板级接口，例如：
  • Vl53Board_Init
  • Vl53Board_StartContinuous
  • Vl53Board_StopContinuous
  • Vl53Board_ReadAll
• 当前版本还扩展了校准相关数据结构和接口

这一层是“上层任务代码直接调用的 API”。

platform/vl53_board.c

板级管理层实现。

主要作用：

• 管理一组 VL53 传感器
• 完成多颗设备的上电、拉低/拉高 XSHUT、分配运行地址
• 调 ST 官方初始化流程
• 启动/停止连续测量
• 轮询读取测距结果
• 组织成统一快照给上层使用
• 对每颗测距值做简单卡尔曼滤波

如果说 vl53l0x_platform.c 是“底层总线适配”，那 vl53_board.c 就是“更贴近业务的板级封装”。

platform/vl53_calibration_config.h

这是我们自己加的运行时校准配置头。

主要作用：

• 集中保存已经确认过的校准值
• 让上层在启动后把这些值写回 VL53

当前主要用于保存：

• offset_micro_meters
• xtalk_compensation_rate_mcps
• 对应的 *_calibrated 标志

这不是 ST 官方自带文件，是我们为了工程集成方便单独加的配置层。

platform/vl53l0x_types.h

类型辅助头文件。

主要作用：

• 补充平台侧需要的公共类型定义
• 给 platform 层做类型适配

platform/vl53l0x_platform_log.h

日志相关兼容头。

主要作用：

• 兼容 ST API 的日志宏
• 当前工程里基本属于轻量占位层

推荐修改边界

如果后续要继续改 VL53 集成，优先修改：

• platform/vl53_board.c/.h
• platform/vl53_calibration_config.h

如果只是换板子、换 I2C、换 XSHUT 引脚，优先修改：

• platform/vl53l0x_platform.c/.h

如果不是明确要动 ST 官方行为，尽量不要去改：

• core/

一句话总结

我们自己写的兼容层分两层：

• vl53l0x_platform.*：把 ST API 接到 STM32 HAL
• vl53_board.*：把多颗 VL53 封装成上层任务可直接使用的板级接口

而 vl53_calibration_config.h 是我们额外加的“运行时固定标定值配置文件”。