跳转至

exs_bmp180 扩展库

作者：江访　|　最后修改：2026-07-23

一、概述

exs_bmp180 是 Bosch Sensortec BMP180 数字气压传感器的 LuatOS 扩展库。BMP180 是一款高精度、低功耗的数字气压传感器，广泛应用于海拔测量、室内外导航、天气预报、垂直速度检测等领域。

1.1 主要特性

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

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

  • 气压测量噪声低至 0.02hPa（超高分辨率模式）

  • I2C 接口通信，固定 7 位地址 0x77

  • 内置 E2PROM 存储 11 个校准参数，每颗芯片独立校准

  • 支持 4 种过采样率（OSS 0~3），精度/速度可调

  • 16~19 位 ADC 分辨率（取决于过采样率）

  • 工作电压 1.8~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

  • BMP180 的 I2C 地址固定为 0x77（7 位），不可更改

1.3 过采样率说明

通过 setup() 的 config.oss 或 set_oss() 参数配置，默认 0。

OSS 模式 转换时间 噪声（hPa） 分辨率
0 Ultra Low Power 4.5ms 0.06 16 位
1 Standard 7.5ms 0.04 17 位
2 High Resolution 13.5ms 0.03 18 位
3 Ultra High Resolution 25.5ms 0.02 19 位

  • OSS 越高，精度越高，但转换时间越长，功耗也越高

  • 便携式应用推荐 OSS=0（超低功耗）

  • 需要高精度气压/海拔时推荐 OSS=3（超高分辨率）

1.4 海拔计算说明

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

其中 p 为当前气压，p0 为海平面标准气压。set_sea_level_pressure() 接口用于设置 p0 值，get_altitude() 接口用于根据 p 和 p0 计算最终海拔。

  • 默认海平面标准气压 101325 Pa（1013.25 hPa），可通过 set_sea_level_pressure() 设置校正值

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

1.5 硬件连接

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

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

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

  • Air8101：SCL=GPIO4, SDA=GPIO5

1.6 加载方式

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

二、核心示例

2.1 按使用接口划分

2.1.1 软件 I2C 模式（推荐）

主动轮询读取：

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

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

2.1.2 硬件 I2C 模式

主动轮询读取：

local exs_bmp180 = require "exs_bmp180"
local result = exs_bmp180.setup({i2c_id = 0, scl = 27, sda = 26})
-- 或仅使用硬件 I2C（无总线恢复）
-- local result = exs_bmp180.setup({i2c_id = 0})
if not result then return end

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

2.2 按使用场景划分

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

适用场景：每隔几秒读一次气压和温度，不关心实时变化。

local result = exs_bmp180.setup({
    scl = 4, sda = 5,
    oss = 0,            -- 超低功耗模式，转换仅 4.5ms
})
if not result then return end

sys.wait(200)  -- 等待传感器稳定，200ms 为数据手册推荐值
local data = exs_bmp180.get_data()
if data then
    log.info("exs_bmp180", string.format("温度=%.1f°C 气压=%.1fPa", data.temperature, data.pressure))
end

2.2.2 高精度气压测量（气象站）

适用场景：气象观测、室内外气压监测，需要高精度数据。

local result = exs_bmp180.setup({
    scl = 4, sda = 5,
    oss = 3,            -- 超高分辨率模式，噪声低至 0.02hPa
})
if not result then return end

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

2.2.3 海拔高度测量

适用场景：登山、无人机、楼层检测。

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

sys.wait(200)  -- 等待传感器稳定，200ms 为数据手册推荐值
local data = exs_bmp180.get_data()
if data then
    -- 计算海拔（默认海平面气压 101325Pa）
    local alt = exs_bmp180.get_altitude(data.pressure)
    log.info("exs_bmp180", string.format("温度=%.1f°C 气压=%.1fPa 海拔=%.1f米", data.temperature, data.pressure, alt))
end

2.2.4 过采样率切换示例

适用场景：在低功耗和高精度模式之间动态切换。

-- 超高精度模式测量
exs_bmp180.set_oss(3)
sys.wait(50)  -- 等待 50ms（按键消抖）
local data = exs_bmp180.get_data()
if data then
    log.info("exs_bmp180", string.format("高精度: 温度=%.1f°C 气压=%.1fPa", data.temperature, data.pressure))
end

-- 切回超低功耗模式
exs_bmp180.set_oss(0)
sys.wait(50)  -- 等待 50ms（按键消抖）
data = exs_bmp180.get_data()
if data then
    log.info("exs_bmp180", string.format("低功耗: 温度=%.1f°C 气压=%.1fPa", data.temperature, data.pressure))
end

三、常量解释

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

四、函数详解

4.1 初始化

4.1.1 exs_bmp180.setup(config)

功能

初始化 BMP180 气压传感器，配置 I2C 通信引脚，读取芯片 E2PROM 校准数据。

