Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'doc/review_get_started' into 'master'

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

See merge request idf/esp-idf!4331
This commit is contained in:
Krzysztof Budzynski 2019-03-14 00:10:26 +08:00
parent d34ca0b897 49cca9288f
commit 16b2fd2dce
35 changed files with 1419 additions and 1303 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/conf_common.py
View file

@ -253,7 +253,9 @@ html_redirect_pages = [('api-reference/ethernet/index', 'api-reference/network/i
('api-reference/wifi/esp_now', 'api-reference/network/esp_now'),
('api-reference/wifi/esp_smartconfig', 'api-reference/network/esp_smartconfig'),
('api-reference/wifi/esp_wifi', 'api-reference/network/esp_wifi'),
('api-reference/system/tcpip_adapter', 'api-reference/network/tcpip_adapter'),]
('api-reference/system/tcpip_adapter', 'api-reference/network/tcpip_adapter'),
('get-started/idf-monitor', 'api-guides/tools/idf-monitor'),
('get-started-cmake/idf-monitor', 'api-guides/tools/idf-monitor'),]
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.

2
docs/en/api-guides/build-system-cmake.rst
View file

@ -83,7 +83,7 @@ Type ``idf.py --help`` for a full list of commands. Here are a summary of the mo
- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`/get-started/idf-monitor` for more details about using the monitor.
- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor.
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.

2
docs/en/api-guides/error-handling.rst
View file

