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

Merge branch 'feature/cmake_separate_docs' into 'feature/cmake'

Browse source 
docs: Copy CMake docs to a separate set of directories

See merge request idf/esp-idf!2959
This commit is contained in:
Angus Gratton 2018-08-13 15:47:07 +08:00
parent dbb82a413f 48bd67524d
commit 810aa5427c
68 changed files with 4379 additions and 1129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/_static/what-you-need-cmake.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 111 KiB

6
docs/conf_common.py
View file

@ -41,11 +41,11 @@ copy_if_modified('xml/', 'xml_in/')
os.system('python ../gen-dxd.py')
# Generate 'kconfig.inc' file from components' Kconfig files
print "Generating kconfig.inc from kconfig contents"
print("Generating kconfig.inc from kconfig contents")
kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"])
kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"])
kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"]).decode()
kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"]).decode()
confgen_args = ["python",
"../../tools/kconfig_new/confgen.py",
"--kconfig", "../../Kconfig",

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

@ -0,0 +1,942 @@
Build System (CMake)
********************
.. include:: ../cmake-warning.rst
.. include:: ../cmake-pending-features.rst
This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components". :doc:`Documentation for the GNU Make based build system <build-system>` is also available
Read this document if you want to know how to organise and build a new ESP-IDF project or component using the CMake-based build system.
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 WiFi 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 system 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 system 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 elements 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 ``idf.py 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.
Using the Build System
======================
.. _idf.py:
idf.py
------
The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools:
- CMake_, which configures the project to be built
- A command line build tool (either Ninja_ build or `GNU Make`)
- `esptool.py`_ for flashing ESP32.
The :ref:`getting started guide <get-started-configure-cmake>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones:
- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
- Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
- Run CMake_ as necessary to configure the project and generate build files for the main build tool.
- Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree.
- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`/get-started/idf-monitor` for more details about using the monitor.
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.
.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
Advanced Commands
^^^^^^^^^^^^^^^^^
- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively.
The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
Using CMake Directly
--------------------
:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
.. highlight:: bash
When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt)::
mkdir -p build
cd build
cmake .. -G Ninja # or 'Unix Makefiles'
ninja
In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project.
It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration.
If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
.. note::
If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
Using CMake in an IDE
---------------------
You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE.
When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_.
.. setting-python-interpreter:
Setting the Python Interpreter
------------------------------
Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems.
If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command.
If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter.
If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter.
To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version.
.. _example-project-structure:
Example Project
===============
.. highlight:: none
An example project directory tree might look like this::
- myProject/
- CMakeLists.txt
- sdkconfig
- components/ - component1/ - CMakeLists.txt
- Kconfig
- src1.c
- component2/ - CMakeLists.txt
- Kconfig
- src1.c
- include/ - component2.h
- main/ - src1.c
- src2.c
- build/
This example "myProject" contains the following elements:
- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then it includes the file :idf_file:`/tools/cmake/project.cmake` which
implements the rest of the build system. Finally, it sets the project name and defines the project.
- "sdkconfig" project configuration file. This file is created/updated when ``idf.py 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 "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also 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 each contain a component ``CMakeLists.txt`` file. This file contains variable definitions
to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
Project CMakeLists File
=======================
Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
Minimal Example CMakeLists
--------------------------
.. highlight:: cmake
Minimal project::
cmake_minimum_required(VERSION 3.5)
set(MAIN_SRCS main/src1.c main/src2.c)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(myProject)
.. _project-mandatory-parts:
Mandatory Parts
---------------
The inclusion of these four lines, in the order shown above, is necessary for every project:
- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" sub-directory, but this structure is encouraged.
It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below.
``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else).
- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
Optional Project Variables
--------------------------
These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, 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. Paths can be relative to the project directory, or absolute.
- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list can be very short.
- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically added to every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this variable is set to the minimal set of core "system" components needed for any ESP-IDF project. Usually, you would not change this variable in your project.
Any paths in these variables can be absolute paths, or set relative to the project directory.
To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
.. _component-directories-cmake:
Component CMakeLists Files
==========================
Each project contains one or more components. Components can be part of ESP-IDF, part of the project's own components directory, or added from custom component directories (:ref:`see above <component-directories-cmake>`).
A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` 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 `CMakeLists.txt` file), or they can be top-level directories whose sub-directories are components.
When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
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 ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories
contain component sub-directories 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 copying that component from the ESP-IDF components directory to the project components directory and then modifying it there.
If used in this way, the ESP-IDF directory itself can remain untouched.
Minimal Component CMakeLists
----------------------------
.. highlight:: cmake
The minimal component ``CMakeLists.txt`` file is as follows::
set(COMPONENT_SRCDIRS ".")
set(COMPONENT_ADD_INCLUDEDIRS "include")
register_component()
- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library.
- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for any component which requires this component, and also the main source files.
- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if function <cmake if_>`_ or similar), this component will not be part of the build.
Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
.. _component variables:
Preset Component Variables
--------------------------
The following component-specific variables are available for use inside component CMakeLists, 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. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
The following variables are set at the project level, but available for use in component CMakeLists:
- ``PROJECT_NAME``: Name of the project, as set in project Makefile
- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to the include search path for
all other components which require this one. If an include directory is only needed to compile this specific component,
add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If this component has a header file in a ``COMPONENT_ADD_INCLUDEDIRS`` directory that includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive.
The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``.
If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead.
See `Component Requirements`_ for more details.
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_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements`_ for more details.
- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will be searched for source files (``*.cpp``,
``*.c``, ``*.S``). Set this to specify a list of directories which contain source files.
- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add include paths for use when compiling other components or the source files listed in ``MAIN_SRCS``.
- ``COMPONENT_SRCEXCLUDE``: Paths to source files to exclude from component. Can be set in conjunction with ``COMPONENT_SRCDIRS`` if there is a directory with a large number of source files to include in the component but one or more source files which should not be. Paths can be specified relative to the component directory or absolute.
Controlling Component Compilation
---------------------------------
.. highlight:: cmake
To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function::
component_compile_options(-Wno-unused-variable)
This is a wrapper around the CMake `target_compile_options`_ command.
To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command::
set_source_files_properties(mysrc.c
PROPERTIES COMPILE_FLAGS
-Wno-unused-variable
)
This can be useful if there is upstream code that emits warnings.
When using these commands, place them after the ``register_component()`` line in the component CMakeLists file.
.. _component-configuration-cmake:
Component Configuration
=======================
Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains
configuration settings to add to the configuration menu 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
========================
The ESP-IDF build system 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`` — Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
Component Requirements
======================
When compiling each component, the ESP-IDF build system recursively evaluates its components.
Each component's source file is compiled with these include path directories:
- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``.
- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies).
- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded).
When writing a component
------------------------
- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
- ``COMPONENT_PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly.
- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``.
- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset.
When creating a project
-----------------------
- By default, every component is included in the build.
- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
- Components mentioned explicitly in ``COMPONENTS``.
- Those components' requirements (evaluated recursively).
- The "common" components that every component depends on.
- Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times.
- When compiling the project's source files (``MAIN_SRCS``), the public header directories (``COMPONENT_ADD_INCLUDEDIRS`` list) of all components included in the build are available.
.. _component-requirements-implementation:
Requirements in the build system implementation
-----------------------------------------------
- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
- Configuration is then evaluated for the components included in the build.
- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
Build Process Internals
=======================
For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`_.
project.cmake contents
----------------------
When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment.
It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality.
project function
----------------
The custom ``project()`` function performs the following steps:
- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above<component-requirements-implementation>`).
- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
- Loads the project configuration from the ``sdkconfig`` file and generates a ``sdkconfig.cmake`` file and a ``sdkconfig.h`` header. These define configuration values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to re-generate these files and re-configure the project.
- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
- Declare the actual cmake-level project by calling the `CMake project function <cmake project_>`_.
- Load the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
- Include ``project_include.cmake`` files from any components which have them.
- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the CMake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
- Add the final app executable to the build.
- Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
Debugging CMake
---------------
Some tips for debugging the ESP-IDF CMake-based build system:
- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
- Running ``cmake -DDEBUG=1`` will produce more verbose diagnostic output from the IDF build system.
- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_.
.. _warn-undefined-variables-cmake:
Warning On Undefined Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files.
If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
Overriding Parts of the Project
-------------------------------
project_include.cmake
^^^^^^^^^^^^^^^^^^^^^
For components that have build requirements which must be evaluated before any component CMakeLists
files are evaluated, you can create a file called ``project_include.cmake`` in the
component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
Note that ``project_include.cmake`` 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 ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
KConfig.projbuild
^^^^^^^^^^^^^^^^^
This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration-cmake` 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 ``CMakeLists.txt`` 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 :ref:`component-configuration-cmake`.
Configuration-Only Components
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration.
Example Component CMakeLists
============================
Because the build environment tries to set reasonable defaults that will work most
of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
Here are some more advanced examples of component CMakeLists files.
Adding conditional configuration
--------------------------------
The configuration system can be used to conditionally compile some files
depending on the options selected in the project configuration.
.. highlight:: none
``Kconfig``::
config FOO_ENABLE_BAR
bool "Enable the BAR feature."
help
This enables the BAR feature of the FOO component.
``CMakeLists.txt``::
set(COMPONENT_SRCS "foo.c" "more_foo.c")
if(CONFIG_FOO_ENABLE_BAR)
list(APPEND COMPONENT_SRCS "bar.c")
endif(CONFIG_FOO_ENABLE_BAR)
This example makes use of the CMake `if function <cmake if_>`_ and `list APPEND <cmake list_>`_ function.
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
.. highlight:: cmake
``CMakeLists.txt``::
if(CONFIG_ENABLE_LCD_OUTPUT)
set(COMPONENT_SRCS lcd-real.c lcd-spi.c)
else()
set(COMPONENT_SRCS lcd-dummy.c)
endif()
# We need font if either console or plot is enabled
if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT)
list(APPEND COMPONENT_SRCS "font.c")
endif()
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::
add_custom_command(OUTPUT logo.h
COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h
DEPENDS ${COMPONENT_PATH}/logo.bmp
VERBATIM)
add_custom_target(logo DEPENDS logo.h)
add_dependencies(${COMPONENT_NAME} logo)
set_property(DIRECTORY "${COMPONENT_PATH}" APPEND PROPERTY
ADDITIONAL_MAKE_CLEAN_FILES logo.h)
This answer is adapted from the `CMake FAQ entry <cmake faq generated files_>`_, which contains some other examples that will also work with ESP-IDF builds.
In this example, 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 should be cleaned when the project is cleaned. For this reason
it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
.. note::
If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between
the two components, to ensure that the component source files were always compiled in the correct 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 your component's CMakeLists, giving space-delimited names of the files to embed::
set(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::
set(COMPONENT_EMBED_TXTFILES server_root_cert.pem)
.. highlight:: c
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.
.. highlight:: cmake
To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
target_add_binary_data(myproject.elf "main/data.bin" TEXT)
Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is.
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.
.. _component-build-full-override:
Fully Overriding The Component Build Process
--------------------------------------------
.. highlight:: cmake
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 using a CMake feature called ExternalProject_. Example component CMakeLists::
# External build process for quirc, runs in source dir and
# produces libquirc.a
externalproject_add(quirc_build
PREFIX ${COMPONENT_PATH}
SOURCE_DIR ${COMPONENT_PATH}/quirc
CONFIGURE_COMMAND ""
BUILD_IN_SOURCE 1
BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
INSTALL_COMMAND ""
)
# Add libquirc.a to the build process
#
add_library(quirc STATIC IMPORTED GLOBAL)
add_dependencies(quirc quirc_build)
set_target_properties(quirc PROPERTIES IMPORTED_LOCATION
${COMPONENT_PATH}/quirc/libquirc.a)
set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
${COMPONENT_PATH}/quirc/lib)
set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
"${COMPONENT_PATH}/quirc/libquirc.a")
(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
- ``externalproject_add`` defines an external build system.
- ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
- Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
- Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
.. _ADDITIONAL_MAKE_CLEAN_FILES_note:
ExternalProject dependencies, clean builds
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CMake has some unusual behaviour around external project builds:
- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
- Therefore, there are two alternative recommended ways to configure the external build command:
1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
.. _custom-sdkconfig-defaults-cmake:
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 creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
Flash arguments
===============
There are 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.
After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
- ``flash_app_args`` contains arguments to flash only the app.
- ``flash_bootloader_args`` contains arguments to flash only the bootloader.
.. highlight:: bash
You can pass any of these flasher argument files to ``esptool.py`` as follows::
python esptool.py --chip esp32 write_flash @build/flash_project_args
Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
Building the Bootloader
=======================
The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
Writing Pure CMake Components
=============================
The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build.
However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
.. highlight:: cmake
Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``::
add_library(json STATIC
cJSON/cJSON.c
cJSON/cJSON_Utils.c)
target_include_directories(json PUBLIC cJSON)
- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
File Globbing & Incremental Builds
==================================
.. highlight:: cmake
The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``::
set(COMPONENT_SRCDIRS library platform)
The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually::
set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c)
CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build.
The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
For project CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is the approach which CMake_ recommends.)
For project components (not part of ESP-IDF), there are a few different options:
- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes.
- If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes.
- If not using Git, remember to manually run ``idf.py reconfigure`` whenever a source file may change.
- To avoid this problem entirely, use ``COMPONENT_SRCS`` to list all source files in project components.
The best option will depend on your particular project and its users.
Build System Metadata
=====================
For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs.
JSON Configuration Server
-------------------------
.. highlight :: json
A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout.
You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator.
The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``::
{"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } }
Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.)
The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline::
{"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } }
The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes::
{"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}}
Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value.
If the range of a config item changes, due to conditional range depending on another value, then this is also sent::
{"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
If invalid data is passed, an "error" field is present on the object::
{"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]}
By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent::
{"version": 1, "save": null }
To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent::
{"version": 1, "load": null }
The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname.
The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started.
Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command.
.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited.
.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run.
.. _gnu-make-to-cmake:
Migrating from ESP-IDF GNU Make System
======================================
Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
Automatic Conversion Tool
-------------------------
.. highlight:: bash
An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this::
$IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir
The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH.
The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files.
It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables.
The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand.
'main' is no longer a component
-------------------------------
In the GNU Make build system ``main`` is a component with a ``component.mk`` file like other components.
Due to CMake requirements for building executables, ``main`` source files are now linked directly into the final binary. The source files in ``main`` must be listed in the ``MAIN_SRCS`` variable (see :ref:`project mandatory variables <project-mandatory-parts>` for more details). At least one source file has to be listed here (although it doesn't need to contain anything in particular).
In general, it's better not to have too many source files in ``MAIN_SRCS``. If you find that you are adding many source files here, see if you can reorganize and group some into project components (see the :ref:`example project structure <example-project-structure>`, above).
No Longer Available in CMake
----------------------------
Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component.
- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``.
- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository.
- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``.
- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead.
- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details.
- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_.
No Default Values
-----------------
The following variables no longer have default values:
- ``COMPONENT_SRCDIRS``
- ``COMPONENT_ADD_INCLUDEDIRS``
No Longer Necessary
-------------------
It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
.. _esp-idf-template: https://github.com/espressif/esp-idf-template
.. _cmake: https://cmake.org
.. _ninja: https://ninja-build.org
.. _esptool.py: https://github.com/espressif/esptool/#readme
.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html
.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/project.html
.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html
.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html
.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html
.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html
.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html
.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F
.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html
.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html
.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages
.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html
.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html
.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
.. _quirc: https://github.com/dlbeer/quirc
.. _pyenv: https://github.com/pyenv/pyenv#README
.. _virtualenv: https://virtualenv.pypa.io/en/stable/

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

File diff suppressed because it is too large Load diff

55
docs/en/api-guides/gnu-make-build-system.rst
View file

@ -1,55 +0,0 @@
GNU Make Build System
*********************
This document contains a "cheat sheet" for users of the older ESP-IDF GNU Make build system and the newer CMake build system.
Currently, this version of ESP-IDF contains support for both build systems, and either build system can be used. However, the rest of the documentation for this version has been updated for the CMake build system.
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view dedicated documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
Dependencies
============
For Linux & Mac OS, the dependencies for the GNU Make and CMake-based build systems are very similar. The only additional tool required for GNU Make is ``make`` 3.81 or newer. This is pre-installed on Mac OS and can be installed on Linux via the distribution package manager.
For Windows, the requirements are different as the GNU Make based build system requires MSYS2 for a Unix compatibility layer. Consult the Getting Started docs for IDF v3.0 for steps to set up MSYS2.
Cheat Sheet
===========
Equivalents between GNU make-based build system commands and the CMake-based build system:
==================== ================== =================
Summary CMake-based GNU Make based
==================== ================== =================
Configure project idf.py menuconfig make menuconfig
Build project idf.py build make
Flash project idf.py flash make flash
Monitor project idf.py monitor make monitor
Clean project idf.py fullclean make clean
==================== ================== =================
To override the default build directory:
- CMake based: ``idf.py -b (directory) build``
- GNU Make based: ``make BUILD_DIR_BASE=(directory)``.
To set the serial port for flashing/monitoring:
- CMake based: ``idf.py -p (port) flash``
- GNU Make based: ``make flash ESPPORT=/dev/ttyUSB0``, or set in ``menuconfig``.
(Note: ``idf.py`` will also use the ``ESPPORT`` environment variable for a default serial port, if no ``-p`` argument is provided.)
To set the baud rate for flashing:
- CMake based: ``idf.py -b 921600 flash``
- GNU Make based: ``make flash ESPBAUD=921600``, or set in ``menuconfig``.
(Note: ``idf.py`` will also use the ``ESPBAUD`` environment variable for a default baud rate, if no ``-b`` argument is provided.)
Porting GNU Make Based Components to CMake
==========================================
See :ref:`gnu-make-to-cmake`.

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

@ -6,6 +6,7 @@ API Guides
General Notes <general-notes>
Build System <build-system>
Build System (CMake) <build-system-cmake>
Deep Sleep Wake Stubs <deep-sleep-stub>
ESP32 Core Dump <core_dump>
Flash Encryption <../security/flash-encryption>

10
docs/en/cmake-pending-features.rst Normal file
View file

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

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

@ -0,0 +1,4 @@
.. 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.

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

@ -0,0 +1,73 @@
Add IDF_PATH & idf.py PATH to User Profile (CMake)
==================================================
.. include:: ../cmake-warning.rst
To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
.. _add-paths-to-profile-windows-cmake:
Windows
-------
To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
- Click ``New...`` to add a new system variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\user-name\esp\esp-idf``.
- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
.. _add-idf_path-to-profile-linux-macos-cmake:
Linux and MacOS
---------------
Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to your ``~/.profile`` file::
export IDF_PATH=~/esp/esp-idf
export PATH="$PATH:$IDF_PATH/tools"
.. note::
``~/.profile`` means a file named ``.profile`` in your user's home directory (which is abbreviated ``~`` in the shell).
Log off and log in back to make this change effective.
.. note::
Not all shells use ``.profile``. If you have ``/bin/bash`` and ``.bash_profile`` exists then update this file instead. For ``zsh``, update ``.zprofile``. Other shells may use other profile files (consult the shell's documentation).
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.
To verify idf.py is now on the ``PATH``, you can run the following::
which idf.py
A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
export IDF_PATH=~/esp/esp-idf
export PATH="$PATH:$IDF_PATH/tools"
If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.

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

@ -0,0 +1,10 @@
****************************************
Build and Flash with Eclipse IDE (CMake)
****************************************
.. 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/

131
docs/en/get-started-cmake/establish-serial-connection.rst Normal file
View file

@ -0,0 +1,131 @@
Establish Serial Connection with ESP32 (CMake)
==============================================
This section provides guidance how to establish serial connection between ESP32 and PC.
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:
* ESP32-PICO-KIT and ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
* ESP32-WROVER-KIT and ESP32 Demo Board - `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/VCP.htm>`_
Above drivers are primarily for reference. They should already be bundled with the operating system and installed automatically once one of listed boards is connected to the PC.
Check port on Windows
---------------------
Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again.
Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
.. figure:: ../../_static/esp32-devkitc-in-device-manager.png
:align: center
:alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager
:figclass: align-center
USB to UART bridge of ESP32-DevKitC in Windows Device Manager
.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
:align: center
:alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
:figclass: align-center
Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
Check port on Linux and MacOS
-----------------------------
To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
Linux ::
ls /dev/tty*
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:
Adding user to ``dialout`` on Linux
-----------------------------------
The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to ``dialout`` group with the following command::
sudo usermod -a -G dialout $USER
Make sure you re-login to enable read and write permissions for the serial port.
Verify serial connection
------------------------
Now verify that the serial connection is operational. You can do this using a serial terminal program. In this example we will use `PuTTY SSH Client <http://www.putty.org/>`_ that is available for both Windows and Linux. You can use other serial program and set communication parameters like below.
Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
.. figure:: ../../_static/putty-settings-windows.png
:align: center
:alt: Setting Serial Communication in PuTTY on Windows
:figclass: align-center
Setting Serial Communication in PuTTY on Windows
.. figure:: ../../_static/putty-settings-linux.png
:align: center
:alt: Setting Serial Communication in PuTTY on Linux
:figclass: align-center
Setting Serial Communication in PuTTY on Linux
Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below.
.. highlight:: none
::
ets Jun 8 2016 00:22:57
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0x00
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0008,len:8
load:0x3fff0010,len:3464
load:0x40078000,len:7828
load:0x40080000,len:252
entry 0x40080034
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
I (45) boot: compile time 18:48:10
...
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::
For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details.
.. 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-cmake` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure-cmake`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

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

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

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

