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

Merge branch 'feature/cmake_default_build_system' into 'master'

Browse source 
cmake: Make CMake the default build system

Closes IDF-198 and IDF-325

See merge request espressif/esp-idf!5328
This commit is contained in:
Angus Gratton 2019-07-10 08:16:39 +08:00
commit 058ef98c33
224 changed files with 7029 additions and 7135 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
Kconfig
View file

@ -46,11 +46,11 @@ mainmenu "Espressif IoT Development Framework Configuration"
The executable name/path that is used to run python. On some systems Python 2.x
may need to be invoked as python2.
(Note: This option is used with the GNU Make build system only, not idf.py
or CMake-based builds.)
(Note: This option is used with the legacy GNU Make build system only.)
config SDK_MAKE_WARN_UNDEFINED_VARIABLES
bool "'make' warns on undefined variables"
depends on !IDF_CMAKE
default "y"
help
Adds --warn-undefined-variables to MAKEFLAGS. This causes make to
@ -60,6 +60,8 @@ mainmenu "Espressif IoT Development Framework Configuration"
or otherwise missing, but it can be unwanted if you have Makefiles which
depend on undefined variables expanding to an empty string.
(Note: this option is used with the legacy GNU Make build system only.)
endmenu # SDK tool configuration
source "$COMPONENT_KCONFIGS_PROJBUILD"

64
README.md
View file

@ -33,9 +33,17 @@ To start your own project based on an example, copy the example project director
See the Getting Started guide links above for a detailed setup guide. This is a quick reference for common commands when working with ESP-IDF projects:
## Setup Build Environment
(See Getting Started guide for a full list of required steps with details.)
* Install host build dependencies mentioned in Getting Started guide.
* Add `tools/` directory to the PATH
* Run `python -m pip install requirements.txt` to install Python dependencies
## Configuring the Project
`make menuconfig`
`idf.py menuconfig`
* Opens a text-based configuration menu for the project.
* Use up & down arrow keys to navigate the menu.
@ -49,76 +57,48 @@ Once done configuring, press Escape multiple times to exit and say "Yes" to save
## Compiling the Project
`make -j4 all`
`idf.py build`
... will compile app, bootloader and generate a partition table based on the config.
NOTE: The `-j4` option causes `make` to run 4 parallel jobs. This is much faster than the default single job. The recommended number to pass to this option is `-j(number of CPUs + 1)`.
## Flashing the Project
When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running:
`make -j4 flash`
`idf.py -p PORT flash`
This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`.
Replace PORT with the name of your serial port (like `COM3` on Windows, `/dev/ttyUSB0` on Linux, or `/dev/cu.usbserial-X` on MacOS. If the `-p` option is left out, `idf.py flash` will try to flash the first available serial port.
You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it.
This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `idf.py menuconfig`.
You don't need to run `idf.py build` before running `idf.py flash`, `idf.py flash` will automatically rebuild anything which needs it.
## Viewing Serial Output
The `make monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html).
The `idf.py monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html).
Exit the monitor by typing Ctrl-].
To build, flash and monitor output in one pass, you can run:
`make -j4 flash monitor`
`idf.py flash monitor`
## Compiling & Flashing Only the App
After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
* `make app` - build just the app.
* `make app-flash` - flash just the app.
* `idf.py app` - build just the app.
* `idf.py app-flash` - flash just the app.
`make app-flash` will automatically rebuild the app if any source files have changed.
`idf.py app-flash` will automatically rebuild the app if any source files have changed.
(In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
## Parallel Builds
ESP-IDF supports compiling multiple files in parallel, so all of the above commands can be run as `make -jN` where `N` is the number of parallel make processes to run (generally N should be equal to the number of CPU cores in your system, plus one.)
Multiple make functions can be combined into one. For example: to build the app & bootloader using 5 jobs in parallel, then flash everything, and then display serial output from the ESP32 run:
```
make -j5 flash monitor
```
## The Partition Table
Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
* "Single factory app, no OTA"
* "Factory app, two OTA definitions"
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
For more details about partition tables and how to create custom variations, view the [`docs/en/api-guides/partition-tables.rst`](docs/en/api-guides/partition-tables.rst) file.
## Erasing Flash
The `make flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `make erase_flash`.
The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase_flash`.
This can be combined with other targets, ie `make erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
This can be combined with other targets, ie `idf.py -p PORT erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
# Resources

11
components/esptool_py/Kconfig.projbuild
View file

@ -135,8 +135,9 @@ menu "Serial flasher config"
bool "Detect flash size when flashing bootloader"
default y
help
If this option is set, 'make flash' targets will automatically detect
the flash size and update the bootloader image when flashing.
If this option is set, flashing the project will automatically detect
the flash size of the target chip and update the bootloader image
before it is flashed.
choice ESPTOOLPY_BEFORE
prompt "Before flashing"
@ -181,11 +182,11 @@ menu "Serial flasher config"
default "no_reset" if ESPTOOLPY_AFTER_NORESET
choice ESPTOOLPY_MONITOR_BAUD
prompt "'make monitor' baud rate"
prompt "'idf.py monitor' baud rate"
default ESPTOOLPY_MONITOR_BAUD_115200B
help
Baud rate to use when running 'make monitor' to view serial output
from a running chip.
Baud rate to use when running 'idf.py monitor' or 'make monitor'
to view serial output from a running chip.
Can override by setting the MONITORBAUD environment variable.

2
components/nvs_flash/README.rst
View file

@ -14,7 +14,7 @@ Currently, NVS uses a portion of main flash memory through ``spi_flash_{read|wri
Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc.
.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``make erase_flash`` target to erase all contents of the flash chip.
.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase_flash`` target to erase all contents of the flash chip.
.. note:: NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library.

2
components/spi_flash/README.rst
View file

@ -73,7 +73,7 @@ SPI Flash Size
The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000.
By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``.
By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration.
If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``esp_flash_*`` functions (in both software & ROM) to check the bounds.

2
components/spi_flash/README_legacy.rst
View file

@ -29,7 +29,7 @@ SPI Flash Size
The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000.
By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``.
By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration.
If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``spi_flash_*`` functions (in both software & ROM) to check the bounds.

10
docs/TEMPLATE_EXAMPLE_README.md
View file

@ -23,21 +23,21 @@ _If any other items (server, BLE device, app, second chip, whatever) are needed,
### Configure the project
```
make menuconfig
idf.py menuconfig
```
* Set serial port under Serial Flasher Options.
* _If there is any menuconfig configuration that the user user must set for this example, mention this here._
* _If there is any project configuration that the user must set for this example, mention this here._
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
make -j4 flash monitor
idf.py -p PORT flash monitor
```
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

28
docs/conf_common.py
View file

@ -18,6 +18,7 @@ from __future__ import print_function
from __future__ import unicode_literals
import sys
import os
import re
import subprocess
# Note: If extensions (or modules to document with autodoc) are in another directory,
@ -235,25 +236,14 @@ pygments_style = 'sphinx'
# Custom added feature to allow redirecting old URLs
#
# list of tuples (old_url, new_url) for pages to redirect
# (URLs should be relative to document root, only)
html_redirect_pages = [('api-reference/ethernet/index', 'api-reference/network/index'),
('api-reference/ethernet/esp_eth', 'api-reference/network/esp_eth'),
('api-reference/mesh/index', 'api-reference/network/index'),
('api-reference/mesh/esp_mesh', 'api-reference/network/esp_mesh'),
('api-reference/wifi/index', 'api-reference/network/index'),
('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'),
('get-started/idf-monitor', 'api-guides/tools/idf-monitor'),
('get-started-cmake/idf-monitor', 'api-guides/tools/idf-monitor'),
('get-started/get-started-devkitc', 'hw-reference/get-started-devkitc'),
('get-started/get-started-wrover-kit', 'hw-reference/get-started-wrover-kit'),
('get-started/get-started-pico-kit', 'hw-reference/get-started-pico-kit'),
('get-started-cmake/get-started-devkitc', 'hw-reference/get-started-devkitc'),
('get-started-cmake/get-started-wrover-kit', 'hw-reference/get-started-wrover-kit'),
('get-started-cmake/get-started-pico-kit', 'hw-reference/get-started-pico-kit')]
# Redirects should be listed in page_redirects.xt
#
with open("../page_redirects.txt") as f:
lines = [re.sub(" +", " ", l.strip()) for l in f.readlines() if l.strip() != "" and not l.startswith("#")]
for line in lines: # check for well-formed entries
if len(line.split(' ')) != 2:
raise RuntimeError("Invalid line in page_redirects.txt: %s" % line)
html_redirect_pages = [tuple(l.split(' ')) for l in lines]
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.

2
docs/en/api-guides/app_trace.rst
View file

@ -149,7 +149,7 @@ In general user should decide what type of data should be transferred in every d
return res;
}
2. The next step is to build the program image and download it to the target as described in :doc:`Build and Flash <../get-started/make-project>`.
2. The next step is to build the program image and download it to the target as described in the :ref:`Getting Started Guide <get-started-build>`.
3. Run OpenOCD (see :doc:`JTAG Debugging <../api-guides/jtag-debugging/index>`).
4. Connect to OpenOCD telnet server. It can be done using the following command in terminal ``telnet <oocd_host> 4444``. If telnet session is opened on the same machine which runs OpenOCD you can use ``localhost`` as ``<oocd_host>`` in the command above.
5. Start trace data collection using special OpenOCD command. This command will transfer tracing data and redirect them to specified file or socket (currently only files are supported as trace data destination). For description of the corresponding commands see `OpenOCD Application Level Tracing Commands`_.

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

File diff suppressed because it is too large Load diff

652
docs/en/api-guides/build-system-legacy.rst Normal file
View file

