跳到主要内容

九轴传感器(imu)

imu 是萤火虫T1 固件内置的九轴运动传感器模块,通过 I2C 驱动 BMI270(3 轴加速度 + 3 轴陀螺仪)与 BMM150(3 轴磁力计),只需要 init() 和 read_9axis() 两个函数,就能拿到设备完整的姿态数据。启动器的「自动休眠」就是靠读它判断设备是否被放置不动。

一次读回 9 个值

read_9axis() 一次返回加速度(m/s²)、角速度(°/s)、磁感应强度(μT)。

与 pm 共用 I2C

SDA=GPIO2、SCL=GPIO1、100 kHz。不要自己再建一条总线。

没数据就返回 -1

三个传感器有一个没刷新就失败,跳过这一轮、下次再读即可。

硬件与引脚​

项目值
加速度 + 陀螺仪BMI270
磁力计BMM150(挂在 BMI270 的辅助接口上访问)
通信方式I2C(与 电源管理(pm) 共用同一条总线)
SDA / SCLGPIO2 / 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、100 kHz)→ 初始化 BMI270 → 配置加速度计与陀螺仪(±2 g / ±2000 °/s、100 Hz)→ 配置磁力计辅助接口 → 启用三个传感器 → 把数据就绪中断映射到 INT1。
  • 已经初始化过时会直接返回 0,不会重复初始化。启动器的自动休眠线程已经调用过一次,所以你的应用里再调用既是安全的、也非常快。
  • 初始化失败后再调用会重新尝试:失败时内部标记不会被置上。

失败时的返回值含义:

rslt名称典型原因
0成功—
-1BMI2_E_NULL_PTR共享 I2C 总线句柄无效,总线没建起来
-2BMI2_E_COM_FAILI2C 通信失败(接线异常,或引脚被别的代码占用)
-3BMI2_E_DEV_NOT_FOUND读不到芯片 ID,传感器没正常工作
-4BMI2_E_INVALID_CONFIG配置参数无效
其它负值Bosch 驱动内部错误码初始化 / 配置过程中的失败

读取九轴数据 imu.read_9axis()​

rslt, accel, gyro, mag = imu.read_9axis()

无参数,返回一个 4 元组:

位置类型说明
rsltint0 表示成功;非 0 表示这一轮没取到有效数据
acceltuple[float, float, float]加速度 (ax, ay, az),单位 m/s²
gyrotuple[float, float, float]角速度 (gx, gy, gz),单位 °/s
magtuple[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,属于正常现象。

常见坑点​

  1. 加速度单位是 m/s²,不是 g。 判断「是否倾斜」时按 ±9.8 来算;直接和 1.0 比较永远不成立。
  2. rslt != 0 不代表传感器坏了。 最常见的含义是「这一轮数据还没就绪」,尤其是两次读取间隔太短时。正确做法是跳过这一轮。
  3. rslt != 0 时三个值全是 0.0。 不判断 rslt 直接运算,会把真实数据抹成 0,进而导致静止检测误判。
  4. init() 失败返回的是负数,别只判断 != 0 就当「坏了」。 把值打印出来,是 -1 / -2 / -3 / -4 中的哪一个,能直接定位原因。
  5. 读得再密也不会更快。 采样率固定 100 Hz,循环里塞 time.sleep(0.001) 只会反复拿到同一帧或 -1,白白占用 CPU。想稳定成功,间隔给到 20 毫秒以上。
  6. 不要自己再建 I2C。 GPIO1 / GPIO2 被 imu 与 pm 共用,模块内部用的是固件里的共享总线,另建一条会互相打架。
  7. 磁力计容易被干扰。 附近的磁铁、扬声器、电机以及灯带的大电流走线都会让 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/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。