GPIO & RTC GPIO

Overview

The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.

  • Note that GPIO6-11 are usually used for SPI flash.
  • GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.

There is also separate “RTC GPIO” support, which functions when GPIOs are routed to the “RTC” low-power and analog subsystem. These pin functions can be used when in deep sleep, when the Ultra Low Power co-processor is running, or when analog functions such as ADC/DAC/etc are in use.

Application Example

GPIO output and input interrupt example: peripherals/gpio.

API Reference - Normal GPIO

Functions

esp_err_t gpio_config(const gpio_config_t *pGPIOConfig)

GPIO common configuration.

Configure GPIO’s Mode,pull-up,PullDown,IntrType

Return
  • ESP_OK success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • pGPIOConfig: Pointer to GPIO configure struct

esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type)

GPIO set interrupt trigger type.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_16 (16);
  • intr_type: Interrupt type, select from gpio_int_type_t

esp_err_t gpio_intr_enable(gpio_num_t gpio_num)

Enable GPIO module interrupt signal.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

esp_err_t gpio_intr_disable(gpio_num_t gpio_num)

Disable GPIO module interrupt signal.

Return
  • ESP_OK success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level)

GPIO set output level.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO number error
Parameters
  • gpio_num: GPIO number. If you want to set the output level of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
  • level: Output level. 0: low ; 1: high

int gpio_get_level(gpio_num_t gpio_num)

GPIO get input level.

Return
  • 0 the GPIO input level is 0
  • 1 the GPIO input level is 1
Parameters
  • gpio_num: GPIO number. If you want to get the logic level of e.g. pin GPIO16, gpio_num should be GPIO_NUM_16 (16);

esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)

GPIO set direction.

Configure GPIO direction,such as output_only,input_only,output_and_input

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO error
Parameters
  • gpio_num: Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
  • mode: GPIO direction

esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull)

Configure GPIO pull-up/pull-down resistors.

Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG : Parameter error
Parameters
  • gpio_num: GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
  • pull: GPIO pull up/down mode.

esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type)

Enable GPIO wake-up function.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number.
  • intr_type: GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used.

esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num)

Disable GPIO wake-up function.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number

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

Register GPIO interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.

This ISR function is called whenever any GPIO interrupt occurs. See the alternative gpio_install_isr_service() and gpio_isr_handler_add() API in order to have the driver support per-GPIO ISRs.

To disable or remove the ISR, pass the returned handle to the interrupt allocation functions.

Parameters
  • fn: Interrupt handler function.
  • intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
  • arg: Parameter for handler function
  • handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

Return
  • ESP_OK Success ;
  • ESP_ERR_INVALID_ARG GPIO error

esp_err_t gpio_pullup_en(gpio_num_t gpio_num)

Enable pull-up on GPIO.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number

esp_err_t gpio_pullup_dis(gpio_num_t gpio_num)

Disable pull-up on GPIO.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number

esp_err_t gpio_pulldown_en(gpio_num_t gpio_num)

Enable pull-down on GPIO.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number

esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num)

Disable pull-down on GPIO.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number

esp_err_t gpio_install_isr_service(int intr_alloc_flags)

Install the driver’s GPIO ISR handler service, which allows per-pin GPIO interrupt handlers.

This function is incompatible with gpio_isr_register() - if that function is used, a single global ISR is registered for all GPIO interrupts. If this function is used, the ISR service provides a global GPIO ISR and individual pin handlers are registered via the gpio_isr_handler_add() function.

Return
  • ESP_OK Success
  • ESP_FAIL Operation fail
  • ESP_ERR_NO_MEM No memory to install this service
Parameters
  • intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

void gpio_uninstall_isr_service()

Uninstall the driver’s GPIO ISR service, freeing related resources.

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

Add ISR handler for the corresponding GPIO pin.

Call this function after using gpio_install_isr_service() to install the driver’s GPIO ISR handler service.

The pin ISR handlers no longer need to be declared with IRAM_ATTR, unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the ISR in gpio_install_isr_service().

This ISR handler will be called from an ISR. So there is a stack size limit (configurable as “ISR stack size” in menuconfig). This limit is smaller compared to a global GPIO interrupt handler due to the additional level of indirection.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number
  • isr_handler: ISR handler function for the corresponding GPIO number.
  • args: parameter for ISR handler.

esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num)

Remove ISR handler for the corresponding GPIO pin.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number

esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength)