@ -0,0 +1,652 @@
Build System (Legacy GNU Make)
******************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
This document explains the legacy GNU Make Espressif IoT Development Framework build system and the
concept of "components"
Read this document if you want to know how to organise an ESP-IDF project using GNU Make build system.
We recommend using the esp-idf-template_ project as a starting point for your project.
Using the Build System
======================
The esp-idf README file contains a description of how to use the build system to build your project.
Overview
========
An ESP-IDF project can be seen as an amalgamation of a number of components.
For example, for a webserver that shows the current humidity, there could be:
- The ESP32 base libraries (libc, rom bindings etc)
- The Wi-Fi drivers
- A TCP/IP stack
- The FreeRTOS operating system
- A webserver
- A driver for the humidity sensor
- Main code tying it all together
ESP-IDF makes these components explicit and configurable. To do that,
when a project is compiled, the build environment will look up all the
components in the ESP-IDF directories, the project directories and
(optionally) in additional custom component directories. It then
allows the user to configure the ESP-IDF project using a a text-based
menu system to customize each component. After the components in the
project are configured, the build process will compile the project.
Concepts
--------
- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader.
- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places.
Some things are not part of the project:
- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration.
Example Project
---------------
An example project directory tree might look like this::
- myProject/
- Makefile
- sdkconfig
- components/ - component1/ - component.mk
- Kconfig
- src1.c
- component2/ - component.mk
- Kconfig
- src1.c
- include/ - component2.h
- main/ - src1.c
- src2.c
- component.mk
- build/
This example "myProject" contains the following elements:
- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines
other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which
implements the rest of the ESP-IDF build system.
- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places.
- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
Component directories contain a component makefile - ``component.mk``. This may contain variable definitions
to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details.
Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`.
Project Makefiles
-----------------
Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal.
Minimal Example Makefile
^^^^^^^^^^^^^^^^^^^^^^^^
::
PROJECT_NAME := myProject
include $(IDF_PATH)/make/project.mk
Mandatory Project Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf.
Optional Project Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^
These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details.
- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces.
- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``.
- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components.
- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories.
- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size.
- ``TEST_EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process of unit tests.
Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``.
These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile.
Component Makefiles
-------------------
Each project contains one or more components, which can either be part of esp-idf or added from other component directories.
A component is any directory that contains a ``component.mk`` file.
Searching for Components
------------------------
The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components.
Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories.
Multiple components with the same name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the
idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories
contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components
with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there.
If used in this way, the esp-idf directory itself can remain untouched.
Minimal Component Makefile
^^^^^^^^^^^^^^^^^^^^^^^^^^
The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set:
- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library
- A sub-directory "include" will be added to the global include search path for all other components.
- The component library will be linked into the project app.
See `example component makefiles`_ for more complete component makefile examples.
Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process.
.. component variables:
Preset Component Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^
The following component-specific variables are available for use inside ``component.mk``, but should not be modified:
- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces.
- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory.
- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory.
- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``.
The following variables are set at the project level, but exported for use in the component build:
- ``PROJECT_NAME``: Name of the project, as set in project Makefile
- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile.
- ``COMPONENTS``: Name of all components that are included in this build.
- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``.
- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain.
- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain.
- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`.
- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values.
- ``PROJECT_VER``: Project version.
* If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used.
* Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``.
* Else, if the project is located inside a Git repository, the output of git describe will be used.
* Otherwise, ``PROJECT_VER`` will be "1".
If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
Optional Project-Wide Component Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables can be set inside ``component.mk`` to control build settings across the entire project:
- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
directory, which will be added to the include search path for
all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile
this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for
the app executable. Defaults to ``-l$(COMPONENT_NAME)``. If
adding pre-compiled libraries to this directory, add them as
absolute paths - ie $(COMPONENT_PATH)/libwhatever.a
- ``COMPONENT_DEPENDS``: Optional list of component names that should
be compiled before this component. This is not necessary for
link-time dependencies, because all component include directories
are available at all times. It is necessary if one component
generates an include file which you then want to include in another
component. Most components do not need to set this variable.
- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths
to files which should trigger a re-link of the ELF file if they change.
Typically used for linker script files and binary libraries. Most components do
not need to set this variable.
The following variable only works for components that are part of esp-idf itself:
- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths
(relative to COMPONENT_PATH) used by the component. These will be
checked (and initialised if necessary) by the build process. This
variable is ignored if the component is outside the IDF_PATH
directory.
Optional Component-Specific Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following variables can be set inside ``component.mk`` to control the build of that component:
- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
the component directory, which will be added to the include search
path for this component's source files only.
- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when
compiling the component's source files. These will be prefixed with
'-I' and passed as-is to the compiler. Similar to the
``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not
expanded relative to the component directory.
- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
component directory, which will be searched for source files (``*.cpp``,
``*.c``, ``*.S``). Defaults to '.', ie the component directory
itself. Override this to specify a different list of directories
which contain source files.
- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o
file for each source file that is found in ``COMPONENT_SRCDIRS``.
Overriding this list allows you to exclude source files in
``COMPONENT_SRCDIRS`` that would otherwise be compiled. See
`Specifying source files`
- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build
directory, of any files that are generated using custom make rules
in the component.mk file and which need to be removed as part of
``make clean``. See `Source Code Generation`_ for an example.
- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These
targets allow you to fully override the default build behaviour for
the component. See `Fully Overriding The Component Makefile`_ for
more details.
- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component
produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built),
and most other component variables are ignored. This flag is used for IDF
internal components which contain only ``KConfig.projbuild`` and/or
``Makefile.projbuild`` files to configure the project, but no source files.
- ``CFLAGS``: Flags passed to the C compiler. A default set of
``CFLAGS`` is defined based on project settings. Component-specific
additions can be made via ``CFLAGS +=``. It is also possible
(although not recommended) to override this variable completely for
a component.
- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp
and .S files). A default set of ``CPPFLAGS`` is defined based on
project settings. Component-specific additions can be made via
``CPPFLAGS +=``. It is also possible (although not recommended) to
override this variable completely for a component.
- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of
``CXXFLAGS`` is defined based on project
settings. Component-specific additions can be made via ``CXXFLAGS
+=``. It is also possible (although not recommended) to override
this variable completely for a component.
- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker
script generation functionality. See :doc:`Linker Script Generation <linker-script-generation>`.
To apply compilation flags to a single source file, you can add a variable override as a target, ie::
apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
This can be useful if there is upstream code that emits warnings.
Component Configuration
-----------------------
Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains
configuration settings to add to the "make menuconfig" for this component.
These settings are found under the "Component Settings" menu when menuconfig is run.
To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf.
For an example, see `Adding conditional configuration`_.
Preprocessor Definitions
------------------------
ESP-IDF build systems adds the following C preprocessor definitions on the command line:
- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details.
Build Process Internals
-----------------------
Top Level: Project Makefile
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- "make" is always run from the project directory and the project makefile, typically named Makefile.
- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables`
- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic.
- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top.
- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`.
- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top.
- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration.
- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets.
- In order to compile each component, a recursive make is performed for the component makefile.
To better understand the project make process, have a read through the ``project.mk`` file itself.
Second Level: Component Makefiles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile.
- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component.
- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``.
- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these.
- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file.
- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration.
To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf.
Running Make Non-Interactively
------------------------------
When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable).
Setting ``BATCH_BUILD`` implies the following:
- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``.
- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item.
- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails.
.. _make-size:
Advanced Make Targets
---------------------
- ``make app``, ``make bootloader``, ``make partition table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
- ``make erase_flash`` and ``make erase_ota`` will use esptool.py to erase the entire flash chip and the OTA selection setting from the flash chip, respectively.
- ``make size`` prints some size information about the app. ``make size-components`` and ``make size-files`` are similar targets which print more detailed per-component or per-source-file information, respectively.
Debugging The Make Process
--------------------------
Some tips for debugging the esp-idf build system:
- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make.
- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands.
- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built.
- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile.
For more debugging tips and general make information, see the `GNU Make Manual`.
.. _warn-undefined-variables-legacy:
Warning On Undefined Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names.
If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`.
Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles.
Overriding Parts of the Project
-------------------------------
Makefile.projbuild
^^^^^^^^^^^^^^^^^^
For components that have build requirements that must be evaluated in the top-level
project make pass, you can create a file called ``Makefile.projbuild`` in the
component directory. This makefile is included when ``project.mk`` is evaluated.
For example, if your component needs to add to CFLAGS for the entire
project (not just for its own source files) then you can set
``CFLAGS +=`` in Makefile.projbuild.
``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details.
Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components!
KConfig.projbuild
^^^^^^^^^^^^^^^^^
This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include
configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file.
Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`.
Makefile.componentbuild
^^^^^^^^^^^^^^^^^^^^^^^
For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions
into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included
in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're
included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component.
Configuration-Only Components
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component.
Example Component Makefiles
---------------------------
Because the build environment tries to set reasonable defaults that will work most
of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality.
Here are some more advanced examples of ``component.mk`` makefiles:
Adding source directories
^^^^^^^^^^^^^^^^^^^^^^^^^
By default, sub-directories are ignored. If your project has sources in sub-directories
instead of in the root of the component then you can tell that to the build
system by setting ``COMPONENT_SRCDIRS``::
COMPONENT_SRCDIRS := src1 src2
This will compile all source files in the src1/ and src2/ sub-directories
instead.
Specifying source files
^^^^^^^^^^^^^^^^^^^^^^^
The standard component.mk logic adds all .S and .c files in the source
directories as sources to be compiled unconditionally. It is possible
to circumvent that logic and hard-code the objects to be compiled by
manually setting the ``COMPONENT_OBJS`` variable to the name of the
objects that need to be generated::
COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
COMPONENT_SRCDIRS := . thing anotherthing
Note that ``COMPONENT_SRCDIRS`` must be set as well.
Adding conditional configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The configuration system can be used to conditionally compile some files
depending on the options selected in ``make menuconfig``. For this, ESP-IDF
has the compile_only_if and compile_only_if_not macros:
``Kconfig``::
config FOO_ENABLE_BAR
bool "Enable the BAR feature."
help
This enables the BAR feature of the FOO component.
``component.mk``::
$(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
As can be seen in the example, the ``compile_only_if`` macro takes a condition and a
list of object files as parameters. If the condition is true (in this case: if the
BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will
always be compiled. The opposite goes as well: if the condition is not true, bar.o
will never be compiled. ``compile_only_if_not`` does the opposite: compile if the
condition is false, not compile if the condition is true.
This can also be used to select or stub out an implementation, as such:
``Kconfig``::
config ENABLE_LCD_OUTPUT
bool "Enable LCD output."
help
Select this if your board has a LCD.
config ENABLE_LCD_CONSOLE
bool "Output console text to LCD"
depends on ENABLE_LCD_OUTPUT
help
Select this to output debugging output to the lcd
config ENABLE_LCD_PLOT
bool "Output temperature plots to LCD"
depends on ENABLE_LCD_OUTPUT
help
Select this to output temperature plots
``component.mk``::
# If LCD is enabled, compile interface to it, otherwise compile dummy interface
$(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
$(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
#We need font if either console or plot is enabled
$(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
Note the use of the Make 'or' function to include the font file. Other substitution functions,
like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also
be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains
only whitespace to be false while a variable with any non-whitespace in it is true.
(Note: Older versions of this document advised conditionally adding object file names to
``COMPONENT_OBJS``. While this still is possible, this will only work when all object
files for a component are named explicitely, and will not clean up deselected object files
in a ``make clean`` pass.)
Source Code Generation
^^^^^^^^^^^^^^^^^^^^^^
Some components will have a situation where a source file isn't
supplied with the component itself but has to be generated from
another file. Say our component has a header file that consists of the
converted binary data of a BMP file, converted using a hypothetical
tool called bmp2h. The header file is then included in as C source
file called graphics_lib.c::
COMPONENT_EXTRA_CLEAN := logo.h
graphics_lib.o: logo.h
logo.h: $(COMPONENT_PATH)/logo.bmp
bmp2h -i $^ -o $@
In this example, graphics_lib.o and logo.h will be generated in the
current directory (the build directory) while logo.bmp comes with the
component and resides under the component path. Because logo.h is a
generated file, it needs to be cleaned when make clean is called which
why it is added to the COMPONENT_EXTRA_CLEAN variable.
Cosmetic Improvements
^^^^^^^^^^^^^^^^^^^^^
Because logo.h is a generated file, it needs to be cleaned when make
clean is called which why it is added to the COMPONENT_EXTRA_CLEAN
variable.
Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be
generated before ``graphics_lib.c`` is compiled.
If a a source file in another component included ``logo.h``, then this
component's name would have to be added to the other component's
``COMPONENT_DEPENDS`` list to ensure that the components were built
in-order.
Embedding Binary Data
^^^^^^^^^^^^^^^^^^^^^
Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way::
COMPONENT_EMBED_FILES := server_root_cert.der
Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string::
COMPONENT_EMBED_TXTFILES := server_root_cert.pem
The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end");
The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
Code and Data Placements
------------------------
ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through
linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking
app binary. See :doc:`Linker Script Generation <linker-script-generation>` for a quick start guide as well as a detailed discussion
of the mechanism.
Fully Overriding The Component Makefile
---------------------------------------
Obviously, there are cases where all these recipes are insufficient for a
certain component, for example when the component is basically a wrapper
around another third-party component not originally intended to be
compiled under this build system. In that case, it's possible to forego
the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and
possibly COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk``
target. The build target can do anything as long as it creates
$(COMPONENT_LIBRARY) for the project make process to link into the app binary.
(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable
is overridden then the component can instruct the linker to link other binaries instead.)
.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
.. _esp-idf-template: https://github.com/espressif/esp-idf-template
.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
.. _custom-sdkconfig-defaults-legacy:
Custom sdkconfig defaults
-------------------------
For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch.
To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
Save flash arguments
--------------------
There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments::
--flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
Then use flash arguments as the arguemnts for esptool write_flash arguments::
python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
Building the Bootloader
=======================
The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build.
The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project.
This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details.

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

File diff suppressed because it is too large Load diff

2
docs/en/api-guides/console.rst
View file

@ -16,7 +16,7 @@ Line editing
Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key.
.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``make monitor`` from project directory).
.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
Here is an overview of functions provided by `linenoise`_ library.

4
docs/en/api-guides/core_dump.rst
View file

@ -16,7 +16,7 @@ ESP-IDF provides special script `espcoredump.py` to help users to retrieve and a
Configuration
-------------
There are a number of core dump related configuration options which user can choose in configuration menu of the application (`make menuconfig`).
There are a number of core dump related configuration options which user can choose in project configuration menu (`idf.py menuconfig`).
1. Core dump data destination (`Components -> ESP32-specific config -> Core dump -> Data destination`):
@ -93,7 +93,7 @@ Generic command syntax:
* --gdb,-g GDB. Path to gdb to use for data retrieval.
* --core,-c CORE. Path to core dump file to use (if skipped core dump will be read from flash).
* --core-format,-t CORE_FORMAT. Specifies that file passed with "-c" is an ELF ("elf"), dumped raw binary ("raw") or base64-encoded ("b64") format.
* --off,-o OFF. Offset of coredump partition in flash (type `make partition_table` to see it).
* --off,-o OFF. Offset of coredump partition in flash (type `idf.py partition_table` to see it).
* --save-core,-s SAVE_CORE. Save core to file. Othwerwise temporary core file will be deleted. Ignored with "-c".
* --rom-elf,-r ROM_ELF. Path to ROM ELF file to use (if skipped "esp32_rom.elf" is used).
* --print-mem,-m Print memory dump. Used only with "info_corefile".

13
docs/en/api-guides/freertos-smp.rst
View file

@ -74,8 +74,9 @@ used to free memory pointed to by TLSP. Call
Callbacks.
:ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be
configured using ``make meunconfig`` such as running ESP-IDF in Unicore Mode,
or configuring the number of Thread Local Storage Pointers each task will have.
set in the project configuration (``idf.py menuconfig``) such as running ESP-IDF in
Unicore (single core) Mode, or configuring the number of Thread Local Storage Pointers
each task will have.
.. _backported-features:
@ -478,10 +479,10 @@ For more details see :doc:`FreeRTOS API reference<../api-reference/system/freert
Configuring ESP-IDF FreeRTOS
----------------------------
The ESP-IDF FreeRTOS can be configured using ``make menuconfig`` under
``Component_Config/FreeRTOS``. The following section highlights some of the
ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF
FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>`
The ESP-IDF FreeRTOS can be configured in the project configuration menu
(``idf.py menuconfig``) under ``Component Config/FreeRTOS``. The following section
highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of
ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>`
:ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only
on **PRO_CPU**. Note that this is **not equivalent to running vanilla

6
docs/en/api-guides/index.rst
View file

@ -7,7 +7,7 @@ API Guides
General Notes <general-notes>
Build System <build-system>
Build System (CMake) <build-system-cmake>
Build System (Legacy GNU Make) <build-system-legacy>
Error Handling <error-handling>
Fatal Errors <fatal-errors>
Event Handling <event-handling>
@ -22,9 +22,9 @@ API Guides
Partition Tables <partition-tables>
Secure Boot <../security/secure-boot>
ULP Coprocessor <ulp>
ULP Coprocessor (CMake) <ulp-cmake>
ULP Coprocessor (Legacy GNU Make) <ulp-legacy>
Unit Testing <unit-tests>
Unit Testing (CMake) <unit-tests-cmake>
Unit Testing (Legacy GNU Make) <unit-tests-legacy>
Application Level Tracing <app_trace>
Console Component <console>
ROM debug console <romconsole>

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

@ -8,7 +8,7 @@ All versions of ESP-WROVER-KIT boards have built-in JTAG functionality. Putting
Configure Hardware
^^^^^^^^^^^^^^^^^^
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options-cmake`.
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:

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

@ -62,7 +62,7 @@ Debugging using JTAG and application loading / monitoring is integrated under th
If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection.
Depending on user preferences, both `debugger` and `make` can be operated directly from terminal / command line, instead from Eclipse.
Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal / command line, instead from Eclipse.
.. _jtag-debugging-selecting-jtag-adapter:
@ -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-and-flash`.
Build and upload your application to ESP32 as usual, see :ref:`get-started-build`.
Another option is to write application image to flash using OpenOCD via JTAG with commands like this::

2
docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst
View file

@ -6,7 +6,7 @@ Set up OpenOCD for Windows
IDF Tools Installer
===================
If you are using CMake build system and followed the :doc:`/get-started-cmake/windows-setup` with the ``ESP-IDF Tools Installer`` V1.2 or newer, then by default you will already have ``openocd`` installed.
If you are using CMake build system and followed the :doc:`/get-started/windows-setup` with the ``ESP-IDF Tools Installer`` V1.2 or newer, then by default you will already have ``openocd`` installed.
``ESP-IDF Tools Installer`` adds ``openocd`` to the ``PATH`` so that it can be run from any directory.

2
docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
View file

@ -58,7 +58,7 @@ ESP-IDF has some support options for OpenOCD debugging which can be set at compi
* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
Please see the :ref:`make menuconfig <get-started-configure>` menu for more details on setting compile-time options.
Please see the :ref:`project configuration menu <get-started-configure>` menu for more details on setting compile-time options.
.. _jtag-debugging-tip-freertos-support:

18
docs/en/api-guides/partition-tables.rst
View file

@ -11,12 +11,12 @@ Partition table length is 0xC00 bytes (maximum 95 partition table entries). An M
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
The simplest way to use the partition table is to open the project configuration menu (``idf.py menuconfig``) and choose one of the simple predefined partition tables under :ref:`CONFIG_PARTITION_TABLE_TYPE`:
* "Single factory app, no OTA"
* "Factory app, two OTA definitions"
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition_table` then it will print a summary of the partition table.
Built-in Partition Tables
-------------------------
@ -100,7 +100,7 @@ The 8-bit subtype field is specific to a given partition type. esp-idf currently
- phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
- In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
- To load PHY data from this partition, run ``make menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
- To load PHY data from this partition, open the project configuration menu (``idf.py menuconfig``) and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
- NVS is used to store per-device PHY calibration data (different to initialisation data).
@ -138,7 +138,7 @@ Generating Binary Partition Table
The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
If you configure the partition table CSV name in ``make menuconfig`` and then ``make partition_table``, this conversion is done as part of the build process.
If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process.
To convert CSV to Binary manually::
@ -148,7 +148,7 @@ To convert binary format back to CSV manually::
python gen_esp32part.py binary_partitions.bin input_partitions.csv
To display the contents of a binary partition table on stdout (this is how the summaries displayed when running `make partition_table` are generated::
To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition_table`` are generated::
python gen_esp32part.py binary_partitions.bin
@ -162,12 +162,12 @@ The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option o
Flashing the partition table
----------------------------
* ``make partition_table-flash``: will flash the partition table with esptool.py.
* ``make flash``: Will flash everything including the partition table.
* ``idf.py partition_table-flash``: will flash the partition table with esptool.py.
* ``idf.py flash``: Will flash everything including the partition table.
A manual flashing command is also printed as part of ``make partition_table``.
A manual flashing command is also printed as part of ``idf.py partition_table`` output.
Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``make erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
Partition Tool (parttool.py)
----------------------------

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

@ -6,11 +6,9 @@ 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``
This tool can be launched from an IDF project by running ``idf.py monitor``.
(For the legacy GNU Make system, run ``make monitor``.)
Keyboard Shortcuts
==================
@ -32,7 +30,7 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - 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+F | Build and flash the project | Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+A (or 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. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -103,7 +101,7 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and
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``.
To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) 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.
@ -115,7 +113,7 @@ In the background, IDF Monitor runs the following command::
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.
IDF monitor can be invoked as ``idf.py monitor --print-filter="xyz"``, 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>`.
@ -188,18 +186,6 @@ The captured output for the filtering options ``PRINT_FILTER="wifi esp_image:E l
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
=============================

53
docs/en/api-guides/ulp-cmake.rst → docs/en/api-guides/ulp-legacy.rst
View file

@ -1,7 +1,5 @@
ULP coprocessor programming (CMake)
===================================
:link_to_translation:`zh_CN:[中文]`
ULP coprocessor (Legacy GNU Make)
=================================
.. toctree::
:maxdepth: 1
@ -9,6 +7,7 @@ ULP coprocessor programming (CMake)
Instruction set reference <ulp_instruction_set>
Programming using macros (legacy) <ulp_macros>
.. include:: ../gnu-make-legacy.rst
ULP (Ultra Low Power) coprocessor is a simple FSM which is designed to perform measurements using ADC, temperature sensor, and external I2C sensors, while main processors are in deep sleep mode. ULP coprocessor can access RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. ULP coprocessor uses fixed-width 32-bit instructions, 32-bit memory addressing, and has 4 general purpose 16-bit registers.
@ -27,35 +26,39 @@ Compiling ULP code
To compile ULP code as part of a component, the following steps must be taken:
1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`.
1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`.
.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory.
2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example::
2. Modify the component makefile, adding the following::
...
register_component()
ULP_APP_NAME ?= ulp_$(COMPONENT_NAME)
ULP_S_SOURCES = $(COMPONENT_PATH)/ulp/ulp_source_file.S
ULP_EXP_DEP_OBJECTS := main.o
include $(IDF_PATH)/components/ulp/component_ulp_common.mk
Here is each line explained:
set(ulp_app_name ulp_${COMPONENT_NAME})
set(ulp_s_sources ulp/ulp_assembly_source_file.S)
set(ulp_exp_dep_srcs "ulp_c_source_file.c")
ULP_APP_NAME
Name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file.
ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs})
ULP_S_SOURCES
List of assembly files to be passed to the ULP assembler. These must be absolute paths, i.e. start with ``$(COMPONENT_PATH)``. Consider using ``$(addprefix)`` function if more than one file needs to be listed. Paths are relative to component build directory, so prefixing them is not necessary.
The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts
such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files.
Finally, the third argument specifies the list of component source files which include the header file to be generated.
This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled.
See section below explaining the concept of generated header files for ULP applications.
ULP_EXP_DEP_OBJECTS
List of object files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications.
3. Build the application as usual (e.g. `idf.py app`)
include $(IDF_PATH)/components/ulp/component_ulp_common.mk
Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc.
3. Build the application as usual (e.g. ``idf.py build`` or ``idf.py app``)
Inside, the build system will take the following steps to build ULP program:
1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d).
1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.pS) in the component build directory. This step also generates dependency files (foo.ulp.d).
2. **Run preprocessed assembly sources through assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process.
3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory.
4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes.
@ -71,7 +74,7 @@ To compile ULP code as part of a component, the following steps must be taken:
Accessing ULP program variables
-------------------------------
Global symbols defined in the ULP program may be used inside the main program.
Global symbols defined in the ULP program may be used inside the main program.
For example, ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep::
@ -82,10 +85,10 @@ For example, ULP program may define a variable ``measurement_count`` which will
move r3, measurement_count
ld r3, r3, 0
Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``.
Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``$(ULP_APP_NAME).h`` and ``$(ULP_APP_NAME).ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``.
The header file contains declaration of the symbol::
extern uint32_t ulp_measurement_count;
Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take address of the symbol and cast to the appropriate type.
@ -136,7 +139,7 @@ Once the program is loaded into RTC memory, application can start it, passing th
.. doxygenfunction:: ulp_run
Declaration of the entry point symbol comes from the above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``::
Declaration of the entry point symbol comes from the above mentioned generated header file, ``$(ULP_APP_NAME).h``. In assembly source of the ULP application, this symbol must be marked as ``.global``::
.global entry

50
docs/en/api-guides/ulp.rst
View file

@ -1,5 +1,7 @@
ULP coprocessor programming
===========================
===================================
:link_to_translation:`zh_CN:[中文]`
.. toctree::
:maxdepth: 1
@ -25,39 +27,35 @@ Compiling ULP code
To compile ULP code as part of a component, the following steps must be taken:
1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`.
1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`.
.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory.
.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
2. Modify the component makefile, adding the following::
2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example::
ULP_APP_NAME ?= ulp_$(COMPONENT_NAME)
ULP_S_SOURCES = $(COMPONENT_PATH)/ulp/ulp_source_file.S
ULP_EXP_DEP_OBJECTS := main.o
include $(IDF_PATH)/components/ulp/component_ulp_common.mk
Here is each line explained:
...
register_component()
ULP_APP_NAME
Name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file.
set(ulp_app_name ulp_${COMPONENT_NAME})
set(ulp_s_sources ulp/ulp_assembly_source_file.S)
set(ulp_exp_dep_srcs "ulp_c_source_file.c")
ULP_S_SOURCES
List of assembly files to be passed to the ULP assembler. These must be absolute paths, i.e. start with ``$(COMPONENT_PATH)``. Consider using ``$(addprefix)`` function if more than one file needs to be listed. Paths are relative to component build directory, so prefixing them is not necessary.
ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs})
ULP_EXP_DEP_OBJECTS
List of object files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications.
The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts
such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files.
Finally, the third argument specifies the list of component source files which include the header file to be generated.
This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled.
See section below explaining the concept of generated header files for ULP applications.
include $(IDF_PATH)/components/ulp/component_ulp_common.mk
Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc.
3. Build the application as usual (e.g. `idf.py app`)
3. Build the application as usual (e.g. `make app`)
Inside, the build system will take the following steps to build ULP program:
1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.pS) in the component build directory. This step also generates dependency files (foo.ulp.d).
1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d).
2. **Run preprocessed assembly sources through assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process.
3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory.
4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes.
@ -73,7 +71,7 @@ To compile ULP code as part of a component, the following steps must be taken:
Accessing ULP program variables
-------------------------------
Global symbols defined in the ULP program may be used inside the main program.
Global symbols defined in the ULP program may be used inside the main program.
For example, ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep::
@ -84,10 +82,10 @@ For example, ULP program may define a variable ``measurement_count`` which will
move r3, measurement_count
ld r3, r3, 0
Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``$(ULP_APP_NAME).h`` and ``$(ULP_APP_NAME).ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``.
Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``.
The header file contains declaration of the symbol::
extern uint32_t ulp_measurement_count;
Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take address of the symbol and cast to the appropriate type.
@ -138,7 +136,7 @@ Once the program is loaded into RTC memory, application can start it, passing th
.. doxygenfunction:: ulp_run
Declaration of the entry point symbol comes from the above mentioned generated header file, ``$(ULP_APP_NAME).h``. In assembly source of the ULP application, this symbol must be marked as ``.global``::
Declaration of the entry point symbol comes from the above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``::
.global entry

57
docs/en/api-guides/unit-tests-cmake.rst → docs/en/api-guides/unit-tests-legacy.rst
View file

@ -1,8 +1,8 @@
Unit Testing in ESP32 (CMake)
=============================
Unit Testing (Legacy GNU Make)
==============================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
.. include:: ../gnu-make-legacy.rst
ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively.
@ -28,18 +28,9 @@ Identifiers are used to group related test, or tests with specific properties.
There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case.
``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``.
The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt <component-directories-cmake>`, since they are themselves,
components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components
:ref:`should list their sources manually <cmake-file-globbing>`; for component tests however, this requirement is relaxed and the
use of ``COMPONENT_SRCDIRS`` is advised.
Each `test` subdirectory needs to include component.mk file with at least the following line of code::
Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows:
.. code:: cmake
idf_component_register(SRC_DIRS "."
INCLUDE_DIRS "."
REQUIRES unity)
COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive
See http://www.throwtheswitch.org/unity for more information about writing tests in Unity.
@ -87,13 +78,27 @@ As the secnario in the above example, slave should get GPIO level after master s
DUT1 (master) console::
Waiting for signal: [output high level]!
Please press "Enter" key to once any board send this signal.
Please press "Enter" key once any board send this signal.
DUT2 (slave) console::
Send signal: [output high level]!
Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level.
Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level.
Signals can also be used to pass parameters between multiple devices. For example, DUT1 want to know the MAC address of DUT2, so it can connect to DUT2.
In this case, ``unity_wait_for_signal_param`` and ``unity_send_signal_param`` can be used:
DUT1 console::
Waiting for signal: [dut2 mac address]!
Please input parameter value from any board send this signal and press "Enter" key.
DUT2 console::
Send signal: [dut2 mac address][10:20:30:40:50:60]!
Once the signal is sent from DUT2, you need to input ``10:20:30:40:50:60`` on DUT1 and press "Enter". Then DUT1 will get the MAC address string of DUT2 and unblocks from ``unity_wait_for_signal_param``, start to connect to DUT2.
Add multiple stages test cases
@ -128,15 +133,15 @@ Make sure that IDF_PATH environment variable is set to point to the path of esp-
Change into tools/unit-test-app directory to configure and build it:
* `idf.py menuconfig` - configure unit test app.
* `make menuconfig` - configure unit test app.
* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
* `idf.py -T xxx build` - build unit test app with tests for specific components.
* `idf.py -T all -E xxx build` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp -E mbedtls build` - build all unit tests exludes ulp and mbedtls components).
* `make TESTS_ALL=1` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
* `make TEST_COMPONENTS='xxx'` - build unit test app with tests for specific components.
* `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'` - build all unit tests exludes ulp and mbedtls components).
When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output.
When the build finishes, it will print instructions for flashing the chip. You can simply run ``make flash`` to flash all build output.
You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing.
You can also run ``make flash TESTS_ALL=1`` or ``make TEST_COMPONENTS='xxx'`` to build and flash. Everything needed will be rebuilt automatically before flashing.
Use menuconfig to set the serial port for flashing.
@ -177,13 +182,13 @@ Normal case will print the case name and description. Master slave cases will al
Test cases can be run by inputting one of the following:
- Test case name in quotation marks to run a single test case
- Test case name in quotation marks (for example, ``"esp_ota_begin() verifies arguments"``) to run a single test case.
- Test case index to run a single test case
- Test case index (for example, ``1``) to run a single test case.
- Module name in square brackets to run all test cases for a specific module
- Module name in square brackets (for example, ``[cxx]``) to run all test cases for a specific module.
- An asterisk to run all test cases
- An asterisk (``*``) to run all test cases
``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case.
These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros.

53
docs/en/api-guides/unit-tests.rst
View file

@ -1,5 +1,5 @@
Unit Testing in ESP32
=====================
=============================
:link_to_translation:`zh_CN:[中文]`
ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively.
@ -26,9 +26,18 @@ Identifiers are used to group related test, or tests with specific properties.
There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case.
``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``.
Each `test` subdirectory needs to include component.mk file with at least the following line of code::
The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt <component-directories>`, since they are themselves,
components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components
:ref:`should list their sources manually <cmake-file-globbing>`; for component tests however, this requirement is relaxed and the
use of ``COMPONENT_SRCDIRS`` is advised.
COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive
Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows:
.. code:: cmake
idf_component_register(SRC_DIRS "."
INCLUDE_DIRS "."
REQUIRES unity)
See http://www.throwtheswitch.org/unity for more information about writing tests in Unity.
@ -76,27 +85,13 @@ As the secnario in the above example, slave should get GPIO level after master s
DUT1 (master) console::
Waiting for signal: [output high level]!
Please press "Enter" key once any board send this signal.
Please press "Enter" key to once any board send this signal.
DUT2 (slave) console::
Send signal: [output high level]!
Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level.
Signals can also be used to pass parameters between multiple devices. For example, DUT1 want to know the MAC address of DUT2, so it can connect to DUT2.
In this case, ``unity_wait_for_signal_param`` and ``unity_send_signal_param`` can be used:
DUT1 console::
Waiting for signal: [dut2 mac address]!
Please input parameter value from any board send this signal and press "Enter" key.
DUT2 console::
Send signal: [dut2 mac address][10:20:30:40:50:60]!
Once the signal is sent from DUT2, you need to input ``10:20:30:40:50:60`` on DUT1 and press "Enter". Then DUT1 will get the MAC address string of DUT2 and unblocks from ``unity_wait_for_signal_param``, start to connect to DUT2.
Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level.
Add multiple stages test cases
@ -131,15 +126,15 @@ Make sure that IDF_PATH environment variable is set to point to the path of esp-
Change into tools/unit-test-app directory to configure and build it:
* `make menuconfig` - configure unit test app.
* `idf.py menuconfig` - configure unit test app.
* `make TESTS_ALL=1` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
* `make TEST_COMPONENTS='xxx'` - build unit test app with tests for specific components.
* `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'` - build all unit tests exludes ulp and mbedtls components).
* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
* `idf.py -T xxx build` - build unit test app with tests for specific components.
* `idf.py -T all -E xxxbuild` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp mbedtls build` - build all unit tests exludes ulp and mbedtls components).
When the build finishes, it will print instructions for flashing the chip. You can simply run ``make flash`` to flash all build output.
When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output.
You can also run ``make flash TESTS_ALL=1`` or ``make TEST_COMPONENTS='xxx'`` to build and flash. Everything needed will be rebuilt automatically before flashing.
You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing.
Use menuconfig to set the serial port for flashing.
@ -180,13 +175,13 @@ Normal case will print the case name and description. Master slave cases will al
Test cases can be run by inputting one of the following:
- Test case name in quotation marks (for example, ``"esp_ota_begin() verifies arguments"``) to run a single test case.
- Test case name in quotation marks to run a single test case
- Test case index (for example, ``1``) to run a single test case.
- Test case index to run a single test case
- Module name in square brackets (for example, ``[cxx]``) to run all test cases for a specific module.
- Module name in square brackets to run all test cases for a specific module
- An asterisk (``*``) to run all test cases
- An asterisk to run all test cases
``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case.
These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros.

17
docs/en/api-reference/kconfig.rst
View file

@ -1,19 +1,28 @@
Configuration Options
Project Configuration
*********************
Introduction
============
ESP-IDF uses Kconfig_ system to provide a compile-time configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc.
ESP-IDF uses Kconfig_ system to provide a compile-time project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc.
Applications developers can use ``make menuconfig`` build target to edit components' configuration. This configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to component makefiles.
.. _project-configuration-menu:
Project Configuration Menu
==========================
Application developers can open a terminal-based project configuration menu with the ``idf.py menuconfig`` build target.
After being updated, this configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to the project build system and source files.
(For the legacy GNU Make build system, the project configuration menu is opened with ``make menuconfig``.)
Using sdkconfig.defaults
========================
When updating ESP-IDF version, it is not uncommon to find that new Kconfig options are introduced. When this happens, application build targets will offer an interactive prompt to select values for the new options. New values are then written into ``sdkconfig`` file. To supress interactive prompts, applications can either define ``BATCH_BUILD`` environment variable, which will cause all prompts to be suppressed. This is the same effect as that of ``V`` or ``VERBOSE`` variables. Alternatively, ``defconfig`` build target can be used to update configuration for all new variables to the default values.
In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``make defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`.
In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``idf.py defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`.
Kconfig Formatting Rules
========================

8
docs/en/api-reference/protocols/mqtt.rst
View file

@ -94,12 +94,12 @@ SSL
For more options on ``esp_mqtt_client_config_t``, please refer to API reference below
Change settings in ``menuconfig``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Change settings in Project Configuration Menu
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
make menuconfig
-> Component config -> ESP-MQTT Configuration
idf.py menuconfig
-> Component config -> ESP-MQTT Configuration
- :ref:`CONFIG_MQTT_PROTOCOL_311`: Enables 3.1.1 version of MQTT protocol

10
docs/en/api-reference/system/efuse.rst
View file

@ -31,8 +31,8 @@ The component has API functions for reading and writing fields. Access to the fi
CSV files:
* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command 'make efuse_common_table' or `idf.py efuse_common_table`). Note that changes in this file can lead to incorrect operation.
* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file (run command 'make efuse_custom_table' or `idf.py efuse_custom_table`).
* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse_common_table``). Note that changes in this file can lead to incorrect operation.
* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse_custom_table``.
Description CSV file
@ -84,7 +84,7 @@ efuse_table_gen.py tool
The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out on the uniqueness of the names and overlaps of the field bits. If an additional `custom` file is used, it will be checked with the existing `common` file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that caused the error. C-source files contain structures of type `esp_efuse_desc_t`.
To generate a `common` files, use the following command 'make efuse_common_table' or `idf.py efuse_common_table` or:
To generate a `common` files, use the following command ``idf.py efuse_common_table`` or:
::
@ -96,7 +96,7 @@ After generation in the folder `esp32` create:
* `esp_efuse_table.c` file.
* In `include` folder `esp_efuse_table.c` file.
To generate a `custom` files, use the following command 'make efuse_custom_table' or `idf.py efuse_custom_table` or:
To generate a `custom` files, use the following command ``idf.py efuse_custom_table`` or:
::
@ -170,7 +170,7 @@ For frequently used fields, special functions are made, like this :cpp:func:`esp
How add a new field
-------------------
1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``make show_efuse_table`` or ``idf.py show_efuse_table`` or the next command:
1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show_efuse_table`` or the next command:
::

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

@ -420,7 +420,7 @@ Interrupt respectively.
Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS.
To enable legacy hooks, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS` should be enabled
in ``make menuconfig``.
in :doc:`project configuration menu </api-reference/kconfig>`.
Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()``
and ``vApplicationTickHook()`` can only be defined once. However, the ESP32 is dual core

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

@ -38,7 +38,7 @@ Heap corruption detection allows you to detect various types of heap memory erro
Assertions
^^^^^^^^^^
The heap implementation (``multi_heap.c``, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in ``make menuconfig`` under ``Compiler options``.
The heap implementation (``multi_heap.c``, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in the project configuration menu under ``Compiler options`` -> :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`.
If a heap integrity assertion fails, a line will be printed like ``CORRUPT HEAP: multi_heap.c:225 detected at 0x3ffbb71c``. The memory address which is printed is the address of the heap structure which has corrupt content.
@ -62,7 +62,7 @@ Configuration
Temporarily increasing the heap corruption detection level can give more detailed information about heap corruption errors.
In ``make menuconfig``, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels:
In the project configuration menu, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels:
Basic (no poisoning)
++++++++++++++++++++
@ -143,7 +143,7 @@ Standalone Mode
Once you've identified the code which you think is leaking:
- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Standalone`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`).
- In the project configuration menu, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Standalone`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`).
- Call the function :cpp:func:`heap_trace_init_standalone` early in the program, to register a buffer which can be used to record the memory trace.
- Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory.
- Call the function :cpp:func:`heap_trace_stop` to stop the trace once the suspect piece of code has finished executing.
@ -205,7 +205,7 @@ In ``HEAP_TRACE_LEAKS`` mode, for each traced memory allocation which has not al
- ``caller 0x...`` gives the call stack of the call to malloc()/free(), as a list of PC addresses.
These can be decoded to source files and line numbers, as shown above.
The depth of the call stack recorded for each trace entry can be configured in ``make menuconfig``, under ``Heap Memory Debugging`` -> ``Enable heap tracing`` -> ``Heap tracing stack depth``. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each ``heap_trace_record_t`` record by eight bytes.
The depth of the call stack recorded for each trace entry can be configured in the project configuration menu, under ``Heap Memory Debugging`` -> ``Enable heap tracing`` -> ``Heap tracing stack depth``. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each ``heap_trace_record_t`` record by eight bytes.
Finally, the total number of 'leaked' bytes (bytes allocated but not freed while trace was running) is printed, and the total number of allocations this represents.
@ -217,9 +217,9 @@ Host-Based Mode
Once you've identified the code which you think is leaking:
- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Host-Based`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`).
- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``Data Destination`` and select ``Trace memory``.
- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``FreeRTOS SystemView Tracing`` and check ``SystemView Tracing Enable``.
- In the project configuration menu, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> :ref:`CONFIG_HEAP_TRACING_DEST` and select ``Host-Based``.
- In the project configuration menu, navigate to ``Component settings`` -> ``Application Level Tracing`` -> :ref:`CONFIG_ESP32_APPTRACE_DESTINATION` and select ``Trace memory``.
- In the project configuration menu, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``FreeRTOS SystemView Tracing`` and enable :ref:`CONFIG_SYSVIEW_ENABLE`.
- Call the function :cpp:func:`heap_trace_init_tohost` early in the program, to initialize JTAG heap tracing module.
- Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory.
In host-based mode argument to this function is ignored and heap tracing module behaves like ``HEAP_TRACE_ALL`` was passed: all allocations and deallocations are sent to the host.
@ -250,7 +250,7 @@ An example::
To gather and analyse heap trace do the following on the host:
1. Build the program and download it to the target as described in :doc:`Build and Flash </get-started/make-project>`.
1. Build the program and download it to the target as described in :ref:`Getting Started Guide <get-started-build>`.
2. Run OpenOCD (see :doc:`JTAG Debugging </api-guides/jtag-debugging/index>`).

4
docs/en/api-reference/system/mem_alloc.rst
View file

@ -41,7 +41,7 @@ DRAM
At startup, the DRAM heap contains all data memory which is not statically allocated by the app. Reducing statically allocated buffers will increase the amount of available free heap.
To find the amount of statically allocated memory, use the :ref:`make size <make-size>` or :ref:`idf.py size <idf.py-size>` (for CMake) command.
To find the amount of statically allocated memory, use the :ref:`idf.py size <idf.py-size>` command.
.. note:: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
@ -52,7 +52,7 @@ IRAM
At startup, the IRAM heap contains all instruction memory which is not used by the app executable code.
The :ref:`make size <make-size>` and :ref:`idf.py size <idf.py-size>` commands can be used to find the amount of IRAM used by the app.
The :ref:`idf.py size <idf.py-size>` command can be used to find the amount of IRAM used by the app.
D/IRAM
^^^^^^

9
docs/en/api-reference/system/system.rst
View file

@ -129,12 +129,13 @@ App version
Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file.
The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars.
To set version in your project manually you need to set ``PROJECT_VER`` variable in your project Makefile/CMakeLists.txt:
To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile:
* For Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including project.mk
* For Cmake build system: in application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including project.cmake.
* In application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including ``project.cmake``.
If ``PROJECT_VER`` variable is not set in project Makefile/CMakeLists.txt then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions.
(For legacy GNU Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including ``project.mk``.)
If ``PROJECT_VER`` variable is not set in the project then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions.
API Reference
-------------

4
docs/en/api-reference/system/wdts.rst
View file

@ -6,7 +6,7 @@ Overview
The ESP-IDF has support for two types of watchdogs: The Interrupt Watchdog Timer
and the Task Watchdog Timer (TWDT). The Interrupt Watchdog Timer and the TWDT
can both be enabled using ``make menuconfig``, however the TWDT can also be
can both be enabled using :ref:`project-configuration-menu`, however the TWDT can also be
enabled during runtime. The Interrupt Watchdog is responsible for detecting
instances where FreeRTOS task switching is blocked for a prolonged period of
time. The TWDT is responsible for detecting instances of tasks running without
@ -63,7 +63,7 @@ longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed
form the TWDT, the TWDT can be deinitialized by calling
:cpp:func:`esp_task_wdt_deinit()`.
By default :ref:`CONFIG_ESP_TASK_WDT` in ``make menuconfig`` will be enabled causing
By default :ref:`CONFIG_ESP_TASK_WDT` in :ref:`project-configuration-menu` be enabled causing
the TWDT to be initialized automatically during startup. Likewise
:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and
:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing

2
docs/en/api-reference/template.rst
View file

@ -79,7 +79,7 @@ API Reference
For example see :idf_file:`docs/en/api-reference/wifi/esp_wifi.rst`
6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp-cmake.rst` for example.
6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp.rst` for example.
Below is the list of common ``.. doxygen...::`` directives:

7
docs/en/cmake-pending-features.rst
View file

@ -1,7 +0,0 @@
.. important::
The following features are not yet supported with the CMake-based build system:
- Eclipse IDE Documentation
Support for these features will be available before CMake becomes the default build system.

4
docs/en/cmake-warning.rst
View file

@ -1,4 +0,0 @@
.. note::
This is documentation for the CMake-based build system which is currently in preview release. If you encounter any gaps or bugs, please report them in the `Issues <https://github.com/espressif/esp-idf/issues>`_ section of the ESP-IDF repository.
The CMake-based build system will become the default build system in ESP-IDF V4.0. The existing GNU Make based build system will be deprecated in ESP-IDF V5.0.

3
docs/en/get-started-cmake/add-idf_path-to-profile.rst
View file

@ -1,3 +0,0 @@
:orphan:
.. Remove this file when the Chinese translation of CMake getting started guide is updated

12
docs/en/get-started-cmake/eclipse-setup.rst
View file

@ -1,12 +0,0 @@
****************************************
Build and Flash with Eclipse IDE (CMake)
****************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon.
.. _eclipse.org: https://www.eclipse.org/

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

@ -1,491 +0,0 @@
*******************
Get Started (CMake)
*******************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
.. include:: ../cmake-pending-features.rst
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 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 compile code for ESP32
* **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
: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 <../hw-reference/get-started-devkitc>
ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit>
ESP32-PICO-KIT <../hw-reference/get-started-pico-kit>
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
.. _get-started-step-by-step-cmake:
Installation Step by Step
=========================
This is a detailed roadmap to walk you through the installation process.
Setting up Development Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-get-prerequisites-cmake` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`macOS <macos-setup>`
* :ref:`get-started-get-esp-idf-cmake`
* :ref:`get-started-set-up-tools-cmake`
* :ref:`get-started-set-up-env-cmake`
Creating Your First Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project-cmake`
* :ref:`get-started-connect-cmake`
* :ref:`get-started-configure-cmake`
* :ref:`get-started-build-cmake`
* :ref:`get-started-flash-cmake`
* :ref:`get-started-build-monitor-cmake`
.. _get-started-get-prerequisites-cmake:
Step 1. Install prerequisites
=============================
Some tools need to be installed on the computer before proceeding to the next steps. Follow the links below for the instructions for your OS:
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
macOS <macos-setup>
* :doc:`windows-setup`
* :doc:`linux-setup`
* :doc:`macos-setup`
.. _get-started-get-esp-idf-cmake:
Step 2. Get ESP-IDF
===================
To build applications for the ESP32, you need the software libraries 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``.
.. 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.
Linux and macOS
~~~~~~~~~~~~~~~
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.
Windows
~~~~~~~
In addition to installing the tools, :ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF.
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions <get-esp-idf-windows-command-line-cmake>`.
.. _get-started-set-up-tools-cmake:
Step 3. Set up the tools
========================
Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc.
Windows
~~~~~~~
:ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools.
If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps:
.. code-block:: batch
cd %userprofile%\esp\esp-idf
install.bat
Linux and macOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/esp-idf
./install.sh
Customizing the tools installation path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path.
If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed.
.. _get-started-set-up-env-cmake:
Step 4. Set up the environment variables
========================================
The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script which does that.
Windows
~~~~~~~
:ref:`get-started-cmake-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step.
Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run:
.. code-block:: batch
%userprofile%\esp\esp-idf\export.bat
Linux and macOS
~~~~~~~~~~~~~~~
In the terminal where you are going to use ESP-IDF, run:
.. code-block:: bash
. $HOME/esp/esp-idf/export.sh
Note the space between the leading dot and the path!
You can also automate this step, making ESP-IDF tools available in every terminal, by adding this line to your ``.profile`` or ``.bash_profile`` script.
.. _get-started-start-project-cmake:
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 ``~/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-cmake:
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-cmake:
Step 7. Configure
=================
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-cmake` and run the project configuration utility ``menuconfig``.
Linux and macOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
idf.py menuconfig
If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead.
Windows
~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
idf.py 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
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
.. 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-cmake:
Step 8. Build the Project
=========================
Build the project by running::
idf.py build
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
$ idf.py build
Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...
... (more lines of build system output)
[527/527] Generating hello-world.bin
esptool.py v2.3.1
Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'
If there are no errors, the build will finish by generating the firmware binary .bin file.
.. _get-started-flash-cmake:
Step 9. Flash onto the Device
=============================
Flash the binaries that you just built onto your ESP32 board by running::
idf.py -p PORT [-b BAUD] flash
Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect-cmake`.
You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``.
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
Running esptool.py in directory [...]/esp/hello_world
Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
esptool.py v2.3.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 22992 bytes to 13019...
Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
Hash of data verified.
Compressed 136672 bytes to 67544...
Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
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>`.
.. _get-started-build-monitor-cmake:
Step 10. Monitor
================
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
Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
--- 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, 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::
You can combine building, flashing and monitoring into one step by running::
idf.py -p PORT flash monitor
See also:
- :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 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.
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`.
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools-cmake`.
Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env-cmake`.
Related Documents
=================
.. toctree::
:maxdepth: 1
establish-serial-connection
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

77
docs/en/get-started-cmake/linux-setup-scratch.rst
View file

@ -1,77 +0,0 @@
******************************************
Setup Linux Toolchain from Scratch (CMake)
******************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- CentOS 7::
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
Compile the Toolchain from Source
=================================
- Install dependencies:
- CentOS 7::
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
- Ubuntu pre-16.04::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
- Ubuntu 16.04 or newer::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- Debian 9::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- Arch::
TODO
Create the working directory and go into it::
mkdir -p ~/esp
cd ~/esp
Download ``crosstool-NG`` and build it:
.. include:: /_build/inc/scratch-build-code.inc
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.

68
docs/en/get-started-cmake/linux-setup.rst
View file

@ -1,68 +0,0 @@
***********************************************
Installation of Prerequisites for Linux (CMake)
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- CentOS 7::
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
Additional Tips
===============
Permission issues /dev/ttyUSB0
------------------------------
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group-cmake>`.
Arch Linux Users
----------------
To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
Related Documents
=================
.. toctree::
:maxdepth: 1
linux-setup-scratch
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

88
docs/en/get-started-cmake/macos-setup-scratch.rst
View file

@ -1,88 +0,0 @@
***********************************************
Setup Toolchain for Mac OS from Scratch (CMake)
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Package Manager
===============
To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or homebrew_ package manager.
MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Install Prerequisites
=====================
- install pip::
sudo easy_install pip
- install pyserial::
pip install --user pyserial
- install CMake & Ninja build:
- If you have HomeBrew, you can run::
brew install cmake ninja
- If you have MacPorts, you can run::
sudo port install cmake ninja
Compile the Toolchain from Source
=================================
- Install dependencies:
- with MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
- with homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
Create a case-sensitive filesystem image::
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
Mount it::
hdiutil mount ~/esp/crosstool.dmg
Create a symlink to your work directory::
mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume
Go into the newly created directory::
cd ~/esp/ctng-volume
Download ``crosstool-NG`` and build it:
.. include:: /_build/inc/scratch-build-code.inc
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.

60
docs/en/get-started-cmake/macos-setup.rst
View file

@ -1,60 +0,0 @@
***********************************************
Installation of Prerequisites for macOS (CMake)
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Install Prerequisites
=====================
ESP-IDF will use the version of Python installed by default on macOS.
- install pip::
sudo easy_install pip
- install pyserial::
pip install --user pyserial
- install CMake & Ninja build:
- If you have HomeBrew_, you can run::
brew install cmake ninja
- If you have MacPorts_, you can run::
sudo port install cmake ninja
- Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads.
- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
.. note::
If an error like this is shown during any step::
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
Related Documents
=================
.. toctree::
:maxdepth: 1
macos-setup-scratch
.. _cmake: https://cmake.org/
.. _ninja: https://ninja-build.org/
.. _ccache: https://ccache.samba.org/
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php

122
docs/en/get-started-cmake/windows-setup-scratch.rst
View file

@ -1,122 +0,0 @@
**********************************
Windows Setup from Scratch (CMake)
**********************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
.. note::
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
.. _get-esp-idf-windows-command-line-cmake:
Get ESP-IDF
===========
.. 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 ``%userprofile%\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
Tools
=====
cmake
^^^^^
Download the latest stable release of CMake_ for Windows and run the installer.
When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
Ninja build
^^^^^^^^^^^
.. note::
Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_ (or you can choose a directory which is already on your Path).
Python 2.x
^^^^^^^^^^
Download the latest Python_ 2.7 for Windows installer, and run it.
The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
pip install --user pyserial
MConf for IDF
^^^^^^^^^^^^^
Download the configuration tool mconf-idf from the `kconfig-frontends releases page <mconf-idf>`_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF.
This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
Download the precompiled Windows toolchain:
|download_link_win32|
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
.. note::
If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
.. _add-directory-windows-path-cmake:
Adding Directory to Path
========================
To add any new directory to your Windows Path environment variable:
Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _MSYS2: https://msys2.github.io/
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/

70
docs/en/get-started-cmake/windows-setup.rst
View file

@ -1,70 +0,0 @@
*************************************************
Installation of Prerequisites for Windows (CMake)
*************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
.. note::
The CMake-based build system is only supported on 64-bit versions of Windows.
Introduction
============
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Python, Git, cross-compilers, menuconfig tool, CMake and Ninja build tools.
For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
.. note::
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
.. _get-started-cmake-windows-tools-installer:
ESP-IDF Tools Installer
=======================
The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe
The installer includes the cross-compilers, OpenOCD, cmake_ and Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for Python_ 3.7 and `Git For Windows`_ if they are not already installed on the computer.
The installer also offers to download one of the ESP-IDF release versions.
Using the Command Prompt
========================
For the remaining Getting Started steps, we're going to use the Windows Command Prompt.
ESP-IDF Tools Installer creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs ``export.bat`` script to set up the environment variables (``PATH``, ``IDF_PATH`` and others). Inside this command prompt, all the installed tools are available.
Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have two options to use them:
1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the new shortcut to the ESP-IDF directory you wish to use.
2. Alternatively, run ``cmd.exe``, then change to the ESP-IDF directory you wish to use, and run ``export.bat``. Note that unlike the previous option, this way requires Python and Git to be present in ``PATH``. If you get errors related to Python or Git not being found, use the first option.
Next Steps
==========
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project-cmake`.
Related Documents
=================
For advanced users who want to customize the install process:
.. toctree::
:maxdepth: 1
windows-setup-scratch
windows-setup-update
.. _MSYS2: https://msys2.github.io/
.. _cmake: https://cmake.org/download/
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _Git for Windows: https://gitforwindows.org/
.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
.. _Github Desktop: https://desktop.github.com/

67
docs/en/get-started-legacy/add-idf_path-to-profile.rst Normal file
View file

@ -0,0 +1,67 @@
Add IDF_PATH to User Profile (Legacy GNU Make)
==============================================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
.. _add-idf_path-to-profile-windows-legacy:
Windows
-------
The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf``
#. Add the ``export`` command to the script file, e.g.::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
Remember to replace back-slashes with forward-slashes in the original Windows path.
#. Save the script file.
#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing::
printenv IDF_PATH
The path previusly entered in the script file should be printed out.
If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
If you got here from section :ref:`get-started-setup-path-legacy`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-legacy`.
.. _add-idf_path-to-profile-linux-macos-legacy:
Linux and MacOS
---------------
Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
export IDF_PATH=~/esp/esp-idf
Log off and log in back to make this change effective.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
Run the following command to check if ``IDF_PATH`` is set::
printenv IDF_PATH
The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
export IDF_PATH=~/esp/esp-idf
If you got here from section :ref:`get-started-setup-path-legacy`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-legacy`.

111
docs/en/get-started-legacy/eclipse-setup.rst Normal file
View file

@ -0,0 +1,111 @@
**************************************************
Build and Flash with Eclipse IDE (Legacy GNU Make)
**************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
.. _eclipse-install-steps-legacy:
Installing Eclipse IDE
======================
The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
* Download the Eclipse Installer for your platform from eclipse.org_.
* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.)
Setting up Eclipse
==================
Once your new Eclipse installation launches, follow these steps:
Import New Project
------------------
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
* Once Eclipse is running, choose File -> Import...
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
Project Properties
------------------
* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer.
* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match).
* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.)
Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
* Click the "Providers" tab
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
Navigate to "C/C++ General" -> "Indexer" property page:
* Check "Enable project specific settings" to enable the rest of the settings on this page.
* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories.
Navigate to "C/C++ Build" -> "Behavior" property page:
* Check "Enable parallel build" to enable multiple build jobs in parallel.
.. _eclipse-build-project-legacy:
Building in Eclipse
-------------------
Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
* Click OK to close the Properties dialog in Eclipse.
* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
* Back in Eclipse, choose Project -> Build to build your project.
**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.
Flash from Eclipse
------------------
You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI:
* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
* Select Build Targets -> Create... from the context menu.
* Type "flash" as the target name. Leave the other options as their defaults.
* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.
Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.)
Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary.
.. _eclipse.org: https://www.eclipse.org/

