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

doc: Update English pages with generic target name

Browse source
This commit is contained in:
Marius Vikhammer 2019-12-09 11:01:09 +08:00 committed by Angus Gratton
parent c848aa74ac
commit 9352899d69
72 changed files with 1346 additions and 1175 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/conf_common.py
View file

@ -135,9 +135,15 @@ def update_exclude_patterns(tags):
'api-guides/jtag-debugging/configure-wrover.rst',
'api-reference/bluetooth/**',
'api-reference/system/himem.rst',
'api-reference/system/ipc.rst',
'hw-reference/get-started-devkitc-v2.rst',
'hw-reference/get-started-devkitc.rst',
'hw-reference/get-started-ethernet-kit-v1.0.rst',
'hw-reference/get-started-ethernet-kit.rst',
'hw-reference/get-started-pico-kit-v3.rst',
'hw-reference/get-started-pico-kit.rst',
'hw-reference/get-started-wrover-kit-v2.rst',
'hw-reference/get-started-wrover-kit-v3.rst',
'hw-reference/get-started-wrover-kit.rst',
'get-started-legacy/**',
'gnu-make-legacy.rst']:

15
docs/en/about.rst
View file

@ -2,9 +2,18 @@ About
=====
:link_to_translation:`zh_CN:[中文]`
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
.. only:: esp32
The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power.
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `{IDF_TARGET_NAME} <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
The {IDF_TARGET_NAME} is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power.
.. only:: esp32s2
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for {IDF_TARGET_NAME}.
The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi module, which integrates a 32-bit microprocessors, with up to 600 DMIPS processing power.
.. figure:: ../_static/about-doc.png
:align: center
@ -13,5 +22,5 @@ The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-b
Espressif IoT Integrated Development Framework
The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems.
The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for {IDF_TARGET_NAME} using Windows, Linux and Mac OS operating systems.

7
docs/en/api-guides/RF_calibration.rst
View file

@ -1,7 +1,7 @@
RF calibration
==============
ESP32 supports three RF calibration methods during RF initialization:
{IDF_TARGET_NAME} supports three RF calibration methods during RF initialization:
1. Partial calibration
@ -41,14 +41,15 @@ If you use the default method of RF calibration, there are two ways to add the f
No calibration
---------------
No calibration method is only used when ESP32 wakes up from deep sleep.
No calibration method is only used when {IDF_TARGET_NAME} wakes up from deep sleep.
PHY initialization data
-----------------------
The PHY initialization data is used for RF calibration.
There are two ways to get the PHY initialization data.
One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/esp32/include/phy_init_data.h`.
One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`.
It is embedded into the application binary after compiling and then stored into read-only memory (DROM).
To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`.

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

@ -5,7 +5,7 @@ Application Level Tracing library
Overview
--------
IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution.
IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution.
Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
@ -31,7 +31,7 @@ The library supports two modes of operation:
**Post-mortem mode**. This is the default mode. The mode does not need interaction with the host side. In this mode tracing module does not check whether host has read all the data from *HW UP BUFFER* buffer and overwrites old data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for analyzing program's behavior just before the crash. Host can read the data later on upon user request, e.g. via special OpenOCD command in case of working via JTAG interface.
**Streaming mode.** Tracing module enters this mode when host connects to ESP32. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities.
**Streaming mode.** Tracing module enters this mode when host connects to {IDF_TARGET_NAME}. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities.
Configuration Options and Dependencies
@ -55,7 +55,7 @@ There are two additional menuconfig options not mentioned above:
How to use this library
-----------------------
This library provides API for transferring arbitrary data between host and ESP32. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data.
This library provides API for transferring arbitrary data between host and {IDF_TARGET_NAME}. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data.
.. _app_trace-application-specific-tracing:
@ -326,7 +326,7 @@ How To Use It
Support for this feature is enabled by *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* (:ref:`CONFIG_SYSVIEW_ENABLE`) menuconfig option. There are several other options enabled under the same menu:
1. *ESP32 timer to use as SystemView timestamp source* (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns.
1. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns.
2. Individually enabled or disabled collection of SystemView events (``CONFIG_SYSVIEW_EVT_XXX``):
- Trace Buffer Overflow Event
@ -405,7 +405,7 @@ Command usage examples:
Data Visualization
""""""""""""""""""
After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32 working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool.
After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from {IDF_TARGET_NAME} working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool.
It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is Eclipse plugin called *Impulse* which can load several trace files and makes it possible to inspect events from both cores in one view. Also this plugin has no limitation of 1,000,000 events as compared to free version of SystemView.
@ -511,15 +511,12 @@ ESP-IDF supports two methods of dumping code coverage data form the target to th
Instant Run-Time Dump
~~~~~~~~~~~~~~~~~~~~~
An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the ESP32's current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the ESP32 will resume it's current state.
.. note::
Due to the use of the debug stub function, the OpenOCD Debug Stub option must be enabled in project configuration. The option can be found under ``Component config -> ESP32-specific -> OpenOCD debug stubs``.
An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the {IDF_TARGET_NAME}'s current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the {IDF_TARGET_NAME} will resume it's current state.
Hard-coded Dump
~~~~~~~~~~~~~~~
A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the ESP32, retrieve the code coverage data, then disconnect from the ESP32 thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime.
A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the {IDF_TARGET_NAME}, retrieve the code coverage data, then disconnect from the {IDF_TARGET_NAME} thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime.
Hard-coded dumps are useful if code coverage data is required at certain points of an application's lifetime by placing :cpp:func:`esp_gcov_dump` where necessary (e.g., after application initialization, during each iteration of an application's main loop).

58
docs/en/api-guides/blufi.rst
View file

@ -4,7 +4,7 @@ BluFi
Overview
--------
The BluFi for ESP32 is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the ESP32. Using this information ESP32 can then e.g. connect to an AP or establish a SoftAP.
The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the {IDF_TARGET_NAME}. Using this information {IDF_TARGET_NAME} can then e.g. connect to an AP or establish a SoftAP.
Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process.
@ -16,29 +16,29 @@ The BluFi networking flow includes the configuration of the SoftAP and Station.
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, connection status backhaul.
1. Set the ESP32 into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
1. Set the {IDF_TARGET_NAME} into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to ESP32 as the GATT Client once the broadcast is confirmed. The App used during this part is up to you.
2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to {IDF_TARGET_NAME} as the GATT Client once the broadcast is confirmed. The App used during this part is up to you.
3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to ESP32 (see the section :ref:`frame_formats` for details).
3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to {IDF_TARGET_NAME} (see the section :ref:`frame_formats` for details).
4. After ESP32 receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
4. After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
5. The mobile phone works with ESP32 for key negotiation using the encryption algorithms such as DH, RSA or ECC.
5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms such as DH, RSA or ECC.
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to ESP32.
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}.
7. When receiving this control frame, ESP32 will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
7. When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to ESP32, including SSID, password, etc.
8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc.
9. The mobile phone sends a control frame of Wi-Fi connection request to ESP32. When receiving this control frame, ESP32 will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
10. After connecting to the Wi-Fi, ESP32 will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed.
10. After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed.
.. note::
1. After ESP32 receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode.
1. After {IDF_TARGET_NAME} receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode.
2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption.
@ -57,16 +57,16 @@ The flow chart of BluFi
span_height = 10;
default_fontsize = 12;
Phone <- ESP32 [label="Advertising"];
Phone -> ESP32 [label="Create GATT connection"];
Phone <- ESP32 [label="Negotiate key procedure"];
Phone -> ESP32 [label="Negotiate key procedure"];
Phone -> ESP32 [label="CTRL: Set ESP32 to Phone Security mode"];
Phone -> ESP32 [label="DATA: SSID"];
Phone -> ESP32 [label="DATA: Password"];
Phone -> ESP32 [label="DATA: Other information, such as CA certification"];
Phone -> ESP32 [label="CTRL: Connect to AP"];
Phone <- ESP32 [label="DATA: Connection State Report"];
Phone <- {IDF_TARGET_NAME} [label="Advertising"];
Phone -> {IDF_TARGET_NAME} [label="Create GATT connection"];
Phone <- {IDF_TARGET_NAME} [label="Negotiate key procedure"];
Phone -> {IDF_TARGET_NAME} [label="Negotiate key procedure"];
Phone -> {IDF_TARGET_NAME} [label="CTRL: Set {IDF_TARGET_NAME} to Phone Security mode"];
Phone -> {IDF_TARGET_NAME} [label="DATA: SSID"];
Phone -> {IDF_TARGET_NAME} [label="DATA: Password"];
Phone -> {IDF_TARGET_NAME} [label="DATA: Other information, such as CA certification"];
Phone -> {IDF_TARGET_NAME} [label="CTRL: Connect to AP"];
Phone <- {IDF_TARGET_NAME} [label="DATA: Connection State Report"];
}
.. _frame_formats:
@ -74,7 +74,7 @@ The flow chart of BluFi
The Frame Formats Defined in BluFi
-----------------------------------
The frame formats for the communication between the mobile phone App and ESP32 are defined as follows:
The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows:
The frame format with no fragment (8 bit)：
@ -391,8 +391,8 @@ The format of Ack Frame（8 bit）：
This field takes 2 bytes that is used to check "sequence + data length + clear text data".
The Security Implementation of ESP32
-------------------------------------
The Security Implementation of {IDF_TARGET_NAME}
------------------------------------------------
1. Securing data
@ -410,7 +410,7 @@ The Security Implementation of ESP32
It is added to the Sequence field and used during the checksum verification.
For the coding of ESP32, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to ESP32 and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME} and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
The application layer needs to register several security-related functions to BluFi:
@ -418,7 +418,7 @@ The Security Implementation of ESP32
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
This function is for ESP32 to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len.
This function is for {IDF_TARGET_NAME} to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len.
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
@ -450,6 +450,6 @@ UUID
BluFi Service UUID: 0xFFFF，16 bit
BluFi (the mobile -> ESP32): 0xFF01, writable
BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable
Blufi (ESP32 -> the mobile phone): 0xFF02, readable and callable
Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable

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

@ -22,7 +22,7 @@ Overview
An ESP-IDF project can be seen as an amalgamation of a number of components.
For example, for a webserver that shows the current humidity, there could be:
- The ESP32 base libraries (libc, rom bindings etc)
- The {IDF_TARGET_NAME} base libraries (libc, rom bindings etc)
- The Wi-Fi drivers
- A TCP/IP stack
- The FreeRTOS operating system

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

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

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

@ -1,9 +1,15 @@
ESP32 Core Dump
===============
{IDF_TARGET_NAME} Core Dump
===========================
Overview
--------
.. only:: esp32s2
.. note::
The python utility does not currently support ESP32-S2
ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows post-mortem analysis of software state at the moment of failure.
Upon the crash system enters panic state, prints some information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse
the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure. Snapshots include tasks control blocks (TCB) and stacks.

8
docs/en/api-guides/deep-sleep-stub.rst
View file

@ -1,7 +1,7 @@
Deep Sleep Wake Stubs
=====================
ESP32 supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally.
{IDF_TARGET_NAME} supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally.
Deep sleep wake stub code is loaded into "RTC Fast Memory" and any data which it uses must also be loaded into RTC memory. RTC memory regions hold their contents during deep sleep.
@ -33,7 +33,7 @@ It is not necessary to implement ``esp_wake_deep_sleep()`` in your app in order
If you want to swap between different deep sleep stubs at runtime, it is also possible to do this by calling the ``esp_set_deep_sleep_wake_stub()`` function. This is not necessary if you only use the default ``esp_wake_deep_sleep()`` function.
All of these functions are declared in the ``esp_deepsleep.h`` header under components/esp32.
All of these functions are declared in the ``esp_sleep.h`` header under components/{IDF_TARGET_PATH_NAME}.
Loading Code Into RTC Memory
----------------------------
@ -69,9 +69,11 @@ The first way is to use the ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` to specify
ets_printf(fmt_str, wake_count++);
}
.. only:: esp32
The RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_ESP32_RTCDATA_IN_FAST_MEM``. This option allows to keep slow memory area for ULP programs and once it is enabled the data marked with ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` are placed in the RTC fast memory segment otherwise it goes to RTC slow memory (default option). This option depends on the ``CONFIG_FREERTOS_UNICORE`` because RTC fast memory can be accessed only by PRO_CPU.
The similar attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it.
The attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it.
Unfortunately, any string constants used in this way must be declared as arrays and marked with RTC_RODATA_ATTR, as shown in the example above.

4
docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst
View file

@ -647,8 +647,8 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP
The examples use :cpp:func:`ESP_LOG_BUFFER_HEX` to print the message context while the ESP-BLE-MESH protocol stack uses :cpp:func:`bt_hex`.
7.2 Which API can be used to restart ESP32?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7.2 Which API can be used to restart {IDF_TARGET_NAME}?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The API :cpp:func:`esp_restart`.

10
docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst
View file

@ -18,7 +18,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.
.. note::
If you are looking for Wi-Fi based implementation of mesh for ESP32, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`.
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`.
.. _getting-started-with-ble-mesh:
@ -26,7 +26,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.
Getting Started with ESP-BLE-MESH
=================================
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32 chip by Espressif.
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif.
We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes.
@ -38,14 +38,14 @@ What You Need
Hardware:
* Three ESP32 boards, see :ref:`options <get-started-ble-mesh-check-hardware>`.
* Three {IDF_TARGET_NAME} boards, see :ref:`options <get-started-ble-mesh-check-hardware>`.
* USB cables to connect the boards.
* Computer configured with ESP-IDF.
* Mobile phone or tablet running Android or iOS.
Software:
* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ESP32 boards.
* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ${IDF_TARGET_NAME} boards.
* Mobile App: **nRF Mesh** for Android or iOS. Optionally you can use some other Apps:
- `EspBleMesh <https://github.com/EspressifApp/EspBLEMeshForAndroid/releases/tag/v1.0.0>`_ Android App
@ -219,7 +219,7 @@ ESP-BLE-MESH Examples
* ESP-BLE-MESH Fast Provisioning - :example:`Client <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>` and :example:`Server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server>`.
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of ESP32. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
* ESP-BLE-MESH Node Console - an example that implements BLE Mesh node basic features. Within this example a node can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see :example:`example node code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_node>` and :example:`example Provisioner code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_provisioner>`.

12
docs/en/api-guides/external-ram.rst
View file

@ -9,15 +9,15 @@ Support for external RAM
Introduction
============
ESP32 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so ESP32 has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM.
{IDF_TARGET_NAME} has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so {IDF_TARGET_NAME} has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM.
Hardware
========
ESP32 supports SPI PSRAM connected in parallel with the SPI flash chip. While ESP32 is capable of supporting several types of RAM chips, the ESP32 SDK only supports the ESP-PSRAM32 chip at the moment.
{IDF_TARGET_NAME} supports SPI PSRAM connected in parallel with the SPI flash chip. While {IDF_TARGET_NAME} is capable of supporting several types of RAM chips, ESP-IDF only supports the ESP-PSRAM32 chip at the moment.
The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program ESP32 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.
The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.
To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals:
@ -50,10 +50,10 @@ ESP-IDF fully supports the use of external memory in applications. Once the exte
.. _external_ram_config_memory_map:
Integrate RAM into the ESP32 memory map
---------------------------------------
Integrate RAM into the {IDF_TARGET_NAME} memory map
---------------------------------------------------
Select this option by choosing "Integrate RAM into ESP32 memory map" from :ref:`CONFIG_SPIRAM_USE`.
Select this option by choosing "Integrate RAM into memory map" from :ref:`CONFIG_SPIRAM_USE`.
This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced option.

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