Set GPIO pad drive capability.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number, only support output GPIOs
  • strength: Drive capability of the pad

esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength)

Get GPIO pad drive capability.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number, only support output GPIOs
  • strength: Pointer to accept drive capability of the pad

Structures

struct gpio_config_t

Configuration parameters of GPIO pad for gpio_config function.

Public Members

uint64_t pin_bit_mask

GPIO pin: set with bit mask, each bit maps to a GPIO

gpio_mode_t mode

GPIO mode: set input/output mode

gpio_pullup_t pull_up_en

GPIO pull-up

gpio_pulldown_t pull_down_en

GPIO pull-down

gpio_int_type_t intr_type

GPIO interrupt type

Macros

GPIO_SEL_0

Pin 0 selected

GPIO_SEL_1

Pin 1 selected

GPIO_SEL_2

Pin 2 selected

Note
There are more macros like that up to pin 39, excluding pins 20, 24 and 28..31. They are not shown here to reduce redundant information.

GPIO_IS_VALID_GPIO(gpio_num)

Check whether it is a valid GPIO number

GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)

Check whether it can be a valid GPIO number of output mode

Type Definitions

typedef void (*gpio_isr_t)(void *)
typedef intr_handle_t gpio_isr_handle_t

Enumerations

enum gpio_num_t

Values:

GPIO_NUM_0 = 0

GPIO0, input and output

GPIO_NUM_1 = 1

GPIO1, input and output

GPIO_NUM_2 = 2

GPIO2, input and output

Note
There are more enumerations like that up to GPIO39, excluding GPIO20, GPIO24 and GPIO28..31. They are not shown here to reduce redundant information.
Note
GPIO34..39 are input mode only.

enum gpio_int_type_t

Values:

GPIO_INTR_DISABLE = 0

Disable GPIO interrupt

GPIO_INTR_POSEDGE = 1

GPIO interrupt type : rising edge

GPIO_INTR_NEGEDGE = 2

GPIO interrupt type : falling edge

GPIO_INTR_ANYEDGE = 3

GPIO interrupt type : both rising and falling edge

GPIO_INTR_LOW_LEVEL = 4

GPIO interrupt type : input low level trigger

GPIO_INTR_HIGH_LEVEL = 5

GPIO interrupt type : input high level trigger

GPIO_INTR_MAX
enum gpio_mode_t

Values:

GPIO_MODE_DISABLE = GPIO_MODE_DEF_DISABLE

GPIO mode : disable input and output

GPIO_MODE_INPUT = GPIO_MODE_DEF_INPUT

GPIO mode : input only

GPIO_MODE_OUTPUT = GPIO_MODE_DEF_OUTPUT

GPIO mode : output only mode

GPIO_MODE_OUTPUT_OD = ((GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD))

GPIO mode : output only with open-drain mode

GPIO_MODE_INPUT_OUTPUT_OD = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD))

GPIO mode : output and input with open-drain mode

GPIO_MODE_INPUT_OUTPUT = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT))

GPIO mode : output and input mode

enum gpio_pullup_t

Values:

GPIO_PULLUP_DISABLE = 0x0

Disable GPIO pull-up resistor

GPIO_PULLUP_ENABLE = 0x1

Enable GPIO pull-up resistor

enum gpio_pulldown_t

Values:

GPIO_PULLDOWN_DISABLE = 0x0

Disable GPIO pull-down resistor

GPIO_PULLDOWN_ENABLE = 0x1

Enable GPIO pull-down resistor

enum gpio_pull_mode_t

Values:

GPIO_PULLUP_ONLY

Pad pull up

GPIO_PULLDOWN_ONLY

Pad pull down

GPIO_PULLUP_PULLDOWN

Pad pull up + pull down

GPIO_FLOATING

Pad floating

enum gpio_drive_cap_t

Values:

GPIO_DRIVE_CAP_0 = 0

Pad drive capability: weak

GPIO_DRIVE_CAP_1 = 1

Pad drive capability: stronger

GPIO_DRIVE_CAP_2 = 2

Pad drive capability: default value

GPIO_DRIVE_CAP_DEFAULT = 2

Pad drive capability: default value

GPIO_DRIVE_CAP_3 = 3

Pad drive capability: strongest

GPIO_DRIVE_CAP_MAX

API Reference - RTC GPIO

Functions

static bool rtc_gpio_is_valid_gpio(gpio_num_t gpio_num)

Determine if the specified GPIO is a valid RTC GPIO.