22
docs/en/get-started-cmake/establish-serial-connection.rst → docs/en/get-started-legacy/establish-serial-connection.rst
View file

@ -1,8 +1,9 @@
Establish Serial Connection with ESP32 (CMake)
==============================================
Establish Serial Connection with ESP32 (Legacy GNU Make)
========================================================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
This section provides guidance how to establish serial connection between ESP32 and PC.
@ -11,7 +12,7 @@ Connect ESP32 to PC
Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them.
Below are the links to drivers for ESP32 boards produced by Espressif:
Below are the links to drivers for ESP32 and other boards produced by Espressif:
.. csv-table::
@ -73,12 +74,8 @@ MacOS ::
ls /dev/cu.*
.. note::
MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
.. _linux-dialout-group-cmake:
.. _linux-dialout-group-legacy:
Adding user to ``dialout`` on Linux
-----------------------------------
@ -141,7 +138,7 @@ Then open serial port in terminal and check, if you see any log printed out by E
...
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
.. note::
@ -149,8 +146,9 @@ If you can see readable log output, it means serial connection is working and yo
.. note::
Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal.
Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal.
If you got here from section :ref:`get-started-connect-legacy` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure-legacy`.
If you got here from :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure-cmake`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

453
docs/en/get-started-legacy/index.rst Normal file
View file