@ -0,0 +1,114 @@
ESP32-DevKitC V4 Getting Started Guide (CMake)
==============================================
This user guide shows how to get started with ESP32-DevKitC V4 development board. For description of other versions of the ESP32-DevKitC check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front-cmake>`
* 1 × USB A / micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard.
The board comes in two versions, either with :ref:`esp-modules-and-boards-esp-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module soldered.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC V4 board.
ESP-WROOM-32
:ref:`esp-modules-and-boards-esp-wroom-32` module soldered to the ESP32-DevKitC V4 board.
ESP32-WROVER
Optionally :ref:`esp-modules-and-boards-esp32-wrover` module may be soldered instead of the ESP-WROOM-32.
USB-UART Bridge
A single chip USB-UART bridge provides up to 3 Mbps transfers rates.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and the ESP module.
5V Power On LED
This LED lights when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
EN
Reset button: pressing this button resets the system.
I/O
Most of the pins on the ESP module are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
.. note::
Some of broken out pins are used internally be the ESP32 module to communicate with SPI memory. They are grouped on one side of the board besides the USB connector and labeled D0, D1, D2, D3, CMD and CLK. In general these pins should be left unconnected or access to the SPI flash memory / SPI RAM may be disturbed.
.. note::
GPIO16 and 17 are used internally by the ESP32-WROVER module. They are broken out and avialable for use only for boards that have the ESP-WROOM-32 module installed.
.. _get-started-esp32-devkitc-board-front-cmake:
.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg
:align: center
:alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
:figclass: align-center
ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
Power Supply Options
--------------------
There following options are available to provide power supply to this board:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Start Application Development
------------------------------
Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
* :ref:`get-started-build-cmake` for an example application
* :ref:`get-started-flash-cmake` to run code on the ESP32
* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
Board Dimensions
----------------
.. figure:: ../../_static/esp32-devkitc-dimensions-back.jpg
:align: center
:alt: ESP32 DevKitC board dimensions - back
:figclass: align-center
ESP32 DevKitC board dimensions - back
Related Documents
-----------------
* `ESP32-DevKitC V4 schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf>`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
.. toctree::
:hidden:
get-started-devkitc-v2

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

