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

BMI270 六轴惯性传感器演示

一、功能模块介绍

1.1 核心主程序模块

1. main.lua - 主程序入口，负责项目初始化、版本定义和任务调度
2. bmi270_app.lua - BMI270 功能演示模块，包含初始化、数据读取、量程切换、姿态解算、中断触发、休眠唤醒共 6 项功能的演示用例

1.2 扩展库模块

1. exs_bmi270 - BMI270 扩展库，提供 I2C/SPI 双接口初始化、三轴加速度/角速度/温度读取、量程与采样率配置、Mahony 姿态解算、中断功能、计步功能、休眠唤醒等 API（8192 字节微程序已内嵌于扩展库，无需单独加载）

1.3 通信模式选择（MODE 变量）

bmi270_app.lua 顶部通过 MODE 变量选择通信模式，改一个变量即可切换，无需注释/取消注释代码：

MODE 值	通信模式	所需参数	适用场景
1	软件 I2C（默认）	scl/sda（任意 GPIO）	接线最灵活，Air780EPM 接线示例用 GPIO31/GPIO30
2	硬件 I2C	i2c_id（Air780EPM 用 1，Pin66=SDA、Pin67=SCL）	占用 CPU 少，实时性要求高
3	SPI	spi_id/cs/speed（Air780EPM 用 SPI0）	高速采样场景

1.4 中断功能说明

BMI270 支持硬件中断输出（INT1/INT2 引脚），扩展库提供：

• data_ready 数据就绪中断：开箱即用，每个采样周期触发一次，适合低功耗事件驱动

• 特征中断（any_motion 任意运动 / no_motion 无运动 / sig_motion 显著运动 / step 步进检测）：开箱即用，setup()/int_config() 配置后自动使能并映射到 INT 引脚；支持阈值与持续时间参数调节（any_motion_thresh_mg/any_motion_duration_ms、no_motion_thresh_mg/no_motion_duration_ms、sig_motion_block_ms、step_counter、step_watermark_steps）

• 计步说明：step 中断每检测到一步触发一次；get_step_count() 读取累计步数（32 位，0~4294967295），步数按 step_watermark_steps 的间隔刷新（默认每 20 步）；reset_step_count() 可清零重新计步

中断使用示例见 bmi270_app.lua 的 [5/6] 中断触发演示，演示 data_ready + any_motion 的配置与触发；接线需将 BMI270 的 INT1 引脚接到一个空闲 GPIO（默认低有效，GPIO 用 FALLING 触发）。

二、演示流程介绍

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

2.1 功能演示项说明

1. [1/6] 初始化和基本信息查询 - 初始化 BMI270 传感器，自动完成芯片 ID 校验（期望 0x24）与 8192 字节微程序加载，注册 INT1 中断，打印扩展库版本号
2. [2/6] 加速度/角速度/温度读取 - 读取三轴加速度（单位 g）、三轴角速度（单位 °/s）、芯片温度（单位 °C）
3. [3/6] 量程切换演示 - 动态切换加速度量程（±4g→±8g）和陀螺仪量程（±500→±1000 °/s），验证切换后数据自动换算
4. [4/6] 姿态解算 - 通过 Mahony 互补滤波输出 roll/pitch/yaw 姿态角，持续演示 5 秒
5. [5/6] 中断触发演示 - data_ready + any_motion 特征中断，topic 方式回调，持续 10 秒
6. [6/6] 休眠唤醒与资源释放 - 进入休眠、3 秒后唤醒验证数据，最后关闭传感器释放资源

三、演示硬件环境

3.1 硬件清单

• Air780EPM 核心板 × 1

• BMI270 六轴惯性传感器模块 × 1 demo所演示的BMI270 惯性传感器模块购买链接

• 母对母杜邦线 × 4

• TYPE-C 数据线 × 1

3.2 接线配置

3.2.1 BMI270 模块接线（软件 I2C，MODE=1，默认推荐）

Air780EPM 核心板	BMI270 模块
GPIO31（PIN32）	SCL
GPIO30（PIN31）	SDA
VDD_EXT	VCC
GND	GND
GPIO32（PIN33）	INT1（中断输出，可选）

说明：接线时注意杜邦线不宜过长，以免通信不稳定。BMI270 模块需 3.3V 供电，SCL/SDA 需上拉电阻（常见模块已内置）。SDO 引脚接 GND 时 I2C 地址为 0x68，接 VCC 时为 0x69，如读取不到数据可切换试试。

四、演示软件环境

4.1 开发工具

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

4.2 内核固件

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

4.3 脚本文件

• main.lua - 程序入口
• bmi270_app.lua - 演示模块
• exs_bmi270 - 扩展库（含 8192 字节微程序）

五、演示核心步骤

5.1 硬件准备

1. 按照接线表将 BMI270 模块连接到核心板（选择 MODE 对应的接线）
2. 确保电源连接正确，通过 TYPE-C USB 口供电
3. 首次上电请将设备水平静止放置，便于观察加速度数据
4. 检查所有接线无误，避免短路

