A GPIO pin. More...

Classes
struct	config
	Configuration parameters for idfxx::gpio_config. More...

class	isr_handle
	Handle to a registered ISR handler. More...

class	unique_isr_handle
	RAII handle for ISR registration that removes the handler on destruction. More...

Public Types
enum class	level : int { low = 0 , high = 1 }
	GPIO output/input level. More...

enum class	mode : int { disable = GPIO_MODE_DISABLE , input = GPIO_MODE_INPUT , output = GPIO_MODE_OUTPUT , output_od = GPIO_MODE_OUTPUT_OD , input_output_od = GPIO_MODE_INPUT_OUTPUT_OD , input_output = GPIO_MODE_INPUT_OUTPUT }
	GPIO direction mode. More...

enum class	pull_mode : int { pullup = GPIO_PULLUP_ONLY , pulldown = GPIO_PULLDOWN_ONLY , pullup_pulldown = GPIO_PULLUP_PULLDOWN , floating = GPIO_FLOATING }
	Pull resistor configuration. More...

enum class	drive_cap : int { cap_0 = GPIO_DRIVE_CAP_0 , cap_1 = GPIO_DRIVE_CAP_1 , cap_2 = GPIO_DRIVE_CAP_2 , cap_default = GPIO_DRIVE_CAP_DEFAULT , cap_3 = GPIO_DRIVE_CAP_3 }
	Pin drive capability (output strength). More...

enum class	intr_type : int { disable = GPIO_INTR_DISABLE , posedge = GPIO_INTR_POSEDGE , negedge = GPIO_INTR_NEGEDGE , anyedge = GPIO_INTR_ANYEDGE , low_level = GPIO_INTR_LOW_LEVEL , high_level = GPIO_INTR_HIGH_LEVEL }
	Interrupt trigger type. More...

enum class	hys_ctrl_mode : int { soft_disable = GPIO_HYS_CTRL_SOFT_DISABLE , soft_enable = GPIO_HYS_CTRL_SOFT_ENABLE }
	Hysteresis control mode. More...

Public Member Functions
constexpr	gpio ()
	Constructs a GPIO representing "not connected".

	gpio (int num)
	Constructs a validated GPIO pin.

	gpio (const gpio &)=default

	gpio (gpio &&)=default

gpio &	operator= (const gpio &)=default

gpio &	operator= (gpio &&)=default

constexpr bool	operator== (const gpio &) const noexcept=default
	Compares two GPIO pins for equality.

constexpr bool	is_connected () const
	Returns true if this is a valid GPIO pin.

constexpr bool	is_output_capable () const
	Returns true if this gpio supports output mode.

constexpr bool	is_digital_io_pin_capable () const
	Returns true if this gpio is a valid digital I/O pin.

constexpr int	num () const
	Returns the underlying GPIO pin number.

constexpr gpio_num_t	idf_num () const
	Returns the underlying ESP-IDF GPIO number.

void	reset ()
	Resets the gpio to default state.

void	set_direction (enum mode mode)
	Sets the GPIO direction mode.

void	set_pull_mode (enum pull_mode mode)
	Sets the pull resistor mode.

void	pullup_enable ()
	Enables the internal pull-up resistor.

void	pullup_disable ()
	Disables the internal pull-up resistor.

void	pulldown_enable ()
	Enables the internal pull-down resistor.

void	pulldown_disable ()
	Disables the internal pull-down resistor.

result< void >	try_set_direction (enum mode mode)
	Sets the GPIO direction mode.

void	input_enable ()
	Enables input on this gpio.

result< void >	try_set_pull_mode (enum pull_mode mode)
	Sets the pull resistor mode.

result< void >	try_pullup_enable ()
	Enables the internal pull-up resistor.

result< void >	try_pullup_disable ()
	Disables the internal pull-up resistor.

result< void >	try_pulldown_enable ()
	Enables the internal pull-down resistor.

result< void >	try_pulldown_disable ()
	Disables the internal pull-down resistor.

void	set_level (enum level level)
	Sets the output level.

enum level	get_level () const
	Reads the current input level.

void	toggle_level ()
	Toggles the output level.

void	set_drive_capability (enum drive_cap strength)
	Sets the gpio drive capability.

enum drive_cap	get_drive_capability () const
	Gets the current drive capability.