@ -58,7 +58,7 @@ Error message will typically look like this::
Backtrace: 0x40086e7c:0x3ffb4ff0 0x40087328:0x3ffb5010 0x400d1fdf:0x3ffb5030 0x400d0816:0x3ffb5050
.. note:: If :doc:`IDF monitor <../get-started/idf-monitor>` is used, addresses in the backtrace will be converted to file names and line numbers.
.. note:: If :doc:`IDF monitor <tools/idf-monitor>` is used, addresses in the backtrace will be converted to file names and line numbers.
- The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code. The latter depends on :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` option being set. Address in the program where error has occured is printed as well.

4
docs/en/api-guides/fatal-errors.rst
View file

@ -126,7 +126,7 @@ In some cases, such as interrupt watchdog timeout, panic handler may print addit
Backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is Stack Pointer, for each stack frame of the current task. If a fatal error happens inside an ISR, the backtrace may include PC:SP pairs both from the task which was interrupted, and from the ISR.
If :doc:`IDF Monitor <../get-started/idf-monitor>` is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines::
If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines::
Core 0 register dump:
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
@ -152,7 +152,7 @@ GDB Stub
If ``CONFIG_ESP32_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port.
If :doc:`IDF Monitor <../get-started/idf-monitor>` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this::
If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this::
Entering gdb stub now.
$T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10

2
docs/en/api-guides/jtag-debugging/index.rst
View file

@ -197,7 +197,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT)::
Upload application for debugging
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Build and upload your application to ESP32 as usual, see :ref:`get-started-build-flash`.
Build and upload your application to ESP32 as usual, see :ref:`get-started-build-and-flash`.
Another option is to write application image to flash using OpenOCD via JTAG with commands like this::

216
docs/en/api-guides/tools/idf-monitor.rst Normal file
View file

@ -0,0 +1,216 @@
***********
IDF Monitor
***********
The IDF monitor tool is mainly a serial terminal program which relays serial data to and from the target device's serial port. It also provides some IDF-specific features.
This tool can be launched by invoking in IDF the following target:
- **For make**: ``make monitor``
- **For cmake**: ``idf.py monitor``
Keyboard Shortcuts
==================
For easy interaction with IDF Monitor, use the keyboard shortcuts given in the table.
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Keyboard Shortcut | Action | Description |
+===================+========================================================+==================================================================================================================================================================+
| Ctrl+] | Exit the program | |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Ctrl+T | Menu escape key | Press and follow it by one of the keys given below. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+T | Send the menu character itself to remote | |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+] | Send the exit character itself to remote | |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+P | Reset target into bootloader to pause app via RTS line | Resets the target, into bootloader via the RTS line (if connected), so that the board runs nothing. Useful when you need to wait for another device to startup. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+R | Reset target board via RTS | Resets the target board and re-starts the application via the RTS line (if connected). |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the ``make flash`` (``idf.py flash``) target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+A | Build and flash the app only | Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+Y | Stop/resume log output printing on screen | Discards all incoming serial data while activated. Allows to quickly pause and examine log output without quitting the monitor. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+H | Display all keyboard shortcuts | |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Any keys pressed, other than ``Ctrl-]`` and ``Ctrl-T``, will be sent through the serial port.
IDF-specific features
=====================
Automatic Address Decoding
~~~~~~~~~~~~~~~~~~~~~~~~~~
Whenever ESP-IDF outputs a hexadecimal code address of the form ``0x4_______``, IDF Monitor uses addr2line_ to look up the location in the source code and find the function name.
.. highlight:: none
If an ESP-IDF app crashes and panics, a register dump and backtrace is produced, such as the following::
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 adds more details to 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
To decode each address, IDF Monitor runs the following command in the background::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
.. note:: Due to a bug in addr2line, line numbers may be incorrect for some source files. However, the function name is always correct.
Launching GDB with GDBStub
~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, if esp-idf crashes, the panic handler prints relevant registers and the stack dump (similar to the ones above) over the serial port. Then it resets the board.
Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware.
To enable GDBStub, run ``make menuconfig`` (for make) or ``idf.py menuconfig`` (for cmake) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``.
In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button.
In the background, IDF Monitor runs the following command::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
Output Filtering
~~~~~~~~~~~~~~~~
IDF monitor can be invoked as ``make monitor PRINT_FILTER=""`` (for make) or ``idf.py monitor PRINT_FILTER=""`` (for cmake), where ``PRINT_FILTER`` is the parameter for output filtering. The default value is an empty string, which means that everything is 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 the set ``{N, E, W, I, D, V, *}`` referring to a level for :doc:`logging <../../api-reference/system/log>`.
For example, ``PRINT_FILTER="tag1:W"`` matches and prints 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::
Use primary logging to disable at compilation the outputs you do not
need through the :doc:`logging library<../../api-reference/system/log>`.
Output filtering with IDF monitor is a secondary solution
which can be useful for adjusting the filtering options without
recompiling the application.
Your app tags must not contain spaces, asterisks ``*``,
and semicolons ``:`` to be compatible with the output filtering feature.
If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e., the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards).
Examples Of Filtering Rules:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- ``*`` can be used to match any tags. However, the string
``PRINT_FILTER="*:I tag1:E"`` with regards to ``tag1`` prints errors
only, because the rule for ``tag1`` has a higher priority over the rule for ``*``.
- The default (empty) rule is equivalent to ``*:V`` because matching every tag
at the Verbose level or lower means matching everything.
- ``"*:N"`` suppresses not only the outputs from logging functions, but also
the prints made by ``printf``, etc. To avoid this, use ``*:E`` or a higher verbosity level.
- Rules ``"tag1:V"``, ``"tag1:v"``, ``"tag1:"``, ``"tag1:*"``, and ``"tag1"``
are equivalent.
- 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"`` only prints ``tag1`` at the Info verbosity level or
lower and ``tag2`` at the Warning verbosity level 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 the rule ``"tag1:I tag2:W tag3:N *:V"`` is more meaningful because
without ``tag3:N`` the ``tag3`` messages could have been printed;
the errors for ``tag1`` and ``tag2`` will be printed at the specified (or lower)
verbosity level and everything else will be printed by default.
A More Complex Filtering Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following log snippet was acquired without any filtering options::
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 the filtering options ``PRINT_FILTER="wifi esp_image:E light_driver:I"`` is given below::
E (31) esp_image: image at 0x30000 has invalid magic byte
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
``The options ``PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V"`` show 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
==============
The earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program.
.. note:: This target only works in a build system based on GNU Make and cannot work in a CMake-based system.
This program can still be run with the command ``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 in the Windows environment you receive the error "winpty: command not found", fix it by running ``pacman -S winpty``.
- Arrow keys, as well as some other keys, do not work in GDB due to Windows Console limitations.
- Occasionally, when "idf.py" or "make" exits, it might stall for up to 30 seconds before IDF Monitor resumes.
- When "gdb" is run, it might 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

2
docs/en/api-reference/system/heap_debug.rst
View file

@ -189,7 +189,7 @@ The output from the heap trace will look something like this::
40 bytes 'leaked' in trace (2 allocations)
total allocations 2 total frees 0
(Above example output is using :doc:`IDF Monitor </get-started/idf-monitor>` to automatically decode PC addresses to their source files & line number.)
(Above example output is using :doc:`IDF Monitor </api-guides/tools/idf-monitor>` to automatically decode PC addresses to their source files & line number.)
The first line indicates how many allocation entries are in the buffer, compared to its total size.

60
docs/en/get-started-cmake/get-started-devkitc-v2.rst
View file

@ -1,40 +1,31 @@
ESP32-DevKitC V2 Getting Started Guide (CMake)
==============================================
This user guide shows how to get started with ESP32-DevKitC development board.
:link_to_translation:`zh_CN:[中文]`
This guide shows how to start using the ESP32-DevKitC V2 development board.
What You Need
-------------
* 1 × :ref:`ESP32-DevKitC V2 board <get-started-esp32-devkitc-v2-board-front-cmake>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
* :ref:`ESP32-DevKitC V2 board <get-started-esp32-devkitc-v2-board-front-cmake>`
* USB A / micro USB B cable
* Computer running Windows, Linux, or macOS
If you want to start using this board right now, go directly to Section `Start Application Development`_.
You can skip the introduction sections and go directly to Section `Start Application Development`_.
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.
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 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.
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-cmake:
@ -46,31 +37,46 @@ I/O
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 following options are available to provide power supply to this board:
There are three mutually exclusive ways to provide power to the board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
* Micro USB port, default power supply
* 5V / GND header pins
* 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.
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 the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP32-DevKitC V2, 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 :ref:`get-started-step-by-step-cmake`.
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents
-----------------
* `ESP32-DevKitC schematic <https://dl.espressif.com/dl/schematics/ESP32-Core-Board-V2_sch.pdf>`_ (PDF)
* `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)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf>`_ (PDF)

