alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'docs/update_api-reference/protocols_and_migration-guides' into 'master'

Browse Source 
docs: update format issues for EN and CN under api-reference/protocols and migration-guides

Closes DOC-5893

See merge request espressif/esp-idf!25090
This commit is contained in:
Cai Xin Ying 2023-08-10 17:26:54 +08:00
commit 67115a4013
56 changed files with 515 additions and 457 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/en/404.rst
View File

@ -2,17 +2,18 @@
Page not Found
==============
:link_to_translation:`zh_CN:[中文]`
.. note::
We're sorry. The page you requested could not be found. This error occurs maybe because the current chip or version you choose does not support the feature you are looking for. If you want to provide feedback about this document, please let us know what exact document you want to access, so that we can better help you.
We are sorry. The page you requested could not be found. This error occurs maybe because the current chip or version you choose does not support the feature you are looking for. If you want to provide feedback about this document, please let us know what exact document you want to access, so that we can better help you.
Please use the menu on the left to navigate through documentation contents. Optionally type the phrase you are looking for in the search box above the menu and press enter.
.. figure:: ../_static/404-page__en.svg
:align: center
:alt: We're sorry. The page you requested could not be found.
:alt: We are sorry. The page you requested could not be found.
:figclass: align-center
* :ref:`genindex`

1
docs/en/about.rst
View File

@ -1,5 +1,6 @@
About
=====
:link_to_translation:`zh_CN:[中文]`
.. only:: esp32

6
docs/en/api-reference/protocols/asio.rst
View File

@ -1,13 +1,13 @@
ASIO port
ASIO Port
=========
Asio is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach.
The ESP-IDF component `ASIO` has been moved from ESP-IDF since version v5.0 to a separate repository:
The ESP-IDF component ``ASIO`` has been moved from ESP-IDF since version v5.0 to a separate repository:
* `ASIO component on GitHub <https://github.com/espressif/esp-protocols/tree/master/components/asio>`__
To add ASIO component in your project, please run `idf.py add-dependency espressif/asio`
To add ASIO component in your project, please run ``idf.py add-dependency espressif/asio``.
Hosted Documentation
--------------------

18
docs/en/api-reference/protocols/esp_crt_bundle.rst
View File

