generated from hulk/gd32e23x_template_cmake_vscode
223 lines
8.8 KiB
C
223 lines
8.8 KiB
C
/**
|
||
* @file VL53L4CD_Driver.h
|
||
* @brief VL53L4CD 测距传感器驱动接口
|
||
*
|
||
* 基于 ST VL53L4CD ULD 和 Pololu 参考实现，寄存器地址均为 16 位，
|
||
* 通过项目现有硬件 I2C0 (PA9/PA10) 访问。
|
||
*/
|
||
#ifndef VL53L4CD_DRIVER_H
|
||
#define VL53L4CD_DRIVER_H
|
||
|
||
#include <stdbool.h>
|
||
#include <stdint.h>
|
||
|
||
/* 板载默认 7 位 I2C 地址，VL53L4CD 出厂默认 0x29 */
|
||
#define VL53L4CD_I2C_ADDR 0x29U
|
||
|
||
/* 寄存器地址 */
|
||
#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
|
||
#define VL53L4CD_REG_RANGE_CONFIG_A 0x005EU
|
||
#define VL53L4CD_REG_RANGE_CONFIG_B 0x0061U
|
||
#define VL53L4CD_REG_SIGMA_THRESHOLD 0x0064U
|
||
#define VL53L4CD_REG_MIN_COUNT_RATE_RTN_LIMIT 0x0066U
|
||
#define VL53L4CD_REG_INTERMEASUREMENT_MS 0x006CU
|
||
#define VL53L4CD_REG_THRESH_HIGH 0x0072U
|
||
#define VL53L4CD_REG_THRESH_LOW 0x0074U
|
||
#define VL53L4CD_REG_SYSTEM_INTERRUPT_CLEAR 0x0086U
|
||
#define VL53L4CD_REG_SYSTEM_START 0x0087U
|
||
#define VL53L4CD_REG_RESULT_RANGE_STATUS 0x0089U
|
||
#define VL53L4CD_REG_RESULT_SPAD_NB 0x008CU
|
||
#define VL53L4CD_REG_RESULT_SIGNAL_RATE 0x008EU
|
||
#define VL53L4CD_REG_RESULT_AMBIENT_RATE 0x0090U
|
||
#define VL53L4CD_REG_RESULT_SIGMA 0x0092U
|
||
#define VL53L4CD_REG_RESULT_DISTANCE 0x0096U
|
||
#define VL53L4CD_REG_RESULT_OSC_CALIBRATE_VAL 0x00DEU
|
||
#define VL53L4CD_REG_FIRMWARE_SYSTEM_STATUS 0x00E5U
|
||
#define VL53L4CD_REG_IDENTIFICATION_MODEL_ID 0x010FU
|
||
|
||
/* 等待固件启动 / 数据就绪的最大时间 */
|
||
#define VL53L4CD_BOOT_TIMEOUT_MS 200U
|
||
#define VL53L4CD_DATA_TIMEOUT_MS 500U
|
||
|
||
/* 一次结果块读包含的字节数：0x89..0x97 */
|
||
#define VL53L4CD_RESULT_BLOCK_SIZE 15U
|
||
|
||
/* 测距状态码（已由原始状态映射为用户可读状态） */
|
||
typedef enum {
|
||
VL53L4CD_STATUS_RANGE_VALID = 0, /* 测距有效 */
|
||
VL53L4CD_STATUS_SIGMA_FAIL, /* Sigma 超限 */
|
||
VL53L4CD_STATUS_SIGNAL_FAIL, /* 信号强度不足 */
|
||
VL53L4CD_STATUS_MIN_RANGE_FAIL, /* 目标过近 */
|
||
VL53L4CD_STATUS_PHASE_FAIL, /* 相位故障 */
|
||
VL53L4CD_STATUS_HW_FAIL, /* 硬件故障 */
|
||
VL53L4CD_STATUS_NO_TARGET, /* 未检测到目标 */
|
||
VL53L4CD_STATUS_SIGNAL_FAIL_NEAR, /* 近距离信号不足 */
|
||
VL53L4CD_STATUS_OUT_OF_BOUNDS, /* 超出边界 */
|
||
VL53L4CD_STATUS_XTALK_SIGNAL_FAIL, /* 串扰信号失败 */
|
||
VL53L4CD_STATUS_LOW_SIGNAL_FAIL, /* 低信号失败 */
|
||
VL53L4CD_STATUS_CROSSTALK_SIGNAL_FAIL,/* 串扰信号失败 */
|
||
VL53L4CD_STATUS_AMBIENT_SIGNAL_FAIL, /* 环境光信号失败 */
|
||
VL53L4CD_STATUS_SNSPD_AMBIENT_FAIL, /* 单光子雪崩二极管环境光失败 */
|
||
VL53L4CD_STATUS_UNKNOWN = 255 /* 未知状态 */
|
||
} vl53l4cd_range_status_t;
|
||
|
||
/* 单次测量结果 */
|
||
typedef struct {
|
||
uint16_t distance_mm; /* 距离，单位 mm */
|
||
uint8_t range_status; /* 测距状态码 */
|
||
uint8_t number_of_spad; /* 有效 SPAD 数 */
|
||
uint32_t signal_rate_kcps; /* 信号速率，单位 kcps */
|
||
uint32_t ambient_rate_kcps; /* 环境光速率，单位 kcps */
|
||
uint32_t signal_per_spad_kcps; /* 每 SPAD 信号速率 */
|
||
uint32_t ambient_per_spad_kcps; /* 每 SPAD 环境光速率 */
|
||
uint16_t sigma_mm; /* Sigma，单位 mm */
|
||
} vl53l4cd_result_t;
|
||
|
||
/**
|
||
* @brief 初始化 VL53L4CD
|
||
* @param[in] none
|
||
* @retval true: 初始化成功; false: 初始化失败
|
||
*/
|
||
bool vl53l4cd_init(void);
|
||
|
||
/**
|
||
* @brief 启动连续测距
|
||
* @param[in] none
|
||
* @retval true: 启动成功; false: 启动失败
|
||
*/
|
||
bool vl53l4cd_start_ranging(void);
|
||
|
||
/**
|
||
* @brief 停止连续测距
|
||
* @param[in] none
|
||
* @retval true: 停止成功; false: 停止失败
|
||
*/
|
||
bool vl53l4cd_stop_ranging(void);
|
||
|
||
/**
|
||
* @brief 检查是否有新测距结果
|
||
* @param[in] none
|
||
* @retval true: 有新结果; false: 无新结果或读取失败
|
||
*/
|
||
bool vl53l4cd_data_ready(void);
|
||
|
||
/**
|
||
* @brief 清除测距完成中断
|
||
* @param[in] none
|
||
* @retval true: 清除成功; false: 清除失败
|
||
*/
|
||
bool vl53l4cd_clear_interrupt(void);
|
||
|
||
/**
|
||
* @brief 读取并解析一次测距结果
|
||
* @param[out] result: 结果结构体指针
|
||
* @retval true: 读取成功; false: 读取失败
|
||
*/
|
||
bool vl53l4cd_get_result(vl53l4cd_result_t *result);
|
||
|
||
/**
|
||
* @brief 设置测距时序预算和测距周期
|
||
* @param[in] timing_budget_ms: 10..200 ms
|
||
* @param[in] inter_measurement_ms: 当前驱动只支持 0（连续模式）
|
||
* @retval true: 设置成功; false: 参数无效或设置失败
|
||
*/
|
||
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 写入串扰（玻璃反射）补偿值，透过玻璃测距时使用
|
||
* @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
|
||
* @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 执行一次串扰校准（透过玻璃安装时使用）
|
||
* @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 位寄存器地址
|
||
* @param[out] value: 返回值指针
|
||
* @retval true: 成功; false: 失败
|
||
*/
|
||
bool vl53l4cd_read_reg8(uint16_t reg, uint8_t *value);
|
||
|
||
/**
|
||
* @brief 读一个 16 位寄存器
|
||
* @param[in] reg: 16 位寄存器地址
|
||
* @param[out] value: 返回值指针
|
||
* @retval true: 成功; false: 失败
|
||
*/
|
||
bool vl53l4cd_read_reg16(uint16_t reg, uint16_t *value);
|
||
|
||
/**
|
||
* @brief 写一个 8 位寄存器
|
||
* @param[in] reg: 16 位寄存器地址
|
||
* @param[in] value: 写入值
|
||
* @retval true: 成功; false: 失败
|
||
*/
|
||
bool vl53l4cd_write_reg8(uint16_t reg, uint8_t value);
|
||
|
||
/**
|
||
* @brief 写一个 16 位寄存器
|
||
* @param[in] reg: 16 位寄存器地址
|
||
* @param[in] value: 写入值
|
||
* @retval true: 成功; false: 失败
|
||
*/
|
||
bool vl53l4cd_write_reg16(uint16_t reg, uint16_t value);
|
||
|
||
#endif /* VL53L4CD_DRIVER_H */
|