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

docs: Make CMake build system default, mark GNU Make as legacy option

Browse source 
All `-cmake` suffixes are removed
Where a GNU Make option is renamed, the `-legacy` suffix is used
This commit is contained in:
Angus Gratton 2019-06-25 11:26:53 +10:00 committed by Angus Gratton
parent 62ed221daf
commit 222146845c
98 changed files with 3429 additions and 3406 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

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

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

@ -1,11 +1,13 @@
Build System
************
Build System (Legacy GNU Make)
******************************
:link_to_translation:`zh_CN:[中文]`
This document explains the Espressif IoT Development Framework build system and the
.. include:: ../gnu-make-legacy.rst
This document explains the legacy GNU Make Espressif IoT Development Framework build system and the
concept of "components"
Read this document if you want to know how to organise a new ESP-IDF project.
Read this document if you want to know how to organise an ESP-IDF project using GNU Make build system.
We recommend using the esp-idf-template_ project as a starting point for your project.
@ -21,7 +23,7 @@ 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
- The Wi-Fi drivers
- A TCP/IP stack
- The FreeRTOS operating system
- A webserver
@ -374,7 +376,7 @@ Some tips for debugging the esp-idf build system:
For more debugging tips and general make information, see the `GNU Make Manual`.
.. _warn-undefined-variables:
.. _warn-undefined-variables-legacy:
Warning On Undefined Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -619,7 +621,7 @@ is overridden then the component can instruct the linker to link other binaries
.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
.. _custom-sdkconfig-defaults:
.. _custom-sdkconfig-defaults-legacy:
Custom sdkconfig defaults
-------------------------

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

@ -1,15 +1,11 @@
Build System (CMake)
********************
Build System
************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
This document explains the implementation of the ESP-IDF build system and the concept of "components". Read this document if you want to know how to organise and build a new ESP-IDF project or component.
.. 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.
.. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make <build-system-legacy>`, which was the default before ESP-IDF V4.0.
Overview
@ -67,7 +63,7 @@ The ``idf.py`` command line tool provides a front-end for easily managing your p
- 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.
The :ref:`getting started guide <get-started-configure>` 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``.
@ -211,7 +207,7 @@ This example "myProject" contains the following elements:
- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main <rename-main-cmake>` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main <rename-main>` section for more info. 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.
@ -262,7 +258,7 @@ Any paths in these variables can be absolute paths, or set relative to the proje
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.
.. _rename-main-cmake:
.. _rename-main:
Renaming ``main`` component
----------------------------
@ -277,12 +273,12 @@ and manually specifying its dependencies. Specifically, the steps to renaming ``
2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory.
3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration<cmake_minimal_component_cmakelists>`.
.. _component-directories-cmake:
.. _component-directories:
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>`).
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>`).
A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file.
@ -382,7 +378,7 @@ This can be useful if there is upstream code that emits warnings.
When using these commands, place them after the call to ``idf_component_register`` in the component CMakeLists file.
.. _component-configuration-cmake:
.. _component-configuration:
Component Configuration
=======================
@ -497,7 +493,11 @@ Some tips for debugging the ESP-IDF CMake-based build system:
- 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:
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.
.. _warn-undefined-variables:
Warning On Undefined Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -506,6 +506,8 @@ By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it
If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
Overriding Parts of the Project
-------------------------------
@ -531,11 +533,12 @@ Take great care when setting variables or targets in a ``project_include.cmake``
KConfig.projbuild
^^^^^^^^^^^^^^^^^
This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration-cmake` KConfig files. If you want to include
This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration` KConfig files. If you want to include
configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``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`.
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`.
``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".
Configuration-Only Components
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -770,7 +773,7 @@ CMake has some unusual behaviour around external project builds:
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:
Custom sdkconfig defaults
=========================
@ -1078,9 +1081,8 @@ Commands that set and operate on variables are generally okay to call before ``i
The arguments for ``idf_component_register`` include:
- SRCS - component source files used for creating a static library for the component; if not specified, component is a treated as a
config-only component and an interface library is created instead.
- SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS.
Note that this is subject to the :ref:`limitations of globbing in CMake<cmake-file-globbing>`. Source files specified in EXCLUDE_SRCS are removed from the globbed files.
config-only component and an interface library is created instead.
- SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS. Note that this is subject to the :ref:`limitations of globbing in CMake<cmake-file-globbing>`. Source files specified in EXCLUDE_SRCS are removed from the globbed files.
- INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path for all other components which require the current component
- PRIV_INCLUDE_DIRS - 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
- REQUIRES - public component requirements for the component
@ -1109,13 +1111,13 @@ For example, to get the directory of the ``freertos`` component:
message(STATUS "The 'freertos' component directory is: ${dir}")
- COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets; set by ``idf_build_component`` and alias library itself
is created by ``idf_component_register``
is created by ``idf_component_register``
- COMPONENT_DIR - component directory; set by ``idf_build_component``
- COMPONENT_LIB - name for created component static/interface library; set by ``idf_build_component`` and library itself
is created by ``idf_component_register``
is created by ``idf_component_register``
- COMPONENT_NAME - name of the component; set by ``idf_build_component`` based on the component directory name
- COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of type LIBRARY if it specifies
source files or embeds a file
source files or embeds a file
- EMBED_FILES - list of files to embed in component; set from ``idf_component_register`` EMBED_FILES argument
- EMBED_TXTFILES - list of text files to embed in component; set from ``idf_component_register`` EMBED_TXTFILES argument
- INCLUDE_DIRS - list of component include directories; set from ``idf_component_register`` INCLUDE_DIRS argument

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

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

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

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

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

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

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

@ -30,7 +30,7 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+R | Reset target board via RTS | Resets the target board and re-starts the application via the RTS line (if connected). |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. |
| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| - Ctrl+A (or A) | Build and flash the app only | Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. |
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+

5
docs/en/api-guides/ulp-legacy.rst
View file

@ -1,5 +1,5 @@
ULP coprocessor programming
===========================
ULP coprocessor (Legacy GNU Make)
=================================
.. toctree::
:maxdepth: 1
@ -7,6 +7,7 @@ ULP coprocessor programming
Instruction set reference <ulp_instruction_set>
Programming using macros (legacy) <ulp_macros>
.. include:: ../gnu-make-legacy.rst
ULP (Ultra Low Power) coprocessor is a simple FSM which is designed to perform measurements using ADC, temperature sensor, and external I2C sensors, while main processors are in deep sleep mode. ULP coprocessor can access RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. ULP coprocessor uses fixed-width 32-bit instructions, 32-bit memory addressing, and has 4 general purpose 16-bit registers.

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

@ -1,4 +1,4 @@
ULP coprocessor programming (CMake)
ULP coprocessor programming
===================================
:link_to_translation:`zh_CN:[中文]`

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

@ -1,7 +1,9 @@
Unit Testing in ESP32
=====================
Unit Testing (Legacy GNU Make)
==============================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively.
Add normal test cases

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

@ -1,9 +1,7 @@
Unit Testing in ESP32 (CMake)
Unit Testing in ESP32
=============================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively.
Add normal test cases
@ -28,7 +26,7 @@ Identifiers are used to group related test, or tests with specific properties.
There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case.
``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``.
The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt <component-directories-cmake>`, since they are themselves,
The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt <component-directories>`, since they are themselves,
components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components
:ref:`should list their sources manually <cmake-file-globbing>`; for component tests however, this requirement is relaxed and the
use of ``COMPONENT_SRCDIRS`` is advised.
@ -132,7 +130,7 @@ Change into tools/unit-test-app directory to configure and build it:
* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory.
* `idf.py -T xxx build` - build unit test app with tests for specific components.
* `idf.py -T all -E xxx build` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp -E mbedtls build` - build all unit tests exludes ulp and mbedtls components).
* `idf.py -T all -E xxxbuild` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp mbedtls build` - build all unit tests exludes ulp and mbedtls components).
When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output.

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

@ -250,7 +250,7 @@ An example::
To gather and analyse heap trace do the following on the host:
1. Build the program and download it to the target as described in :doc:`Build and Flash </get-started/make-project>`.
1. Build the program and download it to the target as described in :ref:`Getting Started Guide <get-started-build>`.
2. Run OpenOCD (see :doc:`JTAG Debugging </api-guides/jtag-debugging/index>`).

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

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

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

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

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

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

14
docs/en/get-started-legacy/get-started/add-idf_path-to-profile.rst → docs/en/get-started-legacy/add-idf_path-to-profile.rst
View file

@ -1,11 +1,13 @@
Add IDF_PATH to User Profile
============================
Add IDF_PATH to User Profile (Legacy GNU Make)
==============================================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
.. _add-idf_path-to-profile-windows:
.. _add-idf_path-to-profile-windows-legacy:
Windows
-------
@ -34,10 +36,10 @@ If you do not like to have ``IDF_PATH`` set up permanently in user profile, you
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`.
If you got here from section :ref:`get-started-setup-path-legacy`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-legacy`.
.. _add-idf_path-to-profile-linux-macos:
.. _add-idf_path-to-profile-linux-macos-legacy:
Linux and MacOS
---------------
@ -62,4 +64,4 @@ If you do not like to have ``IDF_PATH`` set up permanently, you should enter it
export IDF_PATH=~/esp/esp-idf
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
If you got here from section :ref:`get-started-setup-path-legacy`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-legacy`.

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

@ -1,9 +1,11 @@
********************************
Build and Flash with Eclipse IDE
********************************
**************************************************
Build and Flash with Eclipse IDE (Legacy GNU Make)
**************************************************
:link_to_translation:`zh_CN:[中文]`
.. _eclipse-install-steps:
.. include:: ../gnu-make-legacy.rst
.. _eclipse-install-steps-legacy:
Installing Eclipse IDE
======================
@ -70,7 +72,7 @@ Navigate to "C/C++ Build" -> "Behavior" property page:
* Check "Enable parallel build" to enable multiple build jobs in parallel.
.. _eclipse-build-project:
.. _eclipse-build-project-legacy:
Building in Eclipse
-------------------

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

@ -1,7 +1,9 @@
Establish Serial Connection with ESP32
======================================
Establish Serial Connection with ESP32 (Legacy GNU Make)
========================================================
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
This section provides guidance how to establish serial connection between ESP32 and PC.
@ -73,7 +75,7 @@ MacOS ::
ls /dev/cu.*
.. _linux-dialout-group:
.. _linux-dialout-group-legacy:
Adding user to ``dialout`` on Linux
-----------------------------------
@ -146,7 +148,7 @@ If you see some legible log, it means serial connection is working and you are r
Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal.
If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
If you got here from section :ref:`get-started-connect-legacy` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure-legacy`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

91
docs/en/get-started-legacy/get-started/index.rst → docs/en/get-started-legacy/index.rst
View file

@ -1,9 +1,11 @@
***********
Get Started
***********
*****************************
Get Started (Legacy GNU Make)
*****************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32.
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board.
@ -57,13 +59,12 @@ If you have one of ESP32 development boards listed below, you can click on the l
.. toctree::
:maxdepth: 1
ESP32-DevKitC <get-started-devkitc>
ESP-WROVER-KIT <get-started-wrover-kit>
ESP32-PICO-KIT <get-started-pico-kit>
ESP32-DevKitC <../hw-reference/get-started-devkitc>
ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit>
ESP32-PICO-KIT <../hw-reference/get-started-pico-kit>
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
.. _get-started-step-by-step:
.. _get-started-step-by-step-legacy:
Installation Step by Step
=========================
@ -73,22 +74,22 @@ This is a detailed roadmap to walk you through the installation process.
Setting up Development Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-setup-toolchain` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`MacOS <macos-setup>`
* :ref:`get-started-get-esp-idf`
* :ref:`get-started-setup-path`
* :ref:`get-started-get-packages`
* :ref:`get-started-setup-toolchain-legacy` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`MacOS <macos-setup>`
* :ref:`get-started-get-esp-idf-legacy`
* :ref:`get-started-setup-path-legacy`
* :ref:`get-started-get-packages-legacy`
Creating Your First Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project`
* :ref:`get-started-connect`
* :ref:`get-started-configure`
* :ref:`get-started-build-and-flash`
* :ref:`get-started-monitor`
* :ref:`get-started-start-project-legacy`
* :ref:`get-started-connect-legacy`
* :ref:`get-started-configure-legacy`
* :ref:`get-started-build-and-flash-legacy`
* :ref:`get-started-monitor-legacy`
.. _get-started-setup-toolchain:
.. _get-started-setup-toolchain-legacy:
Step 1. Set up the Toolchain
============================
@ -101,36 +102,36 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
+-----------------------------+-------------------------+----------------------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-----------------------------+-------------------------+----------------------------------+
| `Windows <windows-legacy>`_ | `Linux <linux-legacy>`_ | `Mac OS <macos-legacy>`_ |
+-----------------------------+-------------------------+----------------------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started/windows-setup.html
:target: ../get-started-legacy/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started/linux-setup.html
:target: ../get-started-legacy/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started/macos-setup.html
:target: ../get-started-legacy/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
.. _Windows-legacy: ../get-started-legacy/windows-setup.html
.. _Linux-legacy: ../get-started-legacy/linux-setup.html
.. _Mac OS-legacy: ../get-started-legacy/macos-setup.html
.. note::
This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths.
Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup`.
Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup-legacy`.
.. _get-started-get-esp-idf:
.. _get-started-get-esp-idf-legacy:
Step 2. Get ESP-IDF
===================
@ -157,17 +158,17 @@ Consult :doc:`/versions` for information about which ESP-IDF version to use in a
git submodule update --init
.. _get-started-setup-path:
.. _get-started-setup-path-legacy:
Step 3. Set Environment Variables
=================================
The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build.
These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in Section :doc:`add-idf_path-to-profile`.
These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows <add-idf_path-to-profile-windows-legacy>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-legacy>` in Section :doc:`add-idf_path-to-profile`.
.. _get-started-get-packages:
.. _get-started-get-packages-legacy:
Step 4. Install the Required Python Packages
============================================
@ -185,7 +186,7 @@ The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.t
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project:
.. _get-started-start-project-legacy:
Step 5. Start a Project
=======================
@ -218,7 +219,7 @@ It is also possible to build examples in-place, without copying them first.
The esp-idf build system does not support spaces in the paths to either esp-idf or to projects.
.. _get-started-connect:
.. _get-started-connect-legacy:
Step 6. Connect Your Device
===========================
@ -238,12 +239,12 @@ If you are not sure how to check the serial port name, please refer to :doc:`est
Keep the port name handy as you will need it in the next steps.
.. _get-started-configure:
.. _get-started-configure-legacy:
Step 7. Configure
=================
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``.
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-legacy` and run the project configuration utility ``menuconfig``.
Linux and MacOS
~~~~~~~~~~~~~~~
@ -290,7 +291,7 @@ To navigate and use ``menuconfig``, press the following keys:
If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples.
.. _get-started-build-and-flash:
.. _get-started-build-and-flash-legacy:
Step 8. Build and Flash
=======================
@ -337,7 +338,7 @@ If there are no issues by the end of the flash process, you will see messages (b
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-monitor:
.. _get-started-monitor-legacy:
Step 9. Monitor
===============
@ -380,9 +381,9 @@ If IDF monitor fails shortly after the upload, or if instead of the messages abo
If you have such a problem, do the following:
1. Exit the monitor.
2. Go back to :ref:`menuconfig <get-started-configure>`.
2. Go back to :ref:`menuconfig <get-started-configure-legacy>`.
3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.
4. After that, :ref:`build and flash <get-started-build-and-flash>` the application again.
4. After that, :ref:`build and flash <get-started-build-and-flash-legacy>` the application again.
.. note::
@ -429,7 +430,7 @@ Some environment variables can be specified whilst calling ``make`` allowing use
Updating ESP-IDF
================
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`.
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-legacy`.
If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts can find ESP-IDF in its release specific location.

16
docs/en/get-started-legacy/get-started/linux-setup-scratch.rst → docs/en/get-started-legacy/linux-setup-scratch.rst
View file

@ -1,11 +1,13 @@
**********************************
Setup Linux Toolchain from Scratch
**********************************
****************************************************
Setup Linux Toolchain from Scratch (Legacy GNU Make)
****************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
.. note::
Standard process for installing the toolchain is described :doc:`here <linux-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Standard process for installing the toolchain is described :doc:`here <linux-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup-legacy>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Install Prerequisites
=====================
@ -24,7 +26,7 @@ To compile with ESP-IDF you need to get the following packages:
Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF.
In this case please install a supported version via ``pip`` as it is described in section
:ref:`get-started-get-packages`.
:ref:`get-started-get-packages-legacy`.
Compile the Toolchain from Source
=================================
@ -66,10 +68,10 @@ Build the toolchain::
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path-legacy>` to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.