128
docs/en/get-started-cmake/get-started-devkitc.rst
View file

@ -1,55 +1,50 @@
ESP32-DevKitC V4 Getting Started Guide (CMake)
==============================================
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`.
: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
-------------
* 1 × :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front-cmake>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
* :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front-cmake>`
* USB A / micro USB B cable
* Computer running Windows, Linux, or macOS
If you want to start using this board right now, go directly to Section `Start Application Development`_.
You can skip the introduction sections and go directly to Section `Start Application Development`_.
.. _DevKitC-Overview-cmake:
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 connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard.
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.
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>` and :ref:`esp-modules-and-boards-esp32-solo-1`.
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 list and figure below describe key components, interfaces and controls of ESP32-DevKitC V4 board.
ESP-WROOM-32
:ref:`esp-modules-and-boards-esp32-wroom-32` module soldered to the ESP32-DevKitC V4 board. Optionally ESP32-WROOM-32D, ESP32-WROOM-32U or ESP32-SOLO-1 module may be soldered instead of the ESP32-WROOM-32.
USB-UART Bridge
A single chip USB-UART bridge provides up to 3 Mbps transfers rates.
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.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and the ESP module.
5V Power On LED
This LED lights when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
EN
Reset button: pressing this button resets the system.
I/O
Most of the pins on the ESP module 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.
.. note::
Some of broken out pins are used internally be the ESP32 module to communicate with SPI memory. They are grouped on one side of the board besides the USB connector and labeled D0, D1, D2, D3, CMD and CLK. In general these pins should be left unconnected or access to the SPI flash memory / SPI RAM may be disturbed.
.. note::
GPIO16 and 17 are used internally by the ESP32-WROVER module. They are broken out and avialable for use only for boards that have the ESP-WROOM-32 module installed.
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-cmake:
@ -58,29 +53,75 @@ I/O
:alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
:figclass: align-center
ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
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 following options are available to provide power supply to this board:
There are three mutually exclusive ways to provide power to the board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
* Micro USB port, default power supply
* 5V / GND header pins
* 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.
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 the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
Before powering up your ESP32-DevKitC V4, 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 :ref:`get-started-step-by-step-cmake`.
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board.
Board Dimensions
@ -97,10 +138,13 @@ Board Dimensions
Related Documents
-----------------
* `ESP32-DevKitC V4 schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf>`_ (PDF)
* `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)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_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:

4
docs/en/get-started-cmake/get-started-pico-kit-v3.rst
View file

@ -49,9 +49,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 :ref:`get-started-step-by-step-cmake`.
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

4
docs/en/get-started-cmake/get-started-pico-kit.rst
View file

@ -86,9 +86,9 @@ There following options are available to provide power supply to the ESP32-PICO-
Start Application Development
-----------------------------
Before powering up the ESP32-PICO-KIT V4, 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 V4, 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 :ref:`get-started-step-by-step-cmake`.
After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board.
Pin Descriptions

4
docs/en/get-started-cmake/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,7 +161,7 @@ Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`.
Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

4
docs/en/get-started-cmake/get-started-wrover-kit.rst
View file

@ -357,7 +357,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
@ -378,7 +378,7 @@ Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`.
Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board.
Related Documents

135
docs/en/get-started-cmake/idf-monitor.rst
View file

@ -1,135 +0,0 @@
*******************
IDF Monitor (CMake)
*******************
The idf_monitor tool is a Python program which runs when the ``idf.py 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 ``idf.py 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 ``idf.py 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 ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py 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.
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.
.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
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

254
docs/en/get-started-cmake/index.rst
View file

