# 变更说明

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

## 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

输出示例：

```text
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` 已添加：

```cmake
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 会返回失败
- 尚未实现距离阈值中断、Offset/Crosstalk 校准、自主低功耗模式、ULP 模式
- `DEBUG_VERBOSE` 全开时 IIC 调试打印会让 16K Flash 非常紧张，不建议常开
- VL53L4CD 是单区传感器，不是多区测距