16
docs/en/get-started-legacy/get-started/linux-setup.rst → docs/en/get-started-legacy/linux-setup.rst
View file

@ -1,8 +1,10 @@
*************************************
Standard Setup of Toolchain for Linux
*************************************
*******************************************************
Standard Setup of Toolchain for Linux (Legacy GNU Make)
*******************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Install Prerequisites
=====================
@ -22,7 +24,7 @@ To compile with ESP-IDF you need to get the following packages:
.. note::
Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`.
Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages-legacy`.
Toolchain Setup
===============
@ -49,7 +51,7 @@ ESP32 toolchain for Linux is available for download from Espressif website:
.. include:: /_build/inc/unpack-code-linux32.inc
.. _setup-linux-toolchain-add-it-to-path:
.. _setup-linux-toolchain-add-it-to-path-legacy:
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
@ -82,7 +84,7 @@ ESP32 toolchain for Linux is available for download from Espressif website:
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>`.
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group-legacy>`.
Arch Linux Users
@ -103,7 +105,7 @@ Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
Related Documents

16
docs/en/get-started-legacy/get-started/macos-setup-scratch.rst → docs/en/get-started-legacy/macos-setup-scratch.rst
View file

@ -1,11 +1,13 @@
***************************************
Setup Toolchain for Mac OS from Scratch
***************************************
*********************************************************
Setup Toolchain for Mac OS from Scratch (Legacy GNU Make)
*********************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
.. note::
Standard process for installing the toolchain is described :doc:`here <macos-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Standard process for installing the toolchain is described :doc:`here <macos-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup-legacy>` section for some of the reasons why installing the toolchain from scratch may be necessary.
Install Prerequisites
=====================
@ -16,7 +18,7 @@ Install Prerequisites
.. note::
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages-legacy>`.
Compile the Toolchain from Source
=================================
@ -63,10 +65,10 @@ Build the toolchain::
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path-legacy>` to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.

14
docs/en/get-started-legacy/get-started/macos-setup.rst → docs/en/get-started-legacy/macos-setup.rst
View file

@ -1,8 +1,10 @@
**************************************
Standard Setup of Toolchain for Mac OS
**************************************
********************************************************
Standard Setup of Toolchain for Mac OS (Legacy GNU Make)
********************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Install Prerequisites
=====================
@ -12,7 +14,7 @@ Install Prerequisites
.. note::
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages-legacy>`.
Toolchain Setup
===============
@ -27,7 +29,7 @@ Download this file, then extract it in ``~/esp`` directory:
.. include:: /_build/inc/unpack-code-osx.inc
.. _setup-macos-toolchain-add-it-to-path:
.. _setup-macos-toolchain-add-it-to-path-legacy:
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
@ -45,7 +47,7 @@ Then when you need the toolchain you can type ``get_esp32`` on the command line
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
Related Documents

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

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

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

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

16
docs/en/get-started-legacy/get-started/windows-setup-scratch.rst → docs/en/get-started-legacy/windows-setup-scratch.rst
View file

@ -1,13 +1,15 @@
************************************
Setup Windows Toolchain from Scratch
************************************
******************************************************
Setup Windows Toolchain from Scratch (Legacy GNU Make)
******************************************************
.. include:: ../gnu-make-legacy.rst
Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps.
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
.. _configure-windows-toolchain-from-scratch:
.. _configure-windows-toolchain-from-scratch-legacy:
Configure Toolchain & Environment from Scratch
==============================================
@ -84,7 +86,7 @@ If you already have an MSYS2 install or want to do things differently, you can d
.. note::
If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
If you followed instructions :ref:`configure-windows-toolchain-from-scratch-legacy`, you already have the toolchain and you won't need this download.
.. important::
@ -94,9 +96,9 @@ If you already have an MSYS2 install or want to do things differently, you can d
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
.. _updating-existing-windows-environment:
.. _updating-existing-windows-environment-legacy:
Updating The Environment
========================

12
docs/en/get-started-legacy/get-started/windows-setup.rst → docs/en/get-started-legacy/windows-setup.rst
View file

@ -1,8 +1,10 @@
***************************************
Standard Setup of Toolchain for Windows
***************************************
*********************************************************
Standard Setup of Toolchain for Windows (Legacy GNU Make)
*********************************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../gnu-make-legacy.rst
Introduction
============
@ -41,7 +43,7 @@ Use this window in the following steps setting up development environment for ES
Next Steps
==========
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`.
Updating The Environment
========================
@ -56,7 +58,7 @@ When IDF is updated, sometimes new toolchains are required or new requirements a
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.
There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment-legacy>`, although this is more complex.
Related Documents
=================

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

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

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

@ -1,12 +1,9 @@
****************************************
Build and Flash with Eclipse IDE (CMake)
Build and Flash with Eclipse IDE
****************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon.
.. _eclipse.org: https://www.eclipse.org/
If you require Eclipse IDE support for this pre-release version of ESP-IDF, you can follow the :doc:`legacy GNU Make build system Getting Started guide </get-started-legacy/index>` which has steps for :doc:`Building and Flashing with Eclipse IDE </get-started-legacy/eclipse-setup>`.

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

