DIY - ESP32：ESP32 GPIO API 應用程式接口函數（三十）

DIY - ESP32：ESP32 GPIO API 應用程式接口函數（三十）：

ESP32 晶片有 40 個物理 GPIO I/O 焊盤，有部分 GPIO 焊盤不可用或者沒有對應的晶片封裝上的管腳。每個 I/O 焊盤都可用作一個通用 IO，或連接一個內部的外設信號的。 IO_MUX、 RTC IO_MUX 和 GPIO 交換矩陣用於將信號從外設傳輸至 GPIO 接口。這些模組共同組成了晶片的 IO 控制。由於 ESP32 與 ESP8266 的應用程式接口 （API / Application Programming Interface）是不全完相同，所以記錄下來作參考。

功能 – gpio_config
原型：esp_err_t gpio_config(const gpio_config_t *pGPIOConfig)
參數：pGPIOConfig: Pointer to GPIO configure struct
返回：ESP_OK success

          ESP_ERR_INVALID_ARG Parameter error
說明：Configure GPIO’s Mode,pull-up,PullDown,IntrType
範例：

功能 – gpio_reset_pin
原型：esp_err_t gpio_reset_pin(gpio_num_t gpio_num)
參數：gpio_num: GPIO number.
返回：Always return ESP_OK.
說明：Reset an gpio to default state (select gpio function, enable pullup and disable input and output).

Note：This function also configures the IOMUX for this pin to the GPIO function, and disconnects any other peripheral output configured via GPIO Matrix.
範例：

功能 – gpio_set_intr_type

原型：esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type)
參數：gpio_num: GPIO number.

           intr_type: Interrupt type, select from gpio_int_type_t
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：GPIO set interrupt trigger type.
範例：

功能 – gpio_intr_enable
原型：esp_err_t gpio_intr_enable(gpio_num_t gpio_num)
參數：gpio_num: GPIO number.
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Enable GPIO module interrupt signal.

Note：Please do not use the interrupt of GPIO36 and GPIO39 when using ADC. Please refer to the comments of adc1_get_raw. Please refer to section 3.11 of ‘ECO_and_Workarounds_for_Bugs_in_ESP32’ for the description of this issue.
範例：

功能 – gpio_intr_disable
原型：esp_err_t gpio_intr_disable(gpio_num_t gpio_num)
參數：gpio_num: GPIO number.
返回：ESP_OK success

          ESP_ERR_INVALID_ARG Parameter error
說明：Disable GPIO module interrupt signal.
範例：

功能 – gpio_set_level
原型：esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level)
參數：gpio_num: GPIO number

           level: Output level. 0: low ; 1: high
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG GPIO number error
說明：GPIO set output level.
範例：

功能 – gpio_get_level
原型：int gpio_get_level(gpio_num_t gpio_num)
參數：gpio_num: GPIO number.
返回：0 the GPIO input level is 0

          1 the GPIO input level is 1
說明：GPIO get input level. If the pad is not configured for input (or input and output) the returned value is always 0.
範例：

功能 – gpio_set_direction
原型：esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)
參數：gpio_num: Configure GPIO pins number

        mode: GPIO direction
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG GPIO error
說明：GPIO set direction.

Configure GPIO direction,such as output_only,input_only,output_and_input
範例：

功能 – gpio_set_pull_mode
原型：esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull)
參數：gpio_num: GPIO number.

          pull: GPIO pull up/down mode.
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG : Parameter error
說明：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.
範例：

功能 – gpio_wakeup_enable
原型：esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type)
參數：gpio_num: GPIO number.

           intr_type: GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used.
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Enable GPIO wake-up function.
範例：

功能 – gpio_wakeup_disable
原型：esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num)
參數：gpio_num: GPIO number
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Disable GPIO wake-up function.
範例：

功能 – gpio_isr_register
原型：esp_err_t gpio_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, gpio_isr_handle_t *handle, )
參數：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.
返回： ESP_OK Success ;

           ESP_ERR_INVALID_ARG GPIO error

           ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
說明：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.
範例：

功能 – gpio_pullup_en
原型：esp_err_t gpio_pullup_en(gpio_num_t gpio_num)
參數：gpio_num: GPIO number
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Enable pull-up on GPIO.
範例：

