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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 Qz`(%Z>FVdQ&MBb@08X;X%K!iX 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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 literal 0 HcmV?d00001 diff --git a/docs/source/api/gpio.rst b/docs/source/api/gpio.rst index 998f0436..2f63f26e 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