XGO Duck AI 支持 VL53L5CX ToF，并提供前向测距限制。整机套件包含该模块，基础款不含；摄像头和语音可以在不安装 ToF 时使用，是否能够前进还取决于下面的避障配置。完整物料见套件版本与装箱清单。
连接与实时显示
VL53L5CX 连接到 UNO Q 主板上的 3.3 V Qwiic 口，对应 STM32 Wire1，I²C 七位地址 0x29；它与扩展板 IMU 的 Wire 总线分开。实际线束可对照摄像头和 ToF 接线图。其他模块的供电、电平和引脚应按实际模块确认，不能直接套用裸器件引脚表。传感器在 MCU 启动时探测，建议断电后接好，再启动 App；初始化可能需要数秒。
驾驶舱的 ToF 实时测距 显示 8 × 8、约 5 帧/秒的距离阵列、中心距离和最近有效距离。中心距离取中间四格有效测量的中位数；无有效目标或数据过期显示为空，不是 0 距离。热力图颜色使用 0–2 m 色标，数字距离不以 2 m 截断；实际方向由传感器安装朝向决定。
也可只读查看 http://<板子IP>:9527/api/tof/status。如果确认接了 ToF，连续读取时应检查 state=ranging、fresh=true、seq 递增且 valid_zones > 0；HTTP 200 只说明接口可访问，不代表传感器正在正常测距。未安装与尚未确认是否安装应分别记录。
状态异常时，可在 App 容器中运行 python /app/tools/read-tof.py --seconds 4，排查传感器连接和软件状态；完整诊断步骤见ToF 连接与诊断。更新设备时应使用完整匹配的 AI App。
默认前向限制
前向限制默认启用；它与驾驶舱显示分开运行，不要求页面一直打开。默认取阵列中央 4 × 4 范围的最近有效距离，至少需要 3 个有效区域。普通前进速度不超过 0.2 m/s 时：
- 前方距离在 15 cm 内时逐步减速，10 cm 及以内停止前进指令；更高速度会增加距离裕量。
- ToF 缺失、掉线、数据超过 600 ms 或前方有效区域不足时，暂停前进；聊天等其他功能仍可使用。未安装 ToF 也会出现这一限制。
- 阻挡解除需要连续 3 个不同的有效帧确认前方清空；恢复后需要重新发出前进指令。网页或手柄需先松开方向或回中，避免一直按住后自动续走。
- 停止前进会保留平衡和舵机扭矩，不自动转弯或卸力；后退、侧移和原地转向仍受原有控制条件约束。
不安装 ToF 但需要前进时，可按配置说明将该机器人本地 data/obstacle-avoidance.json 的 enabled 设为 false 并重启 App。关闭后不再有这项前向测距限制；其他反馈、控制权限和停止规则仍然存在。
这是前方测距限速，不是路径规划，也不能保证识别透明物体、悬崖、侧后方障碍或实际制动距离。使用前应确认传感器朝前、窗口无遮挡，并结合安装高度检查地面、机身或外壳是否进入视野；先低速测试。已有样本证明可以读取距离，但不等于经过尺量精度标定。