@ -0,0 +1,67 @@
ESP32-PICO-KIT V3 Getting Started Guide (CMake)
===============================================
This user guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × ESP32-PICO-KIT V3 mini development board
* 1 × USB A / Micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
--------
ESP32-PICO-KIT V3 is a mini development board based on the ESP32-PICO-D4 SIP module produced by `Espressif <https://espressif.com>`_. All the IO signals and system power on ESP32-PICO-D4 are led out through two standard 20 pin x 0.1" pitch headers on both sides for easy interfacing. The development board integrates a USB-UART Bridge circuit, allowing the developers to connect the development board to a PC's USB port for downloads and debugging.
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-PICO-KIT V3 board.
ESP32-PICO-D4
Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V3 board. The complete system of the ESP32 chip has been integrated into the SIP module, requiring only external antenna with LC matching network, decoupling capacitors and pull-up resistors for EN signals to function properly.
USB-UART Bridge
A single chip USB-UART bridge provides up to 1 Mbps transfers rates.
I/O
All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32-PICO-KIT V3.
EN Button
Reset button; pressing this button resets the system.
BOOT Button
Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
.. figure:: ../../_static/esp32-pico-kit-v3-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V3 board layout
:figclass: align-center
ESP32-PICO-KIT V3 board layout
Start Application Development
------------------------------
Before powering up the ESP32-PICO-KIT V3, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
* :ref:`get-started-build-cmake` for an example application
* :ref:`get-started-flash-cmake` to run code on the ESP32
* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
Related Documents
-----------------
* `ESP32-PICO-KIT V3 schematic <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v3_schematic.pdf>`_ (PDF)
* `ESP32-PICO-D4 Datasheet <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
* :doc:`../hw-reference/index`

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

@ -0,0 +1,213 @@
ESP32-PICO-KIT V4 Getting Started Guide (CMake)
===============================================
This user guide shows how to get started with the ESP32-PICO-KIT V4 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.
What You Need
-------------
* 1 × :ref:`ESP32-PICO-KIT V4 mini development board <get-started-pico-kit-v4-board-front-cmake>`
* 1 × USB A / Micro USB B cable
* 1 × PC loaded with Windows, Linux or Mac OS
If you like to start using this board right now, go directly to section `Start Application Development`_.
Overview
--------
ESP32-PICO-KIT V4 is a mini development board produced by `Espressif <https://espressif.com>`_. At the core of this board is the ESP32-PICO-D4, a System-in-Package (SIP) module with complete Wi-Fi and Bluetooth functionalities. Comparing to other ESP32 chips, the ESP32-PICO-D4 integrates several peripheral components in one single package, that otherwise would need to be installed separately. This includes a 40 MHz crystal oscillator, 4 MB flash, filter capacitors and RF matching links in. This greatly reduces quantity and costs of additional components, subsequent assembly and testing cost, as well as overall product complexity.
The development board integrates a USB-UART Bridge circuit, allowing the developers to connect the board to a PC's USB port for downloads and debugging.
For easy interfacing, all the IO signals and system power on ESP32-PICO-D4 are led out through two rows of 20 x 0.1" pitch header pads on both sides of the development board. To make the ESP32-PICO-KIT V4 fit into mini breadboards, the header pads are populated with two rows of 17 pin headers. Remaining 2 x 3 pads grouped on each side of the board besides the antenna are not populated. The remaining 2 x 3 pin headers may be soldered later by the user.
.. note::
The 2 x 3 pads not populated with pin headers are internally connected to the flash memory embedded in the ESP32-PICO-D4 SIP module. For more details see module's datasheet in `Related Documents`_.
The board dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"), see section `Board Dimensions`_. An overview functional block diagram is shown below.
.. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png
:align: center
:alt: ESP32-PICO-KIT V4 functional block diagram
:figclass: align-center
ESP32-PICO-KIT V4 functional block diagram
Functional Description
----------------------
The following list and figure below describe key components, interfaces and controls of ESP32-PICO-KIT V4 board.
ESP32-PICO-D4
Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V4 board. The complete system of the ESP32 chip has been integrated into the SIP module, requiring only external antenna with LC matching network, decoupling capacitors and pull-up resistors for EN signals to function properly.
LDO
5V-to-3.3V Low dropout voltage regulator (LDO).
USB-UART Bridge
A single chip USB-UART bridge provides up to 1 Mbps transfers rates.
Micro USB Port
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32-PICO-KIT V4.
5V Power On LED
This light emitting diode lits when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
I/O
All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details please see section `Pin Descriptions`_.
BOOT Button
Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
EN Button
Reset button; pressing this button resets the system.
.. _get-started-pico-kit-v4-board-front-cmake:
.. figure:: ../../_static/esp32-pico-kit-v4-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V4 board layout
:figclass: align-center
ESP32-PICO-KIT V4 board layout
Power Supply Options
--------------------
There following options are available to provide power supply to the ESP32-PICO-KIT V4:
1. Micro USB port, this is default power supply connection
2. 5V / GND header pins
3. 3V3 / GND header pins
.. warning::
Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
Start Application Development
-----------------------------
Before powering up the ESP32-PICO-KIT V4, please make sure that the board has been received in good condition with no obvious signs of damage.
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
* :ref:`get-started-build-cmake` for an example application
* :ref:`get-started-flash-cmake` to run code on the ESP32
* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
Pin Descriptions
----------------
The two tables below provide the **Name** and **Function** of I/O headers 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 on a schematic in `Related Documents`_.
Header J2
"""""""""
====== ================= ====== ======================================================
No. Name Type Function
====== ================= ====== ======================================================
1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2CTS
2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2RTS
3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , 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
7 IO23 I/O | GPIO23, VSPID, HS1_STROBE
8 IO18 I/O | GPIO18, VSPICLK, HS1_DATA7
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:`(4) <get-started-pico-kit-v4-pin-notes-cmake>` , CLK_OUT2
13 TXD0 I/O | GPIO1, U0TXD :ref:`(4) <get-started-pico-kit-v4-pin-notes-cmake>` , CLK_OUT3, EMAC_RXD2
14 IO35 I | ADC1_CH7, RTC_GPIO5
15 IO34 I | ADC1_CH6, RTC_GPIO4
16 IO38 I | GPIO38, ADC1_CH2, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes-cmake>` , RTC_GPIO2
17 IO37 I | GPIO37, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH1, RTC_GPIO1
18 EN I | CHIP_PU
19 GND P | Ground
20 VDD33 (3V3) P | 3.3V power supply
====== ================= ====== ======================================================
Header J3
"""""""""
====== ================= ====== ======================================================
No. Name Type Function
====== ================= ====== ======================================================
1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2RXD, EMAC_CLK_OUT
2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(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:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U1RTS
4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes-cmake>` , RTC_GPIO0
5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes-cmake>` , 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:`(3a) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH4, TOUCH9, RTC_GPIO9
9 IO33 I/O | 32K_XN :ref:`(3b) <get-started-pico-kit-v4-pin-notes-cmake>` , 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:`(5) <get-started-pico-kit-v4-pin-notes-cmake>` , 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
14 IO15 I/O | ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0
| HS2_CMD, SD_CMD, EMAC_RXD3
15 IO2 I/O | ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP,
| HS2_DATA0, SD_DATA0
16 IO4 I/O | ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD,
| HS2_DATA1, SD_DATA1, EMAC_TX_ER
17 IO0 I/O | ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1
| EMAC_TX_CLK
18 VDD33 (3V3) P | 3.3V power supply
19 GND P | Ground
20 EXT_5V (5V) P | 5V power supply
====== ================= ====== ======================================================
.. _get-started-pico-kit-v4-pin-notes-cmake:
**Notes to** `Pin Descriptions`_
1. This pin is connected to the flash pin of ESP32-PICO-D4.
2. When used as ADC_PRE_AMP, connect 270 pF capacitors between: (a) SENSOR_VP and IO37, (b) SENSOR_VN and IO38.
3. 32.768 kHz crystal oscillator: (a) input, (b) output.
4. This pin is connected to the pin of the USB bridge chip on the board.
5. The operating voltage of ESP32-PICO-KIT’s embedded SPI flash is 3.3V. Therefore, the strapping pin MTDI should hold bit ”0” during the module power-on reset.
Board Dimensions
----------------
.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-back.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - back
:figclass: align-center
ESP32-PICO-KIT V4 dimensions - back
.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-side.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - side
:figclass: align-center
ESP32-PICO-KIT V4 dimensions - side
Related Documents
-----------------
* `ESP32-PICO-KIT V4 schematic <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v4_schematic.pdf>`_ (PDF)
* `ESP32-PICO-D4 Datasheet <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
* :doc:`../hw-reference/index`
.. toctree::
:hidden:
get-started-pico-kit-v3

192
docs/en/get-started-cmake/get-started-wrover-kit-v2.rst Normal file
View file

@ -0,0 +1,192 @@
ESP-WROVER-KIT V2 Getting Started Guide (CMake)
===============================================
This user guide shows how to get started with ESP-WROVER-KIT V2 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`.
If you like to start using this board right now, go directly to section :ref:`esp-wrover-kit-v2-start-development-cmake`.
What You Need
-------------
* 1 × ESP-WROVER-KIT V2 board
* 1 x Micro USB 2.0 Cable, Type A to Micro B
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
^^^^^^^^
The ESP-WROVER-KIT is a development board produced by `Espressif <https://espressif.com>`_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective.
.. note::
ESP-WROVER-KIT V2 integrates the ESP-WROOM-32 module by default.
Functionality Overview
^^^^^^^^^^^^^^^^^^^^^^
Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
.. figure:: ../../_static/esp32-wrover-kit-block-diagram.png
:align: center
:alt: ESP-WROVER-KIT block diagram
:figclass: align-center
ESP-WROVER-KIT block diagram
Functional Description
^^^^^^^^^^^^^^^^^^^^^^
The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board.
32.768 kHz
An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode.
ESP32 Module
ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities.
.. note::
GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out.
CTS/RTS
Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers.
UART
Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device.
SPI
SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. If an ESP32-WROVER is being used, please note that the electrical level on the flash and SRAM is 1.8V.
JTAG
JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals.
FT2232
FT2232 chip is a multi-protocol USB-to-serial bridge. The FT2232 chip features USB-to-UART and USB-to-JTAG functionalities. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32.
The embedded FT2232 chip is one of the distinguishing features of the ESP-WROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, uses do not need to buy a JTAG debugger separately, which reduces the development cost, see `ESP-WROVER-KIT V2 schematic`_.
EN
Reset button: pressing this button resets the system.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
USB
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module.
Power Select
Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`esp-wrover-kit-v2-setup-options-cmake`, jumper header JP7.
Power Key
Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off.
5V Input
The 5V power supply interface is used as a backup power supply in case of full-load operation.
LDO
NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT V2 schematic`_.
Camera
Camera interface: a standard OV7670 camera module is supported.
RGB
Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM).
I/O
All the pins on the ESP32 module are led out to the pin headers on the ESPWROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Micro SD Card
Micro SD 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 Micro SD 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 :ref:`esp-wrover-kit-v2-setup-options-cmake`.
LCD
ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`esp-wrover-kit-v2-board-back-cmake`.
.. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png
:align: center
:alt: ESP-WROVER-KIT board layout - front
:figclass: align-center
ESP-WROVER-KIT board layout - front
.. _esp-wrover-kit-v2-board-back-cmake:
.. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png
:align: center
:alt: ESP-WROVER-KIT board layout - back
:figclass: align-center
ESP-WROVER-KIT board layout - back
.. _esp-wrover-kit-v2-setup-options-cmake:
Setup Options
^^^^^^^^^^^^^
There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below.
+--------+----------------------+-------------------------------------------------+
| Header | Jumper Setting | Description of Functionality |
+--------+----------------------+-------------------------------------------------+
| JP1 | |jp1-sd_io2| | Enable pull up for the Micro SD Card |
+--------+----------------------+-------------------------------------------------+
| JP1 | |jp1-both| | Assert GPIO2 low during each download |
| | | (by jumping it to GPIO0) |
+--------+----------------------+-------------------------------------------------+
| JP7 | |jp7-ext_5v| | Power ESP-WROVER-KIT board from an external |
| | | power supply |
+--------+----------------------+-------------------------------------------------+
| JP7 | |jp7-usb_5v| | Power ESP-WROVER-KIT board from an USB port |
+--------+----------------------+-------------------------------------------------+
| JP8 | |jp8| | Enable JTAG functionality |
+--------+----------------------+-------------------------------------------------+
| JP11 | |jp11-rx-tx| | Enable UART communication |
+--------+----------------------+-------------------------------------------------+
| JP14 | |jp14| | Enable RTS/CTS flow control for serial |
| | | communication |
+--------+----------------------+-------------------------------------------------+
.. _esp-wrover-kit-v2-start-development-cmake:
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Initial Setup
^^^^^^^^^^^^^
Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below.
+----------------------+----------------------+
| Power up | Enable UART |
| from USB port | communication |
+----------------------+----------------------+
| |jp7-usb_5v| | |jp11-rx-tx| |
+----------------------+----------------------+
Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
* :ref:`get-started-build-cmake` for an example application
* :ref:`get-started-flash-cmake` to run code on the ESP32
* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
Related Documents
-----------------
* `ESP-WROVER-KIT V2 schematic`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
* :doc:`../api-guides/jtag-debugging/index`
* :doc:`../hw-reference/index`
.. |jp1-sd_io2| image:: ../../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../../_static/wrover-jp8.png
.. |jp11-rx-tx| 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

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

@ -0,0 +1,413 @@
ESP-WROVER-KIT V3 Getting Started Guide (CMake)
===============================================
This user guide shows how to get started with ESP-WROVER-KIT V3 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`.
If you like to start using this board right now, go directly to section :ref:`get-started-esp-wrover-kit-start-development-cmake`.
What You Need
-------------
* 1 × :ref:`ESP-WROVER-KIT V3 board <get-started-esp-wrover-kit-board-front-cmake>`
* 1 x Micro USB 2.0 Cable, Type A to Micro B
* 1 × PC loaded with Windows, Linux or Mac OS
Overview
^^^^^^^^
The ESP-WROVER-KIT is a development board produced by `Espressif <https://espressif.com>`_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective.
.. note::
ESP-WROVER-KIT V3 integrates the ESP32-WROVER module by default.
Functionality Overview
^^^^^^^^^^^^^^^^^^^^^^
Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
.. figure:: ../../_static/esp32-wrover-kit-block-diagram.png
:align: center
:alt: ESP-WROVER-KIT block diagram
:figclass: align-center
ESP-WROVER-KIT block diagram
Functional Description
^^^^^^^^^^^^^^^^^^^^^^
The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board.
32.768 kHz
An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode.
0R
A zero Ohm resistor intended as a placeholder for a current shunt. May be desoldered or replaced with a current shunt to facilitate measurement of current required by ESP32 module depending on power mode.
ESP32 Module
ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities.
.. note::
GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out.
FT2232
The FT2232 chip is a multi-protocol USB-to-serial bridge. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32. The FT2232 chip also features USB-to-JTAG interface. USB-to-JTAG is available on channel A of FT2232, USB-to-serial on channel B. The embedded FT2232 chip is one of the distinguishing features of the ESPWROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, users do not need to buy a JTAG debugger separately, which reduces the development cost, see `ESP-WROVER-KIT V3 schematic`_.
UART
Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device.
SPI
SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. The electrical level on the flash of this module is 1.8V. If an ESP-WROOM-32 is being used, please note that the electrical level on the flash of this module is 3.3V.
CTS/RTS
Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers.
JTAG
JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals.
EN
Reset button: pressing this button resets the system.
Boot
Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
USB
USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module.
Power Select
Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`get-started-esp-wrover-kit-setup-options-cmake`, jumper header JP7.
Power Key
Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off.
5V Input
The 5V power supply interface is used as a backup power supply in case of full-load operation.
LDO
NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT V3 schematic`_.
Camera
Camera interface: a standard OV7670 camera module is supported.
RGB
Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM).
I/O
All the pins on the ESP32 module are led out to the pin headers on the ESP-WROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
Micro SD Card
Micro SD card slot for data storage.
LCD
ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-board-back-cmake`.
.. _get-started-esp-wrover-kit-board-front-cmake:
.. figure:: ../../_static/esp32-wrover-kit-layout-front.jpg
:align: center
:alt: ESP-WROVER-KIT board layout - front
:figclass: align-center
ESP-WROVER-KIT board layout - front
.. _get-started-esp-wrover-kit-board-back-cmake:
.. figure:: ../../_static/esp32-wrover-kit-layout-back.jpg
:align: center
:alt: ESP-WROVER-KIT board layout - back
:figclass: align-center
ESP-WROVER-KIT board layout - back
.. _get-started-esp-wrover-kit-setup-options-cmake:
Setup Options
^^^^^^^^^^^^^
There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below.
+--------+------------------+--------------------------------------------------+
| Header | Jumper Setting | Description of Functionality |
+--------+------------------+--------------------------------------------------+
| JP7 | |jp7-ext_5v| | Power ESP-WROVER-KIT board from an external |
| | | power supply |
+--------+------------------+--------------------------------------------------+
| JP7 | |jp7-usb_5v| | Power ESP-WROVER-KIT board from an USB port |
+--------+------------------+--------------------------------------------------+
| JP8 | |jp8| | Enable JTAG functionality |
+--------+------------------+--------------------------------------------------+
| JP11 | |jp11-rx-tx| | Enable UART communication |
+--------+------------------+--------------------------------------------------+
| JP14 | |jp14| | Enable RTS/CTS flow control for serial |
| | | communication |
+--------+------------------+--------------------------------------------------+
Allocation of ESP32 Pins
^^^^^^^^^^^^^^^^^^^^^^^^
Several pins / terminals of ESP32 module are allocated to the on board hardware. Some of them, like GPIO0 or GPIO2, have multiple functions. If certain hardware is not installed, e.g. nothing is plugged in to the Camera / JP4 header, then selected GPIOs may be used for other purposes.
Main I/O Connector / JP1
""""""""""""""""""""""""
The JP1 connector is shown in two columns in the middle under "I/O" headers. The two columns "Shared With" outside, describe where else on the board certain GPIO is used.
+----------------------+------+------+----------------------+
| Shared With | I/O | I/O | Shared With |
+======================+======+======+======================+
| | 3.3V | GND | |
+----------------------+------+------+----------------------+
| NC/XTAL | IO32 | IO33 | NC/XTAL |
+----------------------+------+------+----------------------+
| JTAG, MicroSD | IO12 | IO13 | JTAG, MicroSD |
+----------------------+------+------+----------------------+
| JTAG, MicroSD | IO14 | IO27 | Camera |
+----------------------+------+------+----------------------+
| Camera | IO26 | IO25 | Camera, LCD |
+----------------------+------+------+----------------------+
| Camera | IO35 | IO34 | Camera |
+----------------------+------+------+----------------------+
| Camera | IO39 | IO36 | Camera |
+----------------------+------+------+----------------------+
| JTAG | EN | IO23 | Camera, LCD |
+----------------------+------+------+----------------------+
| Camera, LCD | IO22 | IO21 | Camera, LCD, MicroSD |
+----------------------+------+------+----------------------+
| Camera, LCD | IO19 | IO18 | Camera, LCD |
+----------------------+------+------+----------------------+
| Camera, LCD | IO5 | IO17 | PSRAM |
+----------------------+------+------+----------------------+
| PSRAM | IO16 | IO4 | LED, Camera, MicroSD |
+----------------------+------+------+----------------------+
| LED, Boot | IO0 | IO2 | LED, Camera, MicroSD |
+----------------------+------+------+----------------------+
| JTAG, MicroSD | IO15 | 5V | |
+----------------------+------+------+----------------------+
Legend:
* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-xtal-cmake>`
* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-jtag-header-cmake>`
* Boot - Boot button / SW2
* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-camera-header-cmake>`
* LED - :ref:`RGB LED <get-started-esp-wrover-rgb-led-connections-cmake>`
* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-microsd-card-slot-cmake>`
* LCD - :ref:`LCD / U5 <get-started-esp-wrover-lcd-connector-cmake>`
* PSRAM - ESP32-WROVER's PSRAM, if ESP32-WROVER is installed
.. _get-started-esp-wrover-kit-xtal-cmake:
32.768 kHz Oscillator
"""""""""""""""""""""
+---+-----------+
| | ESP32 Pin |
+===+===========+
| 1 | GPIO32 |
+---+-----------+
| 2 | GPIO33 |
+---+-----------+
.. note::
As GPIO32 and GPIO33 are connected to the oscillator, to maintain signal integrity, they are not connected to JP1 I/O expansion connector. This allocation may be changed from oscillator to JP1 by desoldering 0R resistors from positions R11 / R23 and installing them in positions R12 / R24.
.. _get-started-esp-wrover-spi-flash-header-cmake:
SPI Flash / JP13
""""""""""""""""
+---+--------------+
| | ESP32 Pin |
+===+==============+
| 1 | CLK / GPIO6 |
+---+--------------+
| 2 | SD0 / GPIO7 |
+---+--------------+
| 3 | SD1 / GPIO8 |
+---+--------------+
| 4 | SD2 / GPIO9 |
+---+--------------+
| 5 | SD3 / GPIO10 |
+---+--------------+
| 6 | CMD / GPIO11 |
+---+--------------+
.. important::
The module's flash bus is connected to the pin header JP13 through 0-Ohm resistors R140 ~ R145. If the flash frequency needs to operate at 80 MHz, to improve integrity of the bus signals, it is recommended to desolder resistors R140 ~ R145. At this point, the module's flash bus is disconnected with the pin header JP13.
.. _get-started-esp-wrover-jtag-header-cmake:
JTAG / JP8
""""""""""
+---+---------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+===============+=============+
| 1 | EN | TRST_N |
+---+---------------+-------------+
| 2 | MTDO / GPIO15 | TDO |
+---+---------------+-------------+
| 3 | MTDI / GPIO12 | TDI |
+---+---------------+-------------+
| 4 | MTCK / GPIO13 | TCK |
+---+---------------+-------------+
| 5 | MTMS / GPIO14 | TMS |
+---+---------------+-------------+
.. _get-started-esp-wrover-camera-header-cmake:
Camera / JP4
""""""""""""
+----+--------------+----------------------+
| | ESP32 Pin | Camera Signal |
+====+==============+======================+
| 1 | GPIO27 | SCCB Clock |
+----+--------------+----------------------+
| 2 | GPIO26 | SCCB Data |
+----+--------------+----------------------+
| 3 | GPIO21 | System Clock |
+----+--------------+----------------------+
| 4 | GPIO25 | Vertical Sync |
+----+--------------+----------------------+
| 5 | GPIO23 | Horizontal Reference |
+----+--------------+----------------------+
| 6 | GPIO22 | Pixel Clock |
+----+--------------+----------------------+
| 7 | GPIO4 | Pixel Data Bit 0 |
+----+--------------+----------------------+
| 8 | GPIO5 | Pixel Data Bit 1 |
+----+--------------+----------------------+
| 9 | GPIO18 | Pixel Data Bit 2 |
+----+--------------+----------------------+
| 10 | GPIO19 | Pixel Data Bit 3 |
+----+--------------+----------------------+
| 11 | GPIO36 | Pixel Data Bit 4 |
+----+--------------+----------------------+
| 11 | GPIO39 | Pixel Data Bit 5 |
+----+--------------+----------------------+
| 11 | GPIO34 | Pixel Data Bit 6 |
+----+--------------+----------------------+
| 11 | GPIO35 | Pixel Data Bit 7 |
+----+--------------+----------------------+
| 11 | GPIO2 | Camera Reset |
+----+--------------+----------------------+
.. _get-started-esp-wrover-rgb-led-connections-cmake:
RGB LED
"""""""
+---+-----------+---------+
| | ESP32 Pin | RGB LED |
+===+===========+=========+
| 1 | GPIO0 | Red |
+---+-----------+---------+
| 2 | GPIO2 | Blue |
+---+-----------+---------+
| 3 | GPIO4 | Green |
+---+-----------+---------+
.. _get-started-esp-wrover-microsd-card-slot-cmake:
MicroSD Card / J4
"""""""""""""""""
+---+---------------+----------------+
| | ESP32 Pin | MicroSD Signal |
+===+===============+================+
| 1 | MTDI / GPIO12 | DATA2 |
+---+---------------+----------------+
| 2 | MTCK / GPIO13 | CD / DATA3 |
+---+---------------+----------------+
| 3 | MTDO / GPIO15 | CMD |
+---+---------------+----------------+
| 4 | MTMS / GPIO14 | CLK |
+---+---------------+----------------+
| 5 | GPIO2 | DATA0 |
+---+---------------+----------------+
| 6 | GPIO4 | DATA1 |
+---+---------------+----------------+
| 7 | GPIO21 | CD |
+---+---------------+----------------+
.. _get-started-esp-wrover-lcd-connector-cmake:
LCD / U5
""""""""
+---+-----------+------------+
| | ESP32 Pin | LCD Signal |
+===+===========+============+
| 1 | GPIO18 | RESET |
+---+-----------+------------+
| 2 | GPIO19 | SCL |
+---+-----------+------------+
| 3 | GPIO21 | D/C |
+---+-----------+------------+
| 4 | GPIO22 | CS |
+---+-----------+------------+
| 5 | GPIO23 | SDA |
+---+-----------+------------+
| 6 | GPIO25 | SDO |
+---+-----------+------------+
| 7 | GPIO5 | Backlight |
+---+-----------+------------+
.. _get-started-esp-wrover-kit-start-development-cmake:
Start Application Development
-----------------------------
Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
Initial Setup
^^^^^^^^^^^^^
Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below.
+----------------------+----------------------+
| Power up | Enable UART |
| from USB port | communication |
+----------------------+----------------------+
| |jp7-usb_5v| | |jp11-rx-tx| |
+----------------------+----------------------+
Do not install any other jumpers.
Now to Development
^^^^^^^^^^^^^^^^^^
To start development of applications for ESP-WROVER-KIT, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
* :ref:`get-started-build-cmake` for an example application
* :ref:`get-started-flash-cmake` to run code on the ESP32
* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
Related Documents
-----------------
* `ESP-WROVER-KIT V3 schematic`_ (PDF)
* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
* :doc:`../api-guides/jtag-debugging/index`
* :doc:`../hw-reference/index`
.. |jp7-ext_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-usb_5v.png
.. |jp8| image:: ../../_static/esp-wrover-kit-v3-jp8.png
.. |jp11-rx-tx| image:: ../../_static/esp-wrover-kit-v3-jp11-tx-rx.png
.. |jp14| image:: ../../_static/esp-wrover-kit-v3-jp14.png
.. _ESP-WROVER-KIT V3 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf
.. toctree::
:hidden:
get-started-wrover-kit-v2.rst

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

@ -0,0 +1,135 @@
*******************
IDF Monitor (CMake)
*******************
The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF.
It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features.
Interacting With IDF Monitor
============================
- ``Ctrl-]`` will exit the monitor.
- ``Ctrl-T Ctrl-H`` will display a help menu with all other keyboard shortcuts.
- Any other key apart from ``Ctrl-]`` and ``Ctrl-T`` is sent through the serial port.
Automatically Decoding Addresses
================================
Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, IDF Monitor will use addr2line_ to look up the source code location and function name.
.. highlight:: none
When an esp-idf app crashes and panics a register dump and backtrace such as this is produced::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
IDF Monitor will augment the dump::
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
Behind the scenes, the command IDF Monitor runs to decode each address is::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
Launch GDB for GDBStub
======================
By default, if an esp-idf app crashes then the panic handler prints registers and a stack dump as shown above, and then resets.
Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
Behind the scenes, the command IDF Monitor runs is::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
Quick Compile and Flash
=======================
The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed.
Quick Reset
===========
The keyboard shortcut ``Ctrl-T Ctrl-R`` will reset the target board via the RTS line (if it is connected.)
Pause the Application
=====================
The keyboard shortcut ``Ctrl-T Ctrl-P`` will reset the target into bootloader, so that the board will run nothing. This is
useful when you want to wait for another device to startup. Then shortcut ``Ctrl-T Ctrl-R`` can be used to restart the
application.
Toggle Output Display
=====================
Sometimes you may want to stop new output printed to screen, to see the log before. The keyboard shortcut ``Ctrl-T Ctrl-Y`` will
toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert
again quickly without quitting the monitor.
Simple Monitor
==============
Earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program.
This program can still be run, via ``make simple_monitor``.
IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts.
.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
Known Issues with IDF Monitor
=============================
Issues Observed on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~
- If you are using the supported Windows environment and receive the error "winpty: command not found" then run ``pacman -S winpty`` to fix.
- Arrow keys and some other special keys in gdb don't work, due to Windows Console limitations.
- Occasionally when "make" exits, it may stall for up to 30 seconds before idf_monitor resumes.
- Occasionally when "gdb" is run, it may stall for a short time before it begins communicating with the gdbstub.
.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html
.. _gdb: https://sourceware.org/gdb/download/onlinedocs/
.. _pySerial: https://github.com/pyserial/pyserial
.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm

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