result< void >	try_set_drive_capability (enum drive_cap strength)
	Sets the gpio drive capability.

result< drive_cap >	try_get_drive_capability () const
	Gets the current drive capability.

isr_handle	isr_handler_add (std::move_only_function< void() const > handler)
	Adds an ISR handler for this gpio.

isr_handle	isr_handler_add (void(fn)(void ), void *arg)
	Adds an ISR handler for this gpio.

void	isr_handler_remove (isr_handle handle)
	Removes a specific ISR handler.

result< isr_handle >	try_isr_handler_add (std::move_only_function< void() const > handler)
	Adds an ISR handler for this gpio.

result< isr_handle >	try_isr_handler_add (void(fn)(void ), void *arg)
	Adds an ISR handler for this gpio.

result< void >	try_isr_handler_remove (isr_handle handle)
	Removes a specific ISR handler.

void	isr_handler_remove_all ()
	Removes all ISR handlers for this gpio.

void	set_intr_type (enum intr_type intr_type)
	Sets the interrupt trigger type.

void	intr_enable ()
	Enables interrupts for this gpio.

void	intr_disable ()
	Disables interrupts for this gpio.

void	wakeup_enable (enum intr_type intr_type)
	Enables GPIO wake-up from light sleep.

void	wakeup_disable ()
	Disables GPIO wake-up.

result< void >	try_wakeup_enable (enum intr_type intr_type)
	Enables GPIO wake-up from light sleep.

result< void >	try_wakeup_disable ()
	Disables GPIO wake-up.

void	hold_enable ()
	Enables gpio hold function.

void	hold_disable ()
	Disables gpio hold function.

result< void >	try_hold_enable ()
	Enables gpio hold function.

result< void >	try_hold_disable ()
	Disables gpio hold function.

void	sleep_sel_enable ()
	Enables SLP_SEL to change GPIO status automatically in light sleep.

void	sleep_sel_disable ()
	Disables SLP_SEL to change GPIO status automatically in light sleep.

void	sleep_set_direction (enum mode mode)
	Sets GPIO direction at sleep.

result< void >	try_sleep_set_direction (enum mode mode)
	Sets GPIO direction at sleep.

void	sleep_set_pull_mode (enum pull_mode pull)
	Sets pull resistor mode at sleep.

Static Public Member Functions
static result< gpio >	make (int num)
	Creates a validated GPIO pin.

static constexpr gpio	nc ()
	Returns a GPIO representing "not connected".

static constexpr gpio	max ()
	Returns a GPIO for the highest valid pin number.

static void	install_isr_service (idfxx::intr_levels levels=intr_level_lowmed, idfxx::flags< intr_flag > flags={})
	Installs the GPIO ISR service for per-gpio interrupt handlers.

static void	install_isr_service (idfxx::flags< intr_flag > flags)
	Installs the GPIO ISR service with default priority levels.

static result< void >	try_install_isr_service (idfxx::intr_levels levels=intr_level_lowmed, idfxx::flags< intr_flag > flags={})
	Installs the GPIO ISR service for per-gpio interrupt handlers.

static result< void >	try_install_isr_service (idfxx::flags< intr_flag > flags)
	Installs the GPIO ISR service with default priority levels.

static void	uninstall_isr_service ()
	Uninstalls the GPIO ISR service, freeing related resources.

static void	deep_sleep_hold_enable ()
	Enables hold for all digital GPIOs during deep sleep.

static void	deep_sleep_hold_disable ()
	Disables hold for all digital GPIOs during deep sleep.

Friends
template<int N>
struct	gpio_constant

Detailed Description

A GPIO pin.

Lightweight, non-owning GPIO pin identifier. Provides type-safe configuration and supports both exception-throwing and result-returning error handling.

Construction is validated: only valid GPIO numbers (or nc) are allowed. Use gpio::make() for result-based construction, or the throwing constructor when exceptions are enabled.

For interrupt handling, first install the ISR service, then add handlers:

idfxx::gpio::install_isr_service();
auto button = idfxx::gpio_28;
button.set_direction(idfxx::gpio::mode::input);
button.set_intr_type(idfxx::gpio::intr_type::negedge);
auto handle = button.isr_handler_add([]() { ... });
button.intr_enable();

Definition at line 61 of file gpio.hpp.

Member Enumeration Documentation

◆ drive_cap

