跳转至

exs_vl6180x 扩展库

作者：江访　|　最后修改：2026-08-20

一、概述

1.1 主要特性

  • 基于 ST(意法半导体) VL6180X 飞行时间(ToF)测距传感器的 LuatOS 扩展库

  • 使用 I2C 总线通信，默认 I2C 地址 0x29

  • 测距范围：0~255mm，单次触发模式

  • 芯片自动校准机制：每 255 次测距后自动执行系统校准

  • 内置 I2C 总线卡死检测与自动恢复（软件 I2C 或硬件 I2C + scl/sda 引脚配置时有效）

1.2 注意事项

  • 本扩展库的测距读取使用轮询等待方式，必须在 sys.taskInit 创建的协程中调用，否则会导致系统挂死

  • VL6180X 测距使用 VCSEL 红外激光发射器，对人眼安全，但仍建议避免长时间直视发射窗口

  • 测距最大范围 255mm（约 25cm），适合近距离障碍物检测，远距离场景请使用 VL53L0X/VL53L1X 等传感器

1.3 硬件连接

VL6180X 模块         主控核心板
  VCC    -----------  VDD_EXT (3.3V)
  GND    -----------  GND
  SCL    -----------  GPIO_SCL
  SDA    -----------  GPIO_SDA

各平台示例接线（以软件 I2C 模式为例）：

  • Air780EPM：SCL=GPIO31, SDA=GPIO30
  • Air780EHM：SCL=GPIO31, SDA=GPIO30
  • Air8000：SCL=GPIO1, SDA=GPIO2

  • Air8101：SCL=GPIO4, SDA=GPIO5

  • VDD_EXT 输出电压为 3.3V，适用于 VL6180X 模块的供电要求

  • VL6180X 模块上的 SCL/SDA 通常已集成上拉电阻，无需额外配置

  • 如果使用其他模组型号，请根据 GPIO 引脚表调整 SCL/SDA 引脚编号

1.4 加载方式

-- 扩展库需要 require 加载后才能调用
local exs_vl6180x = require "exs_vl6180x"

二、核心示例

2.1 测距演示

以下示例演示 VL6180X 的初始化、测距数据读取和关闭流程。

local exs_vl6180x = require "exs_vl6180x"

-- 软件 I2C 模式：SCL=GPIO31, SDA=GPIO30（Air780EPM 接线）
local function init_func()
    local result = exs_vl6180x.setup({scl = 31, sda = 30})
    if not result then
        log.error("demo", "VL6180X 初始化失败")
        return false
    end
    log.info("demo", "VL6180X 初始化成功，版本:", exs_vl6180x.version())
    return true
end

-- 读取测距数据
local function read_range_func()
    local data = exs_vl6180x.get_range()
    if data then
        log.info("demo", string.format("距离=%dmm 状态=%s", data.range_mm, data.status_str))
    else
        log.error("demo", "读取测距数据失败")
    end
end

-- 测距任务
local function demo_task_func()
    sys.wait(100)       -- 等待系统稳定，100ms
    if not init_func() then return end
    for i = 1, 5 do
        read_range_func()
        sys.wait(1000)  -- 每隔 1 秒读取一次测距数据
    end
    exs_vl6180x.close()
end
sys.taskInit(demo_task_func)

三、常量解释

扩展库常量，顾名思义是由 exs_vl6180x 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为扩展库可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 exs_vl6180x.ERROR_NONE

常量含义：测距成功
数据类型：number
注意事项：取值为 0，表示测距数据有效

3.2 exs_vl6180x.ERROR_NOCONVERGE

常量含义：未检测到目标
数据类型：number
注意事项：取值 7，传感器正常但未检测到反射信号，目标超出量程或反射率过低

3.3 exs_vl6180x.ERROR_SNR

常量含义：环境光过强（信噪比过低）
数据类型：number
注意事项：取值 11，环境光太强导致测距不可靠，可尝试遮挡环境光或调整安装位置

四、函数详解

4.1 初始化

4.1.1 exs_vl6180x.setup(config)

功能

初始化 VL6180X 传感器。完成 I2C 初始化、芯片型号校验（Model ID 0xB4）、寄存器配置加载和冷启动清除。

参数

config