@ -0,0 +1,464 @@
*******************
Get Started (CMake)
*******************
.. include:: ../cmake-warning.rst
.. include:: ../cmake-pending-features.rst
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
Introduction
============
ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
What You Need
=============
To develop applications for ESP32 you need:
* **PC** loaded with either Windows, Linux or Mac operating system
* **Toolchain** to compile code for ESP32
* **Build tools** CMake and Ninja to build a full **Application** for ESP32
* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
.. figure:: ../../_static/what-you-need-cmake.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
Development of applications for ESP32
Steps to set up Development Environment:
1. Setup of **Toolchain**
2. Getting **ESP-IDF** from GitHub
Once the development environment is set up, we will follow these steps to create an ESP-IDF application:
1. Configuration of a **Project** and writing the code
2. Compilation of the **Project** and linking it to build an **Application**
3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection
4. Monitoring / debugging of the **Application** output via USB/serial
Development Board Guides
========================
If you have one of ESP32 development boards listed below, click on the link for hardware setup:
.. toctree::
:maxdepth: 1
ESP32 DevKitC <get-started-devkitc>
ESP-WROVER-KIT <get-started-wrover-kit>
ESP32-PICO-KIT <get-started-pico-kit>
If you have different board, move to sections below.
.. _get-started-setup-toolchain-cmake:
Setup Toolchain
===============
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
.. toctree::
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started-cmake/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started-cmake/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started-cmake/macos-setup.html
.. _Windows: ../get-started-cmake/windows-setup.html
.. _Linux: ../get-started-cmake/linux-setup.html
.. _Mac OS: ../get-started-cmake/macos-setup.html
.. note::
We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and MacOS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup-cmake`.
Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf-cmake`.
.. _get-started-get-esp-idf-cmake:
Get ESP-IDF
===========
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command.
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
mkdir -p ~/esp
cd ~/esp
git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
mkdir %userprofile%\esp
cd %userprofile%\esp
git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
.. highlight:: bash
.. note::
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
cd esp-idf
git submodule update --init
.. note::
The CMake-based build system preview uses a different Git branch to the default. This branch is ``feature/cmake``. If you missed the ``--branch`` option when cloning then you can switch branches on the command line::
cd esp-idf
git checkout feature/cmake
.. _get-started-setup-path-cmake:
Setup Environment Variables
===========================
ESP-IDF requires two environment variables to be set for normal operation:
- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory.
- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory.
These two variables should be set up on your PC, otherwise projects will not build.
Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in section :doc:`add-idf_path-to-profile`.
.. _get-started-start-project-cmake:
Start a Project
===============
Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
Copy :example:`get-started/hello_world` to ``~/esp`` directory:
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
It is also possible to build examples in-place, without copying them first.
.. important::
The esp-idf build system does not support spaces in the path to either esp-idf or to projects.
.. _get-started-connect-cmake:
Connect
=======
You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
.. _get-started-configure-cmake:
Configure
=========
Naviagate to the directory of the ``hello_world`` application copy, and run the ``menuconfig`` project configuration utility:
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
idf.py menuconfig
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
idf.py menuconfig
.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path-cmake`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf-cmake`.
.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work (it opens the file in Visual Studio instead). You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead.
If previous steps have been done correctly, the following menu will be displayed:
.. figure:: ../../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center
Project configuration - Home window
Here are couple of tips on navigation and use of ``menuconfig``:
* Use up & down arrow keys to navigate the menu.
* Use Enter key to go into a submenu, Escape key to go up a level or exit.
* Type ``?`` to see a help screen. Enter key exits the help screen.
* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
* Pressing ``?`` while highlighting a configuration item displays help about that item.
* Type ``/`` to search the configuration items.
.. _get-started-build-cmake:
Build The Project
=================
.. highlight:: bash
Now you can build the project. Run::
idf.py build
This command will compile the application and all the ESP-IDF components, generate 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:
Flash To A Device
=================
Now you can flash the application to the ESP32 board. Run::
idf.py -p PORT flash
Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. See :doc:`establish-serial-connection` for full details.
This step will flash the binaries that you just built to your ESP32 board.
.. note:: Running ``idf.py build`` before ``idf.py flash`` is not actually necessary, the flash step will automatically build the project if required before flashing.
.. 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, at the end of flash process, the module will be reset and “hello_world” application will be running there.
.. (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:
Monitor
=======
To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
$ 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
...
Several lines below, after start up and diagnostic log, 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 the monitor use shortcut ``Ctrl+]``.
.. note::
If instead of the messages above, you see a random garbage similar to::
e<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure-cmake>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-flash-cmake>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
.. note::
You can combine building, flashing and monitoring into one step as follows::
idf.py -p PORT flash monitor
Check the section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using the monitor.
Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
That's all what you need to get started with ESP32!
Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
Updating ESP-IDF
================
After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf-cmake`.
Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands:
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/esp-idf
git pull
git submodule update --init --recursive
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\esp-idf
git pull
git submodule update --init --recursive
The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
.. highlight:: bash
It is also possible to check out a specific release of ESP-IDF, e.g. `v2.1`.
Linux and MacOS
~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
cd esp-idf-v2.1/
git checkout v2.1
git submodule update --init --recursive
Windows Command Prompt
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
cd esp-idf-v2.1/
git checkout v2.1
git submodule update --init --recursive
After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
.. note::
Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to.
Related Documents
=================
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
eclipse-setup
idf-monitor
toolchain-setup-scratch

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

@ -0,0 +1,73 @@
******************************************
Setup Linux Toolchain from Scratch (CMake)
******************************************
.. 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 cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial 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::
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
Download ``crosstool-NG`` and build it::
cd ~/esp
git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
cd crosstool-NG
./bootstrap && ./configure --enable-local && make install
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-cmake>` 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-cmake`.

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

@ -0,0 +1,112 @@
*********************************************
Standard Setup of Toolchain for Linux (CMake)
*********************************************
.. 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 cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial 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".
Toolchain Setup
===============
ESP32 toolchain for Linux is available for download from Espressif website:
- for 64-bit Linux:
https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
- for 32-bit Linux:
https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
1. Download this file, then extract it in ``~/esp`` directory::
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
.. _setup-linux-toolchain-add-it-to-path-cmake:
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="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
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="$PATH:$HOME/esp/xtensa-esp32-elf/bin"'
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.
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 end of displayed string::
$ printenv PATH
/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:/home/user-name/esp/xtensa-esp32-elf/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-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 section :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

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

@ -0,0 +1,83 @@
***********************************************
Setup Toolchain for Mac OS from Scratch (CMake)
***********************************************
.. 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
Install Prerequisites
=====================
- install pip::
sudo easy_install pip
- install pyserial::
sudo pip install 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::
cd ~/esp
ln -s /Volumes/ctng crosstool-NG
Download ``crosstool-NG`` and build it::
cd ~/esp
git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
cd crosstool-NG
./bootstrap && ./configure --enable-local && make install
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-macos-toolchain-add-it-to-path-cmake>` 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-cmake`.

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

@ -0,0 +1,90 @@
**********************************************
Standard Setup of Toolchain for Mac OS (CMake)
**********************************************
.. include:: ../cmake-warning.rst
Install Prerequisites
=====================
ESP-IDF will use the version of Python installed by default on Mac OS.
- install pip::
sudo easy_install pip
- install pyserial::
sudo pip install 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 Mac OS 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``.
Toolchain Setup
===============
ESP32 toolchain for macOS is available for download from Espressif website:
https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
Download this file, then extract it in ``~/esp`` directory::
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
.. _setup-macos-toolchain-add-it-to-path-cmake:
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=$PATH:$HOME/esp/xtensa-esp32-elf/bin
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=$PATH:$HOME/esp/xtensa-esp32-elf/bin"
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
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
Next Steps
==========
To carry on with development environment setup, proceed to section :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

25
docs/en/get-started-cmake/toolchain-setup-scratch.rst Normal file
View file

@ -0,0 +1,25 @@
.. _get-started-customized-setup-cmake:
*************************************
Customized Setup of Toolchain (CMake)
*************************************
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain-cmake`) 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:
- if you want to customize toolchain build configuration
- if you want to use a different GCC version (such as 4.8.5)
- if you want to hack gcc or newlib or libstdc++
- if you are curious and/or have time to spare
- if you don't trust binaries downloaded from the Internet
In any case, here are the instructions to compile the toolchain yourself.
.. toctree::
:maxdepth: 1
windows-setup-scratch
linux-setup-scratch
macos-setup-scratch

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

