feat(VL53L4CD): 增加偏移校准支持并固化44mm安装偏移

- 新增 vl53l4cd_set_offset/get_offset/calibrate_offset
- main 支持开机自动校准或启动时写回固定偏移
- 当前44mm哑光目标校准结果 offset=-9mm
- 同步更新 README 与 CHANGES

Inc/VL53L4CD_Driver.h

@@ -17,6 +17,12 @@
 /* 寄存器地址 */
 #define VL53L4CD_REG_I2C_SLAVE_DEVICE_ADDRESS             0x0001U
 #define VL53L4CD_REG_VHV_TIMEOUT_MACROP_LOOP_BOUND        0x0008U
+#define VL53L4CD_REG_XTALK_PLANE_OFFSET_KCPS              0x0016U
+#define VL53L4CD_REG_XTALK_X_PLANE_GRADIENT_KCPS          0x0018U
+#define VL53L4CD_REG_XTALK_Y_PLANE_GRADIENT_KCPS          0x001AU
+#define VL53L4CD_REG_RANGE_OFFSET_MM                      0x001EU
+#define VL53L4CD_REG_INNER_OFFSET_MM                      0x0020U
+#define VL53L4CD_REG_OUTER_OFFSET_MM                      0x0022U
 #define VL53L4CD_REG_GPIO_HV_MUX_CTRL                     0x0030U
 #define VL53L4CD_REG_GPIO_TIO_HV_STATUS                   0x0031U
 #define VL53L4CD_REG_SYSTEM_INTERRUPT                     0x0046U
@@ -127,6 +133,30 @@ bool vl53l4cd_get_result(vl53l4cd_result_t *result);
  */
 bool vl53l4cd_set_range_timing(uint8_t timing_budget_ms, uint32_t inter_measurement_ms);
 
+/**
+ * @brief   写入手动指定的距离偏移量
+ * @param[in]  offset_mm: 偏移量，单位 mm，可为负
+ * @retval   true: 成功; false: 失败
+ */
+bool vl53l4cd_set_offset(int16_t offset_mm);
+
+/**
+ * @brief   读取当前生效的距离偏移量
+ * @param[out] offset_mm: 返回偏移量，单位 mm
+ * @retval   true: 成功; false: 失败
+ */
+bool vl53l4cd_get_offset(int16_t *offset_mm);
+
+/**
+ * @brief   以当前目标执行一次偏移校准
+ * @param[in]  target_distance_mm: 目标实际距离，单位 mm，范围 10..1000
+ * @param[in]  num_samples: 有效采样次数，范围 5..255
+ * @param[out] measured_offset_mm: 计算得到的偏移量，单位 mm
+ * @retval   true: 校准并写入成功; false: 失败
+ */
+bool vl53l4cd_calibrate_offset(uint16_t target_distance_mm, uint16_t num_samples,
+                               int16_t *measured_offset_mm);
+
 /**
  * @brief   读一个 8 位寄存器
  * @param[in]  reg: 16 位寄存器地址

Inc/board_config.h

@@ -48,6 +48,13 @@
   #define RTT_PutChar(ch, c)
 #endif
 
+/* >>>>>>>>>>>>>>>>>>>>[VL53L4CD OFFSET CALIBRATION]<<<<<<<<<<<<<<<<<<<< */
+
+#define VL53L4CD_CALIB_TARGET_MM   44U  // 当前安装位置的目标实际距离
+#define VL53L4CD_CALIB_SAMPLES     20U  // 校准采样次数，ST 推荐 20
+#define VL53L4CD_AUTO_CALIB        CFG_DISABLE  // CFG_ENABLE: 每次开机自动校准; CFG_DISABLE: 使用下面固定偏移
+#define VL53L4CD_CALIB_OFFSET_MM   (-9)  // 校准后保存的固定偏移量，单位 mm，可为负
+
 /* >>>>>>>>>>>>>>>>>>>>[RS485 MODE]<<<<<<<<<<<<<<<<<<<< */
 
 #define RS485_MODE            CFG_ENABLE  // CFG_DISABLE: RS485 off; CFG_ENABLE: RS485 on