Skip to main content

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.

SW6106 over I2C

Device address 0x3C, SDA=GPIO2, SCL=GPIO1, sharing the bus with the IMU.

Four power states

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

poll() does the work

set_power_state() only records the state; the output actually switches inside pm.poll().

Pin and hardware parameters​

ItemValue
Power chipSW6106
BusI2C (shared with the IMU and other modules)
Device address0x3C
SDA / SCLGPIO2 / GPIO1 at 100 kHz
Output control pinsGPIO39 (USB supply output), GPIO21 (3.3V supply control) — both open-drain
Charging status bitbit4 of register 0x11
Battery-level register0x4D (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​

ConstantValueTypical use
pm.IDLE0Idle. Used by the launcher while browsing the app list
pm.VCC_OUTPUT1VCC output. Use this when your app drives an external LED strip
pm.USB_OUTPUT2Force the output on; unused by the launcher in current firmware
pm.SLEEP3Sleep. 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 initialized flag 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)
ArgumentTypeValues
stateintpm.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 valueMeaning
"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 valueMeaning
0Not charging (running on battery)
1Charging

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 setGPIO39 outputSW6106 output enable
pm.IDLEnot charging → 1, charging → 0off
pm.VCC_OUTPUTnot charging → 1, charging → 0not charging → on, charging → off
pm.USB_OUTPUTalways 0on
pm.SLEEPunchangedunchanged
Any other integersame as pm.IDLEoff

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​

  1. set_power_state() needs poll() before anything happens. A standalone program that forgets poll() is the most common cause of "I set the state and nothing happened".
  2. init() is not optional. Every API depends on the I2C handle that init() creates; the order matters.
  3. sleep() really cuts the power. It is not a low-power standby: your program does not continue afterwards. Recovery means power-cycling the board.
  4. Never call sleep() from an exception path or finally block. A Ctrl-C interrupt while debugging (Thonny, REPL) also runs finally, and cutting power there leaves the board unresponsive with a dead serial port. Call it only on a deliberate shutdown path.
  5. get_charging_status() always returns 0 in USB_OUTPUT state. For the real charging status, set the state back to IDLE or VCC_OUTPUT first.
  6. refresh_power_percent() blocks for about 20 milliseconds. Do not refresh the battery level inside a button callback — leave it to the main loop.
  7. 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​

SymptomCause / fix
LED strip dark, no 5V measuredpm.VCC_OUTPUT was never set, or pm.poll() is never called standalone → call it once a second
VCC_OUTPUT set but the output is offCharging, and the output is deliberately disabled in that state → unplug USB and retry
Every API seems to do nothingpm.init() was skipped → it is a prerequisite for all other calls
get_charging_status() stuck at 0 while USB is plugged inThe 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 deadpm.sleep() was called on a Ctrl-C interrupt or exception path → call it only on a real shutdown path
Battery reading looks wrongIt 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/.

Agent entry (coming soon)

The entry link will go here. Once it is live, one click takes you straight to describing the app you want.