@ -0,0 +1,89 @@
********************************************
Setup Windows Toolchain from Scratch (CMake)
********************************************
.. 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.
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 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
===============
Download the precompiled Windows toolchain from dl.espressif.com:
https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
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 section :ref:`get-started-get-esp-idf-cmake`.
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _MSYS2: https://msys2.github.io/

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

@ -0,0 +1,71 @@
***********************************************
Standard Setup of Toolchain for Windows (CMake)
***********************************************
.. 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 Git, a cross-compiler and the CMake build tool. We'll go over each one in this document.
For this Getting Started we're going to use a 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.
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-1.1.exe
The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
Installing Git
==============
The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_.
If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client.
Using a Terminal
================
For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use:
- You can use the built-in Windows Command Prompt, under the Start menu. All Windows command line instructions in this documentation are "batch" commands for use with the Windows Command Prompt.
- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as is given for Mac OS or Linux. You can find it in the Start menu once installed.
- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
Related Documents
=================
For advanced users who want to customize the install process:
.. toctree::
:maxdepth: 1
windows-setup-scratch
.. _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/

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

@ -1,40 +1,40 @@
Add IDF_PATH & idf.py PATH to User Profile
==========================================
Add IDF_PATH to User Profile
============================
:link_to_translation:`zh_CN:[中文]`
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
.. _add-paths-to-profile-windows:
.. _add-idf_path-to-profile-windows:
Windows
-------
To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
#. 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``
- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``.
- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
#. Add the ``export`` command to the script file, e.g.::
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`.
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:
@ -42,20 +42,15 @@ If you got here from section :ref:`get-started-setup-path`, while installing s/w
Linux and MacOS
---------------
Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to your ``~/.profile`` file::
Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
export IDF_PATH=~/esp/esp-idf
export PATH="$PATH:$IDF_PATH/tools"
Log off and log in back to make this change effective.
.. note::
``~/.profile`` means a file named ``.profile`` in your user's home directory (which is abbreviated ``~`` in the shell).
Log off and log in back to make this change effective.
.. note::
Not all shells use ``.profile``. If you have ``/bin/bash`` and ``.bash_profile`` exists then update this file instead. For ``zsh``, update ``.zprofile``. Other shells may use other profile files (consult the shell's documentation).
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::
@ -63,15 +58,8 @@ Run the following command to check if ``IDF_PATH`` is set::
The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
To verify idf.py is now on the ``PATH``, you can run the following::
which idf.py
A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
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
export PATH="$PATH:$IDF_PATH/tools"
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`.

