gpio.h File Reference

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

Go to the source code of this file.

Data Structures
struct	gpio_config_t
	Bulk configuration structure used by gpio_config(). More...

Macros
#define	GPIO_NUM_NC   (-1)

Typedefs
typedef int32_t	gpio_num_t
	GPIO pin number (flat encoding, see file comment).
typedef uint64_t	gpio_pin_bit_mask_t
	Bit-mask of pin numbers used by gpio_config().
typedef void(*	gpio_isr_t) (void *arg)
	Per-pin ISR callback handler.
typedef void *	gpio_isr_handle_t
	Not supported on the VSF shim. Returns ESP_ERR_NOT_SUPPORTED.

Enumerations
enum	gpio_mode_t {   GPIO_MODE_DISABLE = 0 ,   GPIO_MODE_INPUT = 1 ,   GPIO_MODE_OUTPUT = 2 ,   GPIO_MODE_OUTPUT_OD = 3 ,   GPIO_MODE_INPUT_OUTPUT_OD = 4 ,   GPIO_MODE_INPUT_OUTPUT = 5 }
	Pin direction. More...
enum	gpio_pullup_t {   GPIO_PULLUP_DISABLE = 0 ,   GPIO_PULLUP_ENABLE = 1 }
	Pull-resistor configuration. More...
enum	gpio_pulldown_t {   GPIO_PULLDOWN_DISABLE = 0 ,   GPIO_PULLDOWN_ENABLE = 1 }
enum	gpio_pull_mode_t {   GPIO_FLOATING = 0 ,   GPIO_PULLUP_ONLY = 1 ,   GPIO_PULLDOWN_ONLY = 2 ,   GPIO_PULLUP_PULLDOWN = 3 }
enum	gpio_int_type_t {   GPIO_INTR_DISABLE = 0 ,   GPIO_INTR_POSEDGE = 1 ,   GPIO_INTR_NEGEDGE = 2 ,   GPIO_INTR_ANYEDGE = 3 ,   GPIO_INTR_LOW_LEVEL = 4 ,   GPIO_INTR_HIGH_LEVEL = 5 }
	External interrupt trigger type. More...
enum	gpio_level_t {   GPIO_LOW = 0 ,   GPIO_HIGH = 1 }
	Signal level passed to gpio_set_level(). More...

Functions
esp_err_t	gpio_config (const gpio_config_t *config)
	Apply a bulk configuration to every pin listed in config->pin_bit_mask.
esp_err_t	gpio_reset_pin (gpio_num_t gpio_num)
	Reset a single pin to a safe post-boot state (input, no pull, no interrupt).
esp_err_t	gpio_set_direction (gpio_num_t gpio_num, gpio_mode_t mode)
	Set the direction of a single pin.
esp_err_t	gpio_set_pull_mode (gpio_num_t gpio_num, gpio_pull_mode_t pull)
	Set the pull mode of a single pin.
esp_err_t	gpio_set_level (gpio_num_t gpio_num, uint32_t level)
	Set the output level of a single pin (0 = low, non-zero = high).
int	gpio_get_level (gpio_num_t gpio_num)
	Read the input level of a single pin (0 or 1).
esp_err_t	gpio_pullup_en (gpio_num_t gpio_num)
	Shortcut pull-up/pull-down enable/disable APIs.
esp_err_t	gpio_pullup_dis (gpio_num_t gpio_num)
esp_err_t	gpio_pulldown_en (gpio_num_t gpio_num)
esp_err_t	gpio_pulldown_dis (gpio_num_t gpio_num)
esp_err_t	gpio_set_intr_type (gpio_num_t gpio_num, gpio_int_type_t intr_type)
	Configure the edge/level that generates an external interrupt on the pin. This does NOT enable the interrupt by itself – call gpio_intr_enable() afterwards.
esp_err_t	gpio_intr_enable (gpio_num_t gpio_num)
	Per-pin interrupt arm/disarm.
esp_err_t	gpio_intr_disable (gpio_num_t gpio_num)
esp_err_t	gpio_install_isr_service (int intr_alloc_flags)
	Install the shim's per-pin ISR dispatcher.