enum class idfxx::gpio::drive_cap : int

strong

Pin drive capability (output strength).

Enumerator
cap_0	Weak drive capability.
cap_1	Stronger drive capability.
cap_2	Medium drive capability.
cap_default	Medium drive capability.
cap_3	Strongest drive capability.

Definition at line 91 of file gpio.hpp.

◆ hys_ctrl_mode

enum class idfxx::gpio::hys_ctrl_mode : int

strong

Hysteresis control mode.

Enumerator
soft_disable	Pin input hysteresis disable by software.
soft_enable	Pin input hysteresis enable by software.

Definition at line 111 of file gpio.hpp.

◆ intr_type

enum class idfxx::gpio::intr_type : int

strong

Interrupt trigger type.

Enumerator
disable	Disable GPIO interrupt.
posedge	Rising edge.
negedge	Falling edge.
anyedge	Both rising and falling edge.
low_level	Input low level trigger.
high_level	Input high level trigger.

Definition at line 100 of file gpio.hpp.

◆ level

enum class idfxx::gpio::level : int

strong

GPIO output/input level.

Enumerator
low	Logic low (0)
high	Logic high (1)

Definition at line 67 of file gpio.hpp.

◆ mode

enum class idfxx::gpio::mode : int

strong

GPIO direction mode.

Enumerator
disable	Disable input and output.
input	Input only.
output	Output only.
output_od	Output only with open-drain mode.
input_output_od	Input and output with open-drain mode.
input_output	Input and output.

Definition at line 73 of file gpio.hpp.

◆ pull_mode

enum class idfxx::gpio::pull_mode : int

strong

Pull resistor configuration.

Enumerator
pullup	Pin pull up.
pulldown	Pin pull down.
pullup_pulldown	Pin pull up + pull down.
floating	Pin floating.

Definition at line 83 of file gpio.hpp.

Constructor & Destructor Documentation

◆ gpio() [1/4]

constexpr idfxx::gpio::gpio ( )

inlineconstexpr

Constructs a GPIO representing "not connected".

Definition at line 233 of file gpio.hpp.

◆ gpio() [2/4]

idfxx::gpio::gpio ( int num )

explicit

Constructs a validated GPIO pin.

Parameters

num	GPIO pin number.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if the pin number is invalid.

◆ gpio() [3/4]

idfxx::gpio::gpio ( const gpio & )

default

◆ gpio() [4/4]

idfxx::gpio::gpio ( gpio && )

default

Member Function Documentation

◆ deep_sleep_hold_disable()

static void idfxx::gpio::deep_sleep_hold_disable ( )

static

Disables hold for all digital GPIOs during deep sleep.

◆ deep_sleep_hold_enable()

static void idfxx::gpio::deep_sleep_hold_enable ( )

static

Enables hold for all digital GPIOs during deep sleep.

The hold only takes effect during deep sleep. In active mode, GPIO state can still be changed. Each gpio must also have hold_enable() called for this to work.

◆ get_drive_capability()

enum drive_cap idfxx::gpio::get_drive_capability ( ) const

inline

Gets the current drive capability.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 417 of file gpio.hpp.

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

◆ get_level()

enum level idfxx::gpio::get_level ( ) const

Reads the current input level.

Returns: The current input level.

Warning: If the gpio is not configured for input, the returned value is always gpio::level::low.

Note: Returns gpio::level::low for gpio::nc().

◆ hold_disable()

void idfxx::gpio::hold_disable ( )

inline

Disables gpio hold function.

Warning: After waking from sleep, the GPIO will be set to default mode. Configure the GPIO to the desired state before calling this.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 643 of file gpio.hpp.

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

◆ hold_enable()

void idfxx::gpio::hold_enable ( )

inline

Enables gpio hold function.

When enabled, the gpio's state is latched and will not change when the internal signal or IO MUX/GPIO configuration is modified. Use this to retain GPIO state during sleep or reset. Only applicable to output-capable GPIOs.

Note: On ESP32/S2/C3/S3/C2, this cannot hold digital GPIO state during deep sleep. Use deep_sleep_hold_enable() for that purpose.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 634 of file gpio.hpp.

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

◆ idf_num()

constexpr gpio_num_t idfxx::gpio::idf_num ( ) const

inlineconstexpr

Returns the underlying ESP-IDF GPIO number.

Definition at line 281 of file gpio.hpp.

