VL53L1X 的API中文用户手册.pdf

1、 UM2356 用户手册 VL53L1X API用户手 册 介绍 VL53L1X是一款长距离飞行时间传感器 。 本用户手册的目的是描述使用 VL53L1X驱动程序调用以获取测距数据的一组功能。 请参考VL53L1X数据表 。 图 1. VL53L1X测距传感器模 块 1/27 DocID031478 Rev 1 Contents UM2356 2/27 DocID031478 Rev 1 内容 1 VL53L1X系统概 述 4 2 测距 API函数描 述 5 2.1 自主测距说明 5 2.2 时机考虑 . 5 2.3 API函数调用流 程 6 2.3.1 校准流程 . 6 2.3.2 流量 7

2、 2.4 强制测距功能 8 2.4.1 数据初始化 8 2.4.2 静态初始化 8 2.4.3 开始测量 . 8 2.4.4 等待结果：轮 询或中断 8 2.4.5 获取测量 . 8 2.4.6 清楚中断的来源 9 2.4.7 停止测量 . 9 2.5 可选的驱动功能 9 2.5.1 等待启动 . 9 2.5.2 时间预算和测量间期 . 9 2.5.3 距离模式 . 10 2.5.4 限制检查设置 10 2.5.5 阈值 12 2.5.6 感兴趣区域（ ROI）设 置 . 13 2.5.7 Spad数组坐标与场 景 15 2.5.8 光学中心坐标 15 2.5.9 VDDIO配 置 . 16

3、2.6 RangingMeasurementData结 构 . 16 3 校准功能 18 3.1 RefSPAD校 准 18 3.1.1 RefSPAD校准功 能 . 18 3.1.2 RefSPAD校准程 序 . 19 3.1.3 获得 RefSPAD校准结 果 . 19 Contents UM2356 3/27 DocID031478 Rev 1 3.1.4 设置 RefSPAD校准数 据 . 19 3.2 偏移校准 . 20 3.2.1 偏移校准功能 20 3.2.2 偏移校准程序 20 3.2.3 获得偏移 校准结果 20 3.2.4 设置偏移校准数据 20 3.3 串扰校准 . 21

4、 3.3.1 串扰校准功能 21 3.3.2 串扰 校准程序 21 3.3.3 串扰校准距离表征 21 3.3.4 获得串扰校准结果 22 3.3.5 设置串扰校准数据 22 3.3.6 启用 /禁用串扰补 偿 . 23 4 驱动程序错误和警告 24 5 缩略语 26 6 修订记录 27 4/27 DocID031478 Rev 1 VL53L1X system overview UM2356 y s y 1 VL53L1X系统概 述 VL53L1X系统由 VL53L1X模块和在主机上运行的驱动程序组成 。 图 2. VL53L1X系 统 ST提供了一个软件驱动程序，在本文档中称为“驱动程序”

5、 。 本文档介绍主机可以访问的驱动程序功能，以控制设备并获取测距数据。 该驱动程序是使用 VL53L1X器件的一组功能的实现。 它对 OS集成和服务做了最少的假设。 因此，动作的排序，执行 /线程模型，平台适配和设备结构分配不是驱动程序实现的一部分，而是对软件集成商保持开放 。 函数调用的顺序必须遵循本文档中定义的一组规则。 , syusyuosy/5/27 DocID031478 Rev 1 UM2356 Ranging API function descriptions 2 测距 API函数描 述 本节给出了测距的功能描述，并描述了使用 VL53L1X执行测距测量时应遵循的 API呼叫流程

6、 。 2.1 自主测距说明 传感器通过可编程的测量间隔周期连续自动执行测距。 测距是在没有主机参与的情况下完成的，这允许主机处于低功率状态。 当测距可用时，主机仅在测量中断时唤醒 。 可以设置距离和 /或信号检测标准的阈值，然后在满足标准时引发中断 。 2.2 时机考虑 定时预算定义为传感器执行和报告测距测量数据所需的编程时间。 在此期间， VCSEL脉动。 在计时预算结束时引发中断或更新日期就绪寄存器 。 测量间期被定义为两次连续测量之间的编程时间。 图 3 显示时间预算和测量间期。 主机可以通过使用专用驱动程序功能来更改默认的时间预算和测 量间隔时间 第 2.5.2节：时间预算和相互测 量