@ -1,4 +1,4 @@
Establish Serial Connection with ESP32 (CMake)
Establish Serial Connection with ESP32
==============================================
:link_to_translation:`zh_CN:[中文]`
@ -78,7 +78,7 @@ MacOS ::
MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
.. _linux-dialout-group-cmake:
.. _linux-dialout-group:
Adding user to ``dialout`` on Linux
-----------------------------------
@ -151,6 +151,6 @@ If you can see readable log output, it means serial connection is working and yo
Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal.
If you got here from :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure-cmake`.
If you got here from :ref:`get-started-connect` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

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

@ -1,13 +1,9 @@
*******************
Get Started (CMake)
*******************
***********
Get Started
***********
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
.. include:: ../cmake-pending-features.rst
This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif.
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board.
@ -46,7 +42,7 @@ Software:
* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse <https://www.eclipse.org/>`_
.. figure:: ../../_static/what-you-need-cmake.png
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
@ -68,7 +64,7 @@ If you have one of ESP32 development boards listed below, you can click on the l
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
.. _get-started-step-by-step-cmake:
.. _get-started-step-by-step:
Installation Step by Step
=========================
@ -78,23 +74,23 @@ This is a detailed roadmap to walk you through the installation process.
Setting up Development Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-get-prerequisites-cmake` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`macOS <macos-setup>`
* :ref:`get-started-get-esp-idf-cmake`
* :ref:`get-started-set-up-tools-cmake`
* :ref:`get-started-set-up-env-cmake`
* :ref:`get-started-get-prerequisites` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`macOS <macos-setup>`
* :ref:`get-started-get-esp-idf`
* :ref:`get-started-set-up-tools`
* :ref:`get-started-set-up-env`
Creating Your First Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project-cmake`
* :ref:`get-started-connect-cmake`
* :ref:`get-started-configure-cmake`
* :ref:`get-started-build-cmake`
* :ref:`get-started-flash-cmake`
* :ref:`get-started-build-monitor-cmake`
* :ref:`get-started-start-project`
* :ref:`get-started-connect`
* :ref:`get-started-configure`
* :ref:`get-started-build`
* :ref:`get-started-flash`
* :ref:`get-started-build-monitor`
.. _get-started-get-prerequisites-cmake:
.. _get-started-get-prerequisites:
Step 1. Install prerequisites
=============================
@ -108,20 +104,33 @@ Some tools need to be installed on the computer before proceeding to the next st
Linux <linux-setup>
macOS <macos-setup>
* :doc:`windows-setup`
* :doc:`linux-setup`
* :doc:`macos-setup`
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. _get-started-get-esp-idf-cmake:
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
.. _get-started-get-esp-idf:
Step 2. Get ESP-IDF
===================
To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
Get ESP-IDF in accordance with your operating system.
To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``.
To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``, following instructions below specific to your operating system.
.. note::
@ -141,13 +150,13 @@ Consult :doc:`/versions` for information about which ESP-IDF version to use in a
Windows
~~~~~~~
In addition to installing the tools, :ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF.
In addition to installing the tools, :ref:`get-started-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF.
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions <get-esp-idf-windows-command-line-cmake>`.
If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions <get-esp-idf-windows-command-line>`.
.. _get-started-set-up-tools-cmake:
.. _get-started-set-up-tools:
Step 3. Set up the tools
========================
@ -157,7 +166,7 @@ Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such
Windows
~~~~~~~
:ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools.
:ref:`get-started-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools.
If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps:
@ -181,7 +190,7 @@ The scripts introduced in this step install compilation tools required by ESP-ID
If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed.
.. _get-started-set-up-env-cmake:
.. _get-started-set-up-env:
Step 4. Set up the environment variables
========================================
@ -191,7 +200,7 @@ The installed tools are not yet added to the PATH environment variable. To make
Windows
~~~~~~~
:ref:`get-started-cmake-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step.
:ref:`get-started-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step.
Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run:
@ -212,7 +221,7 @@ Note the space between the leading dot and the path!
You can also automate this step, making ESP-IDF tools available in every terminal, by adding this line to your ``.profile`` or ``.bash_profile`` script.
.. _get-started-start-project-cmake:
.. _get-started-start-project:
Step 5. Start a Project
=======================
@ -245,7 +254,7 @@ It is also possible to build examples in-place, without copying them first.
The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects.
.. _get-started-connect-cmake:
.. _get-started-connect:
Step 6. Connect Your Device
===========================
@ -265,12 +274,12 @@ If you are not sure how to check the serial port name, please refer to :doc:`est
Keep the port name handy as you will need it in the next steps.
.. _get-started-configure-cmake:
.. _get-started-configure:
Step 7. Configure
=================
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-cmake` and run the project configuration utility ``menuconfig``.
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``.
Linux and macOS
~~~~~~~~~~~~~~~
@ -313,7 +322,7 @@ To navigate and use ``menuconfig``, press the following keys:
If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples.
.. _get-started-build-cmake:
.. _get-started-build:
Step 8. Build the Project
=========================
@ -347,7 +356,7 @@ This command will compile the application and all ESP-IDF components, then it wi
If there are no errors, the build will finish by generating the firmware binary .bin file.
.. _get-started-flash-cmake:
.. _get-started-flash:
Step 9. Flash onto the Device
=============================
@ -356,7 +365,7 @@ Flash the binaries that you just built onto your ESP32 board by running::
idf.py -p PORT [-b BAUD] flash
Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect-cmake`.
Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect`.
You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``.
@ -402,7 +411,7 @@ If there are no issues by the end of the flash process, the module will be reset
.. (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:
.. _get-started-build-monitor:
Step 10. Monitor
================
@ -446,9 +455,9 @@ If IDF monitor fails shortly after the upload, or, if instead of the messages ab
If you have such a problem, do the following:
1. Exit the monitor.
2. Go back to :ref:`menuconfig <get-started-configure-cmake>`.
2. Go back to :ref:`menuconfig <get-started-configure>`.
3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.
4. After that, :ref:`build and flash <get-started-flash-cmake>` the application again.
4. After that, :ref:`build and flash <get-started-flash>` the application again.
.. note::
@ -468,13 +477,13 @@ Now you are ready to try some other :idf:`examples`, or go straight to developin
Updating ESP-IDF
================
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-cmake`.
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`.
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools-cmake`.
After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`.
Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env-cmake`.
Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env`.
Related Documents
=================
@ -488,4 +497,4 @@ Related Documents
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases
.. _Releases page: https://github.com/espressif/esp-idf/releases

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

@ -1,11 +1,9 @@
******************************************
Setup Linux Toolchain from Scratch (CMake)
Setup Linux Toolchain from Scratch
******************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
Install Prerequisites
@ -68,10 +66,10 @@ Build the toolchain::
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow `instructions for standard setup <setup-linux-toolchain-add-it-to-path>`_ to add the toolchain to your ``PATH``.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.

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

@ -1,11 +1,9 @@
***********************************************
Installation of Prerequisites for Linux (CMake)
***********************************************
*********************************************
Standard Setup of Toolchain for Linux
*********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Install Prerequisites
=====================
@ -32,7 +30,7 @@ Additional Tips
Permission issues /dev/ttyUSB0
------------------------------
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group-cmake>`.
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>`.
Arch Linux Users
@ -53,7 +51,7 @@ Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
Related Documents

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

@ -1,11 +1,9 @@
***********************************************
Setup Toolchain for Mac OS from Scratch (CMake)
Setup Toolchain for Mac OS from Scratch
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Package Manager
===============
@ -85,4 +83,4 @@ Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.

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

@ -1,11 +1,9 @@
***********************************************
Installation of Prerequisites for macOS (CMake)
***********************************************
**********************************************
Standard Setup of Toolchain for Mac OS
**********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
Install Prerequisites
=====================
@ -43,7 +41,7 @@ ESP-IDF will use the version of Python installed by default on macOS.
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
Related Documents
=================

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

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

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

@ -1,11 +1,9 @@
**********************************
Windows Setup from Scratch (CMake)
**********************************
********************************************
Setup Windows Toolchain from Scratch
********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
@ -13,7 +11,7 @@ To quickly setup the toolchain and other tools in standard way, using the ESP-ID
.. note::
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
.. _get-esp-idf-windows-command-line-cmake:
.. _get-esp-idf-windows-command-line:
Get ESP-IDF
===========
@ -98,7 +96,7 @@ Next, the ``bin`` subdirectory of this directory must be `added to your Path <ad
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:
.. _add-directory-windows-path:
Adding Directory to Path
========================
@ -113,7 +111,7 @@ Double-click the ``Path`` variable (either User or System Path, depending if you
Next Steps
==========
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/

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

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

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

@ -1,13 +1,11 @@
*************************************************
Installation of Prerequisites for Windows (CMake)
*************************************************
***********************************************
Standard Setup of Toolchain for Windows
***********************************************
:link_to_translation:`zh_CN:[中文]`
.. include:: ../cmake-warning.rst
.. note::
The CMake-based build system is only supported on 64-bit versions of Windows.
Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`.
Introduction
============
@ -19,7 +17,7 @@ For this Getting Started we're going to use the Command Prompt, but after ESP-ID
.. note::
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
.. _get-started-cmake-windows-tools-installer:
.. _get-started-windows-tools-installer:
ESP-IDF Tools Installer
=======================
@ -48,7 +46,7 @@ Note that this shortcut is specific to the ESP-IDF directory selected in the ESP
Next Steps
==========
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project-cmake`.
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project`.
Related Documents
=================

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

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

2
docs/en/index.rst
View file

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

33
docs/page_redirects.txt
View file

@ -18,8 +18,35 @@ api-reference/system/tcpip_adapter api-reference/network/tcpip_adapter
get-started/idf-monitor api-guides/tools/idf-monitor
get-started-cmake/idf-monitor api-guides/tools/idf-monitor
get-started/get-started-devkitc hw-reference/get-started-devkitc
get-started/get-started-devkitc-v2 hw-reference/get-started-devkitc-v2
get-started/get-started-wrover-kit hw-reference/get-started-wrover-kit
get-started/get-started-wrover-kit-v2 hw-reference/get-started-wrover-kit-v2
get-started/get-started-wrover-kit-v3 hw-reference/get-started-wrover-kit-v3
get-started/get-started-pico-kit hw-reference/get-started-pico-kit
get-started-cmake/get-started-devkitc hw-reference/get-started-devkitc
get-started-cmake/get-started-wrover-kit hw-reference/get-started-wrover-kit
get-started-cmake/get-started-pico-kit hw-reference/get-started-pico-kit
get-started/get-started-pico-kit-v3 hw-reference/get-started-pico-kit-v3
# The preview 'get-started-cmake' guides are now 'get-started'
get-started-cmake get-started
get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile
get-started-cmake/eclipse-setup get-started/eclipse-setup
get-started-cmake/establish-serial-connection get-started/establish-serial-connection
get-started-cmake/index get-started/index
get-started-cmake/linux-setup get-started/linux-setup
get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch
get-started-cmake/macos-setup get-started/macos-setup
get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch
get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch
get-started-cmake/windows-setup get-started/windows-setup
get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch
get-started-cmake/get-started-devkitc hw-reference/get-started-devkitc
get-started-cmake/get-started-devkitc-v2 hw-reference/get-started-devkitc-v2
get-started-cmake/get-started-wrover-kit hw-reference/get-started-wrover-kit
get-started-cmake/get-started-wrover-kit-v2 hw-reference/get-started-wrover-kit-v2
get-started-cmake/get-started-wrover-kit-v3 hw-reference/get-started-wrover-kit-v3
get-started-cmake/get-started-pico-kit hw-reference/get-started-pico-kit
get-started-cmake/get-started-pico-kit-v3 hw-reference/get-started-pico-kit-v3
api-guide/build-system-cmake api-guide/build-system
api-guide/ulp-cmake api-guide/ulp

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

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

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

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

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

File diff suppressed because it is too large Load diff

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

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

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

File diff suppressed because it is too large Load diff

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

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

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

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

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

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

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

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

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

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

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

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

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

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

56
docs/zh_CN/api-guides/unit-tests.rst
View file

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

10
docs/zh_CN/cmake-pending-features.rst
View file

@ -1,10 +0,0 @@
.. important::
目前，CMake 编译系统尚不支持以下功能：
- Eclipse IDE 文档
- 安全启动
- Flash 加密
未来，CMake 编译系统将在 ESP-IDF v4.0 发布后取代现有基于 GNU Make 的编译系统，成为默认编译系统。我们会在 ESP-IDF v4.0 发布前逐步完善上述功能。

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

@ -1,4 +0,0 @@
.. note::
本文档将介绍如何使用 CMake 编译系统。目前，CMake 编译系统仍处于预览发布阶段，如您在使用中遇到任何问题，请前往 ESP-IDF 提交 `Issues <https://github.com/espressif/esp-idf/issues>`_。
未来，CMake 编译系统将在 ESP-IDF v4.0 发布后过渡为默认编译系统，现行基于 GNU Make 的编译系统将在 ESP-IDF v5.0 后弃用。

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

@ -1,75 +0,0 @@
在用户配置文件中添加 IDF_PATH 和 idf.py PATH (CMake)
==========================================================================================================
:link_to_translation:`en:[英文]`
.. include:: ../cmake-warning.rst
使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量：
- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径
- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录
为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。
.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。
.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。
.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。
.. _add-paths-to-profile-windows-cmake:
Windows 操作系统
-----------------------------------
在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。
在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。
你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。
- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。
- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。
如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。
.. _add-idf_path-to-profile-linux-macos-cmake:
Linux 和 MacOS 操作系统
------------------------------------
要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中::
export IDF_PATH=~/esp/esp-idf
export PATH="$IDF_PATH/tools:$PATH"
.. note::
``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。
请退出，并重新登录使更改生效。
.. note::
并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。
运行以下命令来检查 ``IDF_PATH`` 设置是否正确::
printenv IDF_PATH
此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。
为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令::
which idf.py
这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。
如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入::
export IDF_PATH=~/esp/esp-idf
export PATH="$IDF_PATH/tools:$PATH"
如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。

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

@ -1,11 +0,0 @@
****************************************
Eclipse IDE 创建和烧录指南 (CMake)
****************************************
:link_to_translation:`en:[English]`
.. include:: ../cmake-warning.rst
有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。
.. _eclipse.org: https://www.eclipse.org/

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

@ -1,155 +0,0 @@
与 ESP32 创建串口连接 (CMake)
==============================================
:link_to_translation:`en:[English]`
本章节主要介绍如何创建 ESP32 和 PC 之间的串口连接。
连接 ESP32 和 PC
--------------------
用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。
以下是乐鑫 ESP32 开发板驱动程序的链接：
.. csv-table::
:header: 开发板, USB 驱动, 备注
:widths: 40, 20, 40
:ref:`ESP32-DevKitC <esp-modules-and-boards-esp32-devkitc>`, `CP210x`_
`ESP32-LyraT <https://www.espressif.com/en/products/hardware/esp32-lyrat>`_, `CP210x`_
`ESP32-LyraTD-MSC <https://www.espressif.com/en/products/hardware/esp32-lyratd-msc>`_, `CP210x`_
:ref:`ESP32-PICO-KIT <esp-modules-and-boards-esp32-pico-kit>`, `CP210x`_
:ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`, `FTDI`_
:ref:`ESP32 Demo 板 <esp-modules-and-boards-esp32-demo-board>`, `FTDI`_
`ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32)
`ESP32-MeshKit-Sense <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_en.md#esp32-meshkit-sense-hardware-design-guidelines>`_, n/a, 搭配 `ESP-Prog`_ 使用
`ESP32-Sense Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md#guide-for-esp32-sense-development-kit>`_, n/a, 搭配 `ESP-Prog`_ 使用
.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers
.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm
.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board
* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
* FTDI: `FTDI 虚拟 COM 端口驱动程序 <http://www.ftdichip.com/Drivers/VCP.htm>`_
以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。
在 Windows 上查看端口
---------------------
检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。
以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口：
.. figure:: ../../_static/esp32-devkitc-in-device-manager.png
:align: center
:alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥
:figclass: align-center
设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥
.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
:align: center
:alt: Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
:figclass: align-center
Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
在 Linux 和 MacOS 上查看端口
-----------------------------
查看 ESP32 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32 对应的串口：
Linux ::
ls /dev/tty*
MacOS ::
ls /dev/cu.*
.. note::
对于 MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。
.. _linux-dialout-group-cmake:
在 Linux 中添加用户到 ``dialout``
-----------------------------------
当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中，你都可以通过以下命令，将用户添加到 ``dialout`` 组，来获许读写权限::
sudo usermod -a -G dialout $USER
在 Arch Linux 中，需要通过以下命令将用户添加到 ``uucp`` 组中::
sudo usermod -a -G uucp $USER
请重新登录，确保串口读写权限可以生效。
确认串口连接
------------------------
现在，请使用串口终端程序，验证串口连接是否可用。在本示例中，我们将使用 `PuTTY SSH Client <http://www.putty.org/>`_， `PuTTY SSH Client <http://www.putty.org/>`_ 既可用于 Windows 也可用于 Linux。你也可以使用其他串口程序并设置如下的通信参数。
运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了在 Windows 和 Linux 中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。
.. figure:: ../../_static/putty-settings-windows.png
:align: center
:alt: 在 Windows 操作系统中使用 PuTTY 设置串口通信参数
:figclass: align-center
在 Windows 操作系统中使用 PuTTY 设置串口通信参数
.. figure:: ../../_static/putty-settings-linux.png
:align: center
:alt: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数
:figclass: align-center
在 Linux 操作系统中使用 PuTTY 设置串口通信参数
然后，请检查 ESP32 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32 的应用程序，下图即为一个示例。
.. 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
...
如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。
.. note::
在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。
.. note::
请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。
如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect-cmake` 跳转到了这里，请从 :ref:`get-started-configure-cmake` 继续阅读。
.. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

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

@ -1,79 +0,0 @@
******************************************
从零开始设置 Linux 环境下的工具链 (CMake)
******************************************
:link_to_translation:`en:[English]`
.. include:: ../cmake-warning.rst
除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
安装准备
=====================
编译 ESP-IDF 需要以下软件包：
- CentOS 7::
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu 和 Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
从源代码编译工具链
=================================
- 安装依赖：
- 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
创建工作目录，并进入该目录::
mkdir -p ~/esp
cd ~/esp
下载并编译 ``crosstool-NG`` ：
.. include:: /_build/inc/scratch-build-code.inc
编译工具链::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path-cmake>` 的介绍，将工具链添加到 ``PATH``。
后续步骤
==========
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf-cmake` 章节。

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

@ -1,119 +0,0 @@
*******************************************************************
Linux 平台工具链的标准设置 (CMake)
*******************************************************************
:link_to_translation:`en:[英文]`
.. include:: ../cmake-warning.rst
安装前提
=====================
编译 ESP-IDF 需要以下软件包：
- CentOS 7::
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu 和 Debian::
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
工具链的设置
=========================
.. include:: /_build/inc/download-links.inc
Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
- 64 位 Linux：
|download_link_linux64|
- 32 位 Linux：
|download_link_linux32|
1. 下载完成后，将它解压到 ``~/esp`` 目录：
- for 64-bit Linux:
.. include:: /_build/inc/unpack-code-linux64.inc
- for 32-bit Linux:
.. include:: /_build/inc/unpack-code-linux32.inc
.. _setup-linux-toolchain-add-it-to-path-cmake:
2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可::
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
.. note::
如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。
3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确::
printenv PATH
检查字符串的开头是否包含类似的工具链路径::
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
除了 ``/home/user-name``，应该有具体的安装的主路径。
权限问题 /dev/ttyUSB0
----------------------------------------------
使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group-cmake>`
Arch Linux 用户
--------------------------------
在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。
`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置：
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。
或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
后续步骤
================
后续开发环境设置，请参考 :ref:`get-started-get-esp-idf-cmake` 一节。
相关文档
=================
.. toctree::
:maxdepth: 1
linux-setup-scratch
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

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

@ -1,88 +0,0 @@
*********************************************************************
从零开始设置 Mac OS 环境下的工具链 (CMake)
*********************************************************************
:link_to_translation:`en:[英文]`
.. include:: ../cmake-warning.rst
软件包管理器
======================
从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看在哪些情景下需要从头开始设置工具链。
准备工作
============================
- 安装 pip::
sudo easy_install pip
- 安装 pyserial::
pip install --user pyserial
- 安装 CMake 和 Ninja 编译工具：
- 若使用 HomeBrew，你可以运行::
brew install cmake ninja
- 若使用 MacPorts，你可以运行::
sudo port install cmake ninja
从源代码编译工具链
========================================
- 相关安装：
- 对于 MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
- 对于 homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
创建一个文件系统镜像（区分大小写）::
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
挂载::
hdiutil mount ~/esp/crosstool.dmg
创建指向你工作目录的符号链接::
mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume
前往新创建的目录：::
cd ~/esp/ctng-volume
下载 ``crosstool-NG``，并开始编译：
.. include:: /_build/inc/scratch-build-code.inc
编译工具链：::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path-cmake>` 中的介绍，将工具链添加到 ``PATH`` 中。
后续步骤
=================
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf-cmake>` 章节。

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

@ -1,95 +0,0 @@
******************************************************************
在 Mac OS 上安装 ESP32 工具链 (CMake)
******************************************************************
:link_to_translation:`en:[英文]`
.. include:: ../cmake-warning.rst
安装准备
=====================
ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
- 安装 pip::
sudo easy_install pip
- 安装 pyserial::
pip install --user pyserial
- 安装 CMake 和 Ninja 编译工具：
- 若有 HomeBrew_，你可以运行::
brew install cmake ninja
- 若有 MacPorts_，你可以运行::
sudo port install cmake ninja
- 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
.. note::
如在任一步骤中出现以下报错信息::
``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun``
你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。
安装工具链
======================
.. include:: /_build/inc/download-links.inc
下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网：
|download_link_osx|
完成下载后，请在 ``~/esp`` 目录下进行解压：
.. include:: /_build/inc/unpack-code-osx.inc
.. _setup-macos-toolchain-add-it-to-path-cmake:
此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。
为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：::
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令::
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。
注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。
此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确::
printenv PATH
后续步骤
=================
前往 :ref:`get-started-get-esp-idf-cmake`，完成接下来的开发环境配置。
相关文档
=================
.. 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

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

@ -1,27 +0,0 @@
.. _get-started-customized-setup-cmake:
*********************************************************
工具链自定义设置 (CMake)
*********************************************************
:link_to_translation:`en:[英文]`
除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain-cmake`）下载二进制工具链外，你还可以自行编译工具链。
如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链：
- 需要定制工具链编译配置
- 使用其他 GCC 版本（如 4.8.5）
- 需要破解 gcc、newlib 或 libstdc++
- 有相关兴趣或时间充裕
- 不信任从网站下载的 bin 文件
如需自行编译工具链，请查看以下文档：
.. toctree::
:maxdepth: 1
windows-setup-scratch
linux-setup-scratch
macos-setup-scratch

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