功能 – gpio_pullup_dis
原型：esp_err_t gpio_pullup_dis(gpio_num_t gpio_num)
參數：gpio_num: GPIO number
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Disable pull-up on GPIO.
範例：

功能 – gpio_pulldown_en
原型：esp_err_t gpio_pulldown_en(gpio_num_t gpio_num)
參數：gpio_num: GPIO number
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Enable pull-down on GPIO.
範例：

功能 – gpio_pulldown_dis
原型：esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num)
參數：gpio_num: GPIO number
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Disable pull-down on GPIO.
範例：

功能 – gpio_install_isr_service
原型：esp_err_t gpio_install_isr_service(int intr_alloc_flags)
參數：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.
返回：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
說明：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.
範例：

功能 – gpio_uninstall_isr_service
原型：void gpio_uninstall_isr_service()
參數：無
返回：無
說明：Uninstall the driver’s GPIO ISR service, freeing related resources.
範例：

功能 – gpio_isr_handler_add
原型：esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void *args)
參數：gpio_num: GPIO number

          isr_handler: ISR handler function for the corresponding GPIO number.

          args: parameter for ISR handler.
返回：ESP_OK Success

          ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.

          ESP_ERR_INVALID_ARG Parameter error
說明：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.
範例：

功能 – gpio_isr_handler_remove
原型：esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num)
參數：gpio_num: GPIO number
返回：ESP_OK Success

          ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.

          ESP_ERR_INVALID_ARG Parameter error
說明：Remove ISR handler for the corresponding GPIO pin.
範例：

功能 – gpio_config
原型：esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength)
參數：gpio_num: GPIO number, only support output GPIOs

           strength: Drive capability of the pad
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error
說明：Set GPIO pad drive capability.
範例：

功能 – gpio_get_drive_capability
原型：esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength)
參數： gpio_num: GPIO number, only support output GPIOs

           strength: Pointer to accept drive capability of the pad
返回：ESP_OK Success

          ESP_ERR_INVALID_ARG Parameter error

說明：Get GPIO pad drive capability.
範例：

功能 – gpio_hold_en
原型：esp_err_t gpio_hold_en(gpio_num_t gpio_num)
參數：gpio_num: GPIO number, only support output-capable GPIOs
返回：ESP_OK Success

          ESP_ERR_NOT_SUPPORTED Not support pad hold function
說明：Set gpio pad hold function.

The gpio pad hold function works in both input and output modes, but must be output-capable gpios. If pad hold enabled: in output mode: the output level of the pad will be force locked and can not be changed. in input mode: the input value read will not change, regardless the changes of input signal.

Power down or call gpio_hold_dis will disable this function.
範例：

功能 – gpio_hold_dis
原型：esp_err_t gpio_hold_dis(gpio_num_t gpio_num)
參數：gpio_num: GPIO number, only support output-capable GPIOs
返回：ESP_OK Success

          ESP_ERR_NOT_SUPPORTED Not support pad hold function
說明：Unset gpio pad hold function.
範例：

功能 – gpio_iomux_in
原型：void gpio_iomux_in(uint32_t gpio_num, uint32_t signal_idx)
參數：gpio_num: GPIO number of the pad.

           signal_idx: Peripheral signal id to input. One of the *_IN_IDX signals in soc/gpio_sig_map.h.
返回：無
說明：Set pad input to a peripheral signal through the IOMUX.
範例：

功能 – gpio_iomux_out
原型：void gpio_iomux_out(uint8_t gpio_num, int func, bool oen_inv)
參數：gpio_num: gpio_num GPIO number of the pad.

           func: The function number of the peripheral pin to output pin. One of the FUNC_X_* of specified pin (X) in soc/io_mux_reg.h.

           oen_inv: True if the output enable needs to be inversed, otherwise False.
返回：無
說明：Set peripheral output to an GPIO pad through the IOMUX.
範例： 

Header File：driver/include/driver/gpio.h

相關網址：
※ DIY – ESP32：ESP32 GPIO 功能資源（九）
※ DIY - ESP32：ESP32 GPIO API 函數結構件及其它（三十一）
※ DIY - ESP32：ESP32 常用 GPIO 應用程式接口函數（三十二）