Return
true if GPIO is valid for RTC GPIO use. talse otherwise.
Parameters
  • gpio_num: GPIO number

esp_err_t rtc_gpio_init(gpio_num_t gpio_num)

Init a GPIO as RTC GPIO.

This function must be called when initializing a pad for an analog function.

Return
  • ESP_OK success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num)

Init a GPIO as digital GPIO.

Return
  • ESP_OK success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

uint32_t rtc_gpio_get_level(gpio_num_t gpio_num)

Get the RTC IO input level.

Return
  • 1 High level
  • 0 Low level
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level)

Set the RTC IO output level.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)
  • level: output level

esp_err_t rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode)

RTC GPIO set direction.

Configure RTC GPIO direction, such as output only, input only, output and input.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)
  • mode: GPIO direction

esp_err_t rtc_gpio_pullup_en(gpio_num_t gpio_num)

RTC GPIO pullup enable.

This function only works for RTC IOs. In general, call gpio_pullup_en, which will work both for normal GPIOs and RTC IOs.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_pulldown_en(gpio_num_t gpio_num)

RTC GPIO pulldown enable.

This function only works for RTC IOs. In general, call gpio_pulldown_en, which will work both for normal GPIOs and RTC IOs.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_pullup_dis(gpio_num_t gpio_num)

RTC GPIO pullup disable.

This function only works for RTC IOs. In general, call gpio_pullup_dis, which will work both for normal GPIOs and RTC IOs.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_pulldown_dis(gpio_num_t gpio_num)

RTC GPIO pulldown disable.

This function only works for RTC IOs. In general, call gpio_pulldown_dis, which will work both for normal GPIOs and RTC IOs.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_hold_en(gpio_num_t gpio_num)

Enable hold function on an RTC IO pad.

Enabling HOLD function will cause the pad to latch current values of input enable, output enable, output value, function, drive strength values. This function is useful when going into light or deep sleep mode to prevent the pin configuration from changing.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

esp_err_t rtc_gpio_hold_dis(gpio_num_t gpio_num)

Disable hold function on an RTC IO pad.

Disabling hold function will allow the pad receive the values of input enable, output enable, output value, function, drive strength from RTC_IO peripheral.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG GPIO is not an RTC IO
Parameters
  • gpio_num: GPIO number (e.g. GPIO_NUM_12)

void rtc_gpio_force_hold_dis_all()

Disable force hold signal for all RTC IOs.

Each RTC pad has a “force hold” input signal from the RTC controller. If this signal is set, pad latches current values of input enable, function, output enable, and other signals which come from the RTC mux. Force hold signal is enabled before going into deep sleep for pins which are used for EXT1 wakeup.

esp_err_t rtc_gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength)

Set RTC GPIO pad drive capability.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number, only support output GPIOs
  • strength: Drive capability of the pad

esp_err_t rtc_gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength)

Get RTC GPIO pad drive capability.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • gpio_num: GPIO number, only support output GPIOs
  • strength: Pointer to accept drive capability of the pad

Structures

struct rtc_gpio_desc_t

Pin function information for a single GPIO pad’s RTC functions.

This is an internal function of the driver, and is not usually useful for external use.

Public Members

uint32_t reg

Register of RTC pad, or 0 if not an RTC GPIO

uint32_t mux

Bit mask for selecting digital pad or RTC pad

uint32_t func

Shift of pad function (FUN_SEL) field

uint32_t ie

Mask of input enable

uint32_t pullup

Mask of pullup enable

uint32_t pulldown

Mask of pulldown enable

uint32_t slpsel

If slpsel bit is set, slpie will be used as pad input enabled signal in sleep mode

uint32_t slpie

Mask of input enable in sleep mode

uint32_t hold

Mask of hold enable

uint32_t hold_force

Mask of hold_force bit for RTC IO in RTC_CNTL_HOLD_FORCE_REG

uint32_t drv_v

Mask of drive capability

uint32_t drv_s

Offset of drive capability

int rtc_num

RTC IO number, or -1 if not an RTC GPIO

Macros

RTC_GPIO_IS_VALID_GPIO(gpio_num)

Enumerations

enum rtc_gpio_mode_t

Values:

RTC_GPIO_MODE_INPUT_ONLY

Pad input

RTC_GPIO_MODE_OUTPUT_ONLY

Pad output

RTC_GPIO_MODE_INPUT_OUTPUT

Pad pull input + output

RTC_GPIO_MODE_DISABLED

Pad (output + input) disable