@ -1,94 +0,0 @@
******************************************************************
从零开始设置 Windows 环境下的工具链 (CMake)
******************************************************************
:link_to_translation:`en:[英文]`
.. include:: ../cmake-warning.rst
本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 <windows-setup>` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。
使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。
.. note::
基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。
工具
=====
cmake
^^^^^
下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。
当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
Ninja 编译工具
^^^^^^^^^^^^^^^^^^^^
.. note::
Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。
从（`下载页面 <ninja-dl>`_）下载最新发布的 Windows 平台稳定版 `ninja`_。
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 <add-directory-windows-path>`_ （或者选择你的路径中已有的目录）。
Python 2.x
^^^^^^^^^^
下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。
Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。
Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令::
pip install --user pyserial
适用于 IDF 的 MConf
^^^^^^^^^^^^^^^^^^^^^^
从 `kconfig-frontends 发布页面 <mconf-idf>`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。
你需将此工具解压到目录，然后 `添加到你的路径 <add-directory-windows-path>`_。
工具链设置
===============
.. include:: /_build/inc/download-links.inc
下载预编译的 Windows 平台工具链：
|download_link_win32|
解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。
然后，须将该目录下的子目录 ``bin`` `添加到你的路径 <add-directory-windows-path>`_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
.. note::
如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
.. _add-directory-windows-path-cmake:
添加目录到路径
========================
添加任何新目录到你的 Windows Path 环境变量：
打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。
双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
后续步骤
================
要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf-cmake`。
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _MSYS2: https://msys2.github.io/

3
docs/zh_CN/get-started-cmake/windows-setup-update.rst
View file

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

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

@ -1,73 +0,0 @@
**********************************************************
Windows 平台工具链的标准设置 (CMake)
**********************************************************
:link_to_translation:`en:[英文]`
.. include:: ../cmake-warning.rst
.. note::
基于 CMake 的构建系统仅支持 64 位版本 Windows。
引言
============
ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。
在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse <eclipse-setup>` 或支持 CMake 的图形化工具 IDE。
.. note::
基于 GNU Make 的构建系统要求 Windows 系统兼容 MSYS2_ Unix。基于 CMake 的构建系统则无此要求。
ESP-IDF 工具安装器
=======================
安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe
安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。
安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。
请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。
安装 Git
==============
ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。
如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。
使用终端
================
在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符：
- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。
- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。
- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。
后续步骤
==========
要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf-cmake`。
相关文档
=================
想要自定义安装流程的高阶用户可参照：
.. 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/

66
docs/zh_CN/get-started-legacy/add-idf_path-to-profile.rst Normal file
View file

@ -0,0 +1,66 @@
在用户配置文件中添加 IDF_PATH (传统 GNU Make)
=============================================
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
为了在系统多次重新启动时保留 “IDF_PATH” 环境变量的设置，请按照以下说明将其添加到用户配置文件中。
.. _add-idf_path-to-profile-windows-legacy:
Windows
-------
用户配置文件脚本存放在 ``C:/msys32/etc/profile.d/`` 目录中。每次打开 MSYS2 窗口时，系统都执行这些脚本。
#. 在 ``C:/msys32/etc/profile.d/`` 目录下创建一个新的脚本文件。将其命名为 ``export_idf_path.sh``。
#. 确定 ESP-IDF 目录的路径。路径与系统配置有关，例如 ``C:\msys32\home\user-name\esp\esp-idf``。
#. 在脚本中加入 ``export`` 命令，e.g.::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
请将原始 Windows 路径中将反斜杠替换为正斜杠。
#. 保存脚本。
#. 关闭 MSYS2 窗口并再次打开。输入以下命令检查是否设置了 ``IDF_PATH``::
printenv IDF_PATH
将此前在脚本文件中输入的路径打印出来。
如果您不想在用户配置文件中永久设置 ``IDF_PATH``，则应在打开 MSYS2 窗口时手动输入::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-setup-path-legacy` 小节跳转到了这里，请返回到 :ref:`get-started-start-project-legacy` 小节。
.. _add-idf_path-to-profile-linux-macos-legacy:
Linux and MacOS
---------------
在 ``~/.profile`` 文件中加入以下指令，创建 ``IDF_PATH``：
export IDF_PATH=~/esp/esp-idf
注销并重新登录以使此更改生效。
.. note::
如果将 ``/bin/bash`` 已设为登录 shell，并且 ``.bash_profile`` 和 ``.profile`` 同时存在，则更新 ``.bash_profile``。
运行以下命令以确保 ``IDF_PATH`` 已经设置好::
printenv IDF_PATH
此前在 ``~/.profile`` 文件中输入（或者手动设置）的路径应该被打印出来。
如果不想永久设置 ``IDF_PATH``，每次重启或者注销时在终端窗口中手动输入::
export IDF_PATH=~/esp/esp-idf
如果您从 :ref:`get-started-setup-path-legacy` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project-legacy` 小节。

115
docs/zh_CN/get-started-legacy/eclipse-setup.rst Normal file
View file

@ -0,0 +1,115 @@
********************************************
Eclipse IDE 的创建和烧录指南 (传统 GNU Make)
********************************************
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
.. _eclipse-install-steps-legacy:
安装 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）。
配置 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``) 增加至列表，工具链的典型路径类似于 ``/home/user-name/esp/xtensa-esp32-elf/bin``。请注意您需要在附加路径前添加冒号 ``:``。Windows 用户需要将 ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` 添加到 ``PATH`` 环境变量的靠前位置（如果您将 msys32 安装到了其它目录，则需要更改对应的路径以匹配您的本地环境）。
* 在 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 ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``
* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，将 “Compiler command pattern” 修改为 ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
* 前往 “C/C++ General” -> “Indexer” 属性页面。
* 去除 "Allow heuristic resolution of includes" 勾选。启用此选项时，Eclipse 有时无法找到正确的头文件目录。
点击 “C/C++ General" -> "Indexer” 属性页。
* 选择 “Enable project specific settings” 以启用本页上的其他设置。
.. note::
取消选中 “Allow heuristic resolution of includes”。因为启用此选项时，有时会导致 Eclipse 无法找到正确的头文件目录。
点击 “C/C++ Build” -> “Behavior” 属性页。
* 选中 “Enable parallel build” 以启用多任务并行构建。
.. _eclipse-build-project-legacy:
在 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``）。
* 从菜单中选择 “Build Targets” -> “Create”。
* 输入 “flash” 为目标名称，其他选项使用默认值。
* 选择 “Project” -> “Build Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。
注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。
如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。
.. _eclipse.org: https://www.eclipse.org/

132
docs/zh_CN/get-started-legacy/establish-serial-connection.rst Normal file
View file

