Classes
class	deep_sleep_gpio_wake
	Wakes the chip from deep sleep on levels of one or more pins. More...

struct	ext0_wake
	Wakes the chip when a single RTC-capable pin is at a level (EXT0). More...

class	ext1_wake
	Wakes the chip on levels of one or more RTC-capable pins (EXT1). More...

struct	gpio_wake
	Wakes the chip from light sleep when a digital pin is at a level. More...

struct	timer_wake
	Wakes the chip after a fixed duration of sleep. More...

Concepts
concept	wake_spec
	A wake-up source specification accepted by the sleep functions.

Enumerations
enum class	wakeup_source : int { ext0 = 2 , ext1 = 3 , timer = 4 , touchpad = 5 , ulp = 6 , gpio = 7 , uart = 8 , wifi = 9 , cocpu = 10 , cocpu_trap = 11 , bt = 12 , other = 13 }
	Wake-up sources and causes. More...

enum class	ext1_mode : int { any_low = 0 , any_high = 1 }
	EXT1 wake-up trigger mode. More...

enum class	deep_sleep_gpio_mode : int { wake_low = 0 , wake_high = 1 }
	Trigger level for deep-sleep GPIO wake-up. More...

Functions
std::string	to_string (wakeup_source source)
	Returns a string representation of a wake-up source.

template<wake_spec... Sources>
result< wakeup_source >	try_light_sleep (const Sources &... sources)
	Enters light sleep until one of the given wake-up sources triggers.

template<wake_spec... Sources>
wakeup_source	light_sleep (const Sources &... sources)
	Enters light sleep until one of the given wake-up sources triggers.

wakeup_source	light_sleep_for (std::chrono::microseconds duration)
	Enters light sleep for a fixed duration.

result< wakeup_source >	try_light_sleep_for (std::chrono::microseconds duration)
	Enters light sleep for a fixed duration.

template<wake_spec First, wake_spec... Rest>
result< void >	try_deep_sleep (const First &first, const Rest &... rest)
	Enters deep sleep until one of the given wake-up sources triggers.

template<wake_spec First, wake_spec... Rest>
void	deep_sleep (const First &first, const Rest &... rest)
	Enters deep sleep until one of the given wake-up sources triggers.

void	deep_sleep () noexcept
	Enters deep sleep until a previously armed wake-up source triggers.

void	deep_sleep (std::chrono::microseconds duration) noexcept
	Enters deep sleep for a fixed duration.

std::optional< wakeup_source >	wakeup_cause () noexcept
	Returns the cause of the most recent wake from sleep.

uint64_t	ext1_wakeup_status () noexcept
	Returns the pins that triggered the most recent EXT1 wake.

template<wake_spec Source>
void	enable_wakeup (const Source &source)
	Arms a wake-up source persistently.

template<wake_spec Source>
result< void >	try_enable_wakeup (const Source &source)
	Arms a wake-up source persistently.

void	disable_wakeup_source (wakeup_source source)
	Disarms a previously armed wake-up source.

void	disable_all_wakeup_sources ()
	Disarms every armed wake-up source.

result< void >	try_disable_wakeup_source (wakeup_source source)
	Disarms a previously armed wake-up source.

result< void >	try_disable_all_wakeup_sources ()
	Disarms every armed wake-up source.

Enumeration Type Documentation

◆ deep_sleep_gpio_mode

enum class idfxx::sleep::deep_sleep_gpio_mode : int

strong

Trigger level for deep-sleep GPIO wake-up.

Enumerator
wake_low	Wake when a selected pin goes low.
wake_high	Wake when a selected pin goes high.

Definition at line 222 of file sleep.hpp.

◆ ext1_mode

enum class idfxx::sleep::ext1_mode : int

strong

EXT1 wake-up trigger mode.

The low trigger is chip-specific, and only the enumerator matching the hardware is defined for a given target: the original ESP32 wakes only when all selected pins are low (ext1_mode::all_low), whereas every other EXT1-capable chip wakes when any selected pin is low (ext1_mode::any_low). Selecting the wrong one for the target is a compile error rather than a silent change in behaviour; portable code picks the enumerator under #if CONFIG_IDF_TARGET_ESP32. For a single wake pin the two are equivalent.

