pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update document format issues

Browse Source
This commit is contained in:
Cai Xin Ying
2023-10-14 03:55:41 +08:00
committed by Dai Zi Yan
parent e19324b4fa
commit 01209e459c
47 changed files with 245 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh_CN/api-reference/network/esp_now.rst
+4 -4
View File
@@ -22,7 +22,7 @@ ESP-NOW 使用各个供应商的动作帧传输数据，默认比特率为 1 Mbp
-----------------------------------------------------------------------------------------
| MAC 报头 | 分类代码 | 组织标识符 | 随机值 | 供应商特定内容 | FCS |
-----------------------------------------------------------------------------------------
24 字节 1 字节 3 字节 4 字节 7~257 字节 4 字节
24 字节 1 字节 3 字节 4 字节 7-257 字节 4 字节
- 分类代码：分类代码字段可用于指示各个供应商的类别（比如 127）。
- 组织标识符：组织标识符包含一个唯一标识符（比如 0x18fe34），为乐鑫指定的 MAC 地址的前三个字节。
@@ -36,7 +36,7 @@ ESP-NOW 使用各个供应商的动作帧传输数据，默认比特率为 1 Mbp
----------------------------------------------------------------------------------------
| 元素 ID | 长度 | 组织标识符 | 类型 | 版本 | 正文 |
----------------------------------------------------------------------------------------
1 字节 1 字节 3 字节 1 字节 1 字节 0～250 字节
1 字节 1 字节 3 字节 1 字节 1 字节 0-250 字节
- 元素 ID：元素 ID 字段可用于指示特定于供应商的元素。
- 长度：长度是组织标识符、类型、版本和正文的总长度。
@@ -54,7 +54,7 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
* PMK 可使用 AES-128 算法加密 LMK。请调用 :cpp:func:`esp_now_set_pmk()` 设置 PMK。如果未设置 PMK，将使用默认 PMK。
* LMK 可通过 CCMP 方法对供应商特定的动作帧进行加密，最多拥有 6 个不同的 LMK。如果未设置配对设备的 LMK，则动作帧不进行加密。
目前，不支持加密组播供应商特定的动作帧。
初始化和反初始化
@@ -100,7 +100,7 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
调用 :cpp:func:`esp_wifi_config_espnow_rate()` 配置指定接口的 ESP-NOW 速率。确保在配置速率之前启用接口。这个 API 应该在 :cpp:func:`esp_wifi_start()` 之后调用。
.. only:: esp32c6
调用 :cpp:func:`esp_now_set_peer_rate_config()` 配置指定 peer 的 ESP-NOW 速率。确保在配置速率之前添加 peer。这个 API 应该在 :cpp:func:`esp_wifi_start()` 和 :cpp:func:`esp_now_add_peer()` 之后调用。
.. note::
docs/zh_CN/api-reference/peripherals/usb_host.rst
+1 -1
View File
@@ -29,7 +29,7 @@ USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供
- 支持四种传输类型，即控制传输、块传输、中断传输和同步传输。
- 支持多个 Class 驱动程序同时运行，即主机的多个客户端同时运行。
- 单个设备可以由多个客户端同时使用，如复合设备。
- 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``(运行中的主机 Class 驱动程序数量 + 1)``。
- 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``（运行中的主机 Class 驱动程序数量 + 1）``。
目前，主机库及其底层主机栈存在以下限制：
docs/zh_CN/api-reference/protocols/esp_sdio_slave_protocol.rst
+2 -2
View File
@@ -5,7 +5,7 @@ ESP SDIO 主从机通信
本文档介绍了 ESP 数字输入输出 (Secure Digital Input and Output，SDIO) 从机设备的初始化过程，并提供 ESP SDIO 从机协议的详细信息。该协议为非标准协议，允许 SDIO 主机与 ESP SDIO 从机进行通信。
创建 ESP SDIO 从机协议是为了实现 SDIO 主机和从机之间的通信。 这是因为 SDIO 规范只说明了如何访问卡的自定义区（向功能 1-7 发送 CMD52 和 CMD53），却没有说明底层的硬件实现过程。
创建 ESP SDIO 从机协议是为了实现 SDIO 主机和从机之间的通信。这是因为 SDIO 规范只说明了如何访问卡的自定义区（向功能 1-7 发送 CMD52 和 CMD53），却没有说明底层的硬件实现过程。
.. _esp_sdio_slave_caps:
@@ -41,7 +41,7 @@ ESP SDIO 主从机通信
初始化 ESP SDIO 从机
-------------------------
主机需按照标准的 SDIO 初始化流程，对 {IDF_TARGET_NAME} SDIO 从机进行初始化（参考 `SDIO Simplified Specification <https://www.sdcard.org/downloads/pls/>`_ 3.1.2 章节）。下文将 SDIO 从机简称为 (SD)IO 卡。以下是 ESP SDIO 从机初始化流程的一个简单示例：
主机需按照标准的 SDIO 初始化流程，对 {IDF_TARGET_NAME} SDIO 从机进行初始化（参考 `SDIO Simplified Specification <https://www.sdcard.org/downloads/pls/>`_ 3.1.2 章节）。下文将 SDIO 从机简称为 SD/SDIO 卡。以下是 ESP SDIO 从机初始化流程的一个简单示例：
1. SDIO 复位
docs/zh_CN/api-reference/protocols/esp_spi_slave_protocol.rst
+3 -3
View File
@@ -41,7 +41,7 @@ ESP SPI 从机 HD（半双工）模式协议
- 地址阶段：8 位，主机到从机，可选
对于某些命令 (如 WRBUF、RDBUF)，此阶段指定要写入/读取的共享寄存器地址。对于其他包括此阶段的命令，这没有实际意义，但仍必须存在于事务中。
对于某些命令（如 WRBUF、RDBUF），此阶段指定要写入/读取的共享寄存器地址。对于其他包括此阶段的命令，这没有实际意义，但仍必须存在于事务中。
- Dummy 阶段：8 位，浮动，可选
@@ -56,7 +56,7 @@ ESP SPI 从机 HD（半双工）模式协议
数据 IO 模式
-------------
在某些 IO 模式下，可以使用更多数据线来发送数据。因此，与 1 位模式相比，发送相同数据量所需的 SPI 时钟周期更少。例如，在 QIO 模式下，地址和数据 (IN 和 OUT) 应发送到全部 4 条数据线上 (MOSI、MISO、WP 和 HD)。下表展示了 ESP32-S2 SPI 从机支持的模式，以及相应模式下使用的数据线数量。
在某些 IO 模式下，可以使用更多数据线来发送数据。因此，与 1 位模式相比，发送相同数据量所需的 SPI 时钟周期更少。例如，在 QIO 模式下，地址和数据（IN 和 OUT）应发送到全部 4 条数据线上（MOSI、MISO、WP 和 HD）。下表展示了 ESP32-S2 SPI 从机支持的模式，以及相应模式下使用的数据线数量。
+-------+----------+----------+------------+----------+
| Mode | 命令线数 | 地址线数 | dummy 次数 | 数据线数 |
@@ -115,7 +115,7 @@ QPI 模式是 SPI 从机的一种特殊状态。主机可发送 ENQPI 命令，
| EXQPI | 退出 QPI 模式 | 0xDD | - | - |
+----------+---------------+------+----------+------------------------------+
此外，WRBUF、RDBUF、WRDMA 和 RDDMA 命令都有 2 位和 4 位版本。要在 2 位或 4 位模式下操作，请用下表中的对应命令掩码与原始命令按位或（bit OR）后发送。例如，命令 0xA1 表示 QIO 模式下的 WRBUF。
此外，WRBUF、RDBUF、WRDMA 和 RDDMA 命令都有 2 位和 4 位版本。要在 2 位或 4 位模式下操作，请用下表中的对应命令掩码与原始命令按位或 (bit OR) 后发送。例如，命令 0xA1 表示 QIO 模式下的 WRBUF。
+-------+------+
| 模式 | 掩码 |
docs/zh_CN/api-reference/storage/index.rst
+8 -8
View File
@@ -3,20 +3,20 @@
:link_to_translation:`en:[English]`
本节提供高层次的存储 API 的参考文档。这些 API 基于如 SPI Flash、SD/MMC 等低层次驱动。
本节提供高层次的存储 API 的参考文档。这些 API 基于如 SPI flash、SD/MMC 等低层次驱动。
- :doc:`分区表 API <partition>` 基于 :doc:`分区表 </api-guides/partition-tables>` ，允许以块为单位访问 SPI Flash。
- :doc:`非易失性存储库 (NVS) <nvs_flash>` 在 SPI NOR Flash 上实现了一个有容错性，和磨损均衡功能的键值对存储。
- :doc:`分区表 API <partition>` 基于 :doc:`/api-guides/partition-tables` ，允许以块为单位访问 SPI flash。
- :doc:`非易失性存储库 (NVS) <nvs_flash>` 在 SPI NOR flash 上实现了一个有容错性，和磨损均衡功能的键值对存储。
- :doc:`虚拟文件系统 (VFS) <vfs>` 库提供了一个用于注册文件系统驱动的接口。SPIFFS、FAT 以及多种其他的文件系统库都基于 VFS。
- :doc:`SPIFFS <spiffs>` 是一个专为 SPI NOR Flash 优化的磨损均衡的文件系统，非常适用于小分区和低吞吐率的应用。
- :doc:`FAT <fatfs>` 是一个可用于 SPI Flash 或者 SD/MMC 存储卡的标准文件系统。
- :doc:`磨损均衡 <wear-levelling>` 库实现了一个适用于 SPI NOR Flash 的 flash 翻译层 (FTL)，用于 flash 中 FAT 分区的容器。
- :doc:`SPIFFS <spiffs>` 是一个专为 SPI NOR flash 优化的磨损均衡的文件系统，非常适用于小分区和低吞吐率的应用。
- :doc:`FAT <fatfs>` 是一个可用于 SPI flash 或者 SD/MMC 存储卡的标准文件系统。
- :doc:`磨损均衡 <wear-levelling>` 库实现了一个适用于 SPI NOR flash 的 flash 翻译层 (FTL)，用于 flash 中 FAT 分区的容器。
.. note::
建议使用高层次的 API（``esp_partition`` 或者文件系统）而非低层次驱动 API 去访问 SPI NOR Flash。
建议使用高层次的 API（``esp_partition`` 或者文件系统）而非低层次驱动 API 去访问 SPI NOR flash。
由于 NOR Flash 和乐鑫硬件的一些限制，访问主 flash 会影响各个系统的性能。关于这些限制的更多信息，参见 :doc:`SPI Flash Documents </api-reference/peripherals/spi_flash/index>`。
由于 NOR flash 和乐鑫硬件的一些限制，访问主 flash 会影响各个系统的性能。关于这些限制的更多信息，参见 :doc:`/api-reference/peripherals/spi_flash/index`。
.. toctree::
:maxdepth: 1
docs/zh_CN/api-reference/storage/partition.rst
+5 -5
View File
@@ -6,14 +6,14 @@
概述
--------
``esp_partition`` 组件提供了高层次的 API 函数，用于访问定义在 :doc:`分区表 </api-guides/partition-tables>` 中的分区。这些 API 基于 :doc:`SPI Flash 驱动 </api-reference/peripherals/spi_flash/index>` 提供的低层次 API。
``esp_partition`` 组件提供了高层次的 API 函数，用于访问定义在 :doc:`/api-guides/partition-tables` 中的分区。这些 API 基于 :doc:`/api-reference/peripherals/spi_flash/index` 提供的低层次 API。
.. _flash-partition-apis:
分区表 API
-------------------
ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序、各种应用程序二进制文件、数据及文件系统等。请参阅 :doc:`分区表 </api-guides/partition-tables>`，查看详细信息。
ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序、各种应用程序二进制文件、数据及文件系统等。请参阅 :doc:`/api-guides/partition-tables`，查看详细信息。
该组件在 ``esp_partition.h`` 中声明了一些 API 函数，用以枚举在分区表中找到的分区，并对这些分区执行操作：
@@ -28,9 +28,9 @@ ESP-IDF 工程使用分区表保存 SPI flash 各区信息，包括引导程序
另请参考
------------
- :doc:`分区表 <../../api-guides/partition-tables>`
- :doc:`OTA API <../system/ota>` 提供了高层 API 用于更新存储在 flash 中的 app 固件。
- :doc:`NVS API <nvs_flash>` 提供了结构化 API 用于存储 SPI flash 中的碎片数据。
- :doc:`../../api-guides/partition-tables`
- :doc:`../system/ota` 提供了高层 API 用于更新存储在 flash 中的 app 固件。
- :doc:`nvs_flash` 提供了结构化 API 用于存储 SPI flash 中的碎片数据。
.. _api-reference-partition-table:
docs/zh_CN/api-reference/system/esp_https_ota.rst
+1 -1
View File
@@ -48,7 +48,7 @@ ESP HTTPS OTA 升级
在从 AWS S3 等服务获取镜像时，这一选项非常有用。在启用该选项时， 可以将 mbedTLS Rx 的 buffer 大小（即 :ref:`CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN`）设置为较小的值。不启用此配置时，无法将其设置为较小值。
mbedTLS Rx buffer 的默认大小为 16 K，但如果将 ``partial_http_download`` 的 ``max_http_request_size`` 设置为 4 K，便能将 mbedTLS Rx 的 buffer 减小到 4 K。使用这一配置方式预计可以节省约 12 K 内存。
mbedTLS Rx buffer 的默认大小为 16 KB，但如果将 ``partial_http_download`` 的 ``max_http_request_size`` 设置为 4 KB，便能将 mbedTLS Rx 的 buffer 减小到 4 KB。使用这一配置方式预计可以节省约 12 KB 内存。
签名验证
docs/zh_CN/api-reference/system/inc/power_management_esp32.rst
+1 -1
View File
@@ -1,5 +1,5 @@
+---------------+---------------------------------------+-------------------------------------+
| CPU最高频率 | 电源管理锁获取情况 | APB 频率和 CPU 频率 |
| CPU 最高频率 | 电源管理锁获取情况 | APB 频率和 CPU 频率 |
| | | |
+---------------+---------------------------------------+-------------------------------------+
| 240 | | 获取 ``ESP_PM_CPU_FREQ_MAX`` | |
docs/zh_CN/api-reference/system/ota.rst
+7 -7
View File
@@ -8,7 +8,7 @@ OTA 流程概览
OTA 升级机制可以让设备在固件正常运行时根据接收数据（如通过 Wi-Fi 或蓝牙）进行自我更新。
要运行 OTA 机制，需配置设备的 :doc:`分区表 <../../api-guides/partition-tables>`，该分区表至少包括两个 OTA 应用程序分区（即 ``ota_0`` 和 ``ota_1``）和一个 OTA 数据分区。
要运行 OTA 机制，需配置设备的 :doc:`../../api-guides/partition-tables`，该分区表至少包括两个 OTA 应用程序分区（即 ``ota_0`` 和 ``ota_1``）和一个 OTA 数据分区。
OTA 功能启动后，向当前未用于启动的 OTA 应用分区写入新的应用固件镜像。镜像验证后，OTA 数据分区更新，指定在下一次启动时使用该镜像。
@@ -17,7 +17,7 @@ OTA 功能启动后，向当前未用于启动的 OTA 应用分区写入新的
OTA 数据分区
------------
所有使用 OTA 功能项目，其 :doc:`分区表 <../../api-guides/partition-tables>` 必须包含一个 OTA 数据分区（类型为 ``data``，子类型为 ``ota``）。
所有使用 OTA 功能项目，其 :doc:`../../api-guides/partition-tables` 必须包含一个 OTA 数据分区（类型为 ``data``，子类型为 ``ota``）。
工厂启动设置下，OTA 数据分区中应没有数据（所有字节擦写成 0xFF）。如果分区表中有工厂应用程序，ESP-IDF 软件引导加载程序会启动工厂应用程序。如果分区表中没有工厂应用程序，则启动第一个可用的 OTA 分区（通常是 ``ota_0``）。
@@ -201,7 +201,7 @@ Kconfig 中的 :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` 可以帮助用户
OTA 工具 ``otatool.py``
----------------------------
``app_update`` 组件中有 :component_file:`otatool.py<app_update/otatool.py>` 工具，用于在目标设备上完成下列 OTA 分区相关操作：
``app_update`` 组件中有 :component_file:`app_update/otatool.py` 工具，用于在目标设备上完成下列 OTA 分区相关操作：
- 读取 otadata 分区 (read_otadata)
- 擦除 otadata 分区，将设备复位至工厂应用程序 (erase_otadata)
@@ -297,10 +297,10 @@ Python API
相关文档
--------
* :doc:`分区表 <../../api-guides/partition-tables>`
* :doc:`分区表 API <../storage/partition>`
* :doc:`低层 SPI Flash API <../peripherals/spi_flash/index>`
* :doc:`ESP HTTPS OTA <esp_https_ota>`
* :doc:`../../api-guides/partition-tables`
* :doc:`../storage/partition`
* :doc:`../peripherals/spi_flash/index`
* :doc:`esp_https_ota`
应用程序示例
------------
docs/zh_CN/api-reference/system/system_time.rst
+1 -1
View File
@@ -5,7 +5,7 @@
{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz", esp32h2="150 kHz"}
{IDF_TARGET_INT_OSC_FRE:default="未更新", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"}
{IDF_TARGET_INT_OSC_FRE_DIVIDED:default="未更新", esp32="~33 kHz", esp32s2="~33 kHz", esp32s3="~68 kHz", esp32c3="~68 kHz", esp32c2="~68 kHz"}
{IDF_TARGET_INT_OSC_FRE_DIVIDED:default="未更新", esp32="约 33 kHz", esp32s2="约 33 kHz", esp32s3="约 68 kHz", esp32c3="约 68 kHz", esp32c2="约 68 kHz"}
{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N", esp32c6="XTAL_32K_P 和 XTAL_32K_N", esp32h2="XTAL_32K_P 和 XTAL_32K_N"}
{IDF_TARGET_EXT_OSC_PIN:default="未更新", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"}
{IDF_TARGET_HARDWARE_DESIGN_URL:default="未更新", esp32="`ESP32 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s2="`ESP32-S2 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s3="`ESP32-S3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_cn.pdf#page=12>`_", esp32c3="`ESP32-C3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_cn.pdf#page=9>`_", esp32c2="`ESP8684 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp8684_hardware_design_guidelines_cn.pdf#page=10>`_", esp32c6="`ESP32-C6 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-c6_hardware_design_guidelines_cn.pdf#page=12>`_", esp32h2="`ESP32-H2 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-h2_hardware_design_guidelines_cn.pdf#page=11>`_"}