@ -38,13 +38,7 @@ For some of the system level checks (interrupt watchdog, cache access error), th
In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes.
.. only:: esp32
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are:
.. only:: esp32s2
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32S2_PANIC` configuration choice. The available options are:
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` configuration choice. The available options are:
- Print registers and reboot — default option.
@ -64,13 +58,7 @@ In all cases, error cause will be printed in parens. See `Guru Meditation Errors
Behavior of panic handler is affected by two other configuration options.
.. only:: esp32
- If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
.. only:: esp32s2
- If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
- If :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
- If :doc:`Core Dump <core_dump>` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis.
@ -126,7 +114,7 @@ The following diagram illustrates panic handler behavior:
Register Dump and Backtrace
---------------------------
Unless ``CONFIG_ESP32_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console::
Unless ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console::
Core 0 register dump:
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
@ -163,14 +151,14 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050
0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36
0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32/cpu_start.c:470
0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470
To find the location where a fatal error has happened, look at the lines which follow the "Backtrace" line. Fatal error location is the top line, and subsequent lines show the call stack.
GDB Stub
--------
If ``CONFIG_ESP32_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port.
If ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port.
If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this::
@ -181,7 +169,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-esp32-elf".
This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
@ -222,7 +210,7 @@ Most common reasons for this error include:
- Application has reconfigured SPI flash pins as some other function (GPIO, UART, etc.). Consult Hardware Design Guidelines and the Datasheet for the chip or module for details about SPI flash pins.
- Some external device was accidentally connected to SPI flash pins, and has interfered with communication between ESP32 and SPI flash.
- Some external device was accidentally connected to SPI flash pins, and has interfered with communication between {IDF_TARGET_NAME} and SPI flash.
InstrFetchProhibited
@ -277,13 +265,7 @@ Other Fatal Errors
Brownout
^^^^^^^^
.. only:: esp32
ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options.
.. only:: esp32s2
ESP32-S2 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32S2_BROWNOUT_DET` and :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` options.
{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET` and :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET_LVL_SEL` options.
When brownout detector triggers, the following message is printed::

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

@ -4,6 +4,8 @@ ESP-IDF FreeRTOS SMP Changes
Overview
--------
.. only:: esp32
The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is
dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an
Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are
@ -23,6 +25,8 @@ see :doc:`ESP-IDF FreeRTOS Additions<../api-reference/system/freertos_additions>
port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported
to ESP-IDF.
.. only:: esp32
:ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or
:cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The
last parameter of the two functions is ``xCoreID``. This parameter specifies
@ -53,7 +57,7 @@ scheduler and interrupts of the calling core. However the other core is left
unaffected. If the other core attemps to take same mutex, it will spin until
the calling core has released the mutex by exiting the critical section.
:ref:`floating-points`: The ESP32 supports hardware acceleration of single
:ref:`floating-points`: The {IDF_TARGET_NAME} supports hardware acceleration of single
precision floating point arithmetic (``float``). However the use of hardware
acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS.
Therefore, tasks that utilize ``float`` will automatically be pinned to a core if
@ -134,6 +138,8 @@ the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can als
called.
.. _tasks-and-task-creation:
Tasks and Task Creation
@ -349,6 +355,8 @@ context switches and servicing of ISRs during a critical section. Therefore,
critical sections are used as a valid protection method against simultaneous
access in vanilla FreeRTOS.
.. only:: esp32
On the other hand, the ESP32 has no hardware method for cores to disable each
other’s interrupts. Calling ``portDISABLE_INTERRUPTS()`` will have no effect on
the interrupts of the other core. Therefore, disabling interrupts is **NOT**
@ -356,8 +364,13 @@ a valid protection method against simultaneous access to shared data as it
leaves the other core free to access the data even if the current core has
disabled its own interrupts.
.. only:: esp32s2
ESP-IDF contains some modifications to work with dual core concurrency,
and the dual core API is used even on a single core only chip.
For this reason, ESP-IDF FreeRTOS implements critical sections using special mutexes,
referred by portMUX_Type objects on top of specific ESP32 spinlock component
referred by portMUX_Type objects on top of specific spinlock component
and calls to enter or exit a critical must provide a spinlock object that
is associated with a shared resource requiring access protection.
When entering a critical section in ESP-IDF FreeRTOS, the calling core will disable
@ -394,16 +407,13 @@ spinlock is provided upon entering and exiting, the type of call should not
matter.
.. only:: esp32
.. _floating-points:
Floating Point Aritmetic
Floating Point Arithmetic
------------------------
The ESP32 supports hardware acceleration of single precision floating point
arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors)
attached to each core. The use of the FPUs imposes some behavioral restrictions
on ESP-IDF FreeRTOS.
ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words,
the state of a core's FPU registers are not immediately saved when a context
switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a
@ -419,7 +429,6 @@ behavioral restrictions with regards to ``float`` do not apply to ``double``. No
that due to the lack of hardware acceleration, ``double`` operations may consume
significantly larger amount of CPU time in comparison to ``float``.
.. _task-deletion:
Task Deletion
@ -489,7 +498,7 @@ ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>`
:ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only
on **PRO_CPU**. Note that this is **not equivalent to running vanilla
FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such
as :component_file:`esp32/cpu_start.c`. For more details regarding the
as :component_file:`{IDF_TARGET_PATH_NAME}/cpu_start.c`. For more details regarding the
effects of running ESP-IDF FreeRTOS on a single core, search for
occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components.

12
docs/en/api-guides/general-notes.rst
View file

@ -18,7 +18,7 @@ This process is explained in detail in the following sections.
First stage bootloader
^^^^^^^^^^^^^^^^^^^^^^
After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the ESP32 chip and can not be modified.
After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the {IDF_TARGET_NAME} chip and can not be modified.
Startup code called from the reset vector determines the boot mode by checking ``GPIO_STRAP_REG`` register for bootstrap pin states. Depending on the reset reason, the following takes place:
@ -35,7 +35,7 @@ Application binary image is loaded from flash starting at address 0x1000. First
Second stage bootloader
^^^^^^^^^^^^^^^^^^^^^^^
In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the ESP32 chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place.
In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the {IDF_TARGET_NAME} chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place.
When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header.
@ -48,9 +48,9 @@ Currently it is not possible to add application-defined hooks to the bootloader
Application startup
^^^^^^^^^^^^^^^^^^^
ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/esp32/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function.
ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function.
Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/esp32/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started.
Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started.
While PRO CPU does initialization in ``start_cpu0`` function, APP CPU spins in ``start_cpu1`` function, waiting for the scheduler to be started on the PRO CPU. Once the scheduler is started on the PRO CPU, code on the APP CPU starts the scheduler as well.
@ -61,7 +61,7 @@ Main task is the task which runs ``app_main`` function. Main task stack size and
Application memory layout
-------------------------
ESP32 chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default.
{IDF_TARGET_NAME} chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default.
Application code in ESP-IDF can be placed into one of the following memory regions.
@ -85,7 +85,7 @@ Here are the cases when parts of application may or should be placed into IRAM.
- Interrupt handlers must be placed into IRAM if ``ESP_INTR_FLAG_IRAM`` is used when registering the interrupt handler. In this case, ISR may only call functions placed into IRAM or functions present in ROM. *Note 1:* all FreeRTOS APIs are currently placed into IRAM, so are safe to call from interrupt handlers. If the ISR is placed into IRAM, all constant data used by the ISR and functions called from ISR (including, but not limited to, ``const char`` arrays), must be placed into DRAM using ``DRAM_ATTR``.
- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. ESP32 reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss.
- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. {IDF_TARGET_NAME} reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss.
IROM (code executed from Flash)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

@ -4,7 +4,7 @@ High-Level Interrupts
.. toctree::
:maxdepth: 1
The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the ESP32, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies.
The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the {IDF_TARGET_NAME}, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies.
Interrupt Levels
----------------
@ -31,8 +31,8 @@ Using these symbols is done by creating an assembly file (suffix .S) and definin
rsr a0, EXCSAVE_5
rfi 5
For a real-life example, see the :component_file:`{IDF_TARGET_PATH_NAME}/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there.
For a real-life example, see the :component_file:`esp32/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there.
Notes
-----

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

@ -15,7 +15,7 @@ API Guides
Error Handling <error-handling>
:esp32: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
ESP32 Core Dump <core_dump>
{IDF_TARGET_NAME} Core Dump <core_dump>
Event Handling <event-handling>
External SPI-connected RAM <external-ram>
Fatal Errors <fatal-errors>

4
docs/en/api-guides/jtag-debugging/building-openocd-linux.rst
View file

@ -11,7 +11,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E
Download Sources of OpenOCD
===========================
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
cd ~/esp
git clone --recursive https://github.com/espressif/openocd-esp32.git
@ -73,4 +73,4 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will
Next Steps
==========
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.

5
docs/en/api-guides/jtag-debugging/building-openocd-macos.rst
View file

@ -10,7 +10,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E
Download Sources of OpenOCD
===========================
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
cd ~/esp
git clone --recursive https://github.com/espressif/openocd-esp32.git
@ -50,6 +50,5 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will
Next Steps
==========
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.

4
docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
View file

@ -29,7 +29,7 @@ Install packages that are required to compile OpenOCD::
Download Sources of OpenOCD
===========================
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
cd ~/esp
git clone --recursive https://github.com/espressif/openocd-esp32.git
@ -110,4 +110,4 @@ A complete described previously process is provided below for the faster executi
Next Steps
==========
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.

46
docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
View file

@ -2,33 +2,53 @@ Configure Other JTAG Interface
==============================
:link_to_translation:`zh_CN:[中文]`
Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and ESP32. Then follow three configuration steps below to get it working.
Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and {IDF_TARGET_NAME}. Then follow three configuration steps below to get it working.
Configure Hardware
^^^^^^^^^^^^^^^^^^
1. Identify all pins / signals on JTAG interface and ESP32 board, that should be connected to establish communication.
1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
+---+---------------+-------------+
.. only:: esp32
+---+-----------------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+===============+=============+
+===+=======================+=============+
| 1 | CHIP_PU | TRST_N |
+---+---------------+-------------+
+---+-----------------------+-------------+
| 2 | MTDO / GPIO15 | TDO |
+---+---------------+-------------+
+---+-----------------------+-------------+
| 3 | MTDI / GPIO12 | TDI |
+---+---------------+-------------+
+---+-----------------------+-------------+
| 4 | MTCK / GPIO13 | TCK |
+---+---------------+-------------+
+---+-----------------------+-------------+
| 5 | MTMS / GPIO14 | TMS |
+---+---------------+-------------+
+---+-----------------------+-------------+
| 6 | GND | GND |
+---+---------------+-------------+
+---+-----------------------+-------------+
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
.. only:: esp32s2
3. Connect identified pin / signals of ESP32 and JTAG interface.
+---+-----------------------+-------------+
| | ESP32-S2 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | CHIP_PU | TRST_N |
+---+-----------------------+-------------+
| 2 | MTDO / GPIO40 | TDO |
+---+-----------------------+-------------+
| 3 | MTDI / GPIO41 | TDI |
+---+-----------------------+-------------+
| 4 | MTCK / GPIO39 | TCK |
+---+-----------------------+-------------+
| 5 | MTMS / GPIO42 | TMS |
+---+-----------------------+-------------+
| 6 | GND | GND |
+---+-----------------------+-------------+
2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
3. Connect identified pin / signals of {IDF_TARGET_NAME} and JTAG interface.
Configure Drivers
@ -39,7 +59,7 @@ You may need to install driver s/w to make JTAG work with computer. Refer to doc
Connect
^^^^^^^
Connect JTAG interface to the computer. Power on ESP32 and JTAG interface boards. Check if JTAG interface is visible by computer.
Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if JTAG interface is visible by computer.
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.

31
docs/en/api-guides/jtag-debugging/debugging-examples.rst
View file

@ -150,10 +150,17 @@ See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of
Checking and setting memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^
To display or set contents of memory use "Memory" tab at the bottom of "Debug" perspective.
With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
.. only:: esp32
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
.. only:: esp32s2beta
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog.
@ -272,7 +279,7 @@ You can use ``bt`` or ``backtrace`` to see what function calls lead up to this c
(gdb) bt
#0 app_main () at /home/user-name/esp/blink/main/./blink.c:43
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339
(gdb)
Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``.
@ -280,7 +287,7 @@ Line #0 of output provides the last function call before the application halted,
To get to the context of ``main_task`` in file ``cpu_start.c``, enter ``frame N``, where N = 1, because the ``main_task`` is listed under #1)::
(gdb) frame 1
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339
339 app_main();
(gdb)
@ -324,14 +331,14 @@ To see the other code, enter ``i threads``. This will show the list of threads r
(gdb) i threads
Id Target Id Frame
8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=<optimized out>)
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170
at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:170
7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200,
xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452
6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0)
at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445
5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? ()
4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0)
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150
at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:150
3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0)
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0)
@ -438,7 +445,7 @@ To check it delete all breakpoints and enter ``c`` to resume application. Then e
Program received signal SIGINT, Interrupt.
[Switching to Thread 1073413512]
0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52
0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52
52 asm("waiti 0");
(gdb)
@ -513,7 +520,15 @@ Checking and setting memory
Displaying the contents of memory is done with command ``x``. With additional parameters you may vary the format and count of memory locations displayed. Run ``help x`` to see more details. Companion command to ``x`` is ``set`` that let you write values to the memory.
We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
.. only:: esp32
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
.. only:: esp32s2beta
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location::

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

@ -2,18 +2,18 @@ JTAG Debugging
==============
:link_to_translation:`zh_CN:[中文]`
This document provides a guide to installing OpenOCD for ESP32 and debugging using
This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using
GDB. The document is structured as follows:
:ref:`jtag-debugging-introduction`
Introduction to the purpose of this guide.
:ref:`jtag-debugging-how-it-works`
Description how ESP32, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of ESP32.
Description how {IDF_TARGET_NAME}, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of {IDF_TARGET_NAME}.
:ref:`jtag-debugging-selecting-jtag-adapter`
What are the criteria and options to select JTAG adapter hardware.
:ref:`jtag-debugging-setup-openocd`
Procedure to install OpenOCD and verify that it is installed.
:ref:`jtag-debugging-configuring-esp32-target`
:ref:`jtag-debugging-configuring-target`
Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target.
:ref:`jtag-debugging-launching-debugger`
Steps to start up a debug session with GDB from :ref:`jtag-debugging-using-debugger-eclipse` and from :ref:`jtag-debugging-using-debugger-command-line`.
@ -22,7 +22,7 @@ GDB. The document is structured as follows:
:ref:`jtag-debugging-building-openocd`
Procedure to build OpenOCD from sources for :doc:`Windows <building-openocd-windows>`, :doc:`Linux <building-openocd-linux>` and :doc:`MacOS <building-openocd-macos>` operating systems.
:ref:`jtag-debugging-tips-and-quirks`
This section provides collection of tips and quirks related JTAG debugging of ESP32 with OpenOCD and GDB.
This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
.. _jtag-debugging-introduction:
@ -30,13 +30,15 @@ GDB. The document is structured as follows:
Introduction
------------
.. only:: esp32
The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software.
The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port.
Espressif has ported OpenOCD to support the ESP32 processor and the multicore FreeRTOS, which will be the foundation of most ESP32 apps, and has written some tools to help with features OpenOCD does not support natively.
Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multicore FreeRTOS, which will be the foundation of most {IDF_TARGET_NAME} apps, and has written some tools to help with features OpenOCD does not support natively.
This document provides a guide to installing OpenOCD for ESP32 and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems.
This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems.
.. note::
@ -47,7 +49,7 @@ This document provides a guide to installing OpenOCD for ESP32 and debugging usi
How it Works?
-------------
The key software and hardware to perform debugging of ESP32 with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes **xtensa-esp32-elf-gdb debugger**, **OpenOCD on chip debugger** and **JTAG adapter** connected to **ESP32** target.
The key software and hardware to perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb debugger, OpenOCD on chip debugger and JTAG adapter connected to {IDF_TARGET_NAME} target.
.. figure:: ../../../_static/jtag-debugging-overview.jpg
:align: center
@ -56,10 +58,12 @@ The key software and hardware to perform debugging of ESP32 with OpenOCD over JT
JTAG debugging - overview diagram
Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to ESP32, as well as to provide means to monitor diagnostic messages from ESP32.
Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}.
Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
.. only:: esp32
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 `idf.py build` can be operated directly from terminal/command line, instead from Eclipse.
@ -70,13 +74,13 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate
Selecting JTAG Adapter
----------------------
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work.
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the {IDF_TARGET_NAME} does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work.
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the ESP32, although for now, support in OpenOCD for that line is pretty minimal.
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal.
.. _jtag-debugging-setup-openocd:
@ -94,7 +98,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc
The output should be as follows (although the version may be more recent than listed here)::
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
Open On-Chip Debugger v0.10.0-{IDF_TARGET_TOOLCHAIN_NAME}-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
@ -107,12 +111,12 @@ If any of these steps do not work, please go back to the :ref:`setting up the to
It is also possible to build OpenOCD from source. Please refer to :ref:`jtag-debugging-building-openocd` section for details.
.. _jtag-debugging-configuring-esp32-target:
.. _jtag-debugging-configuring-target:
Configuring ESP32 Target
------------------------
Configuring {IDF_TARGET_NAME} Target
-------------------------------------
Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board with JTAG interface). You will do it in the following three steps:
Once OpenOCD is installed, move to configuring {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). You will do it in the following three steps:
* Configure and connect JTAG interface
* Run OpenOCD
@ -122,12 +126,12 @@ Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board wit
Configure and connect JTAG interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This step depends on JTAG and ESP32 board you are using - see the two cases described below.
This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the two cases described below.
.. toctree::
:maxdepth: 1
configure-wrover
:esp32: configure-wrover
configure-other-jtag
@ -169,7 +173,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT)::
* If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory.
* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path.
* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides ESP32's pins, and see if everything is powered on.
* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on.
.. _jtag-upload-app-debug:
@ -177,7 +181,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`.
Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-started-build`.
Another option is to write application image to flash using OpenOCD via JTAG with commands like this::
@ -201,7 +205,7 @@ You are now ready to start application debugging. Follow steps described in sect
Launching Debugger
------------------
The toolchain for ESP32 features GNU Debugger, in short GDB. It is available with other toolchain programs under filename ``xtensa-esp32-elf-gdb``. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal.
The toolchain for {IDF_TARGET_NAME} features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal.
Both options of using debugger are discussed under links below.
@ -228,7 +232,7 @@ This section is intended for users not familiar with GDB. It presents example de
Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`.
Before proceeding to examples, set up your ESP32 target and load it with :example:`get-started/blink`.
Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it with :example:`get-started/blink`.
.. _jtag-debugging-building-openocd:

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

@ -10,7 +10,7 @@ This section provides collection of all tips and quirks referred to from various
Breakpoints and watchpoints available
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP32 debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by ESP32 chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). ESP32 also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description.
{IDF_TARGET_NAME} debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description.
.. _jtag-debugging-tip-where-breakpoints:
@ -26,7 +26,7 @@ Emulating part of hardware breakpoints using software flash ones means that the
Flash Mappings vs SW Flash Breakpoints
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the ESP32 address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
``esp32 appimage_offset <offset>``
@ -55,13 +55,7 @@ Support options for OpenOCD at compile time
ESP-IDF has some support options for OpenOCD debugging which can be set at compile time:
.. only:: esp32
* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
.. only:: esp32s2
* :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
* :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
@ -77,6 +71,8 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
.. _jtag-debugging-tip-code-flash-voltage:
.. only:: esp33
Why to set SPI flash voltage in OpenOCD configuration?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -107,7 +103,7 @@ What is the meaning of debugger's startup commands?
On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging.
* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
* ``mon reset halt`` — reset the chip and keep the CPUs halted
* ``flushregs`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``flushregs`` is a way to force GDB to get new state from the target.
* ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required
@ -170,6 +166,8 @@ Power supply voltage of ESP32's SPI flash chip
Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
.. only:: esp32
Configuration file for ESP32 targets
""""""""""""""""""""""""""""""""""""
@ -202,8 +200,8 @@ Look inside ``board/esp-wroom-32.cfg`` for additional information provided in co
.. _jtag-debugging-tip-reset-by-debugger:
How debugger resets ESP32?
^^^^^^^^^^^^^^^^^^^^^^^^^^
How debugger resets {IDF_TARGET_NAME}?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
@ -213,19 +211,35 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
Do not use JTAG pins for something else
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32 module and JTAG adapter. ESP32 JTAG us using the following pins:
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins:
+---+----------------+-------------+
| | ESP32 JTAG Pin | JTAG Signal |
+===+================+=============+
.. only:: esp32
+---+-----------------------+-------------+
| | ESP32 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | MTDO / GPIO15 | TDO |
+---+----------------+-------------+
+---+-----------------------+-------------+
| 2 | MTDI / GPIO12 | TDI |
+---+----------------+-------------+
+---+-----------------------+-------------+
| 3 | MTCK / GPIO13 | TCK |
+---+----------------+-------------+
+---+-----------------------+-------------+
| 4 | MTMS / GPIO14 | TMS |
+---+----------------+-------------+
+---+-----------------------+-------------+
.. only:: esp32s2
+---+-----------------------+-------------+
| | ESP32-S2 Pin | JTAG Signal |
+===+=======================+=============+
| 1 | MTDO / GPIO40 | TDO |
+---+-----------------------+-------------+
| 2 | MTDI / GPIO41 | TDI |
+---+-----------------------+-------------+
| 3 | MTCK / GPIO39 | TCK |
+---+-----------------------+-------------+
| 4 | MTMS / GPIO42 | TMS |
+---+-----------------------+-------------+
JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it.
@ -243,6 +257,8 @@ Below is an excerpt from series of errors reported by GDB after the application
.. _jtag-debugging-tip-at-firmware-issue:
.. only:: esp32
JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