@ -0,0 +1,132 @@
与 ESP32 创建串口连接 (传统 GNU Make)
=======================================
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
本章节介绍如何在 ESP32 和 PC 之间建立串口连接。
连接 ESP32 和 PC
--------------------
用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，确认 ESP32 开发板上的 USB 转串口芯片（或外部串口适配器）型号，在网上搜索驱动程序并进行安装。
以下是乐鑫 ESP32 开发板驱动程序的链接：
* ESP32-PICO-KIT 和 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 和 ESP32 Demo Board - `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/VCP.htm>`_
以上驱动仅用于参考。当您将上述 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中并自动安装。
在 Windows 上查看端口
---------------------
检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次显示。
以下为 ESP32 DevKitC 和 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
设备管理器中 ESP32-DevKitC 的 USB 串口转换器
.. 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
Windows 设备管理器中的两个 USB-WROVER-KIT 串行端口
在 Linux 和 MacOS 上检查串口
-----------------------------
要查看 ESP32 开发板（或外部串口适配器）的串口设备名称，运行以下命令两次，第一次先拔下开发板或适配器，第二次插入开发板或适配器之后再运行命令，第二次运行指令后出现的端口即是 ESP32 对应的串口：
Linux ::
ls /dev/tty*
MacOS ::
ls /dev/cu.*
.. _linux-dialout-group-legacy:
在 Linux 添加用户到 ``dialout``
-----------------------------------
当前登录用户可以通过 USB 读写串口。在大多数 Linux 发行版中，这是通过以下命令将用户添加到 ``dialout`` 组来完成的::
sudo usermod -a -G dialout $USER
在 Arch Linux 中，需要通过以下命令将用户添加到 ``uucp`` 组中::
sudo usermod -a -G uucp $USER
重新登录以确保串行端口的读写权限被启用。
确认串口连接
------------------------
现在验证串口连接是可用的。您可以使用串口终端程序来执行此操作。在这个例子中，我们将使用 `PuTTY SSH Client <http://www.putty.org/>`_ ，它有 Windows 和 Linux 等平台的版本。您也可以使用其他串口程序并设置如下的通信参数。
运行终端，设置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下是设置串口和在 Windows 和 Linux 上传输参数（如 115200-8-1-N）的一些截屏示例。注意选择上述步骤中确认的串口进行设置。
.. figure:: ../../_static/putty-settings-windows.png
:align: center
:alt: Setting Serial Communication in PuTTY on Windows
:figclass: align-center
在 Windows 上的 PuTTY 设置串口传输。
.. figure:: ../../_static/putty-settings-linux.png
:align: center
:alt: Setting Serial Communication in PuTTY on Linux
:figclass: align-center
在 Linux 上的 PuTTY 设置串口传输。
在终端打开串口，检查是否有任何打印出来的日志。日志内容取决于加载到 ESP32 的应用程序。下图为 ESP32 的一个示例日志。
.. 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
...
如果您看到一些清晰的日志，则表示串行连接正常，您可以继续安装，最后将应用程序上载到 ESP32。
.. note::
对于某些串口接线配置，在 ESP32 启动并产生串行输出之前，需要在终端程序中禁用串行 RTS ＆ DTR 引脚。这取决于串口适配器硬件本身，大多数开发板（包括所有乐鑫开发板）没有这个问题。此问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况。更多详细信息，参见 `esptool documentation`_。
.. note::
验证通讯正常后关闭串口终端。下一步，我们将使用另一个应用程序来上传 ESP32。此应用程序在终端打开时将无法访问串口。
如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-connect-legacy` 小节跳转到了这里，请返回到 :ref:`get-started-configure-legacy` 小节继续阅读。
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

335
docs/zh_CN/get-started-cmake/index.rst → docs/zh_CN/get-started-legacy/index.rst
View file

@ -1,12 +1,9 @@
*******************
快速入门（CMake）
*******************
***************************
快速入门 (传统 GNU Make)
***************************
:link_to_translation:`en:[English]`
.. include:: ../cmake-warning.rst
.. include:: ../cmake-pending-features.rst
.. include:: ../gnu-make-legacy.rst
本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，
@ -40,13 +37,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
软件：
* 设置 **工具链**，用于编译 ESP32 代码；
* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
* 设置 **工具链**，用于编译 ESP32 **应用程序**；
* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本；
* 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse <https://www.eclipse.org/>`_。
.. figure:: ../../_static/what-you-need-cmake.png
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: ESP32 应用程序开发
:figclass: align-center
@ -68,36 +64,35 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
.. _get-started-step-by-step-cmake:
.. _get-started-step-by-step-legacy:
详细安装步骤
==============
============
请根据下方详细步骤，完成安装过程。
设置开发环境
~~~~~~~~~~~~~~~~
~~~~~~~~~~~~
* :ref:`get-started-setup-toolchain-cmake`
* :ref:`get-started-get-esp-idf-cmake`
* :ref:`get-started-setup-path-cmake`
* :ref:`get-started-get-packages-cmake`
* :ref:`get-started-setup-toolchain-legacy`
* :ref:`get-started-get-esp-idf-legacy`
* :ref:`get-started-setup-path-legacy`
* :ref:`get-started-get-packages-legacy`
创建您的第一个工程
~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project-cmake`
* :ref:`get-started-connect-cmake`
* :ref:`get-started-configure-cmake`
* :ref:`get-started-build-cmake`
* :ref:`get-started-flash-cmake`
* :ref:`get-started-build-monitor-cmake`
* :ref:`get-started-start-project-legacy`
* :ref:`get-started-connect-legacy`
* :ref:`get-started-configure-legacy`
* :ref:`get-started-build-and-flash-legacy`
* :ref:`get-started-monitor-legacy`
.. _get-started-setup-toolchain-cmake:
.. _get-started-setup-toolchain-legacy:
第一步：设置工具链
====================
==================
工具链指一套用于编译代码和应用程序的程序。
@ -107,49 +102,44 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
+-----------------------------+-------------------------+----------------------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-----------------------------+-------------------------+----------------------------------+
| `Windows <windows-legacy>`_ | `Linux <linux-legacy>`_ | `Mac OS <macos-legacy>`_ |
+-----------------------------+-------------------------+----------------------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started-cmake/windows-setup.html
:target: ../get-started-legacy/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started-cmake/linux-setup.html
:target: ../get-started-legacy/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started-cmake/macos-setup.html
:target: ../get-started-legacy/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
.. _Windows-legacy: ../get-started-legacy/windows-setup.html
.. _Linux-legacy: ../get-started-legacy/linux-setup.html
.. _Mac OS-legacy: ../get-started-legacy/macos-setup.html
.. note::
在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置<get-started-customized-setup-cmake>` 章节获取更多信息。
此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置<get-started-customized-setup-legacy>` 章节获取更多信息。
.. _get-started-get-esp-idf-cmake:
.. _get-started-get-esp-idf-legacy:
第二步：获取 ESP-IDF
===========================
=====================
除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
请将 ESP-IDF 下载到您的本地。
获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。
Linux 和 MacOS 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
打开终端，后运行以下命令：
.. include:: /_build/inc/git-clone-bash.inc
@ -158,23 +148,6 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
Windows 操作系统
~~~~~~~~~~~~~~~~~~
.. note::
较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
打开命令提示符，后运行以下命令：
.. include:: /_build/inc/git-clone-windows.inc
ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
.. include:: /_build/inc/git-clone-notes.inc
.. note::
@ -184,45 +157,44 @@ ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
cd esp-idf
git submodule update --init
.. _get-started-setup-path-cmake:
.. _get-started-setup-path-legacy:
第三步：设置环境变量
===========================
=====================
请在您的 PC 上设置以下环境变量，否则无法编译工程。
工具链通过环境变量 ``IDF_PATH`` 获得 ESP-IDF 的目录。因此，您需要在 PC 中设置该环境变量，否则无法编译工程。
- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-paths-to-profile-windows-cmake>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos-cmake>` 操作系统的具体设置方式。
您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-idf_path-to-profile-windows-legacy>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos-legacy>` 操作系统的具体设置方式。
.. _get-started-get-packages-cmake:
.. _get-started-get-packages-legacy:
第四步：安装 Python 软件包
=================================
ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
==========================
ESP-IDF 所需 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
python -m pip install --user -r $IDF_PATH/requirements.txt
.. note::
请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如：
请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： ::
``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt``
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project-cmake:
.. _get-started-start-project-legacy:
第五步：开始创建工程
=======================
=====================
现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下：
Linux 和 MacOS 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
@ -230,7 +202,7 @@ Linux 和 MacOS 操作系统
cp -r $IDF_PATH/examples/get-started/hello_world .
Windows 操作系统
~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~
.. code-block:: batch
@ -243,10 +215,10 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
ESP-IDF 编译系统不支持带有空格的路径。
.. _get-started-connect-cmake:
.. _get-started-connect-legacy:
第六步：连接设备
======================
==================
现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。
@ -263,36 +235,28 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
请记住串口名，您会在下面的步骤中用到。
.. _get-started-configure-cmake:
.. _get-started-configure-legacy:
第七步：配置
=================
=============
请进入 :ref:`get-started-start-project-cmake` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。
请进入 :ref:`get-started-start-project-legacy` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。
Linux 和 MacOS 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
idf.py menuconfig
如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。
make menuconfig
Windows 操作系统
~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
idf.py menuconfig
Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。
.. note::
如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path-cmake`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf-cmake`。
make menuconfig
如果之前的步骤都正确，则会显示下面的菜单：
@ -303,6 +267,8 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
工程配置 — 主窗口
进入菜单后，选择 ``Serial flasher config`` > ``Default serial port`` 配置串口（设备将通过该串口加载工程）。按回车键确认选择，点击 ``< Save >`` 保存配置，然后点击 ``< Exit >`` 退出 ``menuconfig``。
``menuconfig`` 工具的常见操作见下。
* ``上下箭头``：移动
@ -310,118 +276,77 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
* ``ESC 键``：返回上级菜单或退出
* ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项
* ``英文问号``：调出有关高亮选项的帮助菜单
* ``英文问号`` ：调出有关高亮选项的帮助菜单
* ``/ 键``：寻找配置项目
.. note::
如果您是 **Arch Linux** 用户，请前往 ``SDK tool configuration``，并将 ``Python 2 interpreter`` 的名称从 ``python`` 替换为 ``python2``。
.. attention::
如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。
.. _get-started-build-cmake:
.. _get-started-build-and-flash-legacy:
第八步：编译工程
==================
请使用以下命令，编译烧录工程：::
idf.py build
运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。
.. 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'
如果一切正常，编译完成后将生成 .bin 文件。
.. _get-started-flash-cmake:
第九步：烧录到设备
第八步：编译和烧录
====================
请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： ::
请使用以下命令，编译烧录工程： ::
idf.py -p PORT [-b BAUD] flash
make flash
请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect-cmake`。
运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。接着，这些二进制文件将被烧录至 ESP32 开发板。
您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
如果一切顺利，您可在烧录完成后看到类似下方的打印信息（代表加载进程）。接着，开发板将会复位，应用程序 "hello_world" 开始启动。
更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。
.. highlight:: none
.. note::
::
勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。
.. 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
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 460800
Changing baud rate to 921600
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size: 4MB
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)...
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 5789.3 kbit/s)...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 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...
如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。
.. note::
（目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 <eclipse-setup>`。
Hard resetting...
.. _get-started-build-monitor-cmake:
如果您希望使用 Eclipse IDE，而非 ``make`` 编译系统，请参考 :doc:`Eclipse 指南 <eclipse-setup>`。
第十步：监视器
==================
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。
.. _get-started-monitor-legacy:
第九步：监视器
===============
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。
运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： ::
$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
--- 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)
@ -435,7 +360,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
I (211) cpu_start:Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
@ -452,45 +377,71 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
此时，请您：
1. 退出监视器。
2. 打开 :ref:`menuconfig <get-started-configure-cmake>`，
2. 打开 :ref:`menuconfig <get-started-configure>`，
3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。
4. 然后，请重新 :ref:`编译和烧录 <get-started-flash-cmake>` 应用程序。
4. 然后，请重新 :ref:`编译和烧录 <get-started-build-and-flash-legacy>` 应用程序。
.. note::
您也可以运行以下命令，一次性执行构建、烧录和监视过程：
您也可以运行以下命令，一次性执行构建、烧录和监视过程： ::
``idf.py -p PORT flash monitor``
make flash monitor
此外，
- 请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。
- 请前往 :ref:`idf.py`，查看更多 ``idf.py`` 命令和选项。
此外，请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。
**恭喜，您已完成 ESP32 的入门学习！**
现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。
更新 ESP-IDF
=================
乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-cmake` 中的指示，重新完成克隆。
环境变量
=========
用户可以在使用 ``make`` 命令时 **直接设置** 部分环境变量，而无需进入 ``make menuconfig`` 进行重新配置。这些变量包括：
+-----------------+-----------------------------------------------------------------------+
| 变量 | 描述与使用方式 |
+-----------------+-----------------------------------------------------------------------+
| ``ESPPORT`` | 覆盖 ``flash`` 和 ``monitor`` 命令使用的串口。 |
+ +-----------------------------------------------------------------------+
| | 例：``make flash ESPPORT=/dev/ttyUSB1``, ``make monitor ESPPORT=COM1``|
+-----------------+-----------------------------------------------------------------------+
| ``ESPBAUD`` | 覆盖烧录 ESP32 时使用的串口速率。 |
+ +-----------------------------------------------------------------------+
| | 例：``make flash ESPBAUD=9600`` |
+-----------------+-----------------------------------------------------------------------+
| ``MONITORBAUD`` | 覆盖监控时使用的串口速率。 |
+ +-----------------------------------------------------------------------+
| | 例：``make monitor MONITORBAUD=9600`` |
+-----------------+-----------------------------------------------------------------------+
.. note::
您可导出环境变量（例：``export ESPPORT=/dev/ttyUSB1``）。
在同一会话窗口中，如果未被同步覆盖，所有 ``make`` 命令均会使用导出的环境变量值。
更新 ESP-IDF
=============
乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，在使用时，您也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-legacy` 中的指示，重新完成克隆。
如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH <add-idf_path-to-profile>`。否则，工具链将无法找到 ESP-IDF。
此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 <updating>` 章节查看。
相关文档
===========
=========
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
../api-guides/tools/idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases
.. _Releases page: https://github.com/espressif/esp-idf/releases

78
docs/zh_CN/get-started-legacy/linux-setup-scratch.rst Normal file
View file

@ -0,0 +1,78 @@
*****************************************************
从零开始设置 Linux 环境下的工具链 (传统 GNU Make)
*****************************************************
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
.. note::
安装工具链的标准流程可以通过阅读文档 :doc:`Linux 平台工具链的标准设置 <linux-setup>` 来获得，:ref:`工具链的自定义设置 <get-started-customized-setup-legacy>` 章节会介绍哪些情况下我们必须要重新定义工具链。
安装必要的工具
==============
要想使用 ESP-IDF 进行编译，您需要获取以下软件包：
- Ubuntu 和 Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
.. note::
一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。
在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 <get-started-get-packages-legacy>` 章节，通过 ``pip`` 工具来安装支持的版本。
从源代码编译工具链
==================
- 安装依赖:
- CentOS 7::
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
- Ubuntu pre-16.04::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
- Ubuntu 16.04::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Debian 9::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
- Arch::
TODO
新建工作目录，然后进入::
mkdir -p ~/esp
cd ~/esp
下载 ``crosstool-NG`` 然后编译:
.. include:: /_build/inc/scratch-build-code.inc
编译工具链::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Linux 下设置环境变量的标准方法 <setup-linux-toolchain-add-it-to-path-legacy>` 中的介绍，将工具链添加到 ``PATH`` 中。
下一步
======
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf-legacy>` 章节。

108
docs/zh_CN/get-started-legacy/linux-setup.rst Normal file
View file

@ -0,0 +1,108 @@
*******************************************
Linux 平台工具链的标准设置 (传统 GNU Make)
*******************************************
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
安装前提
=====================
编译 ESP-IDF 需要以下软件包：
- CentOS 7::
sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial python-pyelftools
- Ubuntu and Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
.. note::
一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。
在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 <get-started-get-packages-legacy>` 章节，通过 ``pip`` 工具来安装支持的版本。
工具链的设置
===============
.. include:: /_build/inc/download-links.inc
Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
- 64-bit Linux：
|download_link_linux64|
- 32-bit Linux：
|download_link_linux32|
1. 下载完成后，将它解压到 ``~/esp`` 目录： :
- 64-bit Linux:
.. include:: /_build/inc/unpack-code-linux64.inc
- 32-bit Linux:
.. include:: /_build/inc/unpack-code-linux32.inc
.. _setup-linux-toolchain-add-it-to-path-legacy:
2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中： ::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
或者你也可以给上面的命令创建一个别名。这样做的好处是，你只在需要使用它的时候才获取工具链。将下面这行代码添加到 ``~/.profile`` 文件中即可： ::
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
.. note::
如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile`` 。在 CentOS 环境下, ``alias`` 需要添加到 ``.bashrc`` 文件中。
3. 退出并重新登录以使 ``.profile`` 更改生效。 运行以下命令来检查 ``PATH`` 设置是否正确： ::
printenv PATH
检查字符串的开头是否包含类似的工具链路径::
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
除了 ``/home/user-name``，应该有具体的安装的主路径。
权限问题 /dev/ttyUSB0
------------------------------
某些 Linux 版本可能在烧写 ESP32 时会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。 :ref:`可以通过将当前用户添加到拨出组来解决<linux-dialout-group-legacy>`。
Arch Linux 用户
----------------
在 Arch 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。在 AUR_ 中向下兼容的库文件，可用于本地和 lib32 的配置：
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
在安装这些软件包之前，你可能需要将作者的公钥添加到你的钥匙圈中，上面链接中的“Comments”部分有所叙述。
或者，你也可以使用 crosstool-NG 编译一个链接 ncurses 6 的 gdb。
后续步骤
==========
要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf-legacy` 一节。
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

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

