From 7a35be3e7e8777a449542de87ec80eff8889029e Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 20 Sep 2021 12:00:52 +0100 Subject: [PATCH 1/3] Added blink example with Wokwi embedded simulation --- docs/source/tutorials/blink.rst | 109 ++++++++++++++++++++++++++++ docs/source/tutorials/tutorials.rst | 1 + 2 files changed, 110 insertions(+) create mode 100644 docs/source/tutorials/blink.rst diff --git a/docs/source/tutorials/blink.rst b/docs/source/tutorials/blink.rst new file mode 100644 index 00000000000..4250a5fe68a --- /dev/null +++ b/docs/source/tutorials/blink.rst @@ -0,0 +1,109 @@ +########################## +Blink Interactive Tutorial +########################## + +Introduction +------------ + +This is the interactive blink tutorial using `Wokwi`_. For this tutorial you don't need the ESP32 board or the Arduino toolchain. + +.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the code from `Wokwi`_ editor and use on the Arduino IDE or PlatformIO. + +About this Tutorial +------------------- + +This tutorial is the most basic for any getting started. In this tutorial, we will show how to set a GPIO pin as output to drive a LED to blink each 1 second. + +Step by step +------------ + +In order to make this simple blink tutorial, you'll need to do the following steps. + +1. Define the GPIO for the LED. + +.. code-block:: + + #define LED 2 + +This ``#define LED 2`` will be used to set the GPIO2 as the ``LED`` output pin. + +2. Setup. + +Inside the ``setup()`` function, we need to add all things we want to run once during the startup. +Here we'll add the ``pinMode`` function to set the pin as output. + +.. code-block:: + + void setup() { + pinMode(LED, OUTPUT); + } + +The first argument is the GPIO number, already defined and the second is the mode, here defined as output. + +3. Main Loop. + +After the ``setup``, the code runs the ``loop`` function infinitely. Here we will handle the GPIO in order to get the LED blinking. + +.. code-block:: + + void loop() { + digitalWrite(LED, HIGH); + delay(100); + digitalWrite(LED, LOW); + delay(100); + } + +The first function is the ``digitalWrite()`` with two arguments: + +* GPIO: Set the GPIO pin. Here defined by our ``LED`` connected to the GPIO2. +* State: Set the GPIO state as HIGH (on) or LOW (off). + +This first ``digitalWrite`` we will set the LED on. + +After the ``digitalWrite``, we will set a ``delay`` function in order to wait for some time, defined in milliseconds. + +Now we can set the GPIO to ``LOW`` to turn the LED off and ``delay`` for more few milliseconds to get the LED blinking. + +4. Run the code. + +To run this code, you'll need a development board and the Arduino toolchain installed in your computer. If you don't have both, you can use the simulator to test and edit the code. + +Simulation +---------- + +This simulator is provided by `Wokwi`_ and you can test the blink code and play with some modification to learn mode about this example. + +.. raw:: html + + + +Change the parameters, like the delay period, to test the code right on your browser. You can add more LEDs, change the GPIO and more. + +Code +---- + +Here is the full blink code. + +.. code-block:: + + #define LED 2 + + void setup() { + pinMode(LED, OUTPUT); + } + + void loop() { + digitalWrite(LED, HIGH); + delay(100); + digitalWrite(LED, LOW); + delay(100); + } + +Resources +--------- + +* `ESP32 Datasheet`_ (Datasheet) +* `Wokwi`_ (Wokwi Website) + +.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf +.. _Wokwi: https://wokwi.com/ \ No newline at end of file diff --git a/docs/source/tutorials/tutorials.rst b/docs/source/tutorials/tutorials.rst index 15d3f463375..57eead06f31 100644 --- a/docs/source/tutorials/tutorials.rst +++ b/docs/source/tutorials/tutorials.rst @@ -6,6 +6,7 @@ Tutorials :maxdepth: 2 :caption: Tutorials: + Blink Basic DFU GPIO Matrix and Pin Mux From e1cdbd7816e2c8255fe5227cba62e0684823201e Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 20 Sep 2021 12:39:05 +0100 Subject: [PATCH 2/3] Minor changes on the blink tutorial --- docs/source/tutorials/blink.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/tutorials/blink.rst b/docs/source/tutorials/blink.rst index 4250a5fe68a..4de4c269128 100644 --- a/docs/source/tutorials/blink.rst +++ b/docs/source/tutorials/blink.rst @@ -5,9 +5,9 @@ Blink Interactive Tutorial Introduction ------------ -This is the interactive blink tutorial using `Wokwi`_. For this tutorial you don't need the ESP32 board or the Arduino toolchain. +This is the interactive blink tutorial using `Wokwi`_. For this tutorial, you don't need the ESP32 board or the Arduino toolchain. -.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the code from `Wokwi`_ editor and use on the Arduino IDE or PlatformIO. +.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use on the Arduino IDE or PlatformIO. About this Tutorial ------------------- @@ -79,8 +79,10 @@ This simulator is provided by `Wokwi`_ and you can test the blink code and play Change the parameters, like the delay period, to test the code right on your browser. You can add more LEDs, change the GPIO and more. -Code ----- +.. _blink_example_code: + +Example Code +------------ Here is the full blink code. From 8be2f7b1cc152dd66538676dee308f24ae32b098 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Tue, 21 Sep 2021 14:34:21 +0100 Subject: [PATCH 3/3] Changes according to the PR review --- docs/source/tutorials/blink.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/source/tutorials/blink.rst b/docs/source/tutorials/blink.rst index 4de4c269128..f65af1b3bae 100644 --- a/docs/source/tutorials/blink.rst +++ b/docs/source/tutorials/blink.rst @@ -7,19 +7,19 @@ Introduction This is the interactive blink tutorial using `Wokwi`_. For this tutorial, you don't need the ESP32 board or the Arduino toolchain. -.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use on the Arduino IDE or PlatformIO. +.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE`_ or `PlatformIO`_. About this Tutorial ------------------- -This tutorial is the most basic for any getting started. In this tutorial, we will show how to set a GPIO pin as output to drive a LED to blink each 1 second. +This tutorial is the most basic for any get started. In this tutorial, we will show how to set a GPIO pin as an output to drive a LED to blink each 1 second. Step by step ------------ In order to make this simple blink tutorial, you'll need to do the following steps. -1. Define the GPIO for the LED. +1. **Define the GPIO for the LED.** .. code-block:: @@ -27,7 +27,7 @@ In order to make this simple blink tutorial, you'll need to do the following ste This ``#define LED 2`` will be used to set the GPIO2 as the ``LED`` output pin. -2. Setup. +2. **Setup.** Inside the ``setup()`` function, we need to add all things we want to run once during the startup. Here we'll add the ``pinMode`` function to set the pin as output. @@ -38,9 +38,9 @@ Here we'll add the ``pinMode`` function to set the pin as output. pinMode(LED, OUTPUT); } -The first argument is the GPIO number, already defined and the second is the mode, here defined as output. +The first argument is the GPIO number, already defined and the second is the mode, here defined as an output. -3. Main Loop. +3. **Main Loop.** After the ``setup``, the code runs the ``loop`` function infinitely. Here we will handle the GPIO in order to get the LED blinking. @@ -56,28 +56,28 @@ After the ``setup``, the code runs the ``loop`` function infinitely. Here we wil The first function is the ``digitalWrite()`` with two arguments: * GPIO: Set the GPIO pin. Here defined by our ``LED`` connected to the GPIO2. -* State: Set the GPIO state as HIGH (on) or LOW (off). +* State: Set the GPIO state as HIGH (ON) or LOW (OFF). -This first ``digitalWrite`` we will set the LED on. +This first ``digitalWrite`` we will set the LED ON. After the ``digitalWrite``, we will set a ``delay`` function in order to wait for some time, defined in milliseconds. Now we can set the GPIO to ``LOW`` to turn the LED off and ``delay`` for more few milliseconds to get the LED blinking. -4. Run the code. +4. **Run the code.** -To run this code, you'll need a development board and the Arduino toolchain installed in your computer. If you don't have both, you can use the simulator to test and edit the code. +To run this code, you'll need a development board and the Arduino toolchain installed on your computer. If you don't have both, you can use the simulator to test and edit the code. Simulation ---------- -This simulator is provided by `Wokwi`_ and you can test the blink code and play with some modification to learn mode about this example. +This simulator is provided by `Wokwi`_ and you can test the blink code and play with some modifications to learn more about this example. .. raw:: html -Change the parameters, like the delay period, to test the code right on your browser. You can add more LEDs, change the GPIO and more. +Change the parameters, like the delay period, to test the code right on your browser. You can add more LEDs, change the GPIO, and more. .. _blink_example_code: @@ -108,4 +108,6 @@ Resources * `Wokwi`_ (Wokwi Website) .. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf -.. _Wokwi: https://wokwi.com/ \ No newline at end of file +.. _Wokwi: https://wokwi.com/ +.. _PlatformIO: https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#platformio +.. _Arduino IDE: https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-boards-manager \ No newline at end of file