# 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` 是我们额外加的“运行时固定标定值配置文件”。