参数

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 通信 + 引脚恢复总线；不传 scl/sda 时使用硬件 I2C 但无总线恢复能力
    参数示例：1
    config.i2c_id ,

    参数含义：过采样率
    数据类型：number
    取值范围：0~3
    是否必选：否
    注意事项：默认 0。0=ultra low power（4.5ms），1=standard（7.5ms），2=high resolution（13.5ms），3=ultra high resolution（25.5ms）
    参数示例：3
    config.oss ,
}
是否必选：否，可不传任何参数使用默认值（硬件 I2C）
参数示例：
         -- 方式一：软件 I2C 模式（推荐）
         exs_bmp180.setup({scl = 30, sda = 29})

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

         -- 方式三：超高分辨率模式
         exs_bmp180.setup({scl = 30, sda = 29, oss = 3})

返回值

local ok = exs_bmp180.setup(config)

ok

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

示例

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

4.2 数据读取

4.2.1 exs_bmp180.get_data()

功能

读取 BMP180 气压和温度数据，自动进行校准补偿。每次调用依次完成温度测量和气压测量，耗时约 5~30ms（取决于 OSS 设置）。

参数

无

返回值

local data = exs_bmp180.get_data()

data

含义说明：气压和温度数据表
数据类型：table 或 nil
取值范围：
        data.temperature - 温度，单位 °C，可精确到 0.1°C，如 25.1
        data.pressure    - 气压，单位 Pa（帕斯卡），如 101325
注意事项：失败返回 nil，失败时请检查 I2C 通信
返回示例：{temperature = 25.1, pressure = 101325}

示例

local data = exs_bmp180.get_data()
if data then
    -- 温度单位 °C，气压单位 Pa
    log.info("exs_bmp180", string.format("温度=%.1f°C 气压=%.2fhPa", data.temperature, data.pressure / 100))
else
    log.error("exs_bmp180", "读取数据失败")
end

4.3 参数配置

4.3.1 exs_bmp180.set_oss(oss)

功能

切换过采样率（Over Sampling Setting）。过采样率越高，精度越高但转换时间越长。

参数

oss

参数含义：目标过采样率
数据类型：number
取值范围：0~3
是否必选：是
注意事项：仅在 setup() 之后调用有效。OSS 选择参考：
            - 0（Ultra Low Power）：4.5ms 转换，适合低功耗应用
            - 1（Standard）：7.5ms 转换，适合常规测量
            - 2（High Resolution）：13.5ms 转换，适合较高精度需求
            - 3（Ultra High Resolution）：25.5ms 转换，适合高精度气象站
参数示例：3

返回值

无

示例

-- 设置为超高分辨率模式
exs_bmp180.set_oss(3)

-- 切换回超低功耗模式
exs_bmp180.set_oss(0)

4.4 海拔计算

4.4.1 exs_bmp180.set_sea_level_pressure(pressure)

功能

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

参数

pressure

参数含义：海平面标准气压，单位 Pa
数据类型：number
取值范围：95000~105000
是否必选：是
注意事项：默认 101325。可通过联网查询本地气象站数据获取更精确的值
参数示例：101800

返回值

无

示例

exs_bmp180.set_sea_level_pressure(101800)

4.4.2 exs_bmp180.get_altitude(pressure, sea_level_pressure)

功能

通过当前气压值和海平面气压计算海拔高度，使用国际气压公式。 海平面气压可通过 set_sea_level_pressure() 预先设置，也可每次调用时传入。

参数

pressure

参数含义：当前气压值，单位 Pa
数据类型：number
取值范围：30000~110000
是否必选：是
注意事项：通常传入 get_data() 返回的 data.pressure
参数示例：101325

sea_level_pressure

参数含义：海平面标准气压，单位 Pa（可选，传入则覆盖 set_sea_level_pressure 设置的默认值）
数据类型：number
取值范围：95000~105000
是否必选：否
注意事项：默认使用 set_sea_level_pressure 设置的值，未设置时默认 101325
参数示例：101325

返回值

local altitude = exs_bmp180.get_altitude(pressure, sea_level_pressure)

altitude

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

示例

-- 方式一：先设海平面气压，再计算海拔
exs_bmp180.set_sea_level_pressure(101800)
local data = exs_bmp180.get_data()
if data then
    local alt = exs_bmp180.get_altitude(data.pressure)
    log.info("exs_bmp180", string.format("海拔=%.1f 米", alt))
end

-- 方式二：每次调用时临时传入
local alt2 = exs_bmp180.get_altitude(data.pressure, 101800)

4.5 传感器控制

4.5.1 exs_bmp180.close()

功能

关闭 BMP180 传感器，重置内部状态。

close 后需要重新调用 setup() 才能再次使用。

close 后调用 get_data() 会返回 nil 并提示"请先 setup()"。

参数

无

返回值

无

示例

exs_bmp180.close()

4.6 辅助函数

4.6.1 exs_bmp180.version()

功能

获取 exs_bmp180 库的版本号。

参数

无

返回值

local ver = exs_bmp180.version()

ver

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

示例

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

五、版本更新说明

版本号：202607220900

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

  2. 更新内容：

    • 初版，实现 BMP180 驱动所有基础功能

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

    • 支持 4 种过采样率（OSS 0~3）

    • 自动读取 E2PROM 校准补偿参数

    • 支持校准温度补偿算法

    • 支持校准气压补偿算法

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

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

六、产品支持说明

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

AI问答