九轴传感器(imu)
imu 是萤火虫T1 固件内置的九轴运动传感器模块,通过 I2C 驱动 BMI270(3 轴加速度 + 3 轴陀螺仪)与 BMM150(3 轴磁力计),只需要 init() 和 read_9axis() 两个函数,就能拿到设备完整的姿态数据。启动器的「自动休眠」就是靠读它判断设备是否被放置不动。
read_9axis() 一次返回加速度(m/s²)、角速度(°/s)、磁感应强度(μT)。
SDA=GPIO2、SCL=GPIO1、100 kHz。不要自己再建一条总线。
三个传感器有一个没刷新就失败,跳过这一轮、下次再读即可。
硬件与引脚
| 项目 | 值 |
|---|---|
| 加速度 + 陀螺仪 | BMI270 |
| 磁力计 | BMM150(挂在 BMI270 的辅助接口上访问) |
| 通信方式 | I2C(与 电源管理(pm) 共用同一条总线) |
SDA / SCL | GPIO2 / GPIO1,100 kHz,内部上拉 |
| 量程 | 加速度 ±2 g,陀螺仪 ±2000 °/s |
| 采样率 | 加速度、陀螺仪、磁力计均为 100 Hz |
| 数据就绪 | 已映射到 BMI270 的 INT1 引脚(固件内部使用,无需你处理) |
你不需要自己创建 I2C 对象——模块内部使用固件里的共享总线封装,imu.init() 会处理这一切。
快速开始
import imu
if imu.init() != 0:
print("IMU 初始化失败")
else:
rslt, accel, gyro, mag = imu.read_9axis()
print("加速度(m/s²):", accel)
print("陀螺仪(°/s):", gyro)
print("磁力计(μT):", mag)
运行现象:把设备平放在桌面上,accel 三个值里会有一个轴接近 ±9.8、另外两轴接近 0(重力);gyro 三个值都接近 0;mag 在几十 μT 量级,转动设备时数值会跟着变。
初始化失败时 imu.init() 返回负数,具体含义见下文错误码表。
九轴数据与单位
这是最容易搞错的部分:固件内部已经帮你把原始 LSB 换算成了物理量,你直接拿到的就是最终数值。
| 数据 | 来源 | 单位 | 量程 | 静止平放时的典型值 |
|---|---|---|---|---|
accel = (ax, ay, az) | BMI270 加速度计 | m/s² | ±2 g | 某一轴 ≈ ±9.8,其余 ≈ 0 |
gyro = (gx, gy, gz) | BMI270 陀螺仪 | °/s | ±2000 °/s | 三个值都 ≈ 0 |
mag = (mx, my, mz) | BMM150 磁力计 | μT | — | 约 ±几十 μT,随朝向变化 |
两个必须记住的要点:
- 加速度单位是 m/s²,不是 g。 固件用
GRAVITY_EARTH = 9.80665换算过,所以静止时读数是 9.8 左右而不是 1.0。想换算成 g,除以9.80665即可。 - 重力落在哪一轴上,以实机实测为准。 它取决于传感器的贴装方向,拿到设备后先读一次静止数据、看哪个轴的绝对值最大,再据此写「朝上 / 朝下 / 立起」之类的判断,不要照抄别人的轴号。
一个与轴方向无关的实用指标是总加速度:
total = math.sqrt(accel[0]**2 + accel[1]**2 + accel[2]**2)
静止时它约等于 9.8,快速挥动时会明显变大,接近 0 则说明在自由落体。
API 参考
初始化 imu.init()
rslt = imu.init() # 0 表示成功
无参数,返回 int:0 表示成功,负数表示失败。
- 首次调用会依次完成:建立共享 I2C 总线(
SDA=GPIO2、SCL=GPIO1、100kHz)→ 初始化 BMI270 → 配置加速度计与陀螺仪(±2 g / ±2000 °/s、100 Hz)→ 配置磁力计辅助接口 → 启用三个传感器 → 把数据就绪中断映射到INT1。 - 已经初始化过时会直接返回
0,不会重复初始化。启动器的自动休眠线程已经调用过一次,所以你的应用里再调用既是安全的、也非常快。 - 初始化失败后再调用会重新尝试:失败时内部标记不会被置上。
失败时的返回值含义:
rslt | 名称 | 典型原因 |
|---|---|---|
0 | 成功 | — |
-1 | BMI2_E_NULL_PTR | 共享 I2C 总线句柄无效,总线没建起来 |
-2 | BMI2_E_COM_FAIL | I2C 通信失败(接线异常,或引脚被别的代码占用) |
-3 | BMI2_E_DEV_NOT_FOUND | 读不到芯片 ID,传感器没正常工作 |
-4 | BMI2_E_INVALID_CONFIG | 配置参数无效 |
| 其它负值 | Bosch 驱动内部错误码 | 初始化 / 配置过程中的失败 |
读取九轴数据 imu.read_9axis()
rslt, accel, gyro, mag = imu.read_9axis()
无参数,返回一个 4 元组:
| 位置 | 类型 | 说明 |
|---|---|---|
rslt | int | 0 表示成功;非 0 表示这一轮没取到有效数据 |
accel | tuple[float, float, float] | 加速度 (ax, ay, az),单位 m/s² |
gyro | tuple[float, float, float] | 角速度 (gx, gy, gz),单位 °/s |
mag | tuple[float, float, float] | 磁感应强度 (mx, my, mz),单位 μT |
行为说明:
- 三组数据一次读回:内部是一次突发读取,所以比分开读三次更省时间。
- 三个传感器只要有一个还没刷新,
rslt就非 0,此时三个三元组全是0.0——这就是为什么必须先判断rslt,否则会把数据「抹平」。 - 不阻塞:它只读一次寄存器,没准备好就直接返回失败,不会等待新数据。
- 每次返回的都是新的元组,所以可以直接
last_accel = accel存下上一次读数,后续读取不会把它覆盖掉。
数据就绪与读取节奏
采样率是 100 Hz,也就是每 10 毫秒三个传感器才各产生一帧新数据。read_9axis() 是否成功,完全取决于「距离上一帧有没有满 10 毫秒」:
| 情况 | rslt | 说明 |
|---|---|---|
| 距上次成功读取 ≥ 10 毫秒 | 0 | 三组数据都是最新的一帧 |
| 两次读取间隔过短 | 常见的 -1 | 还有传感器没刷新,重试即可,不是故障 |
一直返回 -1 | -1 | 长时间拿不到数据 → 见下方排错表 |
启动器的自动休眠线程就是每秒读一次,读到 rslt != 0 时直接跳过这一轮、不做任何报错——这就是推荐的处理方式。
另外,启动器自己的循环也在读同一个传感器,两个线程同时读时偶尔会有一方拿到 -1,属于正常现象。
常见坑点
- 加速度单位是 m/s²,不是 g。 判断「是否倾斜」时按 ±9.8 来算;直接和
1.0比较永远不成立。 rslt != 0不代表传感器坏了。 最常见的含义是「这一轮数据还没就绪」,尤其是两次读取间隔太短时。正确做法是跳过这一轮。rslt != 0时三个值全是0.0。 不判断rslt直接运算,会把真实数据抹成 0,进而导致静止检测误判。init()失败返回的是负数,别只判断!= 0就当「坏了」。 把值打印出来,是-1/-2/-3/-4中的哪一个,能直接定位原因。- 读得再密也不会更快。 采样率固定 100 Hz,循环里塞
time.sleep(0.001)只会反复拿到同一帧或-1,白白占用 CPU。想稳定成功,间隔给到 20 毫秒以上。 - 不要自己再建 I2C。
GPIO1/GPIO2被 imu 与 pm 共用,模块内部用的是固件里的共享总线,另建一条会互相打架。 - 磁力计容易被干扰。 附近的磁铁、扬声器、电机以及灯带的大电流走线都会让
mag跳变;先排查环境,再怀疑传感器。
更多配方
判断设备是否静止
与启动器自动休眠用的是同一套算法:比较连续两次读数的变化量之和。
import imu
import time
THRESHOLD_ACCEL = 0.05 # 单位 m/s²,与启动器一致
THRESHOLD_GYRO = 0.4 # 单位 °/s
imu.init()
last_accel = [0.0, 0.0, 0.0]
last_gyro = [0.0, 0.0, 0.0]
while True:
rslt, accel, gyro, mag = imu.read_9axis()
if rslt != 0: # 没就绪,跳过这一轮
time.sleep(0.1)
continue
delta_accel = sum(abs(a - b) for a, b in zip(accel, last_accel))
delta_gyro = sum(abs(a - b) for a, b in zip(gyro, last_gyro))
if delta_accel < THRESHOLD_ACCEL and delta_gyro < THRESHOLD_GYRO:
print("静止")
else:
print("运动中")
last_accel = accel
last_gyro = gyro
time.sleep(0.1)
晃动就响一声
import imu
import beep
import time
SHAKE_THRESHOLD = 3.0 # m/s²,调小更灵敏
imu.init()
last_accel = [0.0, 0.0, 0.0]
while True:
rslt, accel, gyro, mag = imu.read_9axis()
if rslt == 0:
delta = sum(abs(a - b) for a, b in zip(accel, last_accel))
if delta > SHAKE_THRESHOLD:
beep.tone(2000, 100)
last_accel = accel
time.sleep(0.05)
用总加速度判断运动强度
不关心方向、只关心「动得有多厉害」时,用三个轴合成一个数值最省事:
import imu
import math
import time
imu.init()
while True:
rslt, accel, gyro, mag = imu.read_9axis()
if rslt == 0:
total = math.sqrt(accel[0]**2 + accel[1]**2 + accel[2]**2)
print("总加速度: {:.2f} m/s²".format(total)) # 静止时约 9.8
time.sleep(0.2)
自校准:找出重力落在哪一轴
拿到实机后先跑一次,后面写「朝上 / 朝下」判断就靠它:
import imu
imu.init()
rslt, accel, gyro, mag = imu.read_9axis()
print("平放时的加速度:", accel)
# 绝对值最大的那一轴就是重力轴,记下它的正负号即可。
完整示例
萤火虫T1 的应用放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。下面这段放进 /sd/apps/my-imu-app/boot.py:中键短按打印一次九轴数据,晃动时蜂鸣一次,中键长按退出。
import imu
import beep
import time
from button import Button
imu.init() # 启动器已初始化过,这里会立刻返回
buttons = Button()
running = True
last_accel = [0.0, 0.0, 0.0]
SHAKE_THRESHOLD = 3.0 # m/s²,越小越灵敏
def on_center_short():
rslt, accel, gyro, mag = imu.read_9axis()
if rslt != 0:
print("数据未就绪,请再按一次")
return
print("加速度(m/s²): {:.2f} {:.2f} {:.2f}".format(*accel))
print("陀螺仪(°/s): {:.2f} {:.2f} {:.2f}".format(*gyro))
print("磁力计(μT): {:.1f} {:.1f} {:.1f}".format(*mag))
def on_center_long():
global running
running = False
buttons.register_callback('center', 'short', on_center_short)
buttons.register_callback('center', 'long', on_center_long)
while running:
rslt, accel, gyro, mag = imu.read_9axis()
if rslt == 0: # 没就绪就跳过这一轮
delta = sum(abs(a - b) for a, b in zip(accel, last_accel))
if delta > SHAKE_THRESHOLD:
beep.tone(2000, 80) # 晃一下响一声
last_accel = accel
time.sleep(0.05)
buttons.deinit()
相关模块见 五向按键(button)、蜂鸣器(beep) 与 电源管理(pm)。
排错
| 现象 | 原因 / 处理 |
|---|---|
init() 返回负数 | I2C 通信异常或传感器未正常工作 → 按错误码表定位,重点查 GPIO1/GPIO2 是否被占用 |
偶发 rslt = -1 | 两次读取间隔短于 10 毫秒,或另一线程刚读走了数据 → 跳过这一轮,下次再读 |
一直 rslt = -1 | 传感器始终没有新数据 → 确认 init() 返回了 0,并检查是否与 pm 抢占了同一总线 |
accel 三个值全是 0.0 | 没有判断 rslt,把失败的结果当真用了 → 先判断 rslt == 0 再取数据 |
平放时 accel 出现 9.8 | 正常,单位是 m/s² → 想换成 g 就除以 9.80665 |
| 「倾斜判断」永远不成立 | 拿 m/s² 和 1.0 比较了 → 阈值改按 ±9.8 的量级来定 |
循环里绝大多数读数都是 rslt = -1 | 读得太密,快于 100 Hz 的采样率 → 把间隔提到 20 毫秒以上 |
mag 数值乱跳 | 附近有磁铁、扬声器、电机或大电流走线 → 换个位置再测 |
AI 用法(即将上线)
以后你不用自己分辨三个轴、也不用记 read_9axis() 什么时候会失败:用自然语言描述你想要的体感行为,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。
比如直接对它说:
晃动设备时蜂鸣一下,平放静止一分钟后提示「即将休眠」,中键短按打印当前姿态数据。
它就会把 imu、beep、Button、pm 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。