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 中的固定值，避免每次开机都依赖目标存在。

9. 透过玻璃串扰补偿（Crosstalk）

改动

• Inc/VL53L4CD_Driver.h / Src/VL53L4CD_Driver.c：新增 vl53l4cd_set_xtalk()、vl53l4cd_get_xtalk()、vl53l4cd_calibrate_xtalk()。
• Inc/board_config.h：新增 VL53L4CD_GLASS_XTALK、VL53L4CD_GLASS_XTALK_KCPS、VL53L4CD_XTALK_CALIB_TARGET_MM、VL53L4CD_XTALK_CALIB_SAMPLES 开关。
• Src/main.c：开机按开关写入固定串扰值。

实现

按 ST ULD 官方 vl53l4cd_calibration.c 的 VL53L4CD_CalibrateXtalk() 流程实现（清零补偿 → 热机 10 帧 → 采样有效帧 → 计算写回），浮点公式改为定点数以适配无 FPU 的 Cortex-M23：

xtalk = (1 - 平均距离/目标距离) * 平均信号速率/平均SPAD数

上限 127 kcps，寄存器值 = xtalk_kcps * 512（XTALK_PLANE_OFFSET_KCPS 0x0016），X/Y 梯度寄存器（0x0018/0x001A）清零。

10. 串口命令扩展

改动

• Inc/command.h / Src/command.c：新增命令处理与共享状态（最近一帧结果、上报开关）。
• Src/main.c：主循环推送最近一帧结果、按上报开关输出。

命令列表

• 基础：M1（开上报）、M2（关上报）、M3（查最近一帧 d=距离;s=状态）、M888（重启）、M999（版本）、M9999（OTA）
• 校准：M101[S]（读/写偏移）、M102S（偏移校准）、M103[S]（读/写串扰）、M104S（串扰校准）、M105（存 Flash）、M106（从 Flash 加载应用）、M107（擦除并清零）

M102/M104 阻塞约 2 秒，期间连续上报暂停。带符号参数（如 M101S-9）通过新增的 parse_int_dec() 解析。

11. 校准数据 Flash 持久化

改动

• 新增 Inc/calib_store.h / Src/calib_store.c。
• LD/gd32e23x_flash.ld：代码区 16K → 15K，保留最后一页（1KB）。
• Inc/board_config.h：新增 VL53L4CD_PERSIST_CALIB。
• Src/main.c：开机优先从 Flash 加载校准数据。

实现

• 校准记录（偏移 + 串扰）16 字节：魔数 0x344C5643（"CVL4"）+ 版本 + 偏移 + 串扰 + 累加和。
• 页地址按运行时检测的 Flash 容量取最后一页：16K→0x0800 3C00、32K→0x0800 7C00、64K→0x0800 FC00。
• 擦写用 SDK 的 fmc_page_erase() / fmc_doubleword_program()，期间暂停串口接收中断防止丢字节。

12. 体积优化与构建调整

新增功能后固件超预算（16K 仅剩约 1.9K），做了两处优化：

• Src/main.c：测距上报与启动信息改用手写格式化输出（uart_write_str/u32/i32），输出与原 printf 版本逐字节一致，不再链接 vfprintf/malloc 等 libc 组件，省约 2.7K。
• cmake/project.cmake：Debug 优化等级 -O0 → -Og（-O0 已无法放下，且旧 Debug 本就已用 15.6K/16K）。

结果

• Release：text 12908 / data 24 / bss 1704（改动前 text 14316 / data 116 / bss 2012）
• Debug：text 14876 / data 24 / bss 1712
• 两配置均在 15K 代码区内，编译无警告（Release）