◆ input_enable()

void idfxx::gpio::input_enable ( )

Enables input on this gpio.

Note: Does nothing if called on gpio::nc().

◆ install_isr_service() [1/2]

static void idfxx::gpio::install_isr_service ( idfxx::flags< intr_flag > flags )

inlinestatic

Installs the GPIO ISR service with default priority levels.

Uses low/medium priority levels (1-3). Equivalent to calling install_isr_service(intr_level_lowmed, flags).

Parameters

flags Behavioral flags (e.g., intr_flag::iram).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 457 of file gpio.hpp.

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

◆ install_isr_service() [2/2]

static void idfxx::gpio::install_isr_service	(	idfxx::intr_levels	levels = `intr_level_lowmed`,
		idfxx::flags< intr_flag >	flags = `{}`
	)

inlinestatic

Installs the GPIO ISR service for per-gpio interrupt handlers.

Must be called before adding handlers with isr_handler_add().

Parameters

levels	Interrupt priority levels to accept.
flags	Behavioral flags (e.g., `intr_flag::iram`).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 444 of file gpio.hpp.

◆ intr_disable()

void idfxx::gpio::intr_disable ( )

Disables interrupts for this gpio.

Note: Does nothing if called on gpio::nc().

◆ intr_enable()

void idfxx::gpio::intr_enable ( )

Enables interrupts for this gpio.

Note: Does nothing if called on gpio::nc().

◆ is_connected()

constexpr bool idfxx::gpio::is_connected ( ) const

inlineconstexpr

Returns true if this is a valid GPIO pin.

Definition at line 269 of file gpio.hpp.

◆ is_digital_io_pin_capable()

constexpr bool idfxx::gpio::is_digital_io_pin_capable ( ) const

inlineconstexpr

Returns true if this gpio is a valid digital I/O pin.

Definition at line 275 of file gpio.hpp.

◆ is_output_capable()

constexpr bool idfxx::gpio::is_output_capable ( ) const

inlineconstexpr

Returns true if this gpio supports output mode.

Definition at line 272 of file gpio.hpp.

◆ isr_handler_add() [1/2]

isr_handle idfxx::gpio::isr_handler_add ( std::move_only_function< void() const > handler )

inline

Adds an ISR handler for this gpio.

The handler will be called from an ISR context. ISR handlers do not need IRAM_ATTR unless intr_flag::iram was passed to install_isr_service().

Warning: This overload cannot be used if intr_flag::iram was passed to install_isr_service(), as std::move_only_function may allocate memory outside of IRAM. Registration will fail with not_supported. Use the raw function pointer overload instead.

Precondition: install_isr_service() must have been called.

Parameters

handler Function to call on interrupt.

Returns: Handle for removing this specific handler.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure, including not_supported if the ISR service was installed with intr_flag::iram.

Definition at line 507 of file gpio.hpp.

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

◆ isr_handler_add() [2/2]

isr_handle idfxx::gpio::isr_handler_add	(	void()(void )	fn,
		void *	arg
	)

inline

Adds an ISR handler for this gpio.

The handler will be called from an ISR context. ISR handlers do not need IRAM_ATTR unless intr_flag::iram was passed to install_isr_service().

Precondition: install_isr_service() must have been called.

Parameters

fn	Function to call on interrupt.
arg	Argument passed to the handler.

Returns: Handle for removing this specific handler.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 523 of file gpio.hpp.

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

◆ isr_handler_remove()

void idfxx::gpio::isr_handler_remove ( isr_handle handle )

inline

Removes a specific ISR handler.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 529 of file gpio.hpp.

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

◆ isr_handler_remove_all()

void idfxx::gpio::isr_handler_remove_all ( )

Removes all ISR handlers for this gpio.

Note: Does nothing if called on gpio::nc().

◆ make()

static result< gpio > idfxx::gpio::make ( int num )

static

Creates a validated GPIO pin.

Parameters

num	GPIO pin number.

Returns: A gpio object or an error if the pin number is invalid.

◆ max()

static constexpr gpio idfxx::gpio::max ( )

inlinestaticconstexpr

Returns a GPIO for the highest valid pin number.

Definition at line 257 of file gpio.hpp.

◆ nc()

static constexpr gpio idfxx::gpio::nc ( )

inlinestaticconstexpr