79
docs/en/get-started/eclipse-setup-windows.rst Normal file
View file

@ -0,0 +1,79 @@
**********************
Eclipse IDE on Windows
**********************
:link_to_translation:`zh_CN:[中文]`
Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.
(For OS X and Linux instructions, see the :doc:`Eclipse IDE page <eclipse-setup>`.)
Installing Eclipse IDE
======================
Follow the steps under :ref:`Installing Eclipse IDE <eclipse-install-steps>` for all platforms.
.. _eclipse-windows-setup:
Setting up Eclipse on Windows
=============================
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" uncheck "Show only available toolchains that support this platform".
* On the extended list that appears, choose "Cygwin GCC". Then click Finish.
*Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we're going to reconfigure Eclipse to find our toolchain.*
Project Properties
------------------
* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
* Click on the "C/C++ Build" properties page (top-level):
* Uncheck "Use default build command" and enter this for the custom build command: ``python ${IDF_PATH}/tools/windows/eclipse_make.py``.
* 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. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/user-name/Development/esp-idf*.
* Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match).
* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page:
* Click the "Providers" tab
* In the list of providers, click "CDT GCC Built-in Compiler Settings Cygwin". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern, and wrap remaining part with brackets. This means the full Compiler command pattern should be ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``
Building in Eclipse
-------------------
Continue from :ref:`Building in Eclipse <eclipse-build-project>` for all platforms.
Technical Details
=================
**Of interest to Windows gurus or very curious parties, only.**
Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support:
* The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility.
* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse.

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

@ -3,10 +3,108 @@ Build and Flash with Eclipse IDE
********************************
:link_to_translation:`zh_CN:[中文]`
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
.. _eclipse-install-steps:
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.)
Windows Users
=============
Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide <eclipse-windows-setup>`.
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.
* 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.
* 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.
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". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``
.. _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.
Related Documents
-----------------
.. toctree::
:maxdepth: 1
eclipse-setup-windows
Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon.
.. _eclipse.org: https://www.eclipse.org/

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

@ -55,8 +55,6 @@ 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:
Adding user to ``dialout`` on Linux
@ -128,4 +126,5 @@ If you see some legible log, it means serial connection is working and you are r
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`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

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

@ -3,7 +3,7 @@ IDF Monitor
***********
:link_to_translation:`zh_CN:[中文]`
The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF.
The IDF Monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF.
It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features.
@ -67,7 +67,7 @@ By default, if an esp-idf app crashes then the panic handler prints registers an
Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
@ -79,9 +79,9 @@ Behind the scenes, the command IDF Monitor runs is::
Quick Compile and Flash
=======================
The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause IDF Monitor, run the ``make flash`` target, then resume IDF Monitor. Any changed source files will be recompiled before re-flashing.
The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed.
The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause IDF Monitor, run the ``make app-flash`` target, then resume IDF Monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed.
Quick Reset
@ -115,7 +115,6 @@ This program can still be run, via ``make simple_monitor``.
IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts.
.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
Known Issues with IDF Monitor
=============================

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