@ -0,0 +1,453 @@
*****************************
Get Started (Legacy GNU Make)
*****************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
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 <../hw-reference/get-started-devkitc>
ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit>
ESP32-PICO-KIT <../hw-reference/get-started-pico-kit>
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
.. _get-started-step-by-step-legacy:
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-legacy` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`MacOS <macos-setup>`
* :ref:`get-started-get-esp-idf-legacy`
* :ref:`get-started-setup-path-legacy`
* :ref:`get-started-get-packages-legacy`
Creating Your First Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project-legacy`
* :ref:`get-started-connect-legacy`
* :ref:`get-started-configure-legacy`
* :ref:`get-started-build-and-flash-legacy`
* :ref:`get-started-monitor-legacy`
.. _get-started-setup-toolchain-legacy:
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 <windows-legacy>`_ | `Linux <linux-legacy>`_ | `Mac OS <macos-legacy>`_ |
+-----------------------------+-------------------------+----------------------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started-legacy/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started-legacy/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started-legacy/macos-setup.html
.. _Windows-legacy: ../get-started-legacy/windows-setup.html
.. _Linux-legacy: ../get-started-legacy/linux-setup.html
.. _Mac OS-legacy: ../get-started-legacy/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-legacy`.
.. _get-started-get-esp-idf-legacy:
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-legacy:
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-legacy>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-legacy>` in Section :doc:`add-idf_path-to-profile`.
.. _get-started-get-packages-legacy:
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-legacy:
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-legacy:
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-legacy:
Step 7. Configure
=================
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-legacy` 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-legacy:
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.
If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up.
.. 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 you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-monitor-legacy:
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, or 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-legacy>`.
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-legacy>` 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-legacy`.
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

77
docs/en/get-started-legacy/linux-setup-scratch.rst Normal file
View file

@ -0,0 +1,77 @@
****************************************************
Setup Linux Toolchain from Scratch (Legacy GNU Make)
****************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
.. note::
Standard process for installing the toolchain is described :doc:`here <linux-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup-legacy>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- Ubuntu and Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
.. note::
Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF.
In this case please install a supported version via ``pip`` as it is described in section
:ref:`get-started-get-packages-legacy`.
Compile the Toolchain from Source
=================================
- Install dependencies:
- CentOS 7::
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
- Ubuntu pre-16.04::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
- Ubuntu 16.04 or newer::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Debian 9::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Arch::
TODO
Create the working directory and go into it::
mkdir -p ~/esp
cd ~/esp
Download ``crosstool-NG`` and build it:
.. include:: /_build/inc/scratch-build-code.inc
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path-legacy>` to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.

120
docs/en/get-started-legacy/linux-setup.rst Normal file
View file

@ -0,0 +1,120 @@
*******************************************************
Standard Setup of Toolchain for Linux (Legacy GNU Make)
*******************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- CentOS 7::
sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography
- Ubuntu and Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
.. note::
Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages-legacy`.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
ESP32 toolchain for Linux is available for download from Espressif website:
- for 64-bit Linux:
|download_link_linux64|
- for 32-bit Linux:
|download_link_linux32|
1. Download this file, then extract it in ``~/esp`` directory:
- for 64-bit Linux:
.. include:: /_build/inc/unpack-code-linux64.inc
- for 32-bit Linux:
.. include:: /_build/inc/unpack-code-linux32.inc
.. _setup-linux-toolchain-add-it-to-path-legacy:
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``.
3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
printenv PATH
You are looking for similar result containing toolchain's path at the beginning of displayed string::
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
Instead of ``/home/user-name`` there should be a home path specific to your installation.
Permission issues /dev/ttyUSB0
------------------------------
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group-legacy>`.
Arch Linux Users
----------------
To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
Related Documents
=================
.. toctree::
:maxdepth: 1
linux-setup-scratch
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

74
docs/en/get-started-legacy/macos-setup-scratch.rst Normal file
View file

@ -0,0 +1,74 @@
*********************************************************
Setup Toolchain for Mac OS from Scratch (Legacy GNU Make)
*********************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
.. note::
Standard process for installing the toolchain is described :doc:`here <macos-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup-legacy>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Install Prerequisites
=====================
- install pip::
sudo easy_install pip
.. note::
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages-legacy>`.
Compile the Toolchain from Source
=================================
- Install dependencies:
- Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
- with MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
- with homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
Create a case-sensitive filesystem image::
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
Mount it::
hdiutil mount ~/esp/crosstool.dmg
Create a symlink to your work directory::
mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume
Go into the newly created directory::
cd ~/esp/ctng-volume
Download ``crosstool-NG`` and build it:
.. include:: /_build/inc/scratch-build-code.inc
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path-legacy>` to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.

59
docs/en/get-started-legacy/macos-setup.rst Normal file
View file

@ -0,0 +1,59 @@
********************************************************
Standard Setup of Toolchain for Mac OS (Legacy GNU Make)
********************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Install Prerequisites
=====================
- install pip::
sudo easy_install pip
.. note::
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages-legacy>`.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
ESP32 toolchain for macOS is available for download from Espressif website:
|download_link_osx|
Download this file, then extract it in ``~/esp`` directory:
.. include:: /_build/inc/unpack-code-osx.inc
.. _setup-macos-toolchain-add-it-to-path-legacy:
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
Related Documents
=================
.. toctree::
:maxdepth: 1
macos-setup-scratch

6
docs/en/get-started/make-project.rst → docs/en/get-started-legacy/make-project.rst
View file

@ -1,7 +1,9 @@
Build and Flash with Make
=========================
Build and Flash with Make (Legacy GNU Make)
===========================================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Finding a project
-----------------

12
docs/en/get-started-cmake/toolchain-setup-scratch.rst → docs/en/get-started-legacy/toolchain-setup-scratch.rst
View file

@ -1,12 +1,12 @@
.. _get-started-customized-setup-cmake:
.. _get-started-customized-setup-legacy:
*************************************
Customized Setup of Toolchain (CMake)
*************************************
***********************************************
Customized Setup of Toolchain (Legacy GNU Make)
***********************************************
:link_to_translation:`zh_CN:[中文]`
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain-legacy`) you may build the toolchain yourself.
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-set-up-tools-cmake`) you may build the toolchain yourself.
.. include:: ../gnu-make-legacy.rst
If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:

119
docs/en/get-started-legacy/windows-setup-scratch.rst Normal file
View file

@ -0,0 +1,119 @@
******************************************************
Setup Windows Toolchain from Scratch (Legacy GNU Make)
******************************************************
.. include:: ../gnu-make-legacy.rst
Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps.
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
.. _configure-windows-toolchain-from-scratch-legacy:
Configure Toolchain & Environment from Scratch
==============================================
This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.
* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
*(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*
* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.
* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.
* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
Troubleshooting
~~~~~~~~~~~~~~~
* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following::
*** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL.
If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step.
* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_.
MSYS2 Mirrors in China
~~~~~~~~~~~~~~~~~~~~~~
There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.
To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``).
Add these lines at the top of ``mirrorlist.mingw32``::
Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/
Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686
Add these lines at the top of ``mirrorlist.msys``::
Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch
HTTP Proxy
~~~~~~~~~~
You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::
export http_proxy='http://http.proxy.server:PORT'
Or with credentials::
export http_proxy='http://user:password@http.proxy.server:PORT'
Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.
Alternative Setup: Just download a toolchain
============================================
.. include:: /_build/inc/download-links.inc
If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
|download_link_win32|
.. note::
If you followed instructions :ref:`configure-windows-toolchain-from-scratch-legacy`, you already have the toolchain and you won't need this download.
.. important::
Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
.. _updating-existing-windows-environment-legacy:
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment.
Rather than setting up a new environment, you can update an existing Windows environment & toolchain:
- Update IDF to the new version you want to use.
- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version.
The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_.
If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default.
.. _MSYS2: https://msys2.github.io/
.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/
.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new

72
docs/en/get-started-legacy/windows-setup.rst Normal file
View file

@ -0,0 +1,72 @@
*********************************************************
Standard Setup of Toolchain for Windows (Legacy GNU Make)
*********************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Introduction
============
Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse <eclipse-setup>` or some other front-end), but it runs behind the scenes.
Toolchain Setup
===============
The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
Check it Out
============
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command::
mkdir -p ~/esp
By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step.
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
MSYS2 MINGW32 shell window
Use this window in the following steps setting up development environment for ESP32.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
- Download the new precompiled environment using the steps above.
- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
You can have independent different MSYS2 environments on your system, as long as they are in different directories.
There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment-legacy>`, although this is more complex.
Related Documents
=================
.. toctree::
:maxdepth: 1
windows-setup-scratch
.. _MSYS2: https://msys2.github.io/

66
docs/en/get-started/add-idf_path-to-profile.rst
View file

@ -1,65 +1,3 @@
Add IDF_PATH to User Profile
============================
:link_to_translation:`zh_CN:[中文]`
:orphan:
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
.. _add-idf_path-to-profile-windows:
Windows
-------
The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf``
#. Add the ``export`` command to the script file, e.g.::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
Remember to replace back-slashes with forward-slashes in the original Windows path.
#. Save the script file.
#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing::
printenv IDF_PATH
The path previusly entered in the script file should be printed out.
If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
.. _add-idf_path-to-profile-linux-macos:
Linux and MacOS
---------------
Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
export IDF_PATH=~/esp/esp-idf
Log off and log in back to make this change effective.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
Run the following command to check if ``IDF_PATH`` is set::
printenv IDF_PATH
The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
export IDF_PATH=~/esp/esp-idf
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
.. Remove this file when the Chinese translation of getting started guide is updated

105
docs/en/get-started/eclipse-setup.rst
View file

@ -3,107 +3,10 @@ Build and Flash with Eclipse IDE
********************************
:link_to_translation:`zh_CN:[中文]`
.. _eclipse-install-steps:
ESP-IDF V4.0 will be released with a new CMake-based build system as the default build system.
Installing Eclipse IDE
======================
Eclipse CDT IDE support for CMake-based build system will be available before the ESP-IDF V4.0 release but
is not available yet. We apologise for the inconvenience.
The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
* Download the Eclipse Installer for your platform from eclipse.org_.
* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.)
Setting up Eclipse
==================
Once your new Eclipse installation launches, follow these steps:
Import New Project
------------------
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
* Once Eclipse is running, choose File -> Import...
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
Project Properties
------------------
* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer.
* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match).
* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.)
Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
* Click the "Providers" tab
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
Navigate to "C/C++ General" -> "Indexer" property page:
* Check "Enable project specific settings" to enable the rest of the settings on this page.
* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories.
Navigate to "C/C++ Build" -> "Behavior" property page:
* Check "Enable parallel build" to enable multiple build jobs in parallel.
.. _eclipse-build-project:
Building in Eclipse
-------------------
Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
* Click OK to close the Properties dialog in Eclipse.
* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
* Back in Eclipse, choose Project -> Build to build your project.
**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.
Flash from Eclipse
------------------
You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI:
* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
* Select Build Targets -> Create... from the context menu.
* Type "flash" as the target name. Leave the other options as their defaults.
* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.
Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.)
Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary.
.. _eclipse.org: https://www.eclipse.org/
If you require Eclipse IDE support for this pre-release version of ESP-IDF, you can follow the :doc:`legacy GNU Make build system Getting Started guide </get-started-legacy/index>` which has steps for :doc:`Building and Flashing with Eclipse IDE </get-started-legacy/eclipse-setup>`.

16
docs/en/get-started/establish-serial-connection.rst
View file

@ -1,5 +1,6 @@
Establish Serial Connection with ESP32
======================================
==============================================
:link_to_translation:`zh_CN:[中文]`
This section provides guidance how to establish serial connection between ESP32 and PC.
@ -10,7 +11,7 @@ Connect ESP32 to PC
Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them.
Below are the links to drivers for ESP32 and other boards produced by Espressif:
Below are the links to drivers for ESP32 boards produced by Espressif:
.. csv-table::
@ -72,6 +73,10 @@ MacOS ::
ls /dev/cu.*
.. note::
MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
.. _linux-dialout-group:
@ -136,7 +141,7 @@ Then open serial port in terminal and check, if you see any log printed out by E
...
If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
.. note::
@ -144,9 +149,8 @@ If you see some legible log, it means serial connection is working and you are r
.. note::
Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal.
If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal.
If you got here from :ref:`get-started-connect` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

307
docs/en/get-started/index.rst
View file

@ -1,12 +1,12 @@
***********
***********
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.
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 how to build and flash firmware onto an ESP32 board.
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
@ -36,7 +36,8 @@ Hardware:
Software:
* **Toolchain** to build the **Application** for ESP32
* **Toolchain** to compile code for ESP32
* **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/>`_
@ -61,7 +62,7 @@ If you have one of ESP32 development boards listed below, you can click on the l
ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit>
ESP32-PICO-KIT <../hw-reference/get-started-pico-kit>
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
.. _get-started-step-by-step:
@ -73,10 +74,10 @@ 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-prerequisites` 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`
* :ref:`get-started-set-up-tools`
* :ref:`get-started-set-up-env`
Creating Your First Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -84,25 +85,24 @@ 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`
* :ref:`get-started-build`
* :ref:`get-started-flash`
* :ref:`get-started-build-monitor`
.. _get-started-setup-toolchain:
.. _get-started-get-prerequisites:
Step 1. Set up the Toolchain
============================
Step 1. Install prerequisites
=============================
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.
Some tools need to be installed on the computer before proceeding to the next steps. Follow the links below for the instructions for your OS:
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
Linux <linux-setup>
macOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
@ -123,21 +123,21 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
.. _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 build applications for the ESP32, you need the software libraries 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``.
To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``, following instructions below specific to your operating system.
.. 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.
Linux and macOS
~~~~~~~~~~~~~~~
Open Terminal, and run the following commands:
@ -147,43 +147,79 @@ 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
Windows
~~~~~~~
.. note::
In addition to installing the tools, :ref:`get-started-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF.
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
cd esp-idf
git submodule update --init
If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions <get-esp-idf-windows-command-line>`.
.. _get-started-set-up-tools:
.. _get-started-setup-path:
Step 3. Set up the tools
========================
Step 3. Set Environment Variables
=================================
Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc.
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.
Windows
~~~~~~~
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`.
:ref:`get-started-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools.
If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps:
.. _get-started-get-packages:
.. code-block:: batch
Step 4. Install the Required Python Packages
============================================
cd %userprofile%\esp\esp-idf
install.bat
The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running::
Linux and macOS
~~~~~~~~~~~~~~~
python -m pip install --user -r $IDF_PATH/requirements.txt
.. code-block:: bash
.. note::
cd ~/esp/esp-idf
./install.sh
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.::
Customizing the tools installation path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path.
If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed.
.. _get-started-set-up-env:
Step 4. Set up the environment variables
========================================
The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script which does that.
Windows
~~~~~~~
:ref:`get-started-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step.
Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run:
.. code-block:: batch
%userprofile%\esp\esp-idf\export.bat
Linux and macOS
~~~~~~~~~~~~~~~
In the terminal where you are going to use ESP-IDF, run:
.. code-block:: bash
. $HOME/esp/esp-idf/export.sh
Note the space between the leading dot and the path!
You can also automate this step, making ESP-IDF tools available in every terminal, by adding this line to your ``.profile`` or ``.bash_profile`` script.
.. _get-started-start-project:
@ -192,9 +228,9 @@ 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:
Copy :example:`get-started/hello_world` to ``~/esp`` directory:
Linux and MacOS
Linux and macOS
~~~~~~~~~~~~~~~
.. code-block:: bash
@ -216,7 +252,7 @@ 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.
The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects.
.. _get-started-connect:
@ -245,13 +281,15 @@ 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
Linux and macOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
make menuconfig
idf.py menuconfig
If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead.
Windows
~~~~~~~
@ -259,7 +297,7 @@ Windows
.. code-block:: batch
cd %userprofile%\esp\hello_world
make menuconfig
idf.py menuconfig
If the previous steps have been done correctly, the following menu appears:
@ -270,8 +308,6 @@ If the previous steps have been done correctly, the following menu appears:
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
@ -282,72 +318,111 @@ To navigate and use ``menuconfig``, press the following keys:
* ``?`` 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:
.. _get-started-build:
Step 8. Build and Flash
=======================
Step 8. Build the Project
=========================
Build and flash the project by running::
Build the project by running::
make flash
idf.py build
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.
This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries.
If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up.
.. code-block:: none
.. highlight:: none
$ idf.py build
Running cmake in directory /path/to/hello_world/build
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
Warn about uninitialized values.
-- Found Git: /usr/bin/git (found version "2.17.0")
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...
... (more lines of build system output)
[527/527] Generating hello-world.bin
esptool.py v2.3.1
Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'
::
If there are no errors, the build will finish by generating the firmware binary .bin file.
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
.. _get-started-flash:
Step 9. Flash onto the Device
=============================
Flash the binaries that you just built onto your ESP32 board by running::
idf.py -p PORT [-b BAUD] flash
Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect`.
You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``.
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
Running esptool.py in directory [...]/esp/hello_world
Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
esptool.py v2.3.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changing baud rate to 460800
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)...
Compressed 22992 bytes to 13019...
Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 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)...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
Hash of data verified.
Compressed 136672 bytes to 67544...
Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
Hard resetting via RTS pin...
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>`.
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:
Step 10. Monitor
================
.. _get-started-monitor:
Step 9. Monitor
===============
To check if "hello_world" is indeed running, type ``make monitor``.
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::
$ make monitor
MONITOR
$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
--- 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
@ -370,7 +445,7 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print
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 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.
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
@ -382,71 +457,45 @@ 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.
4. After that, :ref:`build and flash <get-started-flash>` the application again.
.. note::
You can combine building, flashing and monitoring into one step by running::
make flash monitor
idf.py -p PORT flash monitor
See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor.
See also:
- :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 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>`.
After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`.
Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env`.
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
../get-started-legacy/index
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases

34
docs/en/get-started/linux-setup-scratch.rst
View file

@ -1,30 +1,30 @@
**********************************
******************************************
Setup Linux Toolchain from Scratch
**********************************
******************************************
:link_to_translation:`zh_CN:[中文]`
.. note::
Standard process for installing the toolchain is described :doc:`here <linux-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
- CentOS 7::
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF.
In this case please install a supported version via ``pip`` as it is described in section
:ref:`get-started-get-packages`.
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
Compile the Toolchain from Source
=================================
@ -33,19 +33,19 @@ Compile the Toolchain from Source
- CentOS 7::
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
- Ubuntu pre-16.04::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
- Ubuntu 16.04 or newer::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- Debian 9::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- Arch::
@ -66,10 +66,10 @@ Build the toolchain::
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow `instructions for standard setup <setup-linux-toolchain-add-it-to-path>`_ to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.

72
docs/en/get-started/linux-setup.rst
View file

@ -1,6 +1,7 @@
*************************************
*********************************************
Standard Setup of Toolchain for Linux
*************************************
*********************************************
:link_to_translation:`zh_CN:[中文]`
Install Prerequisites
@ -10,75 +11,22 @@ To compile with ESP-IDF you need to get the following packages:
- CentOS 7::
sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`.
Toolchain Setup
Additional Tips
===============
.. include:: /_build/inc/download-links.inc
ESP32 toolchain for Linux is available for download from Espressif website:
- for 64-bit Linux:
|download_link_linux64|
- for 32-bit Linux:
|download_link_linux32|
1. Download this file, then extract it in ``~/esp`` directory:
- for 64-bit Linux:
.. include:: /_build/inc/unpack-code-linux64.inc
- for 32-bit Linux:
.. include:: /_build/inc/unpack-code-linux32.inc
.. _setup-linux-toolchain-add-it-to-path:
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``.
3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
printenv PATH
You are looking for similar result containing toolchain's path at the beginning of displayed string::
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
Instead of ``/home/user-name`` there should be a home path specific to your installation.
Permission issues /dev/ttyUSB0
------------------------------
@ -88,7 +36,7 @@ With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0
Arch Linux Users
----------------
To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
@ -103,7 +51,7 @@ Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
Related Documents

46
docs/en/get-started/macos-setup-scratch.rst
View file

@ -1,11 +1,20 @@
***************************************
***********************************************
Setup Toolchain for Mac OS from Scratch
***************************************
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. note::
Standard process for installing the toolchain is described :doc:`here <macos-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Package Manager
===============
To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or homebrew_ package manager.
MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Install Prerequisites
=====================
@ -14,27 +23,32 @@ Install Prerequisites
sudo easy_install pip
.. note::
- install pyserial::
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
pip install --user pyserial
- install CMake & Ninja build:
- If you have HomeBrew, you can run::
brew install cmake ninja
- If you have MacPorts, you can run::
sudo port install cmake ninja
Compile the Toolchain from Source
=================================
- Install dependencies:
- Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
- with MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
- with homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
Create a case-sensitive filesystem image::
@ -63,10 +77,10 @@ Build the toolchain::
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.

65
docs/en/get-started/macos-setup.rst
View file

@ -1,52 +1,47 @@
**************************************
**********************************************
Standard Setup of Toolchain for Mac OS
**************************************
**********************************************
:link_to_translation:`zh_CN:[中文]`
Install Prerequisites
=====================
ESP-IDF will use the version of Python installed by default on macOS.
- install pip::
sudo easy_install pip
- install pyserial::
pip install --user pyserial
- install CMake & Ninja build:
- If you have HomeBrew_, you can run::
brew install cmake ninja
- If you have MacPorts_, you can run::
sudo port install cmake ninja
- Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads.
- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
.. note::
If an error like this is shown during any step::
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
ESP32 toolchain for macOS is available for download from Espressif website:
|download_link_osx|
Download this file, then extract it in ``~/esp`` directory:
.. include:: /_build/inc/unpack-code-osx.inc
.. _setup-macos-toolchain-add-it-to-path:
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
Related Documents
=================
@ -55,3 +50,9 @@ Related Documents
:maxdepth: 1
macos-setup-scratch
.. _cmake: https://cmake.org/
.. _ninja: https://ninja-build.org/
.. _ccache: https://ccache.samba.org/
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php

8
docs/en/get-started/toolchain-setup-scratch.rst
View file