@ -8,28 +8,43 @@ Get Started (CMake)
.. include:: ../cmake-pending-features.rst
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.
This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif.
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board.
.. 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.
ESP32 is a system on a chip that integrates the following features:
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.
* 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
=============
To develop applications for ESP32 you need:
Hardware:
* An **ESP32** board
* **USB cable** - USB A / micro USB B
* **Computer** running Windows, Linux, or macOS
Software:
* **PC** loaded with either Windows, Linux or Mac operating system
* **Toolchain** to compile code for ESP32
* **Build tools** CMake and Ninja to build a full **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**
* **Build tools** - CMake and Ninja to build a full **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-cmake.png
:align: center
@ -38,6 +53,20 @@ To develop applications for ESP32 you need:
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-cmake:
Installation Step by Step
@ -63,26 +92,15 @@ Creating Your First Project
* :ref:`get-started-flash-cmake`
* :ref:`get-started-build-monitor-cmake`
Development Board Guides
========================
If you have one of ESP32 development boards listed below, click on the link for hardware setup:
.. 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-cmake:
Step 1. Set up Toolchain
========================
Step 1. Set up the Toolchain
============================
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
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:
@ -112,40 +130,52 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
.. note::
We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and MacOS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands.
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-cmake`.
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-cmake`.
.. _get-started-get-esp-idf-cmake:
Step 2. Get ESP-IDF
===================
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 get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command.
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>`_.
Get ESP-IDF in accordance with your operating system.
To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``.
Linux and MacOS
~~~~~~~~~~~~~~~
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:
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 version of ESP-IDF to use in a given situation.
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
Windows
~~~~~~~
.. note::
Previous versions of ESP-IDF used the **MSYS2 bash terminal** command line. The current cmake-based build system can run in the regular **Windows Command Prompt** which is used here.
If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below.
Open Command Prompt and run the following commands:
.. include:: /_build/inc/git-clone-windows.inc
ESP-IDF will be downloaded into ``esp\esp-idf`` in the user's profile directory.
ESP-IDF will be downloaded into ``%userprofile%\esp\esp-idf``.
Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
.. include:: /_build/inc/git-clone-notes.inc
.. highlight:: bash
.. 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::
@ -153,43 +183,44 @@ Consult :doc:`/versions` for information about which version of ESP-IDF to use i
cd esp-idf
git submodule update --init
.. _get-started-setup-path-cmake:
Step 3. Set Environment Variables
=================================
ESP-IDF requires two environment variables to be set for normal operation:
Set the following environment variables on your computer, so that projects can be built:
- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory.
- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory.
- Create ``IDF_PATH`` and assign it the path to the ESP-IDF directory.
- Add to ``PATH`` the path to the ``tools`` directory inside the ``IDF_PATH`` directory.
These two variables should be set up on your PC, otherwise projects will not build.
These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in Section :doc:`add-idf_path-to-profile`.
Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in Section :doc:`add-idf_path-to-profile`.
.. _get-started-get-packages-cmake:
Step 4. 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::
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 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.::
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-cmake:
Step 5. 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.
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 ``~/esp`` directory:
@ -201,35 +232,48 @@ Linux and MacOS
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
Windows
~~~~~~~
.. code-block:: batch
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world 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.
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 path to either esp-idf or to projects.
The esp-idf build system does not support spaces in the paths to either esp-idf or to projects.
.. _get-started-connect-cmake:
Step 6. Connect the Device
==========================
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.
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-cmake:
Step 7. Configure
=================
Navigate to the directory of the ``hello_world`` application copy, and run the ``menuconfig`` project configuration utility:
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-cmake` and run the project configuration utility ``menuconfig``.
Linux and MacOS
~~~~~~~~~~~~~~~
@ -239,21 +283,23 @@ Linux and MacOS
cd ~/esp/hello_world
idf.py menuconfig
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
If your default version of Python is 3.x, you may need to run ``python2 idf.py`` instead.
Windows
~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
idf.py menuconfig
.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path-cmake`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf-cmake`.
The Python 2.7 installer will try to configure Windows to associate ``.py`` files with Python 2. If a separately installed program, such as Visual Studio Python Tools, has created an association with a different version of Python, then running ``idf.py`` may not work (it opens the file in Visual Studio instead). You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work (it opens the file in Visual Studio instead). You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
.. note::
.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead.
If you get an error ``idf.py not found``, make sure that the ``PATH`` environment variable was set correctly in :ref:`get-started-setup-path-cmake`. If there is no ``idf.py`` in ``tools``, make sure you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf-cmake`.
If previous steps have been done correctly, the following menu will be displayed:
If the previous steps have been done correctly, the following menu appears:
.. figure:: ../../_static/project-configuration.png
:align: center
@ -262,31 +308,30 @@ If previous steps have been done correctly, the following menu will be displayed
Project configuration - Home window
Here are couple of tips on navigation and use of ``menuconfig``:
To navigate and use ``menuconfig``, press the following keys:
* Use up & down arrow keys to navigate the menu.
* Use Enter key to go into a submenu, Escape key to go up a level or 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.
* 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
.. 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.
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-cmake:
Step 8. Build the Project
=========================
.. highlight:: bash
Now you can build the project. Run::
Build the project by running::
idf.py build
This command will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries.
.. code-block:: none
@ -310,20 +355,25 @@ This command will compile the application and all the ESP-IDF components, genera
If there are no errors, the build will finish by generating the firmware binary .bin file.
.. _get-started-flash-cmake:
Step 9. Flash to a Device
=========================
Step 9. Flash onto the Device
=============================
Now you can flash the application to the ESP32 board. Run::
Flash the binaries that you just built onto your ESP32 board by running::
idf.py -p PORT flash
idf.py -p PORT [-b BAUD] flash
Replace PORT with the name of your ESP32 board's serial port. 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.
Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect-cmake`.
This step will flash the binaries that you just built to your ESP32 board.
You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``.
.. note:: Running ``idf.py build`` before ``idf.py flash`` is not actually necessary, the flash step will automatically build the project if required before flashing.
For more information on idf.py arguments, see :ref:`idf.py`.
.. note::
The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary.
.. code-block:: none
@ -356,7 +406,7 @@ This step will flash the binaries that you just built to your ESP32 board.
Leaving...
Hard resetting via RTS pin...
If there are no issues, at the end of flash process, the module will be reset and “hello_world” application will be running there.
If there are no issues by the end of the flash process, the module will be reset and the “hello_world” application will be running.
.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
@ -366,7 +416,9 @@ If there are no issues, at the end of flash process, the module will be reset an
Step 10. Monitor
================
To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
To check if "hello_world" is indeed running, type ``idf.py -p PORT monitor`` (Do not forget to replace PORT with your serial port name).
This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application::
$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
@ -379,7 +431,7 @@ To see if "hello_world" application is indeed running, type ``idf.py -p PORT mon
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.
After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application.
.. code-block:: none
@ -391,37 +443,43 @@ Several lines below, after start up and diagnostic log, you should see "Hello wo
Restarting in 8 seconds...
Restarting in 7 seconds...
To exit the monitor use shortcut ``Ctrl+]``.
To exit IDF monitor use the shortcut ``Ctrl+]``.
If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see 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-cmake>`.
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-flash-cmake>` the application again.
.. note::
If instead of the messages above, you see a random garbage similar to::
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
or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure-cmake>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-flash-cmake>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
.. note::
You can combine building, flashing and monitoring into one step as follows::
You can combine building, flashing and monitoring into one step by running::
idf.py -p PORT flash monitor
Check the Section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using the monitor.
See also:
Check the Section :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor.
- :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
That's all what you need to get started with ESP32!
**That's all that 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.
Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications.
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-cmake`.
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.
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>`.
@ -434,7 +492,7 @@ Related Documents
add-idf_path-to-profile
establish-serial-connection
eclipse-setup
idf-monitor
../api-guides/tools/idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/

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<><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
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