@ -3,10 +3,7 @@ Get Started
***********
:link_to_translation:`zh_CN:[中文]`
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
.. note::
The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
Introduction
@ -23,8 +20,7 @@ What You Need
To develop applications for ESP32 you need:
* **PC** loaded with either Windows, Linux or Mac operating system
* **Toolchain** to compile code for ESP32
* **Build tools** CMake and Ninja to build a full **Application** for ESP32
* **Toolchain** to build the **Application** for ESP32
* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
@ -36,23 +32,28 @@ To develop applications for ESP32 you need:
Development of applications for ESP32
Development Environment Steps:
Preparation of development environment consists of three steps:
1. Setup of **Toolchain**
2. Getting **ESP-IDF** from GitHub
2. Getting of **ESP-IDF** from GitHub
3. Installation and configuration of **Eclipse**
Once the development environment is set up, we will follow these steps to create an ESP-IDF application:
You may skip the last step, if you prefer to use different editor.
Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
1. Configuration of a **Project** and writing the code
2. Compilation of the **Project** and linking it to build an **Application**
3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection
4. Monitoring / debugging of the **Application** output via USB/serial
3. Flashing (uploading) of the **Application** to **ESP32**
4. Monitoring / debugging of the **Application**
See instructions below that will walk you through these steps.
Development Board Guides
========================
Guides
======
If you have one of ESP32 development boards listed below, click on the link for hardware setup:
If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
.. toctree::
:maxdepth: 1
@ -99,12 +100,13 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
.. note::
We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and Mac OS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands.
We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
.. _get-started-get-esp-idf:
Get ESP-IDF
@ -114,48 +116,26 @@ Get ESP-IDF
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
.. highlight:: batch
For **Windows Command Prompt** users, the equivalent commands are::
mkdir %userprofile%\esp
cd %userprofile%\esp
git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
.. highlight:: bash
.. note::
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
cd esp-idf
cd ~/esp/esp-idf
git submodule update --init
.. note::
The CMake-based build system preview uses a different Git branch to the default. This branch is ``feature/cmake``. If you missed the ``--branch`` option when cloning then you can switch branches on the command line::
cd esp-idf
git checkout feature/cmake
.. _get-started-setup-path:
Setup Environment Variables
===========================
Setup Path to ESP-IDF
=====================
ESP-IDF requires two environment variables to be set for normal operation:
The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory.
- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory.
These two variables should be set up on your PC, otherwise projects will not build.
Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
.. _get-started-start-project:
@ -164,27 +144,16 @@ Start a Project
Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
.. highlight:: bash
Copy :example:`get-started/hello_world` to ``~/esp`` directory::
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
.. highlight:: batch
For **Windows Command Prompt** users, the equivalent commands are::
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
It is also possible to build examples in-place, without copying them first.
.. important::
The esp-idf build system does not support spaces in the path to either esp-idf or to projects.
The esp-idf build system does not support spaces in paths to esp-idf or to projects.
.. _get-started-connect:
@ -194,32 +163,18 @@ Connect
You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
.. _get-started-configure:
Configure
=========
.. highlight:: bash
Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
cd ~/esp/hello_world
idf.py menuconfig
make menuconfig
.. highlight:: batch
For **Windows Command Prompt** users::
cd %userprofile%\esp\hello_world
idf.py menuconfig
.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf`.
.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work. You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead.
If previous steps have been done correctly, the following menu will be displayed:
If previous steps have been done correctly, the following menu will be displayed:
.. figure:: ../../_static/project-configuration.png
:align: center
@ -228,10 +183,17 @@ If previous steps have been done correctly, the following menu will be displayed
Project configuration - Home window
In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
.. note::
On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
(See :doc:`establish-serial-connection` for full details.)
Here are couple of tips on navigation and use of ``menuconfig``:
* Use up & down arrow keys to navigate the menu.
* Use Enter key to go into a submenu, Escape key to go up a level or exit.
* Use Enter key to go into a submenu, Escape key to go out or to exit.
* Type ``?`` to see a help screen. Enter key exits the help screen.
* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
* Pressing ``?`` while highlighting a configuration item displays help about that item.
@ -241,91 +203,51 @@ Here are couple of tips on navigation and use of ``menuconfig``:
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
.. _get-started-build-flash:
Build The Project and Flash
===========================
Build and Flash
===============
.. highlight:: bash
Now you can build and flash the application. Run::
Now you can build the project. Run::
make flash
idf.py build
This command will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
.. 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 flash'
If there are no errors, the build will finish by generating the firmware binary .bin file.
Flash To A Device
=================
Now you can flash the application to the ESP32 board. Run::
idf.py -p PORT flash
Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. (See :doc:`establish-serial-connection` for full details.)
This step will flash the binaries that you just built to your ESP32 board.
.. note:: Running ``idf.py build`` before ``idf.py flash`` is not actually necessary, the flash step will automatically build the project if required before flashing.
This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
.. highlight:: none
::
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.
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 via RTS pin...
Leaving...
Hard resetting...
If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there.
If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
.. (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:
@ -333,11 +255,10 @@ If there are no issues, at the end of build process, you should see messages des
Monitor
=======
To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor <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"...
$ 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
@ -356,7 +277,7 @@ Several lines below, after start up and diagnostic log, you should see "Hello wo
Restarting in 8 seconds...
Restarting in 7 seconds...
To exit the monitor use shortcut ``Ctrl+]``.
To exit the monitor use shortcut ``Ctrl+]``.
.. note::
@ -365,19 +286,11 @@ To exit the monitor use shortcut ``Ctrl+]``.
e<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
.. note::
To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
You can combine building, flashing and monitoring into one step as follows::
idf.py -p PORT flash monitor
Check the section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using the monitor.
Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
That's all what you need to get started with ESP32!
That's all what you need to get started with ESP32!
Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
@ -387,27 +300,15 @@ Updating ESP-IDF
After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
.. highlight:: bash
Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands::
cd ~/esp/esp-idf
git pull
git submodule update --init --recursive
.. highlight:: batch
For **Windows Command Prompt** users::
cd %userprofile%\esp\esp-idf
git pull
git submodule update --init --recursive
The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
.. highlight:: bash
To use a specific release of ESP-IDF, e.g. `v2.1`, run::
If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
cd ~/esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
@ -415,22 +316,8 @@ To use a specific release of ESP-IDF, e.g. `v2.1`, run::
git checkout v2.1
git submodule update --init --recursive
.. highlight:: batch
For **Windows Command Prompt** users::
cd %userprofile%\esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
cd esp-idf-v2.1/
git checkout v2.1
git submodule update --init --recursive
After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
.. note::
Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to.
Related Documents
=================

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

@ -2,9 +2,6 @@
Setup Linux Toolchain from Scratch
**********************************
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
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`.
@ -13,20 +10,14 @@ 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 cmake ninja-build ccache
- Ubuntu and Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
.. note::
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
Compile the Toolchain from Source
=================================
@ -35,19 +26,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 make
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 make
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
- Ubuntu 16.04::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
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 make
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Arch::

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

@ -3,9 +3,6 @@ Standard Setup of Toolchain for Linux
*************************************
:link_to_translation:`zh_CN:[中文]`
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
Install Prerequisites
=====================
@ -13,18 +10,16 @@ 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 cmake ninja-build ccache
sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial
- Ubuntu and Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-serial
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
.. note::
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
Toolchain Setup
===============
@ -84,7 +79,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:

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

@ -2,16 +2,6 @@
Setup Toolchain for Mac OS from Scratch
***************************************
Package Manager
===============
To set up the toolchain from scratch, rather than `downloading a precocmpiled 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
Install Prerequisites
=====================
@ -23,28 +13,24 @@ Install Prerequisites
sudo pip install 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 make
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 make
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
Create a case-sensitive filesystem image::

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

@ -3,14 +3,9 @@ Standard Setup of Toolchain for Mac OS
**************************************
:link_to_translation:`zh_CN:[中文]`
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
Install Prerequisites
=====================
ESP-IDF will use the version of Python installed by default on Mac OS.
- install pip::
sudo easy_install pip
@ -19,26 +14,6 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
sudo pip install 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 Mac OS 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``.
Toolchain Setup
===============
@ -73,6 +48,7 @@ Next Steps
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
Related Documents
=================
@ -80,9 +56,3 @@ 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

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

@ -2,81 +2,91 @@
Setup Windows Toolchain from Scratch
************************************
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.
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 and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
.. note::
Unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer.
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).
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
Python 2.x
^^^^^^^^^^
.. _configure-windows-toolchain-from-scratch:
Download the latest Python_ 2.7 for Windows installer, and run it.
Configure Toolchain & Environment from Scratch
==============================================
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".
This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
* 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``.
pip install pyserial
* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
MConf for IDF
^^^^^^^^^^^^^
* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
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.
*(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.)*
This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
* 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.
Toolchain Setup
===============
* 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.
Download the precompiled Windows toolchain from dl.espressif.com:
* 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
============================================
If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
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.
If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
.. _add-directory-windows-path:
.. important::
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>``.
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
@ -84,5 +94,22 @@ Next Steps
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _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.
.. _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

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

@ -3,61 +3,64 @@ Standard Setup of Toolchain for Windows
***************************************
:link_to_translation:`zh_CN:[中文]`
.. note::
This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
.. 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 Git, a cross-compiler and the CMake build tool. We'll go over each one in this document.
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.
For this Getting Started we're going to use a command prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
.. note::
Previous versions of ESP-IDF used a GNU Make based build system, which required the MSYS2_ Unix compatibility environment on Windows. This is no longer required.
Toolchain Setup
===============
ESP-IDF Tools Installer
=======================
The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
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/esp32_win32_msys2_environment_and_toolchain-20180110.zip
https://dl.espressif.com/dl/esp-idf-tools-setup-1.1.exe
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 installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
Check it Out
============
Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
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::
Installing Git
==============
mkdir -p ~/esp
The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_.
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.
If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client.
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
Using a Terminal
================
MSYS2 MINGW32 shell window
For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use:
Use this window in the following steps setting up development environment for ESP32.
- You can use the built-in Windows Command Prompt, under the Start menu. Note that command line instructions in this documentation give "bash" commands for Mac OS or Linux first. The Windows Command Prompt equivalent is given afterwards.
- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as Mac OS or Linux. You can find it in the Start menu once installed.
- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal.
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.
Related Documents
=================
For advanced users who want to customize the install process:
.. toctree::
:maxdepth: 1
@ -65,9 +68,3 @@ For advanced users who want to customize the install process:
.. _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/

4
docs/en/index.rst
View file

@ -4,9 +4,6 @@ ESP-IDF Programming Guide
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
.. note::
This is documentation for the the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
The documentation has different language versions (:link_to_translation:`en:English`, :link_to_translation:`zh_CN:中文版`, :doc:`How to switch between languages? <languages>`). However, please refer to the English version if there is any discrepancy.
================== ================== ==================
@ -43,6 +40,7 @@ The documentation has different language versions (:link_to_translation:`en:Engl
: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>

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

@ -0,0 +1 @@
.. include:: ../../en/api-guides/build-system-cmake.rst

1
docs/zh_CN/api-guides/gnu-make-build-system.rst
View file

@ -1 +0,0 @@
.. include:: ../../en/api-guides/gnu-make-build-system.rst

1
docs/zh_CN/cmake-pending-features.rst Normal file
View file

@ -0,0 +1 @@
.. include:: /../en/cmake-pending-features.rst

1
docs/zh_CN/cmake-warning.rst Normal file
View file

@ -0,0 +1 @@
.. include:: /../en/cmake-warning.rst

1
docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/add-idf_path-to-profile.rst

1
docs/zh_CN/get-started-cmake/eclipse-setup.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/eclipse-setup.rst

1
docs/zh_CN/get-started-cmake/establish-serial-connection.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/establish-serial-connection.rst

1
docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/get-started-devkitc-v2.rst

1
docs/zh_CN/get-started-cmake/get-started-devkitc.rst Normal file
View file

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

1
docs/zh_CN/get-started-cmake/get-started-pico-kit-v3.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/get-started-pico-kit-v3.rst

1
docs/zh_CN/get-started-cmake/get-started-pico-kit.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/get-started-pico-kit.rst

1
docs/zh_CN/get-started-cmake/get-started-wrover-kit-v2.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/get-started-wrover-kit-v2.rst

1
docs/zh_CN/get-started-cmake/get-started-wrover-kit.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/get-started-wrover-kit.rst

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

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

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

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

1
docs/zh_CN/get-started-cmake/linux-setup-scratch.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/linux-setup-scratch.rst

1
docs/zh_CN/get-started-cmake/linux-setup.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/linux-setup.rst

1
docs/zh_CN/get-started-cmake/macos-setup-scratch.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/macos-setup-scratch.rst

1
docs/zh_CN/get-started-cmake/macos-setup.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/macos-setup.rst

1
docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/toolchain-setup-scratch.rst

1
docs/zh_CN/get-started-cmake/windows-setup-scratch.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/windows-setup-scratch.rst

1
docs/zh_CN/get-started-cmake/windows-setup.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../en/get-started-cmake/windows-setup.rst

82
docs/zh_CN/get-started/eclipse-setup-windows.rst Normal file
View file

