跳转至

exs_bmx280 扩展库

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

一、概述

exs_bmx280 是 Bosch Sensortec BMP280/BME280 数字气压传感器的 LuatOS 扩展库。 BMP280/BME280 是一款高精度、低功耗的数字气压传感器，广泛应用于海拔测量、室内外导航、天气预报、无人机定高、运动监测等领域。 BME280 在 BMP280 基础上额外支持湿度测量。

1.1 主要特性

  • 压力范围 300~1100hPa（对应海拔 +9000m ~ -500m）

  • 温度测量精度 ±0.5°C（典型值）

  • 气压测量精度 ±0.12hPa（典型值，高精度模式）

  • 湿度测量范围 0~100%RH，精度 ±3%RH（仅 BME280）

  • I2C 接口通信，7 位地址可选 0x76（SDO=GND）或 0x77（SDO=VCC）

  • 内置 E2PROM 存储 12 个校准参数（BME280 额外 6 个湿度校准参数），每颗芯片独立校准

  • 支持 IIR 滤波器（系数 0~4），有效降低噪声

  • 20 位 ADC 分辨率

  • 工作电压 1.71~3.6V

  • 待机电流 0.1μA（典型值）

  • 支持软件 I2C 和硬件 I2C 两种模式

  • 内置 I2C 总线卡死自动检测与恢复

1.2 注意事项

  • 推荐使用软件 I2C 模式：在异常 I2C 通信后可能锁死 SDA 总线，软件 I2C 模式可以通过 GPIO 直接脉冲 SCL 恢复总线。

  • 初始化总线恢复：每次调用 setup() 时，如果传入了 scl/sda 引脚号，驱动会先进行总线恢复。

  • 运行时自动恢复：当 i2c.send() 或 i2c.recv() 返回失败时，驱动自动执行总线恢复并重试。

  • I2C 模式下 SCL 和 SDA 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC

  • BMP280/BME280 的 I2C 地址：SDO=GND 时 0x76，SDO=VCC 时 0x77

  • CHIP_ID 为 0x58(BMP280) 或 0x60(BME280)，自动识别，可用于验证芯片是否正常通信

  • 湿度测量仅 BME280 支持，BMP280 调用 get_humidity() 会提示并返回 nil

1.3 IIR 滤波器说明

BMP280/BME280 内置 IIR（无限脉冲响应）低通滤波器，通过对连续多次采样进行加权平均，有效降低数据噪声。

通过 setup() 的 config.filter 或 set_filter() 参数配置：

filter 值 采样平均次数 适用场景
0 关闭 快速响应，适合变化频繁的环境
1 2 次 轻度滤波
2 4 次 中等滤波
3 8 次 较强滤波
4 16 次 最强滤波，适合静态测量

1.4 海拔计算说明

计算公式：altitude = 44330 * (1 - (p/p0)^(1/5.255))

其中 p 为当前气压，p0 为海平面标准气压，通过 set_sea_level_pressure() 设置。 get_altitude() 传入当前气压 p 即可自动使用已设置的 p0 计算海拔。

  • 内置初始海平面标准气压 1013.25 hPa，可通过 set_sea_level_pressure() 设置校正值

  • 不同天气条件下海平面气压会变化，建议通过联网或本地气象站获取实时海平面气压校正

1.5 硬件连接

BMP280/BME280 通过 I2C 接口与主控连接，SCL/SDA 需外接 4.7kΩ~10kΩ 上拉电阻。

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │  BMP280/BME280   │
  │  (AirXXX)    │                    │  数字气压传感器   │
  │              │                    │                  │
  │ GPIO_SCL ────┼────────────────────┼──→ SCL           │
  │              │                    │                  │
  │ GPIO_SDA ←───┼────────────────────┼──→ SDA           │
  │              │                    │ （需外接上拉电阻）│
  │              │                    │                  │
  │ VCC 3.3V ────┼────────────────────┼──→ VCC           │
  │              │                    │                  │
  │ GND      ────┼────────────────────┼──→ GND           │
  └──────────────┘                    └──────────────────┘

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

  • Air8101：SCL=GPIO4, SDA=GPIO5