@ -1,10 +1,12 @@
.. _get-started-customized-setup:
*****************************
*************************************
Customized Setup of Toolchain
*****************************
*************************************
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself.
:link_to_translation:`zh_CN:[中文]`
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-set-up-tools`) you may build the toolchain yourself.
If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:

199
docs/en/get-started/windows-setup-scratch.rst
View file

@ -1,117 +1,120 @@
************************************
********************************************
Setup Windows Toolchain from Scratch
************************************
********************************************
Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps.
:link_to_translation:`zh_CN:[中文]`
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
.. _configure-windows-toolchain-from-scratch:
.. note::
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
Configure Toolchain & Environment from Scratch
==============================================
.. _get-esp-idf-windows-command-line:
This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.
* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
*(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*
* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.
* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.
* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
Troubleshooting
~~~~~~~~~~~~~~~
* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following::
*** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL.
If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step.
* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_.
MSYS2 Mirrors in China
~~~~~~~~~~~~~~~~~~~~~~
There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.
To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``).
Add these lines at the top of ``mirrorlist.mingw32``::
Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/
Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686
Add these lines at the top of ``mirrorlist.msys``::
Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch
HTTP Proxy
~~~~~~~~~~
You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::
export http_proxy='http://http.proxy.server:PORT'
Or with credentials::
export http_proxy='http://user:password@http.proxy.server:PORT'
Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.
Alternative Setup: Just download a toolchain
============================================
.. include:: /_build/inc/download-links.inc
If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
|download_link_win32|
Get ESP-IDF
===========
.. note::
If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
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.
.. important::
If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below.
Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
Open Command Prompt and run the following commands:
.. include:: /_build/inc/git-clone-windows.inc
ESP-IDF will be downloaded into ``%userprofile%\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
Tools
=====
cmake
^^^^^
Download the latest stable release of CMake_ for Windows and run the installer.
When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
Ninja build
^^^^^^^^^^^
.. note::
Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_ (or you can choose a directory which is already on your Path).
Python 2.x
^^^^^^^^^^
Download the latest Python_ 2.7 for Windows installer, and run it.
The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
pip install --user pyserial
MConf for IDF
^^^^^^^^^^^^^
Download the configuration tool mconf-idf from the `kconfig-frontends releases page <mconf-idf>`_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF.
This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
Download the precompiled Windows toolchain:
|download_link_win32|
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
.. note::
If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
.. _add-directory-windows-path:
Adding Directory to Path
========================
To add any new directory to your Windows Path environment variable:
Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
.. _updating-existing-windows-environment:
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment.
Rather than setting up a new environment, you can update an existing Windows environment & toolchain:
- Update IDF to the new version you want to use.
- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version.
The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_.
If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _MSYS2: https://msys2.github.io/
.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/
.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/

4
docs/en/get-started-cmake/windows-setup-update.rst → docs/en/get-started/windows-setup-update.rst
View file

@ -2,7 +2,7 @@
Updating ESP-IDF tools on Windows
*********************************
.. _get-started-cmake-install_bat-windows:
.. _get-started-install_bat-windows:
Install ESP-IDF tools using ``install.bat``
===========================================
@ -14,7 +14,7 @@ From the Windows Command Prompt, change to the directory where ESP-IDF is instal
This will download and install the tools necessary to use ESP-IDF. If the specific version of the tool is already installed, no action will be taken.
The tools are downloaded and installed into a directory specified during ESP-IDF Tools Installer process. By default, this is ``C:\Users\username\.espressif``.
.. _get-started-cmake-export_bat-windows:
.. _get-started-export_bat-windows:
Add ESP-IDF tools to PATH using ``export.bat``
==============================================

70
docs/en/get-started/windows-setup.rst
View file

@ -1,70 +1,68 @@
***************************************
***********************************************
Standard Setup of Toolchain for Windows
***************************************
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. note::
Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`.
Introduction
============
Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse <eclipse-setup>` or some other front-end), but it runs behind the scenes.
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Python, Git, cross-compilers, menuconfig tool, CMake and Ninja build tools.
For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
Toolchain Setup
===============
.. note::
Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt.
The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
.. _get-started-windows-tools-installer:
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
ESP-IDF Tools Installer
=======================
Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe
Check it Out
============
The installer includes the cross-compilers, OpenOCD, cmake_ and Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for Python_ 3.7 and `Git For Windows`_ if they are not already installed on the computer.
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command::
The installer also offers to download one of the ESP-IDF release versions.
mkdir -p ~/esp
Using the Command Prompt
========================
By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step.
For the remaining Getting Started steps, we're going to use the Windows Command Prompt.
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
ESP-IDF Tools Installer creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs ``export.bat`` script to set up the environment variables (``PATH``, ``IDF_PATH`` and others). Inside this command prompt, all the installed tools are available.
MSYS2 MINGW32 shell window
Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have two options to use them:
Use this window in the following steps setting up development environment for ESP32.
1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the new shortcut to the ESP-IDF directory you wish to use.
2. Alternatively, run ``cmd.exe``, then change to the ESP-IDF directory you wish to use, and run ``export.bat``. Note that unlike the previous option, this way requires Python and Git to be present in ``PATH``. If you get errors related to Python or Git not being found, use the first option.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
- Download the new precompiled environment using the steps above.
- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
You can have independent different MSYS2 environments on your system, as long as they are in different directories.
There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment>`, although this is more complex.
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project`.
Related Documents
=================
For advanced users who want to customize the install process:
.. toctree::
:maxdepth: 1
windows-setup-scratch
windows-setup-update
.. _MSYS2: https://msys2.github.io/
.. _cmake: https://cmake.org/download/
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _Git for Windows: https://gitforwindows.org/
.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
.. _Github Desktop: https://desktop.github.com/

1
docs/en/gnu-make-legacy.rst Normal file
View file

@ -0,0 +1 @@
.. note:: Since ESP-IDF V4.0, the default build system is based on CMake. This documentation is for the legacy build system based on GNU Make. Support for this build system may be removed in future major releases.

8
docs/en/hw-reference/get-started-devkitc-v2.rst
View file

@ -9,7 +9,7 @@ This guide shows how to start using the ESP32-DevKitC V2 development board.
What You Need
-------------
* :ref:`ESP32-DevKitC V2 board <get-started-esp32-devkitc-v2-board-front-cmake>`
* ESP32-DevKitC V2 board
* USB A / micro USB B cable
* Computer running Windows, Linux, or macOS
@ -27,7 +27,7 @@ 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-cmake:
.. _get-started-esp32-devkitc-v2-board-front-make:
.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png
:align: center
@ -71,9 +71,7 @@ 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:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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

15
docs/en/hw-reference/get-started-devkitc.rst
View file

@ -1,5 +1,5 @@
ESP32-DevKitC V4 Getting Started Guide
==============================================
======================================
:link_to_translation:`zh_CN:[中文]`
@ -9,19 +9,19 @@ This guide shows how to start using the ESP32-DevKitC V4 development board. For
What You Need
-------------
* :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front-cmake>`
* 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-cmake:
.. _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.
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:
@ -46,7 +46,7 @@ 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-cmake:
.. _get-started-esp32-devkitc-board-front:
.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg
:align: center
@ -107,6 +107,7 @@ The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boa
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
@ -121,9 +122,7 @@ 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:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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

4
docs/en/hw-reference/get-started-ethernet-kit.rst
View file

@ -348,9 +348,7 @@ Initial Setup
Now to Development
^^^^^^^^^^^^^^^^^^
Proceed to :doc:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
Proceed to :doc:`../get-started/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.
Move on to the next section only if you have successfully completed all the above steps.

6
docs/en/hw-reference/get-started-pico-kit-v3.rst
View file

@ -1,5 +1,5 @@
ESP32-PICO-KIT V3 Getting Started Guide
===============================================
=======================================
:link_to_translation:`zh_CN:[中文]`
This guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../hw-reference/index`.
@ -65,9 +65,7 @@ Start Application Development
Before powering up your ESP32-PICO-KIT V3, please make sure that the board is in good condition with no obvious signs of damage.
After that, proceed to :doc:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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

34
docs/en/hw-reference/get-started-pico-kit.rst
View file

@ -10,7 +10,7 @@ This particular description covers ESP32-PICO-KIT V4 and V4.1. The difference is
What You Need
-------------
* :ref:`ESP32-PICO-KIT mini development board <get-started-pico-kit-v4-board-front-cmake>`
* :ref:`ESP32-PICO-KIT mini development board <get-started-pico-kit-v4-board-front>`
* USB 2.0 A to Micro B cable
* Computer running Windows, Linux, or macOS
@ -58,7 +58,7 @@ Functional Description
The following figure and the table below describe the key components, interfaces, and controls of the ESP32-PICO-KIT board.
.. _get-started-pico-kit-v4-board-front-cmake:
.. _get-started-pico-kit-v4-board-front:
.. figure:: ../../_static/esp32-pico-kit-v4.1-f-layout.jpeg
:align: center
@ -107,7 +107,7 @@ There are three mutually exclusive ways to provide power to the board:
Pin Descriptions
----------------
The two tables below provide the **Name** and **Function** of I/O header pins on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front-cmake`. The pin numbering and header names are the same as in the schematic given in `Related Documents`_.
The two tables below provide the **Name** and **Function** of I/O header pins on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front`. The pin numbering and header names are the same as in the schematic given in `Related Documents`_.
Header J2
@ -116,9 +116,9 @@ Header J2
====== ================= ====== ======================================================
No. Name Type Function
====== ================= ====== ======================================================
1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2CTS
2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2RTS
3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) <get-started-pico-kit-v4-pin-notes-cmake>` , U1CTS
1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes>` , U2CTS
2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes>` , U2RTS
3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) <get-started-pico-kit-v4-pin-notes>` , U1CTS
4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN
5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1
6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0
@ -127,8 +127,8 @@ No. Name Type Function
9 IO5 I/O | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK
10 IO10 I/O | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD
11 IO9 I/O | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD
12 RXD0 I/O | GPIO3, U0RXD :ref:`(See 3) <get-started-pico-kit-v4-pin-notes-cmake>` , CLK_OUT2
13 TXD0 I/O | GPIO1, U0TXD :ref:`(See 3) <get-started-pico-kit-v4-pin-notes-cmake>` , CLK_OUT3, EMAC_RXD2
12 RXD0 I/O | GPIO3, U0RXD :ref:`(See 3) <get-started-pico-kit-v4-pin-notes>` , CLK_OUT2
13 TXD0 I/O | GPIO1, U0TXD :ref:`(See 3) <get-started-pico-kit-v4-pin-notes>` , CLK_OUT3, EMAC_RXD2
14 IO35 I | ADC1_CH7, RTC_GPIO5
15 IO34 I | ADC1_CH6, RTC_GPIO4
16 IO38 I | GPIO38, ADC1_CH2, RTC_GPIO2
@ -145,20 +145,20 @@ Header J3
====== ================= ====== ======================================================
No. Name Type Function
====== ================= ====== ======================================================
1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2RXD, EMAC_CLK_OUT
2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2TXD, EMAC_CLK_OUT_180
3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(See 1) <get-started-pico-kit-v4-pin-notes-cmake>` , U1RTS
1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes>` , U2RXD, EMAC_CLK_OUT
2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(See 1) <get-started-pico-kit-v4-pin-notes>` , U2TXD, EMAC_CLK_OUT_180
3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(See 1) <get-started-pico-kit-v4-pin-notes>` , U1RTS
4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, RTC_GPIO0
5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, RTC_GPIO3
6 IO25 I/O | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
7 IO26 I/O | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
8 IO32 I/O | 32K_XP :ref:`(See 2a) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH4, TOUCH9, RTC_GPIO9
9 IO33 I/O | 32K_XN :ref:`(See 2b) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH5, TOUCH8, RTC_GPIO8
8 IO32 I/O | 32K_XP :ref:`(See 2a) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH4, TOUCH9, RTC_GPIO9
9 IO33 I/O | 32K_XN :ref:`(See 2b) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH5, TOUCH8, RTC_GPIO8
10 IO27 I/O | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17
| EMAC_RX_DV
11 IO14 I/O | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK,
| HS2_CLK, SD_CLK, EMAC_TXD2
12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(See 4) <get-started-pico-kit-v4-pin-notes-cmake>` , HSPIQ,
12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(See 4) <get-started-pico-kit-v4-pin-notes>` , HSPIQ,
| HS2_DATA2, SD_DATA2, EMAC_TXD3
13 IO13 I/O | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID,
| HS2_DATA3, SD_DATA3, EMAC_RX_ER
@ -176,7 +176,7 @@ No. Name Type Function
====== ================= ====== ======================================================
.. _get-started-pico-kit-v4-pin-notes-cmake:
.. _get-started-pico-kit-v4-pin-notes:
The following notes give more information about the items in the tables above.
@ -193,9 +193,7 @@ Start Application Development
Before powering up your ESP32-PICO-KIT, please make sure that the board is in good condition with no obvious signs of damage.
After that, proceed to :doc:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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

18
docs/en/hw-reference/get-started-wrover-kit-v2.rst
View file

@ -1,5 +1,5 @@
ESP-WROVER-KIT V2 Getting Started Guide
===============================================
=======================================
:link_to_translation:`zh_CN:[中文]`
This guide shows how to get started with the ESP-WROVER-KIT V2 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`.
@ -52,7 +52,7 @@ Functional Description
The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board.
.. _get-started-esp-wrover-kit-v2-board-front-cmake:
.. _get-started-esp-wrover-kit-v2-board-front:
.. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png
:align: center
@ -61,7 +61,7 @@ The following two figures and the table below describe the key components, inter
ESP-WROVER-KIT board layout - front
.. _get-started-esp-wrover-kit-v2-board-back-cmake:
.. _get-started-esp-wrover-kit-v2-board-back:
.. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png
:align: center
@ -116,11 +116,11 @@ I/O All the pins on the ESP32 module are broken out to pin heade
MicroSD Card MicroSD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the MicroSD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in Section `Setup Options`_.
LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v2-board-back-cmake`.
LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v2-board-back`.
================== =================================================================================================================================
.. _get-started-esp-wrover-kit-v2-setup-options-cmake:
.. _get-started-esp-wrover-kit-v2-setup-options:
Setup Options
-------------
@ -140,7 +140,7 @@ JP14 |jp14| Enable RTS/CTS flow control for serial communication
======= ================ =========================================================
.. _get-started-esp-wrover-kit-v2-start-development-cmake:
.. _get-started-esp-wrover-kit-v2-start-development:
Start Application Development
-----------------------------
@ -170,9 +170,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up.
Now to Development
^^^^^^^^^^^^^^^^^^
Proceed to :doc:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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
@ -194,4 +192,4 @@ Related Documents
.. |jp11-tx-rx| image:: ../../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../../_static/wrover-jp14.png
.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf
.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf

49
docs/en/hw-reference/get-started-wrover-kit-v3.rst
View file

@ -1,5 +1,6 @@
ESP-WROVER-KIT V3 Getting Started Guide
===============================================
=======================================
:link_to_translation:`zh_CN:[中文]`
This guide shows how to get started with the ESP-WROVER-KIT V3 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`.
@ -8,7 +9,7 @@ This guide shows how to get started with the ESP-WROVER-KIT V3 development board
What You Need
-------------
* :ref:`ESP-WROVER-KIT V3 board <get-started-esp-wrover-kit-v3-board-front-cmake>`
* :ref:`ESP-WROVER-KIT V3 board <get-started-esp-wrover-kit-v3-board-front>`
* USB 2.0 cable（A to Micro-B）
* Computer running Windows, Linux, or macOS
@ -52,7 +53,7 @@ Functional Description
The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board.
.. _get-started-esp-wrover-kit-v3-board-front-cmake:
.. _get-started-esp-wrover-kit-v3-board-front:
.. figure:: ../../_static/esp-wrover-kit-v3-layout-front.jpg
:align: center
@ -61,7 +62,7 @@ The following two figures and the table below describe the key components, inter
ESP-WROVER-KIT board layout - front
.. _get-started-esp-wrover-kit-v3-board-back-cmake:
.. _get-started-esp-wrover-kit-v3-board-back:
.. figure:: ../../_static/esp-wrover-kit-v3-layout-back.jpg
:align: center
@ -118,11 +119,11 @@ I/O All the pins on the ESP32 module are broken out to pin heade
MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and retrieval.
LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v3-board-back-cmake`.
LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v3-board-back`.
================== =================================================================================================================================
.. _get-started-esp-wrover-kit-v3-setup-options-cmake:
.. _get-started-esp-wrover-kit-v3-setup-options:
Setup Options
-------------
@ -178,17 +179,17 @@ JTAG, MicroSD IO15 5V
Legend:
* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-v3-xtal-cmake>`
* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-kit-v3-jtag-header-cmake>`
* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-v3-xtal>`
* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-kit-v3-jtag-header>`
* Boot - Boot button / SW2
* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-kit-v3-camera-header-cmake>`
* LED - :ref:`RGB LED <get-started-esp-wrover-kit-v3-rgb-led-connections-cmake>`
* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-kit-v3-microsd-card-slot-cmake>`
* LCD - :ref:`LCD / U5 <get-started-esp-wrover-kit-v3-lcd-connector-cmake>`
* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-kit-v3-camera-header>`
* LED - :ref:`RGB LED <get-started-esp-wrover-kit-v3-rgb-led-connections>`
* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-kit-v3-microsd-card-slot>`
* LCD - :ref:`LCD / U5 <get-started-esp-wrover-kit-v3-lcd-connector>`
* PSRAM - only in case ESP32-WROVER is installed
.. _get-started-esp-wrover-kit-v3-xtal-cmake:
.. _get-started-esp-wrover-kit-v3-xtal:
32.768 kHz Oscillator
^^^^^^^^^^^^^^^^^^^^^
@ -205,7 +206,7 @@ Legend:
Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24.
.. _get-started-esp-wrover-kit-v3-spi-flash-header-cmake:
.. _get-started-esp-wrover-kit-v3-spi-flash-header:
SPI Flash / JP13
^^^^^^^^^^^^^^^^
@ -223,10 +224,10 @@ SPI Flash / JP13
.. important::
The module's flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can disolder these resistors to disconnect the module's flash bus from the pin header JP13.
The module's flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can desolder these resistors to disconnect the module's flash bus from the pin header JP13.
.. _get-started-esp-wrover-kit-v3-jtag-header-cmake:
.. _get-started-esp-wrover-kit-v3-jtag-header:
JTAG / JP8
^^^^^^^^^^
@ -242,7 +243,7 @@ JTAG / JP8
==== ============== =============
.. _get-started-esp-wrover-kit-v3-camera-header-cmake:
.. _get-started-esp-wrover-kit-v3-camera-header:
Camera / JP4
^^^^^^^^^^^^
@ -273,7 +274,7 @@ Camera / JP4
* Signals D0 .. D7 denote camera data bus
.. _get-started-esp-wrover-kit-v3-rgb-led-connections-cmake:
.. _get-started-esp-wrover-kit-v3-rgb-led-connections:
RGB LED
^^^^^^^
@ -287,7 +288,7 @@ RGB LED
==== ========== =========
.. _get-started-esp-wrover-kit-v3-microsd-card-slot-cmake:
.. _get-started-esp-wrover-kit-v3-microsd-card-slot:
MicroSD Card
^^^^^^^^^^^^
@ -305,7 +306,7 @@ MicroSD Card
==== ============== ===============
.. _get-started-esp-wrover-kit-v3-lcd-connector-cmake:
.. _get-started-esp-wrover-kit-v3-lcd-connector:
LCD / U5
^^^^^^^^
@ -323,7 +324,7 @@ LCD / U5
==== ============== ===============
.. _get-started-esp-wrover-kit-v3-start-development-cmake:
.. _get-started-esp-wrover-kit-v3-start-development:
Start Application Development
-----------------------------
@ -353,9 +354,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up.
Now to Development
^^^^^^^^^^^^^^^^^^
Proceed to :doc:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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
@ -379,4 +378,4 @@ Related Documents
.. toctree::
:hidden:
get-started-wrover-kit-v2.rst
get-started-wrover-kit-v2.rst

48
docs/en/hw-reference/get-started-wrover-kit.rst
View file

@ -1,5 +1,5 @@
ESP-WROVER-KIT V4.1 Getting Started Guide
=================================================
=========================================
:link_to_translation:`zh_CN:[中文]`
This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`.
@ -8,7 +8,7 @@ This guide shows how to get started with the ESP-WROVER-KIT V4.1 development boa
What You Need
-------------
* :ref:`ESP-WROVER-KIT V4.1 board <get-started-esp-wrover-kit-v4.1-board-front-cmake>`
* :ref:`ESP-WROVER-KIT V4.1 board <get-started-esp-wrover-kit-v4.1-board-front>`
* USB 2.0 cable（A to Micro-B）
* Computer running Windows, Linux, or macOS
@ -51,9 +51,9 @@ The block diagram below shows the main components of ESP-WROVER-KIT and their in
Functional Description
----------------------
The following two figures and the table below describe the key components, interfaces and controls of the ESP-WROVER-KIT board.
The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board.
.. _get-started-esp-wrover-kit-v4.1-board-front-cmake:
.. _get-started-esp-wrover-kit-v4.1-board-front:
.. figure:: ../../_static/esp-wrover-kit-v4.1-layout-front.png
:align: center
@ -62,7 +62,7 @@ The following two figures and the table below describe the key components, inter
ESP-WROVER-KIT board layout - front
.. _get-started-esp-wrover-kit-v4.1-board-back-cmake:
.. _get-started-esp-wrover-kit-v4.1-board-back:
.. figure:: ../../_static/esp-wrover-kit-v4.1-layout-back.png
:align: center
@ -123,11 +123,11 @@ I/O Connector All the pins on the ESP32 module are broken out to pin heade
MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and retrieval.
LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v4.1-board-back-cmake`.
LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v4.1-board-back`.
================== =================================================================================================================================
.. _get-started-esp-wrover-kit-v4.1-setup-options-cmake:
.. _get-started-esp-wrover-kit-v4.1-setup-options:
Setup Options
-------------
@ -183,17 +183,17 @@ JTAG, MicroSD IO15 5V
Legend:
* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-v4.1-xtal-cmake>`
* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-kit-v4.1-jtag-header-cmake>`
* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-v4.1-xtal>`
* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-kit-v4.1-jtag-header>`
* Boot - Boot button / SW2
* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-kit-v4.1-camera-header-cmake>`
* LED - :ref:`RGB LED <get-started-esp-wrover-kit-v4.1-rgb-led-connections-cmake>`
* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-kit-v4.1-microsd-card-slot-cmake>`
* LCD - :ref:`LCD / U5 <get-started-esp-wrover-kit-v4.1-lcd-connector-cmake>`
* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-kit-v4.1-camera-header>`
* LED - :ref:`RGB LED <get-started-esp-wrover-kit-v4.1-rgb-led-connections>`
* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-kit-v4.1-microsd-card-slot>`
* LCD - :ref:`LCD / U5 <get-started-esp-wrover-kit-v4.1-lcd-connector>`
* PSRAM - ESP32-WROVER-B's PSRAM
.. _get-started-esp-wrover-kit-v4.1-xtal-cmake:
.. _get-started-esp-wrover-kit-v4.1-xtal:
32.768 kHz Oscillator
^^^^^^^^^^^^^^^^^^^^^
@ -210,7 +210,7 @@ Legend:
Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24.
.. _get-started-esp-wrover-kit-v4.1-spi-flash-header-cmake:
.. _get-started-esp-wrover-kit-v4.1-spi-flash-header:
SPI Flash / JP2
^^^^^^^^^^^^^^^
@ -231,7 +231,7 @@ SPI Flash / JP2
The module's flash bus is connected to the jumper block JP2 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can desolder these resistors to disconnect the module's flash bus from the pin header JP2.
.. _get-started-esp-wrover-kit-v4.1-jtag-header-cmake:
.. _get-started-esp-wrover-kit-v4.1-jtag-header:
JTAG / JP2
^^^^^^^^^^
@ -247,7 +247,7 @@ JTAG / JP2
==== ============== =============
.. _get-started-esp-wrover-kit-v4.1-camera-header-cmake:
.. _get-started-esp-wrover-kit-v4.1-camera-header:
Camera / JP4
^^^^^^^^^^^^
@ -278,7 +278,7 @@ Camera / JP4
* Signals D0 .. D7 denote camera data bus
.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections-cmake:
.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections:
RGB LED
^^^^^^^
@ -292,7 +292,7 @@ RGB LED
==== ========== =========
.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot-cmake:
.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot:
MicroSD Card
^^^^^^^^^^^^
@ -310,7 +310,7 @@ MicroSD Card
==== ============== ===============
.. _get-started-esp-wrover-kit-v4.1-lcd-connector-cmake:
.. _get-started-esp-wrover-kit-v4.1-lcd-connector:
LCD / U5
^^^^^^^^
@ -328,7 +328,7 @@ LCD / U5
==== ============== ===============
.. _get-started-esp-wrover-kit-start-development-cmake:
.. _get-started-esp-wrover-kit-start-development:
Start Application Development
-----------------------------
@ -358,9 +358,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up.
Now to Development
^^^^^^^^^^^^^^^^^^
Proceed to :doc:`../get-started-cmake/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.
If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make.
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
@ -384,4 +382,4 @@ Related Documents
:hidden:
get-started-wrover-kit-v3.rst
get-started-wrover-kit-v2.rst
get-started-wrover-kit-v2.rst

1
docs/en/index.rst
View file

@ -39,7 +39,6 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
:hidden:
Get Started <get-started/index>
Get Started (CMake Preview) <get-started-cmake/index>
API Reference <api-reference/index>
H/W Reference <hw-reference/index>
API Guides <api-guides/index>

37
docs/en/security/flash-encryption.rst
View file