void	gpio_uninstall_isr_service (void)
	Release the per-pin ISR dispatcher.
esp_err_t	gpio_isr_handler_add (gpio_num_t gpio_num, gpio_isr_t isr_handler, void *args)
	Attach a per-pin callback under the ISR service.
esp_err_t	gpio_isr_handler_remove (gpio_num_t gpio_num)
	Detach a per-pin callback previously registered with gpio_isr_handler_add().
esp_err_t	gpio_isr_register (void(*fn)(void *), void *arg, int intr_alloc_flags, gpio_isr_handle_t *handle)
esp_err_t	gpio_wakeup_enable (gpio_num_t gpio_num, gpio_int_type_t intr_type)
	Accepted for source compatibility. Returns ESP_ERR_NOT_SUPPORTED unless the underlying board enables the corresponding low-power feature – which the shim cannot probe.
esp_err_t	gpio_wakeup_disable (gpio_num_t gpio_num)

Macro Definition Documentation

GPIO_NUM_NC

#define GPIO_NUM_NC   (-1)

Typedef Documentation

gpio_num_t

typedef int32_t gpio_num_t

GPIO pin number (flat encoding, see file comment).

A negative value denotes "not assigned".

gpio_pin_bit_mask_t

typedef uint64_t gpio_pin_bit_mask_t

Bit-mask of pin numbers used by gpio_config().

Bit N corresponds to gpio_num_t == N. Callers use pin_bit_mask = 1ULL << GPIO_NUM_X to include pin X.

gpio_isr_t

typedef void(* gpio_isr_t) (void *arg)

Per-pin ISR callback handler.

Invoked from the VSF EXTI dispatcher on the underlying HAL driver's interrupt priority. ISR context constraints apply: do not call blocking APIs from here.

gpio_isr_handle_t

typedef void* gpio_isr_handle_t

Not supported on the VSF shim. Returns ESP_ERR_NOT_SUPPORTED.

The ESP-IDF "raw ISR" path bypasses the dispatcher and hands the IRQ vector to a user-provided assembly-callable handler. VSF's HAL interrupt surface is prio + handler_fn + per-port dispatch, so this legacy path cannot be mapped cleanly.

Enumeration Type Documentation

gpio_mode_t

enum gpio_mode_t

Pin direction.

Enumerator
GPIO_MODE_DISABLE
GPIO_MODE_INPUT
GPIO_MODE_OUTPUT
GPIO_MODE_OUTPUT_OD	open-drain output
GPIO_MODE_INPUT_OUTPUT_OD	open-drain IO – shim maps to OD
GPIO_MODE_INPUT_OUTPUT	push-pull IO – shim maps to PP

gpio_pullup_t

enum gpio_pullup_t

Pull-resistor configuration.

Enumerator
GPIO_PULLUP_DISABLE
GPIO_PULLUP_ENABLE

gpio_pulldown_t

enum gpio_pulldown_t

Enumerator
GPIO_PULLDOWN_DISABLE
GPIO_PULLDOWN_ENABLE

gpio_pull_mode_t

enum gpio_pull_mode_t

Enumerator
GPIO_FLOATING	no internal pull
GPIO_PULLUP_ONLY
GPIO_PULLDOWN_ONLY
GPIO_PULLUP_PULLDOWN	both; shim collapses to FLOATING

gpio_int_type_t

enum gpio_int_type_t

External interrupt trigger type.

Enumerator
GPIO_INTR_DISABLE
GPIO_INTR_POSEDGE
GPIO_INTR_NEGEDGE
GPIO_INTR_ANYEDGE
GPIO_INTR_LOW_LEVEL
GPIO_INTR_HIGH_LEVEL

gpio_level_t

enum gpio_level_t

Signal level passed to gpio_set_level().

Enumerator
GPIO_LOW
GPIO_HIGH

Function Documentation

gpio_config()

esp_err_t gpio_config ( const gpio_config_t *  config )

extern

Apply a bulk configuration to every pin listed in config->pin_bit_mask.

Return values

ESP_OK	success
ESP_ERR_INVALID_ARG	config is NULL or the mask selects a pin that does not exist in the current io_mapper

gpio_reset_pin()

