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

BME680 四合一环境传感器演示

一、功能模块介绍

1.1 核心主程序模块

1. main.lua - 主程序入口
2. bme680_demo.lua - BME680 功能演示模块

1.2 扩展库模块

1. exs_bme680 - BME680 扩展库，提供初始化、温度/气压/湿度/气体电阻读取、过采样率配置、IIR 滤波配置、气体加热器配置、海拔高度计算等 API

1.3 I2C 模式说明

推荐使用软件 I2C 模式：BME680 使用标准 I2C 接口通信，软件 I2C 模式无需指定 I2C 控制器，任意 GPIO 均可模拟 I2C 时序，灵活性更高。本 demo 默认使用软件 I2C 模式演示，也可通过 bme680_demo.lua 中的 MODE 变量切换为硬件 I2C 模式。

二、演示流程介绍

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

2.1 功能演示项说明

1. [1/6] 初始化与数据读取 - 初始化 BME680 传感器并读取温度（°C）、气压（hPa）、湿度（%RH）和气体电阻（Ω）数据，包含气体预热说明
2. [2/6] IIR 滤波器切换演示 - 依次切换 filter=0~7，观察数据平滑效果
3. [3/6] 过采样率切换演示 - 对比低功耗（1X）和高精度（16X）模式下的测量效果
4. [4/6] 气体加热器切换演示 - 依次测试三种加热器温度/时间组合（250°C、320°C、350°C）
5. [5/6] 空气质量判断演示 - 演示如何判断空气好坏：先记录干净空气稳定基线 R0，实时电阻相对 R0 下降越多空气越差（污染度 = (1 - R/R0) × 100%）
6. [6/6] 海拔高度测量与关闭 - 通过气压值计算海拔高度后关闭传感器

关于气体传感器预热与空气好坏判断（详见下文 5.4.5）：

• BME680 的 MOX 气体传感器上电后电阻会从低值（如几 kΩ）缓慢爬升至几十 kΩ，新板首次上电需预热 20~30 分钟电阻才稳定，这是正常现象（预热/烧机效应），稳定前读取的气体电阻没有参考意义
• 不能直接看电阻绝对值判断空气好坏，必须以干净空气中预热稳定后的电阻为基线 R0，实时电阻 R 相对 R0 下降越多说明 VOC 浓度越高、空气越差
• 经验等级：污染度 ≤10% 优、10%~30% 良、30%~60% 中、>60% 差（阈值需结合场景标定）

三、演示硬件环境

3.1 硬件清单

• Air780EPM 核心板 × 1
• BME680 四合一环境传感器模块 × 1 demo所演示的 BME680 环境传感器模块购买链接
• 母对母杜邦线 × 4
• TYPE-C 数据线 × 1

3.2 接线配置

3.2.1 BME680 模块接线

Air780EPM 核心板	BME680 模块
32/GPIO31	SCL
31/GPIO30	SDA
VDD_EXT	VCC
GND	GND

说明：

1. 接线时注意杜邦线不宜过长，以免通信不稳定
2. SCL 和 SDA 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC（部分模块已自带）
3. BME680 的 I2C 地址：SDO=GND 时 0x76，SDO=VCC 时 0x77

四、演示软件环境

4.1 开发工具

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

4.2 内核固件

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

4.3 脚本文件

1. main.lua - 程序入口
2. bme680_demo.lua - BME680 功能演示模块
3. exs_bme680 - BME680 扩展库

五、演示核心步骤

5.1 硬件准备

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

5.2 软件配置

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

require "bme680_demo"

如需切换通信模式，修改 bme680_demo.lua 中的 MODE 变量（1=软件 I2C，2=硬件 I2C）。

5.3 软件烧录

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

5.4 功能测试

5.4.1 初始化与数据读取演示

1. 设备启动后打印 "HELLO"，随后自动进入 [1/6] 初始化与数据读取
2. 观察日志输出，确认初始化成功（打印校准数据、预热提示）
3. 观察温度（°C）、气压（hPa）、湿度（%RH）和气体电阻（kΩ）的连续读取
4. 注意：首次上电气体电阻可能为 0，MOX 气体传感器需预热 20~30 分钟才稳定（详见 5.4.5）

5.4.2 IIR 滤波器切换演示

1. 自动进入 [2/6] IIR 滤波器切换演示
2. 依次观察 filter=0（关闭）~ filter=7（128 次平均）下的数据
3. filter 越大数据跳动越小

5.4.3 过采样率切换演示

1. 自动进入 [3/6] 过采样率切换演示
2. 先切换到低功耗模式（1X），观察数据
3. 再切换到高精度模式（16X），对比数据精度变化