@ -72,7 +72,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3
encrypt flash at boot time
Odd number of bits set (1, 3, 5, 7): do
not encrypt flash at boot time
Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`.
@ -116,9 +116,9 @@ As mentioned above :ref:`flash_enc_development_mode` allows user to download as
- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value.
- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”.
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
- Select “Enable flash encryption on boot”.
- Select :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
- By default the mode is set for **Development**.
@ -132,7 +132,7 @@ Build and flash the complete image including: bootloader, partition table and ap
::
make -j4 flash monitor
idf.py flash monitor
Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time.
@ -281,7 +281,7 @@ At this stage if user wants to update modified plaintext application image to fl
::
make -j4 encrypted-app-flash monitor
idf.py encrypted-app-flash monitor
.. _encrypt_partitions:
@ -292,7 +292,7 @@ If all partitions needs to be updated in encrypted format, it can be done as
::
make -j4 encrypted-flash monitor
idf.py encrypted-flash monitor
.. _pregenerated-flash-encryption-key:
@ -310,9 +310,9 @@ It is possible to pregenerate the flash encryption key on the host computer and
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”.
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
- Select “Enable flash encryption on boot”.
- Select :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
- By default the mode is set for **Development**.
@ -327,7 +327,7 @@ Build and flash the complete image including: bootloader, partition table and ap
::
make -j4 flash monitor
idf.py flash monitor
On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed.
@ -335,7 +335,7 @@ At this stage if user wants to update new plaintext application image to flash t
::
make -j4 encrypted-app-flash monitor
idf.py encrypted-app-flash monitor
For reprogramming all partitions in encrypted format follow :ref:`encrypt_partitions`.
@ -348,10 +348,10 @@ Release Mode
In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash.
- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”.
- Select “Enable flash encryption on boot”.
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
- Select :ref:`Enable flash encryption on boot <CONFIG_SECURE_FLASH_ENC_ENABLED>`.
- Select **Release Mode**, by default the mode is set for **Development**. Please note **once the Release mode is selected the ``download_dis_encrypt`` and ``download_dis_decrypt`` eFuse bits will be programmed to disable UART bootloader access to flash contents**.
@ -365,7 +365,7 @@ Build and flash the complete image including: bootloader, partition table and ap
::
make -j4 flash monitor
idf.py flash monitor
On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application should execute correctly.
@ -549,12 +549,11 @@ If you've accidentally enabled flash encryption for some reason, the next flash
You can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse (only in Development mode):
- First, run ``make menuconfig`` and uncheck "Enable flash encryption boot" under "Security Features".
- First, open :ref:`project-configuration-menu` and disable :ref:`Enable flash encryption boot <CONFIG_SECURE_FLASH_ENC_ENABLED>` under "Security Features".
- Exit menuconfig and save the new configuration.
- Run ``make menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*.
- Run ``make flash`` to build and flash a new bootloader and app, without flash encryption enabled.
- Run ``idf.py menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*.
- Run ``idf.py flash`` to build and flash a new bootloader and app, without flash encryption enabled.
- Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT::
espefuse.py burn_efuse FLASH_CRYPT_CNT
Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal.
@ -584,7 +583,7 @@ Flash Encryption and Secure Boot
It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device:
- :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key).
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``make bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
- :ref:`Reflashing via Pregenerated Flash Encryption Key <pregenerated-flash-encryption-key>` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` option to be enabled in the Secure Boot config.
.. _flash-encryption-without-secure-boot:

18
docs/en/security/secure-boot.rst
View file

