mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: update format issues left in EN docs
This commit is contained in:
caixinying-git
BOT
parent
a9349f4ad4
commit
b07ada6e94
@ -1,6 +1,6 @@
|
||||
:orphan:
|
||||
|
||||
Page not Found
|
||||
Page Not Found
|
||||
==============
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
@ -9,11 +9,11 @@ Page not Found
|
||||
|
||||
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.
|
||||
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 are sorry. The page you requested could not be found.
|
||||
:figclass: align-center
|
||||
|
||||
|
||||
* :ref:`genindex`
|
||||
|
||||
@ -17,13 +17,13 @@ Firmware Components
|
||||
|
||||
These third party libraries can be included into the application (firmware) produced by ESP-IDF.
|
||||
|
||||
* :component:`Newlib <newlib>` is licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB<newlib/COPYING.NEWLIB>`.
|
||||
* :component:`Newlib <newlib>` is licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB <newlib/COPYING.NEWLIB>`.
|
||||
|
||||
* :component:`Xtensa header files<xtensa/include/xtensa>` are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files.
|
||||
* :component:`Xtensa header files <xtensa/include/xtensa>` are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files.
|
||||
|
||||
* Original parts of FreeRTOS_ (components/freertos) are Copyright (C) 2017 Amazon.com, Inc. or its affiliates are licensed under the MIT License, as described in :component_file:`license.txt<freertos/FreeRTOS-Kernel/LICENSE.md>`.
|
||||
* Original parts of FreeRTOS_ (components/freertos) are Copyright (C) 2017 Amazon.com, Inc. or its affiliates are licensed under the MIT License, as described in :component_file:`license.txt <freertos/FreeRTOS-Kernel/LICENSE.md>`.
|
||||
|
||||
* Original parts of LWIP_ (components/lwip) are Copyright (C) 2001, 2002 Swedish Institute of Computer Science and are licensed under the BSD License as described in :component_file:`COPYING file<lwip/lwip/COPYING>`.
|
||||
* Original parts of LWIP_ (components/lwip) are Copyright (C) 2001, 2002 Swedish Institute of Computer Science and are licensed under the BSD License as described in :component_file:`COPYING file <lwip/lwip/COPYING>`.
|
||||
|
||||
* `wpa_supplicant`_ Copyright (c) 2003-2022 Jouni Malinen <j@w1.fi> and contributors and licensed under the BSD license.
|
||||
|
||||
@ -31,7 +31,7 @@ These third party libraries can be included into the application (firmware) prod
|
||||
|
||||
* `FreeBSD net80211`_ Copyright (c) 2004-2008 Sam Leffler, Errno Consulting and licensed under the BSD license.
|
||||
|
||||
* `argtable3`_ argument parsing library Copyright (C) 1998-2001,2003-2011,2013 Stewart Heitmann and licensed under 3-clause BSD license. argtable3 also includes the following software components. For details, please see argtable3 :component_file:`LICENSE file<console/argtable3/LICENSE>`.
|
||||
* `argtable3`_ argument parsing library Copyright (C) 1998-2001,2003-2011,2013 Stewart Heitmann and licensed under 3-clause BSD license. argtable3 also includes the following software components. For details, please see argtable3 :component_file:`LICENSE file <console/argtable3/LICENSE>`.
|
||||
|
||||
* C Hash Table library, Copyright (c) 2002, Christopher Clark and licensed under 3-clause BSD license.
|
||||
* The Better String library, Copyright (c) 2014, Paul Hsieh and licensed under 3-clause BSD license.
|
||||
@ -55,15 +55,15 @@ These third party libraries can be included into the application (firmware) prod
|
||||
|
||||
* :component:`BLE Mesh <bt/esp_ble_mesh>` is adapted from Zephyr Project, Copyright (c) 2017-2018 Intel Corporation and licensed under Apache License 2.0
|
||||
|
||||
* `mynewt-nimble`_ Apache Mynewt NimBLE, Copyright 2015-2018, The Apache Software Foundation, is licensed under Apache License 2.0 as described in :component_file:`LICENSE file<bt/host/nimble/nimble/LICENSE>`.
|
||||
* `mynewt-nimble`_ Apache Mynewt NimBLE, Copyright 2015-2018, The Apache Software Foundation, is licensed under Apache License 2.0 as described in :component_file:`LICENSE file <bt/host/nimble/nimble/LICENSE>`.
|
||||
|
||||
* `TLSF allocator <https://github.com/espressif/tlsf>`_ Two Level Segregated Fit memory allocator, Copyright (c) 2006-2016, Matthew Conte, and licensed under the BSD 3-clause license.
|
||||
|
||||
* :component:`openthread`, Copyright (c) The OpenThread Authors, is licensed under BSD License as described in :component_file:`LICENSE file<openthread/openthread/LICENSE>`.
|
||||
* :component:`openthread`, Copyright (c) The OpenThread Authors, is licensed under BSD License as described in :component_file:`LICENSE file <openthread/openthread/LICENSE>`.
|
||||
|
||||
* :component_file:`UBSAN runtime <esp_system/ubsan.c>` — Copyright (c) 2016, Linaro Limited and Jiří Zárevúcky, licensed under the BSD 2-clause license.
|
||||
|
||||
* :component:`HTTP Parser <http_parser>` Based on src/http/ngx_http_parse.c from NGINX copyright Igor Sysoev. Additional changes are licensed under the same terms as NGINX and Joyent, Inc. and other Node contributors. For details please check :component_file:`LICENSE file<http_parser/LICENSE.txt>`.
|
||||
* :component:`HTTP Parser <http_parser>` Based on src/http/ngx_http_parse.c from NGINX copyright Igor Sysoev. Additional changes are licensed under the same terms as NGINX and Joyent, Inc. and other Node contributors. For details please check :component_file:`LICENSE file <http_parser/LICENSE.txt>`.
|
||||
|
||||
* `SEGGER SystemView`_ target-side library, Copyright (c) 1995-2021 SEGGER Microcontroller GmbH, is licensed under BSD 1-clause license.
|
||||
|
||||
@ -77,7 +77,7 @@ ROM Source Code Copyrights
|
||||
|
||||
ESP32, ESP32-S and ESP32-C Series SoCs mask ROM hardware includes binaries compiled from portions of the following third party software:
|
||||
|
||||
* :component:`Newlib <newlib>`, licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB<newlib/COPYING.NEWLIB>`.
|
||||
* :component:`Newlib <newlib>`, licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB <newlib/COPYING.NEWLIB>`.
|
||||
|
||||
* Xtensa libhal, Copyright (c) Tensilica Inc and licensed under the MIT license (see below).
|
||||
|
||||
@ -93,8 +93,8 @@ ESP32, ESP32-S and ESP32-C Series SoCs mask ROM hardware includes binaries compi
|
||||
* `DesignWare USB device driver`_ Copyright (c) 2016 Intel Corporation and licensed under Apache 2.0 license.
|
||||
* `Generic USB device driver`_ Copyright (c) 2006 Bertrik Sikken (bertrik@sikken.nl), 2016 Intel Corporation and licensed under BSD 3-clause license.
|
||||
* `USB descriptors functionality`_ Copyright (c) 2017 PHYTEC Messtechnik GmbH, 2017-2018 Intel Corporation and licensed under Apache 2.0 license.
|
||||
* `USB DFU class driver`_ Copyright(c) 2015-2016 Intel Corporation, 2017 PHYTEC Messtechnik GmbH and licensed under BSD 3-clause license.
|
||||
* `USB CDC ACM class driver`_ Copyright(c) 2015-2016 Intel Corporation and licensed under Apache 2.0 license
|
||||
* `USB DFU class driver`_ Copyright (c) 2015-2016 Intel Corporation, 2017 PHYTEC Messtechnik GmbH and licensed under BSD 3-clause license.
|
||||
* `USB CDC ACM class driver`_ Copyright (c) 2015-2016 Intel Corporation and licensed under Apache 2.0 license
|
||||
|
||||
Xtensa libhal MIT License
|
||||
=========================
|
||||
@ -134,7 +134,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
|
||||
TJpgDec License
|
||||
===============
|
||||
|
||||
TJpgDec - Tiny JPEG Decompressor R0.01 (C)ChaN, 2011
|
||||
TJpgDec - Tiny JPEG Decompressor R0.01 (C) ChaN, 2011
|
||||
The TJpgDec is a generic JPEG decompressor module for tiny embedded systems.
|
||||
This is a free software that opened for education, research and commercial
|
||||
developments under license policy of following terms.
|
||||
|
||||
@ -171,8 +171,8 @@ Many of the ESP-IDF components use :ref:`api_reference_config_structures` as arg
|
||||
C and C++ languages have different rules with regards to the designated initializers. For example, C++23 (currently the default in ESP-IDF) does not support out-of-order designated initialization, nested designated initialization, mixing of designated initializers and regular initializers, and designated initialization of arrays. Therefore, when porting ESP-IDF C examples to C++, some changes to the structure initializers may be necessary. See the `C++ aggregate initialization reference <https://en.cppreference.com/w/cpp/language/aggregate_initialization>`_ for more details.
|
||||
|
||||
|
||||
iostream
|
||||
^^^^^^^^
|
||||
``iostream``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
``iostream`` functionality is supported in ESP-IDF, with a couple of caveats:
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ Please see the :doc:`ble-mesh-architecture` for information about the implementa
|
||||
ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here <https://launchstudio.bluetooth.com/ListingDetails/94304>`_ for the certification details of ESP-BLE-MESH.
|
||||
|
||||
.. only:: SOC_WIFI_MESH_SUPPORT
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-WIFI-MESH. For more information and documentation see :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`.
|
||||
@ -223,9 +223,9 @@ ESP-BLE-MESH Examples
|
||||
|
||||
* :example_file:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/wifi_coexist>`.
|
||||
|
||||
* ESP-BLE-MESH Remote Provisioning(v1.1) - :example_file:`Client, Server and device <bluetooth/esp_ble_mesh/remote_provisioning/tutorial/BLE_Mesh_Remote_Provisioning_Example_Walkthrough.md>` - this example is used to demonstrate the new remote provisioning feature introduced in the Mesh Protocol v1.1, see :example:`example client code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_client>`, :example:`example server code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_server>` and :example:`example device code <bluetooth/esp_ble_mesh/remote_provisioning/unprov_dev>`.
|
||||
* ESP-BLE-MESH Remote Provisioning (v1.1) - :example_file:`Client, Server and device <bluetooth/esp_ble_mesh/remote_provisioning/tutorial/BLE_Mesh_Remote_Provisioning_Example_Walkthrough.md>` - this example is used to demonstrate the new remote provisioning feature introduced in the Mesh Protocol v1.1, see :example:`example client code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_client>`, :example:`example server code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_server>` and :example:`example device code <bluetooth/esp_ble_mesh/remote_provisioning/unprov_dev>`.
|
||||
|
||||
* ESP-BLE-MESH Directed Forwarding(v1.1) - :example_file:`Client and Server <bluetooth/esp_ble_mesh/directed_forwarding/tutorial/BLE_Mesh_Directed_Forwarding_Example_Walkthrough.md>` - this example is used to demonstrate the new directed forwarding feature introduced in the Mesh Protocol v1.1. Only nodes along the path will forward the directed messages, while other nodes will not actively participate in forwarding, see :example:`example client code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_client>` and :example:`example server code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_server>`.
|
||||
* ESP-BLE-MESH Directed Forwarding (v1.1) - :example_file:`Client and Server <bluetooth/esp_ble_mesh/directed_forwarding/tutorial/BLE_Mesh_Directed_Forwarding_Example_Walkthrough.md>` - this example is used to demonstrate the new directed forwarding feature introduced in the Mesh Protocol v1.1. Only nodes along the path will forward the directed messages, while other nodes will not actively participate in forwarding, see :example:`example client code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_client>` and :example:`example server code <bluetooth/esp_ble_mesh/remote_provisioning/rpr_server>`.
|
||||
|
||||
|
||||
.. _esp-ble-mesh-demo-videos:
|
||||
|
||||
@ -79,7 +79,7 @@ Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access securit
|
||||
|
||||
{IDF_TARGET_NAME} station also supports following additional Wi-Fi CERTIFIED WPA3™ features:
|
||||
|
||||
- **Transition Disable** : WPA3 defines transition modes for client devices so that they can connect to a network even when some of the APs in that network do not support the strongest security mode. Client device implementations typically configure network profiles in a transition mode by default. However, such a client device could be subject to an active downgrade attack in which the attacker causes the client device to use a lower security mode in order to exploit a vulnerability with that mode. WPA3 has introduced the Transition Disable feature to mitigate such attacks, by enabling client devices to change from a transition mode to an “only” mode when connecting to a network, once that network indicates it fully supports the higher security mode. Enable :cpp:type:`transition_disable` in :cpp:type:`wifi_sta_config_t` to enable this feature for {IDF_TARGET_NAME} station.
|
||||
- **Transition Disable** : WPA3 defines transition modes for client devices so that they can connect to a network even when some of the APs in that network do not support the strongest security mode. Client device implementations typically configure network profiles in a transition mode by default. However, such a client device could be subject to an active downgrade attack in which the attacker causes the client device to use a lower security mode in order to exploit a vulnerability with that mode. WPA3 has introduced the Transition Disable feature to mitigate such attacks, by enabling client devices to change from a transition mode to an "only" mode when connecting to a network, once that network indicates it fully supports the higher security mode. Enable :cpp:type:`transition_disable` in :cpp:type:`wifi_sta_config_t` to enable this feature for {IDF_TARGET_NAME} station.
|
||||
|
||||
- **SAE PUBLIC-KEY (PK)** : As the password at small public networks is shared with multiple users, it may be relatively easy for an attacker to find out the password, which is sufficient to launch an evil twin attack. Such attacks are prevented by an extension to WPA3-Personal called SAE-PK. The SAE-PK authentication exchange is very similar to the regular SAE exchange, with the addition of a digital signature sent by the AP to the client device. The client device validates the public key asserted by the AP based on the password fingerprint and verifies the signature using the public key. So even if the attacker knows the password, it does not know the private key to generate a valid signature, and therefore the client device is protected against an evil twin attack. Enable :ref:`CONFIG_ESP_WIFI_ENABLE_SAE_PK` and :cpp:type:`sae_pk_mode` in :cpp:type:`wifi_sta_config_t` to add support of SAE PK for {IDF_TARGET_NAME} station.
|
||||
|
||||
|
||||
@ -18,8 +18,8 @@ Application developers can open a terminal-based project configuration menu with
|
||||
|
||||
After being updated, this configuration is saved in the ``sdkconfig`` file under the project root directory. Based on ``sdkconfig``, application build targets will generate the ``sdkconfig.h`` file under the build directory, and will make the ``sdkconfig`` options available to the project build system and source files.
|
||||
|
||||
Using sdkconfig.defaults
|
||||
========================
|
||||
Using ``sdkconfig.defaults``
|
||||
============================
|
||||
|
||||
In some cases, for example, when the ``sdkconfig`` file is under revision control, it may be inconvenient for the build system to change the ``sdkconfig`` file. The build system offers a solution to prevent it from happening, which is to create the ``sdkconfig.defaults`` file. This file is never touched by the build system, and can be created manually or automatically. It contains all the options which matter to the given application and are different from the default ones. The format is the same as that of the ``sdkconfig`` file. ``sdkconfig.defaults`` can be created manually when one remembers all the changed configuration, or it can be generated automatically by running the ``idf.py save-defconfig`` command.
|
||||
|
||||
|
||||
@ -76,7 +76,7 @@ The application can access the ESP-WIFI-MESH stack directly without having to go
|
||||
|
||||
.. _mesh-writing-mesh-application:
|
||||
|
||||
Writing an ESP-WIFI-MESH Application
|
||||
Writing an ESP-WIFI-MESH Application
|
||||
-------------------------------------------
|
||||
|
||||
The prerequisites for starting ESP-WIFI-MESH is to initialize LwIP and Wi-Fi, The following code snippet demonstrates the necessary prerequisite steps before ESP-WIFI-MESH itself can be initialized.
|
||||
@ -126,22 +126,22 @@ Configuring an ESP-WIFI-MESH Network
|
||||
ESP-WIFI-MESH is configured via :cpp:func:`esp_mesh_set_config` which receives its arguments using the :cpp:type:`mesh_cfg_t` structure. The structure contains the following parameters used to configure ESP-WIFI-MESH:
|
||||
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 15 25
|
||||
|
||||
* - Parameter
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 15 25
|
||||
|
||||
* - Parameter
|
||||
- Description
|
||||
|
||||
|
||||
* - Channel
|
||||
- Range from 1 to 14
|
||||
|
||||
|
||||
* - Mesh ID
|
||||
- ID of ESP-WIFI-MESH Network, see :cpp:type:`mesh_addr_t`
|
||||
|
||||
* - Router
|
||||
- Router Configuration, see :cpp:type:`mesh_router_t`
|
||||
|
||||
- ID of ESP-WIFI-MESH Network, see :cpp:type:`mesh_addr_t`
|
||||
|
||||
* - Router
|
||||
- Router Configuration, see :cpp:type:`mesh_router_t`
|
||||
|
||||
* - Mesh AP
|
||||
- Mesh AP Configuration, see :cpp:type:`mesh_ap_cfg_t`
|
||||
|
||||
@ -236,7 +236,7 @@ ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when enabl
|
||||
| | | - Nodes previously scanning for a parent nodes will stop scanning. Call :cpp:func:`esp_mesh_connect` to restart. |
|
||||
| +--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| | Y | - A root node already connected to router will stay connected. |
|
||||
| | | - A root node disconnected from router will need to call :cpp:func:`esp_mesh_connect` to reconnect. |
|
||||
| | | - A root node disconnected from router will need to call :cpp:func:`esp_mesh_connect` to reconnect. |
|
||||
+---------------+--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| Y | N | - Nodes without a parent node will automatically select a preferred parent and connect. |
|
||||
| | | - Nodes already connected to a parent node will disconnect, reselect a preferred parent node, and connect. |
|
||||
@ -273,7 +273,7 @@ Therefore, application calls to Wi-Fi APIs should be placed in between calls of
|
||||
|
||||
//Stop any scans already in progress
|
||||
esp_wifi_scan_stop();
|
||||
//Manually start scan. Will automatically stop when run to completion
|
||||
//Manually start scan. Will automatically stop when run to completion
|
||||
esp_wifi_scan_start();
|
||||
|
||||
//Process scan results
|
||||
@ -304,9 +304,9 @@ Application Examples
|
||||
|
||||
ESP-IDF contains these ESP-WIFI-MESH example projects:
|
||||
|
||||
:example:`The Internal Communication Example<mesh/internal_communication>` demonstrates how to set up a ESP-WIFI-MESH network and have the root node send a data packet to every node within the network.
|
||||
:example:`The Internal Communication Example <mesh/internal_communication>` demonstrates how to set up a ESP-WIFI-MESH network and have the root node send a data packet to every node within the network.
|
||||
|
||||
:example:`The Manual Networking Example<mesh/manual_networking>` demonstrates how to use ESP-WIFI-MESH without the self-organizing features. This example shows how to program a node to manually scan for a list of potential parent nodes and select a parent node based on custom criteria.
|
||||
:example:`The Manual Networking Example <mesh/manual_networking>` demonstrates how to use ESP-WIFI-MESH without the self-organizing features. This example shows how to program a node to manually scan for a list of potential parent nodes and select a parent node based on custom criteria.
|
||||
|
||||
|
||||
.. ------------------------- ESP-WIFI-MESH API Reference ---------------------------
|
||||
|
||||
@ -457,7 +457,7 @@ Custom PHY Driver
|
||||
|
||||
There are multiple PHY manufacturers with wide portfolios of chips available. The ESP-IDF already supports several PHY chips however one can easily get to a point where none of them satisfies the user's actual needs due to price, features, stock availability, etc.
|
||||
|
||||
Luckily, a management interface between EMAC and PHY is standardized by IEEE 802.3 in Section 22.2.4 Management Functions. It defines provisions of the so-called “MII Management Interface” to control the PHY and gather status from the PHY. A set of management registers is defined to control chip behavior, link properties, auto-negotiation configuration, etc. This basic management functionality is addressed by :component_file:`esp_eth/src/esp_eth_phy_802_3.c` in ESP-IDF and so it makes the creation of a new custom PHY chip driver quite a simple task.
|
||||
Luckily, a management interface between EMAC and PHY is standardized by IEEE 802.3 in Section 22.2.4 Management Functions. It defines provisions of the so-called "MII Management Interface" to control the PHY and gather status from the PHY. A set of management registers is defined to control chip behavior, link properties, auto-negotiation configuration, etc. This basic management functionality is addressed by :component_file:`esp_eth/src/esp_eth_phy_802_3.c` in ESP-IDF and so it makes the creation of a new custom PHY chip driver quite a simple task.
|
||||
|
||||
.. note::
|
||||
Always consult with PHY datasheet since some PHY chips may not comply with IEEE 802.3, Section 22.2.4. It does not mean you are not able to create a custom PHY driver, but it just requires more effort. You will have to define all PHY management functions.
|
||||
|
||||
@ -162,7 +162,7 @@ To be able to use the ESP-NETIF L2 TAP interface, it needs to be enabled in Kcon
|
||||
|
||||
``open()``
|
||||
^^^^^^^^^^
|
||||
Once the ESP-NETIF L2 TAP is registered, it can be opened at path name “/dev/net/tap”. The same path name can be opened multiple times up to :ref:`CONFIG_ESP_NETIF_L2_TAP_MAX_FDS` and multiple file descriptors with a different configuration may access the Data Link Layer frames.
|
||||
Once the ESP-NETIF L2 TAP is registered, it can be opened at path name "/dev/net/tap". The same path name can be opened multiple times up to :ref:`CONFIG_ESP_NETIF_L2_TAP_MAX_FDS` and multiple file descriptors with a different configuration may access the Data Link Layer frames.
|
||||
|
||||
The ESP-NETIF L2 TAP can be opened with the ``O_NONBLOCK`` file status flag to make sure the ``read()`` does not block. Note that the ``write()`` may block in the current implementation when accessing a Network interface since it is a shared resource among multiple ESP-NETIF L2 TAP file descriptors and IP stack, and there is currently no queuing mechanism deployed. The file status flag can be retrieved and modified using ``fcntl()``.
|
||||
|
||||
@ -231,7 +231,7 @@ A raw Data Link Layer frame can be sent to Network Interface via opened and conf
|
||||
* - 6 B
|
||||
- 6 B
|
||||
- 2 B
|
||||
- 0-1486 B
|
||||
- 0-1486 B
|
||||
|
||||
In other words, there is no additional frame processing performed by the ESP-NETIF L2 TAP interface. It only checks the Ethernet type of the frame is the same as the filter configured in the file descriptor. If the Ethernet type is different, an error is returned and the frame is not sent. Note that the ``write()`` may block in the current implementation when accessing a Network interface since it is a shared resource among multiple ESP-NETIF L2 TAP file descriptors and IP stack, and there is currently no queuing mechanism deployed.
|
||||
|
||||
@ -328,7 +328,7 @@ Then we start the service normally with :cpp:func:`esp_netif_sntp_start()`.
|
||||
ESP-NETIF Programmer's Manual
|
||||
-----------------------------
|
||||
|
||||
Please refer to the following example to understand the initialization process of the default interface:
|
||||
Please refer to the following example to understand the initialization process of the default interface:
|
||||
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
@ -15,7 +15,7 @@ As shown in the diagram, the following three API functions for the packet data p
|
||||
* :cpp:func:`esp_netif_free_rx_buffer()`
|
||||
* :cpp:func:`esp_netif_receive()`
|
||||
|
||||
The first two functions for transmitting and freeing the rx buffer are provided as callbacks, i.e.， they get called from esp-netif (and its underlying TCP/IP stack) and I/O driver provides their implementation.
|
||||
The first two functions for transmitting and freeing the rx buffer are provided as callbacks, i.e., they get called from esp-netif (and its underlying TCP/IP stack) and I/O driver provides their implementation.
|
||||
|
||||
The receiving function on the other hand gets called from the I/O driver, so that the driver's code simply calls :cpp:func:`esp_netif_receive()` on a new data received event.
|
||||
|
||||
|
||||
@ -7,7 +7,7 @@ Clock Tree
|
||||
|
||||
{IDF_TARGET_RC_FAST_ADJUSTED_FREQ: default="8.5", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32c6="17.5"}
|
||||
|
||||
{IDF_TARGET_XTAL_FREQ: default="40", esp32="2~40", esp32c2="40/26", esp32h2="32"}
|
||||
{IDF_TARGET_XTAL_FREQ: default="40", esp32="2 ~ 40", esp32c2="40/26", esp32h2="32"}
|
||||
|
||||
{IDF_TARGET_RC_SLOW_VAGUE_FREQ: default="136", esp32="150", esp32s2="90"}
|
||||
|
||||
|
||||
@ -187,7 +187,7 @@ To allocate a capture timer, you can call the :cpp:func:`mcpwm_new_capture_timer
|
||||
- :cpp:member:`mcpwm_capture_timer_config_t::clk_src` sets the clock source of the capture timer.
|
||||
- :cpp:member:`mcpwm_capture_timer_config_t::resolution_hz` The driver internally will set a proper divider based on the clock source and the resolution. If it is set to ``0``, the driver will pick an appropriate resolution on its own, and you can subsequently view the current timer resolution via :cpp:func:`mcpwm_capture_timer_get_resolution`.
|
||||
|
||||
.. only:: not SOC_MCPWM_CAPTURE_CLK_FROM_GROUP
|
||||
.. only:: not SOC_MCPWM_CAPTURE_CLK_FROM_GROUP
|
||||
|
||||
.. note::
|
||||
|
||||
@ -209,7 +209,7 @@ The :cpp:func:`mcpwm_new_capture_channel` will return a pointer to the allocated
|
||||
|
||||
On the contrary, calling :cpp:func:`mcpwm_del_capture_channel` and :cpp:func:`mcpwm_del_capture_timer` will free the allocated capture channel and timer object accordingly.
|
||||
|
||||
MCPWM interrupt priority
|
||||
MCPWM Interrupt Priority
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
MCPWM allows configuring interrupts separately for timer, operator, comparator, fault, and capture events. The interrupt priority is determined by the respective ``config_t::intr_priority``. Additionally, events within the same MCPWM group share a common interrupt source. When registering multiple interrupt events, the interrupt priorities need to remain consistent.
|
||||
@ -335,7 +335,7 @@ One generator can set action on fault based trigger events, by calling :cpp:func
|
||||
|
||||
When no free trigger slot is left in the operator to which the generator belongs, this function will return the :c:macro:`ESP_ERR_NOT_FOUND` error. [1]_
|
||||
|
||||
The trigger only support GPOI fault. when the input is not a GPIO fault, this function will return the :c:macro:`ESP_ERR_NOT_SUPPORTED` error.
|
||||
The trigger only support GPOI fault. when the input is not a GPIO fault, this function will return the :c:macro:`ESP_ERR_NOT_SUPPORTED` error.
|
||||
|
||||
There is a helper macro :c:macro:`MCPWM_GEN_FAULT_EVENT_ACTION` to simplify the construction of a trigger event action entry.
|
||||
|
||||
|
||||
@ -48,14 +48,14 @@ Install PCNT Unit
|
||||
To install a PCNT unit, there is a configuration structure that needs to be given in advance: :cpp:type:`pcnt_unit_config_t`:
|
||||
|
||||
- :cpp:member:`pcnt_unit_config_t::low_limit` and :cpp:member:`pcnt_unit_config_t::high_limit` specify the range for the internal hardware counter. The counter will reset to zero automatically when it crosses either the high or low limit.
|
||||
- :cpp:member:`pcnt_unit_config_t::accum_count` sets whether to create an internal accumulator for the counter. This is helpful when you want to extend the counter's width, which by default is 16bit at most, defined in the hardware. See also :ref:`pcnt-compensate-overflow-loss` for how to use this feature to compensate the overflow loss.
|
||||
- :cpp:member:`pcnt_unit_config_t::accum_count` sets whether to create an internal accumulator for the counter. This is helpful when you want to extend the counter's width, which by default is 16 bit at most, defined in the hardware. See also :ref:`pcnt-compensate-overflow-loss` for how to use this feature to compensate the overflow loss.
|
||||
- :cpp:member:`pcnt_unit_config_t::intr_priority` sets the priority of the interrupt. If it is set to ``0``, the driver will allocate an interrupt with a default priority. Otherwise, the driver will use the given priority.
|
||||
|
||||
.. note::
|
||||
|
||||
Since all PCNT units share the same interrupt source, when installing multiple PCNT units make sure that the interrupt priority :cpp:member:`pcnt_unit_config_t::intr_priority` is the same for each unit.
|
||||
|
||||
Unit allocation and initialization is done by calling a function :cpp:func:`pcnt_new_unit` with :cpp:type:`pcnt_unit_config_t` as an input parameter. The function will return a PCNT unit handle only when it runs correctly. Specifically, when there are no more free PCNT units in the pool (i.e. unit resources have been used up), then this function will return :c:macro:`ESP_ERR_NOT_FOUND` error. The total number of available PCNT units is recorded by :c:macro:`SOC_PCNT_UNITS_PER_GROUP` for reference.
|
||||
Unit allocation and initialization is done by calling a function :cpp:func:`pcnt_new_unit` with :cpp:type:`pcnt_unit_config_t` as an input parameter. The function will return a PCNT unit handle only when it runs correctly. Specifically, when there are no more free PCNT units in the pool (i.e., unit resources have been used up), then this function will return :c:macro:`ESP_ERR_NOT_FOUND` error. The total number of available PCNT units is recorded by :c:macro:`SOC_PCNT_UNITS_PER_GROUP` for reference.
|
||||
|
||||
If a previously created PCNT unit is no longer needed, it is recommended to recycle the resource by calling :cpp:func:`pcnt_del_unit`. Which in return allows the underlying unit hardware to be used for other purposes. Before deleting a PCNT unit, one should ensure the following prerequisites:
|
||||
|
||||
@ -192,7 +192,7 @@ This function should be called when the unit is in the init state. Otherwise, it
|
||||
|
||||
.. note::
|
||||
|
||||
The glitch filter is clocked from APB. For the counter not to miss any pulses, the maximum glitch width should be longer than one APB_CLK cycle (usually 12.5 ns if APB equals 80MHz). As the APB frequency would be changed after DFS (Dynamic Frequency Scaling) enabled, which means the filter does not work as expect in that case. So the driver installs a PM lock for PCNT unit during the first time you enable the glitch filter. For more information related to power management strategy used in PCNT driver, please see :ref:`pcnt-power-management`.
|
||||
The glitch filter is clocked from APB. For the counter not to miss any pulses, the maximum glitch width should be longer than one APB_CLK cycle (usually 12.5 ns if APB equals 80 MHz). As the APB frequency would be changed after DFS (Dynamic Frequency Scaling) enabled, which means the filter does not work as expect in that case. So the driver installs a PM lock for PCNT unit during the first time you enable the glitch filter. For more information related to power management strategy used in PCNT driver, please see :ref:`pcnt-power-management`.
|
||||
|
||||
.. code:: c
|
||||
|
||||
|
||||
@ -127,7 +127,7 @@ Kconfig Options
|
||||
|
||||
.. _convert_to_analog_signal:
|
||||
|
||||
Convert to an analog signal (Optional)
|
||||
Convert to an Analog Signal (Optional)
|
||||
--------------------------------------
|
||||
|
||||
Typically, if a Sigma-Delta signal is connected to an LED to adjust the brightness, you do not have to add any filter between them, because our eyes have their own low-pass filters for changes in light intensity. However, if you want to check the real voltage or watch the analog waveform, you need to design an analog low-pass filter. Also, it is recommended to use an active filter instead of a passive filter to gain better isolation and not lose too much voltage.
|
||||
|
||||
@ -171,7 +171,7 @@ However, unlike interrupt transactions, isochronous transactions are not retried
|
||||
|
||||
Thus, isochronous transfers in Host Mode Scatter/Gather DMA have the following peculiarities:
|
||||
|
||||
- A QTD must be allocated for each (micro) frame. However, non-service service period QTDs should be left blank (i.e., only ever Nth QTD should be filled if the channel's service period is every Nth (micro)frame).
|
||||
- A QTD must be allocated for each (micro)frame. However, non-service service period QTDs should be left blank (i.e., only ever Nth QTD should be filled if the channel's service period is every Nth (micro)frame).
|
||||
- **Each filled QTD must represent a single transaction instead of a transfer**.
|
||||
- Because isochronous transactions are not retried on failure, the status each completed QTD must be checked.
|
||||
|
||||
|
||||
@ -45,7 +45,7 @@ The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the sta
|
||||
|
||||
1. SDIO reset
|
||||
|
||||
CMD52 (Write 0x6=0x8)
|
||||
CMD52 (Write 0x6 = 0x8)
|
||||
|
||||
2. SD reset
|
||||
|
||||
@ -63,9 +63,9 @@ The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the sta
|
||||
|
||||
**Example:**
|
||||
|
||||
Arg of R4 after first CMD5 (arg=0x00000000) is 0xXXFFFF00.
|
||||
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).
|
||||
Keep sending CMD5 with arg = 0x00FFFF00 until the R4 shows card ready (arg bit 31 = 1).
|
||||
|
||||
5. Set address
|
||||
|
||||
@ -83,35 +83,35 @@ The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the sta
|
||||
|
||||
7. Select 4-bit mode (optional)
|
||||
|
||||
CMD52 (Write 0x07=0x02)
|
||||
CMD52 (Write 0x07 = 0x02)
|
||||
|
||||
8. Enable func1
|
||||
|
||||
CMD52 (Write 0x02=0x02)
|
||||
CMD52 (Write 0x02 = 0x02)
|
||||
|
||||
9. Enable SDIO interrupt (required if interrupt line (DAT1) is used)
|
||||
|
||||
CMD52 (Write 0x04=0x03)
|
||||
CMD52 (Write 0x04 = 0x03)
|
||||
|
||||
10. Set Func0 blocksize (optional, default value is 512 (0x200))
|
||||
|
||||
CMD52/53 (Read 0x10~0x11)
|
||||
CMD52/53 (Read 0x10 ~ 0x11)
|
||||
|
||||
CMD52/53 (Write 0x10=0x00)
|
||||
CMD52/53 (Write 0x10 = 0x00)
|
||||
|
||||
CMD52/53 (Write 0x11=0x02)
|
||||
CMD52/53 (Write 0x11 = 0x02)
|
||||
|
||||
CMD52/53 (Read 0x10~0x11, read to check the final value)
|
||||
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 (Read 0x110 ~ 0x111)
|
||||
|
||||
CMD52/53 (Write 0x110=0x00)
|
||||
CMD52/53 (Write 0x110 = 0x00)
|
||||
|
||||
CMD52/53 (Write 0x111=0x02)
|
||||
CMD52/53 (Write 0x111 = 0x02)
|
||||
|
||||
CMD52/53 (Read 0x110~0x111, read to check the final value)
|
||||
CMD52/53 (Read 0x110 ~ 0x111, read to check the final value)
|
||||
|
||||
|
||||
.. _esp_slave_protocol_layer:
|
||||
@ -177,8 +177,8 @@ The slave responds to data that has a length equal to the length field of CMD53.
|
||||
|
||||
In order to achieve higher efficiency when accessing the FIFO by an arbitrary length, the block and byte modes of CMD53 can be used in combination. For example, given that the block size is set to 512 by default, you can write or get 1031 bytes of data from the FIFO by doing the following:
|
||||
|
||||
1. Send CMD53 in block mode, block count = 2 (1024 bytes) to address 0x1F3F9=0x1F800-**1031**.
|
||||
2. Then send CMD53 in byte mode, byte count = 8 (or 7 if your controller supports that) to address 0x1F7F9=0x1F800-**7**.
|
||||
1. Send CMD53 in block mode, block count = 2 (1024 bytes) to address 0x1F3F9 = 0x1F800 - **1031**.
|
||||
2. Then send CMD53 in byte mode, byte count = 8 (or 7 if your controller supports that) to address 0x1F7F9 = 0x1F800 - **7**.
|
||||
|
||||
.. _esp_sdio_slave_interrupts:
|
||||
|
||||
|
||||
@ -189,7 +189,7 @@ The following events may be posted by the MQTT client:
|
||||
* ``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_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
|
||||
|
||||
@ -101,7 +101,7 @@ If you want to use :cpp:func:`select` with a file descriptor belonging to a non-
|
||||
:cpp:func:`end_select` is called to stop/deinitialize/free the environment which was setup by :cpp:func:`start_select`.
|
||||
|
||||
.. note::
|
||||
|
||||
|
||||
:cpp:func:`end_select` might be called without a previous :cpp:func:`start_select` call in some rare circumstances. :cpp:func:`end_select` should fail gracefully if this is the case (i.e., should not crash but return an error instead).
|
||||
|
||||
Please refer to the reference implementation for the UART peripheral in :component_file:`vfs/vfs_uart.c` and most particularly to the functions :cpp:func:`esp_vfs_dev_uart_register`, :cpp:func:`uart_start_select`, and :cpp:func:`uart_end_select` for more information.
|
||||
@ -180,8 +180,8 @@ File Descriptors
|
||||
File descriptors are small positive integers from ``0`` to ``FD_SETSIZE - 1``, where ``FD_SETSIZE`` is defined in newlib's ``sys/types.h``. The largest file descriptors (configured by ``CONFIG_LWIP_MAX_SOCKETS``) are reserved for sockets. The VFS component contains a lookup-table called ``s_fd_table`` for mapping global file descriptors to VFS driver indexes registered in the ``s_vfs`` array.
|
||||
|
||||
|
||||
Standard IO Streams (stdin, stdout, stderr)
|
||||
-------------------------------------------
|
||||
Standard IO Streams (``stdin``, ``stdout``, ``stderr``)
|
||||
-------------------------------------------------------
|
||||
|
||||
If the menuconfig option ``UART for console output`` is not set to ``None``, then ``stdin``, ``stdout``, and ``stderr`` are configured to read from, and write to, a UART. It is possible to use UART0 or UART1 for standard IO. By default, UART0 is used with 115200 baud rate; TX pin is GPIO1; RX pin is GPIO3. These parameters can be changed in menuconfig.
|
||||
|
||||
@ -216,8 +216,8 @@ Such a design has the following consequences:
|
||||
- Closing default ``stdin``, ``stdout``, or ``stderr`` using ``fclose`` closes the ``FILE`` stream object, which will affect all other tasks.
|
||||
- To change the default ``stdin``, ``stdout``, ``stderr`` streams for new tasks, modify ``_GLOBAL_REENT->_stdin`` (``_stdout``, ``_stderr``) before creating the task.
|
||||
|
||||
Event fds
|
||||
-------------------------------------------
|
||||
``eventfd()``
|
||||
-------------
|
||||
|
||||
``eventfd()`` call is a powerful tool to notify a ``select()`` based loop of custom events. The ``eventfd()`` implementation in ESP-IDF is generally the same as described in `man(2) eventfd <https://man7.org/linux/man-pages/man2/eventfd.2.html>`_ except for:
|
||||
|
||||
|
||||
@ -90,8 +90,8 @@ Application Description
|
||||
The ``DROM`` segment of the application binary starts with the :cpp:type:`esp_app_desc_t` structure which carries specific fields describing the application:
|
||||
|
||||
* ``magic_word`` - the magic word for the esp_app_desc structure.
|
||||
* ``secure_version`` - see :doc:`Anti-rollback</api-reference/system/ota>`.
|
||||
* ``version`` - see :doc:`App version</api-reference/system/misc_system_api>`. ``*``
|
||||
* ``secure_version`` - see :doc:`Anti-rollback </api-reference/system/ota>`.
|
||||
* ``version`` - see :doc:`App version </api-reference/system/misc_system_api>`. ``*``
|
||||
* ``project_name`` is filled from ``PROJECT_NAME``. ``*``
|
||||
* ``time`` and ``date`` - compile time and date.
|
||||
* ``idf_ver`` - version of ESP-IDF. ``*``
|
||||
|
||||
@ -51,12 +51,12 @@ To find the amount of statically allocated memory, use the :ref:`idf.py size <id
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. note::
|
||||
|
||||
.. note::
|
||||
|
||||
See the :ref:`dram` section for more details about the DRAM usage limitations.
|
||||
|
||||
.. note::
|
||||
|
||||
.. note::
|
||||
|
||||
At runtime, the available heap DRAM may be less than calculated at compile time, because, at startup, some memory is allocated from the heap before the FreeRTOS scheduler is started (including memory for the stacks of initial FreeRTOS tasks).
|
||||
|
||||
IRAM
|
||||
@ -126,7 +126,7 @@ Memory allocated with ``MALLOC_CAP_32BIT`` can **only** be accessed via 32-bit r
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
To use the region above the 4 MiB limit, you can use the :doc:`himem API</api-reference/system/himem>`.
|
||||
To use the region above the 4 MiB limit, you can use the :doc:`himem API </api-reference/system/himem>`.
|
||||
|
||||
Thread Safety
|
||||
-------------
|
||||
|
||||
@ -201,7 +201,7 @@ The verification of signed OTA updates can be performed even without enabling ha
|
||||
OTA Tool ``otatool.py``
|
||||
-----------------------
|
||||
|
||||
The component ``app_update`` provides a tool :component_file:`otatool.py<app_update/otatool.py>` for performing OTA partition-related operations on a target device. The following operations can be performed using the tool:
|
||||
The component ``app_update`` provides a tool :component_file:`otatool.py <app_update/otatool.py>` for performing OTA partition-related operations on a target device. The following operations can be performed using the tool:
|
||||
|
||||
- read contents of otadata partition (read_otadata)
|
||||
- erase otadata partition, effectively resetting device to factory app (erase_otadata)
|
||||
|
||||
@ -37,7 +37,7 @@ To re-enable the entropy source temporarily during app startup, or for an applic
|
||||
Secondary Entropy
|
||||
-----------------
|
||||
|
||||
{IDF_TARGET_NAME} RNG contains a secondary entropy source, based on sampling an asynchronous 8MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the `Dieharder`_ random number test suite without the main entropy source enabled (test input was created by concatenating short samples from a continuously resetting {IDF_TARGET_NAME}). However, it is currently only guaranteed that true random numbers are produced when the main entropy source is also enabled as described above.
|
||||
{IDF_TARGET_NAME} RNG contains a secondary entropy source, based on sampling an asynchronous 8 MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the `Dieharder`_ random number test suite without the main entropy source enabled (test input was created by concatenating short samples from a continuously resetting {IDF_TARGET_NAME}). However, it is currently only guaranteed that true random numbers are produced when the main entropy source is also enabled as described above.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
@ -45,8 +45,8 @@ API Reference
|
||||
.. include-build-file:: inc/esp_random.inc
|
||||
.. include-build-file:: inc/bootloader_random.inc
|
||||
|
||||
Getrandom
|
||||
---------
|
||||
``getrandom()``
|
||||
---------------
|
||||
|
||||
A compatible version of the Linux ``getrandom()`` function is also provided for ease of porting:
|
||||
|
||||
@ -62,8 +62,8 @@ The ``flags`` argument is ignored, this function is always non-blocking but the
|
||||
|
||||
Return value is -1 (with ``errno`` set to ``EFAULT``) if the ``buf`` argument is NULL, and equal to ``buflen`` otherwise.
|
||||
|
||||
getentropy
|
||||
----------
|
||||
``getentropy()``
|
||||
----------------
|
||||
|
||||
A compatible version of the Linux ``getentropy()`` function is also provided for ease of porting:
|
||||
|
||||
|
||||
@ -131,7 +131,7 @@ The following config options control TWDT configuration. They are all enabled by
|
||||
Configuration
|
||||
"""""""""""""
|
||||
|
||||
- When the external 32KHz crystal or oscillator is selected (:ref:`CONFIG_RTC_CLK_SRC`) the XTWDT can be enabled via the :ref:`CONFIG_ESP_XT_WDT` configuration option.
|
||||
- When the external 32 KHz crystal or oscillator is selected (:ref:`CONFIG_RTC_CLK_SRC`) the XTWDT can be enabled via the :ref:`CONFIG_ESP_XT_WDT` configuration option.
|
||||
- The timeout is configured by setting the :ref:`CONFIG_ESP_XT_WDT_TIMEOUT` option.
|
||||
- The automatic backup clock functionality is enabled via the ref:`CONFIG_ESP_XT_WDT_BACKUP_CLK_ENABLE` configuration option.
|
||||
|
||||
|
||||
@ -10,13 +10,13 @@ Python 3.8.* or above. This is our recommended Python version for ESP-IDF develo
|
||||
|
||||
If you still have Python versions not compatible, update your Python versions before installing the pre-commit hook.
|
||||
|
||||
Install pre-commit
|
||||
------------------
|
||||
Install ``pre-commit``
|
||||
----------------------
|
||||
|
||||
Run ``pip install pre-commit``
|
||||
|
||||
Install pre-commit Hook
|
||||
-----------------------
|
||||
Install ``pre-commit`` Hook
|
||||
---------------------------
|
||||
|
||||
1. Go to the ESP-IDF project directory.
|
||||
|
||||
@ -24,7 +24,7 @@ Install pre-commit Hook
|
||||
|
||||
3. pre-commit hook will run automatically when you are running ``git commit`` command
|
||||
|
||||
Uninstall pre-commit Hook
|
||||
Uninstall ``pre-commit`` Hook
|
||||
-----------------------------
|
||||
|
||||
Run ``pre-commit uninstall``
|
||||
|
||||
@ -213,7 +213,7 @@ Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
|
||||
Check Port on Linux and macOS
|
||||
-----------------------------
|
||||
|
||||
To check the device name for the serial port of your {IDF_TARGET_NAME} board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
|
||||
To check the device name for the serial port of your {IDF_TARGET_NAME} board (or external converter dongle), run this command two times, first with the board/dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
|
||||
|
||||
Linux ::
|
||||
|
||||
|
||||
@ -360,7 +360,7 @@ When flashing, you will see the output log similar to the following:
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
If there are no issues by the end of the flash process, the board will reboot and start up the “hello_world” application.
|
||||
If there are no issues by the end of the flash process, the board will reboot and start up the "hello_world" application.
|
||||
|
||||
If you would like to use the Eclipse or VS Code IDE instead of running ``idf.py``, check out `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_, `VSCode Extension <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md>`_.
|
||||
|
||||
@ -447,12 +447,12 @@ Now you are ready to try some other :idf:`examples`, or go straight to developin
|
||||
Additional Tips
|
||||
===============
|
||||
|
||||
Permission issues /dev/ttyUSB0
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Permission Issues ``/dev/ttyUSB0``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
With some Linux distributions, you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
|
||||
With some Linux distributions, you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group <linux-dialout-group>`.
|
||||
|
||||
Python compatibility
|
||||
Python Compatibility
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF supports Python 3.8 or newer. It is recommended to upgrade your operating system to a recent version satisfying this requirement. Other options include the installation of Python from `sources <https://www.python.org/downloads/>`_ or the use of a Python version management system such as `pyenv <https://github.com/pyenv/pyenv>`_.
|
||||
|
||||
@ -36,14 +36,14 @@ The easiest way to install ESP-IDF's prerequisites is to download one of ESP-IDF
|
||||
.. _Windows Installer Download: https://dl.espressif.com/dl/esp-idf/?idf=4.4
|
||||
|
||||
|
||||
What is the usecase for Online and Offline Installer
|
||||
What Is the Usecase for Online and Offline Installer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Online Installer is very small and allows the installation of all available releases of ESP-IDF. The installer downloads only necessary dependencies including `Git For Windows`_ during the installation process. The installer stores downloaded files in the cache directory ``%userprofile%\.espressif``
|
||||
|
||||
Offline Installer does not require any network connection. The installer contains all required dependencies including `Git For Windows`_ .
|
||||
|
||||
Components of the installation
|
||||
Components of the Installation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The installer deploys the following components:
|
||||
|
||||
@ -83,7 +83,7 @@ GPIO
|
||||
- The user callback of a GPIO interrupt should no longer read the GPIO interrupt status register to get the GPIO's pin number of triggering the interrupt. You should use the callback argument to determine the GPIO's pin number instead.
|
||||
|
||||
- Previously, when a GPIO interrupt occurs, the GPIO's interrupt status register is cleared after calling the user callbacks. Thus, it was possible for users to read the GPIO's interrupt status register inside the callback to determine which GPIO was used to trigger the interrupt.
|
||||
- However, clearing the interrupt status register after calling the user callbacks can potentially cause edge-triggered interrupts to be lost. For example, if an edge-triggered interrupt (re)is triggered while the user callbacks are being called, that interrupt will be cleared without its registered user callback being handled.
|
||||
- However, clearing the interrupt status register after calling the user callbacks can potentially cause edge-triggered interrupts to be lost. For example, if an edge-triggered interrupt is (re)triggered while the user callbacks are being called, that interrupt will be cleared without its registered user callback being handled.
|
||||
- Now, the GPIO's interrupt status register is cleared **before** invoking the user callbacks. Thus, users can no longer read the GPIO interrupt status register to determine which pin has triggered the interrupt. Instead, users should use the callback argument to pass the pin number.
|
||||
|
||||
.. only:: SOC_SDM_SUPPORTED
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
CLion
|
||||
#####
|
||||
|
||||
What is CLion?
|
||||
What Is CLion?
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
`CLion <https://www.jetbrains.com/clion/>`__ is a cross-platform integrated Development Environment (IDE) for C and C++ programming. CLion also provides dedicated support for ESP-IDF, allowing developers to seamlessly work with the ESP-IDF framework.
|
||||
|
||||
@ -11,7 +11,7 @@ PlatformIO
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
What is PlatformIO?
|
||||
What Is PlatformIO?
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`PlatformIO <https://platformio.org/?utm_source=docs.espressif.com>`__
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
VisualGDB
|
||||
#########
|
||||
|
||||
What is VisualGDB?
|
||||
What Is VisualGDB?
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`VisualGDB <https://visualgdb.com/>`__ is a powerful extension for Microsoft Visual Studio that provides advanced development tools and features for embedded systems, including support for the ESP-IDF framework. VisualGDB allows you to leverage the familiar and feature-rich Visual Studio environment for your ESP-IDF projects, enabling efficient coding, debugging, and deployment.
|
||||
|
||||
@ -106,7 +106,7 @@ During the Service period, bugfixes releases are more frequent. In some cases, s
|
||||
|
||||
During the Maintenance period, the version is still supported but only bugfixes for high severity issues or security issues will be applied.
|
||||
|
||||
Using an “In Service” version is recommended when starting a new project.
|
||||
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.
|
||||
|
||||
@ -127,7 +127,7 @@ The local ESP-IDF version can be checked by using idf.py::
|
||||
|
||||
The ESP-IDF version is also compiled into the firmware and can be accessed (as a string) via the macro ``IDF_VER``. The default ESP-IDF bootloader will print the version on boot (the version information is not always updated if the code in the GitHub repo is updated, it only changes if there is a clean build or if that particular source file is recompiled).
|
||||
|
||||
If writing code that needs to support multiple ESP-IDF versions, the version can be checked at compile time using :ref:`compile-time macros<idf-version-h>`.
|
||||
If writing code that needs to support multiple ESP-IDF versions, the version can be checked at compile time using :ref:`compile-time macros <idf-version-h>`.
|
||||
|
||||
Examples of ESP-IDF versions:
|
||||
|
||||
@ -160,7 +160,7 @@ The development (Git) workflow of the Espressif ESP-IDF team is as follows:
|
||||
- Once testing is nearly complete a new release candidate is tagged on the release branch, for example ``v3.1-rc1``. This is still a pre-release version.
|
||||
- If no more significant bugs are found or reported, then the final Major or Minor Version is tagged, for example ``v3.1``. This version appears on the `Releases page`_.
|
||||
- As bugs are reported in released versions, the fixes will continue to be committed to the same release branch.
|
||||
- Regular bugfix releases are made from the same release branch. After manual testing is complete, a bugfix release is tagged (i.e. ``v3.1.1``) and appears on the `Releases page`_.
|
||||
- Regular bugfix releases are made from the same release branch. After manual testing is complete, a bugfix release is tagged (i.e., ``v3.1.1``) and appears on the `Releases page`_.
|
||||
|
||||
|
||||
.. _updating:
|
||||
|
||||
@ -171,8 +171,8 @@ ESP-IDF 希望应用程序入口点 ``app_main`` 以 C 链接定义。当 ``app_
|
||||
C 和 C++ 语言对于指定初始化器有不同的规则。例如，C++23（当前在 ESP-IDF 中默认使用）不支持无序指定初始化、嵌套指定初始化、混合使用指定初始化器和常规初始化器，而对数组进行指定初始化。因此，当将 ESP-IDF 的 C 示例移植到 C++ 时，可能需要对结构体初始化器进行一些更改。详细信息请参阅 `C++ aggregate initialization reference <https://en.cppreference.com/w/cpp/language/aggregate_initialization>`_。
|
||||
|
||||
|
||||
iostream
|
||||
^^^^^^^^
|
||||
``iostream``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
ESP-IDF 支持 ``iostream`` 功能，但应注意：
|
||||
|
||||
|
||||
@ -180,8 +180,8 @@ VFS 对文件路径长度没有限制，但文件系统路径前缀受 ``ESP_VFS
|
||||
文件描述符是一组很小的正整数，从 ``0`` 到 ``FD_SETSIZE - 1``，``FD_SETSIZE`` 在 newlib ``sys/types.h`` 中定义。最大文件描述符由 ``CONFIG_LWIP_MAX_SOCKETS`` 定义，且为套接字保留。VFS 中包含一个名为 ``s_fd_table`` 的查找表，用于将全局文件描述符映射至 ``s_vfs`` 数组中注册的 VFS 驱动索引。
|
||||
|
||||
|
||||
标准 IO 流 (stdin, stdout, stderr)
|
||||
-------------------------------------------
|
||||
标准 IO 流 (``stdin``, ``stdout``, ``stderr``)
|
||||
----------------------------------------------------
|
||||
|
||||
如果 menuconfig 中 ``UART for console output`` 选项没有设置为 ``None``，则 ``stdin``、 ``stdout`` 和 ``stderr`` 将默认从 UART 读取或写入。UART0 或 UART1 可用作标准 IO。默认情况下，UART0 使用 115200 波特率，TX 管脚为 GPIO1，RX 管脚为 GPIO3。上述参数可以在 menuconfig 中更改。
|
||||
|
||||
@ -216,8 +216,8 @@ VFS 还为输入和输出提供换行符转换功能（可选）。多数应用
|
||||
- 但使用 ``fclose`` 关闭默认 ``stdin``、 ``stdout`` 或 ``stderr`` 将同时关闭相应的 ``FILE`` 流对象，因此会影响其他任务；
|
||||
- 如需更改新任务的默认 ``stdin``、 ``stdout`` 和 ``stderr`` 流，请在创建新任务之前修改 ``_GLOBAL_REENT->_stdin`` (``_stdout``、``_stderr``)。
|
||||
|
||||
Event fds
|
||||
-------------------------------------------
|
||||
``eventfd()``
|
||||
-------------
|
||||
|
||||
``eventfd()`` 是一个很强大的工具，可以循环通知基于 ``select()`` 的自定义事件。在 ESP-IDF 中， ``eventfd()`` 的实现大体上与 `man(2) eventfd <https://man7.org/linux/man-pages/man2/eventfd.2.html>`_ 中的描述相同，主要区别如下：
|
||||
|
||||
|
||||
@ -10,12 +10,12 @@
|
||||
|
||||
如果你已安装了不兼容的 Python 版本，应在安装 pre-commit 工具前进行更新。
|
||||
|
||||
安装 pre-commit 工具
|
||||
安装 ``pre-commit`` 工具
|
||||
---------------------------
|
||||
|
||||
运行 ``pip install pre-commit`` 。
|
||||
|
||||
安装 pre-commit 钩子
|
||||
安装 ``pre-commit`` 钩子
|
||||
----------------------------
|
||||
|
||||
1. 切换到 IDF 项目路径。
|
||||
@ -24,8 +24,8 @@
|
||||
|
||||
3. 在运行 ``git commit`` 命令时，pre-commit 钩子会自动运行。
|
||||
|
||||
卸载 pre-commit 钩子
|
||||
----------------------
|
||||
卸载 ``pre-commit`` 钩子
|
||||
---------------------------
|
||||
|
||||
运行 ``pre-commit uninstall`` 。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user