mirror of
https://github.com/0xFEEDC0DE64/arduino-esp32.git
synced 2025-07-29 02:07:15 +02:00
Docs: Initial documentation structure using Sphinx (#5355)
This PR is the initial documentation structure including the basic information about the project and Sphinx configuration. ####CONTENTS: - Getting Started - Installing - Boards - Libraries - Library Builder - Tutorials - ESP-IDF as Component - OTA Web Update - makeEspArduino - Troubleshooting - Contributing This PR also changes the README.md.
This commit is contained in:
Pedro Minatel
GitHub
92
docs/source/tutorials/basic.rst
Normal file
92
docs/source/tutorials/basic.rst
Normal file
@ -0,0 +1,92 @@
|
||||
##############
|
||||
Basic Tutorial
|
||||
##############
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This is the basic tutorial and should be used as template for other tutorials.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
* Arduino IDE
|
||||
* ESP32 Board
|
||||
* Good USB Cable
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
Here are the steps for this tutorial.
|
||||
|
||||
1. Open the Arduino IDE
|
||||
|
||||
.. figure:: ../_static/tutorials/basic/tutorial_basic_ide.png
|
||||
:align: center
|
||||
:width: 600
|
||||
:alt: Arduino IDE (click to enlarge)
|
||||
:figclass: align-center
|
||||
|
||||
2. Build and Flash the `blink` project.
|
||||
|
||||
Code
|
||||
----
|
||||
|
||||
.. code-block:: arduino
|
||||
:caption: Blink.ino
|
||||
|
||||
/*
|
||||
Blink
|
||||
|
||||
Turns an LED on for one second, then off for one second, repeatedly.
|
||||
|
||||
Most Arduinos have an on-board LED you can control. On the UNO, MEGA and ZERO
|
||||
it is attached to digital pin 13, on MKR1000 on pin 6. LED_BUILTIN is set to
|
||||
the correct LED pin independent of which board is used.
|
||||
If you want to know what pin the on-board LED is connected to on your Arduino
|
||||
model, check the Technical Specs of your board at:
|
||||
https://www.arduino.cc/en/Main/Products
|
||||
|
||||
modified 8 May 2014
|
||||
by Scott Fitzgerald
|
||||
modified 2 Sep 2016
|
||||
by Arturo Guadalupi
|
||||
modified 8 Sep 2016
|
||||
by Colby Newman
|
||||
|
||||
This example code is in the public domain.
|
||||
|
||||
http://www.arduino.cc/en/Tutorial/Blink
|
||||
*/
|
||||
|
||||
// the setup function runs once when you press reset or power the board
|
||||
void setup() {
|
||||
// initialize digital pin LED_BUILTIN as an output.
|
||||
pinMode(LED_BUILTIN, OUTPUT);
|
||||
}
|
||||
|
||||
// the loop function runs over and over again forever
|
||||
void loop() {
|
||||
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
|
||||
delay(1000); // wait for a second
|
||||
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
|
||||
delay(1000); // wait for a second
|
||||
}
|
||||
|
||||
Log Output
|
||||
----------
|
||||
|
||||
If the log output from the serial monitor is relevant, please add here:
|
||||
|
||||
.. code-block::
|
||||
|
||||
I (0) cpu_start: App cpu up.
|
||||
I (418) cpu_start: Pro cpu start user code
|
||||
I (418) cpu_start: cpu freq: 160000000
|
||||
|
||||
Resources
|
||||
---------
|
||||
|
||||
* `ESP32 Datasheet`_ (Datasheet)
|
||||
|
||||
.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
|
||||
6
docs/source/tutorials/dfu.rst
Normal file
6
docs/source/tutorials/dfu.rst
Normal file
@ -0,0 +1,6 @@
|
||||
###
|
||||
DFU
|
||||
###
|
||||
|
||||
.. note::
|
||||
DFU is only supported by the ESP32-S2.
|
||||
121
docs/source/tutorials/io_mux.rst
Normal file
121
docs/source/tutorials/io_mux.rst
Normal file
@ -0,0 +1,121 @@
|
||||
#######################
|
||||
GPIO Matrix and Pin Mux
|
||||
#######################
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This is a basic introduction on how the peripherals work in the ESP32. This tutorial can be used to understand
|
||||
how to define the peripheral usage and its corresponding pins.
|
||||
|
||||
In some microcontrollers' architecture, the peripherals are attached to specific pins and cannot be redefined to another one.
|
||||
|
||||
For example.
|
||||
|
||||
The *XYZ* MCU defines that the I2C peripheral SDA signal is the IO5 on the physical pin 10 and the SCL is on the IO6 and physical pin 11.
|
||||
|
||||
This means that, in your hardware project, you **NEED** to use these pins as the I2C and this cannot be changed due to the internal architecture.
|
||||
In this case, you must be very careful during the hardware design to not make any mistake by switching the SDA and SCL connections. Firmware will not help you if you do so.
|
||||
|
||||
GPIO Matrix and Pin Mux
|
||||
-----------------------
|
||||
|
||||
The ESP32 architecture includes the capability of configuring some peripherals to any of the GPIOs pins, managed by the `IO MUX GPIO`_.
|
||||
Essentially, this capability means that we can route the internal peripheral into a different physical pin using the IO MUX and the GPIO Matrix.
|
||||
|
||||
.. figure:: ../_static/tutorials/peripherals/tutorial_peripheral_diagram.png
|
||||
:align: center
|
||||
:width: 600
|
||||
:figclass: align-center
|
||||
|
||||
It means that in the scenario of the *XYZ* MCU, in the ESP32 we can use any of the GPIOs to route the SDA (input/output) and the SCL (output).
|
||||
|
||||
To use this functionality, we must be aware of some precautions:
|
||||
|
||||
* Some of the GPIOs are **INPUT** only.
|
||||
* Some peripherals have output signals and must be used on GPIO's capable to be configured as **OUTPUT**.
|
||||
* Some peripherals, mostly the high speed ones, ADC, DAC, Touch, and JTAG use dedicated GPIOs pins.
|
||||
|
||||
.. warning::
|
||||
Before assigning the peripheral pins in your design, double check if the pins you're using are appropriate.
|
||||
The input-only pins cannot be used for peripherals that require output or input/output signals.
|
||||
|
||||
The greatest advantage of this functionality is the fact that we don't need to be fully dependent on the physical pin, since we can change according to our needs.
|
||||
This can facilitate the hardware design routing or in some cases, fix some pin swap mistake during the hardware design phase.
|
||||
|
||||
Peripherals
|
||||
-----------
|
||||
|
||||
Here is the basic peripherals list present on the `ESP32`_. The peripheral list may vary from each ESP32 SoC family.
|
||||
To see all peripherals available on the `ESP32-S2`_ and `ESP32-C3`_, check each of the datasheets.
|
||||
|
||||
Peripheral Table
|
||||
****************
|
||||
|
||||
============================== ===================================
|
||||
Type Function
|
||||
============================== ===================================
|
||||
ADC Dedicated GPIOs
|
||||
DAC Dedicated GPIOs
|
||||
Touch Sensor Dedicated GPIOs
|
||||
JTAG Dedicated GPIOs
|
||||
SD/SDIO/MMC HostController Dedicated GPIOs
|
||||
Motor PWM Any GPIO
|
||||
SDIO/SPI SlaveController Dedicated GPIOs
|
||||
UART Any GPIO
|
||||
I2C Any GPIO
|
||||
I2S Any GPIO
|
||||
LED PWM Any GPIO
|
||||
RMT Any GPIO
|
||||
GPIO Any GPIO
|
||||
Parallel QSPI Dedicated GPIOs
|
||||
EMAC Dedicated GPIOs
|
||||
Pulse Counter Any GPIO
|
||||
TWAI Any GPIO
|
||||
============================== ===================================
|
||||
|
||||
This table is present on each datasheet provided by Espressif.
|
||||
|
||||
Usage Examples
|
||||
--------------
|
||||
|
||||
In the Arduino Uno, we have the I2C pins defined by hardware, A4 is the SDA and A5 the SCL. In this case, we do not need to set
|
||||
these pins in the ``Wire.begin();`` function, because they are already into the Wire library.
|
||||
|
||||
.. code-block:: arduino
|
||||
|
||||
void setup()
|
||||
{
|
||||
Wire.begin(); // join i2c bus (address optional for master)
|
||||
}
|
||||
|
||||
Now, for the ESP32, the default pins for the I2C are SDA (GPIO21) and SCL (GPIO22). We can use a different pin as alternative for the
|
||||
default ones if you need to change the pins.
|
||||
To change the pins, we must call the ``Wire.setPins(int sda, int scl);`` function before calling ``Wire.begin();``.
|
||||
|
||||
.. code-block:: arduino
|
||||
|
||||
int sda_pin = 16; // GPIO16 as I2C SDA
|
||||
int scl_pin = 17; // GPIO17 as I2C SCL
|
||||
|
||||
void setup()
|
||||
{
|
||||
Wire.setPins(sda_pin, scl_pin); // Set the I2C pins before begin
|
||||
Wire.begin(); // join i2c bus (address optional for master)
|
||||
}
|
||||
|
||||
A similar approach also applies for the other peripherals.
|
||||
|
||||
Resources
|
||||
---------
|
||||
|
||||
* `ESP32`_ (Datasheet)
|
||||
* `ESP32-S2`_ (Datasheet)
|
||||
* `ESP32-C3`_ (Datasheet)
|
||||
|
||||
.. _Espressif Systems: https://www.espressif.com
|
||||
.. _Espressif Product Selector: https://products.espressif.com/
|
||||
.. _ESP32: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf
|
||||
.. _ESP32-S2: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
|
||||
.. _ESP32-C3: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
|
||||
.. _IO MUX GPIO: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#iomuxgpio
|
||||
11
docs/source/tutorials/tutorials.rst
Normal file
11
docs/source/tutorials/tutorials.rst
Normal file
@ -0,0 +1,11 @@
|
||||
#########
|
||||
Tutorials
|
||||
#########
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Tutorials:
|
||||
|
||||
Basic <basic>
|
||||
DFU <dfu>
|
||||
GPIO Matrix and Pin Mux <io_mux>
|
||||
Reference in New Issue
Block a user