跳到主要内容

电源管理(pm)

pm 是萤火虫T1 固件内置的电源管理模块,通过 I2C 控制 SW6106 电源芯片,负责切换供电输出、读取电池电量与充电状态,以及执行休眠关机。

I2C 控制 SW6106

器件地址 0x3C,SDA=GPIO2、SCL=GPIO1,与 IMU 共用同一条总线。

四种电源状态

pm.IDLE / pm.VCC_OUTPUT / pm.USB_OUTPUT / pm.SLEEP。

靠 poll() 生效

set_power_state() 只记录状态,真正的输出切换发生在 pm.poll() 里。

硬件与引脚​

项目值
电源芯片SW6106
通信方式I2C(与 IMU 等模块共用同一条总线)
器件地址0x3C
SDA / SCLGPIO2 / 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.IDLE0空闲。启动器浏览应用列表时使用
pm.VCC_OUTPUT1VCC 输出。应用要驱动外部灯带时使用
pm.USB_OUTPUT2强制打开输出,固件中未被启动器使用
pm.SLEEP3休眠。poll() 在此状态下不动任何输出引脚

API 参考​

初始化 pm.init()​

pm.init()

无参数、无返回值。作用:建立共享 I2C 总线并创建设备句柄、把电源状态置为 pm.IDLE、配置两个输出引脚为开漏输出,并向 SW6106 写入初始寄存器值。

  • 可以重复调用:内部用 initialized 标记,已初始化时直接返回。
  • 必须在所有其他 API 之前调用:否则 I2C 设备句柄还没建立,后续读写不会正常工作。

设置电源状态 pm.set_power_state()​

pm.set_power_state(state)
参数类型取值
stateintpm.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 时外部灯带反而不亮」。

常见坑点​

  1. set_power_state() 之后必须有 poll() 才生效。 独立运行的程序忘了调 poll(),是最常见的「设了状态却毫无反应」。
  2. init() 不能省。 所有接口都依赖 init() 建立的 I2C 句柄,顺序不能颠倒。
  3. sleep() 会真的断电关机。 它不是「低功耗待机」,调用后程序不会继续执行。想恢复只能重新上电或按开机键。
  4. 绝对不要在异常退出 / finally 里调 sleep()。 Ctrl-C 中断调试(Thonny、REPL)也会走 finally,一旦关断电源,设备会「睡死」、串口再也连不上。只在明确的关机路径里调用。
  5. get_charging_status() 在 USB_OUTPUT 状态下恒为 0。 需要真实充电状态时,先把状态设回 IDLE 或 VCC_OUTPUT。
  6. refresh_power_percent() 会阻塞约 20 毫秒。 别在按键回调里用它刷新电量,交给主循环。
  7. 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/。

Agent 入口(即将上线)

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