5.2 软件配置

1. 打开 bmi270_app.lua，根据实际接线设置 MODE 变量（1=软件I2C / 2=硬件I2C / 3=SPI）
2. 确认 INT1_GPIO 与你的中断接线一致
3. main.lua 保持 require "bmi270_app" 即可

5.3 软件烧录

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

5.4 功能测试

5.4.1 初始化和基本信息查询演示

1. 设备启动后打印 "HELLO"，随后自动进入 [1/6] 初始化
2. 观察日志输出，确认初始化成功、芯片 ID 校验通过、中断注册
3. 初始化失败时检查接线：VCC=3.3V、GND、SCL、SDA

5.4.2 数据读取演示

1. 自动进入 [2/6] 数据读取
2. 观察三轴加速度（单位 g）、角速度（单位 °/s）、温度（单位 °C）输出
3. 静止水平放置时，加速度 Z 轴应接近 1.0g，X/Y 接近 0；角速度三轴接近 0

5.4.3 量程切换演示

1. 自动进入 [3/6] 量程切换
2. 观察加速度量程从 ±4g 切换为 ±8g、陀螺仪量程从 ±500°/s 切换为 ±1000°/s
3. 切换后数据自动按新量程换算

说明： 扩展库的量程切换会自动执行软复位 + 完整重新初始化（约 150ms）， 日志中会再次出现"微程序已分块写入"，属正常现象。

5.4.4 姿态解算演示

1. 自动进入 [4/6] 姿态解算
2. 演示会先自动执行陀螺零偏标定（约 50 次采样，需保持设备静止）
3. 标定完成后，观察 roll/pitch 反映设备当前真实静态姿态（水平放置约 0°，竖直/倾斜安装则显示对应角度）
4. 缓慢转动设备，观察三个姿态角实时跟踪变化
5. yaw 角连续叠加无 ±180° 跳变；无磁力计会随时间缓慢漂移

5.4.5 中断触发演示

1. 自动进入 [5/6] 中断触发演示（持续 10 秒）
2. 晃动设备 → 触发 any_motion 事件；静置 → data_ready 周期性触发
3. 观察日志打印触发事件名和三轴数据
4. 若无中断触发，检查 INT1 接线与 INT1_GPIO 配置

5.4.6 休眠唤醒演示

1. 自动进入 [6/6] 休眠唤醒
2. 观察 "已进入休眠" 日志，3 秒后自动唤醒
3. 唤醒后数据恢复读取，最后打印 "传感器已关闭"

5.5 预期效果

• 初始化：BMI270 初始化成功，微程序加载完成，打印扩展库版本号
• 数据读取：静止水平时 Z 轴加速度接近 1.0g，角速度接近 0，温度 30~45°C
• 量程切换：量程切换成功（自动软复位重初始化），切换后数据正常输出
• 姿态解算：先零偏标定，后姿态角平滑跟踪，Mahony 互补滤波有效抑制噪声
• 中断触发：晃动触发 any_motion，静置时 data_ready 周期性触发，事件名打印正常
• 休眠唤醒：休眠日志正常，唤醒后数据恢复
• 日志如下：