28
docs/en/api-guides/jtag-debugging/using-debugger.rst
View file

@ -36,7 +36,7 @@ Once installation is complete, configure debugging session following steps below
Configuration of GDB Hardware Debugging - Main tab
6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-esp32-elf-gdb`` to invoke debugger.
6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` to invoke debugger.
7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number".
@ -82,7 +82,7 @@ Once installation is complete, configure debugging session following steps below
If the "Startup" sequence looks convoluted and respective "Initialization Commands" are not clear to you, check :ref:`jtag-debugging-tip-debugger-startup-commands` for additional explanation.
12. If you previously completed :ref:`jtag-debugging-configuring-esp32-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-esp32-target` and return here to start debugging.
12. If you previously completed :ref:`jtag-debugging-configuring-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-target` and return here to start debugging.
Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below.
@ -101,7 +101,7 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-ec
Command Line
^^^^^^^^^^^^
1. Begin with completing steps described under :ref:`jtag-debugging-configuring-esp32-target`. This is prerequisite to start a debugging session.
1. Begin with completing steps described under :ref:`jtag-debugging-configuring-target`. This is prerequisite to start a debugging session.
.. highlight:: bash
@ -134,7 +134,7 @@ Command Line
::
xtensa-esp32-elf-gdb -x gdbinit build/blink.elf
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
.. highlight:: none
@ -142,14 +142,14 @@ Command Line
::
user-name@computer-name:~/esp/blink$ xtensa-esp32-elf-gdb -x gdbinit build/blink.elf
user-name@computer-name:~/esp/blink$ xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-esp32-elf".
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
@ -158,17 +158,17 @@ Command Line
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from build/blink.elf...done.
0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52
0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52
52 asm("waiti 0");
JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
JTAG tap: esp32.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
JTAG tap: {IDF_TARGET_PATH_NAME}.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
JTAG tap: {IDF_TARGET_PATH_NAME}.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
{IDF_TARGET_PATH_NAME}: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
{IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x5F, after clear 0x0F).
Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000
esp32: target state: halted
esp32: Core was reset (pwrstat=0x1F, after clear 0x0F).
{IDF_TARGET_PATH_NAME}: target state: halted
{IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x1F, after clear 0x0F).
Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400
esp32: target state: halted
{IDF_TARGET_PATH_NAME}: target state: halted
Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/main/./blink.c, line 43.
0x0: 0x00000000
Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8

10
docs/en/api-guides/linker-script-generation.rst
View file

@ -426,11 +426,11 @@ will be generated for the target ``flash_text``.
These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified.
.. note::
The ``default scheme`` is defined in :component:`esp32/ld/esp32_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are
The ``default scheme`` is defined in :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are
built-in schemes referenced in the quick start guide are also defined in this file.
.. _ldgen-mapping-fragment :
**Mapping**
@ -589,9 +589,5 @@ Then the corresponding excerpt from the generated linker script will be as follo
it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first
among all other rules collected under the same target name.
.. note::
The linker script template currently used is :component:`esp32/ld/esp32.project.ld.in`, specified by the ``esp32`` component; the
The linker script template currently used is :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`, specified by the ``{IDF_TARGET_PATH_NAME}`` component; the
generated output script is put under its build directory.

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

@ -5,7 +5,7 @@ Partition Tables
Overview
--------
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table.
@ -23,7 +23,7 @@ Built-in Partition Tables
Here is the summary printed for the "Single factory app, no OTA" configuration::
# Espressif ESP32 Partition Table
# Espressif ESP Partition Table
# Name, Type, SubType, Offset, Size, Flags
nvs, data, nvs, 0x9000, 0x6000,
phy_init, data, phy, 0xf000, 0x1000,
@ -34,7 +34,7 @@ Here is the summary printed for the "Single factory app, no OTA" configuration::
Here is the summary printed for the "Factory app, two OTA definitions" configuration::
# Espressif ESP32 Partition Table
# Espressif ESP Partition Table
# Name, Type, SubType, Offset, Size, Flags
nvs, data, nvs, 0x9000, 0x4000,
otadata, data, ota, 0xd000, 0x2000,
@ -69,7 +69,7 @@ The CSV format is the same format as printed in the summaries shown above. Howev
Name field
~~~~~~~~~~
Name field can be any meaningful name. It is not significant to the ESP32. Names longer than 16 characters will be truncated.
Name field can be any meaningful name. It is not significant to the {IDF_TARGET_NAME}. Names longer than 16 characters will be truncated.
Type field
~~~~~~~~~~
@ -136,7 +136,7 @@ Only one flag is currently supported, ``encrypted``. If this field is set to ``e
Generating Binary Partition Table
---------------------------------
The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process.

10
docs/en/api-guides/romconsole.rst
View file

@ -1,8 +1,8 @@
*****************
ESP32 ROM console
*****************
*****************************
{IDF_TARGET_NAME} ROM console
*****************************
When an ESP32 is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console
When an {IDF_TARGET_NAME} is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console
is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a
preceeding line number, commands entered are executed immediately; lines with a prefixed line number are stored as part of a program.
@ -12,7 +12,7 @@ Full list of supported statements and functions
System
------
- BYE - *exits Basic, reboots ESP32, retries booting from flash*
- BYE - *exits Basic, reboots and retries booting from flash*
- END - *stops execution from the program, also "STOP"*
- MEM - *displays memory usage statistics*
- NEW - *clears the current program*

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

@ -89,11 +89,11 @@ IDF Monitor adds more details to the dump::
0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
0x400d071d: main_task at /home/gus/esp/32/idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254
To decode each address, IDF Monitor runs the following command in the background::
xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
Launching GDB with GDBStub
@ -103,19 +103,13 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and
Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware.
.. only:: esp32
To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``.
.. only:: esp32s2
To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32S2_PANIC` to ``Invoke GDBStub``.
To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` to ``Invoke GDBStub``.
In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button.
In the background, IDF Monitor runs the following command::
xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
Output Filtering

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

@ -6,8 +6,8 @@ ULP Coprocessor programming
.. toctree::
:maxdepth: 1
Instruction set reference for ESP32 ULP <ulp_instruction_set>
Instruction set reference for ESP32-S2 ULP <ulps2_instruction_set>
:esp32: Instruction set reference for ESP32 ULP <ulp_instruction_set>
:esp32s2: Instruction set reference for ESP32-S2 ULP <ulps2_instruction_set>
Programming using macros (legacy) <ulp_macros>
@ -31,7 +31,7 @@ To compile the ULP code as part of the component, the following steps must be ta
1. The ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside the component directory, for instance `ulp/`.
.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-{IDF_TARGET_NAME}-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files.
2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example::

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

@ -1,7 +1,7 @@
ESP32 ULP coprocessor instruction set
=====================================
This document provides details about the instructions used by ESP32 ULP coprocessor assembler.
This document provides details about the instructions used by {IDF_TARGET_NAME} ULP coprocessor assembler.
ULP coprocessor has 4 16-bit general purpose registers, labeled R0, R1, R2, R3. It also has an 8-bit counter register (stage_cnt) which can be used to implement loops. Stage count regiter is accessed using special instructions.
@ -13,7 +13,7 @@ The instruction syntax is case insensitive. Upper and lower case letters can be
Note about addressing
---------------------
ESP32 ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words.
{IDF_TARGET_NAME} ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words.
Consider the following example program::

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

@ -1,5 +1,5 @@
Unit Testing in ESP32
=============================
Unit Testing in {IDF_TARGET_NAME}
=================================
:link_to_translation:`zh_CN:[中文]`
ESP-IDF comes with a unit test application that is based on the Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in the ``test`` subdirectories of each component respectively.
@ -114,7 +114,7 @@ To support this, we can define multi-stage test cases, to group a set of test fu
TEST_ASSERT(reason == DEEPSLEEP_RESET);
}
TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32]", trigger_deepsleep, check_deepsleep_reset_reason);
TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[{IDF_TARGET_PATH_NAME}]", trigger_deepsleep, check_deepsleep_reset_reason);
Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case.
@ -142,7 +142,7 @@ Use menuconfig to set the serial port for flashing.
Running Unit Tests
------------------
After flashing reset the ESP32 and it will boot the unit test app.
After flashing reset the {IDF_TARGET_NAME} and it will boot the unit test app.
When unit test app is idle, press "Enter" will make it print test menu with all available tests::
@ -168,7 +168,7 @@ When unit test app is idle, press "Enter" will make it print test menu with all
(17) "SPI Master no response when switch from host1 (HSPI) to host2 (VSPI)" [spi]
(18) "SPI Master DMA test, TX and RX in different regions" [spi]
(19) "SPI Master DMA test: length, start, not aligned" [spi]
(20) "reset reason check for deepsleep" [esp32][test_env=UT_T2_1][multi_stage]
(20) "reset reason check for deepsleep" [{IDF_TARGET_PATH_NAME}][test_env=UT_T2_1][multi_stage]
(1) "trigger_deepsleep"
(2) "check_deepsleep_reset_reason"

222
docs/en/api-guides/wifi.rst
View file

@ -1,8 +1,8 @@
Wi-Fi Driver
=============
ESP32 Wi-Fi Feature List
-------------------------
{IDF_TARGET_NAME} Wi-Fi Feature List
------------------------------------
- Support Station-only mode, AP-only mode, Station/AP-coexistence mode
- Support IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode
- Support WPA/WPA2/WPA2-Enterprise and WPS
@ -21,7 +21,7 @@ How To Write a Wi-Fi Application
Preparation
+++++++++++
Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`ESP32 Wi-Fi API Error Code`_>, <`ESP32 Wi-Fi Programming Model`_>, and <`ESP32 Wi-Fi Event Description`_>.
Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_>, <`{IDF_TARGET_NAME} Wi-Fi Programming Model`_>, and <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>.
Setting Wi-Fi Compile-time Options
++++++++++++++++++++++++++++++++++++
@ -29,24 +29,24 @@ Refer to <`Wi-Fi Menuconfig`_>
Init Wi-Fi
+++++++++++
Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>.
Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>.
Start/Connect Wi-Fi
++++++++++++++++++++
Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>.
Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>.
Event-Handling
++++++++++++++
Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi Event Description`_>, <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF<event-handling>`.
Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>, <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF<event-handling>`.
Write Error-Recovery Routines Correctly at All Times
++++++++++++++++++++++++++++++++++++++++++++++++++++
Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi API Error Code`_>
Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_>
ESP32 Wi-Fi API Error Code
---------------------------
All of the ESP32 Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into:
{IDF_TARGET_NAME} Wi-Fi API Error Code
--------------------------------------
All of the {IDF_TARGET_NAME} Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into:
- No errors, e.g. ESP_OK means that the API returns successfully
- Recoverable errors, such as ESP_ERR_NO_MEM, etc.
- Non-recoverable, non-critical errors
@ -63,8 +63,8 @@ Whether the error is critical or not depends on the API and the application scen
In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used
as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code.
ESP32 Wi-Fi API Parameter Initialization
------------------------------------------
{IDF_TARGET_NAME} Wi-Fi API Parameter Initialization
----------------------------------------------------
When initializing struct parameters for the API, one of two approaches should be followed:
- explicitly set all fields of the parameter or
@ -74,9 +74,9 @@ Initializing or getting the entire structure is very important because most of t
.. _wifi-programming-model:
ESP32 Wi-Fi Programming Model
-----------------------------
The ESP32 Wi-Fi programming model is depicted as follows:
{IDF_TARGET_NAME} Wi-Fi Programming Model
-----------------------------------------
The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows:
.. blockdiag::
:caption: Wi-Fi Programming Model
@ -124,8 +124,8 @@ The Wi-Fi driver can be considered a black box that knows nothing about high-lay
Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default).
ESP32 Wi-Fi Event Description
------------------------------------
{IDF_TARGET_NAME} Wi-Fi Event Description
-----------------------------------------
WIFI_EVENT_WIFI_READY
++++++++++++++++++++++++++++++++++++
@ -145,7 +145,7 @@ The scan-done event will not arise in the following scenarios:
- The scan is caused by esp_wifi_connect().
Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this)**!
Refer to 'ESP32 Wi-Fi Scan' for a more detailed description.
Refer to '{IDF_TARGET_NAME} Wi-Fi Scan' for a more detailed description.
WIFI_EVENT_STA_START
++++++++++++++++++++++++++++++++++++
@ -202,7 +202,7 @@ The socket is based on the IPV4 address, which means that, if the IPV4 changes,
IP_EVENT_GOT_IP6
++++++++++++++++++++++++++++++++++++
This event arises when the IPV6 SLAAC support auto-configures an address for the ESP32, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME}, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets).
IP_STA_LOST_IP
++++++++++++++++++++++++++++++++++++
@ -222,7 +222,7 @@ Similar to <`WIFI_EVENT_STA_STOP`_>.
WIFI_EVENT_AP_STACONNECTED
++++++++++++++++++++++++++++++++++++
Every time a station is connected to ESP32 AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc.
Every time a station is connected to {IDF_TARGET_NAME} AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc.
WIFI_EVENT_AP_STADISCONNECTED
++++++++++++++++++++++++++++++++++++
@ -240,8 +240,8 @@ WIFI_EVENT_AP_PROBEREQRECVED
This event is disabled by default. The application can enable it via API esp_wifi_set_event_mask().
When this event is enabled, it will be raised each time the AP receives a probe request.
ESP32 Wi-Fi Station General Scenario
---------------------------------------
{IDF_TARGET_NAME} Wi-Fi Station General Scenario
------------------------------------------------
Below is a "big scenario" which describes some small scenarios in Station mode:
.. seqdiag::
@ -314,7 +314,7 @@ Step 1.1~1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based appl
2. Wi-Fi Configuration Phase
+++++++++++++++++++++++++++++++
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`ESP32 Wi-Fi Configuration`_>.
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`{IDF_TARGET_NAME} Wi-Fi Configuration`_>.
Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as esp_wifi_set_protocol) will cause the Wi-Fi to reconnect, which may not be desirable.
@ -363,7 +363,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is
- s8.3: Call esp_wifi_deinit() to unload the Wi-Fi driver.
ESP32 Wi-Fi AP General Scenario
{IDF_TARGET_NAME} Wi-Fi AP General Scenario
---------------------------------------------
Below is a "big scenario" which describes some small scenarios in AP mode:
@ -411,7 +411,7 @@ Below is a "big scenario" which describes some small scenarios in AP mode:
}
ESP32 Wi-Fi Scan
{IDF_TARGET_NAME} Wi-Fi Scan
------------------------
Currently, the esp_wifi_scan_start() API is supported only in Station or Station+AP mode.
@ -662,7 +662,7 @@ If the block parameter of esp_wifi_scan_start() is true, then the scan is a bloc
Parallel Scan
+++++++++++++
Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the ESP32's Wi-Fi functionality improves continuously.
Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the {IDF_TARGET_NAME}'s Wi-Fi functionality improves continuously.
Scan When Wi-Fi Is Connecting
+++++++++++++++++++++++++++++++
@ -681,10 +681,10 @@ In above scenario the scan will never succeed because the connecting is in proce
The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>.
ESP32 Wi-Fi Station Connecting Scenario
----------------------------------------
{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario
---------------------------------------------------
This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`ESP32 Wi-Fi Station Connecting When Multiple APs Are Found`_>.
This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found`_>.
Generally, the application does not need to care about the connecting process. Below is a brief introduction to the process for those who are really interested.
@ -768,7 +768,7 @@ Four-way Handshake Phase
Wi-Fi Reason Code
+++++++++++++++++++++
The table below shows the reason-code defined in ESP32. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason.
The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason.
+---------------------------+-------+---------+-------------------------------------------------------------+
| Reason code | Value |Mapped To| Description |
@ -779,12 +779,12 @@ The table below shows the reason-code defined in ESP32. The first column is the
+---------------------------+-------+---------+-------------------------------------------------------------+
| AUTH_EXPIRE | 2 | 2 | The previous authentication is no longer valid. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - auth is timed out |
| | | | - the reason is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the AP has not received any packets from the station |
| | | | in the past five minutes. |
@ -795,18 +795,18 @@ The table below shows the reason-code defined in ESP32. The first column is the
| AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is |
| | | | leaving (or has left). |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the AP has not received any packets from the |
| | | | station in the past five minutes. |
@ -817,11 +817,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
| ASSOC_TOOMANY | 5 | 5 | Disassociated, because the AP is unable to handle |
| | | | all currently associated STAs at the same time. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the stations associated with the AP reach the |
| | | | maximum number that the AP can support. |
@ -829,11 +829,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
+---------------------------+-------+---------+-------------------------------------------------------------+
| NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the AP receives a packet with data from a |
| | | | non-authenticated station. |
@ -841,11 +841,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
+---------------------------+-------+---------+-------------------------------------------------------------+
| NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the AP receives a packet with data from a |
| | | | non-associated station. |
@ -854,7 +854,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
| ASSOC_LEAVE | 8 | 8 | Disassociated, because the sending STA is leaving (or has |
| | | | left) BSS. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | - the station is disconnected by esp_wifi_disconnect() and |
@ -864,11 +864,11 @@ The table below shows the reason-code defined in ESP32. The first column is the
| ASSOC_NOT_AUTHED | 9 | 9 | STA requesting (re)association is not authenticated by the |
| | | | responding STA. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the AP receives packets with data from an |
| | | | associated, yet not authenticated, station. |
@ -877,7 +877,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
| DISASSOC_PWRCAP_BAD | 10 | 10 | Disassociated, because the information in the Power |
| | | | Capability element is unacceptable. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
@ -885,7 +885,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
| DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported |
| | | | Channels element is unacceptable. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
@ -893,27 +893,27 @@ The table below shows the reason-code defined in ESP32. The first column is the
| IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet|
| | | | the specifications of the Standard in Clause 8. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - the AP parses a wrong WPA or RSN IE. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP32 |
| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP |
| | | | this reason-code is replaced with |
| | | | WIFI_REASON_HANDSHAKE_TIMEOUT. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - the handshake times out |
| | | | - it is received from the AP. |
@ -921,7 +921,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
+---------------------------+-------+---------+-------------------------------------------------------------+
| GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. |
| | | | |
| | | | For the ESP32 station, this reason is reported when: |
| | | | For the ESP station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
@ -929,7 +929,7 @@ The table below shows the reason-code defined in ESP32. The first column is the
| IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the |
| | | | (Re-)Association Request/Probe and Response/Beacon frame. |
| | | | |
| | | | For the ESP32 station, this reason is reported when: |
| | | | For the ESP station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | - the station finds that the four-way handshake IE differs |
@ -939,53 +939,53 @@ The table below shows the reason-code defined in ESP32. The first column is the
+---------------------------+-------+---------+-------------------------------------------------------------+
| GROUP_CIPHER_INVALID | 18 | 18 | Invalid group cipher. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| AKMP_INVALID | 20 | 20 | Invalid AKMP. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
| | | | For the ESP32 AP, this reason is reported when: |
| | | | For the ESP AP, this reason is reported when: |
| | | | |
| | | | - 802.1 x authentication fails. |
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
| CIPHER_SUITE_REJECTED | 24 | 24 | Cipher suite rejected due to security policies. |
| | | | |
| | | | For the ESP32 Station, this reason is reported when: |
| | | | For the ESP Station, this reason is reported when: |
| | | | |
| | | | - it is received from the AP. |
| | | | |
@ -1013,10 +1013,10 @@ The table below shows the reason-code defined in ESP32. The first column is the
| | | | |
+---------------------------+-------+---------+-------------------------------------------------------------+
ESP32 Wi-Fi Station Connecting When Multiple APs Are Found
---------------------------------------------------------------
{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found
----------------------------------------------------------------------
This scenario is similar as <`ESP32 Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs.
This scenario is similar as <`{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs.
Wi-Fi Reconnect
@ -1033,12 +1033,12 @@ Another thing we need to consider is the reconnect may not connect the same AP i
Wi-Fi Beacon Timeout
---------------------------
The beacon timeout mechanism is used by ESP32 station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens.
The beacon timeout mechanism is used by {IDF_TARGET_NAME} station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens.
After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event <`WIFI_EVENT_STA_DISCONNECTED`_> if still no probe response or beacon is received from AP.
ESP32 Wi-Fi Configuration
---------------------------
{IDF_TARGET_NAME} Wi-Fi Configuration
-------------------------------------
All configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to <`Wi-Fi NVS Flash`_>.
@ -1071,8 +1071,8 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode.
| WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, esp_wifi_start() |
| | will simultaneously init both the station and the AP. |
| | This is done in station mode and AP mode. Please note |
| | that the channel of the external AP, which the ESP32 Station |
| | is connected to, has higher priority over the ESP32 AP |
| | that the channel of the external AP, which the ESP Station |
| | is connected to, has higher priority over the ESP AP |
| | channel. |
+------------------+--------------------------------------------------------------+
@ -1169,7 +1169,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr
| | sure the channel is within the required range. |
| | For more details, refer to <`Wi-Fi Country Code`_>. |
+------------------+--------------------------------------------------------------+
| authmode | Auth mode of ESP32 AP; currently, ESP32 Wi-Fi does not |
| authmode | Auth mode of ESP AP; currently, ESP Wi-Fi does not |
| | support AUTH_WEP. If the authmode is an invalid value, |
| | AP defaults the value to WIFI_AUTH_OPEN. |
| | |
@ -1178,7 +1178,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr
| | otherwise, it does broadcast the SSID. |
| | |
+------------------+--------------------------------------------------------------+
| max_connection | Currently, ESP32 Wi-Fi supports up to 10 Wi-Fi connections. |
| max_connection | Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. |
| | If max_connection > 10, AP defaults the value to 10. |
| | |
+------------------+--------------------------------------------------------------+
@ -1219,7 +1219,7 @@ Currently, the IDF supports the following protocol modes:
| | **This mode is an Espressif-patented mode which can achieve|
| | a one-kilometer line of sight range. Please, make sure both|
| | the station and the AP are connected to an |
| | ESP32 device** |
| | ESP device** |
+--------------------+------------------------------------------------------------+
Long Range (LR)
@ -1230,7 +1230,7 @@ Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one
LR Compitability
*************************
Since LR is Espressif unique Wi-Fi mode, only ESP32 devices can transmit and receive the LR data. In other words, the ESP32 device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32 may transmit data in LR rate, otherwise, ESP32 will transmit all data in traditional Wi-Fi data rate.
Since LR is Espressif unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate, otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate.
Following table depicts the Wi-Fi mode negotiation:
@ -1255,9 +1255,9 @@ Following table depicts the Wi-Fi mode negotiation:
In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible.
According to the table, we can conclude that:
- For LR enabled in ESP32 AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode.
- For LR enabled in ESP32 station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode.
- If both station and AP are ESP32 devices and both of them enable LR mode, the negotiated mode supports LR.
- For LR enabled in {IDF_TARGET_NAME} AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode.
- For LR enabled in {IDF_TARGET_NAME} station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode.
- If both station and AP are {IDF_TARGET_NAME} devices and both of them enable LR mode, the negotiated mode supports LR.
If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it.
@ -1284,7 +1284,7 @@ When to Use LR
*************************
The general conditions for using LR are:
- Both the AP and station are ESP32 devices.
- Both the AP and station are devices.
- Long distance WiFi connection and data transmission is required.
- Data throughput requirements are very small, such as remote device control, etc.
@ -1387,18 +1387,18 @@ Following table depicts which country info is used in different WiFi Mode and di
Home Channel
*************************
In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the ESP32 in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP.
In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the {IDF_TARGET_NAME} in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP.
Wi-Fi Vendor IE Configuration
+++++++++++++++++++++++++++++++++++
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In ESP32, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks.
By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In {IDF_TARGET_NAME}, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks.
Wi-Fi Security
-------------------------------
In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), ESP32 Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes.
In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes.
Protected Management Frames (PMF)
++++++++++++++++++++++++++++++++++
@ -1414,11 +1414,11 @@ An attacker can use eavesdropping and packet injection to send spoofed (de)authe
PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation and robust management frames. It also provides Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients.
ESP32 supports the following three modes of operation with respect to PMF.
{IDF_TARGET_NAME} supports the following three modes of operation with respect to PMF.
- PMF not supported: In this mode, ESP32 indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode.
- PMF capable, but not required: In this mode, ESP32 indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF.
- PMF capable and required: In this mode, ESP32 will only connect to AP, if AP supports PMF. If not, ESP32 will refuse to connect to the AP.
- PMF not supported: In this mode, {IDF_TARGET_NAME} indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode.
- PMF capable, but not required: In this mode, {IDF_TARGET_NAME} indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF.
- PMF capable and required: In this mode, {IDF_TARGET_NAME} will only connect to AP, if AP supports PMF. If not, {IDF_TARGET_NAME} will refuse to connect to the AP.
:cpp:func:`esp_wifi_set_config` can be used to configure PMF mode by setting appropriate flags in `pmf_cfg` parameter. Currently, PMF is supported only in Station mode.
@ -1428,15 +1428,15 @@ WPA3-Personal
Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. In order to provide more robust authentication, WPA3 uses Simultaneous Authentication of Equals (SAE), which is password-authenticated key agreement method based on Diffie-Hellman key exchange. Unlike WPA2, the technology is resistant to offline-dictionary attack, where the attacker attempts to determine shared password based on captured 4-way handshake without any further network interaction. WPA3 also provides forward secrecy, which means the captured data cannot be decrypted even if password is compromised after data transmission. Please refer to `Security <https://www.wi-fi.org/discover-wi-fi/security>`_ section of Wi-Fi Alliance's official website for further details.
In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, ESP32 uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for ESP32 to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode.
In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, {IDF_TARGET_NAME} uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for {IDF_TARGET_NAME} to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode.
ESP32 Wi-Fi Power-saving Mode
-----------------------------------
{IDF_TARGET_NAME} Wi-Fi Power-saving Mode
-----------------------------------------
Station Sleep
++++++++++++++++++++++
Currently, ESP32 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode.
Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP.
@ -1451,20 +1451,20 @@ The default Modem-sleep mode is WIFI_PS_MIN_MODEM.
AP Sleep
+++++++++++++++++++++++++++++++
Currently ESP32 AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the ESP32 AP are power save enabled, they may experience multicast packet loss.
Currently {IDF_TARGET_NAME} AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the {IDF_TARGET_NAME} AP are power save enabled, they may experience multicast packet loss.
In future, all power save features will be supported on ESP32 AP.
In future, all power save features will be supported on {IDF_TARGET_NAME} AP.
ESP32 Wi-Fi Connect Crypto
-----------------------------------
Now ESP32 have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware:
{IDF_TARGET_NAME} Wi-Fi Connect Crypto
--------------------------------------
Now {IDF_TARGET_NAME} have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware:
1. Original functions which is the source code used in the folder components/wpa_supplicant/src/crypto function;
2. The optimized functions is in the folder components/wpa_supplicant/src/fast_crypto, these function used the hardware crypto to make it faster than origin one, the type of function's name add `fast_` to distinguish with the original one. For example, the API aes_wrap() is used to encrypt frame information when do 4 way handshake, the fast_aes_wrap() has the same result but can be faster.
Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the
fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish().
ESP32 Wi-Fi Throughput
{IDF_TARGET_NAME} Wi-Fi Throughput
-----------------------------------
The table below shows the best throughput results we got in Espressif's lab and in a shield box.
@ -1504,7 +1504,7 @@ Preconditions of Using esp_wifi_80211_tx
++++++++++++++++++++++++++++++++++++++++++++
- The Wi-Fi mode is Station, or AP, or Station+AP.
- Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In ESP32, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware.
- Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware.
- The parameters of esp_wifi_80211_tx are hereby correctly provided.
Data rate
@ -1636,9 +1636,9 @@ The Wi-Fi multiple antennas selecting can be depicted as following picture::
|__________|
ESP32 supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default.
{IDF_TARGET_NAME} supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default.
Up to four GPIOs are connected to the four active high antenna_select pins. ESP32 can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled.
@ -1679,7 +1679,7 @@ Generally, following steps can be taken to configure the multiple antennas:
Wi-Fi Channel State Information
------------------------------------
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In ESP32, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table.
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table.
+-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+
| channel | secondary channel | none | below | above |
@ -1707,7 +1707,7 @@ All of the information in the table can be found in the structure wifi_csi_info_
- STBC refers to stbc field of rx_ctrl field.
- Total bytes refers to len field.
- The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above).
- If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in ESP32.
- If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}.
- More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field.
.. note::
@ -1730,24 +1730,24 @@ The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy
Wi-Fi HT20/40
-------------------------
ESP32 supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for ESP32 station and AP is HT40.
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40.
In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it's HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting.
Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It's HT40 if the AP and one of the stations support HT40, otherwise it's HT20.
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in ESP32. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the ESP32 device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20.
Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the {IDF_TARGET_NAME} device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20.
Wi-Fi QoS
-------------------------
ESP32 supports all the mandatory features required in WFA Wi-Fi QoS Certification.
{IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification.
Four ACs(Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC.
Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in ESP32, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority.
Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority.
+------------------+------------------------+-----------------+
| IP Precedence | Wi-Fi AC | Support AMPDU? |
@ -1776,17 +1776,17 @@ Theoretically the higher priority AC has better performance than the low priorit
Wi-Fi AMSDU
-------------------------
ESP32 supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since ESP32 has transmitting AMPDU.
{IDF_TARGET_NAME} supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since {IDF_TARGET_NAME} has transmitting AMPDU.
Wi-Fi Fragment
-------------------------
ESP32 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release.
{IDF_TARGET_NAME} supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release.
WPS Enrolle
-------------------------
ESP32 supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently ESP32 supports WPS enrollee type PBC and PIN.
{IDF_TARGET_NAME} supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently {IDF_TARGET_NAME} supports WPS enrollee type PBC and PIN.
.. _wifi-buffer-usage:
@ -1799,11 +1799,11 @@ Why Buffer Configuration Is Important
+++++++++++++++++++++++++++++++++++++++
In order to get a robust, high-performance system, we need to consider the memory usage/configuration very carefully, because:
- the available memory in ESP32 is limited.
- the available memory in {IDF_TARGET_NAME} is limited.
- currently, the default type of buffer in LwIP and Wi-Fi drivers is "dynamic", **which means that both the LwIP and Wi-Fi share memory with the application**. Programmers should always keep this in mind; otherwise, they will face a memory issue, such as "running out of heap memory".
- it is very dangerous to run out of heap memory, as this will cause ESP32 an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it.
- it is very dangerous to run out of heap memory, as this will cause {IDF_TARGET_NAME} an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it.
- the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc.
- the peak heap memory that the ESP32 LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc.
- the peak heap memory that the {IDF_TARGET_NAME} LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc.
- the total memory that the application requires is also an important factor when considering memory configuration.
Due to these reasons, there is not a good-for-all application configuration. Rather, we have to consider memory configurations separately for every different application.
@ -1994,7 +1994,7 @@ If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi AP
Wi-Fi AMPDU
+++++++++++++++++++++++++++
ESP32 supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput.
{IDF_TARGET_NAME} supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput.
Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes.

8
docs/en/api-reference/network/esp_wifi.rst
View file

@ -6,11 +6,11 @@ Wi-Fi
Introduction
------------
The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi networking functionality. This includes configuration for:
The WiFi libraries provide support for configuring and monitoring the {IDF_TARGET_NAME} WiFi networking functionality. This includes configuration for:
- Station mode (aka STA mode or WiFi client mode). ESP32 connects to an access point.
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32.
- Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access point).
- Station mode (aka STA mode or WiFi client mode). {IDF_TARGET_NAME} connects to an access point.
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the {IDF_TARGET_NAME}.
- Combined AP-STA mode ({IDF_TARGET_NAME} is concurrently an access point and a station connected to another access point).
- Various security modes for the above (WPA, WPA2, WEP, etc.)
- Scanning for access points (active & passive scanning).

15
docs/en/api-reference/peripherals/adc.rst
View file

@ -4,7 +4,10 @@ Analog to Digital Converter
Overview
--------
The ESP32 integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
..only:: esp32
The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application:
@ -87,7 +90,7 @@ The value read in both these examples is 12 bits wide (range 0-4095).
Minimizing Noise
----------------
The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise.
.. figure:: ../../../_static/adc-noise-graph.jpg
:align: center
@ -98,7 +101,7 @@ The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC re
ADC Calibration
---------------
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different ESP32s.
The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different {IDF_TARGET_NAME}s.
.. figure:: ../../../_static/adc-vref-graph.jpg
:align: center
@ -111,7 +114,7 @@ Correcting ADC readings using this API involves characterizing one of the ADCs a
Calibration Values
^^^^^^^^^^^^^^^^^^
Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular ESP32. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the ESP32 chip/module.
Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular {IDF_TARGET_NAME}. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module.
* **Two Point** values represent each of the ADCs’ readings at 150mV and 850mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``.
@ -119,6 +122,8 @@ Calibration values are used to generate characteristic curves that account for t
* **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used.
.. only:: esp32
Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below).
.. figure:: ../../../_static/chip_surface_marking.png
@ -135,7 +140,7 @@ If you are unable to check the date code (i.e. the chip may be enclosed inside a
$IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info
Replace ``/dev/ttyUSB0`` with ESP32 board's port name.
Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name.
A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows::

8
docs/en/api-reference/peripherals/can.rst
View file

@ -6,10 +6,10 @@ Controller Area Network (CAN)
Overview
--------
The ESP32's peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification.
The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification.
.. warning::
The ESP32 CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors.
This programming guide is split into the following sections:
@ -199,6 +199,8 @@ Bit timing **macro initializers** are also available for commonly used CAN bus b
- ``CAN_TIMING_CONFIG_800KBITS()``
- ``CAN_TIMING_CONFIG_1MBITS()``
.. only::esp32
.. note::
The macro initializers for 12.5K, 16K, and 20K bit rates are only available
for ESP32 revision 2 or later.
@ -477,7 +479,7 @@ The following example shows how the calculate the acceptance mask given multiple
Application Examples
^^^^^^^^^^^^^^^^^^^^
**Network Example:** The CAN Network example demonstrates communication between two ESP32s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`.
**Network Example:** The CAN Network example demonstrates communication between two {IDF_TARGET_NAME}s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`.
**Alert and Recovery Example:** This example demonstrates how to use the CAN driver's alert and bus recovery API. The example purposely introduces errors on the CAN bus to put the CAN controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via :example:`peripherals/can/can_alert_and_recovery`.

8
docs/en/api-reference/peripherals/dac.rst
View file

@ -4,7 +4,13 @@ Digital To Analog Converter
Overview
--------
ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
.. only:: esp32
{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
.. only:: esp32s2beta
{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO17 (Channel 1) and GPIO18 (Channel 2).
The DAC driver allows these channels to be set to arbitrary voltages.

2
docs/en/api-reference/peripherals/esp_slave_protocol.rst
View file

@ -6,7 +6,7 @@ Communication with ESP SDIO Slave
ESP SDIO slave initialization
------------------------------
The host should initialize the ESP32 SDIO slave according to the standard
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard
SDIO initialization process (Sector 3.1.2 of `SDIO Simplified
Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification
and below, the SDIO slave is also called an (SD)IO card. All the

10
docs/en/api-reference/peripherals/gpio.rst
View file

@ -4,11 +4,19 @@ GPIO & RTC GPIO
Overview
--------
The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
.. only:: esp32
The {IDF_TARGET_NAME} chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
- Note that GPIO6-11 are usually used for SPI flash.
- GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.
.. only:: esp32s2beta
The {IDF_TARGET_NAME} chip features 43 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal.
There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
Application Example

13
docs/en/api-reference/peripherals/i2c.rst
View file

@ -8,7 +8,7 @@ I2C is a serial, synchronous, half-duplex communication protocol that allows co-
With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot).
ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.
{IDF_TARGET_NAME} has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.
Driver Features
@ -50,7 +50,7 @@ To establish I2C communication, start by configuring the driver. This is done by
- Configure **communication pins**
- Assign GPIO pins for SDA and SCL signals
- Set whether to enable ESP32's internal pull-ups
- Set whether to enable {IDF_TARGET_NAME}'s internal pull-ups
- (Master only) Set I2C **clock speed**
- (Slave only) Configure the following
@ -81,9 +81,9 @@ After the I2C driver is configured, install it by calling the function :cpp:func
Communication as Master
^^^^^^^^^^^^^^^^^^^^^^^
After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices.
ESP32's I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
{IDF_TARGET_NAME}'s I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.
For better process organization, the driver provides a container, called a "command link", that should be populated with a sequence of commands and then passed to the I2C controller for execution.
@ -155,7 +155,7 @@ Likewise, the command link to read from the slave looks as follows:
Communication as Slave
^^^^^^^^^^^^^^^^^^^^^^
After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.
After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices.
The API provides the following functions for slaves
@ -179,7 +179,6 @@ During driver installation, an interrupt handler is installed by default. Howeve
To delete an interrupt handler, call :cpp:func:`i2c_isr_free`.
.. _i2c-api-customized-configuration:
Customized Configuration
@ -217,7 +216,7 @@ You can also select different pins for SDA and SCL signals and alter the configu
.. note::
ESP32's internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
{IDF_TARGET_NAME}'s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
.. _i2c-api-error-handling:

4
docs/en/api-reference/peripherals/i2s.rst
View file

@ -6,7 +6,7 @@ Overview
I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices.
ESP32 integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data.
{IDF_TARGET_NAME} integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data.
An I2S bus consists of the following lines:
@ -30,6 +30,8 @@ The I2S peripherals also support LCD mode for communicating data over a parallel
- Camera slave receiving mode
- ADC/DAC mode
.. only:: esp32
For more information, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
.. note::

5
docs/en/api-reference/peripherals/ledc.rst
View file

@ -135,8 +135,13 @@ Of the total 8 timers and 16 channels available in the LED PWM Controller, half
The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
.. only:: esp32
For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
.. only:: esp32s2beta
For additional details regarding speed modes, refer to `ESP32-S2 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
.. _ledc-api-supported-range-frequency-duty-resolution:

11
docs/en/api-reference/peripherals/mcpwm.rst
View file

@ -1,7 +1,7 @@
MCPWM
=====
ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
{IDF_TARGET_NAME} has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs.
.. figure:: ../../../_static/mcpwm-overview.png
:align: center
@ -53,7 +53,7 @@ In this case we will describe a simple configuration to control a brushed DC mot
Configuration covers the following steps:
1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of ESP32 and enumerated in :cpp:type:`mcpwm_unit_t`.
1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of {IDF_TARGET_NAME} and enumerated in :cpp:type:`mcpwm_unit_t`.
2. Initialization of two GPIOs as output signals within selected unit by calling :cpp:func:`mcpwm_gpio_init`. The two output signals are typically used to command the motor to rotate right or left. All available signal options are listed in :cpp:type:`mcpwm_io_signals_t`. To set more than a single pin at a time, use function :cpp:func:`mcpwm_set_pin` together with :cpp:type:`mcpwm_pin_config_t`.
3. Selection of a timer. There are three timers available within the unit. The timers are listed in :cpp:type:`mcpwm_timer_t`.
4. Setting of the timer frequency and initial duty within :cpp:type:`mcpwm_config_t` structure.
@ -89,8 +89,13 @@ There are couple of ways to adjust a signal on the outputs and changing how the
Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`.
.. only:: esp32
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_.
.. only:: esp32s2beta
* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32-S2 Technical Reference Manual`_.
Capture
-------
@ -171,6 +176,8 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf
API Reference
-------------

4
docs/en/api-reference/peripherals/rmt.rst
View file

@ -153,7 +153,7 @@ Now, depending on how the channel is configured, we are ready to either `Transmi
Transmit Data
-------------
Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/esp32/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below.
Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below.
.. packetdiag::
:caption: Structure of RMT items (L - signal level)
@ -242,7 +242,7 @@ The RMT controller triggers interrupts on four specific events describes below.
Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`.
When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/esp32/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above.
When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDT_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above.
If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`.

2
docs/en/api-reference/protocols/esp_http_server.rst
View file

@ -5,7 +5,7 @@ HTTP Server
Overview
--------
The HTTP Server component provides an ability for running a lightweight web server on ESP32. Following are detailed steps to use the API exposed by HTTP Server:
The HTTP Server component provides an ability for running a lightweight web server on {IDF_TARGET_NAME}. Following are detailed steps to use the API exposed by HTTP Server:
* :cpp:func:`httpd_start`: Creates an instance of HTTP server, allocate memory/resources for it depending upon the specified configuration and outputs a handle to the server instance. The server has both, a listening socket (TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin fashion in the server task loop. The task priority and stack size are configurable during server instance creation by passing httpd_config_t structure to httpd_start(). TCP traffic is parsed as HTTP requests and, depending on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response packets.
* :cpp:func:`httpd_stop`: This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task will close all open connections, remove registered URI handlers and reset all session context data to empty.

18
docs/en/api-reference/protocols/mdns.rst
View file

@ -12,8 +12,8 @@ mDNS is installed by default on most operating systems or is available as separa
mDNS Properties
^^^^^^^^^^^^^^^
* ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-esp32`` will resolve to ``my-esp32.local``
* ``default_instance``: friendly name for your device, like ``Jhon's ESP32 Thing``. If not set, ``hostname`` will be used.
* ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-{IDF_TARGET_PATH_NAME}`` will resolve to ``my-{IDF_TARGET_PATH_NAME}.local``
* ``default_instance``: friendly name for your device, like ``Jhon's {IDF_TARGET_NAME} Thing``. If not set, ``hostname`` will be used.
Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``:
@ -31,9 +31,9 @@ Example method to start mDNS for the STA interface and set ``hostname`` and ``de
}
//set hostname
mdns_hostname_set("my-esp32");
mdns_hostname_set("my-{IDF_TARGET_PATH_NAME}");
//set default instance
mdns_instance_name_set("Jhon's ESP32 Thing");
mdns_instance_name_set("Jhon's {IDF_TARGET_NAME} Thing");
}
mDNS Services
@ -41,7 +41,7 @@ mDNS Services
mDNS can advertise information about network services that your device offers. Each service is defined by a few properties.
* ``instance_name``: friendly name for your service, like ``Jhon's ESP32 Web Server``. If not defined, ``default_instance`` will be used.
* ``instance_name``: friendly name for your service, like ``Jhon's E{IDF_TARGET_NAME} Web Server``. If not defined, ``default_instance`` will be used.
* ``service_type``: (required) service type, prepended with underscore. Some common types can be found `here <http://www.dns-sd.org/serviceTypes.html>`_.
* ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp``
* ``port``: (required) network port that the service runs on
@ -58,10 +58,10 @@ Example method to add a few services and different properties::
//NOTE: services must be added before their properties can be set
//use custom instance for the web server
mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32 Web Server");
mdns_service_instance_name_set("_http", "_tcp", "Jhon's {IDF_TARGET_NAME} Web Server");
mdns_txt_item_t serviceTxtData[3] = {
{"board","esp32"},
{"board","{{IDF_TARGET_PATH_NAME}}"},
{"u","user"},
{"p","password"}
};
@ -161,8 +161,8 @@ Example method to resolve local services::
Example of using the methods above::
void my_app_some_method(){
//search for esp32-mdns.local
resolve_mdns_host("esp32-mdns");
//search for {IDF_TARGET_PATH_NAME}-mdns.local
resolve_mdns_host("{IDF_TARGET_PATH_NAME}-mdns");
//search for HTTP servers
find_mdns_service("_http", "_tcp");

6
docs/en/api-reference/storage/nvs_flash.rst
View file

@ -14,15 +14,15 @@ You can find two code examples in the :example:`storage` directory of ESP-IDF ex
Demonstrates how to read a single integer value from, and write it to NVS.
The value checked in this example holds the number of the ESP32 module restarts. The value's function as a counter is only possible due to its storing in NVS.
The value checked in this example holds the number of the {IDF_TARGET_NAME} module restarts. The value's function as a counter is only possible due to its storing in NVS.
The example also shows how to check if a read / write operation was successful, or if a certain value has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the program flow and capture any issues on the way.
:example:`storage/nvs_rw_blob`
Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between ESP32 module restarts.
Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between {IDF_TARGET_NAME} module restarts.
* value - tracks the number of the ESP32 module soft and hard restarts.
* value - tracks the number of the {IDF_TARGET_NAME} module soft and hard restarts.
* blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. A new run time is added to the table on each manually triggered soft restart, and then the added run time is written to NVS. Triggering is done by pulling down GPIO0.
The example also shows how to implement the diagnostic procedure to check if the read / write operation was successful.

4
docs/en/api-reference/storage/spiffs.rst
View file

@ -111,9 +111,9 @@ To pack a folder into a 1-Megabyte image, run::
mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
To flash the image onto ESP32 at offset 0x110000, run::
To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run::
python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
Notes on which SPIFFS tool to use

6
docs/en/api-reference/system/app_image_format.rst
View file

@ -4,7 +4,7 @@ App Image Format
An application image consists of the following structures:
1. The :cpp:type:`esp_image_header_t` structure describes the mode of SPI flash and the count of memory segments.
2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in ESP32's memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way:
2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in {IDF_TARGET_NAME}'s memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way:
* offset for 0 Segment = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`).
* offset for 1 Segment = offset for 0 Segment + length of 0 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`).
@ -17,7 +17,7 @@ To get the list of your image segments, please run the following command:
::
esptool.py --chip esp32 image_info build/app.bin
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
::
@ -58,7 +58,7 @@ You can also see the information on segments in the IDF logs while your applicat
I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load
I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load
For more details on the type of memory segments and their address ranges, see the ESP32 Technical Reference Manual, Section 1.3.2 *Embedded Memory*.
For more details on the type of memory segments and their address ranges, see the {IDF_TARGET_NAME} Technical Reference Manual, Section 1.3.2 *Embedded Memory*.
3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding.
4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from first byte and up to this field. The length of this field is 32 bytes.

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

@ -4,7 +4,7 @@ Application Level Tracing
Overview
--------
IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution.
IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution.
Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are:
1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing`

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

@ -11,8 +11,12 @@ The eFuse Manager library is designed to structure access to eFuse bits and make
Hardware description
--------------------
The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0.
Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). For more details see `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
The {IDF_TARGET_NAME} has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0.
Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0).
.. only:: esp32
For more details see `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available):
@ -21,6 +25,14 @@ ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are availabl
* EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose;
* EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF.
.. only:: esp32s2
For more details see `ESP32-S2 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_. Some eFuse bits are available for user applications.
{IDF_TARGET_NAME} has 11 eFuse blocks each of the size of 256 bits (not all bits are available):
Each block is divided into 8 32-bits registers.
@ -89,9 +101,9 @@ To generate a `common` files, use the following command ``idf.py efuse_common_ta
::
cd $IDF_PATH/components/efuse/
./efuse_table_gen.py esp32/esp_efuse_table.csv
./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv
After generation in the folder `esp32` create:
After generation in the folder `{IDF_TARGET_PATH_NAME}` create:
* `esp_efuse_table.c` file.
* In `include` folder `esp_efuse_table.c` file.
@ -101,7 +113,7 @@ To generate a `custom` files, use the following command ``idf.py efuse_custom_ta
::
cd $IDF_PATH/components/efuse/
./efuse_table_gen.py esp32/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv
./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv
After generation in the folder PROJECT_PATH/main create:
@ -181,7 +193,7 @@ How add a new field
::
$ ./efuse_table_gen.py esp32/esp_efuse_table.csv --info
$ ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv --info
eFuse coding scheme: NONE
# field_name efuse_block bit_start bit_count
1 WR_DIS_FLASH_CRYPT_CNT EFUSE_BLK0 2 1
@ -242,7 +254,7 @@ How add a new field
Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif)
Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32/esp_efuse_table.csv ...
Parsing eFuse CSV input file $IDF_PATH/components/efuse/{IDF_TARGET_PATH_NAME}/esp_efuse_table.csv ...
Verifying eFuse table...
@ -263,7 +275,7 @@ The Kconfig option :envvar:`CONFIG_EFUSE_VIRTUAL` will virtualize eFuse values i
espefuse.py
^^^^^^^^^^^
esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
::

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

@ -280,7 +280,7 @@ To gather and analyse heap trace do the following on the host:
Using this file GDB will connect to the target, reset it, and start tracing when program hits breakpoint at :cpp:func:`heap_trace_start`. Trace data will be saved to ``/tmp/heap_log.svdat``. Tracing will be stopped when program hits breakpoint at :cpp:func:`heap_trace_stop`.
4. Run GDB using the following command ``xtensa-esp32-elf-gdb -x gdbinit </path/to/program/elf>``
4. Run GDB using the following command ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit </path/to/program/elf>``
5. Quit GDB when program stops at :cpp:func:`heap_trace_stop`. Trace data are saved in ``/tmp/heap.svdat``

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

@ -16,8 +16,8 @@ System API
Heap Memory Allocation <mem_alloc>
Heap Memory Debugging <heap_debug>
High Resolution Timer <esp_timer>
Himem (large external SPI RAM) API <himem>
Inter-Processor Call <ipc>
:esp32: Himem (large external SPI RAM) API <himem>
:esp32: Inter-Processor Call <ipc>
Call function with external stack <esp_expression_with_stack>
Interrupt Allocation <intr_alloc>
Logging <log>

12
docs/en/api-reference/system/intr_alloc.rst
View file

@ -4,7 +4,15 @@ Interrupt allocation
Overview
--------
The ESP32 has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
.. only:: esp32
The {IDF_TARGET_NAME} has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
.. only.. esp32s2
The {IDF_TARGET_NAME} has one cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected
to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in
multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details.
@ -34,7 +42,7 @@ Multicore issues
Peripherals that can generate interrupts can be divided in two types:
- External peripherals, within the ESP32 but outside the Xtensa cores themselves. Most ESP32 peripherals are of this type.
- External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type.
- Internal peripherals, part of the Xtensa CPU cores themselves.
Interrupt handling differs slightly between these two types of peripherals.

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

@ -8,7 +8,7 @@ ESP-IDF applications use the common computer architecture patterns of *stack* (d
Because ESP-IDF is a multi-threaded RTOS environment, each RTOS task has its own stack. By default, each of these stacks is allocated from the heap when the task is created. (See :cpp:func:`xTaskCreateStatic` for the alternative where stacks are statically allocated.)
Because ESP32 uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes.
Because {IDF_TARGET_NAME} uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes.
For most purposes, the standard libc ``malloc()`` and ``free()`` functions can be used for heap allocation without any special consideration.
@ -18,7 +18,7 @@ capabilities-based heap memory allocator. If you want to have memory with certai
Memory Capabilities
-------------------
The ESP32 contains multiple types of RAM:
The {IDF_TARGET_NAME} contains multiple types of RAM:
- DRAM (Data RAM) is memory used to hold data. This is the most common kind of memory accessed as heap.
- IRAM (Instruction RAM) usually holds executable data only. If accessed as generic memory, all accesses must be :ref:`32-bit aligned<32-Bit Accessible Memory>`.
@ -26,7 +26,7 @@ The ESP32 contains multiple types of RAM:
For more details on these internal memory types, see :ref:`memory-layout`.
It's also possible to connect external SPI RAM to the ESP32 - :doc:`external RAM </api-guides/external-ram>` can be integrated into the ESP32's memory map using the flash cache, and accessed similarly to DRAM.
It's also possible to connect external SPI RAM to the {IDF_TARGET_NAME} - :doc:`external RAM </api-guides/external-ram>` can be integrated into the {IDF_TARGET_NAME}'s memory map using the flash cache, and accessed similarly to DRAM.
DRAM uses capability ``MALLOC_CAP_8BIT`` (accessible in single byte reads and writes). When calling ``malloc()``, the ESP-IDF ``malloc()`` implementation internally calls ``heap_caps_malloc(size, MALLOC_CAP_8BIT)`` in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime, call cpp:func:`heap_caps_get_free_size(MALLOC_CAP_8BIT)`.
@ -57,7 +57,7 @@ The :ref:`idf.py size <idf.py-size>` command can be used to find the amount of I
D/IRAM
^^^^^^
Some memory in the ESP32 is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease.
Some memory in the {IDF_TARGET_NAME} is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease.
Heap Sizes
^^^^^^^^^^
@ -95,7 +95,7 @@ Use the ``MALLOC_CAP_DMA`` flag to allocate memory which is suitable for use wit
If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be
useful to allocate it with the ``MALLOC_CAP_32BIT`` flag. This also allows the allocator to give out IRAM memory; something
which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32.
which it can't do for a normal malloc() call. This can help to use all the available memory in the {IDF_TARGET_NAME}.
Memory allocated with ``MALLOC_CAP_32BIT`` can *only* be accessed via 32-bit reads and writes, any other type of access will
generate a fatal LoadStoreError exception.
@ -105,6 +105,8 @@ External SPI Memory
When :doc:`external RAM </api-guides/external-ram>` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details.
..only:: esp32
To use the region above the 4MiB limit, you can use the :doc:`himem API</api-reference/system/himem>`.

3
docs/en/api-reference/system/ota.rst
View file

@ -189,6 +189,9 @@ Restrictions:
``security_version``:
- In application image it is stored in ``esp_app_desc`` structure. The number is set :ref:`CONFIG_BOOTLOADER_APP_SECURE_VERSION`.
.. only:: esp32
- In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app.
.. _secure-ota-updates:

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

@ -1,7 +1,7 @@
Performance Monitor
===================
The Performance Monitor component provides APIs to use ESP32 internal performance counters to profile functions and
The Performance Monitor component provides APIs to use {IDF_TARGET_NAME} internal performance counters to profile functions and
applications.
Application Example

13
docs/en/api-reference/system/power_management.rst
View file

@ -31,13 +31,8 @@ Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an a
- ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated.
- ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``).
.. only:: esp32
Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
.. only:: esp32s2beta
Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
.. note::
@ -55,14 +50,14 @@ Applications have the ability to acquire/release locks in order to control the p
Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to be released the same number of times to remove associated restrictions.
ESP32 supports three types of locks described in the table below.
{IDF_TARGET_NAME} supports three types of locks described in the table below.
============================ ======================================================
Lock Description
============================ ======================================================
``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For ESP32, this value can be set to 80 MHz, 160 MHz, or 240 MHz.
``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to 80 MHz, 160 MHz, or 240 MHz.
``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For ESP32, this is 80 MHz.
``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz.
``ESP_PM_NO_LIGHT_SLEEP`` Disables automatic switching to light sleep.
============================ ======================================================

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

@ -4,7 +4,7 @@ Sleep Modes
Overview
--------
ESP32 is capable of light sleep and deep sleep power saving modes.
{IDF_TARGET_NAME} is capable of light sleep and deep sleep power saving modes.
In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-gated, and supply voltage is reduced. Upon exit from light sleep, peripherals and CPUs resume operation, their internal state is preserved.
@ -29,7 +29,7 @@ Wakeup sources
Timer
^^^^^
RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the ESP32 Technical Reference Manual for details about RTC clock options.
RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the {IDF_TARGET_NAME} Technical Reference Manual for details about RTC clock options.
This wakeup mode doesn't require RTC peripherals or RTC memories to be powered on during sleep.
@ -40,6 +40,8 @@ Touch pad
RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to configure the touch pad interrupt before the chip starts deep sleep.
.. only:: esp32
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
:cpp:func:`esp_sleep_enable_touchpad_wakeup` function can be used to enable this wakeup source.
@ -52,6 +54,8 @@ RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a
Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using :cpp:func:`rtc_gpio_pullup_en` and :cpp:func:`rtc_gpio_pulldown_en` functions, before calling :cpp:func:`esp_sleep_start`.
.. only:: esp32
In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources.
:cpp:func:`esp_sleep_enable_ext0_wakeup` function can be used to enable this wakeup source.
@ -81,6 +85,8 @@ ULP coprocessor wakeup
ULP coprocessor can run while the chip is in sleep mode, and may be used to poll sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP coprocessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memory. RTC slow memory will be powered on during sleep if this wakeup mode is requested. RTC peripherals will be automatically powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals are automatically powered down again.
.. only:: esp32
Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO).
:cpp:func:`esp_sleep_enable_ulp_wakeup` function can be used to enable this wakeup source.
@ -95,7 +101,7 @@ In addition to EXT0 and EXT1 wakeup sources described above, one more method of
UART wakeup (light sleep only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When ESP32 receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the ESP32 to trigger wakeup, before sending the data.
When {IDF_TARGET_NAME} receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the {IDF_TARGET_NAME} to trigger wakeup, before sending the data.
:cpp:func:`esp_sleep_enable_uart_wakeup` function can be used to enable this wakeup source.
@ -105,6 +111,8 @@ Power-down of RTC peripherals and memories
By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_start` functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, :cpp:func:`esp_sleep_pd_config` function is provided.
.. only:: esp32
Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep.
If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired.
@ -123,7 +131,7 @@ Entering deep sleep
Configuring IOs
---------------
Some ESP32 IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns.
Some {IDF_TARGET_NAME} IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns.
To isolate a pin, preventing extra current draw, call :cpp:func:`rtc_gpio_isolate` function.

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

@ -26,7 +26,7 @@ Note that ESP-IDF supports multiple heaps with different capabilities. Functions
Random number generation
------------------------
ESP32 contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`.
{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`.
When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number generator (RNG) can be considered true random numbers. Without Wi-Fi or Bluetooth enabled, hardware RNG is a pseudo-random number generator. At startup, ESP-IDF bootloader seeds the hardware RNG with entropy, but care must be taken when reading random values between the start of ``app_main`` and initialization of Wi-Fi or Bluetooth drivers.
@ -38,7 +38,7 @@ These APIs allow querying and customizing MAC addresses for different network in
In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from internal eFuse, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details.
For ESP32:
.. only:: esp32
+---------------+--------------------------------+----------------------------------+
| Interface | MAC address | MAC address |
@ -54,7 +54,7 @@ For ESP32:
| | | first octet randomized |
+---------------+--------------------------------+----------------------------------+
For ESP32-S2:
.. only:: esp32s2
+---------------+--------------------------------+----------------------------------+
| Interface | MAC address | MAC address |

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

@ -44,7 +44,7 @@ elect to be watched by the TWDT. Each watched task must 'reset' the TWDT
periodically to indicate that they have been allocated CPU time. If a task does
not reset within the TWDT timeout period, a warning will be printed with
information about which tasks failed to reset the TWDT in time and which
tasks are currently running on the ESP32 CPUs.
tasks are currently running on the {IDF_TARGET_NAME} CPUs.
And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler`
in the user code to receive this event.
@ -79,7 +79,7 @@ debug code. Therefore OpenOCD will disable the hardware timers of both the
interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not
reenable them upon leaving the breakpoint. This means that interrupt watchdog
and task watchdog functionality will essentially be disabled. No warnings or
panics from either watchdogs will be generated when the ESP32 is connected to
panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to
OpenOCD via JTAG.
@ -89,7 +89,7 @@ Interrupt Watchdog API Reference
Header File
^^^^^^^^^^^
* :component_file:`esp32/include/esp_int_wdt.h`
* :component_file:`{IDF_TARGET_PATH_NAME}/include/esp_int_wdt.h`
Functions

7
docs/en/contribute/add-ons-reference.rst
View file

@ -119,7 +119,6 @@ Other Extensions
:idf_file:`docs/idf_extensions/include_build_file.py`
The ``include-build-file`` directive is like the built-in ``include-file`` directive, but file path is evaluated relative to ``build_dir``.
:idf_file:`docs/idf_extensions/kconfig_reference.py`
Subscribes to ``idf-info`` event and uses confgen to generate ``kconfig.inc`` from the components included in the default project build. This file is then included into :doc:`/api-reference/kconfig`.
@ -147,6 +146,12 @@ Other Extensions
:idf_file:`docs/idf_extensions/util.py`
A collection of utility functions useful primarily when building documentation locally (see :ref:`setup-for-building-documentation`) to reduce the time to generate documentation on a second and subsequent builds.
:idf_file:`docs/idf_extensions/format_idf_target.py`
An extension for replacing generic target related names with the idf_target passed to the Sphinx command line.
This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
This cannot be used inside tables.
Related Documents
-----------------

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

@ -1,18 +1,19 @@
Establish Serial Connection with ESP32
==============================================
Establish Serial Connection with {IDF_TARGET_NAME}
==================================================
:link_to_translation:`zh_CN:[中文]`
This section provides guidance how to establish serial connection between ESP32 and PC.
This section provides guidance how to establish serial connection between {IDF_TARGET_NAME} and PC.
Connect ESP32 to PC
--------------------
Connect {IDF_TARGET_NAME} to PC
-------------------------------
Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them.
Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them.
Below are the links to drivers for ESP32 boards produced by Espressif:
Below are the links to drivers for {IDF_TARGET_NAME} boards produced by Espressif:
.. only:: esp32
.. csv-table::
:header: Development Board, USB Driver, Remarks
@ -41,7 +42,7 @@ The drivers above are primarily for reference. Under normal circumstances, the d
Check port on Windows
---------------------
Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again.
Check the list of identified COM ports in the Windows Device Manager. Disconnect {IDF_TARGET_NAME} and connect it back, to verify which port disappears from the list and then shows back again.
Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
@ -63,7 +64,7 @@ Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
Check port on Linux and MacOS
-----------------------------
To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
To check the device name for the serial port of your {IDF_TARGET_NAME} board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
Linux ::
@ -116,7 +117,7 @@ Run terminal, set identified serial port, baud rate = 115200, data bits = 8, sto
Setting Serial Communication in PuTTY on Linux
Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below.
Then open serial port in terminal and check, if you see any log printed out by {IDF_TARGET_NAME}. The log contents will depend on application loaded to {IDF_TARGET_NAME}. An example log by {IDF_TARGET_NAME} is shown below.
.. highlight:: none
@ -141,16 +142,16 @@ Then open serial port in terminal and check, if you see any log printed out by E
...
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to {IDF_TARGET_NAME}.
.. note::
For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details.
For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the {IDF_TARGET_NAME} will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details.
.. note::
Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal.
Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to {IDF_TARGET_NAME}. This application will not be able to access serial port while it is open in terminal.
If you got here from :ref:`get-started-connect` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure`.
If you got here from :ref:`get-started-connect` when installing s/w for {IDF_TARGET_NAME} development, then you can continue with :ref:`get-started-configure`.
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader

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

@ -4,16 +4,18 @@ Get Started
:link_to_translation:`zh_CN:[中文]`
This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif.
This document is intended to help you set up the software development environment for the hardware based on the {IDF_TARGET_NAME} 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.
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 {IDF_TARGET_NAME} board.
.. include-build-file:: inc/version-note.inc
Introduction
============
ESP32 is a system on a chip that integrates the following features:
..only:: esp32
{IDF_TARGET_NAME} is a system on a chip that integrates the following features:
* Wi-Fi (2.4 GHz band)
* Bluetooth 4.2
@ -21,39 +23,49 @@ ESP32 is a system on a chip that integrates the following features:
* Ultra Low Power co-processor
* Several peripherals
Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
.. only:: esp32s2
Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
{IDF_TARGET_NAME} is a system on a chip that integrates the following features:
* Wi-Fi (2.4 GHz band)
* Ultra Low Power co-processor
* Several peripherals
Powered by 40 nm technology, {IDF_TARGET_NAME} provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
Espressif provides basic hardware and software resources to help application developers realize their ideas using the {IDF_TARGET_NAME} series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
What You Need
=============
Hardware:
* An **ESP32** board
* An **{IDF_TARGET_NAME}** board
* **USB cable** - USB A / micro USB B
* **Computer** running Windows, Linux, or macOS
Software:
* **Toolchain** to compile code for ESP32
* **Build tools** - CMake and Ninja to build a full **Application** for ESP32
* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain**
* **Toolchain** to compile code for {IDF_TARGET_NAME}
* **Build tools** - CMake and Ninja to build a full **Application** for {IDF_TARGET_NAME}
* **ESP-IDF** that essentially contains API (software libraries and source code) for {IDF_TARGET_NAME} and scripts to operate the **Toolchain**
* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse <https://www.eclipse.org/>`_
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:alt: Development of applications for {IDF_TARGET_NAME}
:figclass: align-center
Development of applications for ESP32
Development of applications for {IDF_TARGET_NAME}
Development Board Overviews
===========================
If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware.
If you have one of {IDF_TARGET_NAME} development boards listed below, you can click on the link to learn more about its hardware.
.. only:: esp32
.. toctree::
:maxdepth: 1
@ -128,7 +140,7 @@ Some tools need to be installed on the computer before proceeding to the next st
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>`_.
To build applications for the {IDF_TARGET_NAME}, you need the software libraries provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``, following instructions below specific to your operating system.
@ -239,7 +251,7 @@ You can also automate this step, making ESP-IDF tools available in every termina
Step 5. Start a Project
=======================
Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
Copy :example:`get-started/hello_world` to ``~/esp`` directory:
@ -272,7 +284,7 @@ It is also possible to build examples in-place, without copying them first.
Step 6. Connect Your Device
===========================
Now connect your ESP32 board to the computer and check under what serial port the board is visible.
Now connect your {IDF_TARGET_NAME} board to the computer and check under what serial port the board is visible.
Serial ports have the following patterns in their names:
@ -336,6 +348,8 @@ To navigate and use ``menuconfig``, press the following keys:
* ``?`` while highlighting a configuration item to display help about that item
* ``/`` to find configuration items
.. only:: esp32
.. attention::
If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples.
@ -379,11 +393,11 @@ If there are no errors, the build will finish by generating the firmware binary
Step 9. Flash onto the Device
=============================
Flash the binaries that you just built onto your ESP32 board by running::
Flash the binaries that you just built onto your {IDF_TARGET_NAME} 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`.
Replace PORT with your {IDF_TARGET_NAME} 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``.
@ -400,8 +414,8 @@ For more information on idf.py arguments, see :ref:`idf.py`.
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)
Detecting chip type... {IDF_TARGET_NAME}
Chip is {IDF_TARGET_NAME}D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core
Uploading stub...
Running stub...

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

@ -66,22 +66,22 @@ Download ``crosstool-NG`` and build it:
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``.
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``.
Add Toolchain to PATH
=====================
The custom toolchain needs to be copied to a binary directory and added to the ``PATH``.
Choose a directory, for example ``~/esp/xtensa-esp32-elf/``, and copy the build output to this directory.
Choose a directory, for example ``~/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/``, and copy the build output to this directory.
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
export PATH="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH"
.. note::
@ -94,7 +94,7 @@ Log off and log in back to make the ``.profile`` changes effective. Run the foll
You are looking for similar result containing toolchain's path at the beginning of displayed string::
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
/home/user-name/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
Instead of ``/home/user-name`` there should be a home path specific to your installation.

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

@ -30,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>`.
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
Next Steps
==========

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

@ -73,11 +73,11 @@ Download ``crosstool-NG`` and build it:
Build the toolchain::
./ct-ng xtensa-esp32-elf
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` to ``PATH`` environment variable.
Next Steps

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

@ -81,12 +81,12 @@ Download the precompiled Windows toolchain:
|download_link_win32|
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``.
Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``.
.. note::
If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
If you 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-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
.. _add-directory-windows-path:

20
docs/en/hw-reference/index.rst
View file

@ -1,8 +1,10 @@
************************
ESP32 Hardware Reference
************************
************************************
{IDF_TARGET_NAME} Hardware Reference
************************************
:link_to_translation:`zh_CN:[中文]`
.. only:: esp32
.. toctree::
:maxdepth: 3
@ -14,3 +16,15 @@ ESP32 Hardware Reference
Previous Versions of Modules and Boards <modules-and-boards-previous>
Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
Regulatory Certificates <https://www.espressif.com/en/certificates>
.. only:: esp32s2beta
.. toctree::
:maxdepth: 3
Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>
Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_datasheet_en.pdf>
Modules and Boards <modules-and-boards>
Previous Versions of Modules and Boards <modules-and-boards-previous>
Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
Regulatory Certificates <https://www.espressif.com/en/certificates>

8
docs/en/libraries-and-frameworks/cloud-frameworks.rst
View file

@ -1,21 +1,21 @@
Cloud Frameworks
================
ESP32 supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworks' agents and examples:
{IDF_TARGET_NAME} supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworks' agents and examples:
AWS IoT
-------
`https://github.com/espressif/esp-aws-iot <https://github.com/espressif/esp-aws-iot>`_ is an open source repository for ESP32 based on Amazon Web Services' `aws-iot-device-sdk-embedded-C <https://github.com/aws/aws-iot-device-sdk-embedded-C>`_.
`https://github.com/espressif/esp-aws-iot <https://github.com/espressif/esp-aws-iot>`_ is an open source repository for {IDF_TARGET_NAME} based on Amazon Web Services' `aws-iot-device-sdk-embedded-C <https://github.com/aws/aws-iot-device-sdk-embedded-C>`_.
Azure IoT
---------
`https://github.com/espressif/esp-azure <https://github.com/espressif/esp-azure>`_ is an open source repository for ESP32 based on Microsoft Azure's `azure-iot-sdk-c SDK <https://github.com/Azure/azure-iot-sdk-c>`_.
`https://github.com/espressif/esp-azure <https://github.com/espressif/esp-azure>`_ is an open source repository for {IDF_TARGET_NAME} based on Microsoft Azure's `azure-iot-sdk-c SDK <https://github.com/Azure/azure-iot-sdk-c>`_.
Google IoT Core
---------------
`https://github.com/espressif/esp-google-iot <https://github.com/espressif/esp-google-iot>`_ is an open source repository for ESP32 based on Google's `iot-device-sdk-embedded-c SDK <https://github.com/GoogleCloudPlatform/iot-device-sdk-embedded-c>`_.
`https://github.com/espressif/esp-google-iot <https://github.com/espressif/esp-google-iot>`_ is an open source repository for {IDF_TARGET_NAME} based on Google's `iot-device-sdk-embedded-c SDK <https://github.com/GoogleCloudPlatform/iot-device-sdk-embedded-c>`_.

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

@ -4,14 +4,23 @@ Flash Encryption
:link_to_translation:`zh_CN:[中文]`
This document provides introduction to Flash encryption concept on ESP32 and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_.
.. only:: esp32
This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_.
.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. only:: esp32s2beta
This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32-S2 Technical reference manual`_.
.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf
Introduction
------------
Flash encryption is a feature for encrypting the contents of the ESP32's attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents. Encryption is applied by flashing the ESP32 with plaintext data, and (if encryption is enabled) the bootloader encrypts the data in place on first boot.
Flash encryption is a feature for encrypting the contents of the {IDF_TARGET_NAME}'s attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents. Encryption is applied by flashing the {IDF_TARGET_NAME} with plaintext data, and (if encryption is enabled) the bootloader encrypts the data in place on first boot.
With flash encryption enabled, following kinds of flash data are encrypted by default:
@ -30,13 +39,13 @@ Flash encryption is separate from the :doc:`Secure Boot <secure-boot>` feature,
For production use, flash encryption should be enabled in the "Release" mode only.
.. important::
Enabling flash encryption limits the options for further updates of the ESP32. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption.
Enabling flash encryption limits the options for further updates of the {IDF_TARGET_NAME}. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption.
.. _flash-encryption-efuse:
eFuse Used During Flash Encryption Process
-------------------------------------------
The flash encryption operation is controlled by various eFuses available on ESP32. Below is the list of eFuse and their description:
The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. Below is the list of eFuse and their description:
::
@ -79,7 +88,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3
not encrypt flash at boot time
Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`.
Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about {IDF_TARGET_NAME} eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`.
Flash Encryption Process
@ -96,7 +105,7 @@ Assuming the eFuse values are in default state and second stage bootloader is co
- For :ref:`flash_enc_development_mode` second stage bootloader will program only ``download_dis_decrypt`` & ``download_dis_cache`` eFuse bits to allow UART bootloader reflashing of encrypted binaries. Also ``FLASH_CRYPT_CNT`` eFuse bits will NOT be write protected.
- The second stage bootloader then reboots the device to start executing encrypted image. It will transparently decrypt the flash contents and load into IRAM.
During development stage there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires UART download mode to be able to load new plaintext images as many number of times as required. However during manufacturing or production UART download mode should not be allowed to access flash contents due to security reason. Hence this requires two different ESP32 configurations: one for development and other for production. Following section describes :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` for flash encryption and a step by step process to use them.
During development stage there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires UART download mode to be able to load new plaintext images as many number of times as required. However during manufacturing or production UART download mode should not be allowed to access flash contents due to security reason. Hence this requires two different {IDF_TARGET_NAME} configurations: one for development and other for production. Following section describes :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` for flash encryption and a step by step process to use them.
.. important::
Development mode as the name suggests should be used ONLY DURING DEVELOPMENT as it does not prevent modification and possible read back of encrypted flash contents.
@ -110,14 +119,14 @@ Steps to Setup Flash Encryption
Development Mode
^^^^^^^^^^^^^^^^
It is possible to run flash encryption process for development using either ESP32 internally generated key or external host generated keys.
It is possible to run flash encryption process for development using either {IDF_TARGET_NAME} internally generated key or external host generated keys.
Using ESP32 Generated Flash Encryption Key
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using {IDF_TARGET_NAME} Generated Flash Encryption Key
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As mentioned above :ref:`flash_enc_development_mode` allows user to download as many plaintext images using UART download mode. Following steps needs to be done to test flash encryption process:
- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value.
@ -139,7 +148,7 @@ Build and flash the complete image including: bootloader, partition table and ap
idf.py flash monitor
Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time.
Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when {IDF_TARGET_NAME} boots after flash encryption is enabled for the first time.
::
@ -261,7 +270,7 @@ Once the flashing is complete device will reset and on next boot second stage bo
I (211) cpu_start: ELF file SHA256: 8770c886bdf561a7...
I (217) cpu_start: ESP-IDF: v4.0-dev-850-gc4447462d-dirty
I (224) cpu_start: Starting app cpu, entry point is 0x40080e4c
0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/esp32/cpu_start.c:265
0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:265
I (0) cpu_start: App cpu up.
I (235) heap_init: Initializing. RAM available for dynamic allocation:
@ -275,7 +284,7 @@ Once the flashing is complete device will reset and on next boot second stage bo
I (0) cpu_start: Starting scheduler on APP CPU.
Sample program to check Flash Encryption
This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
This is {IDF_TARGET_NAME} chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
Flash encryption feature is enabled
Flash encryption mode is DEVELOPMENT
Flash in encrypted mode with flash_crypt_cnt = 1
@ -303,17 +312,17 @@ If all partitions needs to be updated in encrypted format, it can be done as
Using Host Generated Flash Encryption Key
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to pregenerate the flash encryption key on the host computer and burn it into the ESP32's eFuse key block. This allows data to be pre-encrypted on the host and flashed to the ESP32 without needing a plaintext flash update. This feature allows encrypted flashing in both :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` modes.
It is possible to pregenerate the flash encryption key on the host computer and burn it into the {IDF_TARGET_NAME}'s eFuse key block. This allows data to be pre-encrypted on the host and flashed to the {IDF_TARGET_NAME} without needing a plaintext flash update. This feature allows encrypted flashing in both :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` modes.
.. note:: This option is not recommended for production unless a separate key is generated for each individual device.
- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Generate a random key with espsecure.py::
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
- Burn the key to the device (one time only). **This must be done before first encrypted boot**, otherwise the ESP32 will generate a random key that software can't access or modify::
- Burn the key to the device (one time only). **This must be done before first encrypted boot**, otherwise the {IDF_TARGET_NAME} will generate a random key that software can't access or modify::
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
@ -353,7 +362,7 @@ Release Mode
In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash.
- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features".
@ -382,7 +391,7 @@ For subsequent plaintext update in field :ref:`OTA scheme <updating-encrypted-fl
Possible Failures
^^^^^^^^^^^^^^^^^
Once flash encryption is enabled and if the ``FLASH_CRYPT_CNT`` eFuse value has an odd number of bits set then all the partitions (which are marked with encryption flag) are expected to contain encrypted ciphertext. Below are three typical failure cases if the ESP32 is loaded with plaintext data:
Once flash encryption is enabled and if the ``FLASH_CRYPT_CNT`` eFuse value has an odd number of bits set then all the partitions (which are marked with encryption flag) are expected to contain encrypted ciphertext. Below are three typical failure cases if the {IDF_TARGET_NAME} is loaded with plaintext data:
1. In case the bootloader partition is re-updated with plaintext bootloader image the ROM loader will fail to load the bootloader and following type of failure will be displayed:
@ -477,7 +486,7 @@ Key Points About Flash Encryption
- The `flash encryption algorithm` is AES-256, where the key is "tweaked" with the offset address of each 32 byte block of flash. This means every 32 byte block (two consecutive 16 byte AES blocks) is encrypted with a unique key derived from the flash encryption key.
- Flash access is transparent via the flash cache mapping feature of ESP32 - any flash regions which are mapped to the address space will be transparently decrypted when read.
- Flash access is transparent via the flash cache mapping feature of {IDF_TARGET_NAME} - any flash regions which are mapped to the address space will be transparently decrypted when read.
It may be desirable for some data partitions to remain unencrypted for ease of access, or to use flash-friendly update algorithms that are ineffective if the data is encrypted. NVS partitions for non-volatile storage cannot be encrypted since NVS library is not directly compatible with flash encryption. Refer to :ref:`NVS Encryption <nvs_encryption>` for more details.
@ -489,7 +498,7 @@ Key Points About Flash Encryption
.. note:: The bootloader app binary ``bootloader.bin`` may become too large when both secure boot and flash encryption are enabled. See :ref:`secure-boot-bootloader-size`.
.. important::
Do not interrupt power to the ESP32 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit.
Do not interrupt power to the {IDF_TARGET_NAME} while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit.
.. _using-encrypted-flash:
@ -497,7 +506,7 @@ Key Points About Flash Encryption
Using Encrypted Flash
---------------------
ESP32 app code can check if flash encryption is currently enabled by calling :cpp:func:`esp_flash_encryption_enabled`. Also, device can identify the flash encryption mode by calling :cpp:func:`esp_get_flash_encryption_mode`.
{IDF_TARGET_NAME} app code can check if flash encryption is currently enabled by calling :cpp:func:`esp_flash_encryption_enabled`. Also, device can identify the flash encryption mode by calling :cpp:func:`esp_get_flash_encryption_mode`.
Once flash encryption is enabled, some care needs to be taken when accessing flash contents from code.
@ -558,7 +567,7 @@ Please refer to :doc:`OTA <../api-reference/system/ota>` for general information
Disabling Flash Encryption
--------------------------
If you've accidentally enabled flash encryption for some reason, the next flash of plaintext data will soft-brick the ESP32 (the device will reboot continuously, printing the error ``flash read err, 1000``).
If you've accidentally enabled flash encryption for some reason, the next flash of plaintext data will soft-brick the {IDF_TARGET_NAME} (the device will reboot continuously, printing the error ``flash read err, 1000``).
If flash encryption is enabled in Development mode, you can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse. This can only be done three times per chip.
@ -569,7 +578,7 @@ If flash encryption is enabled in Development mode, you can disable flash encryp
- Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT::
espefuse.py burn_efuse FLASH_CRYPT_CNT
Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal.
Reset the {IDF_TARGET_NAME} and flash encryption should be disabled, the bootloader will boot as normal.
.. _flash-encryption-limitations:
@ -596,7 +605,7 @@ Flash Encryption and Secure Boot
It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device:
- :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key).
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
- :ref:`Plaintext serial flash updates <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the {IDF_TARGET_NAME} (refer to :ref:`Secure Boot <secure-boot-reflashable>` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data.
- :ref:`Reflashing via Pregenerated Flash Encryption Key <pregenerated-flash-encryption-key>` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` option to be enabled in the Secure Boot config.
.. _flash-encryption-advanced-features:

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

@ -7,7 +7,7 @@ Secure Boot is separate from the :doc:`Flash Encryption <flash-encryption>` feat
.. important::
Enabling secure boot limits your options for further updates of your ESP32. Make sure to read this document throughly and understand the implications of enabling secure boot.
Enabling secure boot limits your options for further updates of your {IDF_TARGET_NAME}. Make sure to read this document throughly and understand the implications of enabling secure boot.
Background
----------
@ -49,7 +49,17 @@ The following keys are used by the secure boot process:
- "secure bootloader key" is a 256-bit AES key that is stored in Efuse block 2. The bootloader can generate this key itself from the internal hardware random number generator, the user does not need to supply it (it is optionally possible to supply this key, see :ref:`secure-boot-reflashable`). The Efuse holding this key is read & write protected (preventing software access) before secure boot is enabled.
- By default, the Efuse Block 2 Coding Scheme is "None" and a 256 bit key is stored in this block. On some ESP32s, the Coding Scheme is set to 3/4 Encoding (CODING_SCHEME efuse has value 1) and a 192 bit key must be stored in this block. See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details. The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details<secure-bootloader-digest-algorithm>`).
- By default, the Efuse Block 2 Coding Scheme is "None" and a 256 bit key is stored in this block. On some {IDF_TARGET_NAME}s, the Coding Scheme is set to 3/4 Encoding (CODING_SCHEME efuse has value 1) and a 192 bit key must be stored in this block.
.. only:: esp32
See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details.
.. only:: esp32s2
See ESP32-S2 Technical Reference Manual for more details.
The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details<secure-bootloader-digest-algorithm>`).
- "secure boot signing key" is a standard ECDSA public/private key pair (see :ref:`secure-boot-image-signing-algorithm`) in PEM format.
@ -64,7 +74,7 @@ Bootloader Size
When secure boot is enabled the bootloader app binary ``bootloader.bin`` may exceed the default bootloader size limit. This is especially likely if flash encryption is enabled as well. The default size limit is 0x7000 (28672) bytes (partition table offset 0x8000 - bootloader offset 0x1000).
If the bootloader becomes too large, the ESP32 will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum.
If the bootloader becomes too large, the {IDF_TARGET_NAME} will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum.
Options to work around this are:
@ -100,11 +110,11 @@ How To Enable Secure Boot
.. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled.
8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration.
8. Reset the {IDF_TARGET_NAME} and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the {IDF_TARGET_NAME} to verify that secure boot is enabled and no errors have occurred due to the build configuration.
.. note:: Secure boot won't be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured.
.. note:: If the ESP32 is reset or powered down during the first boot, it will start the process again on the next boot.
.. note:: If the {IDF_TARGET_NAME} is reset or powered down during the first boot, it will start the process again on the next boot.
9. On subsequent boots, the secure boot hardware will verify the software bootloader has not changed (using the secure bootloader key) and then the software bootloader will verify the signed partition table and app image (using the public key portion of the secure boot signing key).
@ -194,7 +204,7 @@ The following sections contain low-level reference descriptions of various secur
Secure Boot Hardware Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first stage of secure boot verification (checking the software bootloader) is done via hardware. The ESP32's Secure Boot support hardware can perform three basic operations:
The first stage of secure boot verification (checking the software bootloader) is done via hardware. The {IDF_TARGET_NAME}'s Secure Boot support hardware can perform three basic operations:
1. Generate a random sequence of bytes from a hardware random number generator.