7、 期 . 主持人可以决定更改时间预算以提高测距精度或最大距离限制。 图 3. VL53L1X自动量程序列和时 序 5DQJLQJ3RZHU6XSSO*3,2 ,QWHUUXSW ;6KXWULYHU 此功能用于编程设备，以便仅在 10 cm和 1 m内检测到物体时报告测距（如本例中） 。 VL53L1_GetThresholdConfig（）函数允许编程的报告阈值配置被禁用 。 2.5.6 感兴趣区域（ ROI）设 置 传感器的接收 SPAD阵列包括覆盖整个视场（ FoV）的 16x16 SPAD。 可以使用较少数量的 SPAD编程较小的感兴趣区域（ ROI），以减少 FoV。 要设置不同于默

8、认 16x16的投资回报率，用户可以拨打电 话 VL53L1_SetUserROI（）函数 。 ROI是由两个角落定义的正方形或矩形：左上角和右下角。 四个坐标用于定位整个SPAD阵列上的这两个角点 ： TopLeftX TopLeftY BotRightX BotRightY 这些坐标是 VL53L1_UserRoi_t结构的一部分 。 用户必须定义 结构中的 ROI坐标值，并调用驱动程序函数来应用 ROI更改 。 最小 ROI大小是 4x4。 ROI设置的示例在中给出 图 6. 14/27 DocID031478 Rev 1 Ranging API function description

9、s UM2356 图 6. VL53L1X ROI设置示 例 VL53L1_UserRoi_t结构包含 ROI的坐标 ： TopLeftX： 8位整数，给出左上角的 x坐标 0; 15 TopLeftY： 8位整数，给出左上角 y坐标 0; 15 BotRightX： 8位整数，给出右下角的 x坐标 0; 15 BotRightY： 8位整数，给出右下角的 x坐标 0; 15 示例设置一个投资回报率（基于 图 6） ：VL53L1_UserRoi_t roiConfig; roiConfig.TopLeftX = 9; roiConfig.TopLeftY = 13; roiConfig.Bo

10、tRightX = 14; roiConfig.BotRightY = 10; status = VL53L1_SetUserROI（ VL53L1Dev， roiConfig） ; 7RS/HIW%RWWRP5LJKWzy/yy/ 7RS/HIW; %RW5LJKW; %RW5LJKW 7RS/HIW RP%RWW/HIWS/hZ15/27 DocID031478 Rev 1 UM2356 Ranging API function descriptions 2.5.7 Spad数组坐标与场 景 图 7 显示与 FoV中的位置相比， SPAD阵列中的对象的坐标 。 图 7. VL53L1X坐标

11、与场 景 2.5.8 光学中心坐标 由于装配公差，设备的光学中心可能会有所不同。 设备的光学中心针对每个部件进行测量。 光学中心坐标存储在设备 NVM中 。 用户可通过调用 VL53L1_GetCalibrationData（）访问光学中心坐标。 返回的结构VL53L1_CalibrationData_t包含一个包含两个坐标（以 SPAD编号表示）的子结构VL53L1_optical_centre_t： x_centre y_centre 主机可以使用这两个坐标来更好地将 ROI与光学中心对齐 。 16/27 DocID031478 Rev 1 Ranging API function des

12、criptions UM2356 2.5.9 VDDIO配 置 如数据表中所述，用户可以为 1V8或 2V8模式的 VDDIO值选择两种模式 。 通过调用编译密钥直接在代码中选择模式 USE_I2C_2V8k。 如果定义了该编译密钥，系统将进入 2V8模式，否则将保持默认的 1V8模式 。 2.6 RangingMeasurementData结 构 VL53L1_RangingMeasurementData_t结构由以下部分组成 ： TimeStamp：未实施，请忽略它 。 StreamCount：这个 8位整数计数器在每个范围内递增。 该值从 0开始，增加到 255，然后从 128增加到 2