Enumerator
any_low	Wake when any selected pin goes low.
any_high	Wake when any selected pin goes high.

Definition at line 161 of file sleep.hpp.

◆ wakeup_source

enum class idfxx::sleep::wakeup_source : int

strong

Wake-up sources and causes.

Identifies what woke the chip from sleep (see wakeup_cause), and selects a configured source to disable (see try_disable_wakeup_source).

Enumerator
ext0	Level on a single RTC-capable pin (EXT0).
ext1	Level on one or more RTC-capable pins (EXT1).
timer	Sleep timer expired.
touchpad	Touch sensor.
ulp	ULP coprocessor program.
gpio	Digital GPIO level (light sleep; also deep sleep on chips without EXT0/EXT1).
uart	UART activity (light sleep only).
wifi	Wi-Fi beacon (light sleep only).
cocpu	ULP-RISC-V coprocessor interrupt.
cocpu_trap	ULP-RISC-V coprocessor crash.
bt	Bluetooth activity (light sleep only).
other	A source not represented in this enumeration (chip-specific).

Definition at line 54 of file sleep.hpp.

Function Documentation

◆ deep_sleep() [1/3]

void idfxx::sleep::deep_sleep ( )

noexcept

Enters deep sleep until a previously armed wake-up source triggers.

Powers down the CPU and most peripherals, waking on the sources armed with the enable_* functions. Waking restarts the application from the beginning; use wakeup_cause to detect the wake and its source after the restart.

Does not return: with no armed (or no functioning) wake-up source the chip simply sleeps until reset.

◆ deep_sleep() [2/3]

template<wake_spec First, wake_spec... Rest>

void idfxx::sleep::deep_sleep	(	const First &	first,
		const Rest &...	rest
	)

Enters deep sleep until one of the given wake-up sources triggers.

Arms each source, then powers down the CPU and most peripherals. Waking restarts the application from the beginning; use wakeup_cause to detect the wake and its source after the restart.

Template Parameters

First	First wake-up source specification type (see wake_spec).
Rest	Additional wake-up source specification types.

Parameters

first	The source that may wake the chip.
rest	Additional sources that may wake the chip.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if a source is invalid; otherwise does not return.

idfxx::sleep::deep_sleep(
    // The original ESP32 uses ext1_mode::all_low instead (see ext1_mode).
    idfxx::sleep::ext1_wake{{button}, idfxx::sleep::ext1_mode::any_low},
    idfxx::sleep::timer_wake{15min});

Definition at line 472 of file sleep.hpp.

References try_deep_sleep(), and idfxx::unwrap().

◆ deep_sleep() [3/3]

void idfxx::sleep::deep_sleep ( std::chrono::microseconds duration )

noexcept

Enters deep sleep for a fixed duration.

Equivalent to enabling a timer wake-up for duration and calling deep_sleep(). Any other previously armed wake-up sources remain active and may wake the chip sooner.

Powers down the CPU and most peripherals. Waking restarts the application from the beginning; use wakeup_cause to detect the wake and its source after the restart.

Parameters

duration Time to sleep before waking. Negative values are treated as zero.

◆ disable_all_wakeup_sources()

void idfxx::sleep::disable_all_wakeup_sources ( )

Disarms every armed wake-up source.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ disable_wakeup_source()

void idfxx::sleep::disable_wakeup_source ( wakeup_source source )

Disarms a previously armed wake-up source.

Parameters

source The source to disarm.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ enable_wakeup()

template<wake_spec Source>

void idfxx::sleep::enable_wakeup ( const Source & source )

Arms a wake-up source persistently.

The source stays armed across any number of sleeps until disarmed with disable_wakeup_source. Use this instead of passing sources to the sleep functions when the same sources are reused across many sleep cycles.

Template Parameters

Source Wake-up source specification type (see wake_spec).

Parameters

source The source that may wake the chip.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if the source is invalid.

Definition at line 592 of file sleep.hpp.

References idfxx::unwrap().