@ -25,7 +25,7 @@ Secure Boot Process Overview
This is a high level overview of the secure boot process. Step by step instructions are supplied under :ref:`secure-boot-howto`. Further in-depth details are supplied under :ref:`secure-boot-technical-details`:
1. The options to enable secure boot are provided in the ``make menuconfig`` hierarchy, under "Secure Boot Configuration".
1. The options to enable secure boot are provided in the :ref:`project-configuration-menu`, under "Secure Boot Configuration".
2. Secure Boot defaults to signing images and partition table data during the build process. The "Secure boot private signing key" config item is a file path to a ECDSA public/private key pair in a PEM format file.
@ -76,7 +76,7 @@ Options to work around this are:
How To Enable Secure Boot
-------------------------
1. Run ``make menuconfig``, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.)
1. Open the :ref:`project-configuration-menu`, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.)
2. Select a name for the secure boot signing key. This option will appear after secure boot is enabled. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet.
@ -90,15 +90,15 @@ How To Enable Secure Boot
.. important::
For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-generate-key` for more details.
5. Run ``make bootloader`` to build a secure boot enabled bootloader. The output of ``make`` will include a prompt for a flashing command, using ``esptool.py write_flash``.
5. Run ``idf.py bootloader`` to build a secure boot enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``.
.. _secure-boot-resume-normal-flashing:
6. When you're ready to flash the bootloader, run the specified command (you have to enter it yourself, this step is not performed by make) and then wait for flashing to complete. **Remember this is a one time flash, you can't change the bootloader after this!**.
7. Run ``make flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4.
7. Run ``idf.py flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4.
.. note:: ``make flash`` doesn't flash the bootloader if secure boot is enabled.
.. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled.
8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration.
@ -123,13 +123,13 @@ In the esp-idf build process, this 256-bit key file is derived from the app sign
To enable a reflashable bootloader:
1. In the ``make menuconfig`` step, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable.
1. In the :ref:`project-configuration-menu`, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable.
2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool.py`` connects to the chip, or in the ``espefuse.py summary`` output.
2. Follow the steps shown above to choose a signing key file, and generate the key file.
3. Run ``make bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process).
3. Run ``idf.py bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process).
4. Resume from :ref:`Step 6 of the one-time flashing process <secure-boot-resume-normal-flashing>`, to flash the bootloader and enable secure boot. Watch the console log output closely to ensure there were no errors in the secure boot configuration.
@ -244,7 +244,7 @@ Deterministic ECDSA as specified by `RFC 6979 <https://tools.ietf.org/html/rfc69
Manual Commands
~~~~~~~~~~~~~~~
Secure boot is integrated into the esp-idf build system, so ``make`` will automatically sign an app image if secure boot is enabled. ``make bootloader`` will produce a bootloader digest if menuconfig is configured for it.
Secure boot is integrated into the esp-idf build system, so ``make`` will automatically sign an app image if secure boot is enabled. ``idf.py bootloader`` will produce a bootloader digest if menuconfig is configured for it.
However, it is possible to use the ``espsecure.py`` tool to make standalone signatures and digests.
@ -291,7 +291,7 @@ An app can be verified on update and, optionally, be verified on boot.
How To Enable Signed App Verification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Run ``make menuconfig`` -> Security features -> Enable "Require signed app images"
1. Open :ref:`project-configuration-menu` -> Security features -> Enable :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT`
2. "Bootloader verifies app signatures" can be enabled, which verifies app on boot.

52
docs/page_redirects.txt Normal file
View file

@ -0,0 +1,52 @@
# Redirects from "old URL" "new URL"
#
# Space delimited
#
# New URL should be relative to document root, only)
#
# Empty lines and lines starting with # are ignored
api-reference/ethernet/index api-reference/network/index
api-reference/ethernet/esp_eth api-reference/network/esp_eth
api-reference/mesh/index api-reference/network/index
api-reference/mesh/esp_mesh api-reference/network/esp_mesh
api-reference/wifi/index api-reference/network/index
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
get-started/idf-monitor api-guides/tools/idf-monitor
get-started-cmake/idf-monitor api-guides/tools/idf-monitor
get-started/get-started-devkitc hw-reference/get-started-devkitc
get-started/get-started-devkitc-v2 hw-reference/get-started-devkitc-v2
get-started/get-started-wrover-kit hw-reference/get-started-wrover-kit
get-started/get-started-wrover-kit-v2 hw-reference/get-started-wrover-kit-v2
get-started/get-started-wrover-kit-v3 hw-reference/get-started-wrover-kit-v3
get-started/get-started-pico-kit hw-reference/get-started-pico-kit
get-started/get-started-pico-kit-v3 hw-reference/get-started-pico-kit-v3
# The preview 'get-started-cmake' guides are now 'get-started'
get-started-cmake get-started
get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile
get-started-cmake/eclipse-setup get-started/eclipse-setup
get-started-cmake/establish-serial-connection get-started/establish-serial-connection
get-started-cmake/index get-started/index
get-started-cmake/linux-setup get-started/linux-setup
get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch
get-started-cmake/macos-setup get-started/macos-setup
get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch
get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch
get-started-cmake/windows-setup get-started/windows-setup
get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch
get-started-cmake/get-started-devkitc hw-reference/get-started-devkitc
get-started-cmake/get-started-devkitc-v2 hw-reference/get-started-devkitc-v2
get-started-cmake/get-started-wrover-kit hw-reference/get-started-wrover-kit
get-started-cmake/get-started-wrover-kit-v2 hw-reference/get-started-wrover-kit-v2
get-started-cmake/get-started-wrover-kit-v3 hw-reference/get-started-wrover-kit-v3
get-started-cmake/get-started-pico-kit hw-reference/get-started-pico-kit
get-started-cmake/get-started-pico-kit-v3 hw-reference/get-started-pico-kit-v3
api-guide/build-system-cmake api-guide/build-system
api-guide/ulp-cmake api-guide/ulp
api-guide/unit-tests-cmake api-guide/unit-tests

9
docs/sphinx-known-warnings.txt
View file

@ -33,9 +33,12 @@ esp_bt_defs.inc:line: WARNING: Invalid definition: Expected identifier in nested
# sphinx==1.8.4
# breathe==4.11.1
#
ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size)
ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size)
ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size)
ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
#
# Issue present only when building on msys2 / mingw32 START >>>

2
docs/zh_CN/api-guides/app_trace.rst
View file

@ -151,7 +151,7 @@
return res;
}
2. 下一步是编译应用程序的镜像并将其下载到目标板上，这一步可以参考文档 :doc:`构建并烧写 <../get-started/make-project>`。
2. 下一步是编译应用程序的镜像并将其下载到目标板上，这一步可以参考文档 :ref:`构建并烧写 <get-started-build>`。
3. 运行 OpenOCD（参见 :doc:`JTAG 调试 <../api-guides/jtag-debugging/index>`）。
4. 连接到 OpenOCD 的 telnet 服务器，在终端执行如下命令 ``telnet <oocd_host> 4444``。如果在运行 OpenOCD 的同一台机器上打开
telnet 会话，您可以使用 ``localhost`` 替换上面命令中的 ``<oocd_host>``。

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

File diff suppressed because it is too large Load diff

542
docs/zh_CN/api-guides/build-system-legacy.rst Normal file
View file

@ -0,0 +1,542 @@
构建系统 (传统 GNU Make)
==========================
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
本文将介绍乐鑫物联网开发框架中的 ``构建系统`` 和 ``组件`` 的相关概念。
如果您想了解如何构建一个新的 ESP-IDF 项目，请阅读本文档。
我们建议您使用 `ESP-IDF 模板工程 <https://github.com/espressif/esp-idf-template>`_ 来开始您的新项目。
使用构建系统
------------
ESP-IDF 的 :idf_file:`README.md` 文件对如何使用构建系统来构建项目作了简要的说明。
概述
----
一个 ESP-IDF 项目可以看作是许多不同组件的集合，例如对于一个展示当前湿度的网站服务器来说，它可能会包含如下一些组件：
- ESP32 基础库（libc，rom bindings 等）
- WiFi 驱动库
- TCP/IP 协议栈
- FreeRTOS 操作系统
- 网站服务器
- 湿度传感器的驱动
- 将上述组件组织在一起的主代码
ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会查找 ESP-IDF 目录、项目目录和用户自定义目录（可选）中所有的组件，然后使用基于文本的菜单系统让用户配置 ESP-IDF 项目中需要的每个组件。在配置结束后，构建系统开始编译整个项目。
概念
~~~~
- ``项目`` 特指一个目录，其中包含了构建可执行文件的所有源文件和配置，还有其他的支持型输出文件，比如分区表、数据/文件系统分区和引导程序。
- ``项目配置`` 保存在项目根目录下名为 sdkconfig 的文件中，它可以通过 ``make menuconfig`` 进行修改，且一个项目只能包含一个项目配置。
- ``应用程序`` 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（主可执行文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序的引导程序）。
- ``组件`` 是模块化的、独立的代码，它们被编译成静态库（.a 文件）后再链接成应用程序，有些组件是 ESP-IDF 官方提供的，有些则可能来自其它项目。
以下内容并不是项目的组成部分：
- ``ESP-IDF`` 并不是项目的一部分，相反，它是独立的，并通过 IDF_PATH 环境变量链接到项目中，这样做就可以使 IDF 框架与您的项目分离，其中 IDF_PATH 变量保存了 ESP-IDF 目录的路径。
- 交叉编译工具链并不是项目的组成部分，它应该被安装在系统 PATH 环境变量中，或者可以在项目配置中显式指定工具链的前缀为本地的安装路径。
示例项目
~~~~~~~~
示例项目的目录树结构可能如下所示：
.. code::
- myProject/
- Makefile
- sdkconfig
- components/ - component1/ - component.mk
- Kconfig
- src1.c
- component2/ - component.mk
- Kconfig
- src1.c
- include/ - component2.h
- main/ - src1.c
- src2.c
- component.mk
- build/
该示例项目 ``myProject`` 包含以下组成部分：
- 项目顶层 Makefile，该 Makefile 设置了 ``PROJECT_NAME`` 变量，还可以定义作用于整个项目的其它 make 变量（可选）。顶层 Makefile 会导入核心 Makefile 文件 ``$(IDF_PATH)/make/project.mk`` ，由它负责实现 ESP-IDF 构建系统的剩余部分。
- 项目配置文件 sdkconfig，执行 ``make menuconfig`` 后会创建或更新此文件，该文件中保存了项目中所有组件的配置信息（包括 ESP-IDF 本身）。``sdkconfig`` 文件可能会也可能不会被添加到项目的源代码管理系统中。
- 可选的组件目录中包含了属于项目一部分的自定义组件，不是每一个项目都需要它，但它有助于构建可重用代码或者导入第三方组件。
- ``main`` 目录是一个特殊的 ``伪组件``，它包含项目本身的源代码。``main`` 是默认名称，Makefile 变量 ``COMPONENT_DIRS`` 默认会导入此组件，但您也可以修改此变量（或者设置 ``EXTRA_COMPONENT_DIRS`` ）以查找其他位置的组件。
- ``build`` 目录在项目构建的时候创建或者更新，里面包含有构建生成的临时目标文件和库以及最终输出的二进制文件。此目录通常不会被添加到项目的源代码管理系统中，也不会随着项目源代码被发布。
组件目录中会包含组件自己的 Makefile 文件 ``component.mk`` ，里面会定义一些变量来控制该组件的构建过程，以及它与整个项目的集成。更多详细信息请参考 `组件 Makefiles <#component-makefiles>`_。
每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的组件配置信息的选项规则。某些组件还可能还会包含 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 特殊文件，他们可以用来覆盖项目的部分配置。
项目 Makefiles
~~~~~~~~~~~~~~
每个项目都有一个 Makefile ，它包含整个项目的构建设置。默认情况下，项目 Makefile 可以非常小。
最小 Makefile 示例
^^^^^^^^^^^^^^^^^^
.. code::
PROJECT_NAME := myProject
include $(IDF_PATH)/make/project.mk
必须设置的项目变量
^^^^^^^^^^^^^^^^^^
- ``PROJECT_NAME``: 项目名称，最终输出的二进制文件也使用该名称，即 myProject.bin，myProject.elf 。
可选的项目变量
^^^^^^^^^^^^^^
以下这些变量都有默认值，用户可以重写这些变量以自定义构建行为。查看 ``make/project.mk`` 文件可以获得所有的实现细节。
- ``PROJECT_PATH``： 顶层项目目录，默认是包含 Makefile 文件的目录，许多其他的项目变量都基于此变量。注意，项目路径中不能包含有空格。
- ``BUILD_DIR_BASE``： 所有对象、库、二进制文件的输出目录，默认为 ``$(PROJECT_PATH)/build``。
- ``COMPONENT_DIRS``： 组件的搜索目录，默认为 ``$(IDF_PATH)/components``，``$(PROJECT_PATH)/components``，``$(PROJECT_PATH)/main`` 和 ``EXTRA_COMPONENT_DIRS`` 。如果您不希望从这些目录中搜索组件，请重写此变量。
- ``EXTRA_COMPONENT_DIRS``： 组件额外的搜索路径，可选。
- ``COMPONENTS``： 要构建进项目中的组件列表，默认为 ``COMPONENT_DIRS`` 指定目录中所有的组件。
- ``EXCLUDE_COMPONENTS``： 在构建的过程中需要剔除的组件列表，可选。请注意这只会减少构建的时间，并不会减少最终二进制文件的大小。
- ``TEST_EXCLUDE_COMPONENTS``： 在构建单元测试的过程中需要剔除的组件列表，可选。
以上这些 Makefile 变量中的任何路径都要使用绝对路径，您可以使用 ``$(PROJECT_PATH)/xxx``，``$(IDF_PATH)/xxx``，或者使用 Make 内置函数 ``$(abspath xxx)`` 将相对路径转换为绝对路径。
以上这些变量要在 Makefile 中 ``include $(IDF_PATH)/make/project.mk`` 的前面进行设置。
.. _component-makefiles:
组件 Makefiles
~~~~~~~~~~~~~~
每个项目都包含一个或者多个组件，这些组件可以是 ESP-IDF 的一部分，也可以从其他组件目录添加。
组件是包含 ``component.mk`` 文件的任何目录。
搜索组件
~~~~~~~~
搜索 ``COMPONENT_DIRS`` 中指定的目录以查找项目会使用的组件，目录可以是组件本身（即他们包含 ``component.mk`` 文件），也可以是包含组件的上层目录。
运行 ``make list-components`` 命令可以查询这些变量的值，这有助于调试组件的搜索路径是否正确。
同名组件
^^^^^^^^
ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进行，这意味着在默认情况下，首先是 ESP-IDF 组件，然后是项目组件，最后是 ``EXTRA_COMPONENT_DIRS`` 中的组件。如果这些目录中的两个或者多个包含具有相同名字的组件，则使用搜索到的最后一个位置的组件。这就允许将组件复制到项目目录中再修改来覆盖 ESP-IDF 组件，如果使用这种方式，ESP-IDF 目录本身可以保持不变。
.. _minimal-component-makefile:
最小组件 Makefile
^^^^^^^^^^^^^^^^^
最简单的 ``component.mk`` 文件可以是一个空文件，如果文件为空，则组件的默认构建行为会被设置为：
- makefile 所在目录中的所有源文件（``*.c``，``*.cpp``，``*.cc``，``*.S``）将会被编译进组件库中。
- 子目录 ``include`` 将被添加到其他组件的全局头文件搜索路径中。
- 组件库将会被链接到项目的应用程序中。
更完整的组件 makefile 可以查看 `组件 Makefile 示例 <#example-component-makefile>`_。
请注意，空的 ``component.mk`` 文件同没有 ``component.mk`` 文件之间存在本质差异，前者会调用默认的组件构建行为，后者不会发生默认的组件构建行为。一个组件中如果只包含影响项目配置或构建过程的文件，那么它可以没有 ``component.mk`` 文件。
.. _preset-component-variables:
预设的组件变量
^^^^^^^^^^^^^^
以下特定于组件的变量可以在 ``component.mk`` 中使用，但不应该被修改。
- ``COMPONENT_PATH``： 组件的目录，即包含 ``component.mk`` 文件的绝对路径，路径中不能包含空格。
- ``COMPONENT_NAME``： 组件的名字，默认为组件目录的名称。
- ``COMPONENT_BUILD_DIR``： 组件的构建目录，即存放组件构建输出的绝对路径，它是 `$(BUILD_DIR_BASE)` 的子目录。该变量也是构建组件时的当前工作目录，所以 make 中的相对路径都以此目录为基础。
- ``COMPONENT_LIBRARY``： 组件构建后的静态库文件（相对于组件的构建目录）的名字，默认为 ``$(COMPONENT_NAME).a``。
以下变量在项目顶层中设置，并被导出到组件中构建时使用：
- ``PROJECT_NAME``： 项目名称，在项目的 Makefile 中设置。
- ``PROJECT_PATH``： 包含项目 Makefile 的目录的绝对路径。
- ``COMPONENTS``： 此次构建中包含的所有组件的名字。
- ``CONFIG_*``： 项目配置中的每个值在 make 中都对应一个以 ``CONFIG_`` 开头的变量。
- ``CC``，``LD``，``AR``，``OBJCOPY``： gcc xtensa 交叉编译工具链中每个工具的完整路径。
- ``HOSTCC``，``HOSTLD``，``HOSTAR``： 主机本地工具链中每个工具的全名。
- ``IDF_VER``： ESP-IDF 的版本号，可以通过检索 ``$(IDF_PATH)/version.txt`` 文件（假如存在的话）或者使用 git 命令 ``git describe`` 来获取。这里推荐的格式是在一行中指定主 IDF 的发布版本号，例如标记为 ``v2.0`` 的发布版本或者是标记任意一次提交记录的 ``v2.0-275-g0efaa4f``。应用程序可以通过调用 :cpp:func:`esp_get_idf_version` 函数来使用该变量。
- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。
如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的构建，但可能会使您的组件变得难以构建或调试。
.. _optional-project-wide-component-variables:
可选的项目通用组件变量
^^^^^^^^^^^^^^^^^^^^^^
可以在 ``component.mk`` 中设置以下变量来控制整个项目的构建行为：
- ``COMPONENT_ADD_INCLUDEDIRS``： 相对于组件目录的路径，将被添加到项目中所有组件的头文件搜索路径中。如果该变量未被覆盖，则默认为 ``include`` 目录。如果一个头文件路径仅仅为当前组件所用，那么应该将该路径添加到 ``COMPONENT_PRIV_INCLUDEDIRS`` 中。
- ``COMPONENT_ADD_LDFLAGS``： 添加链接参数到全局 ``LDFLAGS`` 中用以指导链接最终的可执行文件，默认为 ``-l$(COMPONENT_NAME)``。如果将预编译好的库添加到此目录，请使用它们为绝对路径，即 ``$(COMPONENT_PATH)/libwhatever.a``。
- ``COMPONENT_DEPENDS``： 需要在当前组件之前构建的组件列表，这对于处理链接时的依赖不是必需的，因为所有组件的头文件目录始终可用。如果一个组件会生成一个头文件，然后另外一个组件需要使用它，此时该变量就有必要进行设置。大多数的组件不需要设置此变量。
- ``COMPONENT_ADD_LINKER_DEPS``： 保存一些文件的路径，当这些文件发生改变时，会触发 ELF 文件重新链接。该变量通常用于链接脚本文件和二进制文件，大多数的组件不需要设置此变量。
以下变量仅适用于属于 ESP-IDF 的组件：
- ``COMPONENT_SUBMODULES``： 组件使用的 git 子模块的路径列表（相对于 ``COMPONENT_PATH``）。这些路径会在构建的过程中被检查（并在必要的时候初始化）。如果组件位于 ``IDF_PATH`` 目录之外，则忽略此变量。
可选的组件特定变量
^^^^^^^^^^^^^^^^^^
以下变量可以在 ``component.mk`` 中进行设置，用以控制该组件的构建行为：
- ``COMPONENT_PRIV_INCLUDEDIRS``： 相对于组件目录的目录路径，该目录仅会被添加到该组件源文件的头文件搜索路径中。
- ``COMPONENT_EXTRA_INCLUDES``： 编译组件的源文件时需要指定的额外的头文件搜索路径，这些路径将以 ``-l`` 为前缀传递给编译器。这和 ``COMPONENT_PRIV_INCLUDEDIRS`` 变量的功能有些类似，但是这些路径不会相对于组件目录进行扩展。
- ``COMPONENT_SRCDIRS``： 相对于组件目录的目录路径，这些路径用于搜索源文件（``*.cpp``，``*.c``，``*.S``），默认为 ``.``，即组件目录本身。重写该变量可以指定包含源文件的不同目录列表。
- ``COMPONENT_OBJS``： 要编译生成的目标文件，默认是 ``COMPONENT_SRCDIRS`` 中每个源文件的 .o 文件。重写该变量将允许您剔除 ``COMPONENT_SRCDIRS`` 中的某些源文件，否则他们将会被编译。相关示例请参阅 `指定需要编译的组件源文件 <#specify-source-files>`_。
- ``COMPONENT_EXTRA_CLEAN``： 相对于组件构建目录的路径，指向 ``component.mk`` 文件中自定义 make 规则生成的任何文件，它们也是 ``make clean`` 命令需要删除的文件。相关示例请参阅 `源代码生成 <#source-code-generation>`_。
- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``： 这些目标允许您完全覆盖组件的默认编译行为。有关详细信息，请参阅 `完全覆盖组件的 Makefile <#fully-overriding-component-makefile-legacy>`_。
- ``COMPONENT_CONFIG_ONLY``： 如果设置了此标志，则表示组件根本不会产生构建输出（即不会构建得到 ``COMPONENT_LIBRARY``），并且会忽略大多数其它组件变量。此标志用于 IDF 内部组件，其中仅包含 ``KConfig.projbuild`` 和/或 ``Makefile.projbuild`` 文件来配置项目，但是没有源文件。
- ``CFLAGS``： 传递给 C 编译器的标志。根据项目设置已经定义一组默认的 ``CFLAGS``，可以通过 ``CFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
- ``CPPFLAGS``： 传递给 C 预处理器的标志（用于 ``.c``，``.cpp`` 和 ``.S`` 文件）。根据项目设置已经定义一组默认的 ``CPPFLAGS`` ，可以通过 ``CPPFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
- ``CXXFLAGS``： 传递给 C++ 编译器的标志。根据项目设置已经定义一组默认的 ``CXXFLAGS`` ，可以通过 ``CXXFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。
如果要将编译标志应用于单个源文件，您可以将该源文件的目标规则覆盖，例如：
.. code:: makefile
apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
如果上游代码在编译的时候发出了警告，那这么做可能会很有效。
配置组件
~~~~~~~~
每个组件都可以包含一个 Kconfig 文件，和 ``component.mk`` 放在同一个目录下。Kconfig 中包含此组件在 ``make menuconfig`` 时要展示的配置规则的设置。
运行 menuconfig 时，可以在 ``Component Settings`` 菜单栏下找到这些设置。
创建一个组件的 Kconfig 文件，最简单的方法就是使用 ESP-IDF 中现有的 Kconfig 文件作为模板，在这基础上进行修改。
有关示例请参阅 `添加条件配置 <#add-conditional-configuration>`_。
预处理器定义
~~~~~~~~~~~~
ESP-IDF 构建系统会在命令行中添加以下 C 预处理定义：
- ``ESP_PLATFORM`` — 可以用来检测在 ESP-IDF 内发生的构建行为。
- ``IDF_VER`` — ESP-IDF 的版本，请参阅 `预设的组件变量 <#preset-component-variables>`_。
构建的内部过程
~~~~~~~~~~~~~~
顶层：项目 Makefile
^^^^^^^^^^^^^^^^^^^
- ``make`` 始终从项目目录处运行，并且项目的 makefile 名字通常为 Makefile 。
- 项目的 makefile 文件会设置 ``PROJECT_NAME`` ，并且可以自定义其他可选的项目变量。
- 项目 makefile 文件会导入 ``$(IDF_PATH)/make/project.mk`` ，该文件中会导入项目级的 Make 逻辑。
- ``project.mk`` 填写默认的项目级 make 变量，并导入项目配置中的 make 变量。如果生成的包含项目配置的 makefile 文件已经过期，那么它将会被重新生成（通过 ``project_config.mk`` 中的目标规则），然后 make 进程从顶层重新开始。
- ``project.mk`` 根据默认组件目录或者可选项目变量中设置的自定义组件列表来编译组件。
- 每个组件都可以设置一些 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ ，他们会通过 ``component_project_vars.mk`` 被导入 ``project.mk`` 文件中。如果这些文件有缺失或者过期，他们会被重新生成（通过对组件 makefile 的递归调用），然后 make 进程从顶层重新开始。
- 组件中的 Makefile.projbuild 文件被包含在了 make 的进程中，以添加额外的目标或者配置。
- 默认情况下，项目 makefile 还为每个组件生成顶层的编译和清理目标，并设置 app 和 clean 目标来调用所有这些子目标。
- 为了编译每个组件，对组件 makefile 执行递归构建。
为了更好地理解项目的构建过程，请通读 ``project.mk`` 文件。
第二层：组件 Makefile 文件
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 每次调用组件 makefile 文件都是通过 ``$(IDF_PATH)/make/component_wrapper.mk`` 这个包装器进行的。
- 此组件包装器包含了所有组件的 ``Makefile.componentbuild`` 文件，使这些文件中的任何配置，变量都可用于每个组件。
- 调用 ``component_wrapper.mk`` 时将当前目录设置为组件构建目录，并将 ``COMPONENT_MAKEFILE`` 变量设置为 ``component.mk`` 的绝对路径。
- ``component_wrapper.mk`` 为所有组件变量设置默认值，然后导入 ``component.mk`` 文件来覆盖或修改这些变量。
- 如果未定义 ``COMPONENT_OWNBUILDTARGET`` 和 ``COMPONENT_OWNCLEANTARGET`` 文件，则会为组件的源文件和必备组件 ``COMPONENT_LIBRARY`` 静态库文件创建默认构建和清理目标。
- ``component_project_vars.mk`` 文件在 ``component_wrapper.mk`` 中有自己的目标，如果由于组件的 makefile 或者项目配置的更改而需要重建此文件，则从 ``project.mk`` 文件中进行评估。
为了更好地理解组件制作过程，请阅读 ``component_wrapper.mk`` 文件和 ESP-IDF 中的 ``component.mk`` 文件。
以非交互的方式运行 Make
~~~~~~~~~~~~~~~~~~~~~~~
如果在运行 ``make`` 的时候不希望出现交互式提示（例如：在IDE或自动构建系统中），可以将 ``BATCH_BUILD=1`` 添加到make的参数中（或者将其设置为环境变量）。
设置 ``BATCH_BUILD`` 意味着：
- 详细输出（与 ``V=1`` 相同，见下文），如果不需要详细输出，就设置 ``V=0`` 。
- 如果项目配置缺少新配置项（来自新组件或者 ESP-IDF 更新），则项目使用默认值，而不是提示用户输入每个项目。
- 如果构建系统需要调用 ``menuconfig`` ，则会打印错误并且构建失败。
.. _make-size:
构建目标的进阶用法
~~~~~~~~~~~~~~~~~~
- ``make app``，``make bootloader``，``make partition table`` 可以根据需要为项目单独构建生成应用程序文件、启动引导文件和分区表文件。
- ``make erase_flash`` 和 ``make erase_ota`` 会调用 esptool.py 脚本分别擦除整块闪存芯片或者其中 OTA 分区的内容。
- ``make size`` 会打印应用程序的大小信息。``make size-components`` 和 ``make size-files`` 两者功能相似，分别打印每个组件或者每个源文件大小的详细信息。
调试 Make 的过程
~~~~~~~~~~~~~~~~
调试 ESP-IDF 构建系统的一些技巧：
- 将 ``V=1`` 添加到 make 的参数中（或将其设置为环境变量）将使 make 回显所有已经执行的命令，以及为子 make 输入的每个目录。
- 运行 ``make -w`` 将导致 make 在为子 make 输入时回显每个目录——与 ``V=1`` 相同但不回显所有命令。
- 运行 ``make --trace`` （可能除了上述参数之一）将打印出构建时的每个目标，以及导致它构建的依赖项）。
- 运行 ``make -p`` 会打印每个 makefile 中每个生成的目标的（非常详细的）摘要。
更多调试技巧和通用的构建信息，请参阅 `GNU 构建手册 <http://www.gnu.org/software/make/manual/make.html>`_。
.. _warn-undefined-variables-legacy:
警告未定义的变量
^^^^^^^^^^^^^^^^
默认情况下，如果引用了未定义的变量（如 ``$(DOES_NOT_EXIST)`` ，构建过程将会打印警告，这对于查找变量名称中的错误非常有用。
如果不想要此行为，可以在 menuconfig 顶层菜单下的 `SDK tool configuration` 中禁用它。
请注意，如果在 Makefile 中使用 ``ifdef`` 或者 ``ifndef`` ，则此选项不会出发警告。
覆盖项目的部分内容
~~~~~~~~~~~~~~~~~~
Makefile.projbuild
^^^^^^^^^^^^^^^^^^
如果一个组件含有必须要在项目构建过程的顶层进行计算的变量，则可以在组件目录下创建名为 ``Makefile.projbuild`` 的文件，项目在执行 ``project.mk`` 的时候会导入此 makefile 。
例如，如果您的组件需要为整个项目添加 CFLAGS（不仅仅是为自身的源文件），那么可以在 ``Makefile.projbuild`` 中设置 ``CFLAGS +=`` 。
``Makefile.projbuild`` 文件在 ESP-IDF 中大量使用，用于定义项目范围的构建功能，例如 ``esptool.py`` 命令行参数和 ``bootloader`` 这个特殊的程序。
请注意， ``Makefile.projbuild`` 对于最常见的组件不是必需的 - 例如向项目中添加 include 目录，或者将 LDFLAGS 添加到最终链接步骤，同样可以通过 ``component.mk`` 文件来自定义这些值。有关详细信息，请参阅 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ 。
.. warning::
在此文件中设置变量或者目标时要小心，由于这些值包含在项目的顶层 makefile 中，因此他们可以影响或者破坏所有组件的功能！
KConfig.projbuild
^^^^^^^^^^^^^^^^^
这相当于 ``Makefile.projbuild`` 的组件配置 KConfig 文件，如果要在 menuconfig 的顶层添加配置选项，而不是在 ``组件配置`` 子菜单中，则可以在 ``component.mk`` 文件所在目录中的 KConfig.projbuild 文件中定义这些选项。
在此文件中添加配置时要小心，因为他们将包含在整个项目配置中，在可能的情况下，通常最好为组件创建和配置 KConfig 文件。
Makefile.componentbuild
^^^^^^^^^^^^^^^^^^^^^^^
对于一些特殊的组件，比如它们会使用工具从其余文件中生成源文件，这时就有必要将配置、宏或者变量的定义添加到每个组件的构建过程中。这是通过在组件目录中包含 ``Makefile.componentbuild`` 文件来实现的。此文件在 ``component.mk`` 文件之前被导入 ``component_wrapper.mk`` 中。同 ``Makefile.projbuild`` 文件一样，请留意这些文件，因为他们包含在每个组件的构建中，所有只有在编译完全不同的组件时才会出现 ``Makefile.componentbuild`` 错误。
仅配置的组件
^^^^^^^^^^^^
仅配置的组件是一类不包含源文件的特殊组件，只有 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 文件，可以在 ``conponent.mk`` 文件中设置标志 ``COMPONENT_CONFIG_ONLY``。如果设置了此标志，则忽略大多数其他组件变量，并且不会为组件执行构建操作。
.. _example-component-makefile-legacy:
组件 Makefile 示例
~~~~~~~~~~~~~~~~~~
因为构建环境试图设置大多数情况都能工作的合理默认值，所以 ``component.mk`` 可能非常小，甚至是空的，请参考 `最小组件 Makefile <#minimal-component-makefile>`_。但是某些功能通常需要覆盖组件的变量。
以下是 ``component.mk`` 的一些更高级的示例：
增加源文件目录
^^^^^^^^^^^^^^
默认情况下，将忽略子目录。如果您的项目在子目录中而不是在组件的根目录中有源文件，那么您可以通过设置 ``COMPONENT_SRCDIRS`` 将其告知构建系统：
.. code::
COMPONENT_SRCDIRS := src1 src2
构建系统将会编译 src1/ 和 src2/ 子目录中的所有源文件。
.. _specify-source-files-legacy:
指定源文件
^^^^^^^^^^
标准 ``component.mk`` 逻辑将源目录中的所有 .S 和 .c 文件添加为无条件编译的源。通过将 ``COMPONENT_OBJS`` 变量手动设置为需要生成的对象的名称，可以绕过该逻辑并对要编译的对象进行硬编码。
.. code::
COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
COMPONENT_SRCDIRS := . thing anotherthing
请注意，还需要另外设置 ``COMPONENT_SRCDIRS`` 。
.. _add-conditional-configuration-legacy:
添加条件配置
^^^^^^^^^^^^
配置系统可用于有条件地编译某些文件，具体取决于 ``make menuconfig`` 中选择的选项。为此，ESP-IDF 具有 ``compile_only_if`` 和 ``compile_only_if_not`` 的宏：
``Kconfig``:
.. code::
config FOO_ENABLE_BAR
bool "Enable the BAR feature."
help
This enables the BAR feature of the FOO component.
``component.mk``:
.. code::
$(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
从示例中可以看出， ``compile_only_if`` 宏将条件和目标文件列表作为参数。如果条件为真（在这种情况下：如果在 menuconfig 中启用了 BAR 功能），将始终编译目标文件（在本例中为 bar.o）。相反的情况也是如此，如果条件不成立，bar.o 将永远不会被编译。 ``compile_only_if_not`` 执行相反的操作，如果条件为 false 则编译，如果条件为 true 则不编译。
这也可以用于选择或者删除实现，如下所示：
``Kconfig``:
.. code::
config ENABLE_LCD_OUTPUT
bool "Enable LCD output."
help
Select this if your board has a LCD.
config ENABLE_LCD_CONSOLE
bool "Output console text to LCD"
depends on ENABLE_LCD_OUTPUT
help
Select this to output debugging output to the lcd
config ENABLE_LCD_PLOT
bool "Output temperature plots to LCD"
depends on ENABLE_LCD_OUTPUT
help
Select this to output temperature plots
``component.mk``:
.. code::
# If LCD is enabled, compile interface to it, otherwise compile dummy interface
$(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
$(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
#We need font if either console or plot is enabled
$(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
请注意使用 Make 或者函数来包含字体文件。其他的替换函数，比如 ``and`` 和 ``if`` 也适用于此处。也可以使用不在 menuconfig 中定义的变量，ESP-IDF 使用默认的 Make 策略，将一个空的或者只包含空格的变量视为 false ，而其中任何非空格的比那辆都为 true 。
（注意：本文档的历史版本建议将目标文件添加到 ``COMPONENT_OBJS`` 中，虽然这仍然可行，但是只有当组件中的所有目标文件都明确命名时才会起作用，并且在 ``make clean`` 后并不会清除 make 中取消选择的目标文件）。
.. _source-code-generation-legacy:
源代码生成
^^^^^^^^^^
某些组件会出现源文件未随组件本身提供，而必须从另外一个文件生成的情况。假设我们的组件有一个头文件，该文件由 BMP 文件转换后的二进制数据组成，假设使用 bmp2h 的工具进行转换，然后将头文件包含在名为 graphics_lib.c 的文件中：
.. code::
COMPONENT_EXTRA_CLEAN := logo.h
graphics_lib.o: logo.h
logo.h: $(COMPONENT_PATH)/logo.bmp
bmp2h -i $^ -o $@
这个示例会在当前目录（构建目录）中生成 graphics_lib.o 和 logo.h 文件，而 logo.bmp 随组件一起提供并位于组件路径下。因为 logo.h 是一个生成的文件，所以当调用 ``make clean`` 时需要清理它，这就是为什么要将它添加到 ``COMPONENT_EXTRA_CLEAN`` 变量中。
润色与改进
^^^^^^^^^^
将 logo.h 添加作为 ``graphics_lib.o`` 的依赖项会导致在编译 ``graphics_lib.c`` 之前先生成它。
如果另一个组件中的源文件需要使用 logo.h，则必须将此组件的名称添加到另一个组件的 ``COMPONENT_DEPENDS`` 列表中，以确保组件按顺序编译。
嵌入二进制数据
^^^^^^^^^^^^^^
有时您的组件希望使用一个二进制文件或者文本文件，但是您又不希望将它重新格式化为 C 源文件。
这时，您可以在 ``component.mk`` 文件中设置变量 ``COMPONENT_EMBED_FILES``，以这种方式指定要嵌入的文件的名称：
.. code::
COMPONENT_EMBED_FILES := server_root_cert.der
或者，如果文件是字符串，则可以使用变量 ``COMPONENT_EMBED_TXTFILES``，这将把文本文件的内容当成以 null 结尾的字符串嵌入：
.. code::
COMPONENT_EMBED_TXTFILES := server_root_cert.pem
文件的内容会被编译进 flash 中的 .rodata 段，并通过符号名称来访问，如下所示：
.. code:: c
extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end");
符号名称是根据文件的全名生成的，如 ``COMPONENT_EMBED_FILES`` 中的所示，字符 / ， . ， 等都将会被下划线替代。符号名称中的 ``_binary`` 前缀由 ``objcopy`` 添加，对于文本和二进制文件都是相同的。
有关使用此技术的示例，请参考 :example:`protocols/https_request` - 证书文件的内容会在编译时从 .pem 文件中加载。
.. _fully-overriding-component-makefile:
完全覆盖组件的 Makefile
~~~~~~~~~~~~~~~~~~~~~~~
显然，在某些情况下，所有这些配置都不足以满足某个组件，例如，当组件基本上是另一个第三方组件的包装器时，该第三方组件最初不打算在 ESP-IDF 构建系统下工作，在这种情况下，可以通过设置 ``COMPONENT_OWNBUILDTARGET`` 和可能的 ``COMPONENT_OWNCLEANTARGET``，并在 ``component.mk`` 中定义名为 ``build`` 和 ``clean`` 的目标。构建目标可以执行任何操作，只要它为项目生成了 ``$(COMPONENT_LIBRARY)`` ，并最终被链接到应用程序二进制文件中即可。
（实际上，这并不是必须的 - 如果 ``COMPONENT_ADD_LDFLAGS`` 变量被覆盖，那么组件可以指示链接器链接其他二进制文件。）
.. _custom-sdkconfig-defaults-legacy:
自定义 sdkconfig 的默认值
~~~~~~~~~~~~~~~~~~~~~~~~~
对于示例工程或者其他您不想指定完整 sdkconfig 配置的项目，但是您确实希望覆盖 ESP-IDF 默认值中的某些键值，则可以在项目中创建文件 ``sdkconfig.defaults``,运行 ``make defconfig`` 或从头创建新配置时将会使用此文件。
要想覆盖此文件的名称，请设置 ``SDKCONFIG_DEFAULTS`` 环境变量。
保存 flash 参数
~~~~~~~~~~~~~~~
在某些情况下，我们希望在没有 IDF 的情况下烧写目标板卡，对于这种情况，我们希望保存构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以简单编写一段脚本来保存二进制文件和 esptool.py，并且使用命令 ``make print_flash_cmd`` 来查看烧写 flash 时的参数。
.. code:: bash
--flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
然后使用这段 flash 参数作为 esptool write_flash 命令的参数：
.. code:: bash
python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
构建 Bootloader
---------------
引导程序默认作为 ``make all`` 的一部分被构建，或者也可以通过 ``make bootloader-clean`` 来单独构建，此外还可以通过 ``make bootloader-list-components`` 来查看构建引导程序时包含的组件。
引导程序是一个特殊的组件，因为主项目中的二级引导程序拥有单独的 .EFL 和 .BIN 文件。但是它与主项目共享配置和构建目录。
这是通过在 components/bootloader/subproject 下添加子项目来完成的。这个子项目有自己的 Makefile，但它希望通过 components/bootloader/Makefile.projectbuild 文件中的一些配置使自己从主项目的 Makefile 被调用。有关详细信息，请参阅这些文件。

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

File diff suppressed because it is too large Load diff

2
docs/zh_CN/api-guides/console.rst
View file

@ -16,7 +16,7 @@ ESP-IDF 提供了 ``console`` 组件，它包含了开发基于串口的交互
行编辑功能允许用户通过按键输入来编辑命令，使用退格键删除符号，使用左/右键在命令中移动光标，使用上/下键导航到之前输入的命令，使用制表键（“Tab”）来自动补全命令。
.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``make monitor`` 来调用）。
.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``idf.py monitor`` 来调用）。
前往这里可以查看 `linenoise <https://github.com/antirez/linenoise>`_ 库提供的所有函数的描述。

8
docs/zh_CN/api-guides/index.rst
View file

@ -7,7 +7,7 @@ API 指南
一般注意事项 <general-notes>
构建系统 <build-system>
构建系统 (CMake) <build-system-cmake>
构建系统 (传统 GNU Make) <build-system-legacy>
错误处理 <error-handling>
严重错误 <fatal-errors>
Event Handling <event-handling>
@ -21,10 +21,10 @@ API 指南
Bootloader <bootloader>
分区表 <partition-tables>
Secure Boot <../security/secure-boot>
ULP Coprocessor <ulp>
ULP 协处理器 (CMake) <ulp-cmake>
ULP 协处理器 <ulp>
ULP ( CMake) <ulp-legacy>
单元测试 <unit-tests>
单元测试 (CMake) <unit-tests-cmake>
单元测试 (传统 GNU Make) <unit-tests-legacy>
应用层跟踪 <app_trace>
控制台终端组件 <console>
ROM debug console <romconsole>

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

@ -8,7 +8,7 @@
配置硬件
^^^^^^^^
1. 根据 :doc:`../../hw-reference/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options-cmake` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。
1. 根据 :doc:`../../hw-reference/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。
2. 检查 ESP32 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。

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-and-flash` 章节。
您可以像往常一样构建并上传 ESP32 应用程序，具体请参阅 :ref:`get-started-build` 章节。
除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下::

2
docs/zh_CN/api-guides/jtag-debugging/setup-openocd-windows.rst
View file

@ -6,7 +6,7 @@
IDF 工具安装程序
================
如果您正在使用 CMake 构建系统，并遵循 :doc:`/get-started-cmake/windows-setup` 章节的指导使用了 ``ESP-IDF Tools Installer`` 的 V1.2 及其以上版本，那么默认情况下您已经安装好了 ``OpenOCD`` 软件。
如果您正在使用 CMake 构建系统，并遵循 :doc:`/get-started/windows-setup` 章节的指导使用了 ``ESP-IDF Tools Installer`` 的 V1.2 及其以上版本，那么默认情况下您已经安装好了 ``OpenOCD`` 软件。
``ESP-IDF Tools Installer`` 会将 ``OpenOCD`` 添加到环境变量 ``PATH`` 中，这样你就可以在任何目录运行它。

2
docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst
View file

@ -57,7 +57,7 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设
* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 默认没有使能。在所有任务堆栈的末尾设置观察点，从 1 号开始索引。这是调试任务堆栈溢出的最准确的方式。
更多有关设置编译时的选项的信息，请参阅 :ref:`make menuconfig <get-started-configure>`。
更多有关设置编译时的选项的信息，请参阅 :ref:`idf.py menuconfig <get-started-configure>`。
.. _jtag-debugging-tip-freertos-support:

18
docs/zh_CN/api-guides/partition-tables.rst
View file

@ -11,12 +11,12 @@
分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。
在使用分区表时，最简单的方法就是用 `make menuconfig` 选择一张预定义的分区表：
在使用分区表时，最简单的方法就是用 `idf.py menuconfig` 选择一张预定义的分区表：
- "Single factory app, no OTA"
- "Factory app, two OTA definitions"
在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `make partition_table` ，即可以打印当前使用分区表的信息摘要。
在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition_table` ，即可以打印当前使用分区表的信息摘要。
内置分区表
------------
@ -102,7 +102,7 @@ SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf
- phy (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。
- 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。
- 如果需要从此分区加载 phy 初始化数据，请运行 ``make menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。
- 如果需要从此分区加载 phy 初始化数据，请运行 ``idf.py menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。
- nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。
- 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。
@ -142,7 +142,7 @@ Flags 字段
烧写到 ESP32 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。
如果您在 ``make menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``make partition_table``。这时，转换将在编译过程中自动完成。
如果您在 ``idf.py menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``idf.py partition_table``。这时，转换将在编译过程中自动完成。
手动将 CSV 文件转换为二进制文件:
@ -152,7 +152,7 @@ Flags 字段
python gen_esp32part.py binary_partitions.bin input_partitions.csv
在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``make partition_table`` 时，我们正是这样打印上文展示的信息摘要的）:
在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``idf.py partition_table`` 时，我们正是这样打印上文展示的信息摘要的）:
python gen_esp32part.py binary_partitions.bin
@ -166,13 +166,13 @@ MD5 校验和
烧写分区表
----------
- ``make partition_table-flash`` ：使用 esptool.py 工具烧写分区表。
- ``make flash`` ：会烧写所有内容，包括分区表。
- ``idf.py partition_table-flash`` ：使用 esptool.py 工具烧写分区表。
- ``idf.py flash`` ：会烧写所有内容，包括分区表。
在执行 ``make partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。
在执行 ``idf.py partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。
.. note::
分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``make erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
.. _secure boot: security/secure-boot.rst

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

@ -8,8 +8,9 @@ IDF 监视器是一个串行终端程序，用于收发目标设备串口的串
在 IDF 中调用以下目标函数可以启用此监视器：
- **若使用 Make 编译系统，请调用**：``make monitor``
- **若使用 CMake 编译系统，则请调用**：``idf.py monitor``
- **若使用传统 GNU Make 编译系统，请调用**：``make monitor``
操作快捷键
@ -26,7 +27,7 @@ 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+F 编译并烧录此项目 暂停 idf_monitor，运行 ``idf.py flash`` 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。
- Ctrl+A (A) 仅编译及烧录应用程序 暂停 idf_monitor，运行 ``app-flash`` 目标，然后恢复 idf_monitor。 这与 ``flash`` 类似，但只有主应用程序被编译并被重新烧录。
- Ctrl+Y 停止/恢复日志输出在屏幕上打印 激活时，会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。
- Ctrl+L 停止/恢复向文件写入日志输出 在工程目录下创建一个文件，用于写入日志输出。可使用快捷键停止/恢复该功能（退出 IDF 监视器也会终止该功能）
@ -91,7 +92,7 @@ IDF 监视器在后台运行以下命令，解码各地址::
或者选择配置 panic 处理器以运行 GDBStub，GDBStub 工具可以与 GDB_ 项目调试器进行通信，允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用，但不需要使用特殊硬件。
如需启用 GDBStub，请运行 ``make menuconfig`` （适用于 Make 编译系统）或 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。
如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。
在这种情况下，如果 panic 处理器被触发，只要 IDF 监视器监控到 GDBStub 已经加载，panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后，通过 RTS 串口线复位开发板。如果未连接 RTS 串口线，请按复位键，手动复位开发板。
@ -103,7 +104,7 @@ IDF 监控器在后台运行如下命令::
输出筛选
~~~~~~~~~~~~~~~~
IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （适用于 Make）或者 ``idf.py monitor --print-filter=""`` （适用于 CMake），其中，``PRINT_FILTER`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。
IDF 监视器有两种启用方式：运行 ``idf.py monitor PRINT_FILTER=""`` （适用于 CMake） 或者 ``make monitor PRINT_FILTER=""`` （适用于传统 GNU Make），其中，``--print-filter`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。
若需对打印内容设置限制，可指定 ``<tag>:<log_level>`` 等选项，其中 ``<tag>`` 是标签字符串，``<log_level>`` 是 ``{N, E, W, I, D, V, *}`` 集合中的一个字母，指的是 :doc:`日志 <../../api-reference/system/log>` 级别。
@ -159,18 +160,6 @@ IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （
D (309) light_driver: [light_init, 74]:status: 1, mode: 2
简单监视器
==============
较早版本的 ESP-IDF 使用 pySerial_ 命令行工具 miniterm_ 作为串行控制台程序。
.. note:: 仅适用于 Make 编译系统，不适用于 CMake 编译系统。
此程序仍然可以通过 ``make simple_monitor`` 运行。
IDF 监视器基于 miniterm，可使用相同的快捷键。
IDF 监视器已知问题
=============================

167
docs/zh_CN/api-guides/ulp-cmake.rst
View file

@ -1,167 +0,0 @@
ULP 协处理器编程 (CMake)
===================================
:link_to_translation:`en:[English]`
.. toctree::
:maxdepth: 1
指令集参考 <ulp_instruction_set>
使用宏进行编程（遗留） <ulp_macros>
ULP（Ultra Low Power 超低功耗）协处理器是一种简单的有限状态机 (FSM)，可以在主处理器处于深度睡眠模式时，使用 ADC、温度传感器和外部 I2C 传感器执行测量操作。ULP 协处理器可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设寄存器。ULP 协处理器使用 32 位固定宽度的指令，32 位内存寻址，配备 4 个 16 位通用寄存器。
安装工具链
------------------------
ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 工具链`_ 进行编译。
1. 从提供的网址中下载最新工具链的预编译二进制文件：https://github.com/espressif/binutils-esp32ulp/releases.
2. 将工具链解压缩到一个目录中，并将工具链的 ``bin/`` 目录路径添加到 ``PATH`` 环境变量中。
编译 ULP 代码
------------------
若需要将 ULP 代码编译为某组件的一部分，则必须执行以下步骤：
1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 .S 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。
.. note:
该目录不要添加到 ``COMPONENT_SRCDIRS`` 环境变量中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``COMPONENT_SRCDIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-esp32-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别的最简单方法就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也不应该添加到 ``COMPONENT_SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。
2. 修改组件 CMakeLists.txt，添加必要的 ULP CMake 定义，示例如下::
set(ULP_APP_NAME ulp_${COMPONENT_NAME})
set(ULP_S_SOURCES ulp/ulp_assembly_source_file.S)
set(ULP_EXP_DEP_SRCS "ulp_c_source_file.c")
include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)
代码解释如下：
``set(ULP_APP_NAME ulp_${COMPONENT_NAME})``
为生成的 ULP 应用程序设置名称，不带扩展名。此名称用于 ULP 应用程序的构建输出：ELF 文件、.map 文件、二进制文件、生成的头文件和链接器导出文件。
``set(ULP_S_SOURCES "ulp/ulp_assembly_source_file_1.S ulp/ulp_assembly_source_file_2.S")``
设置要传递给 ULP 汇编器的程序集文件列表，用空格隔开，路径可以是绝对路径，也可以是组件 CMakeLists.txt 的相对路径。
``set(ULP_EXP_DEP_SRCS "ulp_c_source_file_1.c ulp_c_source_file_2.c")``
设置组件中源文件名称的列表。所有包含被生成的头文件的原文件都必须在列表里。此列表建立正确构建依赖项，并确保在构建过程会先生成才编译包含头文件的原文件。请参考下文，查看为 ULP 应用程序生成的头文件等相关概念。此列表需要用空格隔开，路径可以是组件 CMakeLists.txt 文件的相对路径，也可以是绝对路径。
``include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)``
包含 ULP 编译步骤的通用定义。使用 ULP 工具链为 ULP 目标文件、ELF 文件、二进制文件等设置编译规则。
3. 使用常规方法（例如 `idf.py app`）编译应用程序
在内部，编译系统将按照以下步骤编译 ULP 程序：
1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。
2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。
3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 components/ulp/ld 目录中。
4. **将目标文件链接到 ELF 输出文件** (ulp_app_name.elf)。此步骤生成的.map 文件 (ulp_app_name.map) 默认用于调试。
5. **将 ELF 文件中的内容转储为二进制文件** (ulp_app_name.bin)，以便嵌入到应用程序中。
6. **使用 esp32ulp-elf-nm 在 ELF 文件中生成全局符号列表** (ulp_app_name.sym)。
7. **创建 LD 导出脚本和头文件** (ulp_app_name.ld 和 ulp_app_name.h)，包含来自 ulp_app_name.sym 的符号。此步骤可借助 esp32ulp_mapgen.py 工具来完成。
8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。**
访问 ULP 程序变量
-------------------------------
在 ULP 程序中定义的全局符号也可以在主程序中使用。
例如，ULP 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数::
.global measurement_count
measurement_count: .long 0
/* later, use measurement_count */
move r3, measurement_count
ld r3, r3, 0
主程序需要在启动 ULP 程序之前初始化 ``measurement_count`` 变量，编译系统生成 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件可以实现上述操作，这些文件在 ULP 编程中定义了全局符号，包含了在 ULP 程序中定义的所有全局符号，前缀为 ``ulp_``。
头文件包含对此类符号的声明::
extern uint32_t ulp_measurement_count;
注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。对于函数和数组，先获取符号地址，然后转换为适当的类型。
生成的链接器脚本文件定义了 RTC_SLOW_MEM 中的符号位置::
PROVIDE ( ulp_measurement_count = 0x50000060 );
如果要从主程序访问 ULP 程序变量，先包含生成的头文件，并使用上述变量，操作如下::
#include "ulp_app_name.h"
// later
void init_ulp_vars() {
ulp_measurement_count = 64;
}
注意，ULP 程序在 RTC 内存中只能使用 32 位字的低 16 位，因为寄存器是 16 位的，并且不具备从字的高位加载的指令。
同样，ULP 储存指令将寄存器值写入 32 位字的低 16 位中。高 16 位写入的值取决于储存指令的地址，因此在读取 ULP 写的变量时，主应用程序需要屏蔽高 16 位，例如::
printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX);
启动 ULP 程序
------------------------
要运行 ULP 程序，主应用程序需要调用 ``ulp_load_binary`` 函数将 ULP 程序加载到 RTC 内存中，然后调用 ``ulp_run`` 函数，启动 ULP 程序。
注意，在 menuconfig 中必须启用 "Enable Ultra Low Power (ULP) Coprocessor" 选项，以便为 ULP 预留内存。"RTC slow memory reserved for coprocessor" 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，则 RTC 内存必须足以容纳最大的程序。
每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB （假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``）::
extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start");
extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end");
void start_ulp_program() {
ESP_ERROR_CHECK( ulp_load_binary(
0 /* load address, set to 0 when using default linker scripts */,
bin_start,
(bin_end - bin_start) / sizeof(uint32_t)) );
}
.. doxygenfunction:: ulp_load_binary
一旦上述程序加载到 RTC 内存后，应用程序即可启动此程序，并将入口点的地址传递给 ``ulp_run`` 函数::
ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) );
.. doxygenfunction:: ulp_run
上述生成的头文件 ``${ULP_APP_NAME}.h`` 声明了入口点符号。在 ULP 应用程序的汇编源代码中，此符号必须标记为 ``.global``::
.global entry
entry:
/* code starts here */
ULP 程序流
----------------
ULP 协处理器由定时器启动，而调用 ``ulp_run`` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 150 KHz 晶振器生成）。使用 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器 (x = 0..4) 设置 Tick 数值。第一次启动 ULP 时，使用 ``SENS_ULP_CP_SLEEP_CYC0_REG`` 设置定时器 Tick 数值，之后，ULP 程序可以使用 ``sleep`` 指令来另外选择 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器。
此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值 (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4)。
.. doxygenfunction:: ulp_set_wakeup_period
一旦定时器达到在所选的 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器中设置的数值，ULP 协处理器就会启动，并调用 ``ulp_run`` 的入口点开始运行程序。
程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。
如果想禁用定时器（有效防止 ULP 程序再次运行），请清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位，可在 ULP 代码或主程序中进行以上操作。
.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp

1
docs/zh_CN/api-guides/ulp-legacy.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/api-guides/ulp.rst

168
docs/zh_CN/api-guides/ulp.rst
View file

@ -1 +1,167 @@
.. include:: ../../en/api-guides/ulp.rst
ULP 协处理器编程
===================================
:link_to_translation:`en:[English]`
.. toctree::
:maxdepth: 1
指令集参考 <ulp_instruction_set>
使用宏进行编程（遗留） <ulp_macros>
ULP（Ultra Low Power 超低功耗）协处理器是一种简单的有限状态机 (FSM)，可以在主处理器处于深度睡眠模式时，使用 ADC、温度传感器和外部 I2C 传感器执行测量操作。ULP 协处理器可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设寄存器。ULP 协处理器使用 32 位固定宽度的指令，32 位内存寻址，配备 4 个 16 位通用寄存器。
安装工具链
------------------------
ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 工具链`_ 进行编译。
1. 从提供的网址中下载最新工具链的预编译二进制文件：https://github.com/espressif/binutils-esp32ulp/releases.
2. 将工具链解压缩到一个目录中，并将工具链的 ``bin/`` 目录路径添加到 ``PATH`` 环境变量中。
编译 ULP 代码
------------------
若需要将 ULP 代码编译为某组件的一部分，则必须执行以下步骤：
1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 .S 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。
.. note:
该目录不要添加到 ``COMPONENT_SRCDIRS`` 环境变量中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``COMPONENT_SRCDIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-esp32-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别的最简单方法就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也不应该添加到 ``COMPONENT_SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。
2. 修改组件 CMakeLists.txt，添加必要的 ULP CMake 定义，示例如下::
set(ULP_APP_NAME ulp_${COMPONENT_NAME})
set(ULP_S_SOURCES ulp/ulp_assembly_source_file.S)
set(ULP_EXP_DEP_SRCS "ulp_c_source_file.c")
include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)
代码解释如下：
``set(ULP_APP_NAME ulp_${COMPONENT_NAME})``
为生成的 ULP 应用程序设置名称，不带扩展名。此名称用于 ULP 应用程序的构建输出：ELF 文件、.map 文件、二进制文件、生成的头文件和链接器导出文件。
``set(ULP_S_SOURCES "ulp/ulp_assembly_source_file_1.S ulp/ulp_assembly_source_file_2.S")``
设置要传递给 ULP 汇编器的程序集文件列表，用空格隔开，路径可以是绝对路径，也可以是组件 CMakeLists.txt 的相对路径。
``set(ULP_EXP_DEP_SRCS "ulp_c_source_file_1.c ulp_c_source_file_2.c")``
设置组件中源文件名称的列表。所有包含被生成的头文件的原文件都必须在列表里。此列表建立正确构建依赖项，并确保在构建过程会先生成才编译包含头文件的原文件。请参考下文，查看为 ULP 应用程序生成的头文件等相关概念。此列表需要用空格隔开，路径可以是组件 CMakeLists.txt 文件的相对路径，也可以是绝对路径。
``include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)``
包含 ULP 编译步骤的通用定义。使用 ULP 工具链为 ULP 目标文件、ELF 文件、二进制文件等设置编译规则。
3. 使用常规方法（例如 `idf.py app`）编译应用程序
在内部，编译系统将按照以下步骤编译 ULP 程序：
1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。
2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。
3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 components/ulp/ld 目录中。
4. **将目标文件链接到 ELF 输出文件** (ulp_app_name.elf)。此步骤生成的.map 文件 (ulp_app_name.map) 默认用于调试。
5. **将 ELF 文件中的内容转储为二进制文件** (ulp_app_name.bin)，以便嵌入到应用程序中。
6. **使用 esp32ulp-elf-nm 在 ELF 文件中生成全局符号列表** (ulp_app_name.sym)。
7. **创建 LD 导出脚本和头文件** (ulp_app_name.ld 和 ulp_app_name.h)，包含来自 ulp_app_name.sym 的符号。此步骤可借助 esp32ulp_mapgen.py 工具来完成。
8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。**
访问 ULP 程序变量
-------------------------------
在 ULP 程序中定义的全局符号也可以在主程序中使用。
例如，ULP 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数::
.global measurement_count
measurement_count: .long 0
/* later, use measurement_count */
move r3, measurement_count
ld r3, r3, 0
主程序需要在启动 ULP 程序之前初始化 ``measurement_count`` 变量，编译系统生成 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件可以实现上述操作，这些文件在 ULP 编程中定义了全局符号，包含了在 ULP 程序中定义的所有全局符号，前缀为 ``ulp_``。
头文件包含对此类符号的声明::
extern uint32_t ulp_measurement_count;
注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。对于函数和数组，先获取符号地址，然后转换为适当的类型。
生成的链接器脚本文件定义了 RTC_SLOW_MEM 中的符号位置::
PROVIDE ( ulp_measurement_count = 0x50000060 );
如果要从主程序访问 ULP 程序变量，先包含生成的头文件，并使用上述变量，操作如下::
#include "ulp_app_name.h"
// later
void init_ulp_vars() {
ulp_measurement_count = 64;
}
注意，ULP 程序在 RTC 内存中只能使用 32 位字的低 16 位，因为寄存器是 16 位的，并且不具备从字的高位加载的指令。
同样，ULP 储存指令将寄存器值写入 32 位字的低 16 位中。高 16 位写入的值取决于储存指令的地址，因此在读取 ULP 写的变量时，主应用程序需要屏蔽高 16 位，例如::
printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX);
启动 ULP 程序
------------------------
要运行 ULP 程序，主应用程序需要调用 ``ulp_load_binary`` 函数将 ULP 程序加载到 RTC 内存中，然后调用 ``ulp_run`` 函数，启动 ULP 程序。
注意，在 menuconfig 中必须启用 "Enable Ultra Low Power (ULP) Coprocessor" 选项，以便为 ULP 预留内存。"RTC slow memory reserved for coprocessor" 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，则 RTC 内存必须足以容纳最大的程序。
每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB （假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``）::
extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start");
extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end");
void start_ulp_program() {
ESP_ERROR_CHECK( ulp_load_binary(
0 /* load address, set to 0 when using default linker scripts */,
bin_start,
(bin_end - bin_start) / sizeof(uint32_t)) );
}
.. doxygenfunction:: ulp_load_binary
一旦上述程序加载到 RTC 内存后，应用程序即可启动此程序，并将入口点的地址传递给 ``ulp_run`` 函数::
ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) );
.. doxygenfunction:: ulp_run
上述生成的头文件 ``${ULP_APP_NAME}.h`` 声明了入口点符号。在 ULP 应用程序的汇编源代码中，此符号必须标记为 ``.global``::
.global entry
entry:
/* code starts here */
ULP 程序流
----------------
ULP 协处理器由定时器启动，而调用 ``ulp_run`` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 150 KHz 晶振器生成）。使用 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器 (x = 0..4) 设置 Tick 数值。第一次启动 ULP 时，使用 ``SENS_ULP_CP_SLEEP_CYC0_REG`` 设置定时器 Tick 数值，之后，ULP 程序可以使用 ``sleep`` 指令来另外选择 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器。
此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值 (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4)。
.. doxygenfunction:: ulp_set_wakeup_period
一旦定时器达到在所选的 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器中设置的数值，ULP 协处理器就会启动，并调用 ``ulp_run`` 的入口点开始运行程序。
程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。
如果想禁用定时器（有效防止 ULP 程序再次运行），请清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位，可在 ULP 代码或主程序中进行以上操作。
.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp

60
docs/zh_CN/api-guides/unit-tests-cmake.rst → docs/zh_CN/api-guides/unit-tests-legacy.rst
View file

@ -1,7 +1,9 @@
ESP32 中的单元测试 (CMake)
==========================
ESP32 中的单元测试
==================
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
ESP-IDF
中附带了一个基于 ``Unity`` 的单元测试应用程序框架，且所有的单元测试用例分别保存在
ESP-IDF 仓库中每个组件的 ``test`` 子目录中。
@ -32,19 +34,12 @@ C 文件可以包含多个测试用例。测试文件的名字要以 “test”
来声明主函数的区域， ``unity_platform.c`` 会自动调用
``UNITY_BEGIN()``\ ， 然后运行测试用例，最后调用 ``UNITY_END()``\ 。
``test`` 子目录需要包含 ：ref：`组件 CMakeLists.txt <component-directories-cmake>`，因为他们本身就是一种组件。ESP-IDF 使用了
``unity`` 测试框架，需要将其指定为组件的依赖项。通常，组件
：ref：`需要手动指定待编译的源文件 <cmake-file-globbing>`;但是，对于测试组件来说，这个要求被放宽了，仅仅是建议使用 “COMPONENT_SRCDIRS”。
每一个测试子目录下都应该包含一个
``component.mk``\ ，并且里面至少要包含如下的一行内容：
总的来说，``test`` 子目录下最简单的 CMakeLists.txt 文件可能如下所示:
.. code:: makefile
.. code:: cmake
set(COMPONENT_SRCDIRS ".")
set(COMPONENT_ADD_INCLUDEDIRS ".")
set(COMPONENT_REQUIRES unity)
register_component()
COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive
更多关于如何在 Unity 下编写测试用例的信息，请查阅
http://www.throwtheswitch.org/unity 。
@ -117,6 +112,21 @@ DUT2（slave）终端：
一旦 DUT2 发送了该信号，您需要在 DUT2 的终端输入回车，然后 DUT1 会从
``unity_wait_for_signal`` 函数中解除阻塞，并开始更改 GPIO 的电平。
信号也可以用来在不同 DUT 之间传递参数。例如，DUT1 希望能够拿到 DUT2 的 MAC 地址，来进行蓝牙连接。
这时，我们可以使用 ``unity_wait_for_signal_param`` 以及 ``unity_send_signal_param``。
DUT1 终端::
Waiting for signal: [dut2 mac address]!
Please input parameter value from any board send this signal and press "Enter" key.
DUT2 终端::
Send signal: [dut2 mac address][10:20:30:40:50:60]!
一旦 DUT2 发送信号，您需要在 DUT1 输入 ``10:20:30:40:50:60`` 及回车，然后 DUT1 会从 ``unity_wait_for_signal_param`` 中获取到蓝牙地址的字符串，并解除阻塞开始蓝牙连接。
添加多阶段测试用例
------------------
@ -150,23 +160,23 @@ DUT2（slave）终端：
切换到 ``tools/unit-test-app`` 目录下进行配置和编译：
- ``idf.py menuconfig`` - 配置单元测试程序。
- ``make menuconfig`` - 配置单元测试程序。
- ``idf.py -T all build`` - 编译单元测试程序，测试每个组件 ``test``
- ``make TESTS_ALL=1`` - 编译单元测试程序，测试每个组件 ``test``
子目录下的用例。
- ``idf.py -T xxx build`` - 编译单元测试程序，测试指定的组件。
- ``make TEST_COMPONENTS='xxx'`` - 编译单元测试程序，测试指定的组件。
- ``idf.py -T all -E xxx build`` -
- ``make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'`` -
编译单元测试程序，测试所有（除开指定）的组件。例如
``idf.py -T all -E ulp mbedtls build`` -
``make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'`` -
编译所有的单元测试，不包括 ``ulp`` 和 ``mbedtls``\ 组件。
当编译完成时，它会打印出烧写芯片的指令。您只需要运行 ``idf.py flash``
当编译完成时，它会打印出烧写芯片的指令。您只需要运行 ``make flash``
即可烧写所有编译输出的文件。
您还可以运行 ``idf.py -T all flash`` 或者
``idf.py -T xxx flash``
您还可以运行 ``make flash TESTS_ALL=1`` 或者
``make TEST_COMPONENTS='xxx'``
来编译并烧写，所有需要的文件都会在烧写之前自动重新编译。
使用 ``menuconfig`` 可以设置烧写测试程序所使用的串口。
@ -211,13 +221,13 @@ DUT2（slave）终端：
可以输入以下任意一项来运行测试用例：
- 引号中的测试用例的名字，运行单个测试用例。
- 引号中的测试用例的名字（例如 ``"esp_ota_begin() verifies arguments"``），运行单个测试用例。
- 测试用例的序号，运行单个测试用例。
- 测试用例的序号（例如 ``1``），运行单个测试用例。
- 方括号中的模块名字，运行指定模块所有的测试用例。
- 方括号中的模块名字（例如 ``[cxx]``），运行指定模块所有的测试用例。
- 星号，运行所有测试用例。
- 星号 (``*``)，运行所有测试用例。
``[multi_device]`` 和 ``[multi_stage]``
标签告诉测试运行者该用例是多设备测试还是多阶段测试。这些标签由

Some files were not shown because too many files have changed in this diff Show more