1.6 加载方式

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

二、核心示例

2.1 按使用接口划分

2.1.1 软件 I2C 模式（推荐）

主动轮询读取：

local exs_bmx280 = require "exs_bmx280"
local result = exs_bmx280.setup("I2C", {scl = 27, sda = 26})
if not result then return end

while true do
    local data = exs_bmx280.get_data()
    if data then
        log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.2fhPa", data.temperature, data.pressure))
    end
    sys.wait(5000)  -- 等待 5 秒后再次读取
end

2.1.2 硬件 I2C 模式

local exs_bmx280 = require "exs_bmx280"
local result = exs_bmx280.setup("I2C", {i2c_id = 0, scl = 27, sda = 26})
if not result then return end

while true do
    local data = exs_bmx280.get_data()
    if data then
        log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.2fhPa", data.temperature, data.pressure))
    end
    sys.wait(5000)  -- 等待 5 秒后再次读取
end

2.1.3 BME280 湿度读取（仅 BME280）

local exs_bmx280 = require "exs_bmx280"
local result = exs_bmx280.setup("I2C", {scl = 27, sda = 26})
if not result then return end

while true do
    local data = exs_bmx280.get_data()
    if data then
        log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.2fhPa 湿度=%.1f%%RH",
            data.temperature, data.pressure, data.humidity or -1))
    end
    sys.wait(5000)  -- 等待 5 秒后再次读取
end

2.2 按使用场景划分

2.2.1 气压与温度轮询读取（省电）

local result = exs_bmx280.setup("I2C", {
    scl = 4, sda = 5,
})
if not result then return end

local data = exs_bmx280.get_data()
if data then
    log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.1fhPa", data.temperature, data.pressure))
end

2.2.2 高精度气压测量（开启 IIR 滤波）

local result = exs_bmx280.setup("I2C", {
    scl = 4, sda = 5,
    filter = 4,         -- 16 次采样平均，噪声最低
})
if not result then return end

while true do
    local data = exs_bmx280.get_data()
    if data then
        log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.2fhPa", data.temperature, data.pressure))
    end
    sys.wait(10000)  -- 等待 10 秒后再次读取
end

2.2.3 海拔高度测量

local result = exs_bmx280.setup("I2C", {scl = 4, sda = 5})
if not result then return end

local data = exs_bmx280.get_data()
if data then
    local alt = exs_bmx280.get_altitude(data.pressure)
    log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.1fhPa 海拔=%.1f米", data.temperature, data.pressure, alt))
end

2.2.4 IIR 滤波切换示例

-- 关闭滤波（快速响应）
exs_bmx280.set_filter(0)

-- 最强滤波（最平滑）
exs_bmx280.set_filter(4)

2.2.5 BME280 单独读湿度（仅 BME280）

local exs_bmx280 = require "exs_bmx280"
local result = exs_bmx280.setup("I2C", {scl = 4, sda = 5})
if not result then return end

local hum = exs_bmx280.get_humidity()
if hum then
    log.info("exs_bmx280", string.format("湿度=%.1f%%RH", hum))
else
    log.warn("exs_bmx280", "BMP280 不支持湿度测量")
end

三、常量解释

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

四、函数详解

4.1 初始化

4.1.1 exs_bmx280.setup(model, config)

功能

初始化 BMP280/BME280 气压传感器，配置通信接口和采样参数。 如果是 BME280，还会额外配置湿度采样并读取湿度校准参数。

参数

model

参数含义：通信模式选择
数据类型：string
取值范围："I2C"（当前仅支持 I2C，SPI 预留）
是否必选：是
注意事项："I2C" 模式使用 I2C 总线（可选用软件 I2C 或硬件 I2C）
参数示例："I2C"

config

