电源管理(pm)
pm 是萤火虫T1 固件内置的电源管理模块,通过 I2C 控制 SW6106 电源芯片,负责切换供电输出、读取电池电量与充电状态,以及执行休眠关机。
器件地址 0x3C,SDA=GPIO2、SCL=GPIO1,与 IMU 共用同一条总线。
pm.IDLE / pm.VCC_OUTPUT / pm.USB_OUTPUT / pm.SLEEP。
set_power_state() 只记录状态,真正的输出切换发生在 pm.poll() 里。
硬件与引脚
| 项目 | 值 |
|---|---|
| 电源芯片 | SW6106 |
| 通信方式 | I2C(与 IMU 等模块共用同一条总线) |
| 器件地址 | 0x3C |
SDA / SCL | GPIO2 / GPIO1,100 kHz |
| 输出控制引脚 | GPIO39(USB 供电输出)、GPIO21(3.3V 电源控制),均为开漏输出 |
| 充电状态位 | 寄存器 0x11 的 bit4 |
| 电量寄存器 | 0x4D(启动器就是读它来显示电量百分比) |
你不需要自己创建 I2C 对象——模块内部使用固件里的共享总线封装,pm.init() 会处理这一切。
快速开始
import pm
pm.init() # 必须先初始化
pm.set_power_state(pm.VCC_OUTPUT) # 让 5V 输出接通,给外部灯带供电
print("电量:", int(pm.get_4D_status()), "%")
运行现象:REPL 打印当前电量百分比;如果这段代码跑在启动器里(应用放在 /sd/apps/),5V 输出会在 1 秒内接通——因为启动器有一个后台线程每秒调用 pm.poll()。
独立运行(例如自己写的 main.py,或直接在 REPL 里跑)时,必须自己周期性调用 pm.poll(),否则 set_power_state() 不会产生任何实际效果。
电源状态
| 常量 | 数值 | 典型用途 |
|---|---|---|
pm.IDLE | 0 | 空闲。启动器浏览应用列表时使用 |
pm.VCC_OUTPUT | 1 | VCC 输出。应用要驱动外部灯带时使用 |
pm.USB_OUTPUT | 2 | 强制打开输出,固件中未被启动器使用 |
pm.SLEEP | 3 | 休眠。poll() 在此状态下不动任何输出引脚 |
API 参考
初始化 pm.init()
pm.init()
无参数、无返回值。作用:建立共享 I2C 总线并创建设备句柄、把电源状态置为 pm.IDLE、配置两个输出引脚为开漏输出,并向 SW6106 写入初始寄存器值。
- 可以重复调用:内部用
initialized标记,已初始化时直接返回。 - 必须在所有其他 API 之前调用:否则 I2C 设备句柄还没建立,后续读写不会正常工作。
设置电源状态 pm.set_power_state()
pm.set_power_state(state)
| 参数 | 类型 | 取值 |
|---|---|---|
state | int | pm.IDLE / pm.VCC_OUTPUT / pm.USB_OUTPUT / pm.SLEEP |
无返回值。关键点:它只把状态记下来,不立刻改任何硬件。 真正的输出切换由 pm.poll() 完成,两者的分工见下文。
轮询 pm.poll()
pm.poll()
无参数、无返回值。读取 SW6106 的充电状态,然后按当前电源状态控制 GPIO39 与芯片的输出使能寄存器。
- 必须周期性调用,一般每秒一次就够。启动器就是用后台线程每秒调一次,所以它启动的应用里通常不需要自己调。
- 模块内部会记住上一次的输出动作,只有动作发生变化时才写寄存器,所以每秒调用不会产生多余的 I2C 流量。
休眠关机 pm.sleep()
result = pm.sleep()
无参数,返回一个字符串:
| 返回值 | 含义 |
|---|---|
"go to sleep" | 已执行关机:写入休眠寄存器,并断开 GPIO39 / GPIO21 输出 |
"no sleep" | 正在充电,拒绝休眠,函数什么都没做,设备继续运行 |
pm.sleep() 是真正的断电:它靠 SW6106 切断电源轨,调用后设备会关机,程序不会继续往下执行。这也是固件里唯一的关机手段——pm 模块没有 deinit(),也没有单独的关机方法。
读取电量 pm.get_4D_status()
percent = pm.get_4D_status() # 返回 int
返回芯片寄存器 0x4D 的原值,启动器直接把它当作电量百分比显示。固件不做滤波和平滑,显示时建议 int() 取整。
读取充电状态 pm.get_charging_status()
charging = pm.get_charging_status() # 返回 0 或 1
| 返回值 | 含义 |
|---|---|
0 | 未充电(电池供电) |
1 | 正在充电 |
注意一个特殊情况:当电源状态是 pm.USB_OUTPUT 时,这个函数恒返回 0,因为它直接按「未充电」处理。
刷新电量 pm.refresh_power_percent()
percent = pm.refresh_power_percent() # 返回 int(寄存器 0x4F)
打开芯片的自动电量评估位、触发一次供电控制变化,等待 20 毫秒后返回寄存器 0x4F 的值。
- 它是阻塞的(固件内部
delay 20ms),不要放在按键回调或高频循环里。 - 电量读数明显不合理时,先调用它触发芯片重新评估,再读
get_4D_status()。
读取芯片温度 pm.get_chip_temperature()
temp = pm.get_chip_temperature() # 返回 float,单位摄氏度
由寄存器 0x1A(低位)与 0x1B(高 4 位)换算得出,公式为 ((raw - 1851) / 6.82)。这是芯片自身的温度,不是环境温度。
读取原始状态
pm.get_system_status() # 寄存器 0x11 原值(充电位是 bit4)
pm.get_4E_status() # 寄存器 0x4E 原值
pm.get_4F_status() # 寄存器 0x4F 原值
三个函数都是「读一个寄存器、原样返回 int」,固件不做任何解析。日常开发用不到,调试供电异常时可以用来观察芯片内部状态。
poll() 在各状态下的实际动作
这是理解 pm 的核心。pm.poll() 的目标是「不管插不插 USB,都让输出保持正确」,具体行为如下:
| 你设置的状态 | GPIO39 输出 | SW6106 输出使能 |
|---|---|---|
pm.IDLE | 未充电 → 1,充电中 → 0 | 关闭 |
pm.VCC_OUTPUT | 未充电 → 1,充电中 → 0 | 未充电 → 打开,充电中 → 关闭 |
pm.USB_OUTPUT | 恒为 0 | 打开 |
pm.SLEEP | 不改变 | 不改变 |
| 其它任意整数 | 同 pm.IDLE | 关闭 |
注意 VCC_OUTPUT 这一行:充电时输出会被主动关闭。这是芯片侧的保护逻辑,不是 bug——所以你会发现「插着 USB 时外部灯带反而不亮」。
常见坑点
set_power_state()之后必须有poll()才生效。 独立运行的程序忘了调poll(),是最常见的「设了状态却毫无反应」。init()不能省。 所有接口都依赖init()建立的 I2C 句柄,顺序不能颠倒。sleep()会真的断电关机。 它不是「低功耗待机」,调用后程序不会继续执行。想恢复只能重新上电或按开机键。- 绝对不要在异常退出 /
finally里调sleep()。 Ctrl-C 中断调试(Thonny、REPL)也会走finally,一旦关断电源,设备会「睡死」、串口再也连不上。只在明确的关机路径里调用。 get_charging_status()在USB_OUTPUT状态下恒为 0。 需要真实充电状态时,先把状态设回IDLE或VCC_OUTPUT。refresh_power_percent()会阻塞约 20 毫秒。 别在按键回调里用它刷新电量,交给主循环。- pm 与 IMU 共用 I2C 总线(
GPIO1/GPIO2)。请不要把这两个引脚挪作他用,也不要自己在外面再建一条 I2C。
更多配方
应用启动时接通 5V 输出
放在 App 的 boot.py 开头即可。启动器的 poll 线程会在一秒内让状态生效:
import pm
pm.init()
pm.set_power_state(pm.VCC_OUTPUT) # 外部灯带的 5V 供电
独立运行时的轮询循环
import pm
import time
pm.init()
pm.set_power_state(pm.VCC_OUTPUT)
while True:
pm.poll() # 每秒一次就够
time.sleep(1)
显示电量与充电状态
import pm
percent = int(pm.get_4D_status())
charging = pm.get_charging_status()
print("{}% {}".format(percent, "充电中" if charging else "电池供电"))
空闲自动休眠(充电中不睡)
import pm
import time
IDLE_LIMIT = 60 # 连续空闲 60 秒后休眠
idle = 0
while True:
if pm.get_charging_status() == 1:
idle = 0 # 充电时不计时,sleep() 也会被拒绝
else:
idle += 1
if idle >= IDLE_LIMIT:
print(pm.sleep()) # "go to sleep" 之后设备就断电了
break
time.sleep(1)
完整示例
萤火虫T1 的应用放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。下面这段放进 /sd/apps/my-power-app/boot.py:中键短按报电量,中键长按退出并把输出交还给启动器。
import pm
import time
from button import Button
pm.init()
pm.set_power_state(pm.VCC_OUTPUT) # 接通 5V 输出给灯带供电
buttons = Button()
running = True
def on_center_short():
print("电量: {}% 充电: {}".format(
int(pm.get_4D_status()),
pm.get_charging_status(),
))
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:
# 灯效渲染之类的活干在这里
# 输出切换由启动器的 poll 线程负责,这里不用再调 pm.poll()
time.sleep(0.1)
# 退出前回到空闲状态,把输出交还给启动器管理。
# 注意:这里不要调 pm.sleep(),否则设备会直接断电。
pm.set_power_state(pm.IDLE)
buttons.deinit()
相关模块见 五向按键(button)、WS2812 炫彩灯(ws2812) 与 运动传感器(imu)。
排错
| 现象 | 原因 / 处理 |
|---|---|
| 外部灯带不亮、量不到 5V | 没设 pm.VCC_OUTPUT,或独立运行时没调 pm.poll() → 每秒调一次 |
设了 VCC_OUTPUT 但输出是关的 | 正在充电,该状态下输出被主动关闭 → 拔掉 USB 再试 |
| 所有接口都「无效」 | 忘了 pm.init() → 这是其他调用的前提 |
插着 USB 时 get_charging_status() 一直是 0 | 当前状态是 pm.USB_OUTPUT,该状态下恒返回 0 → 切回 IDLE |
pm.sleep() 返回 "no sleep" | 正在充电,芯片拒绝休眠 → 拔掉 USB 后再调用 |
| 设备睡死、串口无响应 | 在 Ctrl-C 中断或异常退出路径里调了 pm.sleep() → 只在真正的关机路径调用 |
| 电量读数明显不对 | 读的是芯片原值且未刷新 → 先 refresh_power_percent() 再读 get_4D_status() |
AI 用法(即将上线)
以后你不用自己分辨 IDLE 和 VCC_OUTPUT、也不用记 poll() 该在哪调:用自然语言描述你想要的供电与续航行为,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。
比如直接对它说:
应用启动时给灯带接通 5V,屏幕上显示电量,闲置一分钟后自动休眠,充电时不要休眠。
它就会把 pm、Button 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。