alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-09-30 19:19:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update IDF getting started sections for make and cmake as well as IDF monitor…

Browse Source
This commit is contained in:
Kirill Chalov
2019-03-14 00:10:26 +08:00
committed by Krzysztof Budzynski
parent d34ca0b897
commit 49cca9288f
35 changed files with 1419 additions and 1303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
docs/en/get-started/get-started-devkitc-v2.rst
View File

@@ -1,79 +1,82 @@
ESP32-DevKitC V2 Getting Started Guide
======================================
This user guide shows how to get started with ESP32-DevKitC development board.
What You Need
-------------
* 1 × :ref:`ESP32-DevKitC V2 board <get-started-esp32-devkitc-v2-board-front>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-DevKitC is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC board.
ESP-WROOM-32
Standard `ESP-WROOM-32 <https://www.espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ module soldered to the ESP32-DevKitC board.
EN
Reset button: pressing this button resets the system.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
USB
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP-WROOM-32.
I/O
Most of the pins on the ESP-WROOM-32 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
.. _get-started-esp32-devkitc-v2-board-front:
.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png
:align: center
:alt: ESP32-DevKitC V2 board layout
:figclass: align-center
ESP32-DevKitC V2 board layout
Power Supply Options
--------------------
There following options are available to provide power supply to this board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Start Application Development
------------------------------
Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Related Documents
-----------------
* `ESP32-DevKitC schematic <https://dl.espressif.com/dl/schematics/ESP32-Core-Board-V2_sch.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
ESP32-DevKitC V2 Getting Started Guide (CMake)
==============================================
:link_to_translation:`zh_CN:[中文]`
This guide shows how to start using the ESP32-DevKitC V2 development board.
What You Need
-------------
* ESP32-DevKitC V2 board
* USB A / micro USB B cable
* Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section `Start Application Development`_.
Overview
--------
ESP32-DevKitC V2 is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard.
Functional Description
----------------------
The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC V2 board.
.. _get-started-esp32-devkitc-v2-board-front-make:
.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png
:align: center
:alt: ESP32-DevKitC V2 board layout
:figclass: align-center
ESP32-DevKitC V2 board layout
+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Key Component | Description |
+=====================+=========================================================================================================================================================================================+
| ESP32-WROOM-32 | Standard module with ESP32 at its core. For more information, see `ESP32-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ |
+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| EN | Reset button. |
+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Boot | Download button. Holding down **Boot** and then pressing **EN** initiates Firmware Download mode for downloading firmware through the serial port. |
+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Micro USB Port | USB interface. Power supply for the board as well as the communication interface between a computer and ESP32-WROOM-32. |
+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| I/O | Most of the pins on the ESP module are broken out to the pin headers on the board. You can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. |
+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Power Supply Options
--------------------
There are three mutually exclusive ways to provide power to the board:
* Micro USB port, default power supply
* 5V / GND header pins
* 3V3 / GND header pins
.. warning::
The power supply must be provided using **one and only one of the options above**, otherwise the board and/or the power supply source can be damaged.
Start Application Development
------------------------------
Before powering up your ESP32-DevKitC V2, please make sure that the board is in good condition with no obvious signs of damage.
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents
-----------------
* `ESP32-DevKitC schematics <https://dl.espressif.com/dl/schematics/ESP32-Core-Board-V2_sch.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ (PDF)

287
docs/en/get-started/get-started-devkitc.rst
View File

@@ -1,134 +1,153 @@
ESP32-DevKitC V4 Getting Started Guide
======================================
:link_to_translation:`zh_CN:[中文]`
This user guide shows how to get started with ESP32-DevKitC V4 development board. For description of other versions of the ESP32-DevKitC check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the female pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard female headers also make development easy and convenient when using Dupont wires.
The board supports various ESP32 modules, including :ref:`esp-modules-and-boards-esp32-wroom-32`, :ref:`ESP32-WROOM-32U <esp-modules-and-boards-esp32-wroom-32d-and-u>`, :ref:`ESP32-WROOM-32D <esp-modules-and-boards-esp32-wroom-32d-and-u>`, :ref:`esp-modules-and-boards-esp32-solo-1`, and :ref:`esp-modules-and-boards-esp32-wrover` series.
.. note::
Espressif also provides several variants of ESP32-DevKitC that come with specific ESP32 module and female or male pin headers, supporting different requirements of different users. For details please refer to `Espressif Product Ordering Information`_.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC V4 board.
ESP32-WROOM-32D
:ref:`ESP32-WROOM-32D <esp-modules-and-boards-esp32-wroom-32d-and-u>` soldered to the ESP32-DevKitC V4 board.
Optional Space for ESP32-WROVER
Longer :ref:`esp-modules-and-boards-esp32-wrover` modules may be soldered instead of the ESP32-WROOM-32.
USB-to-UART Bridge
A single chip USB-to-UART bridge provides up to 3 Mbps transfers rates.
Boot Button
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
EN Button
Reset button: pressing this button resets the system.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and the ESP module.
Power On LED
Turns on when the power supply is applied to the board. For details see schematic in `Related Documents`_.
I/O Connector
Most of the pins on the ESP module are broken out to the female pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
.. note::
Some of broken out pins are used internally by the ESP32-WROOM-32, ESP32-WROOM-32D/U and ESP32-SOLO-1 modules to communicate with SPI memory. They are grouped on one side of the board besides the USB connector and labeled CLK, D0, D1, D2, D3 and CMD (GPIO6 - GPIO11). In general these pins should be left unconnected, otherwise access to the SPI flash memory / SPI RAM may be disturbed.
.. _get-started-esp32-devkitc-board-front:
.. figure:: ../../_static/esp32-devkitc-functional-overview-f.jpeg
:align: center
:alt: ESP32-DevKitC V4 with ESP32-WROOM-32 module soldered
:figclass: align-center
ESP32-DevKitC V4 with ESP32-WROOM-32D module soldered
Power Supply Options
--------------------
There following options are available to provide power supply to this board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Note on C15
-----------
The C15, on the board of earlier batches of V4, may bring two issues:
1. The board may boot into download mode;
2. If users output clock on GPIO0, C15 may impact the clock output.
As a result, if users believe that C15 will impact their use of the board, they can remove it completely (please refer to the screenshot below for the precise location of C15 that is colored in yellow). Otherwise, users do not need to concern about C15.
.. figure:: ../../_static/esp32-devkitc-c15-location.png
:align: center
:alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board
:figclass: align-center
:width: 30%
Location of C15 (colored yellow) on ESP32-DevKitC V4 board
Start Application Development
------------------------------
Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Board Dimensions
----------------
.. figure:: ../../_static/esp32-devkitc-v4-dimensions-back.jpeg
:align: center
:alt: ESP32-DevKitC board dimensions - back
:figclass: align-center
ESP32-DevKitC board dimensions - back
Related Documents
-----------------
* `ESP32-DevKitC V4 schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROOM-32D/U Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_en.pdf>`_ (PDF)
* `Espressif Product Ordering Information <https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>`_ (PDF)
.. toctree::
:hidden:
get-started-devkitc-v2
ESP32-DevKitC V4 Getting Started Guide
======================================
:link_to_translation:`zh_CN:[中文]`
This guide shows how to start using the ESP32-DevKitC V4 development board. For description of other versions of ESP32-DevKitC check :doc:`../hw-reference/index`.
What You Need
-------------
* ESP32-DevKitC V4 board
* USB A / micro USB B cable
* Computer running Windows, Linux, or macOS
You can skip the introduction sections and go directly to Section `Start Application Development`_.
.. _DevKitC-Overview:
Overview
--------
ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard.
To cover a wide range of user requirements, the following versions of ESP32-DevKitC V4 are available:
- different ESP32 modules
- :ref:`esp-modules-and-boards-esp32-wroom-32`
- :ref:`ESP32-WROOM-32D <esp-modules-and-boards-esp32-wroom-32d-and-u>`
- :ref:`ESP32-WROOM-32U <esp-modules-and-boards-esp32-wroom-32d-and-u>`
- :ref:`esp-modules-and-boards-esp32-solo-1`
- :ref:`ESP32-WROVER <esp-modules-and-boards-esp32-wrover>`
- :ref:`ESP32-WROVER-B <esp-modules-and-boards-esp32-wrover>`
- :ref:`ESP32-WROVER-I <esp-modules-and-boards-esp32-wrover>`
- :ref:`ESP32-WROVER-B (IPEX) <esp-modules-and-boards-esp32-wrover>`
- male or female pin headers.
For details please refer to `Espressif Product Ordering Information`_.
Functional Description
----------------------
The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC V4 board.
.. _get-started-esp32-devkitc-board-front:
.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg
:align: center
:alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
:figclass: align-center
ESP32-DevKitC V4 with ESP32-WROOM-32 module soldered
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Key Component | Description |
+====================+======================================================================================================================================================================================+
| ESP32-WROOM-32 | A module with ESP32 at its core. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| EN | Reset button. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Boot | Download button. Holding down **Boot** and then pressing **EN** initiates Firmware Download mode for downloading firmware through the serial port. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| USB-to-UART Bridge | Single USB-UART bridge chip provides transfer rates of up to 3 Mbps. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Micro USB Port | USB interface. Power supply for the board as well as the communication interface between a computer and the ESP32 module. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 5V Power On LED | Turns on when the USB or an external 5V power supply is connected to the board. For details see the schematics in `Related Documents`_. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| I/O | Most of the pins on the ESP module are broken out to the pin headers on the board. You can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. note::
The pins D0, D1, D2, D3, CMD and CLK are used internally for communication between ESP32 and SPI flash memory. They are grouped on both sides near the USB connector. Avoid using these pins, as it may disrupt access to the SPI flash memory / SPI RAM.
.. note::
The pins GPIO16 and GPIO17 are available for use only on the boards with the modules ESP32-WROOM and ESP32-SOLO-1. The boards with ESP32-WROVER modules have the pins reserved for internal use.
Power Supply Options
--------------------
There are three mutually exclusive ways to provide power to the board:
* Micro USB port, default power supply
* 5V / GND header pins
* 3V3 / GND header pins
.. warning::
The power supply must be provided using **one and only one of the options above**, otherwise the board and/or the power supply source can be damaged.
Note on C15
-----------
The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boards:
* The board may boot into Download mode
* If you output clock on GPIO0, C15 may impact the signal
In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow.
.. figure:: ../../_static/esp32-devkitc-c15-location.png
:align: center
:alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board
:figclass: align-center
:width: 30%
Location of C15 (yellow) on ESP32-DevKitC V4 board
Start Application Development
------------------------------
Before powering up your ESP32-DevKitC V4, please make sure that the board is in good condition with no obvious signs of damage.
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Board Dimensions
----------------
.. figure:: ../../_static/esp32-devkitc-dimensions-back.jpg
:align: center
:alt: ESP32 DevKitC board dimensions - back
:figclass: align-center
ESP32 DevKitC board dimensions - back
Related Documents
-----------------
* `ESP32-DevKitC V4 schematics <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROOM-32D & ESP32-WROOM-32U Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER-B Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_en.pdf>`_ (PDF)
* `Espressif Product Ordering Information <https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>`_ (PDF)
.. toctree::
:hidden:
get-started-devkitc-v2

9
docs/en/get-started/get-started-pico-kit-v3.rst
View File

@@ -47,14 +47,9 @@ BOOT Button
Start Application Development
------------------------------
Before powering up the ESP32-PICO-KIT V3, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP32-PICO-KIT V3, please make sure that the board is in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

9
docs/en/get-started/get-started-pico-kit.rst
View File

@@ -92,14 +92,9 @@ The following options are available to provide power supply to the ESP32-PICO-KI
Start Application Development
-----------------------------
Before powering up the ESP32-PICO-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP32-PICO-KIT, please make sure that the board is in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Pin Descriptions

9
docs/en/get-started/get-started-wrover-kit-v2.rst
View File

@@ -140,7 +140,7 @@ There are five jumper headers available to set up the board functionality. Typic
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP-WROVER-KIT V2, please make sure that the board is in good condition with no obvious signs of damage.
Initial Setup
@@ -161,12 +161,7 @@ Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

9
docs/en/get-started/get-started-wrover-kit-v3.rst
View File

@@ -365,7 +365,7 @@ LCD / U5
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP-WROVER-KIT V3, please make sure that the board is in good condition with no obvious signs of damage.
Initial Setup
@@ -386,12 +386,7 @@ Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP-WROVER-KIT, proceed to the :doc:`index` section which will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

9
docs/en/get-started/get-started-wrover-kit.rst
View File

@@ -314,7 +314,7 @@ LCD / U5
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP-WROVER-KIT, please make sure that the board is in good condition with no obvious signs of damage.
Initial Setup
@@ -335,12 +335,7 @@ Turn the **Power Switch** on. The **5V Power On LED** should turn on.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP-WROVER-KIT, proceed to the :doc:`index` section which will walk you through the following steps:
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

218
docs/en/get-started/idf-monitor.rst
View File

@@ -1,218 +0,0 @@
***********
IDF Monitor
***********
:link_to_translation:`zh_CN:[中文]`
The IDF Monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF.
It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features.
Interacting With IDF Monitor
============================
- ``Ctrl-]`` will exit the monitor.
- ``Ctrl-T Ctrl-H`` will display a help menu with all other keyboard shortcuts.
- Any other key apart from ``Ctrl-]`` and ``Ctrl-T`` is sent through the serial port.
Automatically Decoding Addresses
================================
Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, IDF Monitor will use addr2line_ to look up the source code location and function name.
.. highlight:: none
When an esp-idf app crashes and panics a register dump and backtrace such as this is produced::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
IDF Monitor will augment the dump::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
Behind the scenes, the command IDF Monitor runs to decode each address is::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
Launch GDB for GDBStub
======================
By default, if an esp-idf app crashes then the panic handler prints registers and a stack dump as shown above, and then resets.
Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
Behind the scenes, the command IDF Monitor runs is::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
Quick Compile and Flash
=======================
The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause IDF Monitor, run the ``make flash`` target, then resume IDF Monitor. Any changed source files will be recompiled before re-flashing.
The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause IDF Monitor, run the ``make app-flash`` target, then resume IDF Monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed.
Quick Reset
===========
The keyboard shortcut ``Ctrl-T Ctrl-R`` will reset the target board via the RTS line (if it is connected.)
Pause the Application
=====================
The keyboard shortcut ``Ctrl-T Ctrl-P`` will reset the target into bootloader, so that the board will run nothing. This is
useful when you want to wait for another device to startup. Then shortcut ``Ctrl-T Ctrl-R`` can be used to restart the
application.
Toggle Output Display
=====================
Sometimes you may want to stop new output printed to screen, to see the log before. The keyboard shortcut ``Ctrl-T Ctrl-Y`` will
toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert
again quickly without quitting the monitor.
Filtering the Output
====================
The IDF monitor can be invoked as ``make monitor PRINT_FILTER=""`` with
specifying a custom ``PRINT_FILTER`` option for filtering outputs. The default
value is an empty string which means that everything will be printed.
Restrictions on what to print can be specified as a series of
``<tag>:<log_level>`` items where ``<tag>`` is the tag string and
``<log_level>`` is a character from set ``{N, E, W, I, D, V, *}`` referring to
a level for :doc:`logging <../../api-reference/system/log>`. For example,
``PRINT_FILTER="tag1:W"`` will match and print (only) the outputs written with
``ESP_LOGW("tag1", ...)`` or at lower verbosity level, i.e. ``ESP_LOGE("tag1",
...)``. Not specifying a
``<log_level>`` or using ``*`` defaults to Verbose level.
.. note::
The primary logging is set up at compilation time through the
:doc:`logging library<../../api-reference/system/log>`.
Output filtering by the IDF monitor is only a secondary solution because
one cannot filter something which has been disabled at compilation time.
The advantage of the secondary filtering is that one can use various
filtering options without recompiling the application.
A restriction applies to tags when one wants to use them together with output
filtering: they cannot contain spaces, asterisks ``*`` and semicolons ``:``.
If the last line of the output is written without an end of line then the
output filtering might get confused, i.e. the monitor starts to print the line and only
later finds out that the line should have not been written. This is a known
issue and can be avoided by always adding an end of line after printing
something (especially when no output follows immediately afterwards).
Examples Of Filtering Rules:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Asterisk can be used to match any tags. However, specifying
``PRINT_FILTER="*:I tag1:E"`` will print for ``tag1`` only errors because
the rule for ``tag1`` has a precedence over the rule for ``*``.
- The default (empty) rule is equivalent to ``*:V`` because matching every tag
at level Verbose or lower means matching everything.
- Rule ``"tag1:W tag1:E"`` is equivalent to ``"tag1:E"`` because any
consequent occurrence of the same tag name overwrites the previous one.
- Rule ``"tag1:I tag2:W"`` will print only ``tag1`` at verbosity level Info or
lower and ``tag2`` at verbosity level Warning or lower.
- Rule ``"tag1:I tag2:W tag3:N"`` is essentially equivalent to the previous
one because ``tag3:N`` specifies that ``tag3`` should not be printed.
- ``tag3:N`` in rule ``"tag1:I tag2:W tag3:N *:V"`` is more meaningful because
in this context the result will be that ``tag3`` will not be printed,
``tag1`` and ``tag2`` will be at the specified (or lower) verbosity level
and everything else will be printed by default.
- ``"*:N"`` will suppress all outputs even prints made by something else than
the logging functions, e.g. ``printf``. For printing those outputs one need
to use ``*:E`` or higher verbosity level.
- Rules ``"tag1:V"``, ``"tag1:v"``, ``"tag1:"``, ``"tag1:*"`` and ``"tag1"``
are all equivalent ones.
A More Complex Filtering Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following log snippet was acquired using ``make monitor``::
load:0x40078000,len:13564
entry 0x40078d4c
E (31) esp_image: image at 0x30000 has invalid magic byte
W (31) esp_image: image at 0x30000 has invalid SPI mode 255
E (39) boot: Factory app partition is not bootable
I (568) cpu_start: Pro cpu up.
I (569) heap_init: Initializing. RAM available for dynamic allocation:
I (603) cpu_start: Pro cpu start user code
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
D (318) vfs: esp_vfs_register_fd_range is successful for range <54; 64) and VFS ID 1
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
The captured output for ``make monitor PRINT_FILTER="wifi esp_image:E light_driver:I"`` is the following::
E (31) esp_image: image at 0x30000 has invalid magic byte
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
``make monitor PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V"`` gives the following output::
load:0x40078000,len:13564
entry 0x40078d4c
I (569) heap_init: Initializing. RAM available for dynamic allocation:
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
Simple Monitor
==============
Earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program.
This program can still be run, via ``make simple_monitor``.
IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts.
Known Issues with IDF Monitor
=============================
Issues Observed on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~
- If you are using the supported Windows environment and receive the error "winpty: command not found" then run ``pacman -S winpty`` to fix.
- Arrow keys and some other special keys in gdb don't work, due to Windows Console limitations.
- Occasionally when "make" exits, it may stall for up to 30 seconds before idf_monitor resumes.
- Occasionally when "gdb" is run, it may stall for a short time before it begins communicating with the gdbstub.
.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html
.. _gdb: https://sourceware.org/gdb/download/onlinedocs/
.. _pySerial: https://github.com/pyserial/pyserial
.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm

826
docs/en/get-started/index.rst
View File

@@ -1,376 +1,450 @@
***********
Get Started
***********
:link_to_translation:`zh_CN:[中文]`
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
.. include:: /_build/inc/version-note.inc
Introduction
============
ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
What You Need
=============
To develop applications for ESP32 you need:
* **PC** loaded with either Windows, Linux or Mac operating system
* **Toolchain** to build the **Application** for ESP32
* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
Development of applications for ESP32
Preparation of development environment consists of three steps:
1. Setup of **Toolchain**
2. Getting of **ESP-IDF** from GitHub
3. Installation and configuration of **Eclipse**
You may skip the last step, if you prefer to use different editor.
Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
1. Configuration of a **Project** and writing the code
2. Compilation of the **Project** and linking it to build an **Application**
3. Flashing (uploading) of the **Application** to **ESP32**
4. Monitoring / debugging of the **Application**
See instructions below that will walk you through these steps.
Guides
======
If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
.. toctree::
:maxdepth: 1
ESP32 DevKitC <get-started-devkitc>
ESP-WROVER-KIT <get-started-wrover-kit>
ESP32-PICO-KIT <get-started-pico-kit>
If you have different board, move to sections below.
.. _get-started-setup-toolchain:
Setup Toolchain
===============
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
.. note::
We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
.. _get-started-get-esp-idf:
Get ESP-IDF
===========
.. highlight:: bash
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command:
.. include:: /_build/inc/git-clone-bash.inc
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
.. include:: /_build/inc/git-clone-notes.inc
.. note::
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
cd esp-idf
git submodule update --init --recursive
.. _get-started-setup-path:
Setup Path to ESP-IDF
=====================
The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
.. _get-started-get-packages:
Install the Required Python Packages
====================================
Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running::
python -m pip install --user -r $IDF_PATH/requirements.txt
.. note::
Please invoke that version of the Python interpreter which you will be using with ESP-IDF. The version of the
interpreter can be checked by running command ``python --version`` and depending on the result, you might want to
use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.::
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project:
Start a Project
===============
Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
Copy :example:`get-started/hello_world` to ``~/esp`` directory::
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
.. important::
The esp-idf build system does not support spaces in paths to esp-idf or to projects.
.. _get-started-connect:
Connect
=======
You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
.. _get-started-configure:
Configure
=========
Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
cd ~/esp/hello_world
make menuconfig
If previous steps have been done correctly, the following menu will be displayed:
.. figure:: ../../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center
Project configuration - Home window
In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
.. note::
On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
(See :doc:`establish-serial-connection` for full details.)
Here are couple of tips on navigation and use of ``menuconfig``:
* Use up & down arrow keys to navigate the menu.
* Use Enter key to go into a submenu, Escape key to go out or to exit.
* Type ``?`` to see a help screen. Enter key exits the help screen.
* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
* Pressing ``?`` while highlighting a configuration item displays help about that item.
* Type ``/`` to search the configuration items.
.. note::
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
.. attention::
When using ESP32-DevKitC board with ESP32-SOLO-1 module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing example applications.
.. _get-started-build-flash:
Build and Flash
===============
Now you can build and flash the application. Run::
make flash
This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
.. highlight:: none
::
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 11616 bytes to 6695...
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
Hash of data verified.
Compressed 408096 bytes to 171625...
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-build-monitor:
Monitor
=======
To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
...
Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
To exit the monitor use shortcut ``Ctrl+]``.
.. note::
If instead of the messages above, you see a random garbage similar to::
e<EFBFBD><EFBFBD><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
That's all what you need to get started with ESP32!
Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
Environment Variables
=====================
Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without needing to reconfigure them using** ``make menuconfig``.
+-----------------+--------------------------------------------------------------+
| Variables | Description & Usage |
+=================+==============================================================+
| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. |
| | |
| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, |
| | ``make monitor ESPPORT=COM1`` |
+-----------------+--------------------------------------------------------------+
| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. |
| | |
| | Example: ``make flash ESPBAUD=9600`` |
+-----------------+--------------------------------------------------------------+
| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. |
| | |
| | Example: ``make monitor MONITORBAUD=9600`` |
+-----------------+--------------------------------------------------------------+
.. note::
Users can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``).
All subsequent calls of ``make`` within the same terminal session will use
the exported value given that the variable is not simultaneously overridden.
Updating ESP-IDF
================
After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location.
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
Related Documents
=================
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases
***********
Get Started
***********
:link_to_translation:`zh_CN:[中文]`
This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32.
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board.
.. include:: /_build/inc/version-note.inc
Introduction
============
ESP32 is a system on a chip that integrates the following features:
* Wi-Fi (2.4 GHz band)
* Bluetooth 4.2
* Dual high performance cores
* Ultra Low Power co-processor
* Several peripherals
Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
What You Need
=============
Hardware:
* An **ESP32** board
* **USB cable** - USB A / micro USB B
* **Computer** running Windows, Linux, or macOS
Software:
* **Toolchain** to build the **Application** for ESP32
* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain**
* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse <https://www.eclipse.org/>`_
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
Development of applications for ESP32
Development Board Overviews
===========================
If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware.
.. toctree::
:maxdepth: 1
ESP32-DevKitC <get-started-devkitc>
ESP-WROVER-KIT <get-started-wrover-kit>
ESP32-PICO-KIT <get-started-pico-kit>
.. _get-started-step-by-step:
Installation Step by Step
=========================
This is a detailed roadmap to walk you through the installation process.
Setting up Development Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-setup-toolchain` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`MacOS <macos-setup>`
* :ref:`get-started-get-esp-idf`
* :ref:`get-started-setup-path`
* :ref:`get-started-get-packages`
Creating Your First Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project`
* :ref:`get-started-connect`
* :ref:`get-started-configure`
* :ref:`get-started-build-and-flash`
* :ref:`get-started-monitor`
.. _get-started-setup-toolchain:
Step 1. Set up the Toolchain
============================
The toolchain is a set of programs for compiling code and building applications.
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions.
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
.. note::
This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths.
Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup`.
.. _get-started-get-esp-idf:
Step 2. Get ESP-IDF
===================
Besides the toolchain, you also need ESP32-specific API (software libraries and source code). They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``.
Open Terminal, and run the following commands:
.. include:: /_build/inc/git-clone-bash.inc
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
.. include:: /_build/inc/git-clone-notes.inc
.. note::
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
cd esp-idf
git submodule update --init
.. _get-started-setup-path:
Step 3. Set Environment Variables
=================================
The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build.
These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in Section :doc:`add-idf_path-to-profile`.
.. _get-started-get-packages:
Step 4. Install the Required Python Packages
============================================
The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running::
python -m pip install --user -r $IDF_PATH/requirements.txt
.. note::
Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run
the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7``
or similar instead of just ``python``, e.g.::
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project:
Step 5. Start a Project
=======================
Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
Copy :example:`get-started/hello_world` to the ``~/esp`` directory:
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
Windows
~~~~~~~
.. code-block:: batch
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it.
It is also possible to build examples in-place, without copying them first.
.. important::
The esp-idf build system does not support spaces in the paths to either esp-idf or to projects.
.. _get-started-connect:
Step 6. Connect Your Device
===========================
Now connect your ESP32 board to the computer and check under what serial port the board is visible.
Serial ports have the following patterns in their names:
- **Windows**: names like ``COM1``
- **Linux**: starting with ``/dev/tty``
- **macOS**: starting with ``/dev/cu.``
If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details.
.. note::
Keep the port name handy as you will need it in the next steps.
.. _get-started-configure:
Step 7. Configure
=================
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``.
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
make menuconfig
Windows
~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
make menuconfig
If the previous steps have been done correctly, the following menu appears:
.. figure:: ../../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center
Project configuration - Home window
In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit menuconfig by selecting ``< Exit >``.
To navigate and use ``menuconfig``, press the following keys:
* Arrow keys for navigation
* ``Enter`` to go into a submenu
* ``Esc`` to go up one level or exit
* ``?`` to see a help screen. Enter key exits the help screen
* ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
* ``?`` while highlighting a configuration item to display help about that item
* ``/`` to find configuration items
.. note::
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
.. attention::
If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples.
.. _get-started-build-and-flash:
Step 8. Build and Flash
=======================
Build and flash the project by running::
make flash
This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board.
.. highlight:: none
::
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 11616 bytes to 6695...
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
Hash of data verified.
Compressed 408096 bytes to 171625...
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
If there are no issues by the end of the flash process, you will see messages describing progress of the loading process. Then the module will be reset and the “hello_world” application will start up.
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-monitor:
Step 9. Monitor
===============
To check if "hello_world" is indeed running, type ``make monitor``.
This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application::
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
...
After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application.
.. code-block:: none
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
To exit IDF monitor use the shortcut ``Ctrl+]``.
If IDF monitor fails shortly after the upload, of if instead of the messages above you see a random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value.
.. code-block:: none
e<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
If you have such a problem, do the following:
1. Exit the monitor.
2. Go back to :ref:`menuconfig <get-started-configure>`.
3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.
4. After that, :ref:`build and flash <get-started-build-and-flash>` the application again.
.. note::
You can combine building, flashing and monitoring into one step by running::
make flash monitor
See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor.
**That's all that you need to get started with ESP32!**
Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications.
Environment Variables
=====================
Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without the need to reconfigure them using** ``make menuconfig``.
+-----------------+--------------------------------------------------------------+
| Variables | Description & Usage |
+=================+==============================================================+
| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. |
| | |
| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, |
| | ``make monitor ESPPORT=COM1`` |
+-----------------+--------------------------------------------------------------+
| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. |
| | |
| | Example: ``make flash ESPBAUD=9600`` |
+-----------------+--------------------------------------------------------------+
| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. |
| | |
| | Example: ``make monitor MONITORBAUD=9600`` |
+-----------------+--------------------------------------------------------------+
.. note::
You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``).
All subsequent calls of ``make`` within the same terminal session will use
the exported value given that the variable is not simultaneously overridden.
Updating ESP-IDF
================
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`.
If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts can find ESP-IDF in its release specific location.
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
Related Documents
=================
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
../api-guides/tools/idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases