Status 5
有效可靠目标。distance_mm 可信任，可用于避障、测距等场景。
✅ 正常使用
VL53L5CX 8×8 ToF Multi-Zone Ranging
VL53L5CX 距离异常 / Status 状态码分析
核心结论：Status=255 的点位不能当真实距离；Status=13 更倾向低置信度/一致性异常。软件应先过滤 invalid zone，再排查盖板、开孔、气隙、遮光 gasket 等光学结构问题。
传感器型号
VL53L5CX
制造商
STMicroelectronics
8×8最多 64 个测距区域
4 m标称最大测距
65°对角线 FoV
参数来自 ST VL53L5CX datasheet 和 UM2884 用户手册。具体性能受盖板、环境和校准影响，实际以测试数据为准。
VL53L5CX 8×8 多区域 ToF 测距传感器
进入淘宝店铺咨询
SKU：待补充
ToF 传感器
Target Status
Status 状态码说明（重点）
VL53L5CX 每个测距 zone 都会返回 target_status 字段。不能只看 distance_mm 数值，必须先检查 status 是否有效。以下根据 ST UM2884、datasheet、ST 社区工程师回复和实际测试数据整理。
Status 9 / 10
有效目标但置信度较低（可能是信号较弱、边缘反射或多路径）。可降级使用，建议热力图加斜线或半透明标记。
⚠ 低置信度，观察使用
Status 13
有目标信号但测量一致性差。常见于盖板/开孔串扰、遮挡、天花板反射弱或环境光干扰等情况。不推荐直接作为稳定测距输出。
⚠ 一致性异常，不可直接使用
Status 255
无有效目标数据。distance_mm 字段的值是无意义的，可能是残留值或噪声。热力图中如果画成 0 mm 或一个很小的数值，会严重误导判断。
🚫 丢弃，不可使用
Status 其他值
ST 的 status 定义会在不同驱动版本中略有调整。遇到非 5/9/10/13/255 的值时，建议查阅对应版本 ULD API 文档，不要猜测含义。
📋 查阅 ST ULD API 文档确认
number_of_targets
如果 number_of_targets < 1，即使 status 看起来合理，此 zone 也不应有有效距离数据。软件应先检查 targets 数量再读 distance。
📋 先检查 targets 数量
8×8 Zone Visualization
8×8 Zone Status 可视化示意
自绘示意图：用红/橙/绿区分 Status 255/13/5 的典型分布。实际项目中每个 zone 的 status 可能不同，以下仅作概念参考。
| 数据状态 | Status 值 | distance 含义 | 热力图建议 |
|---|---|---|---|
| 有效 | 5 | 真实距离，可信任 | 按距离色阶正常显示 |
| 低置信度 | 9 / 10 | 距离可信但质量较低 | 正常色阶 + 斜线/半透明标记 |
| 一致性异常 | 13 | 有测量但一致性差 | 灰色或半透明，不参与避障判断 |
| 无目标 | 255 | 无意义噪声值 | 灰色/透明/NaN，绝不能显示为 0 mm |
Software Filter
软件侧过滤策略
热力图和业务逻辑都应先过滤 target_status，不要只看 distance_mm。以下为基础参考逻辑，实际项目可根据场景调整阈值。
处理原则：先把 invalid zone 过滤掉再画热力图，否则会把无效数据当成 0 mm 显示，严重误导使用者。
保守策略：Status 5 信任使用；Status 9/10 可降级为低置信度观察；Status 13/255 直接丢弃不参与避障。
进阶建议：把每帧的 status、distance、signal、ambient、number_of_targets 一起记录到日志，定位问题会更快。
/// VL53L5CX Zone 数据过滤参考逻辑
/// 先检查 numberOfTargets 和 status，再决定是否使用 distance 值
function interpretZone(status, distance, numberOfTargets) {
// 无目标 = 直接丢弃
if (numberOfTargets < 1) return null;
// Status 5 = 有效数据
if (status === 5) {
return { distance, confidence: "valid" };
}
// Status 9/10 = 低置信度，降级使用
if (status === 9 || status === 10) {
return { distance, confidence: "low" };
}
// Status 13 = 一致性异常，不建议使用
// Status 255 = 无有效目标
// 其他未定义值也按无效处理
return null;
}
/// 热力图显示建议：
/// null zone → 灰色 / 透明 / NaN（绝不能显示为 0 mm）
/// valid zone → 按距离色阶正常显示
/// low confidence → 正常色阶 + 斜线或半透明标记Hardware Debug
硬件/光学结构排查流程
软件过滤后如果异常 zone 仍固定在相同位置，按以下次序排查硬件和光学结构问题。
1裸模块测试：不加外壳、盖板、泡棉，对白墙或天花板测一组 8x8 数据作为基准。
2清洁光窗：确认没有保护膜、胶水、指纹、灰尘。VL53L5CX 对光学表面缺陷很敏感。
3检查开孔和气隙：ST 应用笔记指出气隙增加会增加串扰和信号损失。气隙超过 0.7 mm 时建议使用遮光 gasket。
4逐步加回盖板：裸测正常、加盖板异常，基本可以锁定是 cover glass 或结构件串扰。
5必要时做 Xtalk calibration：有盖板产品需要评估串扰。盖板质量差、脏污或涂层不合适会明显影响近距离线性和稳定性。
| 检查项 | 建议 |
|---|---|
| 盖板材料 | 选低 haze、低缺陷、940 nm 透过率合适的材料，避免粗糙表面和内部杂质。 |
| 涂层 | 避免在关键光路区域增加会导光的透射涂层；必要时使用合适的 AR/AFC 方案。 |
| 遮光 gasket | Tx 发射端和 Rx 接收端之间应降低串光路径，气隙较大时增加黑色 gasket 或 light blocker。 |
| 机械位置 | 模块应尽量贴近盖板并保持平行，避免开孔边缘进入视场。 |
| 焊接检查 | 如果裸测就有固定 zone 异常，排除光学问题后应检查模块焊接和 PCB 设计。 |
Xtalk Calibration
串扰校准（Xtalk Calibration）
有盖板的产品必须做串扰校准，否则近距离（尤其 60 cm 以内）的测量可能严重偏离真实值。以下信息来自 ST UM2884 和 AN5856。
为什么要做 Xtalk
盖板会反射一部分发射光直接进入接收端，形成一个"串扰信号"。如果这个串扰信号没有被校准掉，ToF 传感器会把它误判为近距离目标返回，导致热力图出现不合理的"近距离"点位。
校准条件
在 60 cm 距离、暗环境（无红外干扰）、干净的白色漫反射目标下运行 ULD 提供的 Xtalk 校准函数。确保盖板和 gasket 已按最终产品状态安装。
校准失败排查
如果 Xtalk 校准反复失败，检查：盖板是否脏污、目标是否满足条件、环境是否有强红外源。校准数据写入模块后应断电再上电验证。
FAQ
常见问题与排查
热力图上出现 0 mm、1 mm、6 mm 之类很近距离的点位，是不是传感器坏了？
先看目标状态。如果这些 zone 的 target_status 是 255，说明没有有效数据，distance 值无意义，不能当作真实距离。软件应先把 status=255 的 zone 标记为 invalid（灰色/透明），不能显示为 0 mm。
大量 zone 返回 Status 13，怎么处理？
Status 13 表示有目标信号但一致性差。先排除光学结构问题：拆掉外壳/盖板裸测，如果裸测正常则锁定结构串扰。再检查盖板材料、开孔大小、气隙、遮光 gasket 是否达标。
异常 zone 总是固定在某几个位置，是什么原因？
如果每次都是同一批 zone 异常，通常更像是结构视场遮挡或局部光学污染。拆掉外壳和盖板裸测，再逐步加回结构件定位是哪个部件引起的。
加了盖板后近距离测量不准，不加盖板是准的，怎么办？
典型的光学串扰问题。参考 ST AN5856 的盖板设计指南，检查材料、涂层和气隙，并按 ST UM2884 的步骤做 Xtalk calibration。如果盖板质量差或脏污，校准后仍可能不稳定，需要更换盖板。
VL53L5CX 最大能测多远？盖板对测距有什么影响？
datasheet 标称最大 4 m（暗环境、白色目标、无盖板）。加盖板后有效距离会降低，具体取决于盖板的 940 nm 透过率、haze 和反射特性。ST AN5856 中有详细的盖板选材和设计建议。
Customer Service
客户售后话术
客服快速回复参考。先引导排查软件过滤，再排查硬件结构。
References
公开资料链接
只放 ST 官方公开文档和社区链接。不放客户截图、订单信息或聊天隐私。
UM2884
ST VL53L5CX ULD User Manual
确认驱动初始化、校准流程、结果结构体字段解释和 target_status 定义。
打开 ST 官网 PDFDatasheet
VL53L5CX 数据手册
确认 8×8、最大 4 m、FoV、cover glass crosstalk 说明等基础规格。
打开 ST 官网 PDFAN5856
VL53L5CX Cover Glass Guidelines
ST 官方应用笔记，确认盖板材料选择、气隙设计、gasket、haze、涂层和串扰建议。
打开 ST 官网 PDFDriver
STSW-IMG023 ULD API
ST 官方 C 语言驱动和示例代码，包含 Xtalk calibration 函数和结果解析例程。
打开 ST 官网Community
ST Community: Out-of-range values
ST 工程师强调需要检查 number of targets 和 target status，只使用有效数据。Status=255 的距离值不可用。
打开 ST Community待补充
更多资料持续整理
后续如有客户常见问题、新的排查经验或测试数据，会继续补充到此页面。
待更新