From fb00b51f99bd7ef950d2b2fc2c2b699f8738a218 Mon Sep 17 00:00:00 2001 From: Halysson Carvalho Date: Tue, 14 Dec 2021 10:39:54 -0300 Subject: [PATCH] [DOCS] Writing a new Arduino documentation about GPIO (#5894) * add new documation GPIO Co-authored-by: pedro.minatel --- docs/source/_static/gpio_output.png | Bin 0 -> 3504 bytes docs/source/_static/gpio_pullup.png | Bin 0 -> 4840 bytes docs/source/api/gpio.rst | 167 ++++++++++++++++++++++++++++ 3 files changed, 167 insertions(+) create mode 100644 docs/source/_static/gpio_output.png create mode 100644 docs/source/_static/gpio_pullup.png diff --git a/docs/source/_static/gpio_output.png b/docs/source/_static/gpio_output.png new file mode 100644 index 0000000000000000000000000000000000000000..877ead7ef774b0a37890cdd8dccc4e05c689b238 GIT binary patch literal 3504 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 literal 0 HcmV?d00001 diff --git a/docs/source/_static/gpio_pullup.png b/docs/source/_static/gpio_pullup.png new file mode 100644 index 0000000000000000000000000000000000000000..5c31464f4e93e70b16b0f82fb2e5de0bcd980549 GIT binary patch literal 4840 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 KNui=y;C}&5>v&fH literal 0 HcmV?d00001 diff --git a/docs/source/api/gpio.rst b/docs/source/api/gpio.rst index 998f04365..2f63f26e0 100644 --- a/docs/source/api/gpio.rst +++ b/docs/source/api/gpio.rst @@ -1,3 +1,170 @@ #### GPIO #### + +About +----- + +One of the most used and versatile peripheral in a microcontroller is the GPIO. The GPIO is commonly used to write and read the pin state. + +GPIO stands to General Purpose Input Output, and is responsible to control or read the state of a specific pin in the digital world. For example, this peripheral is widely used to create the LED blinking or to read a simple button. + +.. note:: There are some GPIOs with special restrictions, and not all GPIOs are accessible through the developemnt board. For more information about it, see the corresponding board pin layout information. + +GPIOs Modes +*********** + +There are two different modes in the GPIO configuration: + +- **Input Mode** + +In this mode, the GPIO will receive the digital state from a specific device. This device could be a button or a switch. + +- **Output Mode** + +For the output mode, the GPIO will change the GPIO digital state to a specific device. You can drive an LED for example. + +GPIO API +-------- + +Here is the common functions used for the GPIO peripheral. + +pinMode +******* + +The ``pinMode`` function is used to define the GPIO operation mode for a specific pin. + +.. code-block:: arduino + + void pinMode(uint8_t pin, uint8_t mode); + +* ``pin`` defines the GPIO pin number. +* ``mode`` sets operation mode. + +The following modes are supported for the basic `input` and `output`: + +* **INPUT** sets the GPIO as input without pullup or pulldown (high impedance). +* **OUTPUT** sets the GPIO as output/read mode. +* **INPUT_PULLDOWN** sets the GPIO as input with the internal pulldown. +* **INPUT_PULLUP** sets the GPIO as input with the internal pullup. + +Internal Pullup and Pulldown +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ESP32 SoC families supports the internal pullup and pulldown throught a 45kR resistor, that can be enabled when configuring the GPIO mode as ``INPUT`` mode. +If the pullup or pulldown mode is not defined, the pin will stay in the high impedance mode. + +digitalWrite +************* + +The function ``digitalWrite`` sets the state of the selected GPIO to ``HIGH`` or ``LOW``. This function is only used if the ``pinMode`` was configured as ``OUTPUT``. + +.. code-block:: arduino + + void digitalWrite(uint8_t pin, uint8_t val); + +* ``pin`` defines the GPIO pin number. +* ``val`` set the output digital state to ``HIGH`` or ``LOW``. + +digitalRead +*********** + +To read the state of a given pin configured as ``INPUT``, the function ``digitalRead`` is used. + +.. code-block:: arduino + + int digitalRead(uint8_t pin); + +* ``pin`` select GPIO + +This function will return the logical state of the selected pin as ``HIGH`` or ``LOW``. + +Interrupts +---------- + +The GPIO peripheral on the ESP32 supports interruptions. + +attachInterrupt +*************** + +The function ``attachInterruptArg`` is used to attach the interrupt to the defined pin. + +.. code-block:: arduino + + attachInterrupt(uint8_t pin, voidFuncPtr handler, int mode); + +* ``pin`` defines the GPIO pin number. +* ``handler`` set the handler function. +* ``mode`` set the interrupt mode. + +Here are the supported interrupt modes: + +* **DISABLED** +* **RISING** +* **FALLING** +* **CHANGE** +* **ONLOW** +* **ONHIGH** +* **ONLOW_WE** +* **ONHIGH_WE** + +attachInterruptArg +****************** + +The function ``attachInterruptArg`` is used to attach the interrupt to the defined pin using arguments. + +.. code-block:: arduino + + attachInterruptArg(uint8_t pin, voidFuncPtrArg handler, void * arg, int mode); + +* ``pin`` defines the GPIO pin number. +* ``handler`` set the handler function. +* ``arg`` pointer to the interrupt arguments. +* ``mode`` set the interrupt mode. + +detachInterrupt +*************** + +To detach the interruption from a specific pin, use the ``detachInterrupt`` function giving the GPIO to be detached. + +.. code-block:: arduino + + detachInterrupt(uint8_t pin); + +* ``pin`` defines the GPIO pin number. + +.. _gpio_example_code: + +Example Code +------------ + +GPIO Input and Output Modes +*************************** + +.. code-block:: arduino + + #define LED 12 + #define BUTTON 2 + + uint8_t stateLED = 0; + + void setup() { + pinMode(LED, OUTPUT); + pinMode(BUTTON,INPUT_PULLUP); + } + + void loop() { + + if(!digitalRead(BUTTON)){ + stateLED = stateLED^1; + digitalWrite(LED,stateLED); + } + } + +GPIO Interrupt +************** + +.. literalinclude:: ../../../libraries/ESP32/examples/GPIO/GPIOInterrupt/GPIOInterrupt.ino + :language: arduino + +.. _datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf