Power Management (pm)
pm is the power management module built into the Firefly T1 firmware. It talks to the SW6106 power chip over I2C and handles switching the supply output, reading battery level and charging status, and performing a sleep shutdown.
Device address 0x3C, SDA=GPIO2, SCL=GPIO1, sharing the bus with the IMU.
pm.IDLE / pm.VCC_OUTPUT / pm.USB_OUTPUT / pm.SLEEP.
set_power_state() only records the state; the output actually switches inside pm.poll().
Pin and hardware parameters
| Item | Value |
|---|---|
| Power chip | SW6106 |
| Bus | I2C (shared with the IMU and other modules) |
| Device address | 0x3C |
SDA / SCL | GPIO2 / GPIO1 at 100 kHz |
| Output control pins | GPIO39 (USB supply output), GPIO21 (3.3V supply control) — both open-drain |
| Charging status bit | bit4 of register 0x11 |
| Battery-level register | 0x4D (this is what the launcher reads to display the percentage) |
You never create the I2C object yourself — the module uses the firmware's shared bus wrapper, and pm.init() sets everything up.
Quick start
import pm
pm.init() # required first
pm.set_power_state(pm.VCC_OUTPUT) # turn on the 5V output that powers an LED strip
print("Battery:", int(pm.get_4D_status()), "%")
What you'll see: the REPL prints the current battery percentage. If this code runs inside the launcher (an app under /sd/apps/), the 5V output comes on within a second, because the launcher runs a background thread that calls pm.poll() every second.
When running standalone (your own main.py, or pasting into the REPL), you must call pm.poll() periodically yourself — otherwise set_power_state() has no effect at all.
Power states
| Constant | Value | Typical use |
|---|---|---|
pm.IDLE | 0 | Idle. Used by the launcher while browsing the app list |
pm.VCC_OUTPUT | 1 | VCC output. Use this when your app drives an external LED strip |
pm.USB_OUTPUT | 2 | Force the output on; unused by the launcher in current firmware |
pm.SLEEP | 3 | Sleep. poll() leaves all output pins untouched in this state |
API reference
Initialise pm.init()
pm.init()
No arguments, no return value. It sets up the shared I2C bus and creates the device handle, sets the power state to pm.IDLE, configures the two output pins as open-drain, and writes the initial SW6106 registers.
- May be called repeatedly: an internal
initializedflag makes it return immediately when already initialised. - Must be called before any other API: otherwise the I2C device handle does not exist yet and later reads and writes will not work.
Set the power state pm.set_power_state()
pm.set_power_state(state)
| Argument | Type | Values |
|---|---|---|
state | int | pm.IDLE / pm.VCC_OUTPUT / pm.USB_OUTPUT / pm.SLEEP |
No return value. The key point: it only records the state and changes no hardware. The actual output switching happens in pm.poll(); the division of labour is described below.
Poll pm.poll()
pm.poll()
No arguments, no return value. It reads the SW6106 charging status and then drives GPIO39 and the chip's output-enable register according to the current power state.
- Must be called periodically — once a second is plenty. The launcher does exactly that from a background thread, which is why apps it starts usually do not need to call it.
- The module remembers the last output action and only writes the registers when the action changes, so calling it every second costs almost no I2C traffic.
Sleep and shut down pm.sleep()
result = pm.sleep()
No arguments; returns a string:
| Return value | Meaning |
|---|---|
"go to sleep" | Shutdown performed: sleep registers are written and the GPIO39 / GPIO21 outputs are cut |
"no sleep" | Charging, so sleep is refused — the function did nothing and the device keeps running |
pm.sleep() is a real power cut: it relies on the SW6106 to drop the supply rails, so the device shuts down and your program does not continue. This is the only shutdown mechanism in the firmware — the pm module has no deinit() and no separate power-off method.
Read battery level pm.get_4D_status()
percent = pm.get_4D_status() # returns int
Returns the raw value of chip register 0x4D; the launcher treats it directly as a battery percentage. The firmware applies no filtering or smoothing, so wrap it in int() when displaying.
Read charging status pm.get_charging_status()
charging = pm.get_charging_status() # returns 0 or 1
| Return value | Meaning |
|---|---|
0 | Not charging (running on battery) |
1 | Charging |
Note one special case: while the power state is pm.USB_OUTPUT, this function always returns 0, because that state short-circuits to "not charging".
Refresh the battery level pm.refresh_power_percent()
percent = pm.refresh_power_percent() # returns int (register 0x4F)
Enables the chip's automatic fuel-gauge bit, triggers a supply-control change, waits 20 milliseconds, then returns the value of register 0x4F.
- It blocks (the firmware delays 20ms internally), so keep it out of button callbacks and tight loops.
- If the reading looks wrong, call it to force the chip to re-evaluate, then read
get_4D_status().
Read chip temperature pm.get_chip_temperature()
temp = pm.get_chip_temperature() # returns float in degrees Celsius
Derived from register 0x1A (low byte) and 0x1B (high nibble) with the formula ((raw - 1851) / 6.82). This is the chip's own temperature, not the ambient temperature.
Read raw status registers
pm.get_system_status() # raw register 0x11 (the charging bit is bit4)
pm.get_4E_status() # raw register 0x4E
pm.get_4F_status() # raw register 0x4F
All three read one register and return the raw int; the firmware does no parsing. Day-to-day code rarely needs them, but they are useful for inspecting internal chip state when debugging supply problems.
What poll() actually does in each state
This is the heart of the module. pm.poll() aims to keep the output correct whether or not USB is plugged in:
| State you set | GPIO39 output | SW6106 output enable |
|---|---|---|
pm.IDLE | not charging → 1, charging → 0 | off |
pm.VCC_OUTPUT | not charging → 1, charging → 0 | not charging → on, charging → off |
pm.USB_OUTPUT | always 0 | on |
pm.SLEEP | unchanged | unchanged |
| Any other integer | same as pm.IDLE | off |
Note the VCC_OUTPUT row: the output is actively turned off while charging. That is protection logic on the chip side, not a bug — which is why an external LED strip may go dark while USB is plugged in.
Common pitfalls
set_power_state()needspoll()before anything happens. A standalone program that forgetspoll()is the most common cause of "I set the state and nothing happened".init()is not optional. Every API depends on the I2C handle thatinit()creates; the order matters.sleep()really cuts the power. It is not a low-power standby: your program does not continue afterwards. Recovery means power-cycling the board.- Never call
sleep()from an exception path orfinallyblock. A Ctrl-C interrupt while debugging (Thonny, REPL) also runsfinally, and cutting power there leaves the board unresponsive with a dead serial port. Call it only on a deliberate shutdown path. get_charging_status()always returns 0 inUSB_OUTPUTstate. For the real charging status, set the state back toIDLEorVCC_OUTPUTfirst.refresh_power_percent()blocks for about 20 milliseconds. Do not refresh the battery level inside a button callback — leave it to the main loop.- pm and the IMU share the I2C bus (
GPIO1/GPIO2). Do not repurpose those pins and do not create a second I2C bus of your own.
More recipes
Enable the 5V output when your app starts
Put this at the top of your app's boot.py; the launcher's poll thread makes the state take effect within a second:
import pm
pm.init()
pm.set_power_state(pm.VCC_OUTPUT) # 5V supply for an external LED strip
Polling loop for standalone programs
import pm
import time
pm.init()
pm.set_power_state(pm.VCC_OUTPUT)
while True:
pm.poll() # once a second is enough
time.sleep(1)
Show battery level and charging status
import pm
percent = int(pm.get_4D_status())
charging = pm.get_charging_status()
print("{}% {}".format(percent, "charging" if charging else "on battery"))
Idle auto-sleep (never while charging)
import pm
import time
IDLE_LIMIT = 60 # sleep after 60 seconds idle
idle = 0
while True:
if pm.get_charging_status() == 1:
idle = 0 # charging neither counts down nor allows sleep
else:
idle += 1
if idle >= IDLE_LIMIT:
print(pm.sleep()) # after "go to sleep" the board is powered off
break
time.sleep(1)
Complete example
Firefly T1 apps live on the SD card under /sd/apps/<app-directory>/, with boot.py as the entry point. Drop the following into /sd/apps/my-power-app/boot.py: a centre short press reports the battery, a centre long press quits and hands the output back to the launcher.
import pm
import time
from button import Button
pm.init()
pm.set_power_state(pm.VCC_OUTPUT) # turn on the 5V output for the LED strip
buttons = Button()
running = True
def on_center_short():
print("Battery: {}% charging: {}".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:
# Light-effect rendering and other work goes here.
# The launcher's poll thread handles output switching, so no pm.poll() needed.
time.sleep(0.1)
# Return to idle before leaving so the launcher owns the output again.
# Note: do NOT call pm.sleep() here — that would power the board off.
pm.set_power_state(pm.IDLE)
buttons.deinit()
Related modules: D-pad buttons (button), WS2812 addressable LEDs (ws2812), and motion sensor (imu).
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| LED strip dark, no 5V measured | pm.VCC_OUTPUT was never set, or pm.poll() is never called standalone → call it once a second |
VCC_OUTPUT set but the output is off | Charging, and the output is deliberately disabled in that state → unplug USB and retry |
| Every API seems to do nothing | pm.init() was skipped → it is a prerequisite for all other calls |
get_charging_status() stuck at 0 while USB is plugged in | The state is pm.USB_OUTPUT, which always reports 0 → switch back to IDLE |
pm.sleep() returns "no sleep" | Charging, so the chip refuses to sleep → unplug USB and call it again |
| Board unresponsive, serial port dead | pm.sleep() was called on a Ctrl-C interrupt or exception path → call it only on a real shutdown path |
| Battery reading looks wrong | It is a raw, unrefreshed register value → call refresh_power_percent() first, then read get_4D_status() |
AI usage (coming soon)
Soon you will not have to tell IDLE from VCC_OUTPUT or remember where poll() belongs: describe the power and battery behaviour you want in plain language and the Agent will follow the API in this page to generate a complete program that runs on the Firefly T1.
For example, just tell it:
Turn on the 5V supply for the LED strip at startup, show the battery level on screen, sleep automatically after a minute of inactivity, and never sleep while charging.
It will combine pm and Button into a working program and place it on the SD card under /sd/apps/.
The entry link will go here. Once it is live, one click takes you straight to describing the app you want.