13、55。 RangingQualityLevel：未执行，请忽略它 。 SignalRateRtnMegaCps：此值是 MegaCountPer Second（ MCPS）中的返回信号速率。 这是一个 16.16的固定点值。要获得实际值，应该除以 65536。 AmbientRateRtnMegaCps：此值是返回环境速率（以 MCPS计）。 它是一 个 16.16固定点值，这是有效测量红外光的指标。 要获得实际价值，应该除以 65536。 EffectiveSpadRtnCount：这个 16位整数返回当前测距的有效 SPAD计数。 要获得实际值，应该除以 256。 SigmaMilliMe

14、ter：这个 16.16定点值是电流测量的标准偏差的估算，以毫米表示。 要获得实际价值，应该除以 65536。 RangeMilliMeter：这个 16位整数给出了以毫米为单位的范围距离 。 RangeFractionalPart：未执行，请忽略它 。 RangeStatus：这个 8位整数给出当前测量的范围状态。 值为 0表示测距有效（请参阅 表 4). 17/27 DocID031478 Rev 1 UM2356 Ranging API function descriptions 表 4.范围状 态 值 RangeStatus字符 串 评论 0 VL53L1_RANGESTATUS_RA

15、NGE_VALID 测距测量是有效的 1 VL53L1_RANGESTATUS_SIGMA_FAIL 如果西格玛估计器检查高于内部定 义的阈值，则会引发此问 题 2 VL53L1_RANGESTATUS_SIGNAL_FAIL 如果信号值低于内部定义的阈值则产生 4 VL53L1_RANGESTATUS_OUTOFBOUNDS_ FAIL 阶段超出界限时引发 5 VL53L1_RANGESTATUS_HARDWARE_FAIL 在硬件或 VCSEL故障的情况下引 发 7 VL53L1_RANGESTATUS_WRAP_TARGET_ FAIL 包裹的目标，不匹配阶段 8 VL53L1_RANG

16、ESTATUS_PROCESSING_ FAIL 内部算法下溢或溢出 14 VL53L1_RANGESTATUS_RANGE_INVALID 报告的范围无效 18/27 DocID031478 Rev 1 Calibration functions UM2356 3 校准功能 为了充分发挥设备的性能， VL53L1X驱动器包含校准功能，应在客户生产线上运行一次 。 必须运行校准程序以补偿可能影响器件性能的部件间部件参数和玻璃盖的存在。 存储在主机中的校准数据必须在每次启动时使用专用的驱动程序功能加载到 VL53L1X中 。 需要三次校准： RefSPAD，失调和串扰 。 校准函数的调用顺序非常

17、重要：首先调用 RefSPAD，然后偏移第二，串扰第三 。 三种校准功能可以依次进行，也可以单独进行。 当单独运行时，必须在运行当前校准之前加载先前的步骤数据 。 3.1 RefSPAD校 准 ST在最后的模块测试期间校准 SPAD的数量。 该部分对零件的值存储在 NVM中，并在引导期间自动加载到设备中 。 此校准允许调整 SPAD的数量以优化器件动态 。 但是，在模块顶部添加护盖玻璃可能会影响此校准。 我们建议客户在最终产品应用中再次执行此校准 。 在调用此函数时应用在 FMT中运行的相同算法。 该算法搜索三种可能的 SPAD类型 ： 1. 非衰减 SPAD 2. SPAD衰减 5倍 3.

18、SPAD衰减 10倍 选择 SPAD的数量和类型以避免内部信号饱和 。 3.1.1 RefSPAD校准功 能 该操作有专用功能： VL53L1_PerformRefSpadManagement（ VL53L1Dev） 注意： 必须在校准过程中首先调用该功能。 19/27 DocID031478 Rev 1 UM2356 Calibration functions 3.1.2 RefSPAD校准程 序 用户必须确保在校准过程中距离传感器 5厘米处没有距离较近的目标 。 在低红外光条件下（室内）进行校准会更好。 执行此校准的时间仅为几毫秒 。 必 须在调用 VL53L1_DataInit（）和 V