5.4.4 气体加热器切换演示

1. 自动进入 [4/6] 气体加热器切换演示
2. 依次测试 250°C/100ms、320°C/150ms、350°C/200ms 三种参数
3. 观察不同温度下气体电阻值的变化

5.4.5 空气质量判断演示

这是理解 BME680 气体传感器最关键的一步，演示预热时长和如何判断空气好坏。

1. 自动进入 [5/6] 空气质量判断演示
2. 日志会先打印预热说明：新板首次上电 MOX 气体传感器需预热 20~30 分钟，电阻从低值缓慢爬升属正常，稳定前气体电阻读值无参考意义
3. 记录当前读数作为基线 R0（真实使用时必须在干净空气中预热 20~30 分钟、电阻稳定后再记录 R0）
4. 连续读取 3 次，每次计算污染度 (1 - R/R0) × 100% 并输出空气等级

如何判断空气好坏（核心）：

• 不能直接看电阻绝对值（不同芯片、不同温湿度下基线差异大）
• 在干净空气中预热 20~30 分钟后，记录稳定电阻为基线 R0
• 运行时实时电阻 R 相对 R0 下降越多，说明 VOC 浓度越高、空气越差
• 判断指标：ratio = R/R0（越接近 1 越干净），污染度 = (1 - R/R0) × 100%
• 经验等级（阈值需结合场景标定）：污染度 ≤10% 优、10%~30% 良、30%~60% 中、>60% 差

-- 判断空气质量等级，R 为实时气体电阻，R0 为干净空气稳定基线
local function judge_air(R, R0)
    if R0 <= 0 or R <= 0 then return "未就绪" end
    local pollution = (1 - R / R0) * 100
    if pollution <= 10 then return "优" end
    if pollution <= 30 then return "良" end
    if pollution <= 60 then return "中" end
    return "差"
end

5.4.6 海拔高度测量与关闭

1. 自动进入 [6/6] 海拔高度测量与关闭
2. 显示温度、气压、湿度、气体电阻和海拔高度
3. 关闭传感器后打印 "End"

5.5 预期效果

• 初始化与数据读取：BME680 初始化成功，四项环境数据正常输出

• IIR 滤波器切换：不同滤波器下数据平滑度不同

• 过采样率切换：高精度模式数据更稳定

• 气体加热器切换：不同温度下气体电阻值有变化

• 海拔高度测量：根据气压计算出当前海拔高度

• 日志如下：