@ -0,0 +1,82 @@
*****************************************************
Eclipse IDE 的创建和烧录指南（Windows 平台）
*****************************************************
:link_to_translation:`en:[English]`
Windows 平台上的 Eclipse 配置略有不同，具体步骤请见下文。
注意：OS X 和 Linux 平台上的 Eclipse IDE 配置，请见 :doc:`Eclipse IDE page <eclipse-setup>`。
安装 Eclipse IDE
==================
Windows 平台的 Eclipse 安装步骤与其他平台相同，请见 :ref:`Installing Eclipse IDE <eclipse-install-steps>`。
.. _eclipse-windows-setup:
Windows 平台上的 Eclipse 配置
================================
完成 Eclipse IDE 的安装后，请按照下列步骤继续操作：
导入新项目
-------------
* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。
* 运行 Eclipse，选择 “File” -> “Import...”。
* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。
* 下个界面，在 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应填入 ESP-IDF 项目的路径，而非 ESP-IDF 的路径（稍后再填写）。此外，您指定的目录中应包含名为 “Makefile”（项目 Makefile）的文件。
* 在同一页面上，在 “Toolchain for Indexer Settings” 下取消选中 “Show only available toolchains that support this platform”。
* 在出现的扩展列表中，选择 “Cygwin GCC”。然后点击 “Finish”。
*注意：您可能看到有关“无法找到 Cygwin GCC 工具链”的警告。这种情况并不影响安装，我们只需重新配置 Eclipse，并找到我们的工具链即可。*
项目属性
----------
* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择顶层 “Properties”。
* 点击 “C/C++ Build” 属性页。
* 取消选中 “Use default build command”，然后输入命令：``python${IDF_PATH}/tools/windows/eclipse_make.py``，开始自定义创建。
* 点击 “C/C++ Build” 下的 “Environment” 属性页面。
* 选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。
* 再次点击 “Add...”，输入名称 ``IDF_PATH``，并填写 ESP-IDF 的完整安装路径。``IDF_PATH`` 目录路径应使用正斜杠，而非反斜线，即 ``C:/Users/user-name/Development/esp-idf``。
* 选择 PATH 环境变量，删除默认值，并将其替换为 ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` （如果您已经将 msys32 安装到其他目​​录，这里请自行调整）。
* 点击 “C/C++ General” -> “Preprocessor Include Paths, Macros, etc.” 属性页。
* 点击 “Providers” 选项卡。
* 从 “Providers” 列表中选择 “CDT GCC Built-in Compiler Settings Cygwin”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终完整的 ``Command to get compiler specs`` 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。
* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 Compiler 命令模式的起始位置输入 ``xtensa-esp32-elf-``，并用括号把剩余部分扩起来。最终的完整 Compiler 命令模式应为 ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``。
在 Eclipse IDE 中创建项目
---------------------------
Windows 平台的 Eclipse 项目创建步骤与其他平台相同，请见 :ref:`Building in Eclipse <eclipse-build-project>`。
技术细节
=========
**以下内容仅供 Windows 平台专家或非常感兴趣的开发者阅读。**
Windows 平台的 Eclipse 介绍到此结束，下方将主要将介绍一些关键步骤的原理，助您了解更多 Eclipse 的背景信息。
* 首先，xtensa-esp32-elf-gcc 交叉编译器 *并非* Cygwin 工具链，但我们会在 Eclipse 中指定其为 Cygwin 工具链。主要原因在于：msys2 需要使用 Cygwin，并支持 Unix 风格的路径，即 ``/c/blah``，而非 ``c:/blah`` 或 ``c:\\blah``。特别需要说明的是，``xtensa-esp32-elf-gcc`` 会“告知” Eclipse 的 ``built-in compiler settings`` 功能，其内置 “include” 目录全部位于 ``/usr/`` 路径下，这也是 Eclipse 唯一可以解析的 ``Unix/Cygwin`` 风格路径。通过在 Eclipse 中指定 ``xtensa-esp32-elf-gcc`` 交叉编译器为 Cygwin 编译器，可以让 Eclipse 使用 cygpath 实用程序直接内部解析路径。
* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果，查找头文件目录，但是无法脱离 ``cygpath``，直接解析类似 ``/c/blah`` 的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 ``cygpath``，但由于未知原因，目前 ESP-IDF 配置并不会触发该功能。出于这个原因，我们会使用 ``eclipse_make.py`` 包装脚本调用 ``make``，然后使用 ``cygpath`` 处理 Eclipse 的结果。

103
docs/zh_CN/get-started/eclipse-setup.rst
View file

@ -3,6 +3,107 @@ Eclipse IDE 的创建和烧录指南
****************************
:link_to_translation:`en:[English]`
.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
.. _eclipse-install-steps:
安装 Eclipse IDE
================
Eclipse IDE 是一个可视化的集成开发环境，可用于编写、编译和调试 ESP-IDF 项目。
* 首先，请在您的平台上安装相应的 ESP-IDF，具体步骤请参考适用于 Windows、OS X 和 Linux 的相应安装步骤。
* 我们建议，您应首先使用命令行创建一个项目，大致熟悉项目的创建流程。此外，您还需要使用命令行 (``make menuconfig``) 对您的 ESP-IDF 项目进行配置。目前，Eclipse 尚不支持对 ESP-IDF 项目进行配置。
* 下载相应版本的 Eclipse Installer 至您的平台，点击 eclipse.org_。
* 运行 Eclipse Installer，选择 “Eclipse for C/C++ Development”（有的版本也可能显示为 CDT）。
Windows 用户
============
在 Windows 平台上使用 Eclipse IDE 的用户，请参考 :ref:`Windows 用户的 Eclipse IDE 使用指南 <eclipse-windows-setup>`。
配置 Eclipse IDE
=================
请打开安装好的 Eclipse IDE，并按照以下步骤进行操作：
导入新项目
----------
* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。
* 运行 Eclipse，选择 “File” -> “Import...”。
* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。
* 在下个界面中 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应输入 ESP-IDF 项目的路径，而非 ESP-IDF 本身的路径（这个稍后再填）。此外，您指定的目标路径中应包含名为 ``Makefile`` （项目 Makefile）的文件。
* 在本界面，找到 “Toolchain for Indexer Settings”，选择 “Cross GCC”，最后点击 “Finish”。
项目属性
--------
* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择 “Properties”。
* 点击 “C/C++ Build” 下的 “Environment” 属性页，选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。
* 再次点击 “Add...”，并在 “IDF_PATH” 中输入 ESP-IDF 所在的完整安装路径。
* 选择 “PATH” 环境变量，不要改变默认值。如果 Xtensa 工具链的路径尚不在 “PATH” 列表中，则应将该路径 (``something/xtensa-esp32-elf/bin``) 增加至列表。
* 在 macOS 平台上，增加一个 “PYTHONPATH” 环境变量，并将其设置为 ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``， 保证系统中预先安装的 Python （需安装 pyserial 模块）可以覆盖 Eclipse 内置的任何 Python。
* 前往 “C/C++ General” -> “Preprocessor Include Paths” 属性页面。
* 点击 “Providers” 选项卡。从 “Providers” 列表中选择 “CDT Cross GCC Built-in Compiler Settings”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终的完整 “Command to get compiler specs” 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。
* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 “Compiler command pattern“ 输入框的起始位置输入 ``xtensa-esp32-elf-``，最终的完整编译器命令应为 ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``。
.. _eclipse-build-project:
在 Eclipse IDE 中创建项目
--------------------------
在首次创建项目前，Eclipse IDE 可能会显示大量有关未定义值的错误和警告，主要原因在于项目编译过程中所需的一些源文件是在 ESP-IDF 项目创建过程中自动生成的。因此，这些错误和警告将在 ESP-IDF 项目生成完成后消失。
* 点击 “OK”，关闭 Eclipse IDE 中的 “Properties” 对话框。
* 在 Eclipse IDE 界面外，打开命令管理器。进入项目目录，并通过 ``make menuconfig`` 命令对您的 ESP-IDF 项目进行配置。现阶段，您还无法在 Eclipse 中完成本操作。
*如果您未进行最开始的配置步骤，ESP-IDF 将提示在命令行中进行配置 - 但由于 Eclipse 暂时不支持相关功能，因此该项目将挂起或创建失败。*
* 返回 Eclipse IDE 界面中，选择 “Project” -> “Build” 创建您的项目。
**提示**：如果您已经在 Eclipse IDE 环境外创建了项目，则可能需要选择 “Project” -> “Clean before choosing Project” -> “Build”，允许 Eclipse 查看所有源文件的编译器参数，并借此确定头文件包含路径。
在 Eclipse IDE 中烧录项目
--------------------------
您可以将 ``make flash`` 目标放在 Eclipse 项目中，通过 Eclipse UI 调用 ``esptool.py`` 进行烧录：
* 打开 “Project Explorer”，并右击您的项目（请注意右击项目本身，而非项目下的子文件，否则 Eclipse 可能会找到错误的 ``Makefile``）。
* 从菜单中选择 “Make Targets” -> “Create”。
* 输入 “flash” 为目标名称，其他选项使用默认值。
* 选择 “Project” -> “Make Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。
注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。
如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。
相关文档
--------
.. toctree::
:maxdepth: 1
eclipse-setup-windows
.. _eclipse.org: https://www.eclipse.org/

1
docs/zh_CN/index.rst
View file

@ -40,6 +40,7 @@ ESP-IDF 编程指南
:hidden:
快速入门 <get-started/index>
快速入门 (CMake 预览版本) <get-started-cmake/index>
API 参考 <api-reference/index>
H/W 参考 <hw-reference/index>
API 指南 <api-guides/index>

4
tools/cmake/project.cmake
View file

@ -59,8 +59,10 @@ macro(project name)
-D "DEPENDENCIES_FILE=${CMAKE_BINARY_DIR}/component_depends.cmake"
-D "COMPONENT_DIRS=${COMPONENT_DIRS}"
-D "BOOTLOADER_BUILD=${BOOTLOADER_BUILD}"
-D "IDF_PATH=${IDF_PATH}"
-D "DEBUG=${DEBUG}"
-P "${IDF_PATH}/tools/cmake/scripts/expand_requirements.cmake"
WORKING_DIRECTORY "${IDF_PATH}/tools/cmake")
WORKING_DIRECTORY "${PROJECT_PATH}")
include("${CMAKE_BINARY_DIR}/component_depends.cmake")
# We now have the following component-related variables:

12
tools/cmake/scripts/expand_requirements.cmake
View file

@ -15,7 +15,7 @@
#
# TODO: Error out if a component requirement is missing
cmake_minimum_required(VERSION 3.5)
include("utilities.cmake")
include("${IDF_PATH}/tools/cmake/utilities.cmake")
if(NOT DEPENDENCIES_FILE)
message(FATAL_ERROR "DEPENDENCIES_FILE must be set.")
@ -91,8 +91,10 @@ function(components_find_all component_dirs component_paths component_names)
# Look for a component in each component_dirs entry
foreach(dir ${component_dirs})
debug("Looking for CMakeLists.txt in ${dir}")
file(GLOB component "${dir}/CMakeLists.txt")
if(component)
debug("CMakeLists.txt file ${component}")
get_filename_component(component "${component}" DIRECTORY)
get_filename_component(name "${component}" NAME)
if(NOT name IN_LIST names)
@ -182,10 +184,10 @@ debug("components in build: ${build_component_paths}")
debug("components not found: ${not_found}")
function(line contents)
file(APPEND "${DEPENDENCIES_FILE}" "${contents}\n")
file(APPEND "${DEPENDENCIES_FILE}.tmp" "${contents}\n")
endfunction()
file(WRITE "${DEPENDENCIES_FILE}" "# Component requirements generated by expand_requirements.cmake\n\n")
file(WRITE "${DEPENDENCIES_FILE}.tmp" "# Component requirements generated by expand_requirements.cmake\n\n")
line("set(BUILD_COMPONENTS ${build_components})")
line("set(BUILD_COMPONENT_PATHS ${build_component_paths})")
line("")
@ -214,3 +216,7 @@ endforeach()
line(" message(FATAL_ERROR \"Component not found: \${component}\")")
line("endfunction()")
# only replace DEPENDENCIES_FILE if it has changed (prevents ninja/make build loops.)
execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different "${DEPENDENCIES_FILE}.tmp" "${DEPENDENCIES_FILE}")
execute_process(COMMAND ${CMAKE_COMMAND} -E remove "${DEPENDENCIES_FILE}.tmp")

2
tools/idf.py
View file

@ -346,7 +346,7 @@ def print_closing_message(args):
args.port or "(PORT)",
args.baud,
cmd.strip()))
print("or run 'idf.py %s'" % (key + "-flash" if key != "project" else "flash",))
print("or run 'idf.py -p PORT %s'" % (key + "-flash" if key != "project" else "flash",))
if "all" in args.actions or "build" in args.actions:
print_flashing_message("Project", "project")

3
tools/kconfig_new/confgen.py
View file

@ -33,6 +33,9 @@ import pprint
__version__ = "0.1"
if not "IDF_CMAKE" in os.environ:
os.environ["IDF_CMAKE"] = ""
def main():
parser = argparse.ArgumentParser(description='confgen.py v%s - Config Generation Tool' % __version__, prog=os.path.basename(sys.argv[0]))