19、L53L1_StaticInit（）函数后调用VL53L1_PerformRefSpadManagement函数。 参考 图 4： VL53L1X校准流 程 . 当调用校准功能时，执行 RefSPAD校准，并在最后应用新的 RefSPAD参数 。 3.1.3 获得 RefSPAD校准结 果 函数 VL53L1_GetCalibrationData（）允许获取所有校准数据。 返回的结构VL53L1_CalibrationData_t还包含一个名为 VL53L1_customer_nvm_managed_t的子结构，其中包含八个 RefSPAD校准参数 ： ref_spad_man num_req

20、uested_ref_spads：此值介于 5和 44之间。它给出了所选 SPAD的数量 。 ref_spad_man ref_location：这个值可 以 非减毒 SPAD SPAD衰减 5倍 SPAD衰减 10倍 六个附加参数给出了所选位置的良好 SPAD图 。 出厂校准后，这些校准数据必须存储在主机存储器中，并在每个设备启动时加载，以避免重新校准。 用户可以存储整个结构 VL53L1_CalibrationData_t或存储八个参数（以节省存储空间） 。 3.1.4 设置 RefSPAD校准数 据 在每次启动时， 硬重置后，用户可以从主机内存中加载 RefSPAD校准数据。 在调用VL

21、53L1_DataInit（）和 VL53L1_StaticInit（）函数之后，必须调用VL53L1_SetCalibrationData（）。 参考 图 5： VL53L1X测距流 程 如果用户在校准过程中优化了校准数据存储，建议通过调用 VL53L1_GetCalibrationData（）来获得整个校准结构，修改 第 3.1.3节：获取 RefSPAD校准结 果 ， 并调用VL53L1_SetCalibrationData（） 。 20/27 DocID031478 Rev 1 Calibration functions UM2356 3.2 偏移校准 在客户板上焊接器件或添加玻璃罩可

22、能会在测距范围内产生偏移。 在零点校准过程中，必须测量和补偿这种零件间偏移 。 3.2.1 偏移校准功能 该操作有专用功能： VL53L1_PerformOffsetSimpleCalibration（ VL53L1Dev， CalDistanceMilliMeter） 该函数的参数是以毫米为单位的偏移校准距离。 注意： 在串扰校准和 RefSPAD优化完成后（校准完成或 RefSPAD参数加载），必须执行偏移校准 。 3.2.2 偏移校准程序 客户必须使用校准图表，放置在给定的距离（ CalDistanceMilliMeter）来执行偏移校准 。 推荐设置的详细信息在中给出 表 5. 表 5

23、.设置偏移校 准 图表 图 表距离（ CalDistanceMilliMeter） 环境条件 灰色目标 （在 940nm下 17的反射率 ） 建议值： 140毫 米 黑暗 （没有投入红利） 当调用校准功能时，执行偏移校准，并在最后应用偏移校正。 3.2.3 获得偏移校准结果 函数 VL53L1_GetCalibrationData（）允许获取所有校准数据。 返回的结构VL53L1_CalibrationData_t还包含一个名为 VL53L1_customer_nvm_managed_t的子结构，其中包含主要的偏移校准结果 ： 算法 part_to_part_range_offset_mm。

24、3.2.4 设置偏移校准数据 客户可以在调用 VL53L1_DataInit（）和 VL53L1_StaticInit（）函数后，使用VL53L1_SetCalibrationData（）加载偏移校准数据 。 但是，最好调用 VL53L1_GetCalibrationData（），修改参数中描述的参数 第 3.2.3节：获得偏移校准结 果 （ algo part_to_part_range_offset_mm）并调用 VL53L1_SetCalibrationData（） 。 21/27 DocID031478 Rev 1 UM2356 Calibration functions 3.3 串扰

