GPIO¶

API Reference¶

Header File¶

esp8266/include/driver/gpio.h

Functions¶

esp_err_t gpio_config(const gpio_config_t *gpio_cfg)¶

GPIO common configuration.

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

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

gpio_cfg: 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 GPIO12, gpio_num should be GPIO_NUM_12 (12);
intr_type: Interrupt type, select from gpio_int_type_t

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.

Note

If the pad is not configured for input (or input and output) the returned value is always 0.

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

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.

Note

The GPIO of esp8266 can not be pulled down except RTC GPIO which can not be pulled up.

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.

Note

RTC IO can not use the wakeup 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.

Note

RTC IO can not use the wakeup 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 no_use, gpio_isr_handle_t *handle_no_use, )¶

Register GPIO interrupt handler, the handler is an ISR.

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.

Return

ESP_OK Success ;
ESP_ERR_INVALID_ARG GPIO error
ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

Parameters

fn: Interrupt handler function.
no_use: In order to be compatible with esp32, the parameter has no practical meaning and can be filled with 0.
arg: Parameter for handler function
handle_no_use: Pointer to return handle. In order to be compatible with esp32,the parameter has no practical meaning and can be filled with NULL.

esp_err_t gpio_pullup_en(gpio_num_t gpio_num)¶

Enable pull-up on GPIO.

Note

The GPIO of esp8266 can not be pulled down except RTC GPIO which can not be pulled up.

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.

Note

The GPIO of esp8266 can not be pulled down except RTC GPIO which can not be pulled up.

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.

Note

The GPIO of esp8266 can not be pulled down except RTC GPIO which can not be pulled up.

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.

Note

The GPIO of esp8266 can not be pulled down except RTC GPIO which can not be pulled up.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

gpio_num: GPIO number

esp_err_t gpio_install_isr_service(int no_use)¶

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_ERR_NO_MEM No memory to install this service
ESP_ERR_INVALID_STATE ISR service already installed.
ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
ESP_ERR_INVALID_ARG GPIO error

Parameters

no_use: In order to be compatible with esp32, the parameter has no practical meaning and can be filled with 0.

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.

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

Structures¶

struct gpio_config_t¶

Configuration parameters of GPIO pad for gpio_config function.

Public Members

uint32_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¶

BIT(x)¶

GPIO_Pin_0¶

GPIO_Pin_1¶

GPIO_Pin_2¶

GPIO_Pin_3¶

GPIO_Pin_4¶

GPIO_Pin_5¶

GPIO_Pin_6¶

GPIO_Pin_7¶

GPIO_Pin_8¶

GPIO_Pin_9¶

GPIO_Pin_10¶

GPIO_Pin_11¶

GPIO_Pin_12¶

GPIO_Pin_13¶

GPIO_Pin_14¶

GPIO_Pin_15¶

GPIO_Pin_16¶

GPIO_Pin_All¶

GPIO_MODE_DEF_DISABLE¶

GPIO_MODE_DEF_INPUT¶

GPIO_MODE_DEF_OUTPUT¶

GPIO_MODE_DEF_OD¶

GPIO_PIN_COUNT¶

GPIO_IS_VALID_GPIO(gpio_num)¶: Check whether it is a valid GPIO number

RTC_GPIO_IS_VALID_GPIO(gpio_num)¶: Check whether it is a valid RTC GPIO number

Type Definitions¶

typedef void (*gpio_isr_t)(void *)¶

typedef void *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

GPIO_NUM_3 = 3¶: GPIO3, input and output

GPIO_NUM_4 = 4¶: GPIO4, input and output

GPIO_NUM_5 = 5¶: GPIO5, input and output

GPIO_NUM_6 = 6¶: GPIO6, input and output

GPIO_NUM_7 = 7¶: GPIO7, input and output

GPIO_NUM_8 = 8¶: GPIO8, input and output

GPIO_NUM_9 = 9¶: GPIO9, input and output

GPIO_NUM_10 = 10¶: GPIO10, input and output

GPIO_NUM_11 = 11¶: GPIO11, input and output

GPIO_NUM_12 = 12¶: GPIO12, input and output

GPIO_NUM_13 = 13¶: GPIO13, input and output

GPIO_NUM_14 = 14¶: GPIO14, input and output

GPIO_NUM_15 = 15¶: GPIO15, input and output

GPIO_NUM_16 = 16¶: GPIO16, input and output

GPIO_NUM_MAX = 17¶

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

enum gpio_pull_mode_t¶

Values:

GPIO_PULLUP_ONLY¶: Pad pull up

GPIO_PULLDOWN_ONLY¶: Pad pull down

GPIO_FLOATING¶: Pad floating

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