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	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 &other) const =default

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	input_enable ()
	Enables input on this gpio.

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.

result< void >	try_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 (bool level)
	Sets the output level.

bool	get_level () const
	Reads the current input 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.

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

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.

result< void >	try_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.

result< void >	try_set_intr_type (enum intr_type intr_type)
	Sets the interrupt trigger type.

result< void >	try_intr_enable ()
	Enables interrupts for this gpio.

result< void >	try_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.

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

result< void >	try_sleep_sel_enable ()
	Enables SLP_SEL to change GPIO status automatically in light sleep.

result< void >	try_sleep_sel_disable ()
	Disables SLP_SEL to change GPIO status automatically in light sleep.

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

result< void >	try_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 (flags< intr_flag > intr_alloc_flags={})
	Installs the GPIO ISR service for per-gpio interrupt handlers.

static result< void >	try_install_isr_service (flags< intr_flag > intr_flags={})
	Installs the GPIO ISR service for per-gpio interrupt handlers.

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 58 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	Pin drive capability: weak.
cap_1	Pin drive capability: stronger.
cap_2	Pin drive capability: medium.
cap_default	Pin drive capability: medium.
cap_3	Pin drive capability: strongest.

Definition at line 82 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 102 of file gpio.hpp.

◆ intr_type

enum class idfxx::gpio::intr_type : int

strong

Interrupt trigger type.

Enumerator
disable	Disable GPIO interrupt.
posedge	GPIO interrupt type : rising edge.
negedge	GPIO interrupt type : falling edge.
anyedge	GPIO interrupt type : both rising and falling edge.
low_level	GPIO interrupt type : input low level trigger.
high_level	GPIO interrupt type : input high level trigger.

Definition at line 91 of file gpio.hpp.

◆ mode

enum class idfxx::gpio::mode : int

strong

GPIO direction mode.

Enumerator
disable	GPIO mode : disable input and output.
input	GPIO mode : input only.
output	GPIO mode : output only mode.
output_od	GPIO mode : output only with open-drain mode.
input_output_od	GPIO mode : output and input with open-drain mode.
input_output	GPIO mode : output and input mode.

Definition at line 64 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 74 of file gpio.hpp.

Constructor & Destructor Documentation

◆ gpio() [1/4]

constexpr idfxx::gpio::gpio ( )

inlineconstexpr

Constructs a GPIO representing "not connected".

Definition at line 227 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 ( )

inlinestatic

Disables hold for all digital GPIOs during deep sleep.

Definition at line 703 of file gpio.hpp.

◆ deep_sleep_hold_enable()

static void idfxx::gpio::deep_sleep_hold_enable ( )

inlinestatic

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.

Definition at line 701 of file gpio.hpp.

◆ 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 427 of file gpio.hpp.

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

◆ get_level()

bool idfxx::gpio::get_level ( ) const

inline

Reads the current input level.

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

Note: Returns false for gpio::nc().

Definition at line 412 of file gpio.hpp.

◆ 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 671 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 662 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 276 of file gpio.hpp.

◆ input_enable()

void idfxx::gpio::input_enable ( )

inline

Enables input on this gpio.

Note: Only fails if called on gpio::nc().; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 307 of file gpio.hpp.

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

◆ install_isr_service()

static void idfxx::gpio::install_isr_service ( flags< intr_flag > intr_alloc_flags = {} )

inlinestatic

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

Must be called before adding handlers with isr_handler_add().

Parameters

intr_alloc_flags Flags for interrupt allocation (ESP_INTR_FLAG_*).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 462 of file gpio.hpp.

◆ intr_disable()

void idfxx::gpio::intr_disable ( )

inline

Disables interrupts for this gpio.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 593 of file gpio.hpp.

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

◆ intr_enable()

void idfxx::gpio::intr_enable ( )

inline

Enables interrupts for this gpio.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 587 of file gpio.hpp.

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

◆ is_connected()

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

inlineconstexpr

Returns true if this is a valid GPIO pin.

Definition at line 262 of file gpio.hpp.

Referenced by reset(), idfxx::to_string(), and try_get_drive_capability().

◆ 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 270 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 267 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 ESP_INTR_FLAG_IRAM was passed to install_isr_service().

Warning: This overload cannot be used if ESP_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 ESP_INTR_FLAG_IRAM.

Definition at line 501 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 ESP_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 517 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 523 of file gpio.hpp.

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

◆ isr_handler_remove_all()

void idfxx::gpio::isr_handler_remove_all ( )

inline

Removes all ISR handlers for this gpio.

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_all(), and idfxx::unwrap().

◆ 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 251 of file gpio.hpp.

◆ nc()

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

inlinestaticconstexpr

Returns a GPIO representing "not connected".

Definition at line 248 of file gpio.hpp.

◆ num()

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

inlineconstexpr

Returns the underlying GPIO pin number.

Definition at line 273 of file gpio.hpp.

Referenced by idfxx::to_string().

◆ 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 & other ) const

constexprdefault

◆ 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 339 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 333 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 327 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 321 of file gpio.hpp.

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

◆ reset()

void idfxx::gpio::reset ( )

inline

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()).

Definition at line 285 of file gpio.hpp.

References is_connected().

◆ 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 421 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 )

inline

Sets the interrupt trigger type.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 581 of file gpio.hpp.

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

◆ set_level()

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

inline

Sets the output level.

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

Definition at line 406 of file gpio.hpp.

◆ 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 315 of file gpio.hpp.

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

◆ sleep_sel_disable()

void idfxx::gpio::sleep_sel_disable ( )

inline

Disables SLP_SEL to change GPIO status automatically in light sleep.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 718 of file gpio.hpp.

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

◆ sleep_sel_enable()