@ -0,0 +1,74 @@
**************************************************
从零开始设置 Mac OS 环境下的工具链 (传统 GNU Make)
**************************************************
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
.. note::
安装工具链的标准流程可以通过阅读文档 :doc:`在 MacOS 上安装 ESP32 工具链 <macos-setup>` 来获得， :ref:`工具链的自定义设置 <get-started-customized-setup-legacy>` 章节会介绍哪些情况下我们必须要重新定义工具链。
安装必要的工具
=====================
- 安装 pip::
sudo easy_install pip
.. note::
``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 <get-started-get-packages-legacy>`。
从源代码编译工具链
==================
- 安装依赖:
- 安装 MacPorts_ 或者 homebrew_ 包管理器。MacPorts 需要安装完整的 XCode 软件，但是 homebrew 只需要安装 XCode 命令行工具即可。
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
- 对于 MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
- 对于 homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
创建大小写敏感的文件系统镜像::
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
挂载::
hdiutil mount ~/esp/crosstool.dmg
创建指向你工作目录的符号链接::
mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume
进入新创建的工作目录::
cd ~/esp/ctng-volume
下载 ``crosstool-NG`` 然后编译:
.. include:: /_build/inc/scratch-build-code.inc
编译工具链::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path-legacy>` 中的介绍，将工具链添加到 ``PATH`` 中。
下一步
======
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf-legacy>` 章节。

60
docs/zh_CN/get-started-legacy/macos-setup.rst Normal file
View file

@ -0,0 +1,60 @@
************************************************
在 Mac OS 上安装 ESP32 工具链 (传统 GNU Make)
************************************************
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
安装准备
================
- 安装 pip::
sudo easy_install pip
.. note::
``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 <get-started-get-packages-legacy>`。
安装工具链
===============
.. include:: /_build/inc/download-links.inc
Mac OS 版本的 ESP32 工具链可以从以下地址下载：
|download_link_osx|
下载压缩文件之后，解压到 ``~/esp`` 目录中:
.. include:: /_build/inc/unpack-code-osx.inc
.. _setup-macos-toolchain-add-it-to-path-legacy:
工具链将被解压到 ``~/esp/xtensa-esp32-elf/`` 路径下。
在 ``~/.profile`` 文件中更新 ``PATH`` 环境变量以使用工具链。为了使 ``xtensa-esp32-elf`` 在各种终端会话中都可用，在 ``~/.profile`` 文件中加上以下指令::
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
或者，您可以为上述命令创建一个别名。这样只有执行以下指令时工具链才能被使用。将下面的指令添加到您的 ``〜/ .profile`` 文件中::
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
当需要使用工具链时，在命令行里输入 ``get_esp32``，就可以将工具链添加到 ``PATH`` 中。
下一步
==========
前往 :ref:`get-started-get-esp-idf-legacy` 继续配置开发环境。
相关文档
=================
.. toctree::
:maxdepth: 1
macos-setup-scratch

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

@ -1,7 +1,9 @@
通过 make 指令创建和烧录项目
=============================
通过 make 指令创建和烧录项目 (传统 GNU Make)
============================================
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
寻找项目
-----------------

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

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

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

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

69
docs/zh_CN/get-started-legacy/windows-setup.rst Normal file
View file

@ -0,0 +1,69 @@
**********************************************
Windows 平台工具链的标准设置 (传统 GNU Make)
**********************************************
:link_to_translation:`en:[English]`
.. include:: ../gnu-make-legacy.rst
引言
============
Windows 没有内置的 "make" 环境，因此如果要安装工具链，你需要一个 GNU 兼容环境。我们这里使用 MSYS2_ 来提供该环境。你不需要一直使用这个环境（你可以使用 :doc:`Eclipse <eclipse-setup>` 或其它前端工具），但是它是在后台运行的。
工具链的设置
===============
快速设置的方法是从 dl.espressif.com 下载集成在一起的工具链和 MSYS2 压缩文件：
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20181001.zip
将 zip 压缩文件解压到 ``C:\`` (或其它路径，这里假设是 ``C:\``)，它会使用预先准备的环境创建一个 ``msys32`` 目录。
检出
============
运行 ``C:\msys32\mingw32.exe`` 打开一个 MSYS2 的终端窗口。该窗口的环境是一个 bash shell。创建一个 ``esp`` 目录作为开发 ESP32 应用的默认地址。运行指令 ::
mkdir -p ~/esp
输入 ``cd ~/esp`` 就进入到新创建的目录。如果没有错误信息出现则表明此步骤已完成。
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
MSYS2 终端窗口
后续步骤将会使用这个窗口来为 ESP32 设置开发环境。
后续步骤
==========
要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf-legacy` 一节。
更新环境
========================
当 IDF 更新时，有时需要新的工具链，或者将新的需求添加到 Windows MSYS2 环境中。要将旧版本的预编译环境中的数据移动到新版本：
- 把旧的 MSYS2 环境（即 ``C:\msys32``）移动/重命名为不同的目录（即 ``C:\msys32_old``）。
- 按照前文所述步骤下载新的预编译环境。
- 将新的 MSYS2 环境解压缩到 ``C:\msys32`` （或其他位置）。
- 找到旧的 ``C:\msys32_old\home`` 目录并把它移到 ``C:\msys32``。
- 如果你不再需要 ``C:\msys32_old`` 可以将它删除。
你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。
相关文档
=================
.. toctree::
:maxdepth: 1
windows-setup-scratch
.. _MSYS2: https://msys2.github.io/

75
docs/zh_CN/get-started/add-idf_path-to-profile.rst
View file

@ -1,64 +1,73 @@
在用户配置文件中添加 IDF_PATH
==============================
:link_to_translation:`en:[English]`
在用户配置文件中添加 IDF_PATH 和 idf.py PATH
==========================================================================================================
为了在系统多次重新启动时保留 “IDF_PATH” 环境变量的设置，请按照以下说明将其添加到用户配置文件中。
:link_to_translation:`en:[英文]`
.. _add-idf_path-to-profile-windows:
使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量：
- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径
- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录
Windows
-------
为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。
用户配置文件脚本存放在 ``C:/msys32/etc/profile.d/`` 目录中。每次打开 MSYS2 窗口时，系统都执行这些脚本。
.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。
.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。
#. 在 ``C:/msys32/etc/profile.d/`` 目录下创建一个新的脚本文件。将其命名为 ``export_idf_path.sh``。
.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。
#. 确定 ESP-IDF 目录的路径。路径与系统配置有关，例如 ``C:\msys32\home\user-name\esp\esp-idf``。
#. 在脚本中加入 ``export`` 命令，e.g.::
.. _add-paths-to-profile-windows:
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
Windows 操作系统
-----------------------------------
请将原始 Windows 路径中将反斜杠替换为正斜杠。
在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。
#. 保存脚本。
在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。
#. 关闭 MSYS2 窗口并再次打开。输入以下命令检查是否设置了 ``IDF_PATH``::
你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。
printenv IDF_PATH
- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。
- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。
将此前在脚本文件中输入的路径打印出来。
如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。
如果您不想在用户配置文件中永久设置 ``IDF_PATH``，则应在打开 MSYS2 窗口时手动输入::
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-setup-path` 小节跳转到了这里，请返回到 :ref:`get-started-start-project` 小节。
.. _add-idf_path-to-profile-linux-macos:
Linux and MacOS
---------------
Linux 和 MacOS 操作系统
------------------------------------
在 ``~/.profile`` 文件中加入以下指令，创建 ``IDF_PATH``：
要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中::
export IDF_PATH=~/esp/esp-idf
注销并重新登录以使此更改生效。
export PATH="$IDF_PATH/tools:$PATH"
.. note::
如果将 ``/bin/bash`` 已设为登录 shell，并且 ``.bash_profile`` 和 ``.profile`` 同时存在，则更新 ``.bash_profile``。
运行以下命令以确保 ``IDF_PATH`` 已经设置好::
``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。
请退出，并重新登录使更改生效。
.. note::
并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。
运行以下命令来检查 ``IDF_PATH`` 设置是否正确::
printenv IDF_PATH
此前在 ``~/.profile`` 文件中输入（或者手动设置）的路径应该被打印出来。
此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。
如果不想永久设置 ``IDF_PATH``，每次重启或者注销时在终端窗口中手动输入::
为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令::
which idf.py
这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。
如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入::
export IDF_PATH=~/esp/esp-idf
export PATH="$IDF_PATH/tools:$PATH"
如果您从 :ref:`get-started-setup-path` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project` 小节。
如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。

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

@ -1,113 +1,9 @@
****************************
Eclipse IDE 的创建和烧录指南
****************************
****************************************
Eclipse IDE 创建和烧录指南
****************************************
:link_to_translation:`en:[English]`
.. _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）。
配置 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``) 增加至列表，工具链的典型路径类似于 ``/home/user-name/esp/xtensa-esp32-elf/bin``。请注意您需要在附加路径前添加冒号 ``:``。Windows 用户需要将 ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` 添加到 ``PATH`` 环境变量的靠前位置（如果您将 msys32 安装到了其它目录，则需要更改对应的路径以匹配您的本地环境）。
* 在 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 ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``
* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，将 “Compiler command pattern” 修改为 ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
* 前往 “C/C++ General” -> “Indexer” 属性页面。
* 去除 "Allow heuristic resolution of includes" 勾选。启用此选项时，Eclipse 有时无法找到正确的头文件目录。
点击 “C/C++ General" -> "Indexer” 属性页。
* 选择 “Enable project specific settings” 以启用本页上的其他设置。
.. note::
取消选中 “Allow heuristic resolution of includes”。因为启用此选项时，有时会导致 Eclipse 无法找到正确的头文件目录。
点击 “C/C++ Build” -> “Behavior” 属性页。
* 选中 “Enable parallel build” 以启用多任务并行构建。
.. _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``）。
* 从菜单中选择 “Build Targets” -> “Create”。
* 输入 “flash” 为目标名称，其他选项使用默认值。
* 选择 “Project” -> “Build Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。
注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。
如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。
有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。
.. _eclipse.org: https://www.eclipse.org/

81
docs/zh_CN/get-started/establish-serial-connection.rst
View file

@ -1,47 +1,67 @@
与 ESP32 创建串口连接
=========================
==============================================
:link_to_translation:`en:[English]`
本章节介绍如何在 ESP32 和 PC 之间建立串口连接。
本章节主要介绍如何创建 ESP32 和 PC 之间的串口连接。
连接 ESP32 和 PC
--------------------
用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，确认 ESP32 开发板上的 USB 转串口芯片（或外部串口适配器）型号，在网上搜索驱动程序并进行安装。
用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。
以下是乐鑫 ESP32 开发板驱动程序的链接：
* ESP32-PICO-KIT 和 ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
.. csv-table::
:header: 开发板, USB 驱动, 备注
:widths: 40, 20, 40
* ESP32-WROVER-KIT 和 ESP32 Demo Board - `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/VCP.htm>`_
:ref:`ESP32-DevKitC <esp-modules-and-boards-esp32-devkitc>`, `CP210x`_
`ESP32-LyraT <https://www.espressif.com/en/products/hardware/esp32-lyrat>`_, `CP210x`_
`ESP32-LyraTD-MSC <https://www.espressif.com/en/products/hardware/esp32-lyratd-msc>`_, `CP210x`_
:ref:`ESP32-PICO-KIT <esp-modules-and-boards-esp32-pico-kit>`, `CP210x`_
:ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`, `FTDI`_
:ref:`ESP32 Demo 板 <esp-modules-and-boards-esp32-demo-board>`, `FTDI`_
`ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32)
`ESP32-MeshKit-Sense <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_en.md#esp32-meshkit-sense-hardware-design-guidelines>`_, n/a, 搭配 `ESP-Prog`_ 使用
`ESP32-Sense Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md#guide-for-esp32-sense-development-kit>`_, n/a, 搭配 `ESP-Prog`_ 使用
以上驱动仅用于参考。当您将上述 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中并自动安装。
.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers
.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm
.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board
* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
* FTDI: `FTDI 虚拟 COM 端口驱动程序 <http://www.ftdichip.com/Drivers/VCP.htm>`_
以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。
在 Windows 上查看端口
---------------------
检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次显示。
检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。
以下为 ESP32 DevKitC 和 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
:alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥
:figclass: align-center
设备管理器中 ESP32-DevKitC 的 USB 串口转换器
设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥
.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
:align: center
:alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
:alt: Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
:figclass: align-center
Windows 设备管理器中的两个 USB-WROVER-KIT 串行端口
Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口
在 Linux 和 MacOS 上检查串口
在 Linux 和 MacOS 上查看端口
-----------------------------
要查看 ESP32 开发板（或外部串口适配器）的串口设备名称，运行以下命令两次，第一次先拔下开发板或适配器，第二次插入开发板或适配器之后再运行命令，第二次运行指令后出现的端口即是 ESP32 对应的串口：
查看 ESP32 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32 对应的串口：
Linux ::
@ -51,13 +71,16 @@ MacOS ::
ls /dev/cu.*
.. note::
对于 MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。
.. _linux-dialout-group:
在 Linux 添加用户到 ``dialout``
在 Linux 中添加用户到 ``dialout``
-----------------------------------
当前登录用户可以通过 USB 读写串口。在大多数 Linux 发行版中，这是通过以下命令将用户添加到 ``dialout`` 组来完成的::
当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中，你都可以通过以下命令，将用户添加到 ``dialout`` 组，来获许读写权限::
sudo usermod -a -G dialout $USER
@ -65,31 +88,32 @@ MacOS ::
sudo usermod -a -G uucp $USER
重新登录以确保串行端口的读写权限被启用。
请重新登录，确保串口读写权限可以生效。
确认串口连接
------------------------
现在验证串口连接是可用的。您可以使用串口终端程序来执行此操作。在这个例子中，我们将使用 `PuTTY SSH Client <http://www.putty.org/>`_ ，它有 Windows 和 Linux 等平台的版本。您也可以使用其他串口程序并设置如下的通信参数。
现在，请使用串口终端程序，验证串口连接是否可用。在本示例中，我们将使用 `PuTTY SSH Client <http://www.putty.org/>`_， `PuTTY SSH Client <http://www.putty.org/>`_ 既可用于 Windows 也可用于 Linux。你也可以使用其他串口程序并设置如下的通信参数。
运行终端，设置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下是设置串口和在 Windows 和 Linux 上传输参数（如 115200-8-1-N）的一些截屏示例。注意选择上述步骤中确认的串口进行设置。
运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了在 Windows 和 Linux 中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。
.. figure:: ../../_static/putty-settings-windows.png
:align: center
:alt: Setting Serial Communication in PuTTY on Windows
:alt: 在 Windows 操作系统中使用 PuTTY 设置串口通信参数
:figclass: align-center
在 Windows 上的 PuTTY 设置串口传输。
在 Windows 操作系统中使用 PuTTY 设置串口通信参数
.. figure:: ../../_static/putty-settings-linux.png
:align: center
:alt: Setting Serial Communication in PuTTY on Linux
:alt: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数
:figclass: align-center
在 Linux 上的 PuTTY 设置串口传输。
在 Linux 操作系统中使用 PuTTY 设置串口通信参数
在终端打开串口，检查是否有任何打印出来的日志。日志内容取决于加载到 ESP32 的应用程序。下图为 ESP32 的一个示例日志。
然后，请检查 ESP32 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32 的应用程序，下图即为一个示例。
.. highlight:: none
@ -114,17 +138,18 @@ MacOS ::
...
如果您看到一些清晰的日志，则表示串行连接正常，您可以继续安装，最后将应用程序上载到 ESP32。
如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。
.. note::
对于某些串口接线配置，在 ESP32 启动并产生串行输出之前，需要在终端程序中禁用串行 RTS ＆ DTR 引脚。这取决于串口适配器硬件本身，大多数开发板（包括所有乐鑫开发板）没有这个问题。此问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况。更多详细信息，参见 `esptool documentation`_。
在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。
.. note::
验证通讯正常后关闭串口终端。下一步，我们将使用另一个应用程序来上传 ESP32。此应用程序在终端打开时将无法访问串口。
请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。
如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-connect` 小节跳转到了这里，请返回到 :ref:`get-started-configure` 小节继续阅读。
如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect` 跳转到了这里，请从 :ref:`get-started-configure` 继续阅读。
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
.. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

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

