feat(VL53L4CD): 支持透过玻璃串扰补偿、串口校准命令与校准数据Flash存储

Inc/VL53L4CD_Driver.h

@@ -140,6 +140,22 @@ bool vl53l4cd_set_range_timing(uint8_t timing_budget_ms, uint32_t inter_measurem
  */
 bool vl53l4cd_set_offset(int16_t offset_mm);
 
+/**
+ * @brief   写入串扰（玻璃反射）补偿值，透过玻璃测距时使用
+ * @details 写 XTALK_PLANE_OFFSET_KCPS (0x0016) 并将 X/Y 梯度寄存器清零，
+ *          寄存器值为 xtalk_kcps * 512
+ * @param[in]  xtalk_kcps: 串扰补偿值，单位 kcps，范围 0..127
+ * @retval   true: 成功; false: 参数无效或写入失败
+ */
+bool vl53l4cd_set_xtalk(uint16_t xtalk_kcps);
+
+/**
+ * @brief   读取当前生效的串扰补偿值
+ * @param[out] xtalk_kcps: 返回串扰值，单位 kcps
+ * @retval   true: 成功; false: 失败
+ */
+bool vl53l4cd_get_xtalk(uint16_t *xtalk_kcps);
+
 /**
  * @brief   读取当前生效的距离偏移量
  * @param[out] offset_mm: 返回偏移量，单位 mm
@@ -157,6 +173,20 @@ bool vl53l4cd_get_offset(int16_t *offset_mm);
 bool vl53l4cd_calibrate_offset(uint16_t target_distance_mm, uint16_t num_samples,
                                int16_t *measured_offset_mm);
 
+/**
+ * @brief   执行一次串扰校准（透过玻璃安装时使用）
+ * @details 参照 ST ULD vl53l4cd_calibration.c 的 CalibrateXtalk 流程，定点数实现：
+ *          先清零串扰补偿，热机 10 帧，然后采样有效测距帧，
+ *          xtalk = (1 - 平均距离/目标距离) * 平均信号/平均SPAD数，上限 127 kcps。
+ *          校准期间传感器被独占，主循环上报会暂停。
+ * @param[in]  target_distance_mm: 玻璃后方目标的实际距离，单位 mm，范围 10..5000
+ * @param[in]  num_samples: 采样次数，范围 5..255，ST 建议至少 10
+ * @param[out] measured_xtalk_kcps: 计算得到的串扰值，单位 kcps
+ * @retval   true: 校准并写入成功; false: 失败（含有效样本不足或串扰超限）
+ */
+bool vl53l4cd_calibrate_xtalk(uint16_t target_distance_mm, uint16_t num_samples,
+                              uint16_t *measured_xtalk_kcps);
+
 /**
  * @brief   读一个 8 位寄存器
  * @param[in]  reg: 16 位寄存器地址

Inc/board_config.h

@@ -55,6 +55,14 @@
 #define VL53L4CD_AUTO_CALIB        CFG_DISABLE  // CFG_ENABLE: 每次开机自动校准; CFG_DISABLE: 使用下面固定偏移
 #define VL53L4CD_CALIB_OFFSET_MM   (-9)  // 校准后保存的固定偏移量，单位 mm，可为负
 
+/* >>>>>>>>>>>>>>>>>>>>[VL53L4CD GLASS XTALK / FLASH PERSIST]<<<<<<<<<<<<<<<<<<<< */
+
+#define VL53L4CD_GLASS_XTALK            CFG_DISABLE  // CFG_ENABLE: 透过玻璃测距，开机写入串扰补偿
+#define VL53L4CD_GLASS_XTALK_KCPS       20U  // 编译期固定串扰值，单位 kcps，范围 0..127
+#define VL53L4CD_XTALK_CALIB_TARGET_MM  500U // M104 串扰校准默认目标距离（玻璃后方），单位 mm
+#define VL53L4CD_XTALK_CALIB_SAMPLES    20U  // M104 串扰校准默认采样次数，ST 建议至少 10
+#define VL53L4CD_PERSIST_CALIB          CFG_ENABLE  // CFG_ENABLE: 开机优先从 Flash 末页加载校准数据
+
 /* >>>>>>>>>>>>>>>>>>>>[RS485 MODE]<<<<<<<<<<<<<<<<<<<< */
 
 #define RS485_MODE            CFG_ENABLE  // CFG_DISABLE: RS485 off; CFG_ENABLE: RS485 on

Inc/calib_store.h

@@ -0,0 +1,37 @@
+/**
+ * @file calib_store.h
+ * @brief VL53L4CD 校准数据 Flash 持久化存储接口
+ * @details 利用主 Flash 最后一页（1KB，地址按运行时检测到的 Flash 容量计算）
+ *          保存偏移校准与串扰校准结果，掉电不丢失。
+ *          注意：链接脚本已将代码区缩小 1KB，为 16K 容量器件保留该页。
+ */
+#ifndef CALIB_STORE_H
+#define CALIB_STORE_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+/**
+ * @brief   从 Flash 读取校准数据
+ * @param[out] offset_mm: 返回保存的偏移量，单位 mm
+ * @param[out] xtalk_kcps: 返回保存的串扰值，单位 kcps
+ * @retval   true: 校准数据有效; false: 无数据、版本不匹配或校验失败
+ */
+bool calib_store_load(int16_t *offset_mm, uint16_t *xtalk_kcps);
+
+/**
+ * @brief   保存校准数据到 Flash（整页擦除后写入）
+ * @details 操作期间会短暂暂停串口接收中断，耗时约几十毫秒
+ * @param[in]  offset_mm: 偏移量，单位 mm
+ * @param[in]  xtalk_kcps: 串扰值，单位 kcps，0..127
+ * @retval   true: 保存成功; false: Flash 操作失败
+ */
+bool calib_store_save(int16_t offset_mm, uint16_t xtalk_kcps);
+
+/**
+ * @brief   擦除 Flash 中的校准数据页
+ * @retval   true: 擦除成功; false: Flash 操作失败
+ */
+bool calib_store_erase(void);
+
+#endif /* CALIB_STORE_H */

Inc/command.h

@@ -9,6 +9,7 @@
 
 #include <stdint.h>
 #include <stdbool.h>
+#include "VL53L4CD_Driver.h"
 
 /**
  * @defgroup Command 命令处理模块
@@ -95,6 +96,27 @@ void command_execute(const char *cmd_str);
  */
 void command_m737_timer_finished_callback(void);
 
+/**
+ * @brief 由主循环推送最近一帧测距结果，供 M3 命令立即查询
+ * @param result 最近一帧测距结果
+ * @ingroup Command
+ */
+void command_set_last_result(const vl53l4cd_result_t *result);
+
+/**
+ * @brief 查询测距上报是否开启（M1/M2 控制）
+ * @retval true 上报开启；false 上报关闭
+ * @ingroup Command
+ */
+bool get_sensor_report_enabled(void);
+
+/**
+ * @brief 开启/关闭测距上报（同时控制 LED），供 M1/M2 命令调用
+ * @param enabled true 开启上报并点亮 LED；false 关闭上报并熄灭 LED
+ * @ingroup Command
+ */
+void set_sensor_report_enabled(bool enabled);
+
 /** @} */ // end of Command group
 
 #endif // COMMAND_H