Power service

Battery state, charge detection, low-battery policy, and power on/off. More...

Collaboration diagram for Power service:

Files
file	components/services/power/power.c
	Power service implementation: fuel-gauge snapshot, charge/level policy, on/off.

Data Structures
struct	power_state_t
	Cached battery/charge snapshot, refreshed by power_tick(). More...

Typedefs
typedef void(*	power_shutdown_hook_t) (void)
	Callback run by power_shutdown() before the rail is cut (e.g. amp+DAC power-down).

Enumerations
enum	power_level_t { POWER_LEVEL_NORMAL = 0 , POWER_LEVEL_LOW , POWER_LEVEL_CRITICAL }
	Battery charge level band, derived from state of charge. More...
enum	power_usb_route_t { POWER_USB_DATA = 0 , POWER_USB_CHARGE }
	USB-C mux routing through the PI3USB221AZUAEX (PIN_USB_DIR). More...
enum	power_off_cause_t { POWER_OFF_POWER_LOSS = 0 , POWER_OFF_CLEAN , POWER_OFF_CRASH }
	How the previous session ended, reconstructed at boot. More...

Functions
void	power_self_hold (void)
	Latch the regulator on by driving EnableReg high.
void	power_tick (void)
	Refresh the cached battery state and apply the low-battery policy.
void	power_get_state (power_state_t *out)
	Copy the latest cached battery snapshot.
void	power_set_usb_route (power_usb_route_t route)
	Route the USB-C mux to data or charge.
power_usb_route_t	power_get_usb_route (void)
	The route currently driven onto PIN_USB_DIR (for diagnostics).
void	power_usb_autoroute_start (void)
	USB mux hand-off: charger first, then console.
void	power_set_low_batt_shutdown (bool enable)
	Enable or disable the built-in critical-battery auto-shutdown (default enabled).
bool	power_soc_at_shutdown (float soc_pct)
	True when this SoC is at or below the graceful auto-off threshold.
void	power_set_shutdown_hook (power_shutdown_hook_t hook)
	Register a callback to run at the start of power_shutdown().
void	power_shutdown (void) __attribute__((noreturn))
	Run the shutdown hook (if any), release EnableReg, and power the board off.
void	power_boot_off_check (void)
	Classify how the previous session ended (call once at boot, after NVS is up).
void	power_coredump_export (void)
	Copy a pending panic core dump from flash to the SD card, then erase it.
power_off_cause_t	power_last_off_cause (void)
	How the previous session ended. Valid after power_boot_off_check().
const char *	power_last_crash_task (void)
	Faulting task name when the cause is POWER_OFF_CRASH ("" otherwise).
uint32_t	power_last_crash_pc (void)
	Faulting program counter when the cause is POWER_OFF_CRASH (0 otherwise).

Power-saving timeouts (user preferences, persisted in NVS)
Idle durations, in milliseconds, driving the two power-saving policies. Both are cached on first read (no flash access on the hot paths that poll them) and 0 means the policy is disabled ("Never"). Setters persist the new value immediately.
uint32_t	power_get_sleep_ms (void)
	Idle time before the screen blanks (UI task). 0 = never sleep.
void	power_set_sleep_ms (uint32_t ms)
	Set and persist the screen-sleep timeout.
uint32_t	power_get_poweroff_ms (void)
	Idle time before the board auto powers off (maintenance task). 0 = never.
void	power_set_poweroff_ms (uint32_t ms)
	Set and persist the auto power-off timeout.

Detailed Description

Battery state, charge detection, low-battery policy, and power on/off.

Typedef Documentation

power_shutdown_hook_t

typedef void(* power_shutdown_hook_t) (void)

Callback run by power_shutdown() before the rail is cut (e.g. amp+DAC power-down).

Enumeration Type Documentation

power_level_t

enum power_level_t

Battery charge level band, derived from state of charge.

Enumerator
POWER_LEVEL_NORMAL	above the low threshold
POWER_LEVEL_LOW	at or below the low threshold (warn the user)
POWER_LEVEL_CRITICAL	at or below the critical threshold (red warning; the graceful shutdown fires lower, see power_soc_at_shutdown())

power_off_cause_t

enum power_off_cause_t

How the previous session ended, reconstructed at boot.

Enumerator
POWER_OFF_POWER_LOSS	no marker, no core dump: the rail died without warning (battery connector, supervisor, brownout — or first boot)
POWER_OFF_CLEAN	power_shutdown() ran (user off, critical battery, autonomy end)
POWER_OFF_CRASH	a panic core dump was found in flash

power_usb_route_t

enum power_usb_route_t

USB-C mux routing through the PI3USB221AZUAEX (PIN_USB_DIR).

Enumerator
POWER_USB_DATA	LOW: route D+/D- to the CP2102N (console / flash).
POWER_USB_CHARGE	HIGH: route to the MAX77757 charger (USB source current detection).

Function Documentation

power_boot_off_check()

void power_boot_off_check

(

void

)

Classify how the previous session ended (call once at boot, after NVS is up).

Consumes (reads + erases) the clean-shutdown marker power_shutdown() left, and checks the coredump flash partition for a panic dump. Erasing the marker here keeps a stale flag from masking the next crash. The core dump itself is NOT erased here: it stays in flash until power_coredump_export() copies it to the SD card.

power_coredump_export()

void power_coredump_export

(

void

)

Copy a pending panic core dump from flash to the SD card, then erase it.

