docs: update format issues left in EN docs

This commit is contained in:
caixinying-git
2023-09-13 17:05:23 +08:00
committed by BOT
parent a9349f4ad4
commit b07ada6e94
35 changed files with 120 additions and 120 deletions

View File

@ -1,6 +1,6 @@
:orphan:
Page not Found
Page Not Found
==============
:link_to_translation:`zh_CN:[中文]`

View File

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

View File

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

View File

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

View File

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

View File

@ -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()``.

View File

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

View File

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

View File

@ -55,7 +55,7 @@ To install a PCNT unit, there is a configuration structure that needs to be give
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:

View File

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

View File

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

View File

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

View File

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

View File

@ -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>`.
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>`_.

View File

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

View File

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

View File

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

View File

@ -11,7 +11,7 @@ PlatformIO
.. contents::
:local:
What is PlatformIO?
What Is PlatformIO?
~~~~~~~~~~~~~~~~~~~
`PlatformIO <https://platformio.org/?utm_source=docs.espressif.com>`__

View File

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

View File

@ -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.
@ -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:

View File

@ -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`` 功能,但应注意:

View File

@ -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 管脚为 GPIO1RX 管脚为 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>`_ 中的描述相同,主要区别如下:

View File

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