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