2
docs/zh_CN/api-guides/build-system-cmake.rst
View file

@ -71,7 +71,7 @@ idf.py
- ``idf.py clean`` 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。
- ``idf.py fullclean`` 会将整个 ``build`` 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 *所有文件*，请谨慎使用。项目配置文件不会被删除。
- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进 ESP32 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。
- ``idf.py monitor`` 用于显示 ESP32 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`/get-started/idf-monitor`。
- ``idf.py monitor`` 用于显示 ESP32 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。
多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进 ESP32 设备，最后运行串口监视器。

2
docs/zh_CN/api-guides/error-handling.rst
View file

@ -67,7 +67,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
- 最后一行打印回溯结果。对于所有不可恢复错误，这里在应急处理程序中打印的内容都是一样的。更多有关回溯结果的详细信息，请参阅 :doc:`不可恢复错误 <fatal-errors>` 。
.. note:: 如果使用 :doc:`IDF monitor <../get-started/idf-monitor>`, 则最后一行回溯结果中的地址将会被替换为相应的文件名和行号。
.. note:: 如果使用 :doc:`IDF monitor <tools/idf-monitor>`, 则最后一行回溯结果中的地址将会被替换为相应的文件名和行号。
错误处理模式

2
docs/zh_CN/api-guides/jtag-debugging/index.rst
View file

@ -194,7 +194,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
上传待调试的应用程序
~~~~~~~~~~~~~~~~~~~~
您可以像往常一样构建并上传 ESP32 应用程序，具体请参阅 :ref:`get-started-build-flash` 章节。
您可以像往常一样构建并上传 ESP32 应用程序，具体请参阅 :ref:`get-started-build-and-flash` 章节。
除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下::

197
docs/zh_CN/api-guides/tools/idf-monitor.rst Normal file
View file