◆ ext1_wakeup_status()

uint64_t idfxx::sleep::ext1_wakeup_status ( )

noexcept

Returns the pins that triggered the most recent EXT1 wake.

Returns: Bit mask of GPIO numbers (bit n set means GPIO n triggered the wake). Zero if the last wake was not caused by EXT1.

Note: Only available on chips with EXT1 wake-up support (SOC_PM_SUPPORT_EXT1_WAKEUP).

◆ light_sleep()

template<wake_spec... Sources>

wakeup_source idfxx::sleep::light_sleep ( const Sources &... sources )

Enters light sleep until one of the given wake-up sources triggers.

Arms each source, sleeps, then disarms them again before returning. The CPU is suspended and execution resumes here on wake. Peripheral and memory state is retained, but digital interrupts (including GPIO edge interrupts) are not delivered while sleeping — re-check any interrupt-driven state after waking.

With no arguments, sleeps on the wake-up sources previously armed with the enable_* functions. Such sources stay armed afterwards, unless a source of the same kind (or the same pin, for pin-level sources) is passed here, in which case it is replaced for this sleep and disarmed on return.

Template Parameters

Sources Wake-up source specification types (see wake_spec).

Parameters

sources The sources that may wake the chip.

Returns: The source that woke the chip.

Note: At least one wake-up source must be armed, or sleep is rejected.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if a source is invalid or sleep is rejected (e.g. a wake-up source triggered before sleep was entered).

auto cause = idfxx::sleep::light_sleep(
    idfxx::sleep::timer_wake{30s},
    idfxx::sleep::gpio_wake{button, idfxx::gpio::level::low});
if (cause == idfxx::sleep::wakeup_source::gpio) {
    // button pressed
}

Definition at line 368 of file sleep.hpp.

References try_light_sleep(), and idfxx::unwrap().

◆ light_sleep_for()

wakeup_source idfxx::sleep::light_sleep_for ( std::chrono::microseconds duration )

Enters light sleep for a fixed duration.

Equivalent to light_sleep(timer_wake{duration}) — a low-power counterpart to std::this_thread::sleep_for. Wake-up sources previously armed with the enable_* functions may wake the chip sooner.

Parameters

duration Time to sleep before waking.

Returns: The source that woke the chip (normally wakeup_source::timer).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if the duration is invalid or sleep is rejected.

◆ to_string()

std::string idfxx::sleep::to_string ( wakeup_source source )

Returns a string representation of a wake-up source.

Parameters

source The wake-up source to convert.

Returns: The source name, e.g. "timer" or "gpio", or "unknown(N)" for an unrecognized value.

◆ try_deep_sleep()

template<wake_spec First, wake_spec... Rest>

result< void > idfxx::sleep::try_deep_sleep	(	const First &	first,
		const Rest &...	rest
	)

Enters deep sleep until one of the given wake-up sources triggers.

Arms each source, then powers down the CPU and most peripherals. Waking restarts the application from the beginning; use wakeup_cause to detect the wake and its source after the restart.

Returns only on failure — on success the chip is powered down and the call never returns.

Template Parameters

First	First wake-up source specification type (see wake_spec).
Rest	Additional wake-up source specification types.

Parameters

first	The source that may wake the chip.
rest	Additional sources that may wake the chip.

Returns: The error that prevented entering sleep.

Return values

idfxx::errc::invalid_arg if a source is invalid (e.g. an unconnected pin or a pin that cannot wake the chip from deep sleep).

Definition at line 498 of file sleep.hpp.

References idfxx::error().

Referenced by deep_sleep().

◆ try_disable_all_wakeup_sources()

result< void > idfxx::sleep::try_disable_all_wakeup_sources ( )

Disarms every armed wake-up source.

Returns: Success, or an error.

◆ try_disable_wakeup_source()

result< void > idfxx::sleep::try_disable_wakeup_source ( wakeup_source source )

Disarms a previously armed wake-up source.

Parameters

source The source to disarm.

Returns: Success, or an error.

Return values

idfxx::errc::invalid_arg	if the source cannot be disarmed (wakeup_source::other).
idfxx::errc::invalid_state	if the source was not armed.

◆ try_enable_wakeup()

template<wake_spec Source>

result< void > idfxx::sleep::try_enable_wakeup ( const Source & source )

Arms a wake-up source persistently.

The source stays armed across any number of sleeps until disarmed with try_disable_wakeup_source. Use this instead of passing sources to the sleep functions when the same sources are reused across many sleep cycles.

Template Parameters

Source Wake-up source specification type (see wake_spec).

Parameters

source The source that may wake the chip.

Returns: Success, or an error.

Return values

idfxx::errc::invalid_arg if the source is invalid (e.g. an unconnected pin or a negative duration).

Definition at line 612 of file sleep.hpp.

◆ try_light_sleep()

template<wake_spec... Sources>

result< wakeup_source > idfxx::sleep::try_light_sleep ( const Sources &... sources )

Enters light sleep until one of the given wake-up sources triggers.

Arms each source, sleeps, then disarms them again before returning. The CPU is suspended and execution resumes here on wake. Peripheral and memory state is retained, but digital interrupts (including GPIO edge interrupts) are not delivered while sleeping — re-check any interrupt-driven state after waking.

With no arguments, sleeps on the wake-up sources previously armed with the try_enable_* functions. Such sources stay armed afterwards, unless a source of the same kind (or the same pin, for pin-level sources) is passed here, in which case it is replaced for this sleep and disarmed on return.

Template Parameters

Sources Wake-up source specification types (see wake_spec).

Parameters

sources The sources that may wake the chip.

Returns: The source that woke the chip, or an error.

Return values

idfxx::errc::invalid_arg	if a source is invalid (e.g. an unconnected pin, a negative duration, or a timer too short to enter sleep at all).
idfxx::errc::invalid_state	if sleep was rejected (e.g. a wake-up source triggered before sleep was entered).

Note: At least one wake-up source must be armed, or sleep is rejected.

Definition at line 399 of file sleep.hpp.

References idfxx::error().

Referenced by light_sleep().

◆ try_light_sleep_for()

result< wakeup_source > idfxx::sleep::try_light_sleep_for ( std::chrono::microseconds duration )

Enters light sleep for a fixed duration.

Equivalent to try_light_sleep(timer_wake{duration}) — a low-power counterpart to std::this_thread::sleep_for. Wake-up sources previously armed with the try_enable_* functions may wake the chip sooner.

Parameters

duration Time to sleep before waking.

Returns: The source that woke the chip (normally wakeup_source::timer), or an error.

Return values

idfxx::errc::invalid_arg	if the duration is negative or too short to enter sleep at all.
idfxx::errc::invalid_state	if sleep was rejected (e.g. a wake-up source triggered before sleep was entered).

◆ wakeup_cause()

std::optional< wakeup_source > idfxx::sleep::wakeup_cause ( )

noexcept

Returns the cause of the most recent wake from sleep.

After waking from deep sleep (which restarts the application), this identifies the wake-up source. Returns std::nullopt when the chip did not wake from sleep (e.g. cold boot or reset).

Returns: The source that woke the chip, or std::nullopt.

Note: If several sources triggered in the same instant, the lowest-numbered one is reported.

if (auto cause = idfxx::sleep::wakeup_cause()) {
    // woke from sleep; *cause identifies the source
} else {
    // cold boot
}

Classes

Concepts

Enumerations

Functions

Enumeration Type Documentation

◆ deep_sleep_gpio_mode

◆ ext1_mode

◆ wakeup_source

Function Documentation

◆ deep_sleep() [1/3]

◆ deep_sleep() [2/3]

◆ deep_sleep() [3/3]

◆ disable_all_wakeup_sources()

◆ disable_wakeup_source()

◆ enable_wakeup()

◆ ext1_wakeup_status()

◆ light_sleep()

◆ light_sleep_for()

◆ to_string()

◆ try_deep_sleep()

◆ try_disable_all_wakeup_sources()

◆ try_disable_wakeup_source()

◆ try_enable_wakeup()

◆ try_light_sleep()

◆ try_light_sleep_for()

◆ wakeup_cause()