[2026-08-20 21:30:06.039][000000000.246] I/user.main BME680_Demo 001.999.000
[2026-08-20 21:30:06.044][000000000.263] D/user.exs_bme680 version -> 202608080000
[2026-08-20 21:30:06.048][000000000.265] I/user.bme680_demo HELLO
[2026-08-20 21:30:06.172][000000001.265] I/user.bme680_demo ===== [1/5] 初始化与数据读取 =====
[2026-08-20 21:30:06.176][000000001.271] I/user.exs_bme680 I2C总线恢复完成
[2026-08-20 21:30:06.181][000000001.334] I/user.exs_bme680 BME680 @ I2C 0x77, CHIP_ID=0x61
[2026-08-20 21:30:06.194][000000001.347] I/user.exs_bme680 raw_T1=25923 raw_P1=36006 raw_T2=26603 raw_P2=-10347
[2026-08-20 21:30:06.215][000000001.347] I/user.exs_bme680 校准数据: T1=25923 T2=26603 T3=3 P1=36006 P2=-10347 H1=667 H2=1031 GH1=-34 GH2=-6023 GH3=18
[2026-08-20 21:30:06.233][000000001.355] I/user.exs_bme680 BME680 初始化完成, os_temp=4 os_pres=3 os_hum=2 filter=3 heater_temp=320°C heater_dur=150ms
[2026-08-20 21:30:06.241][000000001.355] I/user.exs_bme680 加热器校准: res_heat_range=1 res_heat_val=40 range_sw_err=1 heatr_res=0x76
[2026-08-20 21:30:06.250][000000001.355] I/user.exs_bme680 气体预热提示: 新板首次上电 MOX 气体传感器需预热 20~30 分钟，
[2026-08-20 21:30:06.258][000000001.355] I/user.exs_bme680 电阻会从低值缓慢爬升直至稳定，稳定前 gas_resistance 为 0 或数值不可信
[2026-08-20 21:30:06.270][000000001.355] I/user.bme680_demo BME680 初始化成功，版本: 202608080000
[2026-08-20 21:30:06.390][000000002.048] I/user.bme680_demo 温度=24.12°C 气压=1008.40hPa 湿度=66.6%RH 气体=2.4kΩ
[2026-08-20 21:30:09.534][000000005.241] I/user.bme680_demo 第1次读取: 温度=24.12°C 气压=1008.4hPa 湿度=66.4%RH 气体=3.4kΩ
[2026-08-20 21:30:11.735][000000007.434] I/user.bme680_demo 第2次读取: 温度=24.14°C 气压=1008.4hPa 湿度=66.3%RH 气体=4.6kΩ
[2026-08-20 21:30:13.922][000000009.627] I/user.bme680_demo 第3次读取: 温度=24.16°C 气压=1008.4hPa 湿度=66.1%RH 气体=5.9kΩ
[2026-08-20 21:30:13.929][000000009.628] I/user.bme680_demo ---- [1/5] 完成 ----
[2026-08-20 21:30:14.421][000000010.128] I/user.bme680_demo ===== [2/5] IIR 滤波器切换演示 =====
[2026-08-20 21:30:14.427][000000010.128] I/user.bme680_demo 设置滤波器 filter=0
[2026-08-20 21:30:14.437][000000010.136] I/user.exs_bme680 IIR 滤波器系数设为 0 (0次平均)
[2026-08-20 21:30:14.716][000000010.428] I/user.bme680_demo filter=0: 温度=24.58°C 气压=1008.42hPa 湿度=66.1%RH
[2026-08-20 21:30:15.723][000000011.429] I/user.bme680_demo 设置滤波器 filter=1
[2026-08-20 21:30:15.729][000000011.436] I/user.exs_bme680 IIR 滤波器系数设为 1 (1次平均)
[2026-08-20 21:30:16.019][000000011.729] I/user.bme680_demo filter=1: 温度=24.45°C 气压=1008.44hPa 湿度=65.8%RH
[2026-08-20 21:30:17.026][000000012.730] I/user.bme680_demo 设置滤波器 filter=2
[2026-08-20 21:30:17.033][000000012.737] I/user.exs_bme680 IIR 滤波器系数设为 2 (3次平均)
[2026-08-20 21:30:17.322][000000013.030] I/user.bme680_demo filter=2: 温度=24.45°C 气压=1008.40hPa 湿度=65.5%RH
[2026-08-20 21:30:18.330][000000014.031] I/user.bme680_demo 设置滤波器 filter=3
[2026-08-20 21:30:18.336][000000014.038] I/user.exs_bme680 IIR 滤波器系数设为 3 (7次平均)
[2026-08-20 21:30:18.628][000000014.331] I/user.bme680_demo filter=3: 温度=24.43°C 气压=1008.40hPa 湿度=65.3%RH
[2026-08-20 21:30:19.620][000000015.332] I/user.bme680_demo 设置滤波器 filter=4
[2026-08-20 21:30:19.634][000000015.339] I/user.exs_bme680 IIR 滤波器系数设为 4 (15次平均)
[2026-08-20 21:30:19.930][000000015.632] I/user.bme680_demo filter=4: 温度=24.42°C 气压=1008.36hPa 湿度=65.0%RH
[2026-08-20 21:30:20.921][000000016.633] I/user.bme680_demo 设置滤波器 filter=5
[2026-08-20 21:30:20.937][000000016.640] I/user.exs_bme680 IIR 滤波器系数设为 5 (31次平均)
[2026-08-20 21:30:21.231][000000016.933] I/user.bme680_demo filter=5: 温度=24.43°C 气压=1008.40hPa 湿度=64.9%RH
[2026-08-20 21:30:22.234][000000017.934] I/user.bme680_demo 设置滤波器 filter=6
[2026-08-20 21:30:22.240][000000017.941] I/user.exs_bme680 IIR 滤波器系数设为 6 (63次平均)
[2026-08-20 21:30:22.527][000000018.234] I/user.bme680_demo filter=6: 温度=24.44°C 气压=1008.42hPa 湿度=64.7%RH
[2026-08-20 21:30:23.534][000000019.235] I/user.bme680_demo 设置滤波器 filter=7
[2026-08-20 21:30:23.540][000000019.242] I/user.exs_bme680 IIR 滤波器系数设为 7 (127次平均)
[2026-08-20 21:30:23.829][000000019.535] I/user.bme680_demo filter=7: 温度=24.46°C 气压=1008.40hPa 湿度=64.7%RH
[2026-08-20 21:30:24.831][000000020.536] I/user.bme680_demo ---- [2/5] 完成 ----
[2026-08-20 21:30:25.326][000000021.036] I/user.bme680_demo ===== [3/5] 过采样率切换演示 =====
[2026-08-20 21:30:25.331][000000021.036] I/user.bme680_demo 切换到低功耗模式（1X过采样）
[2026-08-20 21:30:25.342][000000021.043] I/user.exs_bme680 温度过采样率设为 1
[2026-08-20 21:30:25.349][000000021.051] I/user.exs_bme680 气压过采样率设为 1
[2026-08-20 21:30:25.357][000000021.058] I/user.exs_bme680 湿度过采样率设为 1
[2026-08-20 21:30:25.621][000000021.326] I/user.bme680_demo 低功耗: 温度=24.46°C 气压=1008.40hPa 湿度=64.7%RH
[2026-08-20 21:30:26.621][000000022.327] I/user.bme680_demo 切换到高精度模式（16X过采样）
[2026-08-20 21:30:26.626][000000022.334] I/user.exs_bme680 温度过采样率设为 5
[2026-08-20 21:30:26.636][000000022.342] I/user.exs_bme680 气压过采样率设为 5
[2026-08-20 21:30:26.642][000000022.349] I/user.exs_bme680 湿度过采样率设为 5
[2026-08-20 21:30:26.993][000000022.705] I/user.bme680_demo 高精度: 温度=24.46°C 气压=1008.40hPa 湿度=64.7%RH
[2026-08-20 21:30:26.998][000000022.706] I/user.bme680_demo ---- [3/5] 完成 ----
[2026-08-20 21:30:27.504][000000023.206] I/user.bme680_demo ===== [4/5] 气体加热器切换演示 =====
[2026-08-20 21:30:27.512][000000023.206] I/user.bme680_demo 低温短时（250°C/100ms）
[2026-08-20 21:30:27.518][000000023.214] I/user.exs_bme680 气体加热器设为 250°C, 100ms
[2026-08-20 21:30:27.919][000000023.620] I/user.bme680_demo 气体=32.2kΩ 温度=24.46°C 湿度=64.7%RH
[2026-08-20 21:30:28.909][000000024.621] I/user.bme680_demo 默认配置（320°C/150ms）
[2026-08-20 21:30:28.925][000000024.628] I/user.exs_bme680 气体加热器设为 320°C, 150ms
[2026-08-20 21:30:29.374][000000025.085] I/user.bme680_demo 气体=16.6kΩ 温度=24.46°C 湿度=64.6%RH
[2026-08-20 21:30:30.382][000000026.086] I/user.bme680_demo 高温长时（350°C/200ms）
[2026-08-20 21:30:30.389][000000026.093] I/user.exs_bme680 气体加热器设为 350°C, 200ms
[2026-08-20 21:30:30.894][000000026.600] I/user.bme680_demo 气体=14.4kΩ 温度=24.46°C 湿度=64.6%RH
[2026-08-20 21:30:31.888][000000027.601] I/user.bme680_demo ---- [4/5] 完成 ----
[2026-08-20 21:30:32.387][000000028.101] I/user.bme680_demo ===== [5/5] 海拔高度测量与关闭 =====
[2026-08-20 21:30:32.700][000000028.409] I/user.bme680_demo 温度=24.46°C 气压=1008.4hPa 湿度=64.6%RH 气体=16.8kΩ 海拔=40.5米
[2026-08-20 21:30:32.706][000000028.409] I/user.exs_bme680 传感器已关闭
[2026-08-20 21:30:32.712][000000028.410] I/user.bme680_demo ---- [5/5] 完成 ----
[2026-08-20 21:30:33.210][000000028.910] I/user.bme680_demo ===== [演示完毕] =====
[2026-08-20 21:30:33.215][000000028.910] I/user.bme680_demo End

5.6 故障排除

1. 传感器初始化失败：

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

2. 读取数据异常：

   • 检查传感器供电是否正常
   • 自动地址检测会尝试 0x76 和 0x77，确认 SDO 引脚电平
   • 检查接线无松动

3. 气体电阻一直为 0：

   • 新板首次上电需要预热 20~30 分钟，MOX 加热器稳定前 gas_resistance 返回 0，属正常现象（详见 5.4.5）
   • 预热期间电阻从低值缓慢爬升属正常，待电阻稳定后再记录基线 R0 判断空气质量
   • 确认加热器温度和时间设置合理（默认 320°C/150ms），加热器未被禁用
   • 若长时间预热后仍为 0，检查供电是否稳定、set_gas_heater 参数是否合法

4. 海拔高度显示异常：

   • 海拔计算基于海平面标准气压 1013.25hPa，天气变化会影响计算精度
   • 可通过 exs_bme680.set_sea_level_pressure(pressure) 传入实际海平面气压校正

5.7 扩展功能建议

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