power.h File Reference

Power service: battery state, charge detection, and board power on/off. More...

#include "esp_err.h"
#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

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

Power service: battery state, charge detection, and board power on/off.

Owns the energy domain of the board:

• EnableReg self-hold (PIN_REG_EN): keep the regulator latched on at boot, and release it on power_shutdown().
• battery snapshot from the MAX17260 fuel gauge (state of charge, voltage, current) plus a derived charge/level state for the UI.
• low-battery policy: a graceful auto-shutdown when the cell is critically low and not being fed.
• USB-C data/charge mux routing (PI3USB221AZUAEX via PIN_USB_DIR).

This service owns no long-lived task: the maintenance task calls power_tick() periodically (see services/maintenance), and the only task it ever spawns is the short-lived USB mux hand-off, which self-deletes. The fuel gauge and GPIO expander drivers must already be initialised before power_tick() runs.

Note

Développé avec l'assistance de Claude Opus 4.8 (Anthropic), sous la direction de Y. Dos Santos : spécification, revue et validation sur cible par l'auteur.