@ -6,18 +6,22 @@ Overview
The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification.
.. note:: The bundle is currently not available when using WolfSSL.
.. note::
The bundle comes with the complete list of root certificates from Mozilla’s NSS root certificate store. Using the gen_crt_bundle.py python utility the certificates’ subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
The bundle is currently not available when using WolfSSL.
The bundle comes with the complete list of root certificates from Mozilla's NSS root certificate store. Using the gen_crt_bundle.py python utility the certificates' subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
When generating the bundle you may choose between:
* The full root certificate bundle from Mozilla, containing more than 130 certificates. The current bundle was updated Tue Jan 10 04:12:06 2023 GMT.
* A pre-selected filter list of the name of the most commonly used root certificates, reducing the amount of certificates to around 41 while still having around 90% absolute usage coverage and 99% market share coverage according to SSL certificate authorities statistics.
In addition it is possible to specify a path to a certificate file or a directory containing certificates which then will be added to the generated bundle.
In addition, it is possible to specify a path to a certificate file or a directory containing certificates which then will be added to the generated bundle.
.. note:: Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This includes removing them from `cacrt_all.pem`.
.. note::
Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This includes removing them from ``cacrt_all.pem``.
Configuration
-------------
@ -30,7 +34,7 @@ Most configuration is done through menuconfig. CMake will generate the bundle ac
To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
.. code:: c
.. code-block:: c
esp_tls_cfg_t cfg = {
.crt_bundle_attach = esp_crt_bundle_attach,
@ -40,7 +44,7 @@ This is done to avoid embedding the certificate bundle unless activated by the u
If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup process:
.. code:: c
.. code-block:: c
mbedtls_ssl_config conf;
mbedtls_ssl_config_init(&conf);
@ -53,10 +57,12 @@ If using mbedTLS directly then the bundle may be activated by directly calling t
Generating the List of Root Certificates
----------------------------------------
The list of root certificates comes from Mozilla's NSS root certificate store, which can be found `here <https://wiki.mozilla.org/CA/Included_Certificates>`_
The list can be downloaded and created by running the script ``mk-ca-bundle.pl`` that is distributed as a part of `curl <https://github.com/curl/curl>`_.
Another alternative would be to download the finished list directly from the curl website: `CA certificates extracted from Mozilla <https://curl.se/docs/caextract.html>`_
The common certificates bundle were made by selecting the authorities with a market share of more than 1 % from w3tech's `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_.
These authorities were then used to pick the names of the certificates for the filter list, `cmn_crt_authorities.csv`, from `this list <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ provided by Mozilla.

11
docs/en/api-reference/protocols/esp_http_client.rst
View File

@ -1,5 +1,6 @@
ESP HTTP Client
===============
:link_to_translation:`zh_CN:[中文]`
Overview
@ -7,8 +8,8 @@ Overview
``esp_http_client`` component provides a set of APIs for making HTTP/S requests from ESP-IDF applications. The steps to use these APIs are as follows:
* :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance, i.e., an HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values will be assumed for the configuration values that are not explicitly defined by the user.
* :cpp:func:`esp_http_client_perform`: Performs all operations of the ``esp_http_client`` - opening the connection, exchanging data, and closing the connection (as required), while blocking the current task before its completion. All related events will be invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
* :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance, i.e., an HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values are assumed for the configuration values that are not explicitly defined by the user.
* :cpp:func:`esp_http_client_perform`: Performs all operations of the ``esp_http_client`` - opening the connection, exchanging data, and closing the connection (as required), while blocking the current task before its completion. All related events are invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
* :cpp:func:`esp_http_client_cleanup`: Closes the connection (if any) and frees up all the memory allocated to the HTTP client instance. This must be the last function to be called after the completion of operations.
@ -36,7 +37,7 @@ To allow ESP HTTP client to take full advantage of persistent connections, one s
Use Secure Element (ATECC608) for TLS
_____________________________________
A secure element (ATECC608) can be also used for the underlying TLS connection in the HTTP client connection. Please refer to the *ATECC608A (Secure Element) with ESP-TLS* section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The secure element support has to be first enabled in menuconfig through :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`. Then the HTTP client can be configured to use secure element as follows:
A secure element (ATECC608) can be also used for the underlying TLS connection in the HTTP client connection. Please refer to the **ATECC608A (Secure Element) with ESP-TLS** section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The secure element support has to be first enabled in menuconfig through :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`. Then the HTTP client can be configured to use secure element as follows:
.. code-block:: c
@ -51,7 +52,9 @@ HTTPS Request
ESP HTTP client supports SSL connections using **mbedTLS**, with the ``url`` configuration starting with ``https`` scheme or ``transport_type`` set to ``HTTP_TRANSPORT_OVER_SSL``. HTTPS support can be configured via :ref:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` (enabled by default).
.. note:: While making HTTPS requests, if server verification is needed, an additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in the ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.
.. note::
While making HTTPS requests, if server verification is needed, an additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in the ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.
Check out the example functions ``https_with_url`` and ``https_with_hostname_path`` in the application example for implementation details of the above note.

12
docs/en/api-reference/protocols/esp_http_server.rst
View File

@ -8,16 +8,14 @@ Overview
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.
* :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 closes all open connections, removes registered URI handlers and resets all session context data to empty.
* :cpp:func:`httpd_register_uri_handler`: A URI handler is registered by passing object of type ``httpd_uri_t`` structure which has members including ``uri`` name, ``method`` type (eg. ``HTTPD_GET/HTTPD_POST/HTTPD_PUT`` etc.), function pointer of type ``esp_err_t *handler (httpd_req_t *req)`` and ``user_ctx`` pointer to user context data.
Application Example
-------------------
.. highlight:: c
::
.. code-block:: c
/* Our URI handler function to be called during GET /uri request */
esp_err_t get_handler(httpd_req_t *req)
@ -119,9 +117,7 @@ HTTP server features persistent connections, allowing for the re-use of the same
Persistent Connections Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. highlight:: c
::
.. code-block:: c
/* Custom function to free context */
void free_ctx_func(void *ctx)

1
docs/en/api-reference/protocols/esp_https_server.rst
View File

@ -1,5 +1,6 @@
HTTPS Server
============
:link_to_translation:`zh_CN:[中文]`
Overview

69
docs/en/api-reference/protocols/esp_local_ctrl.rst
View File

@ -3,13 +3,12 @@ ESP Local Control
Overview
--------
ESP Local Control (**esp_local_ctrl**) component in ESP-IDF provides capability to control an ESP device over HTTPS or BLE. It provides access to application defined **properties** that are available for reading / writing via a set of configurable handlers.
Initialization of the **esp_local_ctrl** service over BLE transport is performed as follows:
ESP Local Control (**esp_local_ctrl**) component in ESP-IDF provides capability to control an ESP device over HTTPS or Bluetooth® Low Energy. It provides access to application defined **properties** that are available for reading/writing via a set of configurable handlers.
.. highlight:: c
Initialization of the **esp_local_ctrl** service over Bluetooth Low Energy transport is performed as follows:
::
.. code-block:: c
esp_local_ctrl_config_t config = {
.transport = ESP_LOCAL_CTRL_TRANSPORT_BLE,
@ -46,9 +45,7 @@ Initialization of the **esp_local_ctrl** service over BLE transport is performed
Similarly for HTTPS transport:
.. highlight:: c
::
.. code-block:: c
/* Set the configuration */
httpd_ssl_config_t https_conf = HTTPD_SSL_CONFIG_DEFAULT();
@ -91,27 +88,27 @@ Similarly for HTTPS transport:
You may set security for transport in ESP local control using following options:
1. `PROTOCOM_SEC2`: specifies that SRP6a based key exchange and end to end encryption based on AES-GCM is used. This is the most preffered option as it adds a robust security with Augmented PAKE protocol i.e. SRP6a.
2. `PROTOCOM_SEC1`: specifies that Curve25519 based key exchange and end to end encryption based on AES-CTR is used.
3. `PROTOCOM_SEC0`: specifies that data will be exchanged as a plain text (no security).
4. `PROTOCOM_SEC_CUSTOM`: you can define your own security requirement. Please note that you will also have to provide `custom_handle` of type `protocomm_security_t *` in this context.
1. ``PROTOCOM_SEC2``: specifies that SRP6a based key exchange and end to end encryption based on AES-GCM is used. This is the most preffered option as it adds a robust security with Augmented PAKE protocol i.e., SRP6a.
2. ``PROTOCOM_SEC1``: specifies that Curve25519 based key exchange and end to end encryption based on AES-CTR is used.
3. ``PROTOCOM_SEC0``: specifies that data will be exchanged as a plain text (no security).
4. ``PROTOCOM_SEC_CUSTOM``: you can define your own security requirement. Please note that you will also have to provide ``custom_handle`` of type ``protocomm_security_t *`` in this context.
.. note:: The respective security schemes need to be enabled through the project configuration menu. Please refer to the Enabling protocom security version section in :doc:`Protocol Communication </api-reference/provisioning/protocomm>` for more details.
.. note::
Creating a property
The respective security schemes need to be enabled through the project configuration menu. Please refer to the Enabling protocom security version section in :doc:`Protocol Communication </api-reference/provisioning/protocomm>` for more details.
Creating a Property
-------------------
Now that we know how to start the **esp_local_ctrl** service, let's add a property to it. Each property must have a unique `name` (string), a `type` (e.g. enum), `flags` (bit fields) and `size`.
Now that we know how to start the **esp_local_ctrl** service, let us add a property to it. Each property must have a unique ``name`` (string), a ``type`` (e.g., enum), ``flags`` (bit fields) and ``size``.
The `size` is to be kept 0, if we want our property value to be of variable length (e.g. if its a string or bytestream). For fixed length property value data-types, like int, float, etc., setting the `size` field to the right value, helps **esp_local_ctrl** to perform internal checks on arguments received with write requests.
The ``size`` is to be kept 0, if we want our property value to be of variable length (e.g., if its a string or bytestream). For fixed length property value data-types, like int, float, etc., setting the ``size`` field to the right value, helps **esp_local_ctrl** to perform internal checks on arguments received with write requests.
The interpretation of `type` and `flags` fields is totally upto the application, hence they may be used as enumerations, bitfields, or even simple integers. One way is to use `type` values to classify properties, while `flags` to specify characteristics of a property.
The interpretation of ``type`` and ``flags`` fields is totally upto the application, hence they may be used as enumerations, bitfields, or even simple integers. One way is to use ``type`` values to classify properties, while ``flags`` to specify characteristics of a property.
Here is an example property which is to function as a timestamp. It is assumed that the application defines `TYPE_TIMESTAMP` and `READONLY`, which are used for setting the `type` and `flags` fields here.
Here is an example property which is to function as a timestamp. It is assumed that the application defines ``TYPE_TIMESTAMP`` and ``READONLY``, which are used for setting the ``type`` and ``flags`` fields here.
.. highlight:: c
::
.. code-block:: c
/* Create a timestamp property */
esp_local_ctrl_prop_t timestamp = {
@ -127,13 +124,11 @@ Here is an example property which is to function as a timestamp. It is assumed t
esp_local_ctrl_add_property(&timestamp);
Also notice that there is a ctx field, which is set to point to some custom `func_get_time()`. This can be used inside the property get / set handlers to retrieve timestamp.
Also notice that there is a ctx field, which is set to point to some custom ``func_get_time()``. This can be used inside the property get/set handlers to retrieve timestamp.
Here is an example of `get_prop_values()` handler, which is used for retrieving the timestamp.
Here is an example of ``get_prop_values()`` handler, which is used for retrieving the timestamp.
.. highlight:: c
::
.. code-block:: c
static esp_err_t get_property_values(size_t props_count,
const esp_local_ctrl_prop_t *props,
@ -146,11 +141,7 @@ Here is an example of `get_prop_values()` handler, which is used for retrieving
/* Obtain the timer function from ctx */
int32_t (*func_get_time)(void) = props[i].ctx;
/* Use static variable for saving the value.
* This is essential because the value has to be
* valid even after this function returns.
* Alternative is to use dynamic allocation
* and set the free_fn field */
/* Use static variable for saving the value. This is essential because the value has to be valid even after this function returns. Alternative is to use dynamic allocation and set the free_fn field */
static int32_t ts = func_get_time();
prop_values[i].data = &ts;
}
@ -159,11 +150,9 @@ Here is an example of `get_prop_values()` handler, which is used for retrieving
}
Here is an example of `set_prop_values()` handler. Notice how we restrict from writing to read-only properties.
Here is an example of ``set_prop_values()`` handler. Notice how we restrict from writing to read-only properties.
.. highlight:: c
::
.. code-block:: c
static esp_err_t set_property_values(size_t props_count,
const esp_local_ctrl_prop_t *props,
@ -191,15 +180,15 @@ For complete example see :example:`protocols/esp_local_ctrl`
Client Side Implementation
--------------------------
The client side implementation will have establish a protocomm session with the device first, over the supported mode of transport, and then send and receive protobuf messages understood by the **esp_local_ctrl** service. The service will translate these messages into requests and then call the appropriate handlers (set / get). Then, the generated response for each handler is again packed into a protobuf message and transmitted back to the client.
The client side implementation will have establish a protocomm session with the device first, over the supported mode of transport, and then send and receive protobuf messages understood by the **esp_local_ctrl** service. The service will translate these messages into requests and then call the appropriate handlers (set/get). Then, the generated response for each handler is again packed into a protobuf message and transmitted back to the client.
See below the various protobuf messages understood by the **esp_local_ctrl** service:
1. `get_prop_count` : This should simply return the total number of properties supported by the service
2. `get_prop_values` : This accepts an array of indices and should return the information (name, type, flags) and values of the properties corresponding to those indices
3. `set_prop_values` : This accepts an array of indices and an array of new values, which are used for setting the values of the properties corresponding to the indices
1. ``get_prop_count`` : This should simply return the total number of properties supported by the service
2. ``get_prop_values`` : This accepts an array of indices and should return the information (name, type, flags) and values of the properties corresponding to those indices
3. ``set_prop_values`` : This accepts an array of indices and an array of new values, which are used for setting the values of the properties corresponding to the indices
Note that indices may or may not be the same for a property, across multiple sessions. Therefore, the client must only use the names of the properties to uniquely identify them. So, every time a new session is established, the client should first call `get_prop_count` and then `get_prop_values`, hence form an index to name mapping for all properties. Now when calling `set_prop_values` for a set of properties, it must first convert the names to indexes, using the created mapping. As emphasized earlier, the client must refresh the index to name mapping every time a new session is established with the same device.
Note that indices may or may not be the same for a property, across multiple sessions. Therefore, the client must only use the names of the properties to uniquely identify them. So, every time a new session is established, the client should first call ``get_prop_count`` and then ``get_prop_values``, hence form an index to name mapping for all properties. Now when calling ``set_prop_values`` for a set of properties, it must first convert the names to indexes, using the created mapping. As emphasized earlier, the client must refresh the index to name mapping every time a new session is established with the same device.
The various protocomm endpoints provided by **esp_local_ctrl** are listed below:
@ -207,7 +196,7 @@ The various protocomm endpoints provided by **esp_local_ctrl** are listed below:
:widths: 10 25 50
:header-rows: 1
* - Endpoint Name (BLE + GATT Server)
* - Endpoint Name (Bluetooth Low Energy + GATT Server)
- URI (HTTPS Server + mDNS)
- Description
* - esp_local_ctrl/version

38
docs/en/api-reference/protocols/esp_sdio_slave_protocol.rst
View File

@ -7,7 +7,7 @@ The ESP SDIO Slave protocol was created to implement the communication between S
.. _esp_sdio_slave_caps:
SDIO Slave Capabilities of Espressif chips
SDIO Slave Capabilities of Espressif Chips
------------------------------------------
The services provided by the SDIO Slave peripheral of the {IDF_TARGET_NAME} chip are listed in the table below:
@ -42,45 +42,57 @@ ESP SDIO Slave Initialization
The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard SDIO initialization process (Section 3.1.2 of `SDIO Simplified Specification <https://www.sdcard.org/downloads/pls/>`_). In this specification as well as below, the SDIO slave is called an (SD)IO card. Here is a brief example of an ESP SDIO Slave initialization process:
1. SDIO reset
CMD52 (Write 0x6=0x8)
2. SD reset
CMD0
3. Check whether IO card (optional)
CMD8
4. Send SDIO op cond and wait for card ready
CMD5 arg = 0x00000000
CMD5 arg = 0x00ff8000 (according to the response above, poll until ready)
**Example:**
Arg of R4 after first CMD5 (arg=0x00000000) is 0xXXFFFF00.
Keep sending CMD5 with arg=0x00FFFF00 until the R4 shows card ready (arg bit 31=1).
5. Set address
CMD3
6. Select card
CMD7 (arg address according to CMD3 response)
**Example:**
Arg of R6 after CMD3 is 0x0001xxxx.
Arg of CMD7 should be 0x00010000.
7. Select 4-bit mode (optional)
CMD52 (Write 0x07=0x02)
8. Enable func1
CMD52 (Write 0x02=0x02)
9. Enable SDIO interrupt (required if interrupt line (DAT1) is used)
CMD52 (Write 0x04=0x03)
10. Set Func0 blocksize (optional, default value is 512 (0x200))
CMD52/53 (Read 0x10~0x11)
CMD52/53 (Write 0x10=0x00)
@ -90,6 +102,7 @@ The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the sta
CMD52/53 (Read 0x10~0x11, read to check the final value)
11. Set Func1 blocksize (optional, default value is 512 (0x200))
CMD52/53 (Read 0x110~0x111)
CMD52/53 (Write 0x110=0x00)
@ -107,7 +120,7 @@ ESP SDIO Slave Protocol
The ESP SDIO Slave protocol is based on the SDIO Specification's I/O Read/Write commands, i.e., CMD52 and CMD53. The protocol offers the following services:
- Sending FIFO and receiving FIFO
- 52 8-bit R/W registers shared by host and slave (For details, see *{IDF_TARGET_NAME} Technical Reference Manual* > *SDIO Slave Controller* > *Register Summary* > SDIO SLC Host registers [`PDF <{IDF_TARGET_TRM_EN_URL}#sdioslave-reg-summ>`__]
- 52 8-bit R/W registers shared by host and slave (For details, see **{IDF_TARGET_NAME} Technical Reference Manual** > **SDIO Slave Controller** > **Register Summary** > SDIO SLC Host registers [`PDF <{IDF_TARGET_TRM_EN_URL}#sdioslave-reg-summ>`__]
- 16 general purpose interrupt sources, 8 from host to slave and 8 from slave to host
To begin communication, the host needs to enable the I/O Function 1 in the slave and access its registers as described below.
@ -118,7 +131,7 @@ The :doc:`ESP Serial Slave Link </api-reference/protocols/esp_serial_slave_link>
.. _esp_sdio_slave_shared_registers:
Slave register table
Slave Register Table
^^^^^^^^^^^^^^^^^^^^
32-bit
@ -142,9 +155,10 @@ Shared general purpose registers:
- 0x09C-0x0BB: R/W registers 32-63 shared by slave and host.
Interrupt Registers:
- 0x08D (SLAVE_INT): bits for host to interrupt slave. auto clear.
FIFO (sending and receiving)
FIFO (Sending and Receiving)
""""""""""""""""""""""""""""
0x090 - 0x1F7FF are reserved for FIFOs.
@ -153,7 +167,7 @@ The address of CMD53 is related to the length requested to read from or write to
*requested length = 0x1F800-address*
The slave will respond with data that has a length equal to the length field of CMD53. In cases where the data is longer than the *requested length*, the data will be zero filled (when sending) or discarded (when receiving). This includes both the block and the byte mode of CMD53.
The slave responds with data that has a length equal to the length field of CMD53. In cases where the data is longer than the **requested length**, the data will be zero filled (when sending) or discarded (when receiving). This includes both the block and the byte mode of CMD53.
.. note::
@ -169,11 +183,11 @@ The slave will respond with data that has a length equal to the length field of
Interrupts
^^^^^^^^^^
SDIO interrupts are "level sensitive". For host interrupts, the slave sends an interrupt by pulling the DAT1 line down at a proper time. The host detects when the interrupt line is pulled down and reads the INT_ST register to determine the source of the interrupt. After that, the host can clear the interrupt bits by writing the INT_CLR register and process the interrupt. The host can also mask unneeded sources by clearing the bits in the INT_ENA register corresponding to the sources. If all the sources are cleared (or masked), the DAT1 line goes inactive.
SDIO interrupts are "level sensitive". For host interrupts, the slave sends an interrupt by pulling the DAT1 line down at a proper time. The host detects when the interrupt line is pulled down and reads the INT_ST register to determine the source of the interrupt. After that, the host can clear the interrupt bits by writing the ``INT_CLR`` register and process the interrupt. The host can also mask unneeded sources by clearing the bits in the INT_ENA register corresponding to the sources. If all the sources are cleared (or masked), the DAT1 line goes inactive.
On {IDF_TARGET_NAME}, the corresponding host_int bits are: bit 0 to bit 7.
On {IDF_TARGET_NAME}, the corresponding ``host_int`` bits are: bit 0 to bit 7.
For slave interrupts, the host sends a transfer to write the SLAVE_INT register. Once a bit is set to 1, the slave hardware and the driver will detect it and inform the application.
For slave interrupts, the host sends a transfer to write the ``SLAVE_INT`` register. Once a bit is set to 1, the slave hardware and the driver will detect it and inform the application.
.. _esp_sdio_slave_rcv_fifo:
@ -183,8 +197,8 @@ Receiving FIFO
To write to the slave's receiving FIFO, the host should complete the following steps:
1. **Read the TOKEN1 field (bits 27-16) of the register TOKEN_RDATA (0x044)**. The buffer number remaining is TOKEN1 minus the number of buffers used by host.
2. **Make sure the buffer number is sufficient** (*buffer_size* x *buffer_num* is greater than the data to write, *buffer_size* is pre-defined between the host and the slave before the communication starts). Otherwise, keep returning to Step 1 until the buffer size is sufficient.
3. **Write to the FIFO address with CMD53**. Note that the *requested length* should not exceed the length calculated at Step 2, and the FIFO address is related to *requested length*.
2. **Make sure the buffer number is sufficient** (**buffer_size** x **buffer_num** is greater than the data to write, **buffer_size** is pre-defined between the host and the slave before the communication starts). Otherwise, keep returning to Step 1 until the buffer size is sufficient.
3. **Write to the FIFO address with CMD53**. Note that the **requested length** should not exceed the length calculated at Step 2, and the FIFO address is related to **requested length**.
4. **Calculate used buffers**. Note that a partially used buffer at the tail is counted as used.
.. _esp_sdio_slave_send_fifo:
@ -196,6 +210,6 @@ To read the slave's sending FIFO, the host should complete the following steps:
1. **Wait for the interrupt line to become active** (optional, low by default).
2. **Read (poll) the interrupt bits in the INT_ST register** to monitor if new packets exist.
3. **If new packets are ready, read the PKT_LEN register**. Before reading the packets, determine the length of data to be read. As the host keeps the length of data already read from the slave, subtract this value from PKT_LEN, the result will be the maximum length of data available for reading. If no data has been added to the sending FIFO yet, wait and poll until the slave is ready and update PKT_LEN.
4. **Read from the FIFO using CMD53**. Note that the *requested length* should not be greater than calculated at Step 3, and the FIFO address is related to *requested length*.
3. **If new packets are ready, read the PKT_LEN register**. Before reading the packets, determine the length of data to be read. As the host keeps the length of data already read from the slave, subtract this value from ``PKT_LEN``, the result will be the maximum length of data available for reading. If no data has been added to the sending FIFO yet, wait and poll until the slave is ready and update ``PKT_LEN``.
4. **Read from the FIFO using CMD53**. Note that the **requested length** should not be greater than calculated at Step 3, and the FIFO address is related to **requested length**.
5. **Update the read length**.

94
docs/en/api-reference/protocols/esp_serial_slave_link.rst
View File

@ -4,15 +4,12 @@ ESP Serial Slave Link
Overview
--------
Espressif provides several chips that can work as slaves. These slave devices rely on some
common buses, and have their own communication protocols over those buses. The `esp_serial_slave_link` component is
designed for the master to communicate with ESP slave devices through those protocols over the
bus drivers.
Espressif provides several chips that can work as slaves. These slave devices rely on some common buses, and have their own communication protocols over those buses. The ``esp_serial_slave_link`` component is designed for the master to communicate with ESP slave devices through those protocols over the bus drivers.
After an `esp_serial_slave_link` device is initialized properly, the application can use it to communicate with the ESP
After an ``esp_serial_slave_link`` device is initialized properly, the application can use it to communicate with the ESP
slave devices conveniently.
Espressif Device protocols
Espressif Device Protocols
--------------------------
For more details about Espressif device protocols, see the following documents.
@ -28,34 +25,25 @@ Terminology
- ESSL: Abbreviation for ESP Serial Slave Link, the component described by this document.
- Master: The device running the `esp_serial_slave_link` component.
- Master: The device running the ``esp_serial_slave_link`` component.
- ESSL device: a virtual device on the master associated with an ESP slave device. The device
context has the knowledge of the slave protocol above the bus, relying on some bus drivers to
communicate with the slave.
- ESSL device: a virtual device on the master associated with an ESP slave device. The device context has the knowledge of the slave protocol above the bus, relying on some bus drivers to communicate with the slave.
- ESSL device handle: a handle to ESSL device context containing the configuration, status and
data required by the ESSL component. The context stores the driver configurations,
communication state, data shared by master and slave, etc.
- ESSL device handle: a handle to ESSL device context containing the configuration, status and data required by the ESSL component. The context stores the driver configurations, communication state, data shared by master and slave, etc.
The context should be initialized before it is used, and get deinitialized if not used any more. The
master application operates on the ESSL device through this handle.
- The context should be initialized before it is used, and get deinitialized if not used any more. The master application operates on the ESSL device through this handle.
- ESP slave: the slave device connected to the bus, which ESSL component is designed to
communicate with.
- ESP slave: the slave device connected to the bus, which ESSL component is designed to communicate with.
- Bus: The bus over which the master and the slave communicate with each other.
- Slave protocol: The special communication protocol specified by Espressif HW/SW over the bus.
- TX buffer num: a counter, which is on the slave and can be read by the master, indicates the
accumulated buffer numbers that the slave has loaded to the hardware to receive data from the
master.
- TX buffer num: a counter, which is on the slave and can be read by the master, indicates the accumulated buffer numbers that the slave has loaded to the hardware to receive data from the master.
- RX data size: a counter, which is on the slave and can be read by the master, indicates the
accumulated data size that the slave has loaded to the hardware to send to the master.
- RX data size: a counter, which is on the slave and can be read by the master, indicates the accumulated data size that the slave has loaded to the hardware to send to the master.
Services provided by ESP slave
Services Provided by ESP Slave
------------------------------
There are some common services provided by the Espressif slaves:
@ -64,21 +52,15 @@ There are some common services provided by the Espressif slaves:
2. Frhost Interrupts: The master can inform the slave about certain events.
3. Tx FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can
also indicate it has new data to send to master by the interrupt line.
3. TX FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can also indicate it has new data to send to master by the interrupt line.
The slave updates the TX buffer num to inform the master how much data it can receive, and the
master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.
The slave updates the TX buffer num to inform the master how much data it can receive, and the master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.
4. Rx FIFO (slave to master): the slave can receive data from the master in units of receiving
buffers.
4. RX FIFO (slave to master): the slave can receive data from the master in units of receiving buffers.
The slave updates the RX data size to inform the master how much data it has prepared to
send, and then the master read the data size, and take off the data length it has already received to know how many
data is remaining.
The slave updates the RX data size to inform the master how much data it has prepared to send, and then the master read the data size, and take off the data length it has already received to know how many data is remaining.
5. Shared registers: the master can read some part of the registers on the slave, and also write
these registers to let the slave read.
5. Shared registers: the master can read some part of the registers on the slave, and also write these registers to let the slave read.
.. only:: SOC_SDIO_SLAVE_SUPPORTED
@ -97,18 +79,13 @@ Initialization of ESP Serial Slave Link
ESP SDIO Slave
^^^^^^^^^^^^^^
The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. It includes the usage
of communicating with ESP SDIO Slave device via SDSPI feature. The ESSL device should be
initialized as below:
The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. It includes the usage of communicating with ESP SDIO Slave device via SDSPI feature. The ESSL device should be initialized as below:
1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`)
structure.
1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`) structure.
2. Call :cpp:func:`sdmmc_card_init` to initialize the card.
3. Initialize the ESSL device with :cpp:type:`essl_sdio_config_t`. The `card` member should be
the :cpp:type:`sdmmc_card_t` got in step 2, and the `recv_buffer_size` member should be filled
correctly according to pre-negotiated value.
3. Initialize the ESSL device with :cpp:type:`essl_sdio_config_t`. The ``card`` member should be the :cpp:type:`sdmmc_card_t` got in step 2, and the ``recv_buffer_size`` member should be filled correctly according to pre-negotiated value.
4. Call :cpp:func:`essl_init` to do initialization of the SDIO part.
@ -118,28 +95,26 @@ ESP SPI Slave
^^^^^^^^^^^^^
.. note::
If you are communicating with the ESP SDIO Slave device through SPI interface, you should use
the :ref:`SDIO interface <essl_sdio_slave_init>` instead.
Hasn't been supported yet.
If you are communicating with the ESP SDIO Slave device through SPI interface, you should use the :ref:`SDIO interface <essl_sdio_slave_init>` instead.
Has not been supported yet.
APIs
----
After the initialization process above is performed, you can call the APIs below to make use of
the services provided by the slave:
After the initialization process above is performed, you can call the APIs below to make use of the services provided by the slave:
Tohost Interrupts (optional)
Tohost Interrupts (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Call :cpp:func:`essl_get_intr_ena` to know which events will trigger the interrupts to the master.
1. Call :cpp:func:`essl_get_intr_ena` to know which events trigger the interrupts to the master.
2. Call :cpp:func:`essl_set_intr_ena` to set the events that will trigger interrupts to the master.
2. Call :cpp:func:`essl_set_intr_ena` to set the events that trigger interrupts to the master.
3. Call :cpp:func:`essl_wait_int` to wait until interrupt from the slave, or timeout.
4. When interrupt is triggered, call :cpp:func:`essl_get_intr` to know which events are active,
and call :cpp:func:`essl_clear_intr` to clear them.
4. When interrupt is triggered, call :cpp:func:`essl_get_intr` to know which events are active, and call :cpp:func:`essl_clear_intr` to clear them.
Frhost Interrupts
^^^^^^^^^^^^^^^^^
@ -149,28 +124,21 @@ Frhost Interrupts
TX FIFO
^^^^^^^
1. Call :cpp:func:`essl_get_tx_buffer_num` to know how many buffers the slave has prepared to
receive data from the master. This is optional. The master will poll `tx_buffer_num` when it try
to send packets to the slave, until the slave has enough buffer or timeout.
1. Call :cpp:func:`essl_get_tx_buffer_num` to know how many buffers the slave has prepared to receive data from the master. This is optional. The master will poll ``tx_buffer_num`` when it try to send packets to the slave, until the slave has enough buffer or timeout.
2. Call :cpp:func:`essl_send_packet` to send data to the slave.
RX FIFO
^^^^^^^
1. Call :cpp:func:`essl_get_rx_data_size` to know how many data the slave has prepared to send to
the master. This is optional. When the master tries to receive data from the slave, it will update
the `rx_data_size` for once, if the current `rx_data_size` is shorter than the buffer size the
master prepared to receive. And it may poll the `rx_data_size` if the `rx_dat_size` keeps 0,
until timeout.
1. Call :cpp:func:`essl_get_rx_data_size` to know how many data the slave has prepared to send to the master. This is optional. When the master tries to receive data from the slave, it will update the ``rx_data_size`` for once, if the current ``rx_data_size`` is shorter than the buffer size the master prepared to receive. And it may poll the ``rx_data_size`` if the ``rx_dat_size`` keeps 0, until timeout.
2. Call :cpp:func:`essl_get_packet` to receive data from the slave.
Reset counters (Optional)
Reset Counters (Optional)
^^^^^^^^^^^^^^^^^^^^^^^^^
Call :cpp:func:`essl_reset_cnt` to reset the internal counter if you find the slave has reset its
counter.
Call :cpp:func:`essl_reset_cnt` to reset the internal counter if you find the slave has reset its counter.
Application Example

13
docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
View File

@ -4,11 +4,12 @@ ESP SPI Slave HD (Half Duplex) Mode Protocol
.. only:: esp32
.. warning::
The driver for ESP32 hasn't been developed yet.
The driver for ESP32 has not been developed yet.
.. _esp_spi_slave_caps:
SPI Slave Capabilities of Espressif chips
SPI Slave Capabilities of Espressif Chips
-----------------------------------------
+------------------+-------+----------+----------+----------+----------+----------+----------+
@ -48,7 +49,7 @@ In the half duplex mode, the master has to use the protocol defined by the slave
This may be a data OUT phase, in which the direction is slave to master, or a data IN phase, in which the direction is master to slave.
The *direction* means which side (master or slave) controls the MOSI, MISO, WP, and HD pins.
The **direction** means which side (master or slave) controls the MOSI, MISO, WP, and HD pins.
Data IO Modes
-------------
@ -76,7 +77,7 @@ Normally, which mode is used is determined by the command sent by the master (Se
QPI Mode
^^^^^^^^
The QPI mode is a special state of the SPI Slave. The master can send the ENQPI command to put the slave into the QPI mode state. In the QPI mode, the command is also sent in 4-bit, thus it's not compatible with the normal modes. The master should only send QPI commands when the slave is in QPI mode. To exit from the QPI mode, master can send the EXQPI command.
The QPI mode is a special state of the SPI Slave. The master can send the ENQPI command to put the slave into the QPI mode state. In the QPI mode, the command is also sent in 4-bit, thus it is not compatible with the normal modes. The master should only send QPI commands when the slave is in QPI mode. To exit from the QPI mode, master can send the EXQPI command.
.. _spi_slave_hd_supported_cmds:
@ -133,11 +134,11 @@ Moreover, WRBUF, RDBUF, WRDMA, RDDMA commands have their 2-bit and 4-bit version
Segment Transaction Mode
------------------------
Segment transaction mode is the only mode supported by the SPI Slave HD driver for now. In this mode, for a transaction the slave load onto the DMA, the master is allowed to read or write in segments. This way the master doesn't have to prepare a large buffer as the size of data provided by the slave. After the master finishes reading/writing a buffer, it has to send the corresponding termination command to the slave as a synchronization signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command.
Segment transaction mode is the only mode supported by the SPI Slave HD driver for now. In this mode, for a transaction the slave load onto the DMA, the master is allowed to read or write in segments. This way the master does not have to prepare a large buffer as the size of data provided by the slave. After the master finishes reading/writing a buffer, it has to send the corresponding termination command to the slave as a synchronization signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command.
The termination command is WR_DONE (0x07) for the WRDMA and CMD8 (0x08) for the RDDMA.
Here's an example for the flow the master read data from the slave DMA:
Here is an example for the flow the master read data from the slave DMA:
1. The slave loads 4092 bytes of data onto the RDDMA
2. The master do seven RDDMA transactions, each of them is 512 bytes long, and reads the first 3584 bytes from the slave

44
docs/en/api-reference/protocols/esp_tls.rst
View File

@ -25,9 +25,7 @@ Simple HTTPS example that uses ESP-TLS to establish a secure socket connection:
Tree Structure for ESP-TLS Component
-------------------------------------
.. highlight:: none
::
.. code-block:: none
├── esp_tls.c
├── esp_tls.h
@ -46,12 +44,12 @@ TLS Server Verification
ESP-TLS provides multiple options for TLS server verification on the client side. The ESP-TLS client can verify the server by validating the peer's server certificate or with the help of pre-shared keys. The user should select only one of the following options in the :cpp:type:`esp_tls_cfg_t` structure for TLS server verification. If no option is selected, the client will return a fatal error by default during the TLS connection setup.
* **cacert_buf** and **cacert_bytes**: The CA certificate can be provided in a buffer to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS will use the CA certificate present in the buffer to verify the server. The following variables in the :cpp:type:`esp_tls_cfg_t` structure must be set.
* **cacert_buf** and **cacert_bytes**: The CA certificate can be provided in a buffer to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS uses the CA certificate present in the buffer to verify the server. The following variables in the :cpp:type:`esp_tls_cfg_t` structure must be set.
* ``cacert_buf`` - pointer to the buffer which contains the CA certification.
* ``cacert_bytes`` - the size of the CA certificate in bytes.
* **use_global_ca_store**: The ``global_ca_store`` can be initialized and set at once. Then it can be used to verify the server for all the ESP-TLS connections which have set ``use_global_ca_store = true`` in their respective :cpp:type:`esp_tls_cfg_t` structure. See the API Reference section below for information regarding different APIs used for initializing and setting up the ``global_ca_store``.
* **crt_bundle_attach**: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. More details can be found at :doc:`ESP x509 Certificate Bundle</api-reference/protocols/esp_crt_bundle>`.
* **crt_bundle_attach**: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. More details can be found at :doc:`ESP x509 Certificate Bundle </api-reference/protocols/esp_crt_bundle>`.
* **psk_hint_key**: To use pre-shared keys for server verification, :ref:`CONFIG_ESP_TLS_PSK_VERIFICATION` should be enabled in the ESP-TLS menuconfig. Then the pointer to the PSK hint and key should be provided to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS will use the PSK for server verification only when no other option regarding server verification is selected.
* **skip server verification**: This is an insecure option provided in the ESP-TLS for testing purposes. The option can be set by enabling :ref:`CONFIG_ESP_TLS_INSECURE` and :ref:`CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY` in the ESP-TLS menuconfig. When this option is enabled the ESP-TLS will skip server verification by default when no other options for server verification are selected in the :cpp:type:`esp_tls_cfg_t` structure.
@ -85,12 +83,14 @@ Underlying SSL/TLS Library Options
The ESP-TLS component offers the option to use MbedTLS or WolfSSL as its underlying SSL/TLS library. By default, only MbedTLS is available and used, WolfSSL SSL/TLS library is also available publicly at https://github.com/espressif/esp-wolfssl. The repository provides the WolfSSL component in binary format, and it also provides a few examples that are useful for understanding the API. Please refer to the repository ``README.md`` for information on licensing and other options. Please see the below section for instructions on how to use WolfSSL in your project.
.. note:: `As the library options are internal to ESP-TLS, switching the libraries will not change ESP-TLS specific code for a project.`
.. note::
As the library options are internal to ESP-TLS, switching the libraries will not change ESP-TLS specific code for a project.
How to Use WolfSSL with ESP-IDF
-------------------------------
There are two ways to use WolfSSL in your project：
There are two ways to use WolfSSL in your project:
1) Directly add WolfSSL as a component in your project with the following three commands::
@ -125,16 +125,18 @@ The following table shows a typical comparison between WolfSSL and MbedTLS when
- WolfSSL
- MbedTLS
* - Total Heap Consumed
- ~19 KB
- ~37 KB
- ~ 19 KB
- ~ 37 KB
* - Task Stack Used
- ~2.2 KB
- ~3.6 KB
- ~ 2.2 KB
- ~ 3.6 KB
* - Bin size
- ~858 KB
- ~736 KB
- ~ 858 KB
- ~ 736 KB
.. note:: `These values can vary based on configuration options and version of respective libraries`.
.. note::
These values can vary based on configuration options and version of respective libraries.
.. only:: esp32
@ -143,9 +145,11 @@ The following table shows a typical comparison between WolfSSL and MbedTLS when
ESP-TLS provides support for using ATECC608A cryptoauth chip with ESP32-WROOM-32SE. The use of ATECC608A is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. ESP-TLS uses MbedTLS as its underlying TLS/SSL stack by default unless changed manually.
.. note:: ATECC608A chip on ESP32-WROOM-32SE must be already configured, for details refer `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_.
.. note::
To enable the secure element support, and use it in your project for TLS connection, you will have to follow the below steps:
ATECC608A chip on ESP32-WROOM-32SE must be already configured, for details refer `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_.
To enable the secure element support, and use it in your project for TLS connection, you have to follow the below steps:
1) Add `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ in your project, for details please refer `how to use esp-cryptoauthlib with ESP-IDF <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_.
@ -175,7 +179,7 @@ The following table shows a typical comparison between WolfSSL and MbedTLS when
Digital Signature with ESP-TLS
------------------------------
ESP-TLS provides support for using the Digital Signature (DS) with {IDF_TARGET_NAME}. Use of the DS for TLS is supported only when ESP-TLS is used with MbedTLS (default stack) as its underlying SSL/TLS stack. For more details on Digital Signature, please refer to the :doc:`Digital Signature (DS) </api-reference/peripherals/ds>`. The technical details of Digital Signature such as how to calculate private key parameters can be found in *{IDF_TARGET_NAME} Technical Reference Manual* > *Digital Signature (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. The DS peripheral must be configured before it can be used to perform Digital Signature, see :ref:`configure-the-ds-peripheral`.
ESP-TLS provides support for using the Digital Signature (DS) with {IDF_TARGET_NAME}. Use of the DS for TLS is supported only when ESP-TLS is used with MbedTLS (default stack) as its underlying SSL/TLS stack. For more details on Digital Signature, please refer to the :doc:`Digital Signature (DS) </api-reference/peripherals/ds>`. The technical details of Digital Signature such as how to calculate private key parameters can be found in **{IDF_TARGET_NAME} Technical Reference Manual** > **Digital Signature (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]. The DS peripheral must be configured before it can be used to perform Digital Signature, see :ref:`configure-the-ds-peripheral`.
The DS peripheral must be initialized with the required encrypted private key parameters, which are obtained when the DS peripheral is configured. ESP-TLS internally initializes the DS peripheral when provided with the required DS context, i.e., DS parameters. Please see the below code snippet for passing the DS context to the ESP-TLS context. The DS context passed to the ESP-TLS context should not be freed till the TLS connection is deleted.
@ -191,12 +195,15 @@ The following table shows a typical comparison between WolfSSL and MbedTLS when
.ds_data = (void *)ds_ctx,
};
.. note:: When using Digital Signature for the TLS connection, along with the other required params, only the client certification (`clientcert_buf`) and the DS params (`ds_data`) are required and the client key (`clientkey_buf`) can be set to NULL.
.. note::
When using Digital Signature for the TLS connection, along with the other required params, only the client certification (`clientcert_buf`) and the DS params (`ds_data`) are required and the client key (`clientkey_buf`) can be set to NULL.
* An example of mutual authentication with the DS peripheral can be found at :example:`ssl mutual auth<protocols/mqtt/ssl_mutual_auth>` which internally uses (ESP-TLS) for the TLS connection.
TLS Ciphersuites
------------------------------------
ESP-TLS provides the ability to set a ciphersuites list in client mode. The TLS ciphersuites list informs the server about the supported ciphersuites for the specific TLS connection regardless of the TLS stack configuration. If the server supports any ciphersuite from this list, then the TLS connection will succeed; otherwise, it will fail.
You can set ``ciphersuites_list`` in the :cpp:type:`esp_tls_cfg_t` structure during client connection as follows:
@ -212,6 +219,7 @@ You can set ``ciphersuites_list`` in the :cpp:type:`esp_tls_cfg_t` structure dur
ESP-TLS will not check the validity of ``ciphersuites_list`` that was set, you should call :cpp:func:`esp_tls_get_ciphersuites_list` to get ciphersuites list supported in the TLS stack and cross-check it against the supplied list.
.. note::
This feature is supported only in the MbedTLS stack.
API Reference

22
docs/en/api-reference/protocols/icmp_echo.rst
View File

@ -6,22 +6,20 @@ Overview
ICMP (Internet Control Message Protocol) is used for diagnostic or control purposes or generated in response to errors in IP operations. The common network util ``ping`` is implemented based on the ICMP packets with the type field value of 0, also called ``Echo Reply``.
During a ping session, the source host firstly sends out an ICMP echo request packet and wait for an ICMP echo reply with specific times. In this way, it also measures the round-trip time for the messages. After receiving a valid ICMP echo reply, the source host will generate statistics about the IP link layer (e.g. packet loss, elapsed time, etc).
During a ping session, the source host firstly sends out an ICMP echo request packet and wait for an ICMP echo reply with specific times. In this way, it also measures the round-trip time for the messages. After receiving a valid ICMP echo reply, the source host will generate statistics about the IP link layer (e.g., packet loss, elapsed time, etc).
It is common that IoT device needs to check whether a remote server is alive or not. The device should show the warnings to users when it got offline. It can be achieved by creating a ping session and sending/parsing ICMP echo packets periodically.
To make this internal procedure much easier for users, ESP-IDF provides some out-of-box APIs.
Create a new ping session
Create a New Ping Session
^^^^^^^^^^^^^^^^^^^^^^^^^
To create a ping session, you need to fill in the ``esp_ping_config_t`` configuration structure firstly, specifying target IP address, interval times, and etc. Optionally, you can also register some callback functions with the `esp_ping_callbacks_t`` structure.
To create a ping session, you need to fill in the ``esp_ping_config_t`` configuration structure firstly, specifying target IP address, interval times, and etc. Optionally, you can also register some callback functions with the ``esp_ping_callbacks_t`` structure.
Example method to create a new ping session and register callbacks:
.. highlight:: c
::
.. code-block:: c
static void test_on_ping_success(esp_ping_handle_t hdl, void *args)
{
@ -84,26 +82,26 @@ Example method to create a new ping session and register callbacks:
cbs.on_ping_success = test_on_ping_success;
cbs.on_ping_timeout = test_on_ping_timeout;
cbs.on_ping_end = test_on_ping_end;
cbs.cb_args = "foo"; // arguments that will feed to all callback functions, can be NULL
cbs.cb_args = "foo"; // arguments that feeds to all callback functions, can be NULL
cbs.cb_args = eth_event_group;
esp_ping_handle_t ping;
esp_ping_new_session(&ping_config, &cbs, &ping);
}
Start and Stop ping session
Start and Stop Ping Session
^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can start and stop ping session with the handle returned by ``esp_ping_new_session``. Note that, the ping session won't start automatically after creation. If the ping session is stopped, and restart again, the sequence number in ICMP packets will recount from zero again.
You can start and stop ping session with the handle returned by ``esp_ping_new_session``. Note that, the ping session does not start automatically after creation. If the ping session is stopped, and restart again, the sequence number in ICMP packets will recount from zero again.
Delete a ping session
Delete a Ping Session
^^^^^^^^^^^^^^^^^^^^^
If a ping session won't be used any more, you can delete it with ``esp_ping_delete_session``. Please make sure the ping session is in stop state (i.e. you have called ``esp_ping_stop`` before or the ping session has finished all the procedures) when you call this function.
If a ping session will not be used any more, you can delete it with ``esp_ping_delete_session``. Please make sure the ping session is in stop state (i.e., you have called ``esp_ping_stop`` before or the ping session has finished all the procedures) when you call this function.
Get runtime statistics
Get Runtime Statistics
^^^^^^^^^^^^^^^^^^^^^^
As the example code above, you can call ``esp_ping_get_profile`` to get different runtime statistics of ping session in the callback function.

1
docs/en/api-reference/protocols/index.rst
View File

@ -1,5 +1,6 @@
Application Protocols
*********************
:link_to_translation:`zh_CN:[中文]`
.. toctree::

20
docs/en/api-reference/protocols/mbedtls.rst
View File

@ -3,7 +3,9 @@ Mbed TLS
`Mbed TLS <https://github.com/Mbed-TLS/mbedtls>`_ is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
.. note:: ESP-IDF uses a `fork <https://github.com/espressif/mbedtls>`_ of Mbed TLS which includes a few patches (related to hardware routines of certain modules like ``bignum (MPI)`` and ``ECC``) over vanilla Mbed TLS.
.. note::
ESP-IDF uses a `fork <https://github.com/espressif/mbedtls>`_ of Mbed TLS which includes a few patches (related to hardware routines of certain modules like ``bignum (MPI)`` and ``ECC``) over vanilla Mbed TLS.
Mbed TLS supports SSL 3.0 up to TLS 1.3 and DTLS 1.0 to 1.2 communication by providing the following:
@ -14,7 +16,9 @@ Mbed TLS supports SSL 3.0 up to TLS 1.3 and DTLS 1.0 to 1.2 communication by pro
- Hashing
- Encryption/decryption
.. note:: Mbed TLS is in the process of migrating all the documentation to a single place. In the meantime, users can find the documentation at the `old Mbed TLS site <https://tls.mbed.org/api>`_ .
.. note::
Mbed TLS is in the process of migrating all the documentation to a single place. In the meantime, users can find the documentation at the `old Mbed TLS site <https://tls.mbed.org/api>`_ .
Mbed TLS Support in ESP-IDF
@ -23,7 +27,9 @@ Mbed TLS Support in ESP-IDF
Please find the information about the Mbed TLS versions present in different branches of ESP-IDF `here <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__.
.. note:: Please refer the :ref:`ESP-IDF Migration Guide <migration_guide_mbedtls>` to migrate from Mbed TLS version 2.x to version 3.0 or greater.
.. note::
Please refer the :ref:`ESP-IDF Migration Guide <migration_guide_mbedtls>` to migrate from Mbed TLS version 2.x to version 3.0 or greater.
Application Examples
--------------------
@ -60,7 +66,9 @@ Following is a brief list of important config options accessible at ``Component
:SOC_MPI_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`: Support for hardware MPI (bignum) acceleration
:SOC_ECC_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`: Support for hardware ECC acceleration
.. note:: Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1 and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__.
.. note::
Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1 and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__.
Performance and Memory Tweaks
@ -87,7 +95,9 @@ The following table shows typical memory usage with different configs when the :
| | :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT` | |
+------------------------------+--------------------------------------------------+----------------------+
.. note:: These values are subject to change with change in configuration options and versions of Mbed TLS.
.. note::
These values are subject to change with change in configuration options and versions of Mbed TLS.
Reducing Binary Size

5
docs/en/api-reference/protocols/mdns.rst
View File

@ -1,14 +1,15 @@
mDNS Service
============
:link_to_translation:`zh_CN:[中文]`
mDNS is a multicast UDP service that is used to provide local network service and host discovery.
The ESP-IDF component `mDNS` has been moved from ESP-IDF since version v5.0 to a separate repository:
The ESP-IDF component ``mDNS`` has been moved from ESP-IDF since version v5.0 to a separate repository:
* `mDNS component on GitHub <https://github.com/espressif/esp-protocols/tree/master/components/mdns>`__
To add mDNS component in your project, please run `idf.py add-dependency espressif/mdns`.
To add mDNS component in your project, please run ``idf.py add-dependency espressif/mdns``.
Hosted Documentation
--------------------

24
docs/en/api-reference/protocols/mqtt.rst
View File

@ -1,5 +1,6 @@
ESP-MQTT
========
:link_to_translation:`zh_CN:[中文]`
Overview
@ -10,6 +11,7 @@ ESP-MQTT is an implementation of `MQTT <https://mqtt.org/>`__ protocol client, w
Features
--------
* Support MQTT over TCP, SSL with Mbed TLS, MQTT over WebSocket, and MQTT over WebSocket Secure
* Easy to setup with URI
* Multiple instances (multiple clients in one application)
@ -33,7 +35,7 @@ MQTT Message Retransmission
A new MQTT message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
Messages with QoS 0 will be sent only once. QoS 1 and 2 have different behaviors since the protocol requires extra steps to complete the process.
Messages with QoS 0 is sent only once. QoS 1 and 2 have different behaviors since the protocol requires extra steps to complete the process.
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to avoid losses in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
@ -87,7 +89,7 @@ The :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` field
- Minimal configurations:
.. code:: c
.. code-block:: c
const esp_mqtt_client_config_t mqtt_cfg = {
.broker.address.uri = "mqtt://mqtt.eclipseprojects.io",
@ -96,7 +98,9 @@ The :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` field
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client);
esp_mqtt_client_start(client);
.. note:: By default MQTT client uses event loop library to post related MQTT events (connected, subscribed, published, etc.).
.. note::
By default MQTT client uses event loop library to post related MQTT events (connected, subscribed, published, etc.).
============
Verification
@ -137,7 +141,7 @@ All client related credentials are under the :cpp:class:`credentials <esp_mqtt_c
Authentication
==============
It's possible to set authentication parameters through the :cpp:class:`authentication <esp_mqtt_client_config_t::credentials_t::authentication_t>` field. The client supports the following authentication methods:
It is possible to set authentication parameters through the :cpp:class:`authentication <esp_mqtt_client_config_t::credentials_t::authentication_t>` field. The client supports the following authentication methods:
* :cpp:member:`password <esp_mqtt_client_config_t::credentials_t::authentication_t::password>`: use a password by setting
* :cpp:member:`certificate <esp_mqtt_client_config_t::credentials_t::authentication_t::certificate>` and :cpp:member:`key <esp_mqtt_client_config_t::credentials_t::authentication_t::key>`: mutual authentication with TLS, and both can be provided in PEM or DER format
@ -181,12 +185,12 @@ The following events may be posted by the MQTT client:
* ``MQTT_EVENT_BEFORE_CONNECT``: The client is initialized and about to start connecting to the broker.
* ``MQTT_EVENT_CONNECTED``: The client has successfully established a connection to the broker. The client is now ready to send and receive data.
* ``MQTT_EVENT_DISCONNECTED``: The client has aborted the connection due to being unable to read or write data, e.g. because the server is unavailable.
* ``MQTT_EVENT_SUBSCRIBED``: The broker has acknowledged the client's subscribe request. The event data will contain the message ID of the subscribe message.
* ``MQTT_EVENT_UNSUBSCRIBED``: The broker has acknowledged the client's unsubscribe request. The event data will contain the message ID of the unsubscribe message.
* ``MQTT_EVENT_PUBLISHED``: The broker has acknowledged the client's publish message. This will only be posted for QoS level 1 and 2, as level 0 does not use acknowledgements. The event data will contain the message ID of the publish message.
* ``MQTT_EVENT_DATA``: The client has received a publish message. The event data contains: message ID, name of the topic it was published to, received data and its length. For data that exceeds the internal buffer, multiple ``MQTT_EVENT_DATA`` will be posted and :cpp:member:`current_data_offset <esp_mqtt_event_t::current_data_offset>` and :cpp:member:`total_data_len<esp_mqtt_event_t::total_data_len>` from event data updated to keep track of the fragmented message.
* ``MQTT_EVENT_ERROR``: The client has encountered an error. The field :cpp:type:`error_handle <esp_mqtt_error_codes_t>` in the event data contains :cpp:type:`error_type <esp_mqtt_error_type_t>` that can be used to identify the error. The type of error will determine which parts of the :cpp:type:`error_handle <esp_mqtt_error_codes_t>` struct is filled.
* ``MQTT_EVENT_DISCONNECTED``: The client has aborted the connection due to being unable to read or write data, e.g., because the server is unavailable.
* ``MQTT_EVENT_SUBSCRIBED``: The broker has acknowledged the client's subscribe request. The event data contains the message ID of the subscribe message.
* ``MQTT_EVENT_UNSUBSCRIBED``: The broker has acknowledged the client's unsubscribe request. The event data contains the message ID of the unsubscribe message.
* ``MQTT_EVENT_PUBLISHED``: The broker has acknowledged the client's publish message. This is only posted for QoS level 1 and 2, as level 0 does not use acknowledgements. The event data contains the message ID of the publish message.
* ``MQTT_EVENT_DATA``: The client has received a publish message. The event data contains: message ID, name of the topic it was published to, received data and its length. For data that exceeds the internal buffer, multiple ``MQTT_EVENT_DATA`` events are posted and :cpp:member:`current_data_offset <esp_mqtt_event_t::current_data_offset>` and :cpp:member:`total_data_len<esp_mqtt_event_t::total_data_len>` from event data updated to keep track of the fragmented message.
* ``MQTT_EVENT_ERROR``: The client has encountered an error. The field :cpp:type:`error_handle <esp_mqtt_error_codes_t>` in the event data contains :cpp:type:`error_type <esp_mqtt_error_type_t>` that can be used to identify the error. The type of error determines which parts of the :cpp:type:`error_handle <esp_mqtt_error_codes_t>` struct is filled.
API Reference
-------------

1
docs/en/index.rst
View File

@ -1,5 +1,6 @@
ESP-IDF Programming Guide
=========================
:link_to_translation:`zh_CN:[中文]`
.. only:: fast_build

8
docs/en/migration-guides/release-5.x/5.0/build-system.rst
View File

@ -9,12 +9,12 @@ ESP-IDF v5.0 no longer supports GNU make-based projects. Please follow the :ref:
Update Fragment File Grammar
----------------------------
Please follow the :ref:`migrate linker script fragment files grammar<ldgen-migrate-lf-grammar>` chapter for migrating v3.x grammar to the new one.
Please follow the :ref:`migrate linker script fragment files grammar <ldgen-migrate-lf-grammar>` chapter for migrating v3.x grammar to the new one.
Specify Component Requirements Explicitly
-----------------------------------------
In previous versions of ESP-IDF, some components were always added as public requirements (dependencies) to every component in the build, in addition to the :ref:`common component requirements<component-common-requirements>`:
In previous versions of ESP-IDF, some components were always added as public requirements (dependencies) to every component in the build, in addition to the :ref:`common component requirements <component-common-requirements>`:
* ``driver``
* ``efuse``
@ -54,8 +54,8 @@ instead of::
Defining these variables as CMake lists is compatible with previous ESP-IDF versions.
Update Usage of target_link_libraries with project_elf
------------------------------------------------------
Update Usage of ``target_link_libraries`` with ``project_elf``
--------------------------------------------------------------
ESP-IDF v5.0 fixes CMake variable propagation issues for components. This issue caused compiler flags and definitions that were supposed to apply to one component to be applied to every component in the project.

1
docs/en/migration-guides/release-5.x/5.0/gcc.rst
View File

@ -20,6 +20,7 @@ Warnings
The upgrade to GCC 11.2.0 has resulted in the addition of new warnings, or enhancements to existing warnings. The full details of all GCC warnings can be found in `GCC Warning Options <https://gcc.gnu.org/onlinedocs/gcc-11.2.0/gcc/Warning-Options.html>`_. Users are advised to double-check their code, then fix the warnings if possible. Unfortunately, depending on the warning and the complexity of the user's code, some warnings will be false positives that require non-trivial fixes. In such cases, users can choose to suppress the warning in multiple ways. This section outlines some common warnings that users are likely to encounter, and ways to suppress them.
.. warning::
Users are advised to check that a warning is indeed a false positive before attempting to suppress them it.

24
docs/en/migration-guides/release-5.x/5.0/networking.rst
View File

@ -6,8 +6,8 @@ Networking
Wi-Fi
*****
Callback function type esp_now_recv_cb_t
----------------------------------------
Callback Function Type ``esp_now_recv_cb_t``
--------------------------------------------
Previously, the first parameter of ``esp_now_recv_cb_t`` was of type ``const uint8_t *mac_addr``, which only included the address of ESP-NOW peer device.
@ -26,8 +26,8 @@ Please refer to the ESP-NOW example: :example_file:`wifi/espnow/main/espnow_exam
Ethernet
********
esp_eth_ioctl() API
-------------------
``esp_eth_ioctl()`` API
-----------------------
Previously, the :cpp:func:`esp_eth_ioctl` API had the following issues:
@ -38,7 +38,7 @@ Previously, the :cpp:func:`esp_eth_ioctl` API had the following issues:
esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
Therefore, the usage of :cpp:func:`esp_eth_ioctl` is now unified. Arguments to the third parameter must be passed as pointers to a specific data type to/from where data will be stored/read by :cpp:func:`esp_eth_ioctl`. The code snippets below demonstrate the usage of :cpp:func:`esp_eth_ioctl`.
Therefore, the usage of :cpp:func:`esp_eth_ioctl` is now unified. Arguments to the third parameter must be passed as pointers to a specific data type to/from where data is stored/read by :cpp:func:`esp_eth_ioctl`. The code snippets below demonstrate the usage of :cpp:func:`esp_eth_ioctl`.
Usage example to set Ethernet configuration:
@ -81,7 +81,7 @@ SPI-Ethernet Module Initialization
The SPI-Ethernet Module initialization is now simplified. Previously, you had to manually allocate an SPI device using :cpp:func:`spi_bus_add_device` before instantiating the SPI-Ethernet MAC.
Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices are allocated internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros are updated to accept new input parameters. Refer to :doc:`Ethernet API Reference Guide<../../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization.
Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices are allocated internally. As a result, the :cpp:class:`eth_dm9051_config_t`, :cpp:class:`eth_w5500_config_t`, and :cpp:class:`eth_ksz8851snl_config_t` configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ``ETH_DM9051_DEFAULT_CONFIG``, ``ETH_W5500_DEFAULT_CONFIG``, and ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` configuration initialization macros are updated to accept new input parameters. Refer to :doc:`Ethernet API Reference Guide <../../../api-reference/network/esp_eth>` for an example of SPI-Ethernet Module initialization.
.. _tcpip-adapter:
@ -89,7 +89,7 @@ Now, you no longer need to call :cpp:func:`spi_bus_add_device` as SPI devices ar
TCP/IP Adapter
*****************
The TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This section outlines migration from tcpip_adapter API to its successor :doc:`/api-reference/network/esp_netif`.
The TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This section outlines migration from ``tcpip_adapter`` API to its successor :doc:`/api-reference/network/esp_netif`.
Updating Network Connection Code
@ -121,10 +121,10 @@ Please refer to the example initialization code for these three interfaces:
- WiFi Access Point: :example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
- Ethernet: :example_file:`ethernet/basic/main/ethernet_example_main.c`
Other tcpip_adapter API Replacement
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Other ``tcpip_adapter`` API Replacement
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All the tcpip_adapter functions have their esp-netif counter-part. Please refer to the esp_netif.h grouped into these sections:
All the ``tcpip_adapter`` functions have their ``esp-netif`` counter-part. Please refer to the ``esp_netif.h`` grouped into these sections:
* :component_file:`Setters/Getters <esp_netif/include/esp_netif.h#L241>`
* :component_file:`DHCP <esp_netif/include/esp_netif.h#L387>`
@ -134,7 +134,7 @@ All the tcpip_adapter functions have their esp-netif counter-part. Please refer
Default Event Handlers
^^^^^^^^^^^^^^^^^^^^^^
Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, as all events should be handled in the same way. Please note that for IP-related event handlers, application code usually receives IP addresses in the form of an esp-netif specific struct instead of the LwIP structs. However, both structs are binary compatible.
Event handlers are moved from ``tcpip_adapter`` to appropriate driver code. There is no change from application code perspective, as all events should be handled in the same way. Please note that for IP-related event handlers, application code usually receives IP addresses in the form of an ``esp-netif`` specific struct instead of the LwIP structs. However, both structs are binary compatible.
This is the preferred way to print the address:
@ -154,6 +154,6 @@ Since ``ip4addr_ntoa()`` is a LwIP API, the esp-netif provides ``esp_ip4addr_nto
IP Addresses
^^^^^^^^^^^^
You are advised to use esp-netif defined IP structures. Please note that with default compatibility enabled, the LwIP structs will still work.
You are advised to use ``esp-netif`` defined IP structures. Please note that with default compatibility enabled, the LwIP structs still work.
* :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`

92
docs/en/migration-guides/release-5.x/5.0/peripherals.rst
View File

@ -6,7 +6,7 @@ Peripherals
Peripheral Clock Gating
-----------------------
As usual, peripheral clock gating is still handled by driver itself, users don't need to take care of the peripheral module clock gating.
As usual, peripheral clock gating is still handled by driver itself, users do not need to take care of the peripheral module clock gating.
However, for advanced users who implement their own drivers based on ``hal`` and ``soc`` components, the previous clock gating include path has been changed from ``driver/periph_ctrl.h`` to ``esp_private/periph_ctrl.h``.
@ -18,7 +18,7 @@ RTC control APIs have been moved from ``driver/rtc_cntl.h`` to ``esp_private/rtc
ADC
---
ADC Oneshot & Continuous Mode drivers
ADC Oneshot & Continuous Mode Drivers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ADC oneshot mode driver has been redesigned.
@ -30,7 +30,7 @@ The ADC continuous mode driver has been moved from ``driver`` component to ``esp
- The include path has been changed from ``driver/adc.h`` to ``esp_adc/adc_continuous.h``.
Attempting to use the legacy include path ``driver/adc.h`` of either driver will trigger the build warning below by default. However, the warning can be suppressed by enabling the :ref:`CONFIG_ADC_SUPPRESS_DEPRECATE_WARN` Kconfig option.
Attempting to use the legacy include path ``driver/adc.h`` of either driver triggers the build warning below by default. However, the warning can be suppressed by enabling the :ref:`CONFIG_ADC_SUPPRESS_DEPRECATE_WARN` Kconfig option.
.. code-block:: text
@ -45,7 +45,7 @@ The ADC calibration driver has been redesigned.
Legacy driver is still available by including ``esp_adc_cal.h``. However, if users still would like to use the include path of the legacy driver, users should add ``esp_adc`` component to the list of component requirements in CMakeLists.txt.
Attempting to use the legacy include path ``esp_adc_cal.h`` will trigger the build warning below by default. However, the warning can be suppressed by enabling the :ref:`CONFIG_ADC_CALI_SUPPRESS_DEPRECATE_WARN` Kconfig option.
Attempting to use the legacy include path ``esp_adc_cal.h`` triggers the build warning below by default. However, the warning can be suppressed by enabling the :ref:`CONFIG_ADC_CALI_SUPPRESS_DEPRECATE_WARN` Kconfig option.
.. code-block:: text
@ -93,10 +93,10 @@ GPIO
The Sigma-Delta Modulator driver has been redesigned into :doc:`SDM <../../../api-reference/peripherals/sdm>`.
- The new driver implements a factory pattern, where the SDM channels are managed in a pool internally, thus users don't have to fix a SDM channel to a GPIO manually.
- The new driver implements a factory pattern, where the SDM channels are managed in a pool internally, thus users do not have to fix a SDM channel to a GPIO manually.
- All SDM channels can be allocated dynamically.
Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/sigmadelta.h``. However, by default, including ``driver/sigmadelta.h`` will trigger the build warning below. The warning can be suppressed by Kconfig option :ref:`CONFIG_SDM_SUPPRESS_DEPRECATE_WARN`.
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/sigmadelta.h``. However, by default, including ``driver/sigmadelta.h`` triggers the build warning below. The warning can be suppressed by Kconfig option :ref:`CONFIG_SDM_SUPPRESS_DEPRECATE_WARN`.
.. code-block:: text
@ -109,22 +109,22 @@ GPIO
- SDM channel representation has changed from ``sigmadelta_channel_t`` to :cpp:type:`sdm_channel_handle_t`, which is an opaque pointer.
- SDM channel configurations are stored in :cpp:type:`sdm_config_t` now, instead the previous ``sigmadelta_config_t``.
- In the legacy driver, users don't have to set the clock source for SDM channel. But in the new driver, users need to set a proper one in the :cpp:member:`sdm_config_t::clk_src`. The available clock sources are listed in the :cpp:type:`soc_periph_sdm_clk_src_t`.
- In the legacy driver, users do not have to set the clock source for SDM channel. But in the new driver, users need to set a proper one in the :cpp:member:`sdm_config_t::clk_src`. The available clock sources are listed in the :cpp:type:`soc_periph_sdm_clk_src_t`.
- In the legacy driver, users need to set a ``prescale`` for the channel, which reflects the frequency in which the modulator outputs a pulse. In the new driver, users should use :cpp:member:`sdm_config_t::sample_rate_hz` to set the over sample rate.
- In the legacy driver, users set ``duty`` to decide the output analog value, it's now renamed to a more appropriate name ``density``.
- In the legacy driver, users set ``duty`` to decide the output analog value, it is now renamed to a more appropriate name ``density``.
Breaking Changes in Usage
^^^^^^^^^^^^^^^^^^^^^^^^^
- Channel configuration was done by channel allocation, in :cpp:func:`sdm_new_channel`. In the new driver, only the ``density`` can be changed at runtime, by :cpp:func:`sdm_channel_set_pulse_density`. Other parameters like ``gpio number`` and ``prescale`` are only allowed to set during channel allocation.
- Before further channel operations, users should **enable** the channel in advance, by calling :cpp:func:`sdm_channel_enable`. This function will help to manage some system level services, like **Power Management**.
- Before further channel operations, users should **enable** the channel in advance, by calling :cpp:func:`sdm_channel_enable`. This function helps to manage some system level services, like **Power Management**.
Timer Group Driver
------------------
Timer Group driver has been redesigned into :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`, which aims to unify and simplify the usage of general purpose timer.
Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` will trigger the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/timer.h``. However, by default, including ``driver/timer.h`` triggers the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_GPTIMER_SUPPRESS_DEPRECATE_WARN`.
.. code-block:: text
@ -146,7 +146,7 @@ Breaking Changes in Usage
- Timer initialization is done by creating a timer instance from :cpp:func:`gptimer_new_timer`. Basic configurations like clock source, resolution and direction should be set in :cpp:type:`gptimer_config_t`. Note that, specific configurations of alarm events are not needed during the installation stage of the driver.
- Alarm event is configured by :cpp:func:`gptimer_set_alarm_action`, with parameters set in the :cpp:type:`gptimer_alarm_config_t`.
- Setting and getting count value are done by :cpp:func:`gptimer_get_raw_count` and :cpp:func:`gptimer_set_raw_count`. The driver doesn't help convert the raw value into UTC time-stamp. Instead, the conversion should be done from user's side as the timer resolution is also known to the user.
- Setting and getting count value are done by :cpp:func:`gptimer_get_raw_count` and :cpp:func:`gptimer_set_raw_count`. The driver does not help convert the raw value into UTC time-stamp. Instead, the conversion should be done from user's side as the timer resolution is also known to the user.
- The driver will install the interrupt service as well if :cpp:member:`gptimer_event_callbacks_t::on_alarm` is set to a valid callback function. In the callback, users do not have to deal with the low level registers (like "clear interrupt status", "re-enable alarm event" and so on). So functions like ``timer_group_get_intr_status_in_isr`` and ``timer_group_get_auto_reload_in_isr`` are not used anymore.
- To update the alarm configurations when alarm event happens, one can call :cpp:func:`gptimer_set_alarm_action` in the interrupt callback, then the alarm will be re-enabled again.
- Alarm will always be re-enabled by the driver if :cpp:member:`gptimer_alarm_config_t::auto_reload_on_alarm` is set to true.
@ -192,7 +192,7 @@ I2C
- I2C interrupt handling is implemented by driver itself.
* - ``i2c_opmode_t``
- None
- It's not used anywhere in esp-idf.
- It is not used anywhere in ESP-IDF.
SPI
---
@ -247,7 +247,7 @@ LEDC
Pulse counter driver has been redesigned (see :doc:`PCNT <../../../api-reference/peripherals/pcnt>`), which aims to unify and simplify the usage of PCNT peripheral.
Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/pcnt.h``. However, including ``driver/pcnt.h`` will trigger the build warning below by default. The warning can be suppressed by the Kconfig option :ref:`CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN`.
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/pcnt.h``. However, including ``driver/pcnt.h`` triggers the build warning below by default. The warning can be suppressed by the Kconfig option :ref:`CONFIG_PCNT_SUPPRESS_DEPRECATE_WARN`.
.. code-block:: text
@ -259,7 +259,7 @@ LEDC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- ``pcnt_port_t``, ``pcnt_unit_t`` and ``pcnt_channel_t`` which used to identify the hardware unit and channel are removed from user's code. In the new driver, PCNT unit is represented by :cpp:type:`pcnt_unit_handle_t`, likewise, PCNT channel is represented by :cpp:type:`pcnt_channel_handle_t`. Both of them are opaque pointers.
- ``pcnt_evt_type_t`` is not used any more, they have been replaced by a universal **Watch Point Event**. In the event callback :cpp:type:`pcnt_watch_cb_t`, it's still possible to distinguish different watch points from :cpp:type:`pcnt_watch_event_data_t`.
- ``pcnt_evt_type_t`` is not used any more, they have been replaced by a universal **Watch Point Event**. In the event callback :cpp:type:`pcnt_watch_cb_t`, it is still possible to distinguish different watch points from :cpp:type:`pcnt_watch_event_data_t`.
- ``pcnt_count_mode_t`` is replaced by :cpp:type:`pcnt_channel_edge_action_t`, and ``pcnt_ctrl_mode_t`` is replaced by :cpp:type:`pcnt_channel_level_action_t`.
Breaking Changes in Usage
@ -291,7 +291,7 @@ LEDC
The temperature sensor driver has been redesigned and it is recommended to use the new driver. However, the old driver is still available but cannot be used with the new driver simultaneously.
The new driver can be included via ``driver/temperature_sensor.h``. The old driver is still available in the previous include path ``driver/temp_sensor.h``. However, including ``driver/temp_sensor.h`` will trigger the build warning below by default. The warning can be suppressed by enabling the menuconfig option :ref:`CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN`.
The new driver can be included via ``driver/temperature_sensor.h``. The old driver is still available in the previous include path ``driver/temp_sensor.h``. However, including ``driver/temp_sensor.h`` triggers the build warning below by default. The warning can be suppressed by enabling the menuconfig option :ref:`CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN`.
.. code-block:: text
@ -308,7 +308,7 @@ LEDC
RMT driver has been redesigned (see :doc:`RMT transceiver <../../../api-reference/peripherals/rmt>`), which aims to unify and extend the usage of RMT peripheral.
Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/rmt.h``. However, including ``driver/rmt.h`` will trigger the build warning below by default. The warning can be suppressed by the Kconfig option :ref:`CONFIG_RMT_SUPPRESS_DEPRECATE_WARN`.
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/rmt.h``. However, including ``driver/rmt.h`` triggers the build warning below by default. The warning can be suppressed by the Kconfig option :ref:`CONFIG_RMT_SUPPRESS_DEPRECATE_WARN`.
.. code-block:: text
@ -321,15 +321,15 @@ LEDC
- ``rmt_channel_t`` which used to identify the hardware channel are removed from user space. In the new driver, RMT channel is represented by :cpp:type:`rmt_channel_handle_t`. The channel is dynamically allocated by the driver, instead of designated by user.
- ``rmt_item32_t`` is replaced by :cpp:type:`rmt_symbol_word_t`, which avoids a nested union inside a struct.
- ``rmt_mem_t`` is removed, as we don't allow users to access RMT memory block (a.k.an RMTMEM) directly. Direct access to RMTMEM doesn't make sense but make mistakes, especially when the RMT channel also connected with a DMA channel.
- ``rmt_mem_t`` is removed, as we do not allow users to access RMT memory block (a.k.an RMTMEM) directly. Direct access to RMTMEM does not make sense but make mistakes, especially when the RMT channel also connected with a DMA channel.
- ``rmt_mem_owner_t`` is removed, as the ownership is controlled by driver, not by user anymore.
- ``rmt_source_clk_t`` is replaced by :cpp:type:`rmt_clock_source_t`, and note they're not binary compatible.
- ``rmt_source_clk_t`` is replaced by :cpp:type:`rmt_clock_source_t`, and note they are not binary compatible.
- ``rmt_data_mode_t`` is removed, the RMT memory access mode is configured to always use Non-FIFO and DMA mode.
- ``rmt_mode_t`` is removed, as the driver has stand alone install functions for TX and RX channels.
- ``rmt_idle_level_t`` is removed, setting IDLE level for TX channel is available in :cpp:member:`rmt_transmit_config_t::eot_level`.
- ``rmt_carrier_level_t`` is removed, setting carrier polarity is available in :cpp:member:`rmt_carrier_config_t::polarity_active_low`.
- ``rmt_channel_status_t`` and ``rmt_channel_status_result_t`` are removed, they're not used anywhere.
- Transmitting by RMT channel doesn't expect user to prepare the RMT symbols, instead, user needs to provide an RMT Encoder to tell the driver how to convert user data into RMT symbols.
- ``rmt_channel_status_t`` and ``rmt_channel_status_result_t`` are removed, they are not used anywhere.
- Transmitting by RMT channel does not expect user to prepare the RMT symbols, instead, user needs to provide an RMT Encoder to tell the driver how to convert user data into RMT symbols.
Breaking Changes in Usage
^^^^^^^^^^^^^^^^^^^^^^^^^
@ -348,8 +348,8 @@ LEDC
- ``rmt_set_source_clk`` and ``rmt_get_source_clk`` are removed. Configuring clock source is only possible during channel installation by :cpp:member:`rmt_tx_channel_config_t::clk_src` and :cpp:member:`rmt_rx_channel_config_t::clk_src`.
- ``rmt_set_rx_filter`` is removed. In the new driver, the filter threshold is redesigned into a new concept :cpp:member:`rmt_receive_config_t::signal_range_min_ns`.
- ``rmt_set_idle_level`` and ``rmt_get_idle_level`` are removed. Setting IDLE level for TX channel is available in :cpp:member:`rmt_transmit_config_t::eot_level`.
- ``rmt_set_rx_intr_en``, ``rmt_set_err_intr_en``, ``rmt_set_tx_intr_en``, ``rmt_set_tx_thr_intr_en`` and ``rmt_set_rx_thr_intr_en`` are removed. The new driver doesn't allow user to turn on/off interrupt from user space. Instead, it provides callback functions.
- ``rmt_set_gpio`` and ``rmt_set_pin`` are removed. The new driver doesn't support to switch GPIO dynamically at runtime.
- ``rmt_set_rx_intr_en``, ``rmt_set_err_intr_en``, ``rmt_set_tx_intr_en``, ``rmt_set_tx_thr_intr_en`` and ``rmt_set_rx_thr_intr_en`` are removed. The new driver does not allow user to turn on/off interrupt from user space. Instead, it provides callback functions.
- ``rmt_set_gpio`` and ``rmt_set_pin`` are removed. The new driver does not support to switch GPIO dynamically at runtime.
- ``rmt_config`` is removed. In the new driver, basic configuration is done during the channel installation stage.
- ``rmt_isr_register`` and ``rmt_isr_deregister`` are removed, the interrupt is allocated by the driver itself.
- ``rmt_driver_install`` is replaced by :cpp:func:`rmt_new_tx_channel` and :cpp:func:`rmt_new_rx_channel`.
@ -358,22 +358,22 @@ LEDC
- ``rmt_get_counter_clock`` is removed, as the channel clock resolution is configured by user from :cpp:member:`rmt_tx_channel_config_t::resolution_hz`.
- ``rmt_wait_tx_done`` is replaced by :cpp:func:`rmt_tx_wait_all_done`.
- ``rmt_translator_init``, ``rmt_translator_set_context`` and ``rmt_translator_get_context`` are removed. In the new driver, the translator has been replaced by the RMT encoder.
- ``rmt_get_ringbuf_handle`` is removed. The new driver doesn't use Ringbuffer to save RMT symbols. Instead, the incoming data are saved to the user provided buffer directly. The user buffer can even be mounted to DMA link internally.
- ``rmt_get_ringbuf_handle`` is removed. The new driver does not use Ringbuffer to save RMT symbols. Instead, the incoming data are saved to the user provided buffer directly. The user buffer can even be mounted to DMA link internally.
- ``rmt_register_tx_end_callback`` is replaced by :cpp:func:`rmt_tx_register_event_callbacks`, where user can register :cpp:member:`rmt_tx_event_callbacks_t::on_trans_done` event callback.
- ``rmt_set_intr_enable_mask`` and ``rmt_clr_intr_enable_mask`` are removed, as the interrupt is handled by the driver, user doesn't need to take care of it.
- ``rmt_set_intr_enable_mask`` and ``rmt_clr_intr_enable_mask`` are removed, as the interrupt is handled by the driver, user does not need to take care of it.
- ``rmt_add_channel_to_group`` and ``rmt_remove_channel_from_group`` are replaced by RMT sync manager. Please refer to :cpp:func:`rmt_new_sync_manager`.
- ``rmt_set_tx_loop_count`` is removed. The loop count in the new driver is configured in :cpp:member:`rmt_transmit_config_t::loop_count`.
- ``rmt_enable_tx_loop_autostop`` is removed. In the new driver, TX loop auto stop is always enabled if available, it's not configurable anymore.
- ``rmt_enable_tx_loop_autostop`` is removed. In the new driver, TX loop auto stop is always enabled if available, it is not configurable anymore.
LCD
---
- The LCD panel initialization flow is slightly changed. Now the :cpp:func:`esp_lcd_panel_init` won't turn on the display automatically. User needs to call :cpp:func:`esp_lcd_panel_disp_on_off` to manually turn on the display. Note, this is different from turning on backlight. With this breaking change, user can flash a predefined pattern to the screen before turning on the screen. This can help avoid random noise on the screen after a power on reset.
- The LCD panel initialization flow is slightly changed. Now the :cpp:func:`esp_lcd_panel_init` will not turn on the display automatically. User needs to call :cpp:func:`esp_lcd_panel_disp_on_off` to manually turn on the display. Note, this is different from turning on backlight. With this breaking change, user can flash a predefined pattern to the screen before turning on the screen. This can help avoid random noise on the screen after a power on reset.
- :cpp:func:`esp_lcd_panel_disp_off` is deprecated, please use :cpp:func:`esp_lcd_panel_disp_on_off` instead.
- ``dc_as_cmd_phase`` is removed. The SPI LCD driver currently doesn't support a 9-bit SPI LCD. Please always use a dedicated GPIO to control the LCD D/C line.
- ``dc_as_cmd_phase`` is removed. The SPI LCD driver currently does not support a 9-bit SPI LCD. Please always use a dedicated GPIO to control the LCD D/C line.
- The way to register RGB panel event callbacks has been moved from the :cpp:type:`esp_lcd_rgb_panel_config_t` into a separate API :cpp:func:`esp_lcd_rgb_panel_register_event_callbacks`. However, the event callback signature is not changed.
- Previous ``relax_on_idle`` flag in :cpp:type:`esp_lcd_rgb_panel_config_t` has been renamed into :cpp:member:`esp_lcd_rgb_panel_config_t::refresh_on_demand`, which expresses the same meaning but with a clear name.
- If the RGB LCD is created with the ``refresh_on_demand`` flag enabled, the driver won't start a refresh in the :cpp:func:`esp_lcd_panel_draw_bitmap`. Now users have to call :cpp:func:`esp_lcd_rgb_panel_refresh` to refresh the screen by themselves.
- If the RGB LCD is created with the ``refresh_on_demand`` flag enabled, the driver will not start a refresh in the :cpp:func:`esp_lcd_panel_draw_bitmap`. Now users have to call :cpp:func:`esp_lcd_rgb_panel_refresh` to refresh the screen by themselves.
- :cpp:type:`esp_lcd_color_space_t` is deprecated, please use :cpp:type:`lcd_color_space_t` to describe the color space, and use :cpp:type:`lcd_color_rgb_endian_t` to describe the data order of RGB color.
.. only:: SOC_MCPWM_SUPPORTED
@ -385,7 +385,7 @@ LCD
The new driver's aim is to make each MCPWM submodule independent to each other, and give the freedom of resource connection back to users.
Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/mcpwm.h``. However, using legacy driver will rigger the build warning below by default. This warning can be suppressed by the Kconfig option :ref:`CONFIG_MCPWM_SUPPRESS_DEPRECATE_WARN`.
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/mcpwm.h``. However, using legacy driver triggers the build warning below by default. This warning can be suppressed by the Kconfig option :ref:`CONFIG_MCPWM_SUPPRESS_DEPRECATE_WARN`.
.. code-block:: text
@ -398,13 +398,13 @@ LCD
The new MCPWM driver is object-oriented, where most of the MCPWM submodule has a driver object associated with it. The driver object is created by factory function like :cpp:func:`mcpwm_new_timer`. IO control function always needs an object handle, in the first place.
The legacy driver has an inappropriate assumption, that is the MCPWM operator should be connected to different MCPWM timer. In fact, the hardware doesn't have such limitation. In the new driver, a MCPWM timer can be connected to multiple operators, so that the operators can achieve the best synchronization performance.
The legacy driver has an inappropriate assumption, that is the MCPWM operator should be connected to different MCPWM timer. In fact, the hardware does not have such limitation. In the new driver, a MCPWM timer can be connected to multiple operators, so that the operators can achieve the best synchronization performance.
The legacy driver presets the way to generate a PWM waveform into a so called ``mcpwm_duty_type_t``. However, the duty cycle modes listed there are far from sufficient. Likewise, legacy driver has several preset ``mcpwm_deadtime_type_t``, which also doesn't cover all the use cases. What's more, user usually gets confused by the name of the duty cycle mode and dead-time mode. In the new driver, there're no such limitation, but user has to construct the generator behavior from scratch.
The legacy driver presets the way to generate a PWM waveform into a so called ``mcpwm_duty_type_t``. However, the duty cycle modes listed there are far from sufficient. Likewise, legacy driver has several preset ``mcpwm_deadtime_type_t``, which also does not cover all the use cases. What is more, user usually gets confused by the name of the duty cycle mode and dead-time mode. In the new driver, there are no such limitation, but user has to construct the generator behavior from scratch.
In the legacy driver, the ways to synchronize the MCPWM timer by GPIO, software and other timer module are not unified. It increased learning costs for users. In the new driver, the synchronization APIs are unified.
The legacy driver has mixed the concepts of "Fault detector" and "Fault handler". Which make the APIs very confusing to users. In the new driver, the fault object just represents a failure source, and we introduced a new concept -- **brake** to express the concept of "Fault handler". What's more, the new driver supports software fault.
The legacy driver has mixed the concepts of "Fault detector" and "Fault handler". Which make the APIs very confusing to users. In the new driver, the fault object just represents a failure source, and we introduced a new concept -- **brake** to express the concept of "Fault handler". What is more, the new driver supports software fault.
The legacy drive only provides callback functions for the capture submodule. The new driver provides more useful callbacks for various MCPWM submodules, like timer stop, compare match, fault enter, brake, etc.
@ -416,14 +416,14 @@ LCD
Breaking Changes in Usage
^^^^^^^^^^^^^^^^^^^^^^^^^
- ``mcpwm_gpio_init`` and ``mcpwm_set_pin``: GPIO configurations are moved to submodule's own configuration. e.g. set the PWM GPIO in :cpp:member:`mcpwm_generator_config_t::gen_gpio_num`.
- ``mcpwm_init``: To get an expected PWM waveform, users need to allocated at least one MCPWM timer and MCPWM operator, then connect them by calling :cpp:func:`mcpwm_operator_connect_timer`. After that, users should set the generator's actions on various events by calling e.g. :cpp:func:`mcpwm_generator_set_actions_on_timer_event`, :cpp:func:`mcpwm_generator_set_actions_on_compare_event`.
- ``mcpwm_group_set_resolution``: in the new driver, the group resolution is fixed to the maximum, usually it's 80MHz.
- ``mcpwm_gpio_init`` and ``mcpwm_set_pin``: GPIO configurations are moved to submodule's own configuration. e.g., set the PWM GPIO in :cpp:member:`mcpwm_generator_config_t::gen_gpio_num`.
- ``mcpwm_init``: To get an expected PWM waveform, users need to allocated at least one MCPWM timer and MCPWM operator, then connect them by calling :cpp:func:`mcpwm_operator_connect_timer`. After that, users should set the generator's actions on various events by calling e.g., :cpp:func:`mcpwm_generator_set_actions_on_timer_event`, :cpp:func:`mcpwm_generator_set_actions_on_compare_event`.
- ``mcpwm_group_set_resolution``: in the new driver, the group resolution is fixed to the maximum, usually it is 80 MHz.
- ``mcpwm_timer_set_resolution``: MCPWM Timer resolution is set in :cpp:member:`mcpwm_timer_config_t::resolution_hz`.
- ``mcpwm_set_frequency``: PWM frequency is determined by :cpp:member:`mcpwm_timer_config_t::resolution_hz`, :cpp:member:`mcpwm_timer_config_t::count_mode` and :cpp:member:`mcpwm_timer_config_t::period_ticks`.
- ``mcpwm_set_duty``: To set the PWM duty cycle, users should call :cpp:func:`mcpwm_comparator_set_compare_value` to change comparator's threshold.
- ``mcpwm_set_duty_type``: There won't be any preset duty cycle types, the duty cycle type is configured by setting different generator actions. e.g. :cpp:func:`mcpwm_generator_set_actions_on_timer_event`.
- ``mcpwm_set_signal_high`` and ``mcpwm_set_signal_low`` are replaced by :cpp:func:`mcpwm_generator_set_force_level`. In the new driver, it's implemented by setting force action for the generator, instead of changing the duty cycle to 0% or 100% at the background.
- ``mcpwm_set_duty_type``: There is no preset duty cycle types. The duty cycle type is configured by setting different generator actions. e.g., :cpp:func:`mcpwm_generator_set_actions_on_timer_event`.
- ``mcpwm_set_signal_high`` and ``mcpwm_set_signal_low`` are replaced by :cpp:func:`mcpwm_generator_set_force_level`. In the new driver, it is implemented by setting force action for the generator, instead of changing the duty cycle to 0% or 100% at the background.
- ``mcpwm_start`` and ``mcpwm_stop`` are replaced by :cpp:func:`mcpwm_timer_start_stop`. You have more modes to start and stop the MCPWM timer, see :cpp:type:`mcpwm_timer_start_stop_cmd_t`.
- ``mcpwm_carrier_init`` is replaced by :cpp:func:`mcpwm_operator_apply_carrier`.
- ``mcpwm_carrier_enable`` and ``mcpwm_carrier_disable``: Enabling and disabling carrier submodule is done automatically by checking whether the carrier configuration structure :cpp:type:`mcpwm_carrier_config_t` is NULL.
@ -435,11 +435,11 @@ LCD
- ``mcpwm_deadtime_enable`` and ``mcpwm_deadtime_disable`` are replaced by :cpp:func:`mcpwm_generator_set_dead_time`.
- ``mcpwm_fault_init`` is replaced by :cpp:func:`mcpwm_new_gpio_fault`.
- ``mcpwm_fault_set_oneshot_mode``, ``mcpwm_fault_set_cyc_mode`` are replaced by :cpp:func:`mcpwm_operator_set_brake_on_fault` and :cpp:func:`mcpwm_generator_set_actions_on_brake_event`.
- ``mcpwm_capture_enable`` is removed. It's duplicated to :cpp:func:`mcpwm_capture_enable_channel`.
- ``mcpwm_capture_disable`` is removed. It's duplicated to :cpp:func:`mcpwm_capture_capture_disable_channel`.
- ``mcpwm_capture_enable`` is removed. It is duplicated to :cpp:func:`mcpwm_capture_enable_channel`.
- ``mcpwm_capture_disable`` is removed. It is duplicated to :cpp:func:`mcpwm_capture_capture_disable_channel`.
- ``mcpwm_capture_enable_channel`` and ``mcpwm_capture_disable_channel`` are replaced by :cpp:func:`mcpwm_capture_channel_enable` and :cpp:func:`mcpwm_capture_channel_disable`.
- ``mcpwm_capture_signal_get_value`` and ``mcpwm_capture_signal_get_edge``: Capture timer count value and capture edge are provided in the capture event callback, via :cpp:type:`mcpwm_capture_event_data_t`. Capture data are only valuable when capture event happens. Providing single API to fetch capture data is meaningless.
- ``mcpwm_sync_enable`` is removed. It's duplicated to :cpp:func:`mcpwm_sync_configure`.
- ``mcpwm_sync_enable`` is removed. It is duplicated to :cpp:func:`mcpwm_sync_configure`.
- ``mcpwm_sync_configure`` is replaced by :cpp:func:`mcpwm_timer_set_phase_on_sync`.
- ``mcpwm_sync_disable`` is equivalent to setting :cpp:member:`mcpwm_timer_sync_phase_config_t::sync_src` to ``NULL``.
- ``mcpwm_set_timer_sync_output`` is replaced by :cpp:func:`mcpwm_new_timer_sync_src`.
@ -456,7 +456,7 @@ LCD
.. only:: SOC_I2S_SUPPORTED
I2S driver
I2S Driver
----------
The I2S driver has been redesigned (see :doc:`I2S Driver <../../../api-reference/peripherals/i2s>`), which aims to rectify the shortcomings of the driver that were exposed when supporting all the new features of ESP32-C3 & ESP32-S3. The new driver's APIs are available by including corresponding I2S mode's header files :component_file:`driver/i2s/include/driver/i2s_std.h`, :component_file:`driver/i2s/include/driver/i2s_pdm.h`, or :component_file:`driver/i2s/include/driver/i2s_tdm.h`.
@ -478,11 +478,11 @@ LCD
The minimum control unit in new I2S driver are now individual TX/RX channels instead of an entire I2S controller (that consistes of multiple channels).
- The TX and RX channels of the same I2S controller can be controlled separately, meaning that they are configured such that they can be started or stopped separately.
- The c:type:`i2s_chan_handle_t` handle type is used to uniquely identify I2S channels. All the APIs will require the channel handle and users need to maintain the channel handles by themselves.
- The :cpp:type:`i2s_chan_handle_t` handle type is used to uniquely identify I2S channels. All the APIs require the channel handle and users need to maintain the channel handles by themselves.
- On the ESP32-C3 and ESP32-S3, TX and RX channels in the same controller can be configured to different clocks or modes.
- However, on the ESP32 and ESP32-S2, the TX and RX channels of the same controller still share some hardware resources. Thus, configurations may cause one channel to affect another channel in the same controller.
- The channels can be registered to an available I2S controller automatically by setting :cpp:enumerator:`i2s_port_t::I2S_NUM_AUTO` as I2S port ID which will cause the driver to search for the available TX/RX channels. However, the driver also supports registering channels to a specific port.
- In order to distinguish between TX/RX channels and sound channels, the term 'channel' in the context of the I2S driver will only refer to TX/RX channels. Meanwhile, sound channels will be referred to as "slots".
- The channels can be registered to an available I2S controller automatically by setting :cpp:enumerator:`i2s_port_t::I2S_NUM_AUTO` as I2S port ID which causes the driver to search for the available TX/RX channels. However, the driver also supports registering channels to a specific port.
- In order to distinguish between TX/RX channels and sound channels, the term "channel" in the context of the I2S driver only refers to TX/RX channels. Meanwhile, sound channels are referred to as "slots".
I2S Mode Categorization
""""""""""""""""""""""""
@ -509,7 +509,7 @@ LCD
""""
- States and state-machine are adopted in the new I2S driver to avoid APIs called in wrong state.
- ADC and DAC modes are removed. They will only be supported in their own drivers and the legacy I2S driver.
- ADC and DAC modes are removed. They are only supported in their own drivers and the legacy I2S driver.
Breaking Changes in Usage
^^^^^^^^^^^^^^^^^^^^^^^^^
@ -519,7 +519,7 @@ LCD
1. Call :cpp:func:`i2s_new_channel` to acquire channel handles. We should specify the work role and I2S port in this step. Besides, the TX or RX channel handle will be generated by the driver. Inputting both two TX and RX channel handles is not necessary but at least one handle is needed. In the case of inputting both two handles, the driver will work at the duplex mode. Both TX and RX channels will be avaliable on a same port, and they will share the MCLK, BCLK and WS signal. But if only one of the TX or RX channel handle is inputted, this channel will only work in the simplex mode.
2. Call :func:`i2s_channel_init_std_mode`, :func:`i2s_channel_init_pdm_rx_mode`, :func:`i2s_channel_init_pdm_tx_mode` or :func:`i2s_channel_init_tdm_mode` to initialize the channel to the specified mode. Corresponding slot, clock and GPIO configurations are needed in this step.
3. (Optional) Call :cpp:func:`i2s_channel_register_event_callback` to register the ISR event callback functions. I2S events now can be received by the callback function synchronously, instead of from the event queue asynchronously.
4. Call :cpp:func:`i2s_channel_enable` to start the hardware of I2S channel. In the new driver, I2S won't start automatically after installed, and users are supposed to know clearly whether the channel has started or not.
4. Call :cpp:func:`i2s_channel_enable` to start the hardware of I2S channel. In the new driver, I2S does not start automatically after installed, and users are supposed to know clearly whether the channel has started or not.
5. Read or write data by :cpp:func:`i2s_channel_read` or :cpp:func:`i2s_channel_write`. Certainly, only the RX channel handle is suppoesd to be inputted in :cpp:func:`i2s_channel_read` and the TX channel handle in :cpp:func:`i2s_channel_write`.
6. (Optional) The slot, clock and GPIO configurations can be changed by corresponding 'reconfig' functions, but :cpp:func:`i2s_channel_disable` must be called before updating the configurations.
7. Call :cpp:func:`i2s_channel_disable` to stop the hardware of I2S channel.

15
docs/en/migration-guides/release-5.x/5.0/protocols.rst
View File

@ -15,7 +15,7 @@ For more details about Mbed TLS's migration from version 2.x to version 3.0 or g
Breaking Changes (Summary)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most structure fields are now private
Most Structure Fields Are Now Private
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Direct access to fields of structures (``struct`` types) declared in public headers is no longer supported.
@ -37,6 +37,7 @@ Deprecated Functions Were Removed from Cryptography Modules
Deprecated Config Options
^^^^^^^^^^^^^^^^^^^^^^^^^
Following are some of the important config options deprecated by this update. The configs related to and/or dependent on these have also been deprecated.
- ``MBEDTLS_SSL_PROTO_SSL3`` : Support for SSL 3.0
@ -46,7 +47,9 @@ Following are some of the important config options deprecated by this update. Th
- ``MBEDTLS_DES_C`` : Support for 3DES ciphersuites
- ``MBEDTLS_RC4_MODE`` : Support for RC4-based ciphersuites
.. note:: This list includes only major options configurable through ``idf.py menuconfig``. For more details on deprecated options, refer to the `official guide <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md#most-structure-fields-are-now-private>`__.
.. note::
This list includes only major options configurable through ``idf.py menuconfig``. For more details on deprecated options, refer to the `official guide <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md#most-structure-fields-are-now-private>`__.
Miscellaneous
@ -61,7 +64,9 @@ The Diffie-Hellman Key Exchange modes have now been disabled by default due to s
- ``MBEDTLS_KEY_EXCHANGE_DHE_PSK`` : Support for Diffie-Hellman PSK (pre-shared-key) TLS authentication modes
- ``MBEDTLS_KEY_EXCHANGE_DHE_RSA`` : Support for cipher suites with the prefix ``TLS-DHE-RSA-WITH-``
.. note:: During the initial step of the handshake (i.e. ``client_hello``), the server selects a cipher from the list that the client publishes. As the DHE_PSK/DHE_RSA ciphers have now been disabled by the above change, the server would fall back to an alternative cipher; if in a rare case, it does not support any other cipher, the handshake would fail. To retrieve the list of ciphers supported by the server, one must attempt to connect with the server with a specific cipher from the client-side. Few utilities can help do this, e.g. ``sslscan``.
.. note::
During the initial step of the handshake (i.e., ``client_hello``), the server selects a cipher from the list that the client publishes. As the DHE_PSK/DHE_RSA ciphers have now been disabled by the above change, the server would fall back to an alternative cipher; if in a rare case, it does not support any other cipher, the handshake would fail. To retrieve the list of ciphers supported by the server, one must attempt to connect with the server with a specific cipher from the client-side. Few utilities can help do this, e.g., ``sslscan``.
Remove ``certs`` Module from X509 Library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -109,7 +114,7 @@ ESP-TLS
Breaking Changes (Summary)
~~~~~~~~~~~~~~~~~~~~~~~~~~
``esp_tls_t`` Structure is Now Private
``esp_tls_t`` Structure Is Now Private
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :cpp:type:`esp_tls_t` has now been made completely private. You cannot access its internal structures directly. Any necessary data that needs to be obtained from the ESP-TLS handle can be done through respective getter/setter functions. If there is a requirement of a specific getter/setter function, please raise an `issue <https://github.com/espressif/esp-idf/issues>`__ on ESP-IDF.
@ -118,10 +123,12 @@ The :cpp:type:`esp_tls_t` has now been made completely private. You cannot acces
The list of newly added getter/setter function is as as follows:
.. list::
* :cpp:func:`esp_tls_get_ssl_context` - Obtain the ssl context of the underlying ssl stack from the ESP-TLS handle.
Function Deprecations And Recommended Alternatives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Following table summarizes the deprecated functions removed and their alternatives to be used from ESP-IDF v5.0 onwards.
.. list-table::

9
docs/en/migration-guides/release-5.x/5.0/removed-components.rst
View File

@ -3,10 +3,10 @@ Removed or Deprecated Components
:link_to_translation:`zh_CN:[中文]`
Components Moved to IDF Component Registry
Components Moved to ESP-IDF Component Registry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Following components are removed from ESP-IDF and moved to `IDF Component Registry <https://components.espressif.com/>`_:
Following components are removed from ESP-IDF and moved to `ESP-IDF Component Registry <https://components.espressif.com/>`_:
* `libsodium <https://components.espressif.com/component/espressif/libsodium>`_
* `cbor <https://components.espressif.com/component/espressif/cbor>`_
@ -27,6 +27,7 @@ Following components are removed from ESP-IDF and moved to `IDF Component Regist
* `tinyusb <https://components.espressif.com/components/espressif/esp_tinyusb>`_
.. note::
Please note that http parser functionality which was previously part of ``nghttp`` component is now part of :component:`http_parser <http_parser>` component.
These components can be installed using ``idf.py add-dependency`` command.
@ -40,14 +41,16 @@ To find out which versions of each component are available, open https://compone
Deprecated Components
^^^^^^^^^^^^^^^^^^^^^
The following components are removed since they were deprecated in IDF v4.x:
The following components are removed since they were deprecated in ESP-IDF v4.x:
* ``tcpip_adapter``. Please use the :doc:`ESP-NETIF </api-reference/network/esp_netif>` component instead; you can follow the :ref:`tcpip-adapter`.
.. note::
OpenSSL-API component is no longer supported. It is not available in the IDF Component Registry, either. Please use :doc:`ESP-TLS </api-reference/protocols/esp_tls>` or :component:`mbedtls` API directly.
.. note::
``esp_adc_cal`` component is no longer supported. New adc calibration driver is in ``esp_adc`` component. Legacy adc calibration driver has been moved into ``esp_adc`` component. To use legacy ``esp_adc_cal`` driver APIs, you should add ``esp_adc`` component to the list of component requirements in CMakeLists.txt. Also check :doc:`Peripherals Migration Guide </migration-guides/release-5.x/5.0/peripherals>` for more details.
The targets components are no longer necessary after refactoring and have been removed:

36
docs/en/migration-guides/release-5.x/5.0/system.rst
View File

@ -24,8 +24,8 @@ Cache Error Interrupt
The Cache Error Interrupt API (functions/types/macros prefixed with ``esp_cache_err``) has been made into a private API. Thus, the previous include path ``#include "{IDF_TARGET_NAME}/cache_err_int.h"`` has been removed. If users still require usage of the Cache Error Interrupt API (though this is not recommended), it can be included via ``#include "esp_private/cache_err_int.h"``.
bootloader_support
--------------------
``bootloader_support``
----------------------
* The function ``bootloader_common_get_reset_reason()`` has been removed. Please use the function ``esp_rom_get_reset_reason()`` in the ROM component.
* The functions ``esp_secure_boot_verify_sbv2_signature_block()`` and ``esp_secure_boot_verify_rsa_signature_block()`` have been removed without replacement. We do not expect users to use these directly. If they are indeed still neccessary, please open a feature request on `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ explaining why these functions are necessary to you.
@ -45,8 +45,8 @@ ROM
The previously deprecated ROM-related header files located in ``components/esp32/rom/`` (old include path: ``rom/*.h``) have been moved. Please use the new target-specific path from ``components/esp_rom/include/{IDF_TARGET_NAME}/`` (new include path: ``{IDF_TARGET_NAME}/rom/*.h``).
esp_hw_support
--------------
``esp_hw_support``
------------------
- The header files ``soc/cpu.h`` have been deleted and deprecated CPU util functions have been removed. ESP-IDF developers should include ``esp_cpu.h`` instead for equivalent functions.
- The header files ``hal/cpu_ll.h``, ``hal/cpu_hal.h``, ``hal/soc_ll.h``, ``hal/soc_hal.h`` and ``interrupt_controller_hal.h`` CPU API functions have been deprecated. ESP-IDF developers should include ``esp_cpu.h`` instead for equivalent functions.
@ -56,7 +56,7 @@ esp_hw_support
- The Panic API (functions/types/macros prefixed with ``esp_panic``) has been made into a private API. Thus, the previous include path ``#include "esp_panic.h"`` has been removed. If users still require usage of the Trax API (though this is not recommended), it can be included via ``#include "esp_private/panic_reason.h"``. Besides, developers should include ``esp_debug_helpers.h`` instead to use any debug-related helper functions, e.g., print backtrace.
- The header file ``soc_log.h`` is now renamed to ``esp_hw_log.h`` and has been made private. Users are encouraged to use logging APIs provided under ``esp_log.h`` instead.
- The header files ``spinlock.h``, ``clk_ctrl_os.h``, and ``rtc_wdt.h`` must now be included without the ``soc`` prefix. For example, ``#include "spinlock.h"``.
- ``esp_chip_info()`` returns the chip version in the format = 100 * ``major eFuse version`` + ``minor eFuse version``. Thus, the ``revision`` in the ``esp_chip_info_t`` structure is expanded to uint16_t to fit the new format.
- ``esp_chip_info()`` returns the chip version in the format = 100 * ``major eFuse version`` + ``minor eFuse version``. Thus, the ``revision`` in the ``esp_chip_info_t`` structure is expanded to ``uint16_t`` to fit the new format.
PSRAM
^^^^^
@ -70,20 +70,22 @@ eFuse
- The parameter type of function ``esp_secure_boot_read_key_digests()`` changed from ``ets_secure_boot_key_digests_t*`` to ``esp_secure_boot_key_digests_t*``. The new type is the same as the old one, except that the ``allow_key_revoke`` flag has been removed. The latter was always set to ``true`` in current code, not providing additional information.
- Added eFuse wafer revisions: major and minor. The ``esp_efuse_get_chip_ver()`` API is not compatible with these changes, so it was removed. Instead, please use the following APIs: ``efuse_hal_get_major_chip_version()``, ``efuse_hal_get_minor_chip_version()`` or ``efuse_hal_chip_revision()``.
esp_common
------------
``EXT_RAM_ATTR`` is deprecated. Use the new macro ``EXT_RAM_BSS_ATTR`` to put .bss on PSRAM.
``esp_common``
--------------
``EXT_RAM_ATTR`` is deprecated. Use the new macro ``EXT_RAM_BSS_ATTR`` to put ``.bss`` on PSRAM.
``esp_system``
--------------
esp_system
------------
- The header files ``esp_random.h``, ``esp_mac.h``, and ``esp_chip_info.h``, which were all previously indirectly included via the header file ``esp_system.h``, must now be included directly. These indirect inclusions from ``esp_system.h`` have been removed.
- The Backtrace Parser API (functions/types/macros prefixed with ``esp_eh_frame_``) has been made into a private API. Thus, the previous include path ``#include "eh_frame_parser.h"`` has been removed. If users still require usage of the Backtrace Parser API (though this is not recommended), it can be included via ``#include "esp_private/eh_frame_parser.h"``.
- The Interrupt Watchdog API (functions/types/macros prefixed with ``esp_int_wdt_``) has been made into a private API. Thus, the previous include path ``#include "esp_int_wdt.h"`` has been removed. If users still require usage of the Interrupt Watchdog API (though this is not recommended), it can be included via ``#include "esp_private/esp_int_wdt.h"``.
SOC Dependency
SoC Dependency
--------------
- Public API headers listed in the Doxyfiles will not expose unstable and unnecessary soc header files, such as ``soc/soc.h`` and ``soc/rtc.h``. That means the user has to explicitly include them in their code if these "missing" header files are still wanted.
- Public API headers listed in the Doxyfiles will not expose unstable and unnecessary SoC header files, such as ``soc/soc.h`` and ``soc/rtc.h``. That means the user has to explicitly include them in their code if these "missing" header files are still wanted.
- Kconfig option ``LEGACY_INCLUDE_COMMON_HEADERS`` is also removed.
- The header file ``soc/soc_memory_types.h`` has been deprecated. Users should use the ``esp_memory_utils.h`` instead. Including ``soc/soc_memory_types.h`` will bring a build warning like ``soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h``
@ -92,10 +94,10 @@ APP Trace
One of the timestamp sources has changed from the legacy timer group driver to the new :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`. Kconfig choices like ``APPTRACE_SV_TS_SOURCE_TIMER00`` has been changed to ``APPTRACE_SV_TS_SOURCE_GPTIMER``. User no longer need to choose the group and timer ID.
esp_timer
-----------
``esp_timer``
-------------
The FRC2-based legacy implementation of esp_timer available on ESP32 has been removed. The simpler and more efficient implementation based on the LAC timer is now the only option.
The FRC2-based legacy implementation of ``esp_timer`` available on ESP32 has been removed. The simpler and more efficient implementation based on the LAC timer is now the only option.
ESP Image
---------
@ -167,6 +169,6 @@ Bootloader Support
Chip Revision
^^^^^^^^^^^^^
The bootloader checks the chip revision at the beginning of the application loading. The application can only be loaded if the version is ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and `<` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
The bootloader checks the chip revision at the beginning of the application loading. The application can only be loaded if the version is ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
During the OTA upgrade, the version requirements and chip revision in the application header are checked for compatibility. The application can only be updated if the version is ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and `<` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
During the OTA upgrade, the version requirements and chip revision in the application header are checked for compatibility. The application can only be updated if the version is ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.

10
docs/en/migration-guides/release-5.x/5.0/tools.rst
View File

@ -3,12 +3,12 @@ Tools
:link_to_translation:`zh_CN:[中文]`
IDF Monitor
-----------
ESP-IDF Monitor
---------------
IDF Monitor makes the following changes regarding baud-rate:
ESP-IDF Monitor makes the following changes regarding baud-rate:
- IDF monitor now uses the custom console baud-rate (:ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`) by default instead of 115200.
- ESP-IDF monitor now uses the custom console baud-rate (:ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`) by default instead of 115200.
- Setting a custom baud from menuconfig is no longer supported.
- A custom baud-rate can be specified from command line with the ``idf.py monitor -b <baud>`` command or through setting environment variables.
- Please note that the baud-rate argument has been renamed from ``-B`` to ``-b`` in order to be consistent with the global baud-rate ``idf.py -b <baud>``. Run ``idf.py monitor --help`` for more information.
@ -46,7 +46,7 @@ Deprecated Commands
Esptool
-------
The CONFIG_ESPTOOLPY_FLASHSIZE_DETECT option has been renamed to :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` and has been disabled by default. New and existing projects migrated to ESP-IDF v5.0 will have to set :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`. If this is not possible due to an unknown flash size at build time, then :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` can be enabled. However, once enabled, to keep the digest valid, a SHA256 digest will no longer be appended to the image when updating the binary header with the flash size during flashing.
The ``CONFIG_ESPTOOLPY_FLASHSIZE_DETECT`` option has been renamed to :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` and has been disabled by default. New and existing projects migrated to ESP-IDF v5.0 have to set :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`. If this is not possible due to an unknown flash size at build time, then :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` can be enabled. However, once enabled, to keep the digest valid, an SHA256 digest is no longer appended to the image when updating the binary header with the flash size during flashing.
Windows Environment
--------------------

10
docs/en/migration-guides/release-5.x/5.1/gcc.rst
View File

@ -21,7 +21,7 @@ The upgrade to GCC 12.2.0 has resulted in the addition of new warnings, or enhan
``-Wuse-after-free``
--------------------
Typically, this warning should not produce false-positives for release-level code. But this may appear in test cases. There is an example of how it was fixed in IDF's test_realloc.c.
Typically, this warning should not produce false-positives for release-level code. But this may appear in test cases. There is an example of how it was fixed in ESP-IDF's ``test_realloc.c``.
.. code-block:: c
@ -42,7 +42,7 @@ Pointers may be converted to int to avoid warning ``-Wuse-after-free``.
GCC 12.2.0 introduces an enhanced version of the ``-Waddress`` warning option, which is now more eager in detecting the checking of pointers to an array in if-statements.
The following code will trigger the warning:
The following code triggers the warning:
.. code-block:: c
@ -61,10 +61,10 @@ Eliminating unnecessary checks resolves the warning.
memset(array, 0xff, sizeof(array));
RISC-V Builds Outside of IDF
============================
RISC-V Builds Outside of ESP-IDF
================================
The RISC-V extensions ``zicsr`` and ``zifencei`` have been separated from the ``I`` extension. GCC 12 reflects this change, and as a result, when building for RISC-V ESP32 chips outside of the IDF framework, you must include the ``_zicsr_zifencei`` postfix when specifying the -march option in your build system.
The RISC-V extensions ``zicsr`` and ``zifencei`` have been separated from the ``I`` extension. GCC 12 reflects this change, and as a result, when building for RISC-V ESP32 chips outside of the ESP-IDF framework, you must include the ``_zicsr_zifencei`` postfix when specifying the -march option in your build system.
Example:

2
docs/en/migration-guides/release-5.x/5.1/networking.rst
View File

@ -6,4 +6,4 @@ Networking
SNTP
----
SNTP module now provides thread safe APIs to access lwIP functionality. It's recommended to use :doc:`ESP_NETIF </api-reference/network/esp_netif>` API. Please refer to the chapter :ref:`esp_netif-sntp-api` for more details.
SNTP module now provides thread safe APIs to access lwIP functionality. It is recommended to use :doc:`ESP_NETIF </api-reference/network/esp_netif>` API. Please refer to the chapter :ref:`esp_netif-sntp-api` for more details.

1
docs/en/migration-guides/release-5.x/5.1/storage.rst
View File

@ -8,6 +8,7 @@ FatFs
``esp_vfs_fat_sdmmc_unmount()`` is now deprecated, and you can use :cpp:func:`esp_vfs_fat_sdcard_unmount()` instead. This API is deprecated in previous ESP-IDF versions, but without a deprecation warning or migration guide. Since ESP-IDF v5.1, calling this ``esp_vfs_fat_sdmmc_unmount()`` API will generate a deprecation warning.
SPI_FLASH
---------

2
docs/en/migration-guides/release-5.x/5.1/system.rst
View File

@ -19,7 +19,7 @@ FreeRTOS
Allowing FreeRTOS objects (such as queues and semaphores) to be placed in external RAM becomes an issue if those objects are accessed while the cache is disabled (such as during SPI flash write operations) and would lead to a cache access errors (see :doc:`Fatal Errors </api-guides/fatal-errors>` for more details).
Therefore, FreeRTOS has been updated to always use internal memory (i.e., DRAM) for dynamic memory allocation. Calling FreeRTOS creation functions (e.g., :cpp:func:`xTaskCreate`, :cpp:func:`xQueueCreate` ) will guarantee that the memory allocated for those tasks/objects is from internal memory (see :ref:`freertos-heap` for more details).
Therefore, FreeRTOS has been updated to always use internal memory (i.e., DRAM) for dynamic memory allocation. Calling FreeRTOS creation functions (e.g., :cpp:func:`xTaskCreate`, :cpp:func:`xQueueCreate`) guarantees that the memory allocated for those tasks/objects is from internal memory (see :ref:`freertos-heap` for more details).
.. warning::

14
docs/en/versions.rst
View File

@ -110,7 +110,7 @@ Using an “In Service” version is recommended when starting a new project.
Users are encouraged to upgrade all projects to a newer ESP-IDF release before the support period finishes and the release becomes End of Life (EOL). It is our policy to not continue fixing bugs in End of Life releases.
Pre-release versions (betas, previews, `-rc` and `-dev` versions, etc) are not covered by any support period. Sometimes a particular feature is marked as "Preview" in a release, which means it is also not covered by the support period.
Pre-release versions (betas, previews, ``-rc`` and ``-dev`` versions, etc) are not covered by any support period. Sometimes a particular feature is marked as "Preview" in a release, which means it is also not covered by the support period.
The ESP-IDF Programming Guide has information about the `different versions of ESP-IDF <https://docs.espressif.com/projects/esp-idf/en/latest/versions.html>`_ (major, minor, bugfix, etc).
@ -174,7 +174,9 @@ Updating ESP-IDF depends on which version(s) you wish to follow:
- :ref:`updating-master` is recommended for the latest features, development use, and testing.
- :ref:`updating-release-branch` is a compromise between the first two.
.. note:: These guides assume that you already have a local copy of ESP-IDF cloned. To get one, check Step 2 in the :doc:`Getting Started </get-started/index>` guide for any ESP-IDF version.
.. note::
These guides assume that you already have a local copy of ESP-IDF cloned. To get one, check Step 2 in the :doc:`Getting Started </get-started/index>` guide for any ESP-IDF version.
.. _`updating-stable-releases`:
@ -198,7 +200,9 @@ To update to a new ESP-IDF release (recommended for production use), this is the
- In the Windows system, please replace ``cd $IDF_PATH`` with ``cd %IDF_PATH%``.
- When major or minor updates are released, check the Release Notes on the releases page and decide if you want to update or to stay with your current release. Updating is via the same Git commands shown above.
.. note:: If you installed the stable release via zip file instead of using git, it might not be possible to update versions using the commands. In this case, update by downloading a new zip file and replacing the entire ``IDF_PATH`` directory with its contents.
.. note::
If you installed the stable release via zip file instead of using git, it might not be possible to update versions using the commands. In this case, update by downloading a new zip file and replacing the entire ``IDF_PATH`` directory with its contents.
.. _`updating-pre-release`:
@ -215,7 +219,9 @@ Pre-release tags are not always found on the `Releases page`_. Consult the `list
Updating to Master Branch
^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: Using Master branch means living "on the bleeding edge" with the latest ESP-IDF code.
.. note::
Using Master branch means living "on the bleeding edge" with the latest ESP-IDF code.
To use the latest version on the ESP-IDF master branch, this is the process to follow:

5
docs/zh_CN/404.rst
View File

@ -2,11 +2,12 @@
无法找到该网页
==============
:link_to_translation:`en:[English]`
.. note::
抱歉，无法找到您想访问的页面。出现这一错误可能是由于您当前所选芯片或版本不支持您查找的功能。如要提供有关此文档的反馈，请告知我们您希望获取的具体文档，以便我们更好地帮助您解决问题。
抱歉，无法找到访问页面。出现该错误可能是由于当前所选芯片或版本不支持所要查找的功能。如要提供相关反馈，请告知希望获取的具体文档，以便我们提供更好的帮助。
请使用左侧菜单，浏览其他文档内容。您也可以使用菜单上方的搜索框，搜索您想查看的内容。
@ -14,5 +15,5 @@
:align: center
:alt: 抱歉，无法找到您想访问的页面。
:figclass: align-center
* :ref:`genindex`

1
docs/zh_CN/about.rst
View File

@ -1,5 +1,6 @@
关于本指南
===========
:link_to_translation:`en:[English]`
.. only:: esp32

1
docs/zh_CN/api-reference/protocols/esp_http_client.rst
View File

@ -1,5 +1,6 @@
ESP HTTP 客户端
===============
:link_to_translation:`en:[English]`
概述

10
docs/zh_CN/api-reference/protocols/esp_http_server.rst
View File

@ -8,16 +8,14 @@ HTTP 服务器
HTTP Server 组件提供了在 ESP32 上运行轻量级 Web 服务器的功能，下面介绍使用 HTTP Server 组件 API 的详细步骤：
* :cpp:func:`httpd_start`： 创建 HTTP 服务器的实例，根据具体的配置为其分配内存和资源，并返回该服务器实例的句柄。服务器使用了两个套接字，一个用来监听 HTTP 流量（TCP 类型），另一个用来处理控制信号（UDP 类型），它们在服务器的任务循环中轮流使用。通过向 httpd_start() 传递 httpd_config_t 结构体，可以在创建服务器实例时配置任务的优先级和堆栈的大小。TCP 流量被解析为 HTTP 请求，根据请求的 URI 来调用用户注册的处理程序，在处理程序中需要发送回 HTTP 响应数据包。
* :cpp:func:`httpd_start`： 创建 HTTP 服务器的实例，根据具体的配置为其分配内存和资源，并返回该服务器实例的句柄。服务器使用了两个套接字，一个用来监听 HTTP 流量（TCP 类型），另一个用来处理控制信号（UDP 类型），它们在服务器的任务循环中轮流使用。通过向 ``httpd_start()`` 传递 ``httpd_config_t`` 结构体，可以在创建服务器实例时配置任务的优先级和堆栈的大小。TCP 流量被解析为 HTTP 请求，根据请求的 URI 来调用用户注册的处理程序，在处理程序中需要发送回 HTTP 响应数据包。
* :cpp:func:`httpd_stop`： 根据传入的句柄停止服务器，并释放相关联的内存和资源。这是一个阻塞函数，首先给服务器任务发送停止信号，然后等待其终止。期间服务器任务会关闭所有已打开的连接，删除已注册的 URI 处理程序，并将所有会话的上下文数据重置为空。
* :cpp:func:`httpd_register_uri_handler`： 通过传入 ``httpd_uri_t`` 结构体类型的对象来注册 URI 处理程序。该结构体包含如下成员：``uri`` 名字，``method`` 类型（比如 ``HTTPD_GET/HTTPD_POST/HTTPD_PUT`` 等等）， ``esp_err_t *handler (httpd_req_t *req)`` 类型的函数指针，指向用户上下文数据的 ``user_ctx`` 指针。
应用示例
--------
.. highlight:: c
::
.. code-block:: c
/* URI 处理函数，在客户端发起 GET /uri 请求时被调用 */
esp_err_t get_handler(httpd_req_t *req)
@ -119,9 +117,7 @@ HTTP 服务器具有长连接的功能，允许重复使用同一个连接（会
长连接示例
^^^^^^^^^^
.. highlight:: c
::
.. code-block:: c
/* 自定义函数，用来释放上下文数据 */
void free_ctx_func(void *ctx)

5
docs/zh_CN/api-reference/protocols/esp_https_server.rst
View File

@ -1,5 +1,6 @@
HTTPS 服务器
============
:link_to_translation:`en:[English]`
概述
@ -36,9 +37,9 @@ API 说明
请参考示例 :example:`protocols/https_server` 来学习如何搭建安全的服务器。
总体而言，您只需要生成证书，将其嵌入到固件中，并且在初始化结构体中配置好正确的证书地址和长度后，将其传入服务器启动函数。
总体而言，只需生成证书，将其嵌入到固件中，并且在初始化结构体中配置好正确的证书地址和长度后，将其传入服务器启动函数。
通过改变初始化配置结构体中的标志 :cpp:member:`httpd_ssl_config::transport_mode`，可以选择是否需要 SSL 连接来启动服务器。在测试时或在速度比安全性更重要的可信环境中，您可以使用此功能。
通过改变初始化配置结构体中的标志 :cpp:member:`httpd_ssl_config::transport_mode`，可以选择是否需要 SSL 连接来启动服务器。在测试时或在速度比安全性更重要的可信环境中，可以使用此功能。
性能
-----

36
docs/zh_CN/api-reference/protocols/esp_tls.rst
View File

@ -25,9 +25,7 @@ ESP-TLS 组件提供简化 API 接口，用于访问常用 TLS 功能，支持
ESP-TLS 组件的树形结构
-------------------------------------
.. highlight:: none
::
.. code-block:: none
├── esp_tls.c
├── esp_tls.h
@ -85,7 +83,9 @@ ESP-TLS 服务器证书选择回调
ESP-TLS 组件支持以 MbedTLS 或 WolfSSL 作为其底层 SSL/TLS 库，默认仅使用 MbedTLS，WolfSSL 的 SSL/TLS 库可在 https://github.com/espressif/esp-wolfssl 上公开获取，该仓库提供二进制格式的 WolfSSL 组件，并提供了一些示例帮助用户了解相关 API。有关许可证和其他选项，请参阅仓库的 ``README.md`` 文件。下文介绍了在工程中使用 WolfSSL 的具体流程。
.. note:: `库选项位于 ESP-TLS 内部，因此切换库不会更改工程的 ESP-TLS 特定代码。`
.. note::
库选项位于 ESP-TLS 内部，因此切换库不会更改工程的 ESP-TLS 特定代码。
在 ESP-IDF 使用 WolfSSL
----------------------------------------
@ -125,16 +125,18 @@ MbedTLS 与 WolfSSL 对比
- WolfSSL
- MbedTLS
* - 总消耗堆空间
- ~19 KB
- ~37 KB
- ~ 19 KB
- ~ 37 KB
* - 任务栈使用
- ~2.2 KB
- ~3.6 KB
- ~ 2.2 KB
- ~ 3.6 KB
* - 二进制文件大小
- ~858 KB
- ~736 KB
- ~ 858 KB
- ~ 736 KB
.. note:: `若配置选项不同或相应库的版本不同，得到的值可能与上表不同`。
.. note::
若配置选项不同或相应库的版本不同，得到的值可能与上表不同。
.. only:: esp32
@ -143,7 +145,9 @@ MbedTLS 与 WolfSSL 对比
ESP-TLS 支持在 ESP32-WROOM-32SE 上使用 ATECC608A 加密芯片，但必须将 MbedTLS 作为 ESP-TLS 的底层 SSL/TLS 协议栈。未经手动更改，ESP-TLS 默认以 MbedTLS 为其底层 TLS/SSL 协议栈。
.. note:: 在 ESP32-WROOM-32SE 上的 ATECC608A 芯片必须预先配置，详情请参阅 `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_。
.. note::
在 ESP32-WROOM-32SE 上的 ATECC608A 芯片必须预先配置，详情请参阅 `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_。
要启用安全元件支持，并将其应用于工程 TLS 连接，请遵循以下步骤：
@ -175,7 +179,7 @@ MbedTLS 与 WolfSSL 对比
ESP-TLS 的数字签名
----------------------------------
ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用数字签名 (DS)，但只有当 ESP-TLS 以 MbedTLS（默认协议栈）为底层 SSL/TLS 协议栈时，才支持使用 TLS 的数字签名。有关数字签名的详细信息，请参阅 :doc:`数字签名 (DS) </api-reference/peripherals/ds>`。有关数字签名的技术细节（例如私钥参数计算），请参阅 *{IDF_TARGET_NAME} 技术参考手册* > *数字签名 (DS)* [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]。在使用数字签名前，应预先配置数字签名外设，请参阅 :ref:`configure-the-ds-peripheral`。
ESP-TLS 支持在 {IDF_TARGET_NAME} 中使用数字签名 (DS)，但只有当 ESP-TLS 以 MbedTLS（默认协议栈）为底层 SSL/TLS 协议栈时，才支持使用 TLS 的数字签名。有关数字签名的详细信息，请参阅 :doc:`数字签名 (DS) </api-reference/peripherals/ds>`。有关数字签名的技术细节（例如私钥参数计算），请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **数字签名 (DS)** [`PDF <{IDF_TARGET_TRM_EN_URL}#digsig>`__]。在使用数字签名前，应预先配置数字签名外设，请参阅 :ref:`configure-the-ds-peripheral`。
数字签名外设必须用所需的加密私钥参数初始化，相应参数在配置数字签名外设时获取。具备所需的数字签名上下文，即数字签名参数时，ESP-TLS 会在内部初始化数字签名外设。要将数字签名上下文传递给 ESP-TLS 上下文，请参阅以下代码段。注意，在删除 TLS 连接之前，不应释放传递给 ESP-TLS 上下文的数字签名上下文。
@ -191,12 +195,15 @@ MbedTLS 与 WolfSSL 对比
.ds_data = (void *)ds_ctx,
};
.. note:: 当使用数字签名进行 TLS 连接时，除其他必要参数外，仅需提供客户端证书 (``clientcert_buf``) 和数字签名参数 (``ds_data``) ，此时可将客户端密钥 (``clientkey_buf``) 设置为 NULL。
.. note::
当使用数字签名进行 TLS 连接时，除其他必要参数外，仅需提供客户端证书 (``clientcert_buf``) 和数字签名参数 (``ds_data``) ，此时可将客户端密钥 (``clientkey_buf``) 设置为 NULL。
* 使用数字签名外设进行双向认证的示例请参阅 :example:`SSL 双向认证 <protocols/mqtt/ssl_mutual_auth>`，该示例使用 ESP-TLS 实现 TLS 连接。
TLS 加密套件
------------------------------------
ESP-TLS 支持在客户端模式下设置加密套件列表，TLS 密码套件列表用于向服务器传递所支持的密码套件信息，用户可以根据自己需求增减加密套件，且适用于任何 TLS 协议栈配置。如果服务器支持列表中的任一密码套件，则 TLS 连接成功，反之连接失败。
连接客户端时，在 :cpp:type:`esp_tls_cfg_t` 结构体中设置 ``ciphersuites_list`` 的步骤如下：
@ -212,6 +219,7 @@ ESP-TLS 支持在客户端模式下设置加密套件列表，TLS 密码套件
ESP-TLS 不会检查 ``ciphersuites_list`` 的有效性，因此需调用 :cpp:func:`esp_tls_get_ciphersuites_list` 获取 TLS 协议栈中支持的加密套件列表，并检查设置的加密套件是否在支持的加密套件列表中。
.. note::
此功能仅在 MbedTLS 协议栈中有效。
API 参考

1
docs/zh_CN/api-reference/protocols/index.rst
View File

@ -1,5 +1,6 @@
应用层协议
**********
:link_to_translation:`en:[English]`
.. toctree::

5
docs/zh_CN/api-reference/protocols/mdns.rst
View File

@ -1,14 +1,15 @@
mDNS 服务
=========
:link_to_translation:`en:[English]`
mDNS 是一种组播 UDP 服务，用来提供本地网络服务和主机发现。
自 v5.0 版本起，ESP-IDF 组件 `mDNS` 已从 ESP-IDF 中迁出至独立的仓库：
自 v5.0 版本起，ESP-IDF 组件 ``mDNS`` 已从 ESP-IDF 中迁出至独立的仓库：
* GitHub 上 `mDNS 组件 <https://github.com/espressif/esp-protocols/tree/master/components/mdns>`__
运行 `idf.py add-dependency espressif/mdns`，在项目中添加 mDNS 组件。
运行 ``idf.py add-dependency espressif/mdns``，在项目中添加 mDNS 组件。
托管的文档
--------------------

10
docs/zh_CN/api-reference/protocols/mqtt.rst
View File

@ -1,5 +1,6 @@
ESP-MQTT
========
:link_to_translation:`en:[English]`
概述
@ -10,6 +11,7 @@ ESP-MQTT 是 `MQTT <https://mqtt.org/>`__ 协议客户端的实现，MQTT 是一
特性
--------
* 支持基于 TCP 的 MQTT、基于 Mbed TLS 的 SSL、基于 WebSocket 的 MQTT 以及基于 WebSocket Secure 的 MQTT
* 通过 URI 简化配置流程
* 多个实例（一个应用程序中有多个客户端）
@ -60,7 +62,7 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避
地址
===========
通过 :cpp:class:`address <esp_mqtt_client_config_t::broker_t::address_t>` 结构体的 :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` 字段或者 :cpp:member:`hostname <esp_mqtt_client_config_t::broker_t::address_t::hostname>`、:cpp:member:`transport <esp_mqtt_client_config_t::broker_t::address_t::transport>` 以及 :cpp:member:`port <esp_mqtt_client_config_t::broker_t::address_t::port>` 的组合，可以设置服务器地址。您也可以选择设置 :cpp:member:`path <esp_mqtt_client_config_t::broker_t::address_t::path>`，该字段对 WebSocket 连接而言非常有用。
通过 :cpp:class:`address <esp_mqtt_client_config_t::broker_t::address_t>` 结构体的 :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` 字段或者 :cpp:member:`hostname <esp_mqtt_client_config_t::broker_t::address_t::hostname>`、:cpp:member:`transport <esp_mqtt_client_config_t::broker_t::address_t::transport>` 以及 :cpp:member:`port <esp_mqtt_client_config_t::broker_t::address_t::port>` 的组合，可以设置服务器地址。也可以选择设置 :cpp:member:`path <esp_mqtt_client_config_t::broker_t::address_t::path>`，该字段对 WebSocket 连接而言非常有用。
使用 :cpp:member:`uri <esp_mqtt_client_config_t::broker_t::address_t::uri>` 字段的格式为 ``scheme://hostname:port/path``。
@ -87,7 +89,7 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避
- 最简配置：
.. code:: c
.. code-block:: c
const esp_mqtt_client_config_t mqtt_cfg = {
.broker.address.uri = "mqtt://mqtt.eclipseprojects.io",
@ -96,7 +98,9 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client);
esp_mqtt_client_start(client);
.. note:: 默认情况下，MQTT 客户端使用事件循环库来发布相关 MQTT 事件（已连接、已订阅、已发布等）。
.. note::
默认情况下，MQTT 客户端使用事件循环库来发布相关 MQTT 事件（已连接、已订阅、已发布等）。
=============
验证

1
docs/zh_CN/index.rst
View File

@ -1,5 +1,6 @@
ESP-IDF 编程指南
=========================
:link_to_translation:`en:[English]`
.. only:: fast_build

4
docs/zh_CN/languages.rst
View File

@ -3,12 +3,12 @@
:link_to_translation:`en:[English]`
《ESP-IDF 编程指南》部分文档现在有两种语言的版本。如有出入请以英文版本为准。
《ESP-IDF 编程指南》部分文档现在有两种语言的版本。如有出入，请以英文版本为准。
- 英文
- 中文
如下图所示，如果该文档两种语言版本均具备，您可以通过点击文档上方的语言链接轻松进行语言切换。
如下图所示，如果该文档两种语言版本均具备，可以通过点击文档上方的语言链接，轻松进行语言切换。
.. image:: /../_static/choose_language.png

4
docs/zh_CN/migration-guides/release-5.x/5.0/build-system.rst
View File

@ -14,7 +14,7 @@ ESP-IDF v5.0 已不再支持基于 Make 的工程，请参考 :ref:`从 ESP-IDF
明确指定组件依赖
-----------------------------------------
在之前的 ESP-IDF 版本中，除了 :ref:`通用组件依赖项 <component-common-requirements>`，还有一些组件总是作为公共依赖项在构建中被添加至每个组件中，如：
在之前的 ESP-IDF 版本中，除了 :ref:`通用组件依赖项 <component-common-requirements>`，还有一些组件总是作为公共依赖项，在构建时添加至每个组件中，如：
* ``driver``
* ``efuse``
@ -72,7 +72,7 @@ ESP-IDF v5.0 修复了组件的 CMake 变量传播问题。此问题导致本应
更新 CMake 版本
-----------------------
在 ESP-IDF v5.0 中，最低 CMake 版本已更新到 3.16，并且不再支持低于 3.16 的版本。如果您的操作系统没有安装 CMake，请运行 ``tools/idf_tools.py install cmake`` 来安装合适的版本。
在 ESP-IDF v5.0 中，最低 CMake 版本已更新到 3.16，并且不再支持低于 3.16 的版本。如果你的操作系统没有安装 CMake，请运行 ``tools/idf_tools.py install cmake`` 来安装合适的版本。
该变更会影响到使用系统提供的 CMake 以及自定义 CMake 的 ESP-IDF 用户。

5
docs/zh_CN/migration-guides/release-5.x/5.0/gcc.rst
View File

@ -7,7 +7,7 @@ GCC
GCC 版本
========
ESP-IDF 之前使用的 GCC 版本为 8.4.0，现已针对所有芯片目标升级至 GCC 11.2.0。若需要将您的代码从 GCC 8.4.0 迁移到 GCC 11.2.0，请参考以下官方 GCC 迁移指南。
ESP-IDF 之前使用的 GCC 版本为 8.4.0，现已针对所有芯片目标升级至 GCC 11.2.0。若需要将代码从 GCC 8.4.0 迁移到 GCC 11.2.0，请参考以下官方 GCC 迁移指南。
* `迁移至 GCC 9 <https://gcc.gnu.org/gcc-9/porting_to.html>`_
* `迁移至 GCC 10 <https://gcc.gnu.org/gcc-10/porting_to.html>`_
@ -20,6 +20,7 @@ ESP-IDF 之前使用的 GCC 版本为 8.4.0，现已针对所有芯片目标升
升级至 GCC 11.2.0 后会触发新警告，或是导致原有警告内容发生变化。所有 GCC 警告的详细内容，请参考 `GCC 警告选项 <https://gcc.gnu.org/onlinedocs/gcc-11.2.0/gcc/Warning-Options.html>`_。建议用户仔细检查代码，并设法解决这些警告。但由于某些警告的特殊性及用户代码的复杂性，有些警告可能为误报，需要进行关键修复。在这种情况下，用户可以采取多种方式来抑制这些警告。本节介绍了用户可能遇到的常见警告及如何抑制这些警告。
.. 注意::
建议用户在抑制警告之前仔细确认该警告是否确实为误报。
@ -134,6 +135,6 @@ Xtensa 编译器中的 ``int32_t`` 和 ``uint32_t``
移除构建选项 ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS``
----------------------------------------------------------
原有的 ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` 选项用于构建使用现已僵化的 GCC 5 工具链编写的陈旧代码。但由于已经过去较长时间，现在可以对警告进行修复，因此该选项已被移除。
原有的 ``CONFIG_COMPILER_DISABLE_GCC8_WARNINGS`` 选项用于构建使用现已僵化的 GCC 5 工具链编写的陈旧代码。但由于已经过去较长时间，现在可以对警告进行修复，因此该选项已移除。
目前，在 GCC 11 中，建议用户仔细检查代码，尽量解决编译器警告。

32
docs/zh_CN/migration-guides/release-5.x/5.0/networking.rst
View File

@ -6,8 +6,8 @@
Wi-Fi
*****
回调函数类型 esp_now_recv_cb_t
------------------------------
回调函数类型 ``esp_now_recv_cb_t``
----------------------------------
此前 ``esp_now_recv_cb_t`` 的第一个参数的类型是 ``const uint8_t *mac_addr``，该参数只包含对端 ESP-NOW 设备的地址。
@ -26,13 +26,13 @@ Wi-Fi
以太网
**************
esp_eth_ioctl() API
-------------------
``esp_eth_ioctl()`` API
-----------------------
此前，:cpp:func:`esp_eth_ioctl` API 存在以下问题：
- 在某些情况下，第三个参数（数据类型为 ``void /*``）可以接受 ``int``/``bool`` 类型实参（而非指针）作为输入。然而，文档中未描述这些情况。
- 为了将 ``int``/``bool`` 类型实参作为第三个参数传递，实参将被强制转换为 ``void *`` 类型，以防出现如下所示的编译器警告。此等转换可能引起 :cpp:func:`esp_eth_ioctl` 函数的滥用。
- 为了将 ``int``/``bool`` 类型实参作为第三个参数传递，实参将强制转换为 ``void *`` 类型，以防出现如下所示的编译器警告。此等转换可能引起 :cpp:func:`esp_eth_ioctl` 函数的滥用。
.. code-block:: c
@ -68,7 +68,7 @@ KSZ8041/81 和 LAN8720 驱动现已更新，以支持相关产品系列中的更
ESP NETIF Glue 时间处理程序
-----------------------------------
``esp_eth_set_default_handlers()`` 和 ``esp_eth_clear_default_handlers()`` 函数现已删除。现在可以自动处理以太网默认 IP 层处理程序的注册。如您在注册以太网/IP 事件处理程序之前已经按照建议完全初始化以太网驱动和网络接口，则无需执行任何操作（除了删除受影响的函数）。否则，在注册用户事件处理程序后，应随即启动以太网驱动。
``esp_eth_set_default_handlers()`` 和 ``esp_eth_clear_default_handlers()`` 函数现已删除。现在可以自动处理以太网默认 IP 层处理程序的注册。如果在注册以太网/IP 事件处理程序之前，你已经按照建议，完全初始化以太网驱动和网络接口，则无需执行任何操作（除了删除受影响的函数）。否则，在注册用户事件处理程序后，应随即启动以太网驱动。
PHY 地址自动检测
---------------------------
@ -79,9 +79,9 @@ PHY 地址自动检测
SPI 以太网模块初始化
--------------------------------------
SPI 以太网模块的初始化过程已经简化。此前，您需要在实例化 SPI 以太网 MAC 之前，使用 :cpp:func:`spi_bus_add_device` 手动分配 SPI 设备。
SPI 以太网模块的初始化过程已经简化。此前，你需要在实例化 SPI 以太网 MAC 之前，使用 :cpp:func:`spi_bus_add_device` 手动分配 SPI 设备。
现在，由于 SPI 设备已在内部分配，您无需再调用 :cpp:func:`spi_bus_add_device`。:cpp:class:`eth_dm9051_config_t`、:cpp:class:`eth_w5500_config_t` 和 :cpp:class:`eth_ksz8851snl_config_t` 配置结构体现已包含 SPI 设备配置成员（例如，可以微调可能依赖 PCB 设计的 SPI 时序）。``ETH_DM9051_DEFAULT_CONFIG``、``ETH_W5500_DEFAULT_CONFIG`` 和 ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` 配置初始化宏也已接受新的参数输入。了解 SPI 以太网模块初始化示例，请查看 :doc:`以太网 API 参考指南<../../../api-reference/network/esp_eth>`。
现在，SPI 设备已在内部分配，因此无需再调用 :cpp:func:`spi_bus_add_device`。:cpp:class:`eth_dm9051_config_t`、:cpp:class:`eth_w5500_config_t` 和 :cpp:class:`eth_ksz8851snl_config_t` 配置结构体现已包含 SPI 设备配置成员（例如，可以微调可能依赖 PCB 设计的 SPI 时序）。``ETH_DM9051_DEFAULT_CONFIG``、``ETH_W5500_DEFAULT_CONFIG`` 和 ``ETH_KSZ8851SNL_DEFAULT_CONFIG`` 配置初始化宏也已接受新的参数输入。了解 SPI 以太网模块初始化示例，请查看 :doc:`以太网 API 参考指南<../../../api-reference/network/esp_eth>`。
.. _tcpip-adapter:
@ -89,7 +89,7 @@ SPI 以太网模块的初始化过程已经简化。此前，您需要在实例
TCP/IP 适配器
****************
TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。本文档概述了从 tcpip_adapter API 迁移至 :doc:`/api-reference/network/esp_netif` 的过程。
TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。本文档概述了从 ``tcpip_adapter`` API 迁移至 :doc:`/api-reference/network/esp_netif` 的过程。
更新网络连接代码
@ -99,9 +99,9 @@ TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。
网络软件栈初始化
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 您只需用 ``esp_netif_init()`` 替换 ``tcpip_adapter_init()``，注意 ``esp_netif_init()`` 函数现将返回标准错误代码。了解详细信息，请参考 :doc:`/api-reference/network/esp_netif`。
- 你只需用 ``esp_netif_init()`` 替换 ``tcpip_adapter_init()``，注意 ``esp_netif_init()`` 函数现将返回标准错误代码。了解详细信息，请参考 :doc:`/api-reference/network/esp_netif`。
- ``esp_netif_deinit()`` 函数用于反初始化网络软件栈。
- 您还需用 ``#include "esp_netif.h"`` 替换 ``#include "tcpip_adapter.h"``。
- 你还需用 ``#include "esp_netif.h"`` 替换 ``#include "tcpip_adapter.h"``。
创建网络接口
@ -121,10 +121,10 @@ TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。
- Wi-Fi AP：:example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
- 以太网：:example_file:`ethernet/basic/main/ethernet_example_main.c`
其他 tcpip_adapter API 更换
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
其他 ``tcpip_adapter`` API 更换
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
所有 tcpip_adapter 函数都有对应的 esp-netif。请参考以下章节中的 esp_netif.h 部分，了解更多信息：
所有 ``tcpip_adapter`` 函数都有对应的 ``esp-netif``。请参考以下章节中的 ``esp_netif.h`` 部分，了解更多信息：
* :component_file:`Setters/Getters <esp_netif/include/esp_netif.h#L241>`
* :component_file:`DHCP <esp_netif/include/esp_netif.h#L387>`
@ -134,7 +134,7 @@ TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。
默认事件处理程序
^^^^^^^^^^^^^^^^^^^^^^
事件处理程序已从 tcpip_adapter 移至相应驱动程序代码。从应用程序的角度来看，这一变更不会产生任何影响，所有事件仍将以相同的方式处理。请注意，在与 IP 相关的事件处理程序中，应用程序代码通常以 esp-netif 结构体而非 LwIP 结构体的形式接收 IP 地址。两种结构体均兼容二进制格式。
事件处理程序已从 ``tcpip_adapter`` 移至相应驱动程序代码。从应用程序的角度来看，这一变更不会产生任何影响，所有事件仍将以相同的方式处理。请注意，在与 IP 相关的事件处理程序中，应用程序代码通常以 ``esp-netif`` 结构体而非 LwIP 结构体的形式接收 IP 地址。两种结构体均兼容二进制格式。
打印地址的首选方式如下所示：
@ -154,6 +154,6 @@ TCP/IP 适配器是在 ESP-IDF v4.1 之前使用的网络接口抽象组件。
IP 地址
^^^^^^^^^^^^
推荐使用 esp-netif 定义的 IP 结构。请注意，在启用默认兼容性时，LwIP 结构体仍然可以工作。
推荐使用 ``esp-netif`` 定义的 IP 结构。请注意，在启用默认兼容性时，LwIP 结构体仍然可以工作。
* :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`

2
docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst
View File

@ -478,7 +478,7 @@ LCD
更新后，I2S 驱动的最小控制单元是发送/接收通道，而不是整个 I2S 控制器（控制器包括多个通道）。
- 用户可以分别控制同一个 I2S 控制器的发送通道和接收通道，即可以通过配置实现分别开启和关闭发送通道和接收通道。
- :c:type:`i2s_chan_handle_t` 句柄类型用于唯一地识别 I2S 通道。所有的 API 都需要该通道句柄，用户需要对这些通道句柄进行维护。
- :cpp:type:`i2s_chan_handle_t` 句柄类型用于唯一地识别 I2S 通道。所有的 API 都需要该通道句柄，用户需要对这些通道句柄进行维护。
- 对于 ESP32-C3 和 ESP32-S3，同一个控制器中的发送通道和接收通道可以配置为不同的时钟或不同的模式。
- 但是对于 ESP32 和 ESP32-S2， 同一个控制器中的发送通道和接收通道共享某些硬件资源。因此，配置可能会造成一个通道影响同一个控制器中的另一个通道。
- 通过将 :cpp:enumerator:`i2s_port_t::I2S_NUM_AUTO` 设置为 I2S 端口 ID，驱动会搜索可用的发送/接收通道，之后通道会被自动注册到可用的 I2S 控制器上。但是，驱动仍然支持将通道注册到一个特定的端口上。

11
docs/zh_CN/migration-guides/release-5.x/5.0/protocols.rst
View File

@ -37,6 +37,7 @@ SSL
废弃配置选项
^^^^^^^^^^^^^^^^^^^^^^^^^
下列为在此次更新中废弃的重要配置选项。与以下配置有关或是依赖于下列配置的相关配置也已相应废弃。
- ``MBEDTLS_SSL_PROTO_SSL3``：原用于支持 SSL 3.0
@ -46,7 +47,9 @@ SSL
- ``MBEDTLS_DES_C``：原用于支持 3DES 密码套件
- ``MBEDTLS_RC4_MODE``：原用于支持基于 RC4 的密码套件
.. note:: 上述仅列出了可通过 ``idf.py menuconfig`` 配置的主要选项。更多有关废弃选项的信息，请参考 `官方指南 <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md>`__。
.. note::
上述仅列出了可通过 ``idf.py menuconfig`` 配置的主要选项。更多有关废弃选项的信息，请参考 `官方指南 <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md>`__。
其他更新
@ -61,7 +64,9 @@ SSL
- ``MBEDTLS_KEY_EXCHANGE_DHE_PSK``：原用于支持 Diffie-Hellman 预共享密钥 (PSK) TLS 认证模式
- ``MBEDTLS_KEY_EXCHANGE_DHE_RSA``：原用于支持带有前缀的密码套件 ``TLS-DHE-RSA-WITH-``
.. note:: 在信号交换的初始步骤（即 ``client_hello``）中，服务器会在客户端提供的列表中选择一个密码。由于 DHE_PSK/DHE_RSA 密码已在本次更新中禁用，服务器将退回到一个替代密码。在极个别情况中，服务器不支持任何其他的代码，此时，初始步骤将失败。若要检索服务器所支持的密码列表，需要首先在客户端使用特定的密码连接服务器，可以使用 ``sslscan`` 等工具完成连接。
.. note::
在信号交换的初始步骤（即 ``client_hello``）中，服务器会在客户端提供的列表中选择一个密码。由于 DHE_PSK/DHE_RSA 密码已在本次更新中禁用，服务器将退回到一个替代密码。在极个别情况中，服务器不支持任何其他的代码，此时，初始步骤将失败。若要检索服务器所支持的密码列表，需要首先在客户端使用特定的密码连接服务器，可以使用 ``sslscan`` 等工具完成连接。
从 X509 库中移除 ``certs`` 模块
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -118,10 +123,12 @@ ESP-TLS
下列为新增的 getter/setter 函数：
.. list::
* :cpp:func:`esp_tls_get_ssl_context`：从 ESP-TLS 句柄获取底层 ssl 栈的 ssl 上下文。
废弃函数及推荐的替代函数
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
下表总结了在 ESP-IDF v5.0 中废弃的函数以及相应的替代函数。
.. list-table::

15
docs/zh_CN/migration-guides/release-5.x/5.0/removed-components.rst
View File

@ -3,10 +3,10 @@
:link_to_translation:`en:[English]`
移至 IDF Component Registry 的组件
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
移至 ESP-IDF Component Registry 的组件
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
以下组件已经从 ESP-IDF 中迁出至 `IDF Component Registry <https://components.espressif.com/>`_：
以下组件已经从 ESP-IDF 中迁出至 `ESP-IDF Component Registry <https://components.espressif.com/>`_：
* `libsodium <https://components.espressif.com/component/espressif/libsodium>`_
* `cbor <https://components.espressif.com/component/espressif/cbor>`_
@ -27,6 +27,7 @@
* `tinyusb <https://components.espressif.com/components/espressif/esp_tinyusb>`_
.. note::
请注意，http 解析功能以前属于 ``nghttp`` 组件一部分，但现在属于 :component:`http_parser <http_parser>` 组件。
可使用 ``idf.py add-dependency`` 命令安装以上组件。
@ -40,15 +41,17 @@
弃用的组件
^^^^^^^^^^^^^^^^^^^^^
IDF v4.x 版本中已不再使用以下组件，这些组件已弃用：
ESP-IDF v4.x 版本中已不再使用以下组件，这些组件已弃用：
* ``tcpip_adapter``。可使用 :doc:`ESP-NETIF </api-reference/network/esp_netif>` 组件代替，具体可参考 :ref:`tcpip-adapter`。
.. note::
不再支持 OpenSSL-API 组件。IDF Component Registry 中也没有该组件。请直接使用 :doc:`ESP-TLS </api-reference/protocols/esp_tls>` 或 :component:`mbedtls` API。
不再支持 OpenSSL-API 组件。ESP-IDF Component Registry 中也没有该组件。请直接使用 :doc:`ESP-TLS </api-reference/protocols/esp_tls>` 或 :component:`mbedtls` API。
.. note::
不再支持 esp_adc_cal 组件。 新的 adc 校准驱动在 esp_adc 组件中。旧版 adc 校准驱动已被迁移进 esp_adc 组件中。 要使用旧版 esp_adc_cal 驱动接口，你应该在 CMakeLists.txt 文件的组件依赖列表中增加 esp_adc 。更多细节请查看 :doc:`Peripherals Migration Guide </migration-guides/release-5.x/5.0/peripherals>`。
不再支持 ``esp_adc_cal`` 组件。 新的 adc 校准驱动在 ``esp_adc`` 组件中。旧版 adc 校准驱动已被迁移进 ``esp_adc`` 组件中。 要使用旧版 ``esp_adc_cal`` 驱动接口，你应该在 CMakeLists.txt 文件的组件依赖列表中增加 esp_adc 。更多细节请查看 :doc:`Peripherals Migration Guide </migration-guides/release-5.x/5.0/peripherals>`。
版本更新后无需目标组件，因此以下目标组件也已经从 ESP-IDF 中删除：

14
docs/zh_CN/migration-guides/release-5.x/5.0/storage.rst
View File

@ -26,7 +26,7 @@
请根据项目的实际情况，更新相应的 ``REQUIRES`` 或是 ``PRIV_REQUIRES`` 部分。上述代码片段仅为范例。
如果问题仍未解决，请联系我们，我们将协助您进行代码迁移。
如果问题仍未解决，请联系我们，我们将协助你进行代码迁移。
SDMMC/SDSPI
@ -58,7 +58,7 @@ VFS
函数签名更改
^^^^^^^^^^^^^^^^^^^^^^^^^^
以下函数现将返回 ``esp_err_t``，而非 ``void`` 或 ``nvs_iterator_t``。此前，当参数无效或内部出现问题时，这些函数将 ``assert()`` 或返回 ``nullptr``。通过返回 ``esp_err_t``，您将获得更加实用的错误报告。
以下函数现将返回 ``esp_err_t``，而非 ``void`` 或 ``nvs_iterator_t``。此前，当参数无效或内部出现问题时，这些函数将 ``assert()`` 或返回 ``nullptr``。通过返回 ``esp_err_t``，你将获得更加实用的错误报告。
- :cpp:func:`nvs_entry_find`
- :cpp:func:`nvs_entry_next`
@ -108,9 +108,9 @@ ROM SPI flash
在 v5.0 之前的版本中，ROM SPI flash 函数一般通过 ``esp32**/rom/spi_flash.h`` 得以体现。因此，为支持不同 ESP 芯片而编写的代码可能会填充不同目标的 ROM 头文件。此外，并非所有 API 都可以在全部的 ESP 芯片上使用。
现在，常用 API 被提取至 ``esp_rom_spiflash.h``。尽管这不能算作重大变更，我们强烈建议您仅使用此头文件中的函数（即以 ``esp_rom_spiflash`` 为前缀并包含在 ``esp_rom_spiflash.h`` 中），以获得不同 ESP 芯片之间更佳的交叉兼容性。
现在，常用 API 已提取至 ``esp_rom_spiflash.h``。尽管这不能算作重大变更，我们强烈建议仅使用此头文件中的函数（即以 ``esp_rom_spiflash`` 为前缀并包含在 ``esp_rom_spiflash.h`` 中），以获得不同 ESP 芯片之间更佳的交叉兼容性。
为了提高 ROM SPI flash API 的可读性，以下函数也被重命名：
为了提高 ROM SPI flash API 的可读性，以下函数也进行了重命名：
- ``esp_rom_spiflash_lock()`` 更名为 ``esp_rom_spiflash_set_bp()``
- ``esp_rom_spiflash_unlock()`` 更名为 ``esp_rom_spiflash_clear_bp()``
@ -118,7 +118,7 @@ ROM SPI flash
SPI flash 驱动
^^^^^^^^^^^^^^^^^^^^^^
``esp_flash_speed_t`` ``enum`` 类型现已弃用。现在，您可以直接将实际时钟频率值传递给 flash 配置结构。下为配置 80MHz flash 频率的示例：
``esp_flash_speed_t`` ``enum`` 类型现已弃用。现在，可以直接将实际时钟频率值传递给 flash 配置结构。下为配置 80 MHz flash 频率的示例：
.. code-block:: c
@ -131,7 +131,7 @@ SPI flash 驱动
旧版 SPI flash 驱动
^^^^^^^^^^^^^^^^^^^^^^^
为了使 SPI flash 驱动更为稳定，v5.0 已经删除旧版 SPI flash 驱动。旧版 SPI flash 驱动程序是指自 v3.0 以来的默认 SPI flash 驱动程序，以及自 v4.0 以来启用配置选项 ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` 的 SPI flash 驱动。从 v5.0 开始，我们将不再支持旧版 SPI flash 驱动程序。因此，旧版驱动 API 和 ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` 配置选项均被删除，请改用新 SPI flash 驱动的 API。
为了使 SPI flash 驱动更为稳定，v5.0 已经删除旧版 SPI flash 驱动。旧版 SPI flash 驱动程序是指自 v3.0 以来的默认 SPI flash 驱动程序，以及自 v4.0 以来启用配置选项 ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` 的 SPI flash 驱动。从 v5.0 开始，我们将不再支持旧版 SPI flash 驱动程序。因此，旧版驱动 API 和 ``CONFIG_SPI_FLASH_USE_LEGACY_IMPL`` 配置选项均已删除，请改用新 SPI flash 驱动的 API。
.. list-table::
:widths: 50 50
@ -154,6 +154,6 @@ SPI flash 驱动
.. note::
带有前缀 ``esp_flash`` 的新函数接受额外的 ``esp_flash_t*`` 参数。您可以直接将其设置为 NULL，从而使函数运行主 flash (``esp_flash_default_chip``)。
带有前缀 ``esp_flash`` 的新函数接受额外的 ``esp_flash_t*`` 参数。你可以直接将其设置为 NULL，从而使函数运行主 flash (``esp_flash_default_chip``)。
由于系统函数不再是公共函数， ``esp_spi_flash.h`` 头文件已停止使用。若要使用 flash 映射 API，请使用 ``spi_flash_mmap.h``。

100
docs/zh_CN/migration-guides/release-5.x/5.0/system.rst
View File

@ -1,19 +1,19 @@
系统
======
:link_to_translation:`en:[英文]`
:link_to_translation:`en:[English]`
跨核执行
----------
跨核执行 (Inter-Processor Call, IPC) 不再是一个独立组件，现已被包含至 ``esp_system``。
跨核执行 (Inter-Processor Call, IPC) 不再是一个独立组件，现已包含至 ``esp_system``。
因此，若项目的 ``CMakeLists.txt`` 文件中出现 ``PRIV_REQUIRES esp_ipc`` 或 ``REQUIRES esp_ipc``，应删除这些选项，因为项目中已默认包含 ``esp_system`` 组件。
ESP 时钟
---------
ESP 时钟 API（即以 ``esp_clk`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "{IDF_TARGET_NAME}/clk.h"`` 和 ``#include "esp_clk.h"`` 已被移除。如仍需使用 ESP 时钟 API（并不推荐），请使用 ``#include "esp_private/esp_clk.h"`` 来包含。
ESP 时钟 API（即以 ``esp_clk`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "{IDF_TARGET_NAME}/clk.h"`` 和 ``#include "esp_clk.h"`` 已移除。如仍需使用 ESP 时钟 API（并不推荐），请使用 ``#include "esp_private/esp_clk.h"`` 来包含。
.. 注意::
@ -22,90 +22,92 @@ ESP 时钟 API（即以 ``esp_clk`` 为前缀的函数、类型或宏）已被
缓存错误中断
--------------
缓存错误中断 API（即以 ``esp_cache_err`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "{IDF_TARGET_NAME}/cache_err_int.h"`` 已被移除。如仍需使用缓存错误中断 API（并不推荐），请使用 ``#include "esp_private/cache_err_int.h"`` 来包含。
缓存错误中断 API（即以 ``esp_cache_err`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "{IDF_TARGET_NAME}/cache_err_int.h"`` 已移除。如仍需使用缓存错误中断 API（并不推荐），请使用 ``#include "esp_private/cache_err_int.h"`` 来包含。
bootloader_support
--------------------
``bootloader_support``
------------------------
* 函数 ``bootloader_common_get_reset_reason()`` 已被移除。请使用 ROM 组件中的函数 ``esp_rom_get_reset_reason()``。
* 函数 ``esp_secure_boot_verify_sbv2_signature_block()`` 和 ``esp_secure_boot_verify_rsa_signature_block()`` 已被移除，无新的替换函数。不推荐用户直接使用以上函数。如确需要，请在 `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ 上对该功能提交请求，并解释您需要此函数的原因。
* 函数 ``bootloader_common_get_reset_reason()`` 已移除。请使用 ROM 组件中的函数 ``esp_rom_get_reset_reason()``。
* 函数 ``esp_secure_boot_verify_sbv2_signature_block()`` 和 ``esp_secure_boot_verify_rsa_signature_block()`` 已移除，无新的替换函数。不推荐用户直接使用以上函数。如确需要，请在 `GitHub <https://github.com/espressif/esp-idf/issues/new/choose>`_ 上对该功能提交请求，并解释需要此函数的原因。
断电
--------
断电 API（即以 ``esp_brownout`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "brownout.h"`` 已被移除。如仍需使用断电 API（并不推荐），请使用 ``#include "esp_private/brownout.h"`` 来包含。
断电 API（即以 ``esp_brownout`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "brownout.h"`` 已移除。如仍需使用断电 API（并不推荐），请使用 ``#include "esp_private/brownout.h"`` 来包含。
Trax
----
Trax API（即以 ``trax_`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "trax.h"`` 已被移除。如仍需使用 Trax API（并不推荐），请使用 ``#include "esp_private/trax.h"`` 来包含。
Trax API（即以 ``trax_`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "trax.h"`` 已移除。如仍需使用 Trax API（并不推荐），请使用 ``#include "esp_private/trax.h"`` 来包含。
ROM
---
``components/esp32/rom/`` 路径下存放的已弃用的 ROM 相关头文件已被移除（原包含路径为 ``rom/*.h``）。请使用新的特定目标的路径 ``components/esp_rom/include/{IDF_TARGET_NAME}/``（新的包含路径为 ``{IDF_TARGET_NAME}/rom/*.h``）。
``components/esp32/rom/`` 路径下存放的已弃用的 ROM 相关头文件已移除（原包含路径为 ``rom/*.h``）。请使用新的特定目标的路径 ``components/esp_rom/include/{IDF_TARGET_NAME}/``（新的包含路径为 ``{IDF_TARGET_NAME}/rom/*.h``）。
esp_hw_support
-----------------
``esp_hw_support``
---------------------
- 头文件 ``soc/cpu.h`` 及弃用的 CPU util 函数都已被移除。请包含 ``esp_cpu.h`` 来代替相同功能的函数。
- 头文件 ``soc/cpu.h`` 及弃用的 CPU util 函数都已移除。请包含 ``esp_cpu.h`` 来代替相同功能的函数。
- 头文件 ``hal/cpu_ll.h``、``hal/cpu_hal.h``、``hal/soc_ll.h``、``hal/soc_hal.h`` 和 ``interrupt_controller_hal.h`` 的 CPU API 函数已弃用。请包含 ``esp_cpu.h`` 来代替相同功能的函数。
- 头文件 ``compare_set.h`` 已被移除。请使用 ``esp_cpu.h`` 中提供的 ``esp_cpu_compare_and_set()`` 函数来代替。
- 头文件 ``compare_set.h`` 已移除。请使用 ``esp_cpu.h`` 中提供的 ``esp_cpu_compare_and_set()`` 函数来代替。
- ``esp_cpu_get_ccount()``、``esp_cpu_set_ccount()`` 和 ``esp_cpu_in_ocd_debug_mode()`` 已从 ``esp_cpu.h`` 中移除。请分别使用 ``esp_cpu_get_cycle_count()``、``esp_cpu_set_cycle_count()`` 和 ``esp_cpu_dbgr_is_attached()`` 代替。
- 头文件 ``esp_intr.h`` 已被移除。请包含 ``esp_intr_alloc.h`` 以分配和操作中断。
- Panic API（即以 ``esp_panic`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "esp_panic.h"`` 已被移除。如仍需使用 Panic API（并不推荐），请使用 ``#include "esp_private/panic_reason.h"`` 来包含。此外，请包含 ``esp_debug_helpers.h`` 以使用与调试有关的任意辅助函数，如打印回溯。
- 头文件 ``esp_intr.h`` 已移除。请包含 ``esp_intr_alloc.h`` 以分配和操作中断。
- Panic API（即以 ``esp_panic`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "esp_panic.h"`` 已移除。如仍需使用 Panic API（并不推荐），请使用 ``#include "esp_private/panic_reason.h"`` 来包含。此外，请包含 ``esp_debug_helpers.h`` 以使用与调试有关的任意辅助函数，如打印回溯。
- 头文件 ``soc_log.h`` 现更名为 ``esp_hw_log.h``，并已更新为私有。建议用户使用 ``esp_log.h`` 头文件下的日志 API。
- 包含头文件 ``spinlock.h``、``clk_ctrl_os.h`` 和 ``rtc_wdt.h`` 时不应当使用 ``soc`` 前缀，如 ``#include "spinlock.h"``。
- ``esp_chip_info()`` 命令返回芯片版本，格式为 = 100 * ``主要 eFuse 版本`` + ``次要 eFuse 版本``。因此，为适应新格式， ``esp_chip_info_t`` 结构体中的 ``revision`` 被扩展为 uint16_t。
- ``esp_chip_info()`` 命令返回芯片版本，格式为 = 100 * ``主要 eFuse 版本`` + ``次要 eFuse 版本``。因此，为适应新格式， ``esp_chip_info_t`` 结构体中的 ``revision`` 扩展为 ``uint16_t``。
PSRAM
^^^^^
- 针对特定目标的头文件 ``spiram.h`` 及头文件 ``esp_spiram.h`` 已被移除，创建新组件 ``esp_psram``。对于与 PSRAM 或 SPIRAM 相关的函数，请包含 ``esp_psram.h``，并在 CMakeLists.txt 项目文件中将 ``esp_psram`` 设置为必需组件。
- ``esp_spiram_get_chip_size`` 和 ``esp_spiram_get_size`` 已被移除，请使用 ``esp_psram_get_size``。
- 针对特定目标的头文件 ``spiram.h`` 及头文件 ``esp_spiram.h`` 已移除，创建新组件 ``esp_psram``。对于与 PSRAM 或 SPIRAM 相关的函数，请包含 ``esp_psram.h``，并在 CMakeLists.txt 项目文件中将 ``esp_psram`` 设置为必需组件。
- ``esp_spiram_get_chip_size`` 和 ``esp_spiram_get_size`` 已移除，请使用 ``esp_psram_get_size``。
eFuse
-------
- 函数 ``esp_secure_boot_read_key_digests()`` 的参数类型从 ``ets_secure_boot_key_digests_t*`` 更新为 ``esp_secure_boot_key_digests_t*``。新类型与旧类型相同，仅移除了 ``allow_key_revoke`` 标志。在当前代码中，后者总是被设置为 ``true``，并未提供额外信息。
- 针对 eFuse 晶圆增加主要修订版本和次要修订版本。API ``esp_efuse_get_chip_ver()`` 与新修订不兼容，因此已被移除。请使用 API ``efuse_hal_get_major_chip_version()``、``efuse_hal_get_minor_chip_version()`` 或 ``efuse_hal_chip_revision()`` 来代替原有 API。
- 函数 ``esp_secure_boot_read_key_digests()`` 的参数类型从 ``ets_secure_boot_key_digests_t*`` 更新为 ``esp_secure_boot_key_digests_t*``。新类型与旧类型相同，仅移除了 ``allow_key_revoke`` 标志。在当前代码中，后者总是设置为 ``true``，并未提供额外信息。
- 针对 eFuse 晶圆增加主要修订版本和次要修订版本。API ``esp_efuse_get_chip_ver()`` 与新修订不兼容，因此已移除。请使用 API ``efuse_hal_get_major_chip_version()``、``efuse_hal_get_minor_chip_version()`` 或 ``efuse_hal_chip_revision()`` 来代替原有 API。
esp_common
------------
``EXT_RAM_ATTR`` 已被弃用。请使用新的宏 ``EXT_RAM_BSS_ATTR`` 以将 .bss 放在 PSRAM 上。
``esp_common``
----------------
``EXT_RAM_ATTR`` 已弃用。请使用新的宏 ``EXT_RAM_BSS_ATTR`` 以将 ``.bss`` 放在 PSRAM 上。
``esp_system``
----------------
esp_system
------------
- 头文件 ``esp_random.h``、``esp_mac.h`` 和 ``esp_chip_info.h`` 以往都是通过头文件 ``esp_system.h`` 间接包含，更新后必须直接包含。已移除从 ``esp_system.h`` 中的间接包含功能。
- 回溯解析器 API（即以 ``esp_eh_frame_`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "eh_frame_parser.h"`` 已被移除。如仍需使用回溯解析器 API（并不推荐），请使用 ``#include "esp_private/eh_frame_parser.h"`` 来包含。
- 中断看门狗定时器 API（即以 ``esp_int_wdt_`` 为前缀的函数、类型或宏）已被更新为私有 API。因此，原先的包含路径 ``#include "esp_int_wdt.h"`` 已被移除。如仍需使用中断看门狗定时器 API（并不推荐），请使用 ``#include "esp_private/esp_int_wdt.h"`` 来包含。
- 回溯解析器 API（即以 ``esp_eh_frame_`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "eh_frame_parser.h"`` 已移除。如仍需使用回溯解析器 API（并不推荐），请使用 ``#include "esp_private/eh_frame_parser.h"`` 来包含。
- 中断看门狗定时器 API（即以 ``esp_int_wdt_`` 为前缀的函数、类型或宏）已更新为私有 API。因此，原先的包含路径 ``#include "esp_int_wdt.h"`` 已移除。如仍需使用中断看门狗定时器 API（并不推荐），请使用 ``#include "esp_private/esp_int_wdt.h"`` 来包含。
SOC 依赖性
--------------
- Doxyfiles 中列出的公共 API 头文件中不会显示不稳定和非必要的 SOC 头文件，如 ``soc/soc.h`` 和 ``soc/rtc.h``。这意味着，如果用户仍然需要这些“缺失”的头文件，就必须在代码中明确包含这些文件。
- Kconfig 选项 ``LEGACY_INCLUDE_COMMON_HEADERS`` 也已被移除。
- 头文件 ``soc/soc_memory_types.h`` 已被弃用。请使用 ``esp_memory_utils.h``。包含 ``soc/soc_memory_types.h`` 将触发构建警告，如 ``soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h``。
- Kconfig 选项 ``LEGACY_INCLUDE_COMMON_HEADERS`` 也已移除。
- 头文件 ``soc/soc_memory_types.h`` 已弃用。请使用 ``esp_memory_utils.h``。包含 ``soc/soc_memory_types.h`` 将触发构建警告，如 ``soc_memory_types.h is deprecated, please migrate to esp_memory_utils.h``。
应用跟踪
--------
其中一个时间戳源已从定时器组驱动改为新的 :doc:`GPTimer <../../../api-reference/peripherals/gptimer>`。Kconfig 选项已重新命名，例如 ``APPTRACE_SV_TS_SOURCE_TIMER00`` 已更改为 ``APPTRACE_SV_TS_SOURCE_GPTIMER``。用户已无需选择组和定时器 ID。
esp_timer
-----------
``esp_timer``
---------------
基于 FRC2 的 esp_timer 过去可用于 ESP32，现在已被移除，更新后仅可使用更简单有效的 LAC 定时器。
基于 FRC2 的 ``esp_timer`` 过去可用于 ESP32，现在已移除，更新后仅可使用更简单有效的 LAC 定时器。
ESP 镜像
---------
ESP 镜像中关于 SPI 速度的枚举成员已重新更名：
- ``ESP_IMAGE_SPI_SPEED_80M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_1``。
- ``ESP_IMAGE_SPI_SPEED_40M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_2``。
- ``ESP_IMAGE_SPI_SPEED_26M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_3``。
- ``ESP_IMAGE_SPI_SPEED_20M`` 已被重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_4``。
- ``ESP_IMAGE_SPI_SPEED_80M`` 已重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_1``。
- ``ESP_IMAGE_SPI_SPEED_40M`` 已重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_2``。
- ``ESP_IMAGE_SPI_SPEED_26M`` 已重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_3``。
- ``ESP_IMAGE_SPI_SPEED_20M`` 已重新命名为 ``ESP_IMAGE_SPI_SPEED_DIV_4``。
任务看门狗定时器
--------------------
@ -115,7 +117,7 @@ ESP 镜像中关于 SPI 速度的枚举成员已重新更名：
- 以结构体的形式传递配置。
- 可将该函数配置为订阅空闲任务。
- 原先的配置选项 ``CONFIG_ESP_TASK_WDT`` 被重新命名为 :ref:`CONFIG_ESP_TASK_WDT_INIT` 并引入了一个新选项 :ref:`CONFIG_ESP_TASK_WDT_EN`。
- 原先的配置选项 ``CONFIG_ESP_TASK_WDT`` 重新命名为 :ref:`CONFIG_ESP_TASK_WDT_INIT` 并引入了一个新选项 :ref:`CONFIG_ESP_TASK_WDT_EN`。
FreeRTOS
--------
@ -138,24 +140,24 @@ FreeRTOS
FreeRTOS 断言
^^^^^^^^^^^^^^^^
在以往版本中，FreeRTOS 断言通过 ``FREERTOS_ASSERT`` kconfig 选项独立配置，不同于系统的其他部分。该选项已被移除，现在需要通过 ``COMPILER_OPTIMIZATION_ASSERTION_LEVEL`` 来完成配置。
在以往版本中，FreeRTOS 断言通过 ``FREERTOS_ASSERT`` kconfig 选项独立配置，不同于系统的其他部分。该选项已移除，现在需要通过 ``COMPILER_OPTIMIZATION_ASSERTION_LEVEL`` 来完成配置。
FreeRTOS 移植相关的宏
^^^^^^^^^^^^^^^^^^^^^^^^^^
已移除用以保证弃用 API 向后兼容性的 ``portmacro_deprecated.h`` 文件。建议使用下列函数来代替弃用 API。
- ``portENTER_CRITICAL_NESTED()`` 已被移除，请使用 ``portSET_INTERRUPT_MASK_FROM_ISR()`` 宏。
- ``portEXIT_CRITICAL_NESTED()`` 已被移除，请使用 ``portCLEAR_INTERRUPT_MASK_FROM_ISR()`` 宏。
- ``vPortCPUInitializeMutex()`` 已被移除，请使用 ``spinlock_initialize()`` 函数。
- ``vPortCPUAcquireMutex()`` 已被移除，请使用 ``spinlock_acquire()`` 函数。
- ``vPortCPUAcquireMutexTimeout()`` 已被移除，请使用 ``spinlock_acquire()`` 函数。
- ``vPortCPUReleaseMutex()`` 已被移除，请使用 ``spinlock_release()`` 函数。
- ``portENTER_CRITICAL_NESTED()`` 已移除，请使用 ``portSET_INTERRUPT_MASK_FROM_ISR()`` 宏。
- ``portEXIT_CRITICAL_NESTED()`` 已移除，请使用 ``portCLEAR_INTERRUPT_MASK_FROM_ISR()`` 宏。
- ``vPortCPUInitializeMutex()`` 已移除，请使用 ``spinlock_initialize()`` 函数。
- ``vPortCPUAcquireMutex()`` 已移除，请使用 ``spinlock_acquire()`` 函数。
- ``vPortCPUAcquireMutexTimeout()`` 已移除，请使用 ``spinlock_acquire()`` 函数。
- ``vPortCPUReleaseMutex()`` 已移除，请使用 ``spinlock_release()`` 函数。
应用程序更新
------------
- 函数 :cpp:func:`esp_ota_get_app_description` 和 :cpp:func:`esp_ota_get_app_elf_sha256` 已被弃用，请分别使用 :cpp:func:`esp_app_get_description` 和 :cpp:func:`esp_app_get_elf_sha256` 函数来代替。这些函数已被移至新组件 :component:`esp_app_format`。请参考头文件 :component_file:`esp_app_desc.h <esp_app_format/include/esp_app_desc.h>`。
- 函数 :cpp:func:`esp_ota_get_app_description` 和 :cpp:func:`esp_ota_get_app_elf_sha256` 已弃用，请分别使用 :cpp:func:`esp_app_get_description` 和 :cpp:func:`esp_app_get_elf_sha256` 函数来代替。这些函数已移至新组件 :component:`esp_app_format`。请参考头文件 :component_file:`esp_app_desc.h <esp_app_format/include/esp_app_desc.h>`。
引导加载程序支持
----------------
@ -167,6 +169,6 @@ FreeRTOS 移植相关的宏
芯片版本
^^^^^^^^^^^^^
在应用程序开始加载时，引导加载程序会检查芯片版本。只有当版本为 ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 和 `<` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL`` 时，应用程序才能成功加载。
在应用程序开始加载时，引导加载程序会检查芯片版本。只有当版本为 ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 和 ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL`` 时，应用程序才能成功加载。
在 OTA 升级时，会检查应用程序头部中的版本需求和芯片版本是否符合条件。只有当版本为 ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 和 `<` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL`` 时，应用程序才能成功更新。
在 OTA 升级时，会检查应用程序头部中的版本需求和芯片版本是否符合条件。只有当版本为 ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` 和 ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL`` 时，应用程序才能成功更新。

10
docs/zh_CN/migration-guides/release-5.x/5.0/tools.rst
View File

@ -3,12 +3,12 @@
:link_to_translation:`en:[English]`
IDF 监视器
-----------
ESP-IDF 监视器
---------------
IDF 监视器在波特率方面的改动如下：
ESP-IDF 监视器在波特率方面的改动如下：
- 目前，IDF 监视器默认遵循自定义的控制台波特率 (:ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`)，而非 115200。
- 目前，ESP-IDF 监视器默认遵循自定义的控制台波特率 (:ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`)，而非 115200。
- ESP-IDF v5.0 不再支持通过 menuconfig 自定义波特率。
- 支持通过设置环境变量或在命令行中使用 ``idf.py monitor -b <baud>`` 命令自定义波特率。
- 注意，为了与全局波特率 ``idf.py -b <baud>`` 保持一致，波特率参数已从 ``-B`` 改名为 ``-b``。请运行 ``idf.py monitor --help`` 获取更多信息。
@ -46,7 +46,7 @@ ESP-IDF v5.0 已将 ``idf.py`` 子命令和 ``cmake`` 目标名中的下划线 (
Esptool
-------
CONFIG_ESPTOOLPY_FLASHSIZE_DETECT 选项已重命名为 :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE`，且默认禁用。迁移到 ESP-IDF v5.0 的新项目和现有项目必须设置 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`。若因编译时 flash 大小未知而无法设置，可启用 :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE`。但需注意的是，启用该项后，为在烧录期间使用 flash 大小更新二进制头时不会导致摘要无效，映像后将不再附加 SHA256 摘要。
``CONFIG_ESPTOOLPY_FLASHSIZE_DETECT`` 选项已重命名为 :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE`，且默认禁用。迁移到 ESP-IDF v5.0 的新项目和现有项目必须设置 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`。若因编译时 flash 大小未知而无法设置，可启用 :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE`。但需注意的是，启用该项后，为在烧录期间使用 flash 大小更新二进制头时不会导致摘要无效，映像后将不再附加 SHA256 摘要。
Windows 环境
-------------

10
docs/zh_CN/migration-guides/release-5.x/5.1/gcc.rst
View File

@ -7,7 +7,7 @@ GCC
GCC 版本
========
ESP-IDF 之前使用的 GCC 版本为 11.2.0，现已针对所有芯片目标升级至 GCC 12.2.0。若您需要将代码从 GCC 11.2.0 迁移到 GCC 12.2.0，请参考以下 GCC 官方迁移指南。
ESP-IDF 之前使用的 GCC 版本为 11.2.0，现已针对所有芯片目标升级至 GCC 12.2.0。若需要将代码从 GCC 11.2.0 迁移到 GCC 12.2.0，请参考以下 GCC 官方迁移指南。
* `迁移至 GCC 12 <https://gcc.gnu.org/gcc-12/porting_to.html>`_
@ -21,7 +21,7 @@ ESP-IDF 之前使用的 GCC 版本为 11.2.0，现已针对所有芯片目标升
``-Wuse-after-free``
--------------------
一般而言，此警告不会针对发布版本的代码产生误报，但是这种情况可能出现在测试用例中。以下示例为如何在 IDF 的 test_realloc.c 中修复该警告。
一般而言，此警告不会针对发布版本的代码产生误报，但是这种情况可能出现在测试用例中。以下示例为如何在 ESP-IDF 的 test_realloc.c 中修复该警告。
.. code-block:: c
@ -61,10 +61,10 @@ GCC 12.2.0 引入了增强版 ``-Waddress`` 警告选项，该选项对 if 语
memset(array, 0xff, sizeof(array));
在 IDF 框架之外构建 RISC-V
============================
在 ESP-IDF 框架之外构建 RISC-V
================================
RISC-V 的 ``zicsr`` 和 ``zifencei`` 扩展现已独立于 ``I`` 扩展，这一变化在 GCC 12 中也有所体现。因此，在 IDF 框架之外构建 RISC-V ESP32 芯片时，请在构建系统中指定 -march 选项时添加 ``_zicsr_zifencei`` 后缀。示例如下。
RISC-V 的 ``zicsr`` 和 ``zifencei`` 扩展现已独立于 ``I`` 扩展，这一变化在 GCC 12 中也有所体现。因此，在 ESP-IDF 框架之外构建 RISC-V ESP32 芯片时，请在构建系统中指定 -march 选项时添加 ``_zicsr_zifencei`` 后缀。示例如下。
原为：

8
docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst
View File

@ -6,11 +6,11 @@
FatFs
-----
``esp_vfs_fat_sdmmc_unmount()`` 已被弃用，可以使用 :cpp:func:`esp_vfs_fat_sdcard_unmount()` 代替。此接口在更早的 ESP-IDF 版本中已被弃用，但是尚未添加弃用警告。自 ESP-IDF v5.1 起，调用这个 ``esp_vfs_fat_sdmmc_unmount()`` 接口将会产生弃用警告。
``esp_vfs_fat_sdmmc_unmount()`` 已弃用，可以使用 :cpp:func:`esp_vfs_fat_sdcard_unmount()` 代替。此接口在更早的 ESP-IDF 版本中已弃用，但是尚未添加弃用警告。自 ESP-IDF v5.1 起，调用 ``esp_vfs_fat_sdmmc_unmount()`` 接口将会产生弃用警告。
SPI_FLASH
---------
- :cpp:func:`spi_flash_get_counters` 已被弃用，请使用 :cpp:func:`esp_flash_get_counters` 代替。
- :cpp:func:`spi_flash_dump_counters` 已被弃用，请使用 :cpp:func:`esp_flash_dump_counters` 代替。
- :cpp:func:`spi_flash_reset_counters` 已被弃用，请使用 :cpp:func:`esp_flash_reset_counters` 代替。
- :cpp:func:`spi_flash_get_counters` 已弃用，请使用 :cpp:func:`esp_flash_get_counters` 代替。
- :cpp:func:`spi_flash_dump_counters` 已弃用，请使用 :cpp:func:`esp_flash_dump_counters` 代替。
- :cpp:func:`spi_flash_reset_counters` 已弃用，请使用 :cpp:func:`esp_flash_reset_counters` 代替。

6
docs/zh_CN/migration-guides/release-5.x/5.1/system.rst
View File

@ -1,7 +1,7 @@
系统
======
:link_to_translation:`en:[英文]`
:link_to_translation:`en:[English]`
FreeRTOS
--------
@ -33,5 +33,5 @@ FreeRTOS
电源管理
----------
* ``esp_pm_config_esp32xx_t`` 已被弃用，应使用 ``esp_pm_config_t`` 替代。
* ``esp32xx/pm.h`` 已被弃用，应使用 ``esp_pm.h`` 替代。
* ``esp_pm_config_esp32xx_t`` 已弃用，应使用 ``esp_pm_config_t`` 替代。
* ``esp32xx/pm.h`` 已弃用，应使用 ``esp_pm.h`` 替代。

9
docs/zh_CN/resources.rst
View File

@ -1,6 +1,7 @@
****
资源
****
:link_to_translation:`en:[English]`
.. toctree::
@ -13,17 +14,17 @@
有用的链接
##########
* 您可以在 `ESP32 论坛 <https://esp32.com/>`_ 中提出您的问题，访问社区资源。
* 请在 `ESP32 论坛 <https://esp32.com/>`_ 中提出问题，访问社区资源。
* 您可以通过 GitHub 的 `Issues <https://github.com/espressif/esp-idf/issues>`_ 版块提交 bug 或功能请求。在提交新 Issue 之前，请先查看现有的 `Issues <https://github.com/espressif/esp-idf/issues>`_。
* 请通过 GitHub 的 `Issues <https://github.com/espressif/esp-idf/issues>`_ 版块提交 bug 或功能请求。在提交新 Issue 之前，请先查看现有的 `Issues <https://github.com/espressif/esp-idf/issues>`_。
* 您可以在 `ESP IoT Solution <https://github.com/espressif/esp-iot-solution>`_ 库中找到基于 ESP-IDF 的 `解决方案 <https://github.com/espressif/esp-iot-solution#solutions>`_、`应用实例 <https://github.com/espressif/esp-iot-solution#esp32-iot-example-list>`_、`组件和驱动 <https://github.com/espressif/esp-iot-solution#components>`_ 等内容。多数文档均提供中英文版本。
* 请在 `ESP IoT Solution <https://github.com/espressif/esp-iot-solution>`_ 库中找到基于 ESP-IDF 的 `解决方案 <https://github.com/espressif/esp-iot-solution#solutions>`_、`应用实例 <https://github.com/espressif/esp-iot-solution#esp32-iot-example-list>`_、`组件和驱动 <https://github.com/espressif/esp-iot-solution#components>`_ 等内容。多数文档均提供中英文版本。
* 通过 Arduino 平台开发应用，请参考 `ESP32、ESP32-S2 和 ESP32-C3 芯片的 Arduino 内核 <https://github.com/espressif/arduino-esp32#readme>`_。
* 关于 ESP32 的书籍列表，请查看 `乐鑫 <https://www.espressif.com/zh-hans/support/iot-college/books-new>`_ 网站。
* 如果您有兴趣参与到 ESP-IDF 的开发, 请查阅 :doc:`contribute/index`。
* 如果你有兴趣参与到 ESP-IDF 的开发, 请查阅 :doc:`contribute/index`。
* 关于 {IDF_TARGET_NAME} 的其它信息，请查看官网 `文档 <https://espressif.com/zh-hans/support/download/documents>`_ 版块。

58
docs/zh_CN/versions.rst
View File

@ -11,18 +11,18 @@ ESP-IDF 的 GitHub 仓库时常更新，特别是用于开发新特性的 master
发布版本
---------
您可以通过以下链接访问各个版本的配套文档：
通过以下链接，可以访问各个版本的配套文档：
* 最新稳定版 ESP-IDF：https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
* 最新版 ESP-IDF（即 master 分支）：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/
ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。您可以在该页面查看各个版本的发布说明、配套文档及相应获取方式。
ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。该页面支持查看各个版本的发布说明、配套文档及相应获取方式。
.. only:: html
此外，您还可以直接前往文档页面，查看不同 ESP-IDF 版本的配套文档，具体可点击页面左上角中版本的下拉菜单（在目标下拉菜单和搜索栏之间），实现在不同版本间切换。
此外，也可以直接前往文档页面，查看不同 ESP-IDF 版本的配套文档，具体可点击页面左上角中版本的下拉菜单（在目标下拉菜单和搜索栏之间），实现在不同版本间切换。
.. image:: /../_static/choose_version.png
@ -41,7 +41,7 @@ ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。
- 如需尝试/测试 ESP-IDF 的最新特性，请使用 `最新版本（在 master 分支上） <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/>`_。最新版本包含 ESP-IDF 的所有最新特性，已通过自动化测试，但尚未全部完成人工测试（因此存在一定风险）。
- 如需使用稳定版本中没有的新特性，但同时又不希望受到 master 分支更新的影响，您可以将一个最适合您的稳定版本 :ref:`更新至一个预发布版本` 或 :ref:`更新至一个发布分支`。
- 如需使用稳定版本中没有的新特性，但同时又不希望受到 master 分支更新的影响，可以按照需求选择一个最适合的稳定版本，将其 :ref:`更新至一个预发布版本` 或 :ref:`更新至一个发布分支`。
- 如需使用其他基于 ESP-IDF 的项目，请先查看该项目的文档，以确定其兼容的 ESP-IDF 版本。
@ -52,19 +52,19 @@ ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。
版本管理
-----------------
ESP-IDF 采用了 `语义版本管理方法 <https://semver.org/>`_，即您可以从字面含义理解每个版本的差异。其中
ESP-IDF 采用了 `语义版本管理方法 <https://semver.org/>`_，你可以从字面含义理解每个版本的差异。其中
- 主要版本（例 ``v3.0``）代表有重大更新，包括增加新特性、改变现有特性及移除已弃用的特性。
升级至一个新的主要版本（例 ``v2.1`` 升级至 ``v3.0``）意味着您可能需要更新工程代码，并重新测试工程，具体可参考 `发布说明页面`_ 的重大变更 (Breaking Change) 部分。
升级至一个新的主要版本（例 ``v2.1`` 升级至 ``v3.0``）意味着你可能需要更新工程代码，并重新测试工程，具体可参考 `发布说明页面`_ 的重大变更 (Breaking Change) 部分。
- 次要版本（例 ``v3.1``）代表有新增特性和 bug 修复，但现有特性不受影响，公开 API 的使用也不受影响。
升级至一个新的次要版本（例 ``v3.0`` 升级至 ``v3.1``）意味着您可能不需要更新您的工程代码，但需重新测试您的工程，特别是 `发布说明页面`_ 中专门提到的部分。
升级至一个新的次要版本（例 ``v3.0`` 升级至 ``v3.1``）意味着你可能不需要更新工程代码，但需重新测试工程，特别是 `发布说明页面`_ 中专门提到的部分。
- Bugfix 版本（例 ``v3.0.1``）仅修复 bug，并不增加任何新特性。
升级至一个新的 Bugfix 版本（例 ``v3.0`` 升级至 ``v3.0.1``）意味着您不需要更新您的工程代码，仅需测试与本次发布修复 bug（列表见 `发布说明页面`_）直接相关的特性。
升级至一个新的 Bugfix 版本（例 ``v3.0`` 升级至 ``v3.0.1``）意味着你不需要更新工程代码，仅需测试与本次发布修复 bug（列表见 `发布说明页面`_）直接相关的特性。
支持期限
---------------
@ -77,10 +77,10 @@ ESP-IDF 的每个主要版本和次要版本都有相应的支持期限。支持
一般而言：
- 如您刚开始一个新项目，建议使用最新稳定版本。
- 如您有 GitHub 账号，请点击 `发布说明页面`_ 界面右上角的 "Watch" 按键，并选中 "Releases only" 选项。GitHub 将会在新版本发布的时候通知您。当您所使用的版本有 Bugfix 版本发布时，请做好升级至该 Bugfix 版本的规划。
- 如果你刚开始一个新项目，建议使用最新稳定版本。
- 如果你有 GitHub 账号，请点击 `发布说明页面`_ 界面右上角的 "Watch" 按键，并选中 "Releases only" 选项。GitHub 将会在新版本发布的时候发送通知。当你所使用的版本有 Bugfix 版本发布时，请做好升级至该 Bugfix 版本的规划。
- 如可能，请定期（如每年一次）将项目的 IDF 版本升级至一个新的主要版本或次要版本。对于次要版本更新，更新过程应该比较简单，但对于主要版本更新，可能需要细致查看发布说明并做对应的更新规划。
- 请确保您所使用的版本停止更新维护前，已做好升级至新版本的规划。
- 请确保你所使用的版本停止更新维护前，已做好升级至新版本的规划。
ESP-IDF 的每个主要版本和次要版本（V4.1、V4.2 等）的支持期限为 30 个月，从最初的稳定版发布日算起。
@ -108,7 +108,7 @@ ESP-IDF 的每个主要版本和次要版本（V4.1、V4.2 等）的支持期限
当开始一个新项目时，建议使用在服务期内的版本。
鼓励用户在您所用的版本支持期限结束之前，将所有的工程升级到最新的 ESP-IDF 版本。在版本支持期限满后，我们将不再继续进行 bug 修复。
鼓励用户在所用版本支持期限结束之前，将所有的工程升级到最新的 ESP-IDF 版本。在版本支持期限满后，我们将不再继续进行 bug 修复。
支持期限不包括预发布版本（betas、预览版、 `-rc` 和 `-dev` 版等），有时会将某个特性在发布版中标记为“预览版”，这意味着该特性也不在支持期限内。
@ -125,7 +125,7 @@ ESP-IDF 的每个主要版本和次要版本（V4.1、V4.2 等）的支持期限
idf.py --version
此外，由于 ESP-IDF 的版本也已编译至固件中，因此您也可以使用宏 ``IDF_VER`` 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导程序会在设备启动时打印 ESP-IDF 的版本。请注意，在 GitHub 仓库中的代码更新时，代码中的版本信息仅会在源代码重新编译或在清除编译时才会更新，因此打印出来的版本可能并不是最新的。
此外，由于 ESP-IDF 的版本也已编译至固件中，因此你也可以使用宏 ``IDF_VER`` 查看 ESP-IDF 的版本（以字符串的格式）。ESP-IDF 默认引导程序会在设备启动时打印 ESP-IDF 的版本。请注意，在 GitHub 仓库中的代码更新时，代码中的版本信息仅会在源代码重新编译或在清除编译时才会更新，因此打印出来的版本可能并不是最新的。
如果编写的代码需要支持多个 ESP-IDF 版本，可以在编译时使用 :ref:`compile-time macros<idf-version-h>` 检查版本。
@ -155,7 +155,7 @@ Git 工作流
- 新的改动总是在 master 分支（最新版本）上进行。master 分支上的 ESP-IDF 版本总带有 ``-dev`` 标签，表示“正在开发中”，例 ``v3.1-dev``。
- 这些改动将首先在乐鑫的内部 Git 仓库进行代码审阅与测试，而后在自动化测试完成后推至 GitHub。
- 新版本一旦完成特性开发（在 ``master`` 分支上进行）并达到进入 beta 测试的标准，则将该版本切换至一个新分支（例 ``release/v3.1``）。此外，该分支还打上预发布标签（例 ``v3.1-beta1``）。您可以在 GitHub 平台上查看 ESP-IDF 的完整 `分支列表`_ 和 `标签列表`_。Beta 预发布版本可能仍存在大量“已知问题”(Known Issue)。
- 新版本一旦完成特性开发（在 ``master`` 分支上进行）并达到进入 beta 测试的标准，则将该版本切换至一个新分支（例 ``release/v3.1``）。此外，该分支还打上预发布标签（例 ``v3.1-beta1``）。你可以在 GitHub 平台上查看 ESP-IDF 的完整 `分支列表`_ 和 `标签列表`_。Beta 预发布版本可能仍存在大量“已知问题”(Known Issue)。
- 随着对 beta 版本的不断测试，bug 修复将同时增加至该发布分支和 ``master`` 分支。而且，``master`` 分支可能也已经开始为下个版本开发新特性了。
- 当测试快结束时，该发布分支上将增加一个 rc 标签，代表候选发布 (Release Candidate) ，例 ``v3.1-rc1``。此时，该分支仍属于预发布版本。
- 如果一直未发现或报告重大 bug，则该预发布版本将最终增加“主要版本”（例 ``v4.0``）或“次要版本”标记（例 ``v3.1``），成为正式发布版本，并体现在 `发布说明页面`_ 。
@ -168,13 +168,15 @@ Git 工作流
更新 ESP-IDF
----------------
请根据您的实际情况，对 ESP-IDF 进行更新。
请根据实际情况，对 ESP-IDF 进行更新。
- 如有量产用途，建议参考 :ref:`更新至一个稳定发布版本`。
- 如需测试/研发/尝试最新特性，建议参考 :ref:`更新至 master 分支` 。
- 两者折衷建议参考 :ref:`更新至一个发布分支`。
.. note:: 在参考本指南时，请首先获得 ESP-IDF 的本地副本，具体步骤请参考 :doc:`入门指南 </get-started/index>` 中的介绍。
.. note::
在参考本指南时，请首先获得 ESP-IDF 的本地副本，具体步骤请参考 :doc:`入门指南 </get-started/index>` 中的介绍。
.. _`更新至一个稳定发布版本`:
@ -185,7 +187,7 @@ Git 工作流
对于量产用户，推荐更新至一个新的 ESP-IDF 发布版本，请参考以下步骤：
- 请定期查看 `发布说明页面`_ ，了解最新发布情况。
- 如有新发布的 Bugfix 版本（例 ``v3.0.1`` 或 ``v3.0.2``）时，请将新的 Bugfix 版本更新至您的 ESP-IDF 目录。
- 如有新发布的 Bugfix 版本（例 ``v3.0.1`` 或 ``v3.0.2``）时，请将新的 Bugfix 版本更新至你的 ESP-IDF 目录。
- 在 Linux 或 macOS 系统中，请运行如下命令将分支更新至 vX.Y.Z：
.. code-block:: bash
@ -196,9 +198,11 @@ Git 工作流
git submodule update --init --recursive
- 在 Windows 系统中，需要将 ``cd $IDF_PATH`` 替换为 ``cd %IDF_PATH%``。
- 在主要版本或次要版本新发布时，请查看发布说明中的具体描述，并决定是否升级您的版本。具体命令与上方描述一致。
- 在主要版本或次要版本新发布时，请查看发布说明中的具体描述，并决定是否升级版本。具体命令与上方描述一致。
.. note:: 如果您之前在安装 ESP-IDF 时使用了 zip 文件包，而非通过 Git 命令，则您将无法使用 Git 命令进行版本升级，此属正常情况。这种情况下，请重新下载最新 zip 文件包，并替换掉之前 ``IDF_PATH`` 下的全部内容。
.. note::
如果你在安装 ESP-IDF 时使用的是 zip 文件包，而非通过 Git 命令，则将无法使用 Git 命令进行版本升级，此属正常情况。这种情况下，请重新下载最新 zip 文件包，并替换掉之前 ``IDF_PATH`` 下的全部内容。
.. _`更新至一个预发布版本`:
@ -206,7 +210,7 @@ Git 工作流
更新至一个预发布版本
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
您也可以将您的本地副本切换（命令 ``git checkout``）至一个预发布版本或 rc 版本，具体方法请参考 :ref:`更新至一个稳定发布版本` 中的描述。
你也可以将你的本地副本切换（命令 ``git checkout``）至一个预发布版本或 rc 版本，具体方法请参考 :ref:`更新至一个稳定发布版本` 中的描述。
预发布版本通常不体现在 `发布说明页面`_。更多详情，请查看完整 `标签列表`_。使用预发布版本的注意事项，请参考 :ref:`更新至一个发布分支` 中的描述。
@ -215,7 +219,9 @@ Git 工作流
更新至 master 分支
^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: ESP-IDF 中 master 分支上的代码会时时更新，因此使用 master 分支相当在“流血的边缘试探”，存在一定风险。
.. note::
ESP-IDF 中 master 分支上的代码会时时更新，因此使用 master 分支相当在“流血的边缘试探”，存在一定风险。
如需使用 ESP-IDF 的 master 分支，请参考以下步骤：
@ -229,12 +235,12 @@ Git 工作流
git submodule update --init --recursive
- 在 Windows 系统中，需要将 ``cd $IDF_PATH`` 替换为 ``cd %IDF_PATH%``。
- 此外，您还应在后续工作中不时使用 ``git pull`` 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，您可能需要更改工程代码，也可能遇到新的 bug。
- 此外，你还应在后续工作中不时使用 ``git pull`` 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，你可能需要更改工程代码，也可能遇到新的 bug。
- 如需从 master 分支切换至一个发布分支或稳定版本，请使用 ``git checkout`` 命令。
.. important::
强烈建议您定期使用 ``git pull`` 和 ``git submodule update --init --recursive`` 命令，确保本地副本得到及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 :ref:`更新至一个发布分支`。
强烈建议定期使用 ``git pull`` 和 ``git submodule update --init --recursive`` 命令，确保本地副本得到及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 :ref:`更新至一个发布分支`。
.. _`更新至一个发布分支`:
@ -245,7 +251,7 @@ Git 工作流
更多详情，请前往 GitHub 查看完整 `标签列表`_。
例如，在 Linux 或 macOS 系统中，您可以运行以下命令更新至ESP-IDF v3.1，随时关注该分支上的 Bugfix 版本发布（如 ``v3.1.1`` 等）：
例如，在 Linux 或 macOS 系统中，可以运行以下命令更新至ESP-IDF v3.1，随时关注该分支上的 Bugfix 版本发布（如 ``v3.1.1`` 等）：
.. code-block:: bash
@ -257,11 +263,11 @@ Git 工作流
在 Windows 系统中，需要将 ``cd $IDF_PATH`` 替换为 ``cd %IDF_PATH%``。
您每次在该分支上使用 ``git pull`` 时都相当于把最新的 Bugfix 版本发布更新至您的本地副本中。
每次在该分支上使用 ``git pull`` 时，都相当于把最新的 Bugfix 版本发布更新至你的本地副本中。
.. note::
发布分支并不会有专门的配套文档，建议您使用与本分支最接近版本的文档。
发布分支并不会有专门的配套文档，建议使用与本分支最接近版本的文档。
.. _`发布说明页面`: https://github.com/espressif/esp-idf/releases
.. _`分支列表`: https://github.com/espressif/esp-idf/branches