esp_err_t gpio_reset_pin ( gpio_num_t  gpio_num )

extern

Reset a single pin to a safe post-boot state (input, no pull, no interrupt).

gpio_set_direction()

esp_err_t gpio_set_direction ( gpio_num_t  gpio_num, gpio_mode_t  mode  )

extern

Set the direction of a single pin.

gpio_set_pull_mode()

esp_err_t gpio_set_pull_mode ( gpio_num_t  gpio_num, gpio_pull_mode_t  pull  )

extern

Set the pull mode of a single pin.

gpio_set_level()

esp_err_t gpio_set_level ( gpio_num_t  gpio_num, uint32_t  level  )

extern

Set the output level of a single pin (0 = low, non-zero = high).

gpio_get_level()

int gpio_get_level ( gpio_num_t  gpio_num )

extern

Read the input level of a single pin (0 or 1).

gpio_pullup_en()

esp_err_t gpio_pullup_en ( gpio_num_t  gpio_num )

extern

Shortcut pull-up/pull-down enable/disable APIs.

gpio_pullup_dis()

esp_err_t gpio_pullup_dis ( gpio_num_t  gpio_num )

extern

gpio_pulldown_en()

esp_err_t gpio_pulldown_en ( gpio_num_t  gpio_num )

extern

gpio_pulldown_dis()

esp_err_t gpio_pulldown_dis ( gpio_num_t  gpio_num )

extern

gpio_set_intr_type()

esp_err_t gpio_set_intr_type ( gpio_num_t  gpio_num, gpio_int_type_t  intr_type  )

extern

Configure the edge/level that generates an external interrupt on the pin. This does NOT enable the interrupt by itself – call gpio_intr_enable() afterwards.

gpio_intr_enable()

esp_err_t gpio_intr_enable ( gpio_num_t  gpio_num )

extern

Per-pin interrupt arm/disarm.

gpio_intr_disable()

esp_err_t gpio_intr_disable ( gpio_num_t  gpio_num )

extern

gpio_install_isr_service()

esp_err_t gpio_install_isr_service ( int  intr_alloc_flags )

extern

Install the shim's per-pin ISR dispatcher.

Mirrors the ESP-IDF "ISR service" concept: a single central IRQ handler fans out to per-pin callbacks registered via gpio_isr_handler_add(). Must be called once before any _add/_remove call.

Parameters

intr_alloc_flags

accepted for source compatibility and otherwise ignored (VSF routes every EXTI through the same HAL priority level chosen by the board).

Return values

ESP_OK	success or already installed
ESP_ERR_NO_MEM	handler table could not be allocated
ESP_ERR_INVALID_STATE	VSF io_mapper reports zero ports

gpio_uninstall_isr_service()

void gpio_uninstall_isr_service ( void  )

extern

Release the per-pin ISR dispatcher.

All registered per-pin callbacks are dropped; per-port EXTI handlers are disabled in the underlying HAL driver.

gpio_isr_handler_add()

esp_err_t gpio_isr_handler_add ( gpio_num_t  gpio_num, gpio_isr_t  isr_handler, void *  args  )

extern

Attach a per-pin callback under the ISR service.

Return values

ESP_OK	success
ESP_ERR_INVALID_STATE	the ISR service has not been installed
ESP_ERR_INVALID_ARG	gpio_num is out of range or isr_handler is NULL

gpio_isr_handler_remove()

esp_err_t gpio_isr_handler_remove ( gpio_num_t  gpio_num )

extern

Detach a per-pin callback previously registered with gpio_isr_handler_add().

gpio_isr_register()

esp_err_t gpio_isr_register ( void(*)(void *)  fn, void *  arg, int  intr_alloc_flags, gpio_isr_handle_t *  handle  )

extern

gpio_wakeup_enable()

esp_err_t gpio_wakeup_enable ( gpio_num_t  gpio_num, gpio_int_type_t  intr_type  )

extern

Accepted for source compatibility. Returns ESP_ERR_NOT_SUPPORTED unless the underlying board enables the corresponding low-power feature – which the shim cannot probe.

gpio_wakeup_disable()

esp_err_t gpio_wakeup_disable ( gpio_num_t  gpio_num )

extern