void idfxx::gpio::sleep_sel_enable ( )

inline

Enables SLP_SEL to change GPIO status automatically in light sleep.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 712 of file gpio.hpp.

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

◆ 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 724 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 )

inline

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.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 732 of file gpio.hpp.

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

◆ try_get_drive_capability()

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

inline

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.

Definition at line 442 of file gpio.hpp.

References idfxx::error(), idfxx::invalid_state, is_connected(), and idfxx::wrap().

Referenced by get_drive_capability().

◆ try_hold_disable()

result< void > idfxx::gpio::try_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.

Return values

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

Definition at line 694 of file gpio.hpp.

Referenced by hold_disable().

◆ try_hold_enable()

result< void > idfxx::gpio::try_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.

Return values

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

Definition at line 685 of file gpio.hpp.

Referenced by hold_enable().

◆ try_input_enable()

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

inline

Enables input on this gpio.

Return values

invalid_state If called on gpio::nc().

Note: Only fails if called on gpio::nc().

Definition at line 355 of file gpio.hpp.

Referenced by input_enable().

◆ try_install_isr_service()

static result< void > idfxx::gpio::try_install_isr_service ( flags< intr_flag > intr_flags = {} )

static

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

Must be called before adding handlers with isr_handler_add().

Parameters

intr_flags Flags for interrupt allocation (ESP_INTR_FLAG_*).

◆ try_intr_disable()

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

inline

Disables interrupts for this gpio.

Return values

invalid_state If called on gpio::nc().

Note: Only fails if called on gpio::nc().

Definition at line 614 of file gpio.hpp.

Referenced by intr_disable().

◆ try_intr_enable()

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

inline

Enables interrupts for this gpio.

Return values

invalid_state If called on gpio::nc().

Note: Only fails if called on gpio::nc().

Definition at line 608 of file gpio.hpp.

Referenced by intr_enable().

◆ 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 ESP_INTR_FLAG_IRAM was passed to install_isr_service().

Warning: This overload cannot be used if ESP_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 ESP_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 ESP_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_isr_handler_remove_all()

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

Removes all ISR handlers for this gpio.

Return values

invalid_state If called on gpio::nc().

Note: Only fails if called on gpio::nc().

Referenced by isr_handler_remove_all().

◆ try_pulldown_disable()

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

inline

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.

Definition at line 397 of file gpio.hpp.

Referenced by pulldown_disable().

◆ try_pulldown_enable()

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

inline

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.

Definition at line 389 of file gpio.hpp.

Referenced by pulldown_enable().

◆ try_pullup_disable()

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

inline

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.

Definition at line 381 of file gpio.hpp.

Referenced by pullup_disable().

◆ try_pullup_enable()

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

inline

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.

Definition at line 373 of file gpio.hpp.

Referenced by pullup_enable().

◆ try_set_direction()

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

inline

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.

Definition at line 347 of file gpio.hpp.

Referenced by set_direction().

◆ try_set_drive_capability()

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

inline

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.

Definition at line 434 of file gpio.hpp.

Referenced by set_drive_capability().

◆ try_set_intr_type()

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

inline

Sets the interrupt trigger type.

Return values

invalid_state If called on gpio::nc().

Note: Only fails if called on gpio::nc().

Definition at line 600 of file gpio.hpp.

Referenced by set_intr_type().

◆ try_set_pull_mode()

result< void > idfxx::gpio::try_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.

Return values

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

Definition at line 365 of file gpio.hpp.

Referenced by set_pull_mode().

◆ try_sleep_sel_disable()

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

inline

Disables SLP_SEL to change GPIO status automatically in light sleep.

Note: Only fails if called on gpio::nc().

Definition at line 743 of file gpio.hpp.

Referenced by sleep_sel_disable().

◆ try_sleep_sel_enable()

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

inline

Enables SLP_SEL to change GPIO status automatically in light sleep.

Note: Only fails if called on gpio::nc().

Definition at line 738 of file gpio.hpp.

Referenced by sleep_sel_enable().

◆ try_sleep_set_direction()

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

inline

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.

Definition at line 749 of file gpio.hpp.

Referenced by sleep_set_direction().

◆ try_sleep_set_pull_mode()

result< void > idfxx::gpio::try_sleep_set_pull_mode ( enum pull_mode pull )

inline

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.

Return values

invalid_state If called on gpio::nc().

Note: Only fails if called on gpio::nc().

Definition at line 759 of file gpio.hpp.

Referenced by sleep_set_pull_mode().

◆ try_wakeup_disable()

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

inline

Disables GPIO wake-up.

Return values

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

Definition at line 646 of file gpio.hpp.

Referenced by wakeup_disable().

◆ try_wakeup_enable()

result< void > idfxx::gpio::try_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.

Return values

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

Definition at line 638 of file gpio.hpp.

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 630 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 624 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 60 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

◆ 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()

◆ 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()

◆ try_get_drive_capability()

◆ try_hold_disable()

◆ try_hold_enable()

◆ try_input_enable()

◆ try_install_isr_service()

◆ try_intr_disable()

◆ try_intr_enable()

◆ try_isr_handler_add() [1/2]

◆ try_isr_handler_add() [2/2]

◆ try_isr_handler_remove()

◆ try_isr_handler_remove_all()

◆ try_pulldown_disable()

◆ try_pulldown_enable()

◆ try_pullup_disable()

◆ try_pullup_enable()

◆ try_set_direction()

◆ try_set_drive_capability()

◆ try_set_intr_type()

◆ try_set_pull_mode()

◆ try_sleep_sel_disable()

◆ try_sleep_sel_enable()

◆ try_sleep_set_direction()

◆ try_sleep_set_pull_mode()