GD32E230_VL53L4CD/CHANGES.md

变更说明

本文记录本仓库当前未提交改动的背景、目的和验证结果，方便后续维护时快速了解这次迭代做了什么。

1. I2C 底层支持 16 位寄存器地址

改动

• Inc/i2c.h
• Src/i2c.c

i2c_write() 和 i2c_read() 的 reg_addr 参数由 uint8_t 改为 uint16_t，发送寄存器地址时先发高字节、再发低字节。

目的

VL53L4CD 的所有寄存器地址都是 16 位，例如：

• IDENTIFICATION__MODEL_ID = 0x010F
• RESULT__RANGE_STATUS = 0x0089
• RESULT__DISTANCE = 0x0096

原来的 uint8_t 寄存器地址接口无法直接访问这些寄存器。

兼容性

对于寄存器地址仍为 8 位的普通 I2C 器件，调用方传入的地址会自动被当作低字节发送，高字节为 0x00，因此原有行为不变。

2. 新增 VL53L4CD 驱动

新增文件：

• Inc/VL53L4CD_Driver.h
• Src/VL53L4CD_Driver.c

驱动参考 ST VL53L4CD ULD 和 Pololu Arduino 实现，提供：

• vl53l4cd_init()：读取型号、等待固件启动、写入默认配置、VHV 校准、设置 50ms 时序预算
• vl53l4cd_start_ranging() / vl53l4cd_stop_ranging()：启动/停止连续测距
• vl53l4cd_data_ready()：查询是否有新结果
• vl53l4cd_clear_interrupt()：清除测距完成中断
• vl53l4cd_get_result()：读取并解析 15 字节结果块
• vl53l4cd_set_range_timing()：设置 10-200ms 时序预算，当前只支持连续模式
• vl53l4cd_read_reg8/16()、vl53l4cd_write_reg8/16()：寄存器调试接口

结果结构体包含：

• distance_mm
• range_status
• number_of_spad
• signal_rate_kcps
• ambient_rate_kcps
• signal_per_spad_kcps
• ambient_per_spad_kcps
• sigma_mm

3. main.c 集成

在 main.c 中：

• 初始化完成后调用 vl53l4cd_init()
• 成功后调用 vl53l4cd_start_ranging()
• 主循环每 500ms 检查 vl53l4cd_data_ready()
• 有结果时清除中断、读取结果，并通过 printf 输出距离、状态、信号、环境光和 Sigma

输出示例：

Distance: 830 mm | status: 0 | signal: 1128 kcps | ambient: 72 kcps | sigma: 3 mm

4. 板级配置

Inc/board_config.h 当前状态：

• DEBUG_MODE = CFG_DISABLE：关闭启动横幅，距离输出仍然保留
• DEBUG_VERBOSE = CFG_DISABLE：关闭 IIC 调试打印和启动 I2C 扫描
• RS485_MODE = CFG_ENABLE：使用 RS485 串口输出
• I2C 使用 PA9/PA10，复用 AF4

IIC 源码中的调试 printf 已恢复并保留在 DEBUG_VERBOSE 条件编译中，需要排查 I2C 时可临时打开。

5. 构建系统

CMakeLists.txt 的 TARGET_SRC 已添加：

Src/VL53L4CD_Driver.c

6. 体积与验证

• MCU：GD32E230，Flash 16K，RAM 4K
• Release 编译：text 14316 / data 116 / bss 2012
• 编译通过，无警告
• 已通过 DAPLink/CMSIS-DAP + OpenOCD 烧录
• 已在 COM17 @ 115200 验证连续输出，间隔约 500ms
• status: 0 表示测距有效

7. 当前已知限制

• 驱动只支持连续测距模式，inter_measurement_ms 非 0 会返回失败
• 尚未实现 Crosstalk 校准、距离阈值中断、自主低功耗模式、ULP 模式
• DEBUG_VERBOSE 全开时 IIC 调试打印会让 16K Flash 非常紧张，不建议常开
• VL53L4CD 是单区传感器，不是多区测距

8. VL53L4CD 偏移校准

改动

• Inc/VL53L4CD_Driver.h：新增 RANGE_OFFSET_MM、INNER_OFFSET_MM、OUTER_OFFSET_MM 寄存器宏，以及偏移校准接口声明。
• Src/VL53L4CD_Driver.c：
  • vl53l4cd_set_offset()：写入距离偏移量，寄存器值为 offset_mm * 4。
  • vl53l4cd_get_offset()：读取当前生效偏移量。
  • vl53l4cd_calibrate_offset()：清零偏移、热机 10 帧、采样有效测距结果，计算 offset = 实际距离 - 平均距离 并写回。
• Inc/board_config.h：新增校准目标距离、采样次数、自动校准开关和固定偏移配置。
• Src/main.c：初始化后支持自动校准或写回固定偏移。

当前校准结果

• 安装位置目标实际距离：44mm
• 目标类型：橙色 3D 打印哑光件
• 采样次数：20 次
• 校准偏移：-9mm
• 写回后串口输出稳定在约 41-47mm，多数为 44mm
• status: 0，测距有效

说明

固定安装场景使用单点偏移校准即可。VL53L4CD_AUTO_CALIB = CFG_ENABLE 时每次开机自动校准，适合重新标定；校准完成后建议改为 CFG_DISABLE，使用 VL53L4CD_CALIB_OFFSET_MM 中的固定值，避免每次开机都依赖目标存在。