参数含义：配置参数表
数据类型：table
取值范围：
{
    参数含义：I2C 总线 id（可选）
    数据类型：number
    取值范围：0 ~ 1，具体取决于硬件支持
    是否必选：否
    注意事项：仅传 i2c_id 时不具总线自动恢复能力；与 scl+sda 同时传入时激活硬件 I2C + 总线恢复
    参数示例：0
    config.i2c_id ,

    参数含义：软件 I2C SCL 引脚
    数据类型：number
    取值范围：根据芯片 GPIO 引脚定义
    是否必选：否
    注意事项：与 sda 需同时传入；不传 i2c_id 时自动使用软件 I2C
    参数示例：31
    config.scl ,

    参数含义：软件 I2C SDA 引脚
    数据类型：number
    取值范围：根据芯片 GPIO 引脚定义
    是否必选：否
    注意事项：与 scl 需同时传入
    参数示例：30
    config.sda ,
}
是否必选：是
参数示例：
    -- 硬件 I2C 模式
    exs_vl6180x.setup({i2c_id = 0})

    -- 软件 I2C 模式
    exs_vl6180x.setup({scl = 31, sda = 30})

返回值

含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功），false（失败）
注意事项：失败时请检查接线和 I2C 通信
返回示例：true

示例

-- 软件 I2C 初始化 VL6180X
local result = exs_vl6180x.setup({scl = 31, sda = 30})
if not result then
    log.error("demo", "初始化失败")
    return
end
log.info("demo", "初始化成功，版本:", exs_vl6180x.version())

4.2 数据读取

4.2.1 exs_vl6180x.get_range()

功能

读取一帧测距数据。内部执行：等待设备就绪 → 触发测距 → 等待测距完成 → 读取距离值 → 清除中断。

⚠️ 协程限制：必须在 sys.taskInit 创建的协程中调用

原因：内部使用轮询等待，每次检测间隔 1ms

最长等待：约 500ms（测距完成等待）

参数

无

返回值

含义说明：测距数据表，失败返回 nil
数据类型：table 或 nil
取值范围：
    data.range_mm   - 距离值，单位 mm，范围 0~255
    data.status     - 测距状态码，0=成功，非 0 表示异常
    data.status_str - 状态码中文描述
注意事项：status 非 0 时，range_mm 值可能不可靠，建议重新测量
返回示例：{range_mm = 120, status = 0, status_str = "测距成功"}

示例

local function read_range_func()
    local data = exs_vl6180x.get_range()
    if data then
        log.info("demo", string.format("距离=%dmm 状态=%s", data.range_mm, data.status_str))
    end
end

4.3 状态查询

4.3.1 exs_vl6180x.get_range_status()

功能

查询最近一次测距的状态码（从 RESULT_RANGE_STATUS 寄存器读取 bit[7:4] 的 error_code 值）。

参数

无

返回值

含义说明：测距状态码，0 表示成功
数据类型：number
取值范围：
    0  - 测距成功
    1  - 系统错误(1)
    5  - 系统错误(5)
    6  - 早期收敛估计失败
    7  - 未检测到目标
    8  - 忽略阈值检查失败
    11 - 环境光过强
    12 - 原始测距下溢
    13 - 原始测距上溢
    14 - 测距值下溢
    15 - 测距值上溢
返回示例：0

示例

local status = exs_vl6180x.get_range_status()
log.info("demo", string.format("测距状态码=%d", status))

4.4 电源管理

4.4.1 exs_vl6180x.sleep()

功能

停止后续测量，使芯片进入低功耗待机状态。VL6180X 没有专用睡眠寄存器，通过停止触发新测量实现低功耗。

参数

无

返回值

无

示例

exs_vl6180x.sleep()
log.info("demo", "传感器已进入待机")

4.4.2 exs_vl6180x.wakeup()

功能

从待机状态唤醒（恢复测量能力）。

参数

无

返回值

含义说明：唤醒是否成功
数据类型：boolean
取值范围：true（成功），false（未初始化）
返回示例：true

示例

exs_vl6180x.wakeup()
log.info("demo", "传感器已唤醒")

4.5 资源释放

4.5.1 exs_vl6180x.close()

功能

关闭传感器，释放 I2C 总线资源，重置内部状态。

参数

无

返回值

无

示例

exs_vl6180x.close()
log.info("demo", "传感器已关闭")

4.6 版本信息

4.6.1 exs_vl6180x.version()

功能

获取扩展库版本号。

参数

无

返回值

含义说明：扩展库版本号
数据类型：string
取值范围：固定格式 "yyyymmddhhmm"
返回示例："202608200000"

示例

local ver = exs_vl6180x.version()
log.info("demo", "扩展库版本:", ver)

五、版本更新说明

版本号：202608200000

  1. 更新时间：2026-08-20

  2. 更新内容：

    • 移除 ALS 环境光读取功能（get_lux 及相关增益常量）

    • 仅保留测距功能（0~255mm，单次触发模式）及测距状态查询、睡眠/唤醒/关闭

    • 支持软件 I2C 和硬件 I2C 初始化

    • 支持 I2C 总线卡死自动检测与恢复

六、产品支持说明

所有支持 LuatOS 二次开发的模块，具体可以查看选型手册。

搜索