参数含义：初始化配置表
数据类型：table
取值范围：包含以下子参数：
{
    参数含义：SCL 时钟引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：与 sda 一起可选
    注意事项：与 sda 一起传入时无 i2c_id 则创建软件 I2C（推荐），有 i2c_id 则走硬件 I2C 并附带总线恢复
    参数示例：27
    config.scl ,

    参数含义：SDA 数据引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：与 scl 一起可选
    注意事项：该引脚需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
    参数示例：26
    config.sda ,

    参数含义：硬件 I2C 总线 ID
    数据类型：number
    取值范围：有效的 I2C 总线编号
    是否必选：可选
    注意事项：默认 0。与 scl/sda 一起传时使用硬件 I2C 通信 + 引脚恢复总线
    参数示例：1
    config.i2c_id ,

    参数含义：IIR 滤波器系数
    数据类型：number
    取值范围：0~4（默认 0=关闭，4=16 次平均最强滤波）
    是否必选：否
    注意事项：滤波系数越大数据越平滑，但对变化响应越慢
    参数示例：4
    config.filter ,
}
是否必选：否，可不传任何参数使用默认值（硬件 I2C）
参数示例：
         -- 方式一：软件 I2C 模式（推荐）
         exs_bmx280.setup("I2C", {scl = 30, sda = 29})

         -- 方式二：硬件 I2C + 总线恢复
         exs_bmx280.setup("I2C", {i2c_id = 1, scl = 18, sda = 19})

         -- 方式三：开启 IIR 滤波
         exs_bmx280.setup("I2C", {scl = 30, sda = 29, filter = 4})

返回值

local ok = exs_bmx280.setup(model, config)

ok

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

示例

-- 软件 I2C 模式
local result = exs_bmx280.setup("I2C", {scl = 30, sda = 29})
if not result then return end

4.2 数据读取

4.2.1 exs_bmx280.get_data()

功能

读取 BMP280/BME280 气压和温度数据，自动进行校准补偿。数据寄存器为 20 位，每次读取温度 ADC 和气压 ADC（共 6 字节）。 如果是 BME280，会额外读取湿度 ADC（2 字节）并返回湿度值。

参数

无

返回值

local data = exs_bmx280.get_data()

data

含义说明：气压、温度和湿度数据表
数据类型：table 或 nil
取值范围：
    data.temperature - 温度，单位 °C，精确到 0.01°C，如 25.12
    data.pressure    - 气压，取值范围 300.00~1100.00（单位 hPa，精度小数点后2位），如 1013.25
    data.humidity    - 相对湿度，取值范围 0.00~100.00（单位 %RH，精度小数点后2位，仅 BME280 有），如 46.33
注意事项：失败返回 nil，失败时请检查 I2C 通信；BMP280 无 data.humidity 字段
返回示例：{temperature = 25.12, pressure = 1013.25, humidity = 46.33}

示例

local data = exs_bmx280.get_data()
if data then
    log.info("exs_bmx280", string.format("温度=%.2f°C 气压=%.2fhPa 湿度=%.1f%%RH",
        data.temperature, data.pressure, data.humidity or -1))
else
    log.error("exs_bmx280", "读取数据失败")
end

4.3 参数配置

4.3.1 exs_bmx280.set_filter(coeff)

功能

设置 IIR 滤波器系数。系数越大，数据越平滑，但对环境变化的响应越慢。

参数

coeff

参数含义：滤波器系数
数据类型：number
取值范围：0~4
是否必选：是
注意事项：仅在 setup() 之后调用有效。IIR 滤波器系数选择参考：
            - 0=关闭，适合快速响应场景
            - 1=2 次平均，轻度滤波
            - 2=4 次平均，中等滤波
            - 3=8 次平均，较强滤波
            - 4=16 次平均，最强滤波，适合静态精密测量
参数示例：4

返回值

无

示例

-- 设置为最强滤波
exs_bmx280.set_filter(4)

