alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-08-08 04:02:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
caixinying-git
2023-07-31 16:13:41 +08:00
parent efd46fc140
commit 946496405a
56 changed files with 515 additions and 457 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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
-------------