@ -1,6 +1,6 @@
********
快速入门
********
*******************
快速入门（CMake）
*******************
:link_to_translation:`en:[English]`
@ -36,7 +36,8 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
软件：
* 设置 **工具链**，用于编译 ESP32 **应用程序**；
* 设置 **工具链**，用于编译 ESP32 代码；
* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本；
* 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse <https://www.eclipse.org/>`_。
@ -66,12 +67,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
.. _get-started-step-by-step:
详细安装步骤
============
==============
请根据下方详细步骤，完成安装过程。
设置开发环境
~~~~~~~~~~~~
~~~~~~~~~~~~~~~~
* :ref:`get-started-setup-toolchain`
* :ref:`get-started-get-esp-idf`
@ -79,19 +80,20 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
* :ref:`get-started-get-packages`
创建您的第一个工程
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`get-started-start-project`
* :ref:`get-started-connect`
* :ref:`get-started-configure`
* :ref:`get-started-build-and-flash`
* :ref:`get-started-monitor`
* :ref:`get-started-build`
* :ref:`get-started-flash`
* :ref:`get-started-build-monitor`
.. _get-started-setup-toolchain:
第一步：设置工具链
==================
====================
工具链指一套用于编译代码和应用程序的程序。
@ -101,8 +103,8 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
:hidden:
Windows <windows-setup>
Linux <linux-setup>
MacOS <macos-setup>
Linux <linux-setup>
MacOS <macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
@ -133,12 +135,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
.. _get-started-get-esp-idf:
第二步：获取 ESP-IDF
=====================
===========================
除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
请将 ESP-IDF 下载到您的本地。
获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。
Linux 和 MacOS 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
打开终端，后运行以下命令：
.. include:: /_build/inc/git-clone-bash.inc
@ -147,6 +154,23 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
Windows 操作系统
~~~~~~~~~~~~~~~~~~
.. note::
较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
打开命令提示符，后运行以下命令：
.. include:: /_build/inc/git-clone-windows.inc
ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
.. include:: /_build/inc/git-clone-notes.inc
.. note::
@ -156,44 +180,45 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
cd esp-idf
git submodule update --init
.. _get-started-setup-path:
第三步：设置环境变量
=====================
===========================
工具链通过环境变量 ``IDF_PATH`` 获得 ESP-IDF 的目录。因此，您需要在 PC 中设置该环境变量，否则无法编译工程。
请在您的 PC 上设置以下环境变量，否则无法编译工程。
您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-idf_path-to-profile-windows>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos>` 操作系统的具体设置方式。
- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-paths-to-profile-windows>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos>` 操作系统的具体设置方式。
.. _get-started-get-packages:
第四步：安装 Python 软件包
==========================
=================================
ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
ESP-IDF 所需 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
python -m pip install --user -r $IDF_PATH/requirements.txt
.. note::
请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： ::
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如：
``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt``
.. _get-started-start-project:
第五步：开始创建工程
=====================
=======================
现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下：
Linux 和 MacOS 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
@ -201,7 +226,7 @@ Linux 和 MacOS 操作系统
cp -r $IDF_PATH/examples/get-started/hello_world .
Windows 操作系统
~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
@ -215,9 +240,9 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
ESP-IDF 编译系统不支持带有空格的路径。
.. _get-started-connect:
第六步：连接设备
==================
======================
现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。
@ -237,25 +262,33 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
.. _get-started-configure:
第七步：配置
=============
=================
请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。
Linux 和 MacOS 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: bash
cd ~/esp/hello_world
make menuconfig
idf.py menuconfig
如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。
Windows 操作系统
~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~
.. code-block:: batch
cd %userprofile%\esp\hello_world
make menuconfig
idf.py menuconfig
Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。
.. note::
如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf`。
如果之前的步骤都正确，则会显示下面的菜单：
@ -266,8 +299,6 @@ Windows 操作系统
工程配置 — 主窗口
进入菜单后，选择 ``Serial flasher config`` > ``Default serial port`` 配置串口（设备将通过该串口加载工程）。按回车键确认选择，点击 ``< Save >`` 保存配置，然后点击 ``< Exit >`` 退出 ``menuconfig``。
``menuconfig`` 工具的常见操作见下。
* ``上下箭头``：移动
@ -275,77 +306,118 @@ Windows 操作系统
* ``ESC 键``：返回上级菜单或退出
* ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项
* ``英文问号`` ：调出有关高亮选项的帮助菜单
* ``英文问号``：调出有关高亮选项的帮助菜单
* ``/ 键``：寻找配置项目
.. note::
如果您是 **Arch Linux** 用户，请前往 ``SDK tool configuration``，并将 ``Python 2 interpreter`` 的名称从 ``python`` 替换为 ``python2``。
.. attention::
如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。
.. _get-started-build-and-flash:
.. _get-started-build:
第八步：编译和烧录
第八步：编译工程
==================
请使用以下命令，编译烧录工程：::
idf.py build
运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。
.. 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'
如果一切正常，编译完成后将生成 .bin 文件。
.. _get-started-flash:
第九步：烧录到设备
====================
请使用以下命令，编译烧录工程： ::
请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： ::
make flash
idf.py -p PORT [-b BAUD] flash
运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。接着，这些二进制文件将被烧录至 ESP32 开发板。
请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。
如果一切顺利，您可在烧录完成后看到类似下方的打印信息（代表加载进程）。接着，开发板将会复位，应用程序 "hello_world" 开始启动。
您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
.. highlight:: none
更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。
::
.. note::
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。
.. code-block:: none
Running esptool.py in directory [...]/esp/hello_world
Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
esptool.py v2.3.1
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changing baud rate to 460800
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size:4MB
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 11616 bytes to 6695...
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
Hash of data verified.
Compressed 408096 bytes to 171625...
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
Compressed 22992 bytes to 13019...
Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
Hash of data verified.
Compressed 136672 bytes to 67544...
Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
Hard resetting via RTS pin...
如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。
.. note::
（目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 <eclipse-setup>`。
如果您希望使用 Eclipse IDE，而非 ``make`` 编译系统，请参考 :doc:`Eclipse 指南 <eclipse-setup>`。
.. _get-started-build-monitor:
第十步：监视器
==================
.. _get-started-monitor:
第九步：监视器
===============
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。
运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： ::
$ make monitor
MONITOR
$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit:Ctrl+] | Menu:Ctrl+T | Help:Ctrl+T followed by Ctrl+H ---
--- 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)
@ -359,7 +431,7 @@ Windows 操作系统
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start:Starting scheduler on APP CPU.
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
@ -378,69 +450,43 @@ Windows 操作系统
1. 退出监视器。
2. 打开 :ref:`menuconfig <get-started-configure>`，
3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。
4. 然后，请重新 :ref:`编译和烧录 <get-started-build-and-flash>` 应用程序。
4. 然后，请重新 :ref:`编译和烧录 <get-started-flash>` 应用程序。
.. note::
您也可以运行以下命令，一次性执行构建、烧录和监视过程： ::
您也可以运行以下命令，一次性执行构建、烧录和监视过程：
make flash monitor
``idf.py -p PORT flash monitor``
此外，请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。
此外，
- 请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。
- 请前往 :ref:`idf.py`，查看更多 ``idf.py`` 命令和选项。
**恭喜，您已完成 ESP32 的入门学习！**
现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。
环境变量
=========
用户可以在使用 ``make`` 命令时 **直接设置** 部分环境变量，而无需进入 ``make menuconfig`` 进行重新配置。这些变量包括：
+-----------------+-----------------------------------------------------------------------+
| 变量 | 描述与使用方式 |
+-----------------+-----------------------------------------------------------------------+
| ``ESPPORT`` | 覆盖 ``flash`` 和 ``monitor`` 命令使用的串口。 |
+ +-----------------------------------------------------------------------+
| | 例：``make flash ESPPORT=/dev/ttyUSB1``, ``make monitor ESPPORT=COM1``|
+-----------------+-----------------------------------------------------------------------+
| ``ESPBAUD`` | 覆盖烧录 ESP32 时使用的串口速率。 |
+ +-----------------------------------------------------------------------+
| | 例：``make flash ESPBAUD=9600`` |
+-----------------+-----------------------------------------------------------------------+
| ``MONITORBAUD`` | 覆盖监控时使用的串口速率。 |
+ +-----------------------------------------------------------------------+
| | 例：``make monitor MONITORBAUD=9600`` |
+-----------------+-----------------------------------------------------------------------+
.. note::
您可导出环境变量（例：``export ESPPORT=/dev/ttyUSB1``）。
在同一会话窗口中，如果未被同步覆盖，所有 ``make`` 命令均会使用导出的环境变量值。
更新 ESP-IDF
=============
=================
乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，在使用时，您也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。
乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。
如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH <add-idf_path-to-profile>`。否则，工具链将无法找到 ESP-IDF。
此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 <updating>` 章节查看。
相关文档
=========
===========
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
../api-guides/tools/idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases
.. _Releases page: https://github.com/espressif/esp-idf/releases

53
docs/zh_CN/get-started/linux-setup-scratch.rst
View file

@ -1,63 +1,63 @@
**********************************
******************************************
从零开始设置 Linux 环境下的工具链
**********************************
******************************************
:link_to_translation:`en:[English]`
.. note::
除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
安装工具链的标准流程可以通过阅读文档 :doc:`Linux 平台工具链的标准设置 <linux-setup>` 来获得，:ref:`工具链的自定义设置 <get-started-customized-setup>` 章节会介绍哪些情况下我们必须要重新定义工具链。
安装准备
=====================
编译 ESP-IDF 需要以下软件包：
安装必要的工具
==============
- CentOS 7::
要想使用 ESP-IDF 进行编译，您需要获取以下软件包：
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu 和 Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。
在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 <get-started-get-packages>` 章节，通过 ``pip`` 工具来安装支持的版本。
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
从源代码编译工具链
==================
=================================
- 安装依赖:
- 安装依赖：
- CentOS 7::
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
- Ubuntu pre-16.04::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
- Ubuntu 16.04::
- Ubuntu 16.04 及以上::
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- Debian 9::
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
- Arch::
TODO
新建工作目录，然后进入::
创建工作目录，并进入该目录::
mkdir -p ~/esp
cd ~/esp
下载 ``crosstool-NG`` 然后编译:
下载并编译 ``crosstool-NG`` ：
.. include:: /_build/inc/scratch-build-code.inc
@ -67,10 +67,11 @@
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Linux 下设置环境变量的标准方法 <setup-linux-toolchain-add-it-to-path>` 中的介绍，将工具链添加到 ``PATH`` 中。
编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path>` 的介绍，将工具链添加到 ``PATH``。
下一步
======
后续步骤
==========
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf>` 章节。

79
docs/zh_CN/get-started/linux-setup.rst
View file