No-op when the coredump partition holds no valid image. When the SD card is not mounted the dump is left in flash untouched, so a later call — the next boot, or the hot-plug mount in the maintenance task — can still export it. Once the card is available the flash image is erased even if the file write failed: a stale dump would label every later power loss as a crash (see power_boot_off_check). Analyze the file with: espcoredump.py info_corefile -t raw -c core_NNN.bin <app.elf>

power_get_poweroff_ms()

uint32_t power_get_poweroff_ms

(

void

)

Idle time before the board auto powers off (maintenance task). 0 = never.

power_get_sleep_ms()

uint32_t power_get_sleep_ms

(

void

)

Idle time before the screen blanks (UI task). 0 = never sleep.

power_get_state()

void power_get_state

(

power_state_t *

out

)

Copy the latest cached battery snapshot.

Parameters

[out]

out

Receives the snapshot. Single writer (maintenance task), so a concurrent read can at worst see one stale field — cosmetic for the UI.

power_get_usb_route()

power_usb_route_t power_get_usb_route

(

void

)

The route currently driven onto PIN_USB_DIR (for diagnostics).

Reports POWER_USB_DATA before the first power_set_usb_route() call, when the pin is not driven yet — boot calls it immediately, so only the very first instants of bring-up lie.

power_last_crash_pc()

uint32_t power_last_crash_pc

(

void

)

Faulting program counter when the cause is POWER_OFF_CRASH (0 otherwise).

power_last_crash_task()

const char * power_last_crash_task

(

void

)

Faulting task name when the cause is POWER_OFF_CRASH ("" otherwise).

power_last_off_cause()

power_off_cause_t power_last_off_cause

(

void

)

How the previous session ended. Valid after power_boot_off_check().

power_self_hold()

void power_self_hold

(

void

)

Latch the regulator on by driving EnableReg high.

The rail is only held by USB / the power button at boot; the firmware must take over the hold immediately or releasing them cuts power. Call this first thing at startup, before any other bring-up. Preloads the output high before enabling the driver so the pin never drives low on its way up.

power_set_low_batt_shutdown()

void power_set_low_batt_shutdown

(

bool

enable

)

Enable or disable the built-in critical-battery auto-shutdown (default enabled).

The autonomy test disables it while a run is in progress so the service can detect the critical level itself, write its final log, and then call power_shutdown() in order. Restore it (true) when the run ends or is cancelled.

Parameters

enable

true to keep the built-in graceful shutdown, false to suspend it.

power_set_poweroff_ms()

void power_set_poweroff_ms

(

uint32_t

ms

)

Set and persist the auto power-off timeout.

See also

power_get_poweroff_ms

power_set_shutdown_hook()

void power_set_shutdown_hook

(

power_shutdown_hook_t

hook

)

Register a callback to run at the start of power_shutdown().

Lets a subsystem clean up before the rail drops without power having to know the details — e.g. the audio service registers an amp-off-then-DAC-off sequence here, keeping the mute/shutdown ordering in the audio service. Pass NULL to clear.

power_set_sleep_ms()

void power_set_sleep_ms

(

uint32_t

ms

)

Set and persist the screen-sleep timeout.

See also

power_get_sleep_ms

power_set_usb_route()

void power_set_usb_route

(

power_usb_route_t

route

)

Route the USB-C mux to data or charge.

Configures PIN_USB_DIR as an output and drives it. Glitch-free: sets the level before enabling the driver.

power_shutdown()

void power_shutdown

(

void

)

Run the shutdown hook (if any), release EnableReg, and power the board off.

Drives PIN_REG_EN low; the rail collapses within the regulator's turn-off time and this never returns. If USB is still latching the regulator on, power stays up. Persists a "clean shutdown" marker in NVS just before the rail drops, so the next boot can tell an intentional off from a crash or hard power loss (the EnableReg scheme makes every reset look like ESP_RST_POWERON).

See also

power_last_off_cause

power_soc_at_shutdown()

bool power_soc_at_shutdown

(

float

soc_pct

)

True when this SoC is at or below the graceful auto-off threshold.

The threshold (near VEmpty) is decoupled from the CRITICAL red-flag band so the UI can warn the user well before the device actually powers off. Single source of truth shared by the built-in shutdown and the autonomy test, which mirror the same end condition.

Parameters

soc_pct

Reported state of charge, %.

Returns

true if the cell is near-empty enough to power off.

power_tick()

void power_tick

(

void

)

Refresh the cached battery state and apply the low-battery policy.

Reads the fuel gauge and the INOKB input, updates the snapshot, and — if the cell is near-empty (power_soc_at_shutdown()) while discharging on battery — calls power_shutdown(). A failed gauge read marks the snapshot invalid and takes no action (fail-safe). Intended to be called from the maintenance task, not at interrupt time.

power_usb_autoroute_start()

void power_usb_autoroute_start

(

void

)

USB mux hand-off: charger first, then console.

Routes the USB-C data lines to the MAX77757 (POWER_USB_CHARGE) so the charger can run its BC1.2 source detection, then spawns a short-lived task that hands the lines to the CP2102N (POWER_USB_DATA) once INOKB asserts (valid input) and the detection has had time to finish, or after a safety timeout if no source ever shows up. The task self-deletes when done.

Call once early in boot; power_tick() then re-arms it on every plug event, since BC1.2 needs the data lines and would otherwise leave a legacy charger capped at its 500 mA default. Calls made while a hand-off is already running are ignored. Requires gpio_expander_init() (INOKB).

The console loses its USB device for the duration of each hand-off.