[2026-08-05 12:15:08.669][000000000.200] I/user.main BMI270_Demo 001.000.000
[2026-08-05 12:15:08.728][000000000.522] I/user.TEST === [1/6] 初始化 ===
[2026-08-05 12:15:08.790][000000000.525] I/user.exs_bmi270 BMI270 @ I2C 模式，芯片 ID=0x24
[2026-08-05 12:15:10.464][000000002.784] I/user.exs_bmi270 微程序已分块写入（8192 字节，每块 128）
[2026-08-05 12:15:10.635][000000002.953] I/user.exs_bmi270 init verify: PWR_CTRL=0x0E STATUS=0xD0 ACC_RANGE=0x01 GYR_RANGE=0x02
[2026-08-05 12:15:10.654][000000002.957] I/user.exs_bmi270 初始化完成：acc_range=4g gyro_range=500 acc_odr=200Hz gyro_odr=200Hz
[2026-08-05 12:15:10.673][000000002.967] I/user.exs_bmi270 any_motion 特征已使能（含自定义阈值）
[2026-08-05 12:15:10.689][000000002.974] I/user.exs_bmi270 INT1 已注册, int_gpio=32
[2026-08-05 12:15:10.706][000000002.975] I/user.TEST 初始化成功，扩展库版本: 202608051200
[2026-08-05 12:15:10.727][000000002.975] I/user.TEST === [2/6] 数据读取 (单位 g / °/s / °C) ===
[2026-08-05 12:15:10.743][000000002.981] I/user.exs_bmi270 ACC_RAW: 01 F1 BB 00 64 F3
[2026-08-05 12:15:10.761][000000002.981] I/user.exs_bmi270 GYR_RAW: 00 1E 03 18 C2 FE
[2026-08-05 12:15:10.778][000000002.982] I/user.exs_bmi270 TMP_RAW: 97 0C
[2026-08-05 12:15:10.795][000000002.993] I/user.TEST accel  x=-0.469  y=0.023  z=-0.394
[2026-08-05 12:15:10.811][000000002.994] I/user.TEST gyro   x=126.0  y=81.2  z=-11.3
[2026-08-05 12:15:10.829][000000002.994] I/user.TEST temp   29.3°C
[2026-08-05 12:15:11.178][000000003.495] I/user.TEST === [3/6] 量程切换演示 ===
[2026-08-05 12:15:13.439][000000005.755] I/user.exs_bmi270 微程序已分块写入（8192 字节，每块 128）
[2026-08-05 12:15:13.662][000000005.946] I/user.TEST 加速度量程已切换为 ±8g
[2026-08-05 12:15:16.114][000000008.403] I/user.TEST 陀螺仪量程已切换为 ±1000°/s
[2026-08-05 12:15:16.596][000000008.909] I/user.TEST === [4/6] 姿态解算 (5秒) ===
[2026-08-05 12:15:16.845][000000009.165] I/user.exs_bmi270 陀螺零偏标定完成: (1.976, -7.871, -10.207)°/s
[2026-08-05 12:15:16.877][000000009.172] I/user.TEST roll=168.6°  pitch=41.8°  yaw=150.8°
[2026-08-05 12:15:16.892][000000009.198] I/user.TEST roll=168.9°  pitch=41.7°  yaw=150.9°
[2026-08-05 12:15:16.908][000000009.224] I/user.TEST roll=169.2°  pitch=41.5°  yaw=151.0°
（姿态角每 20ms 打印一次，此处省略中间大量日志）
[2026-08-05 12:15:21.690][000000014.011] I/user.TEST 姿态解算演示结束
[2026-08-05 12:15:22.201][000000014.511] I/user.TEST === [5/6] 中断触发演示 (10秒) ===
[2026-08-05 12:15:22.435][000000014.754] I/user.TEST 中断事件: any_motion
[2026-08-05 12:15:22.453][000000014.759] I/user.TEST acc(-0.17,-0.03,1.02)g gyr(-89.8,70.2,-5.8)°/s
[2026-08-05 12:15:33.119][000000025.408] I/user.TEST 中断触发演示结束
[2026-08-05 12:15:33.135][000000025.408] I/user.TEST === [6/6] 休眠唤醒演示 ===
[2026-08-05 12:15:33.156][000000025.409] I/user.exs_bmi270 已进入休眠模式
[2026-08-05 12:15:36.139][000000028.432] I/user.TEST 已唤醒，读取一次数据验证
[2026-08-05 12:15:36.157][000000028.437] I/user.TEST accel  x=-0.678  y=0.011  z=-0.725
[2026-08-05 12:15:36.174][000000028.439] I/user.exs_bmi270 传感器已关闭
[2026-08-05 12:15:36.213][000000028.439] I/user.TEST ========== 所有演示完成 ==========

5.6 故障排除

现象	可能原因	解决方法
初始化失败，日志提示芯片识别失败	接线错误或供电不足	检查 VCC/GND/SCL/SDA 接线，确保 3.3V 供电
初始化失败，日志提示配置加载失败	传感器损坏	更换传感器模块
读取不到数据	接线错误或地址探测无命中	扩展库已自动探测 0x68/0x69（SDO 决定），仍失败检查 SDO 接线、供电与总线冲突
加速度 Z 轴偏差大	传感器未水平放置	水平静止放置后重新观察；竖直/倾斜安装属正常
数据不稳定	杜邦线过长/干扰	缩短杜邦线，降低 SPI 速率或改软件 I2C
中断不触发	INT1 接线错误或 INT1_GPIO 配置不对	检查 INT1 引脚接线，确认 bmi270_app.lua 中 INT1_GPIO 与实际一致
SPI 模式芯片 ID 读回 0xFF	① SDO/MISO 未接 ② 上电时 CSB 非低电平 ③ 模块 I2C 地址电阻钳住 SDO ④ SPI 引脚复用被占用	① 检查 4 根信号线 ② 确认 CS 上电为低 ③ 移除/确认 SDO 电阻 ④ 通过 LuatIO 检查 SPI0 复用是否被其他外设占用

5.7 扩展功能建议

1. 多圈偏航累计：get_attitude() 的 yaw 角为连续叠加值，可用于旋转圈数计数场景
2. 跌倒检测：将加速度量程设为 "16g" 并监测合加速度阈值，可识别剧烈冲击
3. SPI 高速采样：对采样率要求高的场景可改用 SPI 模式（MODE=3，接线见 3.2.3，速率最高 1MHz 以上）
4. 低功耗应用：间歇采样场景可读取一次后调用 sleep()，需要时再 wakeup() 降低功耗
5. 零偏标定：产品首次上电静止 1~2 秒调用 calibrate_gyro()，可显著降低静止姿态漂移
6. 计步功能：配置 step = true + step_counter = true + step_watermark_steps，配合 get_step_count()/reset_step_count() 实现计步器
7. exs_bmi270 更多接口的使用可以查看 exs_bmi270 扩展库说明