@ -1,9 +1,8 @@
*****************************
*******************************************************************
Linux 平台工具链的标准设置
*****************************
:link_to_translation:`en:[English]`
*******************************************************************
.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
:link_to_translation:`en:[英文]`
安装前提
=====================
@ -12,65 +11,63 @@ Linux 平台工具链的标准设置
- CentOS 7::
sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial python-pyelftools
sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache
- Ubuntu and Debian::
- Ubuntu 和 Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
sudo apt-get install git wget libncurses-dev flex bison gperf python python-click python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
.. note::
一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。
在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 <get-started-get-packages>` 章节，通过 ``pip`` 工具来安装支持的版本。
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
工具链的设置
===============
=========================
.. include:: /_build/inc/download-links.inc
Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
- 64-bit Linux：
- 64 位 Linux：
|download_link_linux64|
- 32-bit Linux：
- 32 位 Linux：
|download_link_linux32|
1. 下载完成后，将它解压到 ``~/esp`` 目录： :
1. 下载完成后，将它解压到 ``~/esp`` 目录：
- 64-bit Linux:
- for 64-bit Linux:
.. include:: /_build/inc/unpack-code-linux64.inc
- 32-bit Linux:
- for 32-bit Linux:
.. include:: /_build/inc/unpack-code-linux32.inc
.. _setup-linux-toolchain-add-it-to-path:
2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中： ::
要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
或者你也可以给上面的命令创建一个别名。这样做的好处是，你只在需要使用它的时候才获取工具链。将下面这行代码添加到 ``~/.profile`` 文件中即可： ::
或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可::
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
.. note::
如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile`` 。在 CentOS 环境下, ``alias`` 需要添加到 ``.bashrc`` 文件中。
如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。
3. 退出并重新登录以使 ``.profile`` 更改生效。 运行以下命令来检查 ``PATH`` 设置是否正确： ::
3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确::
printenv PATH
@ -81,28 +78,40 @@ Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
除了 ``/home/user-name``，应该有具体的安装的主路径。
权限问题 /dev/ttyUSB0
------------------------------
某些 Linux 版本可能在烧写 ESP32 时会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。 :ref:`可以通过将当前用户添加到拨出组来解决<linux-dialout-group>`。
权限问题 /dev/ttyUSB0
----------------------------------------------
使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`
Arch Linux 用户
----------------
--------------------------------
在 Arch 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。在 AUR_ 中向下兼容的库文件，可用于本地和 lib32 的配置：
在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。
`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置：
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
在安装这些软件包之前，你可能需要将作者的公钥添加到你的钥匙圈中，上面链接中的“Comments”部分有所叙述。
在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。
或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
或者，你也可以使用 crosstool-NG 编译一个链接 ncurses 6 的 gdb。
后续步骤
==========
================
要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf` 一节。
后续开发环境设置，请参考 :ref:`get-started-get-esp-idf` 一节。
相关文档
=================
.. toctree::
:maxdepth: 1
linux-setup-scratch
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

66
docs/zh_CN/get-started/macos-setup-scratch.rst
View file

@ -1,42 +1,56 @@
**********************************
*********************************************************************
从零开始设置 Mac OS 环境下的工具链
**********************************
:link_to_translation:`en:[English]`
*********************************************************************
.. note::
安装工具链的标准流程可以通过阅读文档 :doc:`在 MacOS 上安装 ESP32 工具链 <macos-setup>` 来获得， :ref:`工具链的自定义设置 <get-started-customized-setup>` 章节会介绍哪些情况下我们必须要重新定义工具链。
:link_to_translation:`en:[英文]`
安装必要的工具
=====================
软件包管理器
======================
从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看在哪些情景下需要从头开始设置工具链。
准备工作
============================
- 安装 pip::
sudo easy_install pip
.. note::
- 安装 pyserial::
``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 <get-started-get-packages>`。
pip install --user pyserial
- 安装 CMake 和 Ninja 编译工具：
- 若使用 HomeBrew，你可以运行::
brew install cmake ninja
- 若使用 MacPorts，你可以运行::
sudo port install cmake ninja
从源代码编译工具链
==================
========================================
- 安装依赖:
- 安装 MacPorts_ 或者 homebrew_ 包管理器。MacPorts 需要安装完整的 XCode 软件，但是 homebrew 只需要安装 XCode 命令行工具即可。
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
- 相关安装：
- 对于 MacPorts::
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
- 对于 homebrew::
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
创建大小写敏感的文件系统镜像::
创建一个文件系统镜像（区分大小写）::
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
@ -49,24 +63,24 @@
mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume
进入新创建的工作目录::
前往新创建的目录：::
cd ~/esp/ctng-volume
下载 ``crosstool-NG`` 然后编译:
下载 ``crosstool-NG``，并开始编译：
.. include:: /_build/inc/scratch-build-code.inc
编译工具链::
编译工具链：::
./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path>` 中的介绍，将工具链添加到 ``PATH`` 中。
编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path>` 中的介绍，将工具链添加到 ``PATH`` 中。
下一步
======
后续步骤
=================
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf>` 章节。

69
docs/zh_CN/get-started/macos-setup.rst
View file

@ -1,54 +1,82 @@
**************************************
******************************************************************
在 Mac OS 上安装 ESP32 工具链
**************************************
:link_to_translation:`en:[English]`
******************************************************************
.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
:link_to_translation:`en:[英文]`
安装准备
================
=====================
ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
- 安装 pip::
sudo easy_install pip
- 安装 pyserial::
pip install --user pyserial
- 安装 CMake 和 Ninja 编译工具：
- 若有 HomeBrew_，你可以运行::
brew install cmake ninja
- 若有 MacPorts_，你可以运行::
sudo port install cmake ninja
- 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
.. note::
``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 <get-started-get-packages>`。
如在任一步骤中出现以下报错信息::
``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun``
你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。
安装工具链
===============
======================
.. include:: /_build/inc/download-links.inc
Mac OS 版本的 ESP32 工具链可以从以下地址下载：
下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网：
|download_link_osx|
下载压缩文件之后，解压到 ``~/esp`` 目录中:
完成下载后，请在 ``~/esp`` 目录下进行解压：
.. include:: /_build/inc/unpack-code-osx.inc
.. _setup-macos-toolchain-add-it-to-path:
工具链将被解压到 ``~/esp/xtensa-esp32-elf/`` 路径下。
此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。
在 ``~/.profile`` 文件中更新 ``PATH`` 环境变量以使用工具链。为了使 ``xtensa-esp32-elf`` 在各种终端会话中都可用，在 ``~/.profile`` 文件中加上以下指令::
为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：::
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
或者，您可以为上述命令创建一个别名。这样只有执行以下指令时工具链才能被使用。将下面的指令添加到您的 ``〜/ .profile`` 文件中::
此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令::
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
当需要使用工具链时，在命令行里输入 ``get_esp32``，就可以将工具链添加到 ``PATH`` 中。
此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。
注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。
此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确::
printenv PATH
下一步
==========
前往 :ref:`get-started-get-esp-idf` 继续配置开发环境。
后续步骤
=================
前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。
相关文档
=================
@ -58,3 +86,8 @@ Mac OS 版本的 ESP32 工具链可以从以下地址下载：
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

28
docs/zh_CN/get-started/toolchain-setup-scratch.rst
View file

@ -1 +1,27 @@
.. include:: ../../en/get-started/toolchain-setup-scratch.rst
.. _get-started-customized-setup:
*********************************************************
工具链自定义设置
*********************************************************
:link_to_translation:`en:[英文]`
除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。
如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链：
- 需要定制工具链编译配置
- 使用其他 GCC 版本（如 4.8.5）
- 需要破解 gcc、newlib 或 libstdc++
- 有相关兴趣或时间充裕
- 不信任从网站下载的 bin 文件
如需自行编译工具链，请查看以下文档：
.. toctree::
:maxdepth: 1
windows-setup-scratch
linux-setup-scratch
macos-setup-scratch

93
docs/zh_CN/get-started/windows-setup-scratch.rst
View file

@ -1 +1,92 @@
.. include:: ../../en/get-started/windows-setup-scratch.rst
******************************************************************
从零开始设置 Windows 环境下的工具链
******************************************************************
:link_to_translation:`en:[英文]`
本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 <windows-setup>` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。
使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。
.. note::
基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。
工具
=====
cmake
^^^^^
下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。
当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
Ninja 编译工具
^^^^^^^^^^^^^^^^^^^^
.. note::
Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。
从（`下载页面 <ninja-dl>`_）下载最新发布的 Windows 平台稳定版 `ninja`_。
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 <add-directory-windows-path>`_ （或者选择你的路径中已有的目录）。
Python 2.x
^^^^^^^^^^
下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。
Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。
Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令::
pip install --user pyserial
适用于 IDF 的 MConf
^^^^^^^^^^^^^^^^^^^^^^
从 `kconfig-frontends 发布页面 <mconf-idf>`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。
你需将此工具解压到目录，然后 `添加到你的路径 <add-directory-windows-path>`_。
工具链设置
===============
.. include:: /_build/inc/download-links.inc
下载预编译的 Windows 平台工具链：
|download_link_win32|
解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。
然后，须将该目录下的子目录 ``bin`` `添加到你的路径 <add-directory-windows-path>`_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
.. note::
如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
.. _add-directory-windows-path:
添加目录到路径
========================
添加任何新目录到你的 Windows Path 环境变量：
打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。
双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
后续步骤
================
要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
.. _ninja: https://ninja-build.org/
.. _Python: https://www.python.org/downloads/windows/
.. _MSYS2: https://msys2.github.io/

3
docs/zh_CN/get-started/windows-setup-update.rst Normal file
View file

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

75
docs/zh_CN/get-started/windows-setup.rst
View file

@ -1,64 +1,60 @@
***************************************
**********************************************************
Windows 平台工具链的标准设置
***************************************
:link_to_translation:`en:[English]`
**********************************************************
.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
:link_to_translation:`en:[英文]`
.. note::
基于 CMake 的构建系统仅支持 64 位版本 Windows。
引言
============
Windows 没有内置的 "make" 环境，因此如果要安装工具链，你需要一个 GNU 兼容环境。我们这里使用 MSYS2_ 来提供该环境。你不需要一直使用这个环境（你可以使用 :doc:`Eclipse <eclipse-setup>` 或其它前端工具），但是它是在后台运行的。
ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。
工具链的设置
===============
快速设置的方法是从 dl.espressif.com 下载集成在一起的工具链和 MSYS2 压缩文件：
在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse <eclipse-setup>` 或支持 CMake 的图形化工具 IDE。
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
将 zip 压缩文件解压到 ``C:\`` (或其它路径，这里假设是 ``C:\``)，它会使用预先准备的环境创建一个 ``msys32`` 目录。
ESP-IDF 工具安装器
=======================
检出
============
安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
运行 ``C:\msys32\mingw32.exe`` 打开一个 MSYS2 的终端窗口。该窗口的环境是一个 bash shell。创建一个 ``esp`` 目录作为开发 ESP32 应用的默认地址。运行指令 ::
https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe
mkdir -p ~/esp
输入 ``cd ~/esp`` 就进入到新创建的目录。如果没有错误信息出现则表明此步骤已完成。
安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。
安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。
MSYS2 终端窗口
安装 Git
==============
后续步骤将会使用这个窗口来为 ESP32 设置开发环境。
ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。
如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。
使用终端
================
在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符：
- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。
- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。
- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。
后续步骤
==========
要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf` 一节。
更新环境
========================
当 IDF 更新时，有时需要新的工具链，或者将新的需求添加到 Windows MSYS2 环境中。要将旧版本的预编译环境中的数据移动到新版本：
- 把旧的 MSYS2 环境（即 ``C:\msys32``）移动/重命名为不同的目录（即 ``C:\msys32_old``）。
- 按照前文所述步骤下载新的预编译环境。
- 将新的 MSYS2 环境解压缩到 ``C:\msys32`` （或其他位置）。
- 找到旧的 ``C:\msys32_old\home`` 目录并把它移到 ``C:\msys32``。
- 如果你不再需要 ``C:\msys32_old`` 可以将它删除。
你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。
要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
相关文档
=================
想要自定义安装流程的高阶用户可参照：
.. toctree::
:maxdepth: 1
@ -66,4 +62,9 @@ https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611
.. _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/

3
docs/zh_CN/gnu-make-legacy.rst Normal file
View file

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

2
docs/zh_CN/hw-reference/get-started-ethernet-kit.rst
View file

@ -342,7 +342,7 @@ ESP32-Ethernet-Kit 上电前，请首先确认开发板完好无损。
正式开始开发
^^^^^^^^^^^^^^^^^^
现在，请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。
现在，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。
如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。

2
docs/zh_CN/index.rst
View file

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

2
examples/build_system/cmake/idf_as_lib/README.md
View file

@ -67,4 +67,4 @@ or
---
There is a discussion on using ESP-IDF in custom CMake projects in the programming guide under `API Guides` -> `Build System (CMake)` -> `Using ESP-IDF in Custom CMake Projects`
There is a discussion on using ESP-IDF in custom CMake projects in the programming guide under `API Guides` -> `Build System` -> `Using ESP-IDF in Custom CMake Projects`

2
examples/build_system/cmake/import_lib/README.md
View file

@ -33,4 +33,4 @@ I (677) example: Example end
```
---
There is a discussion on importing third-party CMake libraries in the programming guide under `API Guides` -> `Build System (CMake)` -> `Using Third-Party CMake Projects with Components`
There is a discussion on importing third-party CMake libraries in the programming guide under `API Guides` -> `Build System` -> `Using Third-Party CMake Projects with Components`

4
tools/unit-test-app/README.md
View file

@ -26,9 +26,9 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un
# Flash Size
The unit test partition table assumes a 4MB flash size. When testing `TESTS_ALL=1` (Make) or `-T all` (CMake), this additional factory app partition size is required.
The unit test partition table assumes a 4MB flash size. When testing `-T all` or `TESTS_ALL=1` (Legacy GNU Make) or, this additional factory app partition size is required.
If building unit tests to run on a smaller flash size, edit `partition_table_unit_tests_app.csv` and use `TEST_COMPONENTS=` (Make) or `-T <component> <component> ...` (CMake) instead of `TESTS_ALL` or `-T all` if tests don't fit in a smaller factory app partition (exact size will depend on configured options).
If building unit tests to run on a smaller flash size, edit `partition_table_unit_tests_app.csv` and use `-T <component> <component> ...` or `TEST_COMPONENTS=` (Legacy GNU Make) or instead of `-T all` or `TESTS_ALL` if tests don't fit in a smaller factory app partition (exact size will depend on configured options).
# Running Unit Tests