-- 关闭滤波
exs_bmx280.set_filter(0)

4.4 海拔计算

4.4.1 exs_bmx280.set_sea_level_pressure(pressure)

功能

设置海平面标准气压，用于校准海拔计算精度。不同天气条件下海平面气压会变化，可通过本地气象站数据或联网获取校正值。

参数

pressure

参数含义：海平面标准气压
数据类型：number
取值范围：950.00~1050.00（单位 hPa，精度小数点后2位）
是否必选：是
注意事项：内置初始值 1013.25。可通过联网查询本地气象站数据获取更精确的值
参数示例：1018.00

返回值

无

示例

exs_bmx280.set_sea_level_pressure(1018.00)

4.4.2 exs_bmx280.get_altitude(pressure)

功能

通过当前气压值计算海拔高度，使用国际气压公式。 海平面标准气压通过 set_sea_level_pressure() 设置。

参数

pressure

参数含义：当前气压值
数据类型：number
取值范围：300.00~1100.00（单位 hPa，精度小数点后2位）
是否必选：是
注意事项：传入 get_data() 返回的 data.pressure
参数示例：1013.25

返回值

local altitude = exs_bmx280.get_altitude(pressure)

altitude

含义说明：海拔高度
数据类型：number（浮点数，小数点后一位）
取值范围：-500.0~9000.0（单位米）
返回示例：50.0

示例

local data = exs_bmx280.get_data()
if data then
    local alt = exs_bmx280.get_altitude(data.pressure)
    log.info("exs_bmx280", string.format("海拔=%.1f 米", alt))
end

4.5 湿度读取（仅 BME280）

4.5.1 exs_bmx280.get_humidity()

功能

单独读取 BME280 湿度值。仅 BME280 支持此功能，BMP280 调用会提示"不支持湿度测量"并返回 nil。

内部使用数据手册 8.1 节 double 精度公式计算，结果限制在 0~100%RH 范围内。

参数

无

返回值

local humidity = exs_bmx280.get_humidity()

humidity

含义说明：相对湿度值
数据类型：number 或 nil
取值范围：0.00~100.00（单位 %RH，精度小数点后2位），如 46.33 表示 46.33%RH
注意事项：仅 BME280 返回有效值；BMP280 返回 nil 并提示不支持
返回示例：46.33

示例

local hum = exs_bmx280.get_humidity()
if hum then
    log.info("exs_bmx280", string.format("湿度=%.1f%%RH", hum))
else
    log.warn("exs_bmx280", "BMP280 不支持湿度测量")
end

4.6 传感器控制

4.6.1 exs_bmx280.close()

功能

关闭 BMP280/BME280 传感器，将传感器切换到待机模式，重置内部状态。 close 后需要重新调用 setup() 才能再次使用。 close 后调用 get_data() 会返回 nil 并提示"请先 setup()"。

参数

无

返回值

无

示例

exs_bmx280.close()

4.6 版本信息

4.6.1 exs_bmx280.version()

功能

获取 exs_bmx280 库的版本号。

参数

无

返回值

local ver = exs_bmx280.version()

ver

含义说明：版本号字符串
数据类型：string
取值范围：格式 "yyyymmddhhmm"，表示 yyyy年mm月dd日hh时mm分发布的版本
注意事项：无
返回示例："202607240000"

示例

local ver = exs_bmx280.version()
log.info("exs_bmx280", "版本号:", ver)

五、版本更新说明

版本号：202607240000（初版）

  1. 更新时间：2026-07-24

  2. 更新内容：

    • 支持软件 I2C 和硬件 I2C 两种模式

    • 支持 BMP280/BME280 自动识别

    • 支持 IIR 滤波器（系数 0~4）

    • 支持 BME280 湿度读取（get_data() 返回 humidity，单独 get_humidity()）

    • 支持海拔高度计算（国际气压公式）

    • 内置 I2C 总线卡死自动检测与恢复

六、产品支持说明

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

搜索