Returns a GPIO representing "not connected".

Definition at line 254 of file gpio.hpp.

◆ num()

constexpr int idfxx::gpio::num ( ) const

inlineconstexpr

Returns the underlying GPIO pin number.

Definition at line 278 of file gpio.hpp.

◆ operator=() [1/2]

gpio & idfxx::gpio::operator= ( const gpio & )

default

◆ operator=() [2/2]

gpio & idfxx::gpio::operator= ( gpio && )

default

◆ operator==()

constexpr bool idfxx::gpio::operator== ( const gpio & ) const

constexprdefaultnoexcept

Compares two GPIO pins for equality.

◆ pulldown_disable()

void idfxx::gpio::pulldown_disable ( )

inline

Disables the internal pull-down resistor.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 332 of file gpio.hpp.

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

◆ pulldown_enable()

void idfxx::gpio::pulldown_enable ( )

inline

Enables the internal pull-down resistor.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 326 of file gpio.hpp.

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

◆ pullup_disable()

void idfxx::gpio::pullup_disable ( )

inline

Disables the internal pull-up resistor.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 320 of file gpio.hpp.

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

◆ pullup_enable()

void idfxx::gpio::pullup_enable ( )

inline

Enables the internal pull-up resistor.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 314 of file gpio.hpp.

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

◆ reset()

void idfxx::gpio::reset ( )

Resets the gpio to default state.

Selects GPIO function, enables pullup, and disables input and output.

Note: Does nothing if called on an invalid gpio (e.g. gpio::nc()).

◆ set_direction()

void idfxx::gpio::set_direction ( enum mode mode )

inline

Sets the GPIO direction mode.

Note: This always overwrites all current modes applied to the gpio.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 300 of file gpio.hpp.

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

◆ set_drive_capability()

void idfxx::gpio::set_drive_capability ( enum drive_cap strength )

inline

Sets the gpio drive capability.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 411 of file gpio.hpp.

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

◆ set_intr_type()

void idfxx::gpio::set_intr_type ( enum intr_type intr_type )

Sets the interrupt trigger type.

Note: Does nothing if called on gpio::nc().

◆ set_level()

void idfxx::gpio::set_level ( enum level level )

Sets the output level.

Parameters

level The level to set (gpio::level::low or gpio::level::high).

Note: Does nothing if the gpio is not configured for output.

◆ set_pull_mode()

void idfxx::gpio::set_pull_mode ( enum pull_mode mode )

inline

Sets the pull resistor mode.

Note: On ESP32, only GPIOs that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 308 of file gpio.hpp.

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

◆ sleep_sel_disable()

void idfxx::gpio::sleep_sel_disable ( )

Disables SLP_SEL to change GPIO status automatically in light sleep.

Note: Does nothing if called on gpio::nc().

◆ sleep_sel_enable()

void idfxx::gpio::sleep_sel_enable ( )

Enables SLP_SEL to change GPIO status automatically in light sleep.

Note: Does nothing if called on gpio::nc().

◆ sleep_set_direction()

void idfxx::gpio::sleep_set_direction ( enum mode mode )

inline

Sets GPIO direction at sleep.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 694 of file gpio.hpp.

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

◆ sleep_set_pull_mode()

void idfxx::gpio::sleep_set_pull_mode ( enum pull_mode pull )

Sets pull resistor mode at sleep.

Note: On ESP32, only GPIOs that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.; Does nothing if called on gpio::nc().

◆ toggle_level()

void idfxx::gpio::toggle_level ( )

Toggles the output level.

Reads the current level and sets the output to the opposite level.

Note: Does nothing if the gpio is not configured for output.

Warning: If the gpio is not configured for input, get_level() always returns gpio::level::low, so the output will always be set to gpio::level::high.

◆ try_get_drive_capability()

result< drive_cap > idfxx::gpio::try_get_drive_capability ( ) const

Gets the current drive capability.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If called on a gpio that is not output-capable.

Referenced by get_drive_capability().

◆ try_hold_disable()

result< void > idfxx::gpio::try_hold_disable ( )

Disables gpio hold function.

Warning: After waking from sleep, the GPIO will be set to default mode. Configure the GPIO to the desired state before calling this.

Return values

invalid_state	If called on gpio::nc().
not_supported	If the GPIO doesn't support hold.

Referenced by hold_disable().

◆ try_hold_enable()