25、校准 串扰（ xtalk）定义为由于审美和保护性原因，在模块顶部添加的保护窗（保护玻璃）内由于 VCSEL光反射而在感应阵列上接收的返回信号量 。 根据玻璃罩的质量，返回信号的数量可能很大，并可能影响传感器的性能。 VL53L1X具有内置校正功能，可以补偿这种串扰现象 。 串扰校准用于估计补偿模块顶部添加的玻璃罩所产生的影响所需的校正量。 3.3.1 串扰校准功能 一 个专用功能可用于此操作： VL53L1_PerformSingleTargetXTalkCalibration（VL53L1Dev， XtalkCalDistance） ; 该功能的一个参数是以毫米为单位的串扰校准距离。 注意：

26、 在完成偏移补偿（校准完成或偏移参数加载）之后，此功能必须在校准流程中第三位调用。 3.3.2 串扰校准程序 串扰校准应该在黑暗的环境中进行，没有红外线贡献。 当调用校准功能时，将执行串扰校准，并在最后应用串扰校正。 表 6.设置串扰校 准 图表 图 表距离（ XtalkCalDistance） 环境条件 灰色目标 （在 940nm下 17的反射率 ） 如定义 第 3.3.3节：串 扰 校准距离表征 黑暗 （没有投入红利） 3.3.3 串扰校准距离表征 串扰校准距离需要由用户来表征，因为它取决于系统环境，主要取决于覆盖玻璃材料和光学属性，以及气隙值（传感器和玻璃盖之间的距离）。 图 8： VL

27、53L1X串扰校准距离定义 显示测距曲线上的串扰效应。 从给定的距离，串扰的影响是主要的，传感器开始低于范围 。 22/27 DocID031478 Rev 1 Calibration functions UM2356 图 8. VL53L1X串扰校准距离定 义 串扰校准距离对应于存在盖玻片时传感器报告的最大测距距离（参见图 2） 图 8). 该最大测距距离是串扰校准驱动器功能的一个参数。 串扰校正的测距曲线是应用串扰补偿时（串扰校准完成时或串扰校准数据加载后）的测距结 果 。 3.3.4 获得串扰校准结果 函数 VL53L1_GetCalibrationData（）允许获取所有校准数据。 返

28、回的结构VL53L1_CalibrationData_t还包含一个名为 VL53L1_customer_nvm_managed_t的子结构，其中包含串扰校准结果 ： 算法 crosstalk_compensation_plane_offset_kcps。 3.3.5 设置串扰校准数据 客户可以在调用 VL53L1_DataInit（）和 VL53L1_StaticInit（）函数后，使用VL53L1_SetCalibrationData（）函数加载串扰校准数据 ， 建议调用 VL53L1_GetCalibrationData（），修改VL53L1_customer_nvm_managed_t子

29、结构中的算法crosstalk_compensation_plane_offset_kcps参数，然后调用VL53L1_SetCalibrationData（）应用串扰补偿 。 dPvZvPvPvZvPvPZyol(/oZvPvPZvPvPZyoluvyolovv23/27 DocID031478 Rev 1 UM2356 Calibration functions 3.3.6 启用 /禁用串扰补 偿 调用以启用或禁用串扰补偿的功能是： VL53L1_SetXTalkCompensationEnable（） 。 VL53L1_SetXTalkCompensationEnable（ VL53L1

30、Dev， 0） ; /禁用串扰补偿 。 V53L1_SetXTalkCompensationEnable（ VL53L1Dev， 1） ; /启用串扰补偿 。 注意： 此功能不执行任何串扰校准或数据加载，它只是启用串扰补偿。 必须在启动测距之前调用可选的函数调用 。 24/27 DocID031478 Rev 1 Driver errors and warnings UM2356 4 驱动程序错误和警告 当调用任何驱动程序函数时会报告驱动程序错误。 驱动程序错误的可能值在 表 7. 请注意，存在警告以通知用户某些参数未优化。 警告不是阻 止主机的点 。 表 7.裸机驱动程序错误和警告说 明 错

31、误值 API错误字符 串 发生 0 VL53L1_ERROR_NONE 没有错误 -1 VL53L1_ERROR_CALIBRATION_WARNING 校准数据无效 -4 VL53L1_ERROR_INVALID_PARAMS 无效的参数在函数中设置 -5 VL53L1_ERROR_NOT_SUPPORTED 编程的配置不支持所请求的参数 -6 VL53L1_ERROR_RANGE_ERROR 中断状态不正确 -7 VL53L1_ERROR_TIME_OUT 测距由于超时而中止 -8 VL53L1_ERROR_MODE_NOT_SUPPORTED 请求模式不受支持 -10 VL53L1_ER

32、ROR_CALIBRATION_WARNING 提供的缓冲区大于 I2C支 持 -14 VL53L1_ERROR_INVALID_COMMAND 命令在当前模式下无效 -16 VL53L1_ERROR_REF_SPAD_INIT 参考 SPAD校准期间发生错 误 -22 VL53L1_ERROR_XTALK_EXTRACTION_FAIL 当串扰校准功能没有成功的采样来计算串扰时投射。 在这种情况下，没有足够的信息来生成新的串扰参数信息。 该功能将退出并保持当前的串扰参数不变 。 -23 VL53L1_ERROR_XTALK_EXTRACTION_SIGMA_ LIMIT_FAIL 当串扰校准

33、函数发现 估计超出允许的最大限制时抛出。 在这种情况下，串扰样本的噪声太大，无法进行测量。 该功能将 退出并保持当前的串扰参数不变 。 -24 VL53L1_ERROR_OFFSET_CAL_NO_SAMPLE_ FAIL 偏移校准功能找不到有效测距时抛出。 -28 VL53L1_WARNING_REF_SPAD_CHAR_NOT_ ENOUGH_SPADS 如果有少于 5个可用的 SPAD，则投掷。 确保校准设置符合 ST的建议 。 -29 VL53L1_WARNING_REF_SPAD_CHAR_RATE_ TOO_HIGH 如果最终参考速率大于参考速率上限，则抛出 - 默认值为 40 M

34、cps。 确保校准设置符合 ST的建议 。 -30 VL53L1_WARNING_REF_SPAD_CHAR_RATE_ TOO_LOW 如果最终参考速率低于参考速率下限，则抛出 - 默认值为 10 Mcps。 确保校准设置符合 ST的建议 。 25/27 DocID031478 Rev 1 UM2356 Driver errors and warnings 表 7.裸机驱动程序错误和警告说明（续 ） 错误值 API错误字符 串 发生 -31 VL53L1_WARNING_OFFSET_CAL_MISSING_ SAMPLES 如果有少于所要求的有效样本数量，则抛出。 确保偏移校准设置符合 S

35、T建议 。 -32 VL53L1_WARNING_OFFSET_CAL_SIGMA_ TOO_HIGH 如果偏移校准范围西格玛估计过高，则抛出。 确保偏移校准设置符合 ST建议 。 -33 VL53L1_WARNING_OFFSET_CAL_RATE_ TOO_HIGH 信号速率大于极限且传感器饱和时投射。 确保偏移校准设置符合 ST建议 。 -34 VL53L1_WARNING_OFFSET_CAL_SPAD_ COUNT_TOO_LOW 投掷不足时可以使用 SPADS。 确保偏移校准设置符合 ST建议 。 -41 VL53L1_ERROR_NOT_IMPLEMENTED 所调用的函数未实现 26/27 DocID031478 Rev 1 Acronyms and abbreviations UM2356 5 缩略语 表 8.缩略语和缩 写 首字母缩略词 /缩 写 定义 I2C 内部集成电路（串行总线） NVM 非易失性存储器 SPAD 单光子雪崩二极管 VCSEL 垂直腔面发射激光器 FMT 最终模块测试 API 应用程序接口 27/27 DocID031478 Rev 1 UM2356 Revision history 6 修订记录 表 9.文档修订历史记 录 日期 调整 变化 07-Mar-2018 1 初始发行