@ -0,0 +1,197 @@
*******************
IDF 监视器
*******************
:link_to_translation:`en:[English]`
IDF 监视器是一个串行终端程序，用于收发目标设备串口的串行数据，IDF 监视器同时还兼具 IDF 的其他特性。
在 IDF 中调用以下目标函数可以启用此监视器：
- **若使用 Make 编译系统，请调用**：``make monitor``
- **若使用 CMake 编译系统，则请调用**：``idf.py monitor``
操作快捷键
==================
为了方便与 IDF 监视器进行交互，请使用表中给出的快捷键。
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| 快捷键 | 操作 | 描述 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| Ctrl+] | 退出监视器程序 | |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| Ctrl+T | 菜单退出键 | 按下如下给出的任意键，并按指示操作。 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+T | 将菜单字符发送至远程 | |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+] | 将 exit 字符发送至远程 | |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+P | 重置目标设备，进入 Bootloader，通过 RTS 线暂停应用程序 | 重置目标设备，通过 RTS 线（如已连接）进入 Bootloader，此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+R | 通过 RTS 线重置目标设备 | 重置设备，并通过 RTS 线（如已连接）重新启动应用程序。 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+F | 编译并烧录此项目 | 暂停 idf_monitor，运行 ``make flash`` (``idf.py flash``) 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+A | 仅编译及烧录应用程序 | 暂停 idf_monitor，运行 ``app-flash`` 目标，然后恢复 idf_monitor。 这与 ``flash`` 类似，但只有主应用程序被编译并被重新烧录。 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+Y | 停止/恢复日志输出在屏幕上打印 | 激活时，会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。 |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+H | 显示所有快捷键 | |
+----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
除了 ``Ctrl-]`` 和 ``Ctrl-T``，其他快捷键信号会通过串口发送到目标设备。
兼具 IDF 特性
=====================
自动解码地址
~~~~~~~~~~~~~~~~~~~~~~~~~~
ESP-IDF 输出形式为 ``0x4_______`` 的十六进制代码地址后，IDF 监视器将使用 addr2line_ 查找该地址在源代码中的位置和对应的函数名。
.. highlight:: none
ESP-IDF 应用程序发生 crash 和 panic 事件时，将产生如下的寄存器转储和回溯::
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 监视器为寄存器转储补充如下信息::
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
IDF 监视器在后台运行以下命令，解码各地址::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
配置 GDBStub 以启用 GDB
~~~~~~~~~~~~~~~~~~~~~~~~~
默认情况下，如果 ESP-IDF 应用程序发生 crash 事件，panic 处理器将在串口上打印相关寄存器和堆栈转储（类似上述情况），然后重置开发板。
或者选择配置 panic 处理器以运行 GDBStub，GDBStub 工具可以与 GDB_ 项目调试器进行通信，允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用，但不需要使用特殊硬件。
如需启用 GDBStub，请运行 ``make menuconfig`` （适用于 Make 编译系统）或 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。
在这种情况下，如果 panic 处理器被触发，只要 IDF 监视器监控到 GDBStub 已经加载，panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后，通过 RTS 串口线复位开发板。如果未连接 RTS 串口线，请按复位键，手动复位开发板。
IDF 监控器在后台运行如下命令::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
输出筛选
~~~~~~~~~~~~~~~~
IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （适用于 Make）或者 ``idf.py monitor PRINT_FILTER=""`` （适用于 CMake），其中，``PRINT_FILTER`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。
若需对打印内容设置限制，可指定 ``<tag>:<log_level>`` 等选项，其中 ``<tag>`` 是标签字符串，``<log_level>`` 是 ``{N, E, W, I, D, V, *}`` 集合中的一个字母，指的是 :doc:`日志 <../../api-reference/system/log>` 级别。
例如，``PRINT_FILTER="tag1:W"`` 只匹配并打印 ``ESP_LOGW("tag1", ...)`` 所写的输出，或者写在较低冗余级别的输出，即 ``ESP_LOGE("tag1", ...)``。请勿指定 ``<log_level>`` 或使用冗余级别默认值 ``*``。
.. note::
编译时，可以使用主日志在 :doc:`日志库 <../../api-reference/system/log>` 中禁用不需要的输出。也可以使用 IDF 监视器筛选输出来调整筛选设置，且无需重新编译应用程序。
应用程序标签不能包含空格、星号 ``*``、分号 ``:``，以便兼容输出筛选功能。
如果应用程序输出的最后一行后面没有回车，可能会影响输出筛选功能，即，监视器开始打印该行，但后来发现该行不应该被写入。这是一个已知问题，可以通过添加回车来避免此问题（特别是在没有输出紧跟其后的情况下）。
筛选规则示例
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- ``*`` 可用于匹配任何类型标签。但 ``PRINT_FILTER="*:I tag1:E"`` 打印关于 ``tag1`` 的输出时会报错，这是因为 ``tag1`` 规则比 ``*`` 规则的优先级高。
- 默认规则（空）等价于 ``*:V``，因为在冗余级别或更低级别匹配任意标签即意味匹配所有内容。
- ``"*:N"`` 不仅抑制了日志功能的输出，也抑制了 ``printf`` 的打印输出。为了避免这一问题，请使用 ``*:E`` 或更高的冗余级别。
- 规则 ``"tag1:V"``、``"tag1:v"``、``"tag1:"``、``"tag1:*"`` 和 ``"tag1"`` 等同。
- 规则 ``"tag1:W tag1:E"`` 等同于 ``"tag1:E"``，这是因为后续出现的具有相同名称的标签会覆盖掉前一个标签。
- 规则 ``"tag1:I tag2:W"`` 仅在 Info 冗余级别或更低级别打印 ``tag1``，在 Warning 冗余级别或更低级别打印 ``tag2``。
- 规则 ``"tag1:I tag2:W tag3:N"`` 在本质上等同于上一规则，这是因为 ``tag3:N`` 指定 ``tag3`` 不打印。
- ``tag3:N`` 在规则 ``"tag1:I tag2:W tag3:N *:V"`` 中更有意义，这是因为如果没有 ``tag3:N``，``tag3`` 信息就可能打印出来了；``tag1`` 和 ``tag2`` 错误信息会打印在指定的冗余级别（或更低级别），并默认打印所有内容。
高级筛选规则示例
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
如下日志是在没有设置任何筛选选项的情况下获得的::
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
``PRINT_FILTER="wifi esp_image:E light_driver:I"`` 筛选选项捕获的输出如下所示::
E (31) esp_image: image at 0x30000 has invalid magic byte
I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
``PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V"`` 选项的输出如下::
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
简单监视器
==============
较早版本的 ESP-IDF 使用 pySerial_ 命令行工具 miniterm_ 作为串行控制台程序。
.. note:: 仅适用于 Make 编译系统，不适用于 CMake 编译系统。
此程序仍然可以通过 ``make simple_monitor`` 运行。
IDF 监视器基于 miniterm，可使用相同的快捷键。
IDF 监视器已知问题
=============================
Windows 环境下已知问题
~~~~~~~~~~~~~~~~~~~~~~~~~~
- 若在 Windows 环境下，出现 "winpty: command not found" 错误，请运行 ``pacman -S winpty`` 进行修复。
- 由于 Windows 控制台限制，有些箭头键及其他一些特殊键无法在 GDB 中使用。
- 偶然情况下，``idf.py`` 或 ``make`` 退出时，可能会在 IDF 监视器恢复之前暂停 30 秒。
- GDB 运行时，可能会暂停一段时间，然后才开始与 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

1
docs/zh_CN/get-started-cmake/idf-monitor.rst
View file

@ -1 +0,0 @@
.. include:: ../../en/get-started-cmake/idf-monitor.rst

6
docs/zh_CN/get-started-cmake/index.rst
View file

@ -345,7 +345,7 @@ Windows Command Prompt
监视器
================
如果要查看 "hello_world" 程序是否真的在运行，输入命令 ``idf.py -p PORT monitor``。这个命令会启动 :doc:`IDF Monitor <idf-monitor>` 程序::
如果要查看 "hello_world" 程序是否真的在运行，输入命令 ``idf.py -p PORT monitor``。这个命令会启动 :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` 程序::
$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
@ -387,7 +387,7 @@ Windows Command Prompt
idf.py -p PORT flash monitor
有关监视器使用的快捷键和其他详情，请参阅 :doc:`IDF Monitor <idf-monitor>`。
有关监视器使用的快捷键和其他详情，请参阅 :doc:`IDF Monitor <../api-guides/tools/idf-monitor>`。
有关 ``idf.py`` 的全部命令和选项，请参阅 :ref:`idf.py`。
@ -414,7 +414,7 @@ Windows Command Prompt
add-idf_path-to-profile
establish-serial-connection
eclipse-setup
idf-monitor
../api-guides/tools/idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/

