宏	当前值	作用
`DEBUG_MODE`	`CFG_DISABLE`	关闭 `Hello World` 启动横幅；距离输出仍保留
`DEBUG_VERBOSE`	`CFG_DISABLE`	关闭 IIC 调试打印和启动 I2C 扫描
`COM_DEBUG`	`CFG_DISABLE`	关闭命令帧调试打印
`SEGGER_RTT_DETECTION`	`CFG_DISABLE`	关闭 SEGGER RTT
`RS485_MODE`	`CFG_ENABLE`	使用 RS485 串口输出
`SOFTWARE_IIC`	`CFG_DISABLE`	使用硬件 I2C

如果需要临时扫描 I2C 总线或查看 IIC 调试信息，把 DEBUG_VERBOSE 改为 CFG_ENABLE。注意 16K Flash 下全开会让固件体积非常紧张。

编译与烧录

编译

在仓库根目录执行：

cmake --preset Release
cmake --build Build/Release

Debug 构建：

cmake --preset Debug
cmake --build Build/Debug

产物位于 Build/Release/Application/：

Application.elf
Application.hex
Application.bin
Application.map

烧录

通过 DAPLink/CMSIS-DAP 烧录：

D:/toolchain/openocd/bin/openocd.exe \
  -s D:/toolchain/openocd/scripts \
  -f interface/cmsis-dap.cfg \
  -f target/gd32e23x.cfg \
  -c "reset_config srst_only connect_assert_srst; init; reset halt; flash write_image erase Build/Release/Application/Application.elf; reset; exit"

也可以在 VSCode 中使用已配置的 Flash 任务。

串口输出

连接串口后使用 115200 8N1 查看，例如 COM17：

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

默认每 500ms 输出一次。

VL53L4CD 驱动

驱动文件：

Inc/VL53L4CD_Driver.h
Src/VL53L4CD_Driver.c

主要接口

函数	作用
`vl53l4cd_init()`	初始化传感器，写入默认配置，默认 50ms 时序预算
`vl53l4cd_start_ranging()`	启动连续测距
`vl53l4cd_stop_ranging()`	停止连续测距
`vl53l4cd_data_ready()`	查询是否有新结果
`vl53l4cd_clear_interrupt()`	清除测距完成中断
`vl53l4cd_get_result()`	读取并解析测距结果
`vl53l4cd_set_range_timing()`	设置 10-200ms 时序预算，当前仅支持连续模式
`vl53l4cd_read_reg8/16()`	读 8/16 位寄存器
`vl53l4cd_write_reg8/16()`	写 8/16 位寄存器

修改时序预算

在 Src/VL53L4CD_Driver.c 的 vl53l4cd_init() 末尾：

return vl53l4cd_set_range_timing(50U, 0U);

第一个参数是时序预算，范围 10-200ms。第二个参数当前只能传 0，表示连续测距模式。

修改输出间隔

在 Src/main.c 主循环中：

delay_ms(500);

改为需要的毫秒数即可。

测距结果字段

vl53l4cd_get_result() 返回 vl53l4cd_result_t：

字段	含义
`distance_mm`	距离，单位 mm
`range_status`	测距状态码
`number_of_spad`	有效 SPAD 数
`signal_rate_kcps`	目标反射信号强度
`ambient_rate_kcps`	环境光/背景噪声强度
`signal_per_spad_kcps`	每个 SPAD 的信号强度
`ambient_per_spad_kcps`	每个 SPAD 的环境光强度
`sigma_mm`	测距噪声/不确定度，单位 mm

测距状态码

状态码	含义
0	测距有效
1	Sigma 超限，结果不稳定
2	信号太弱，目标太远、太黑或反射率低
3	目标过近
4	相位故障
5	硬件故障
6	未检测到目标
7	近距离信号不足
255	未知状态

I2C 16 位寄存器说明

VL53L4CD 的寄存器地址是 16 位。本项目的 i2c_read() / i2c_write() 已改为支持 uint16_t 寄存器地址，发送时先发高字节、再发低字节。

对原有 8 位寄存器地址的 I2C 器件仍然兼容：地址高字节为 0x00，发送序列与原来一致。

Flash 体积说明

当前 Release 固件约：

text   14316
data     116
bss     2012

16K Flash 下仍有约 2K 余量。保留 printf 后体积会增加约 2.5K，因此不建议同时开启全部 IIC 调试打印。

已知限制

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

变更记录

当前迭代的详细说明见 CHANGES.md。

GD32E230_VL53L4CD v0.0.1

Latest

2026-09-14 17:22:05 +08:00

C 95%

Assembly 2%

C++ 1.9%

CMake 0.8%

Linker Script 0.3%

README.md Unescape Escape

GD32E230 + VL53L4CD 测距项目

目录

硬件连接

主控

VL53L4CD

串口

其他

功能开关