0. 前言

• VL53L5CX简单来说就是一个可以选择 8x8 或者 4x4 个像素的tof测距传感器，视场角63度，价格便宜、体积小、功耗低，同时由于数据量比较小，对算力要求也比较低。

• 在小型机器人等设备上使用，可以使其具备一定的环境感知能力，在某些特定场景使用可能还会产出意想不到的价值。

• 本文参考官方英文文档UM2884翻译和修改，核心内容均进行了校准和注释，非核心的部分直接用了机翻，大家可以与原文档比对参考.

1. 简介

本用户手册的目的是解释如何使用 Ultra lite 驱动程序 (ULD) API 处理 VL53L5CX 飞行时间 (ToF) 传感器。它描述了对设备进行编程、校准和输出结果的主要功能。

VL53L5CX 是一种先进的 ToF 多区域测距传感器，增强了 ST FlightSense 产品系列。它采用微型可回流焊封装，集成了 SPAD 阵列、物理红外滤光片和衍射光学元件 (DOE)，可通过各种盖玻片材料在各种环境照明条件下实现最佳测距性能。

多区域距离测量可多达 8x8 个区域，具有 63° 对角线视场 (FoV)，可通过软件缩小。 VL53L5CX 的每个区域以 60 Hz 的最大频率测量目标的距离，最长可达 4 米。

由于 ST Histogram 专利算法，VL53L5CX 能够检测 FoV 内的不同物体。直方图还提供了对超过 60 厘米的盖玻片串扰的免疫力。

2.功能说明

2.1 系统概述

VL53L5CX 系统由硬件模块和运行在主机上的 Ultra lite 驱动软件（VL53L5CX ULD）组成（见下图）。硬件模块包含 ToF 传感器。 ST 提供的软件驱动程序在本文档中称为“驱动程序”。本文档描述了主机可以访问的驱动程序的功能。这些函数控制传感器并获取测距数据。

2.2 有效方向

该模块包括一个位于 RX 光圈上方的镜头，可翻转（水平和垂直）捕获的目标图像。因此，SPAD 阵列左下方标识为区域 0 的区域被位于场景右上角的目标照亮。

2.3 原理图和 I2C 配置

驱动程序和固件之间的通信由 I2C 处理，工作频率高达 1 MHz。该实施需要在 SCL 和 SDA 线上进行上拉。有关详细信息，请参阅 VL53L5CX 数据表。
VL53L5CX 器件的默认 I2C 地址为 0x52。但是，可以更改默认地址以避免与其他设备发生冲突，或者便于将多个 VL53L5CX 模块添加到系统中以获得更大的系统 FoV。可以使用 vl53l5cx_set_i2c_address() 函数更改 I2C 地址。

为了允许设备更改其 I2C 地址而不影响 I2C 总线上的其他设备，禁用未更改设备的 I2C 通信非常重要。程序如下：

1. 正常启动系统。
2. 将地址不变的器件的 LPn 引脚拉低。
3. 将 I2C 地址改变的器件的 LPn 引脚上拉。
4. 使用函数 set_i2c_address() 将 I2C 地址编程到设备中。
5. 上拉未重新编程器件的 LPn 引脚。
   现在所有设备都应该在 I2C 总线上可用。对系统中需要新 I2C 地址的所有 VL53L5CX 设备重复上述步骤。

3 包内容和数据流

3.1 驱动架构和内容

VL53L5CX ULD 包由四个文件夹组成。驱动程序位于文件夹 /VL53L5CX_ULD_API 中。
驱动程序由强制和可选文件组成。可选文件是用于扩展 ULD 功能的插件。每个插件都以“vl53l5cx_plugin”开头（例如 vl53l5cx_plugin_xtalk.h）。如果用户不想要推荐的插件，可以在不影响其他驱动程序功能的情况下删除它们。下图表示强制文件和可选插件。

用户还需要实现位于 /Platform 文件夹中的两个文件。提议的平台是一个空壳，必须填充专用功能。

注意：Platform.h 文件包含使用 ULD 的必需宏。所有文件内容都是正确使用 ULD 所必需的。

3.2 校准流程（Calibration flow）

串扰 (xtalk) 定义为 SPAD 阵列上接收到的信号量，这是由于 VCSEL 光在模块顶部添加的保护窗口（盖玻璃）内的反射造成的。 VL53L5CX 模块经过自校准，无需任何额外校准即可使用。

如果模块有盖玻片保护，则可能需要进行 Xtalk 校准。由于直方图算法，VL53L5CX 不受 60 cm 以上的 xtalk 影响，但在 60 cm 以下的短距离内，xtalk 可能大于实际返回的信号，从而给出错误的目标读数或使目标看起来比实际距离更近。所有 xtalk
校准功能包含在 xtalk 插件中（可选）。用户需要使用文件‘vl53l5cx_plugin_xtalk’。

xtalk可以校准一次，数据可以保存以备后用。需要具有已知反射率的固定距离目标。所需的最小距离为 600 毫米，并且目标必须覆盖整个 FoV。根据设置，用户可以修改设置以适应 Xtalk 校准，如下表所示。

注意：增加样本数量会提高准确度，但也会增加校准时间。 相对于样本数量的时间是线性的，并且值遵循近似超时：
• 1 个样本 ≈ 1 秒
• 4 个样本 ≈ 2.5 秒
• 16 个样本 ≈ 8.5 秒

使用函数 vl53l5cx_calibrate_xtalk() 执行校准。 这个功能可以随时使用。
但是，必须首先初始化传感器。 下图表示 Xtalk 校准流程。

3.3 测距流程

下图表示用于获取测量值的测距流程。在开始测距会话之前，必须使用 Xtalk 校准和可选函数调用。在测距会话期间不能使用获取/设置功能，并且不支持“即时”编程。

1. 初始化传感器 vl53l5cx_init()
2. (可选) Xtalk Calibration
3. (可选) 函数调用：更改分辨率、频率、曝光时间等
4. 开始测距 vl53l5cx_start_ranging()
5. 等待数据准备就绪：使用函数 vl53l5cx_check_data_ready()
6. 获取测量值 vl53l5cx_get_ranging_data()
7. 结束测距 vl53l5cx_stop_ranging()

4. 可用功能

VL53L5CX ULD API 包含多个功能，允许用户根据用例调整传感器。以下部分介绍了驱动程序可用的所有功能。

4.1 初始化

在使用 VL53L5CX 传感器之前必须进行初始化。此操作要求用户：

1. 开启传感器（VDDIO、AVDD、LPn 引脚设置为高电平，引脚 I2C_RST 设置为 0）
2. 调用函数 vl53l5cx_init()。该函数通过在 I2C 接口上加载代码并执行引导例程来完成初始化，从而将固件（约 84 KB）复制到模块。

4.2 传感器重置管理

要重置设备，需要切换以下引脚：

1. 将引脚 VDDIO、AVDD 和 LPn 引脚设置为低电平。
2. 等待 10 毫秒。
3. 将引脚 VDDIO、AVDD 和 LPn 引脚设置为高电平。

注意：仅切换 I2C_RST 引脚会重置 I2C 通信。

4.3 分辨率

分辨率对应于可用区域的数量。 VL53L5CX 传感器有两种可能的分辨率：4x4（16 个区域）和 8x8（64 个区域）。默认情况下，传感器被编程为 4x4。

函数 vl53l5cx_set_resolution() 允许用户更改分辨率。由于测距频率取决于分辨率，因此必须在更新测距频率之前使用此功能。此外，更改分辨率还会增加读取结果时 I2C 总线上的流量大小。

4.4 测距频率

测距频率可用于改变测量频率。由于 4x4 和 8x8 分辨率的最大频率不同，因此需要在选择分辨率后使用此功能。

4x4最小频率1Hz，最大60Hz；8x8最小频率1Hz，最大15Hz。

测距频率可以使用函数 vl53l5cx_set_ranging_frequency_hz() 更新。 默认情况下，测距频率设置为 1 Hz。

4.5 测距模式

测距模式允许用户在高性能或低功耗测距之间进行选择。提出了两种模式：

• 连续(Continuous)：设备以用户定义的测距频率连续抓取帧。 VCSEL 在所有测距期间启用，因此最大测距距离和环境抗扰度更好。建议使用此模式进行快速测距测量或高性能。

• 自主(Autonomous)：这是默认模式。该设备以用户定义的测距频率连续抓取帧。 VCSEL 在用户定义的时间段内启用，使用函数 vl53l5cx_set_integration_time_ms()。由于 VCSEL 并不总是启用，因此功耗会降低。随着测距频率的降低，好处更加明显。建议将此模式用于低功耗应用。

可以使用函数 vl53l5cx_set_ranging_mode() 更改测距模式。

4.6 积分时间/曝光时间（Integration time）

积分时间是一项仅在使用自主测距模式时可用的功能（请参阅第 4.5 节测距模式）。 它允许用户在启用 VCSEL 时更改时间。 如果测距模式设置为连续，则更改积分时间无效。 默认积分时间设置为 5 ms。
对于 4x4 和 8x8 分辨率，积分时间的影响是不同的。 分辨率 4x4 由一个积分时间组成，8x8 分辨率由四个积分时间组成。 下图表示两种分辨率的 VCSEL 发射。

所有积分时间之和 + 1 ms 开销必须低于测量周期，否则测距周期将自动增加。

4.7 电源模式

不使用设备时，可以使用电源模式来降低功耗。 VL53L5CX 可以在以下电源模式之一下运行：

• 唤醒：设备设置为HP 空闲（高功率），等待指令。
• 睡眠：设备设置为LP 空闲（低功耗），即低功耗状态。在设置为唤醒模式之前，设备无法使用。此模式保留固件和配置。

可以使用函数 vl53l5cx_set_power_mode() 更改电源模式。默认模式是唤醒。

注意：如果用户想改变电源模式，设备一定不能处于测距状态。

4.8 锐化度（Sharpener）

从目标返回的信号不是具有尖锐边缘的干净脉冲。边缘倾斜并可能影响相邻区域中报告的距离。锐化器用于去除由遮蔽式眩光引起的部分或全部信号。
下图所示的示例表示在 FoV 中心 100 mm 处的近距离目标，以及在 500 mm 处更远的另一个目标。根据锐化器值，接近目标可能出现在比真实目标更多的区域中。

可以使用函数 vl53l5cx_set_sharpener_percent() 更改Sharpener。允许的值介于 0 % 和 99 % 之间。默认值为 5%。

4.9 目标顺序

VL53L5CX 可以测量每个区域的多个目标。 由于直方图处理，主机能够选择报告目标的顺序。 有两种选择：

• 最近的：最接近的目标是最先报告的目标
• 最强：最强目标是最先报告的目标

可以使用函数 vl53l5cx_set_target_order() 更改目标顺序。 默认顺序是最强的。
下图中的例子代表了两个目标的检测。 一种在 100 毫米处具有低反射率，另一种在 500 毫米处具有高反射率。

4.10 每个区域有多个目标

VL53L5CX 每个区域最多可以测量四个目标。 用户可以配置传感器返回的目标数量。

无法从驱动程序中选择； 它必须在“platform.h”文件中完成。 宏 VL53L5CX_NB_TARGET_PER_ZONE 需要设置为 1 到 4 之间的值。第 4.9 节目标顺序中描述的目标顺序将直接影响检测到的目标的顺序。 默认情况下，传感器每个区域最多只能输出一个目标。

注意：增加每个区域的目标数量将增加所需的 RAM 大小。

4.11 Xtalk 边距

Xtalk 边距是一项附加功能，只能使用插件 Xtalk。 需要使用 .c 和 .f 文件“vl53l5cx_plugin_xtalk”。

当传感器顶部存在盖玻片时，余量用于更改检测阈值。 在设置 Xtalk 校准数据后，可以增加阈值以确保永远不会检测到盖玻片。

例如，用户可以在一台设备上运行 Xtalk 校准，并为所有其他设备重复使用相同的校准数据。 Xtalk 余量可用于调整 Xtalk 校正。 下图表示 Xtalk 余量。

4.12 检测阈值

除了常规测距功能外，传感器还可以编程以在某些预定义标准下检测物体。使用插件“检测阈值”可以使用此功能，该选项默认情况下不包含在 API 中。需要使用名为“vl53l5cx_plugin_detection_thresholds”的文件。

当满足用户定义的条件时，该功能可用于触发引脚 A3 (INT) 的中断。有三种可能的配置：

• 分辨率 4x4：每个区域使用 1 个阈值（总共 16 个阈值）
• 分辨率 4x4：每个区域使用 2 个阈值（总共 32 个阈值）
• 分辨率 8x8：每个区域使用 1 个阈值（总共 64 个阈值）

无论使用何种配置，创建阈值的过程和 RAM 大小都是相同的。对于每个阈值组合，需要填写几个字段：

• Zone id：所选区域的 id（请参阅第 2.2 节有效方向）
• 测量：要捕获的测量（距离、信号、SPAD 数量……）
• 类型：测量窗口（窗口内、窗口外、低于低阈值……）
• 低阈值：触发的低阈值用户。用户无需设置格式，由 API 自动处理。
• 高阈值：触发的高阈值用户。用户无需设置格式，由 API 自动处理。
• 数学运算：仅用于 4x4 – 每个区域 2 个阈值组合。用户可以在一个区域中使用多个阈值设置组合。

4.13 运动指示器

VL53L5CX 传感器具有嵌入式固件功能，允许在场景中进行运动检测。运动指示符是在连续帧之间计算的。使用插件可以使用此选项
‘vl53l5cx_plugin_motion_indicator’。

使用 vl53l5cx_motion_indicator_init() 函数初始化运动指示器。如果用户想要更改传感器分辨率，他必须使用专用函数更新运动指示器分辨率：vl53l5cx_motion_indicator_set_resolution()。

用户还可以更改检测运动的最小和最大距离。最小和最大距离之差不能大于 1500 mm。默认情况下，距离的初始化值介于 400 mm 和 1500 mm 之间。

结果存储在“motion_indicator”字段中。在该字段中，数组“motion”给出了一个包含每个区域的运动强度的值。高值表示帧之间的高运动变化。典型的移动给出的值介于 100 和 500 之间。此灵敏度取决于积分时间、目标距离和目标
反射率。

低功耗应用的理想组合是使用具有自主测距模式的运动指示器，以及针对运动编程的检测阈值。这允许以最小的功耗检测 FoV 中的运动变化。

5 测距结果

5.1 可用数据

在测距活动期间，可能会输出大量目标和环境数据。 下表描述了用户可用的参数。

表 3. 使用 VL53L5CX 传感器的可用输出

注意：对于多个元素（每个 Spad 的信号、sigma 等），如果用户为每个区域编程了超过 1 个目标（请参阅第 4.10 节每个区域多个目标），则对数据的访问是不同的。 有关详细信息，请参阅示例代码。

5.2 自定义输出选择

默认情况下，启用所有 VL53L5CX 输出。 如果需要，用户可以禁用某些传感器输出。

禁用测量在驱动程序上不可用； 它必须在“platform.h”文件中执行。 用户可以声明以下宏来禁用输出：

#define VL53L5CX_DISABLE_AMBIENT_PER_SPAD
#define VL53L5CX_DISABLE_NB_SPADS_ENABLED
#define VL53L5CX_DISABLE_NB_TARGET_DETECTED
#define VL53L5CX_DISABLE_SIGNAL_PER_SPAD
#define VL53L5CX_DISABLE_RANGE_SIGMA_MM
#define VL53L5CX_DISABLE_DISTANCE_MM
#define VL53L5CX_DISABLE_TARGET_STATUS
#define VL53L5CX_DISABLE_REFLECTANCE_PERCENT
#define VL53L5CX_DISABLE_MOTION_INDICATOR

因此，字段不会在结果结构中声明，数据也不会传输到主机。 RAM 大小和 I2C 大小减小。

为确保数据一致性，ST 建议始终启用“number of target detected”和“target status”。 它允许根据目标状态过滤测量值（请参阅第 5.5 节结果解释）。

5.3 获取测距结果

在测距会话期间，有两种方法可以知道是否有新的测距数据可用：

• 轮询模式：持续使用函数vl53l5cx_check_data_ready()。 它将检测传感器返回的新流计数。

• 中断模式：等待引脚A3 (GPIO1) 产生中断。 约 100 μs 后中断自动清除。

当新数据准备好时，可以使用函数 vl53l5cx_get_ranging_data() 读取结果。 它将返回一个包含所有选定输出的更新结构。 由于设备是异步的，因此无需清除中断即可继续测距会话。

此功能适用于连续测距和自主测距模式。

5.4 使用原始固件格式

通过 I2C 传输测距数据后，固件格式与主机格式之间存在转换。 通常执行此操作以具有以毫米为单位的测距距离作为传感器的默认输出。 如果用户要使用固件格式，必须在平台文件中定义如下宏：

#define VL53L5CX_USE_RAW_FORMAT

5.5 结果解读

可以过滤 VL53L5CX 返回的数据以考虑目标状态。 状态指示测量有效性。 下表描述了完整的状态列表。

表 4. 可用目标状态列表

要获得一致的数据，用户需要过滤无效的目标状态。 为了给出置信度等级，状态为 5 的目标被视为 100% 有效。 可以认为 6 或 9 的状态具有 50% 的置信度值。 所有其他状态均低于 50 % 置信水平。

5.6 驱动程序错误

当使用 VL53L5CX 传感器发生错误时，驱动程序会返回特定错误。 下表列出了可能的错误。

表 5. 使用驱动程序可用的错误列表

注意：主机可以使用平台文件实现更多错误代码。

6 参考资料：

1. 官方手册原文(UM2884)：具有宽视野ULD的VL53L5CX多区域TOF测距传感器的使用指南
2. 官方介绍：https://www.stmicroelectronics.com.cn/zh/imaging-and-photonics-solutions/vl53l5cx.html
3. 其他官方手册：https://www.stmicroelectronics.com.cn/zh/imaging-and-photonics-solutions/vl53l5cx.html#documentation