5
docs/zh_CN/get-started/get-started-devkitc.rst
View file

@ -106,9 +106,8 @@ ESP32-DevKitC 上电前，请首先确认电路板完好无损。
* :ref:`设置 Toolchain <get-started-setup-toolchain>`，以便用 C 语言开发应用
* :ref:`连接 <get-started-connect>` 模组至 PC，并确认访问状态
* :ref:`构建并向 ESP32 烧录示例 <get-started-build-flash>`
* :ref:`即刻监测 <get-started-build-monitor>` 应用程序的动作
* :ref:`构建并向 ESP32 烧录 example <get-started-build-and-flash>`
* :ref:`即刻监测 <get-started-monitor>` 应用程序的动作
开发板尺寸
----------------

4
docs/zh_CN/get-started/get-started-pico-kit.rst
View file

@ -102,8 +102,8 @@ ESP32-PICO-KIT V4 支持以下几种供电模式：
* :ref:`设置 Toolchain <get-started-setup-toolchain>`，以便用 C 语言开发应用
* :ref:`连接 <get-started-connect>` 模组至 PC，并确认访问状态
* :ref:`构建并向 ESP32 烧录 example <get-started-build-flash>`
* :ref:`即刻监测 <get-started-build-monitor>` 应用程序的动作
* :ref:`构建并向 ESP32 烧录 example <get-started-build-and-flash>`
* :ref:`即刻监测 <get-started-monitor>` 应用程序的动作
管脚说明

4
docs/zh_CN/get-started/get-started-wrover-kit.rst
View file

@ -348,8 +348,8 @@ USB 供电 使能 UART 通信
* :ref:`设置 Toolchain <get-started-setup-toolchain>`，以便用 C 语言开发应用
* :ref:`连接 <get-started-connect>` 模组至 PC，并确认访问状态
* :ref:`构建并向 ESP32 烧录示例 <get-started-build-flash>`
* :ref:`即刻监测 <get-started-build-monitor>` 应用程序的动作
* :ref:`构建并向 ESP32 烧录示例 <get-started-build-and-flash>`
* :ref:`即刻监测 <get-started-monitor>` 应用程序的动作
相关文档

125
docs/zh_CN/get-started/idf-monitor.rst
View file