result< void > idfxx::gpio::try_hold_enable ( )

Enables gpio hold function.

When enabled, the gpio's state is latched and will not change when the internal signal or IO MUX/GPIO configuration is modified. Use this to retain GPIO state during sleep or reset. Only applicable to output-capable GPIOs.

Note: On ESP32/S2/C3/S3/C2, this cannot hold digital GPIO state during deep sleep. Use deep_sleep_hold_enable() for that purpose.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO doesn't support hold.

Referenced by hold_enable().

◆ try_install_isr_service() [1/2]

static result< void > idfxx::gpio::try_install_isr_service ( idfxx::flags< intr_flag > flags )

inlinestatic

Installs the GPIO ISR service with default priority levels.

Uses low/medium priority levels (1-3). Equivalent to calling try_install_isr_service(intr_level_lowmed, flags).

Parameters

flags Behavioral flags (e.g., intr_flag::iram).

Definition at line 477 of file gpio.hpp.

References idfxx::intr_level_lowmed, and try_install_isr_service().

◆ try_install_isr_service() [2/2]

static result< void > idfxx::gpio::try_install_isr_service	(	idfxx::intr_levels	levels = `intr_level_lowmed`,
		idfxx::flags< intr_flag >	flags = `{}`
	)

static

Installs the GPIO ISR service for per-gpio interrupt handlers.

Must be called before adding handlers with isr_handler_add().

Parameters

levels	Interrupt priority levels to accept.
flags	Behavioral flags (e.g., `intr_flag::iram`).

Referenced by install_isr_service(), and try_install_isr_service().

◆ try_isr_handler_add() [1/2]

result< isr_handle > idfxx::gpio::try_isr_handler_add ( std::move_only_function< void() const > handler )

Adds an ISR handler for this gpio.

The handler will be called from an ISR context. ISR handlers do not need IRAM_ATTR unless intr_flag::iram was passed to install_isr_service().

Warning: This overload cannot be used if intr_flag::iram was passed to install_isr_service(), as std::move_only_function may allocate memory outside of IRAM. Registration will fail with not_supported. Use the raw function pointer overload instead.

Precondition: install_isr_service() must have been called.

Parameters

handler Function to call on interrupt.

Returns: Handle for removing this specific handler.

Return values

not_supported If the ISR service was installed with intr_flag::iram.

Referenced by isr_handler_add(), and isr_handler_add().

◆ try_isr_handler_add() [2/2]

result< isr_handle > idfxx::gpio::try_isr_handler_add	(	void()(void )	fn,
		void *	arg
	)

Adds an ISR handler for this gpio.

The handler will be called from an ISR context. ISR handlers do not need IRAM_ATTR unless intr_flag::iram was passed to install_isr_service().

Precondition: install_isr_service() must have been called.

Parameters

fn	Function to call on interrupt.
arg	Argument passed to the handler.

Returns: Handle for removing this specific handler.

Note: Only fails if called on gpio::nc() or the ISR service is not installed.

◆ try_isr_handler_remove()

result< void > idfxx::gpio::try_isr_handler_remove ( isr_handle handle )

Removes a specific ISR handler.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the handle is not valid for this gpio.

Referenced by isr_handler_remove().

◆ try_pulldown_disable()

result< void > idfxx::gpio::try_pulldown_disable ( )

Disables the internal pull-down resistor.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO doesn't support pull resistors.

Referenced by pulldown_disable().

◆ try_pulldown_enable()

result< void > idfxx::gpio::try_pulldown_enable ( )

Enables the internal pull-down resistor.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO doesn't support pull resistors.

Referenced by pulldown_enable().

◆ try_pullup_disable()

result< void > idfxx::gpio::try_pullup_disable ( )

Disables the internal pull-up resistor.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO doesn't support pull resistors.

Referenced by pullup_disable().

◆ try_pullup_enable()

result< void > idfxx::gpio::try_pullup_enable ( )

Enables the internal pull-up resistor.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO doesn't support pull resistors.

Referenced by pullup_enable().

◆ try_set_direction()

result< void > idfxx::gpio::try_set_direction ( enum mode mode )

Sets the GPIO direction mode.

Note: This always overwrites all current modes applied to the gpio.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the gpio is input-only and an output mode is requested.

Referenced by set_direction().

◆ try_set_drive_capability()

