mobile_comm/luatos/air780epm/module/Air780EPM/demo/sensor/vl53l1x

VL53L1X 激光红外测距传感器演示

一、功能模块介绍

1.1 核心主程序模块

1. main.lua - 主程序入口，负责项目初始化、版本定义和任务调度
2. vl53l1x_demo.lua - VL53L1X 功能演示模块，包含标准测距、模式切换、休眠唤醒、持续测距等所有功能的演示用例

1.2 扩展库模块

1. exs_vl53l1x - VL53L1X 扩展库，提供初始化、测距数据读取、模式切换、睡眠/唤醒、关闭等 API

1.3 诊断工具模块（按需使用）

1. vl53l1x_scan.lua - 基础扫描：I2C 地址检测、软件复位、固件状态、Model ID 读取
2. vl53l1x_deep_scan.lua - 深度扫描：扫描全寄存器，判断芯片响应是否正常
3. vl53l1x_xshut_test.lua - XSHUT 硬件复位测试

注：诊断工具模块需要在 main.lua 中通过 require 切换加载，不参与演示流程。

二、演示流程介绍

本 demo 按顺序演示 exs_vl53l1x 扩展库的 4 项功能：HELLO → [1/4] → [2/4] → [3/4] → [4/4] → End

2.1 功能演示项说明

1. [1/5] 标准测距 - 初始化传感器，连续读取 5 次距离数据（默认 standard 模式）
2. [2/4] 测距模式切换 - 演示 short（抗强光）和 long（远距离）两种模式切换
3. [3/4] 休眠与唤醒 - 演示 sleep() 进入软件待机、wakeup() 唤醒恢复测距
4. [4/4] 持续测距 - 演示 sleep() 进入软件待机、wakeup() 唤醒恢复测距 ** - 每隔 1 秒读取一次距离数据，共 5 次

三、演示硬件环境

3.1 硬件清单

• Air780EPM 核心板 × 1

• VL53L1X 激光红外测距传感器模块（如 GY-VL53L1X 等） × 1 demo所演示的VL53L1X 激光红外测距传感器模块购买链接

• 母对母杜邦线 × 4

• TYPE-C 数据线 × 1

3.2 接线配置

3.2.1 I2C 模式接线

Air780EPM 核心板	VL53L1X 模块
32/GPIO31	SCL
31/GPIO30	SDA
VDD_EXT	VCC（3.3V）
GND	GND

说明：接线时注意杜邦线不宜过长，以免通信不稳定。VL53L1X 模块上的 SCL/SDA 通常已集成上拉电阻，无需额外配置。XSHUT 引脚不接时传感器会自动启动。

四、演示软件环境

4.1 开发工具

• Luatools下载调试工具 - 固件烧录和代码调试

4.2 内核固件

• 点击下载Air780EPM系列最新版本内核固件，demo所使用的是 LuatOS-SoC_V2046_Air780EPM 1号固件

4.3 脚本文件

1. main.lua - 程序入口
2. vl53l1x_demo.lua - VL53L1X 功能演示模块
3. exs_vl53l1x - VL53L1X 扩展库

五、演示核心步骤

5.1 硬件准备

1. 按照接线表将 VL53L1X 模块连接到核心板
2. 确保电源连接正确，通过 TYPE-C USB 口供电
3. 检查所有接线无误，避免短路

5.2 软件配置

在 main.lua 中加载对应的演示模块：

-- 加载 vl53l1x_demo.lua 演示模块
require "vl53l1x_demo"

5.3 软件烧录

1. 使用 Luatools 选择最新内核固件
2. 下载本项目所有脚本文件
3. 将固件和脚本一起烧录到设备
4. 烧录成功后设备自动重启后开始运行

5.4 功能测试

5.4.1 标准测距演示

1. 设备启动后打印 "HELLO"，随后自动进入 [1/5] 标准测距
2. 观察日志输出，确认初始化成功（应看到 MID=0xEA MT=0xCC）
3. 观察距离数据（单位 mm）的连续读取，共 5 次

5.4.2 测距模式切换演示

1. 自动进入 [2/4] 测距模式切换
2. short 模式：抗环境光干扰最强，适合窗口附近等强光环境
3. long 模式：最远可测约 3.6m，适合室内暗光远距离场景

5.4.3 休眠与唤醒演示

1. 自动进入 [3/4] 休眠与唤醒演示
2. 读一次当前距离作为参考
3. sleep() 进入软件待机（约 6μA），3 秒后 wakeup() 唤醒恢复测距
4. 观察唤醒后测距是否正常恢复

5.4.4 持续测距演示

1. 自动进入 [4/4] 持续测距演示
2. 每隔 1 秒读取一次距离数据，共 5 次
3. 观察数据稳定性与状态码

5.5 预期效果

• 标准测距：初始化成功，距离数据正常输出
• 模式切换：short/long 模式均能正常读取距离
• 休眠唤醒：sleep 后停止测距，wakeup 后测距恢复正常
• 持续测距：每秒一帧数据，状态码 0（测距成功）
• 日志如下：

[2026-07-21 20:17:13.093][000000000.246] I/user.main VL53L1X_Demo 001.999.000
[2026-07-21 20:17:13.099][000000000.263] I/user.vl53l1x_demo HELLO
[2026-07-21 20:17:13.228][000000001.264] I/user.vl53l1x_demo ===== [1/5] 标准测距 =====
[2026-07-21 20:17:13.232][000000001.275] I/user.exs_vl53l1x 固件就绪 0x00E5=0x03
[2026-07-21 20:17:13.238][000000001.385] I/user.exs_vl53l1x 预设模式配置写入完成 (mode=standard)
[2026-07-21 20:17:13.243][000000001.388] I/user.exs_vl53l1x 芯片 MID=0xEA MT=0xCC
[2026-07-21 20:17:13.377][000000001.591] I/user.exs_vl53l1x 初始化完成，Standard Ranging 测距已启动
[2026-07-21 20:17:13.382][000000001.591] I/user.vl53l1x_demo VL53L1X 初始化成功，版本: 202607201200
[2026-07-21 20:17:13.400][000000001.845] I/user.vl53l1x_demo 第1次: 距离=201mm 状态=测距成功 stream=1
[2026-07-21 20:17:13.820][000000002.354] I/user.vl53l1x_demo 第2次: 距离=200mm 状态=测距成功 stream=2
[2026-07-21 20:17:14.325][000000002.863] I/user.vl53l1x_demo 第3次: 距离=200mm 状态=测距成功 stream=3
[2026-07-21 20:17:14.827][000000003.372] I/user.vl53l1x_demo 第4次: 距离=196mm 状态=测距成功 stream=4
[2026-07-21 20:17:15.339][000000003.881] I/user.vl53l1x_demo 第5次: 距离=197mm 状态=测距成功 stream=5
[2026-07-21 20:17:15.837][000000004.385] I/user.exs_vl53l1x 传感器已关闭
[2026-07-21 20:17:15.845][000000004.385] I/user.vl53l1x_demo ---- [1/5] 完成 ----
[2026-07-21 20:17:16.343][000000004.886] I/user.vl53l1x_demo ===== [2/5] 测距模式切换 =====
[2026-07-21 20:17:16.348][000000004.886] I/user.vl53l1x_demo 切换 short 模式（抗强光）
[2026-07-21 20:17:16.358][000000004.898] I/user.exs_vl53l1x 固件就绪 0x00E5=0x03
[2026-07-21 20:17:16.466][000000005.008] I/user.exs_vl53l1x 预设模式配置写入完成 (mode=short)
[2026-07-21 20:17:16.471][000000005.011] I/user.exs_vl53l1x 芯片 MID=0xEA MT=0xCC
[2026-07-21 20:17:16.668][000000005.215] I/user.exs_vl53l1x 初始化完成，Standard Ranging 测距已启动
[2026-07-21 20:17:16.916][000000005.461] I/user.vl53l1x_demo short 模式: 距离=24mm 状态=串扰信号
[2026-07-21 20:17:16.923][000000005.465] I/user.exs_vl53l1x 传感器已关闭
[2026-07-21 20:17:16.928][000000005.465] I/user.vl53l1x_demo 切换 long 模式（远距离）
[2026-07-21 20:17:16.934][000000005.477] I/user.exs_vl53l1x 固件就绪 0x00E5=0x03
[2026-07-21 20:17:17.040][000000005.587] I/user.exs_vl53l1x 预设模式配置写入完成 (mode=long)
[2026-07-21 20:17:17.056][000000005.590] I/user.exs_vl53l1x 芯片 MID=0xEA MT=0xCC
[2026-07-21 20:17:17.258][000000005.794] I/user.exs_vl53l1x 初始化完成，Standard Ranging 测距已启动
[2026-07-21 20:17:17.524][000000006.058] I/user.vl53l1x_demo long 模式: 距离=199mm 状态=测距成功
[2026-07-21 20:17:17.530][000000006.062] I/user.exs_vl53l1x 传感器已关闭
[2026-07-21 20:17:17.534][000000006.062] I/user.vl53l1x_demo ---- [2/5] 完成 ----
[2026-07-21 20:17:18.021][000000006.563] I/user.vl53l1x_demo ===== [4/5] 休眠与唤醒演示 =====
[2026-07-21 20:17:18.036][000000006.574] I/user.exs_vl53l1x 固件就绪 0x00E5=0x03
[2026-07-21 20:17:18.144][000000006.684] I/user.exs_vl53l1x 预设模式配置写入完成 (mode=standard)
[2026-07-21 20:17:18.151][000000006.688] I/user.exs_vl53l1x 芯片 MID=0xEA MT=0xCC
[2026-07-21 20:17:18.345][000000006.891] I/user.exs_vl53l1x 初始化完成，Standard Ranging 测距已启动
[2026-07-21 20:17:18.609][000000007.144] I/user.vl53l1x_demo 休眠前: 距离=201mm 状态=测距成功
[2026-07-21 20:17:18.614][000000007.144] I/user.vl53l1x_demo 进入软件待机模式
[2026-07-21 20:17:18.620][000000007.149] I/user.exs_vl53l1x 已进入软件待机
[2026-07-21 20:17:21.610][000000010.149] I/user.vl53l1x_demo 从软件待机模式唤醒
[2026-07-21 20:17:21.626][000000010.162] I/user.exs_vl53l1x 已从软件待机唤醒，测距已恢复
[2026-07-21 20:17:21.875][000000010.415] I/user.vl53l1x_demo 唤醒后: 距离=199mm 状态=测距成功
[2026-07-21 20:17:21.882][000000010.419] I/user.exs_vl53l1x 传感器已关闭
[2026-07-21 20:17:21.887][000000010.419] I/user.vl53l1x_demo ---- [4/5] 完成 ----
[2026-07-21 20:17:22.385][000000010.920] I/user.vl53l1x_demo ===== [5/5] 持续测距演示 =====
[2026-07-21 20:17:22.391][000000010.931] I/user.exs_vl53l1x 固件就绪 0x00E5=0x03
[2026-07-21 20:17:22.508][000000011.041] I/user.exs_vl53l1x 预设模式配置写入完成 (mode=standard)
[2026-07-21 20:17:22.514][000000011.044] I/user.exs_vl53l1x 芯片 MID=0xEA MT=0xCC
[2026-07-21 20:17:22.711][000000011.248] I/user.exs_vl53l1x 初始化完成，Standard Ranging 测距已启动
[2026-07-21 20:17:22.721][000000011.248] I/user.vl53l1x_demo 每隔 1 秒读取一次距离数据，共 5 次
[2026-07-21 20:17:23.764][000000012.302] I/user.vl53l1x_demo 持续测距[1]: 距离=201mm 状态=测距成功
[2026-07-21 20:17:24.771][000000013.311] I/user.vl53l1x_demo 持续测距[2]: 距离=199mm 状态=测距成功
[2026-07-21 20:17:25.779][000000014.320] I/user.vl53l1x_demo 持续测距[3]: 距离=197mm 状态=测距成功
[2026-07-21 20:17:26.788][000000015.329] I/user.vl53l1x_demo 持续测距[4]: 距离=198mm 状态=测距成功
[2026-07-21 20:17:27.803][000000016.338] I/user.vl53l1x_demo 持续测距[5]: 距离=197mm 状态=测距成功
[2026-07-21 20:17:27.808][000000016.342] I/user.exs_vl53l1x 传感器已关闭
[2026-07-21 20:17:27.813][000000016.342] I/user.vl53l1x_demo ---- [5/5] 完成 ----
[2026-07-21 20:17:28.299][000000016.843] I/user.vl53l1x_demo ===== [演示完毕] =====

5.6 故障排除

1. 传感器初始化失败：

   • 检查 VL53L1X 接线是否正确（SCL、SDA、VCC、GND）
   • 确认 GPIO 引脚配置与接线一致
   • 检查电源电压是否稳定（3.3V）
   • 确认 exs_vl53l1x 扩展库已正常加载

2. 读取数据始终为 0 或异常：

   • 检查传感器供电是否正常
   • 确认 I2C 地址是否正确（默认 0x29）
   • 确认接线无松动

3. 测距状态码异常：

   • 状态码 1（Sigma 失效）：测量波动太大，目标反射率过低
   • 状态码 2（信号失效）：信号太弱，目标距离过远或反射率低
   • 状态码 9（串扰信号）：有保护玻璃串扰，可运行串扰校准
   • 状态码 14（范围无效）：通常对应第一帧无效数据，会自动跳过

5.7 扩展功能建议

exs_vl53l1x 更多接口的使用可以查看 exs_vl53l1x 扩展库说明