@ -1,125 +0,0 @@
***********
IDF Monitor
***********
:link_to_translation:`en:[English]`
IDF Monitor 工具是在 IDF 中调用 “make monitor” 目标时运行的 Python 程序。
它主要是一个串行终端程序，用于收发该端口的串行数据，IDF Monitor 同时兼具 IDF 的其他特性。
IDF Monitor 操作快捷键
===========================
- ``Ctrl-]`` 退出 monitor；
- ``Ctrl-T Ctrl-H`` 展示帮助页面和其他快捷键；
- 除了 ``Ctrl-]`` 和 ``Ctrl-T``，其他快捷键信号会通过串口发送到目标设备。
自动解码地址
=================
当 esp-idf 以 “0x4 _______” 形式打印一个十六进制的代码地址时，IDF Monitor 将使用 addr2line_ 来查找源代码的位置和函数名称。
.. highlight:: none
当某个 esp-idf 应用程序发生 crash 和 panic 事件之后，将产生如下的寄存器转储和回溯::
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 为转储补充如下信息::
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
在后台，IDF Monitor 运行以下命令解码各个地址::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
配置 GDBStub 供 GDB 调试
============================
默认情况下，如果 esp-idf 应用程序 crash, panic 处理函数打印上述的寄存器和堆栈转储，然后重启。
您可以选择配置 panic 处理函数，使其运行串行的 "gdb stub"。该程序可以与 gdb 调试器通信，提供内存，变量，栈帧读取的功能。虽然这不像 JTAG 调试那样通用，但您不需要使用特殊硬件。
要启用 gdbstub，运行 ``make menuconfig`` 并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。
如果启用此选项并且 IDF Monitor 发现 gdbstub 已加载，它将自动暂停串口监控并使用正确的参数运行 GDB。GDB 退出后，电路板将通过 RTS 串行线路复位（如果已连接）。
IDF Monitor 在后台运行的命令是::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
快速编译与烧录
=================
使用快捷键 ``Ctrl-T Ctrl-A`` 暂停 IDF Monitor，并运行 ``make flash`` 目标，然后 IDF Monitor 就会恢复正常。任何更改的源文件将在烧录之前重新编译。
使用快捷键 ``Ctrl-T Ctrl-A`` 暂停 IDF Monitor，并运行 ``make app-flash`` 目标，然后 IDF Monitor 就会恢复正常。这与 ``make flash`` 类似，但只有主应用程序被编译和重新烧录。
快速重置
======================
键盘快捷键 ``Ctrl-T Ctrl-R`` 将通过 RTS 线（如果已连接）重置开发板。
暂停应用程序
=====================
通过快捷键 ``Ctrl-T Ctrl-P`` 重启进入 bootloader，开发板将不运行任何程序。等待其他设备启动时可以使用此操作。使用快捷键 ``Ctrl-T Ctrl-R`` 重新启动应用程序。
输出显示开关
================
暂停屏幕上的输出，以查看之前日志，可以使用快捷键 ``Ctrl-T Ctrl-Y`` 切换显示（当显示关闭时丢弃所有的串行数据）。这样您可以停下来查看日志，不必关闭显示器就可以快速恢复打印。
Simple Monitor
=======================
较早版本的 ESP-IDF 使用 pySerial_ 命令行程序 miniterm_ 作为串行控制台程序。
这个程序仍然可以通过 ``make simple_monitor`` 运行。
IDF Monitor 基于 miniterm 并使用相同的快捷键。
IDF Monitor 已知问题
=============================
Windows 环境下已知问题
~~~~~~~~~~~~~~~~~~~~~~~~~~
- 如果您使用支持 idf_monitor 的 Windows 环境，却收到错误 "winpty: command not found”，请运行 ``pacman -S winpty`` 进行修复。
- 由于 Windows 控制台的限制，gdb 中的箭头键和其他一些特殊键不起作用。
- 偶尔当 “make” 退出时，可能会在 idf_monitor 恢复之前暂停 30 秒。
- 偶尔当 "gdb" 运行时，它可能会暂停一段时间，然后才开始与 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

12
docs/zh_CN/get-started/index.rst
View file

@ -64,6 +64,8 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了
如果你使用其它开发板，请查看下面的内容。
.. _get-started-step-by-step:
.. _get-started-setup-toolchain:
设置工具链
@ -220,7 +222,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
如果 ESP32-DevKitC 板载的是 ESP32-SOLO-1 模组，请务必在烧写示例程序之前在 menuconfig 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。
.. _get-started-build-flash:
.. _get-started-build-and-flash:
编译和烧写
===============
@ -265,7 +267,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
如果你想使用 Eclipse IDE 而不是运行 ``make``，请参考 :doc:`Eclipse guide <eclipse-setup>`。
.. _get-started-build-monitor:
.. _get-started-monitor:
监视器
=======
@ -301,9 +303,9 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
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
或者监视器程序启动失败，那么可能你的开发板用的是 26 MHz 晶振，而 ESP-IDF 默认的是 40 MHz 晶振。请退出监视器，回到 :ref:`配置 <get-started-configure>`，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz，然后再次 :ref:`编译和烧写 <get-started-build-flash>`。请在 ``make menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。
或者监视器程序启动失败，那么可能你的开发板用的是 26 MHz 晶振，而 ESP-IDF 默认的是 40 MHz 晶振。请退出监视器，回到 :ref:`配置 <get-started-configure>`，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz，然后再次 :ref:`编译和烧写 <get-started-build-and-flash>`。请在 ``make menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。
要一次性执行 ``make flash`` 和 ``make monitor``，输入 ``make flash monitor``。参考文档 :doc:`IDF Monitor <idf-monitor>` 里的快捷键和更多内容。
要一次性执行 ``make flash`` 和 ``make monitor``，输入 ``make flash monitor``。参考文档 :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` 里的快捷键和更多内容。
你已完成 ESP32 的入门！
@ -329,7 +331,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
establish-serial-connection
make-project
eclipse-setup
idf-monitor
../api-guides/tools/idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/