result< void > idfxx::gpio::try_set_drive_capability ( enum drive_cap strength )

Sets the gpio drive capability.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If called on a gpio that is not output-capable.

Referenced by set_drive_capability().

◆ try_set_pull_mode()

result< void > idfxx::gpio::try_set_pull_mode ( enum pull_mode mode )

Sets the pull resistor mode.

Note: On ESP32, only GPIOs that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO doesn't support pull resistors.

Referenced by set_pull_mode().

◆ try_sleep_set_direction()

result< void > idfxx::gpio::try_sleep_set_direction ( enum mode mode )

Sets GPIO direction at sleep.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the gpio is input-only and an output mode is requested.

Referenced by sleep_set_direction().

◆ try_wakeup_disable()

result< void > idfxx::gpio::try_wakeup_disable ( )

Disables GPIO wake-up.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If the GPIO is not an RTC GPIO.

Referenced by wakeup_disable().

◆ try_wakeup_enable()

result< void > idfxx::gpio::try_wakeup_enable ( enum intr_type intr_type )

Enables GPIO wake-up from light sleep.

Parameters

intr_type Only low_level or high_level can be used.

Return values

invalid_state	If called on gpio::nc().
invalid_arg	If intr_type is not low_level or high_level.

Referenced by wakeup_enable().

◆ uninstall_isr_service()

static void idfxx::gpio::uninstall_isr_service ( )

static

Uninstalls the GPIO ISR service, freeing related resources.

All registered ISR handlers are removed and internal state is reset.

◆ wakeup_disable()

void idfxx::gpio::wakeup_disable ( )

inline

Disables GPIO wake-up.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 604 of file gpio.hpp.

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

◆ wakeup_enable()

void idfxx::gpio::wakeup_enable ( enum intr_type intr_type )

inline

Enables GPIO wake-up from light sleep.

Parameters

intr_type Only low_level or high_level can be used.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 598 of file gpio.hpp.

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

Friends And Related Symbol Documentation

◆ gpio_constant

template<int N>

friend struct gpio_constant

friend

Definition at line 63 of file gpio.hpp.

The documentation for this class was generated from the following file:

idfxx_gpio/include/idfxx/gpio.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ drive_cap

◆ hys_ctrl_mode

◆ intr_type

◆ level

◆ mode

◆ pull_mode

Constructor & Destructor Documentation

◆ gpio() [1/4]

◆ gpio() [2/4]

◆ gpio() [3/4]

◆ gpio() [4/4]

Member Function Documentation

◆ deep_sleep_hold_disable()

◆ deep_sleep_hold_enable()

◆ get_drive_capability()

◆ get_level()

◆ hold_disable()

◆ hold_enable()

◆ idf_num()

◆ input_enable()

◆ install_isr_service() [1/2]

◆ install_isr_service() [2/2]

◆ intr_disable()

◆ intr_enable()

◆ is_connected()

◆ is_digital_io_pin_capable()

◆ is_output_capable()

◆ isr_handler_add() [1/2]

◆ isr_handler_add() [2/2]

◆ isr_handler_remove()

◆ isr_handler_remove_all()

◆ make()

◆ max()

◆ nc()

◆ num()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ pulldown_disable()

◆ pulldown_enable()

◆ pullup_disable()

◆ pullup_enable()

◆ reset()

◆ set_direction()

◆ set_drive_capability()

◆ set_intr_type()

◆ set_level()

◆ set_pull_mode()

◆ sleep_sel_disable()

◆ sleep_sel_enable()

◆ sleep_set_direction()

◆ sleep_set_pull_mode()

◆ toggle_level()

◆ try_get_drive_capability()

◆ try_hold_disable()

◆ try_hold_enable()

◆ try_install_isr_service() [1/2]

◆ try_install_isr_service() [2/2]

◆ try_isr_handler_add() [1/2]

◆ try_isr_handler_add() [2/2]

◆ try_isr_handler_remove()

◆ try_pulldown_disable()

◆ try_pulldown_enable()

◆ try_pullup_disable()

◆ try_pullup_enable()

◆ try_set_direction()

◆ try_set_drive_capability()

◆ try_set_pull_mode()

◆ try_sleep_set_direction()

◆ try_wakeup_disable()

◆ try_wakeup_enable()

◆ uninstall_isr_service()

◆ wakeup_disable()