docs: update format issues for EN and CN files under api-reference/network folder and api-reference folder
This commit is contained in:
Cai Xin Ying
@@ -3,7 +3,7 @@ ESP-WIFI-MESH 编程指南
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
这是 ESP-WIFI-MESH 的编程指南，包括 API 参考和编码示例。本指南分为以下部分：
|
||||
本文是 ESP-WIFI-MESH 的编程指南，包括 API 参考和编码示例。本指南分为以下部分：
|
||||
|
||||
1. :ref:`mesh-programming-model`
|
||||
|
||||
@@ -58,6 +58,7 @@ ESP-WIFI-MESH 软件栈基于 Wi-Fi 驱动程序和 FreeRTOS 构建，某些情
|
||||
Mesh 事件的典型应用场景包括：使用 :cpp:enumerator:`MESH_EVENT_PARENT_CONNECTED` 和 :cpp:enumerator:`MESH_EVENT_CHILD_CONNECTED` 事件来指示节点何时可以分别开始传输上行和下行的数据。同样，也可以使用 :cpp:enumerator:`IP_EVENT_STA_GOT_IP` 和 :cpp:enumerator:`IP_EVENT_STA_LOST_IP` 事件来指示根节点何时可以向外部 IP 网络传输数据。
|
||||
|
||||
.. warning::
|
||||
|
||||
在自组网模式下使用 ESP-WIFI-MESH 时，用户必须确保不得调用 Wi-Fi API。原因在于：自组网模式将在内部调用 Wi-Fi API 实现连接/断开/扫描等操作。 **此时，如果外部应用程序调用 Wi-Fi API（包括来自回调函数和 Wi-Fi 事件处理程序的调用）都可能会干扰 ESP-WIFI-MESH 的自组网行为**。因此，用户不应该在 :cpp:func:`esp_mesh_start` 和 :cpp:func:`esp_mesh_stop` 之间调用 Wi-Fi API。
|
||||
|
||||
LwIP & ESP-WIFI-MESH
|
||||
@@ -68,7 +69,7 @@ LwIP & ESP-WIFI-MESH
|
||||
**可成为根节点的每个节点都需要通过调用** :cpp:func:`esp_netif_init` **来初始化 LwIP 软件栈**。为了防止非根节点访问 LwIP，应用程序不应使用 esp_netif API 创建或注册任何网络接口。
|
||||
|
||||
|
||||
ESP-WIFI-MESH 的根节点必须与路由器连接。因此，当一个节点成为根节点时，**该节点对应的处理程序必须启动 DHCP 客户端服务并立即获取 IP 地址。** 这样做将允许其他节点开始向/从外部 IP 网络发送/接收数据包。但是，如果使用静态 IP 设置，则不需要执行此步骤。
|
||||
ESP-WIFI-MESH 的根节点必须与路由器连接。因此，当一个节点成为根节点时，**该节点对应的处理程序必须启动 DHCP 客户端服务并立即获取 IP 地址**。这样做将允许其他节点开始向/从外部 IP 网络发送/接收数据包。如果使用静态 IP 设置，则不需要执行此步骤。
|
||||
|
||||
|
||||
.. ---------------------- Writing a Mesh Application --------------------------
|
||||
@@ -84,13 +85,13 @@ ESP-WIFI-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。
|
||||
|
||||
ESP_ERROR_CHECK(esp_netif_init());
|
||||
|
||||
/*事件初始化*/
|
||||
/* 事件初始化 */
|
||||
ESP_ERROR_CHECK(esp_event_loop_create_default());
|
||||
|
||||
/*Wi-Fi 初始化 */
|
||||
/* Wi-Fi 初始化 */
|
||||
wifi_init_config_t config = WIFI_INIT_CONFIG_DEFAULT();
|
||||
ESP_ERROR_CHECK(esp_wifi_init(&config));
|
||||
/*注册 IP 事件处理程序 */
|
||||
/* 注册 IP 事件处理程序 */
|
||||
ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &ip_event_handler, NULL));
|
||||
ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_FLASH));
|
||||
ESP_ERROR_CHECK(esp_wifi_start());
|
||||
@@ -110,9 +111,9 @@ ESP-WIFI-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/*Mesh 初始化 */
|
||||
/* Mesh 初始化 */
|
||||
ESP_ERROR_CHECK(esp_mesh_init());
|
||||
/*注册 mesh 事件处理程序 */
|
||||
/* 注册 mesh 事件处理程序 */
|
||||
ESP_ERROR_CHECK(esp_event_handler_register(MESH_EVENT, ESP_EVENT_ANY_ID, &mesh_event_handler, NULL));
|
||||
|
||||
.. _mesh-configuring-mesh:
|
||||
@@ -197,7 +198,7 @@ ESP-WIFI-MESH 可通过 :cpp:func:`esp_mesh_set_config` 进行配置，并使用
|
||||
- 选择首选的父节点（见 :ref:`mesh-building-a-network` 中的 **父节点选择**）
|
||||
- 网络断开时自动重新连接（见 :ref:`mesh-managing-a-network` 中的 **中间父节点失败**）
|
||||
|
||||
启用自组网功能后，ESP-WIFI-MESH 软件栈将内部调用 Wi-Fi API。因此，**在启用自组网功能时，应用层不得调用 Wi-Fi API，否则会干扰 ESP-WIFI-MESH 的工作。**
|
||||
启用自组网功能后，ESP-WIFI-MESH 软件栈将内部调用 Wi-Fi API。因此，**在启用自组网功能时，应用层不得调用 Wi-Fi API，否则会干扰 ESP-WIFI-MESH 的工作**。
|
||||
|
||||
开关自组网
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -262,7 +263,7 @@ ESP-WIFI-MESH 将尝试在启用自组网时保持节点的当前 Wi-Fi 状态
|
||||
调用 Wi-Fi API
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
在有些情况下，应用程序可能希望在使用 ESP-WIFI-MESH 期间调用 Wi-Fi API。例如，应用程序可能需要手动扫描邻近的接入点 (AP)。**但在应用程序调用任何 Wi-Fi API 之前，必须先禁用自组网。** 否则，ESP-WIFI-MESH 软件栈可能会同时调用 Wi-Fi API，进而影响应用程序的正常调用。
|
||||
在有些情况下，应用程序可能希望在使用 ESP-WIFI-MESH 期间调用 Wi-Fi API。例如，应用程序可能需要手动扫描邻近的接入点 (AP)。**但在应用程序调用任何 Wi-Fi API 之前，必须先禁用自组网**。 否则，ESP-WIFI-MESH 软件栈可能会同时调用 Wi-Fi API，进而影响应用程序的正常调用。
|
||||
|
||||
应用程序不应在 :cpp:func:`esp_mesh_set_self_organized` 之间调用 Wi-Fi API。下方代码片段展示了应用程序如何在 ESP-WIFI-MESH 运行期间安全地调用 :cpp:func:`esp_wifi_scan_start`。
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
以太网
|
||||
=========
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. -------------------------------- Overview -----------------------------------
|
||||
|
||||
@@ -113,13 +113,13 @@ ESP-IDF 提供一系列功能强大且兼具一致性的 API，为内部以太
|
||||
|
||||
MII 和 RMII 的一个明显区别在于其所需的信号数。MII 通常需要多达 18 个信号，RMII 接口则仅需要 9 个信号。
|
||||
|
||||
在 RMII 模式下，接收器和发射器信号的参考时钟为 ``REF_CLK``。 **在访问 PHY 和 MAC 时，REF_CLK 必须保持稳定**。一般来说，根据您设计中 PHY 设备的特征，可通过以下三种方式生成 ``REF_CLK``：
|
||||
在 RMII 模式下，接收器和发射器信号的参考时钟为 ``REF_CLK``。 **在访问 PHY 和 MAC 时，REF_CLK 必须保持稳定**。一般来说，根据设计中 PHY 设备的特征，可通过以下三种方式生成 ``REF_CLK``：
|
||||
|
||||
* 一些 PHY 芯片可以从其外部连接的 25 MHz 晶体振荡器中获取 ``REF_CLK`` （如图中的选项 *a* 所示）。对于此类芯片，请在 :ref:`CONFIG_ETH_RMII_CLK_MODE` 中选择 ``CONFIG_ETH_RMII_CLK_INPUT``。
|
||||
* 一些 PHY 芯片可以从其外部连接的 25 MHz 晶体振荡器中获取 ``REF_CLK`` （如图中的选项 **a** 所示）。对于此类芯片，请在 :ref:`CONFIG_ETH_RMII_CLK_MODE` 中选择 ``CONFIG_ETH_RMII_CLK_INPUT``。
|
||||
|
||||
* 一些 PHY 芯片使用可以作为 MAC 端 ``REF_CLK`` 的外接 50 MHz 晶体振荡器或其他时钟源（如图中的选项 *b* 所示）。对于此类芯片，请同样在 :ref:`CONFIG_ETH_RMII_CLK_MODE` 中选择 ``CONFIG_ETH_RMII_CLK_INPUT``。
|
||||
* 一些 PHY 芯片使用可以作为 MAC 端 ``REF_CLK`` 的外接 50 MHz 晶体振荡器或其他时钟源（如图中的选项 **b** 所示）。对于此类芯片，请同样在 :ref:`CONFIG_ETH_RMII_CLK_MODE` 中选择 ``CONFIG_ETH_RMII_CLK_INPUT``。
|
||||
|
||||
* 一些 EMAC 控制器可以使用其内部的高精度 PLL 生成 ``REF_CLK`` （如图中的选项 *c* 所示）。此种情况下，请在 :ref:`CONFIG_ETH_RMII_CLK_MODE` 中选择 ``CONFIG_ETH_RMII_CLK_OUTPUT``。
|
||||
* 一些 EMAC 控制器可以使用其内部的高精度 PLL 生成 ``REF_CLK`` （如图中的选项 **c** 所示）。此种情况下，请在 :ref:`CONFIG_ETH_RMII_CLK_MODE` 中选择 ``CONFIG_ETH_RMII_CLK_OUTPUT``。
|
||||
|
||||
.. note::
|
||||
如上所述，``REF_CLK`` 默认通过项目配置进行配置。然而，通过设置 :cpp:member:`eth_esp32_emac_config_t::interface` 和 :cpp:member:`eth_esp32_emac_config_t::clock_config`，也可以实现在用户应用代码中覆盖该时钟。更多细节，请参见 :cpp:enum:`emac_rmii_clock_mode_t` 和 :cpp:enum:`emac_rmii_clock_gpio_t`。
|
||||
@@ -127,15 +127,15 @@ ESP-IDF 提供一系列功能强大且兼具一致性的 API，为内部以太
|
||||
.. warning::
|
||||
如果配置 RMII 时钟模式为 ``CONFIG_ETH_RMII_CLK_OUTPUT``，那么就可以使用 ``GPIO0`` 输出 ``REF_CLK`` 信号。更多细节，请参见 :ref:`CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0`。
|
||||
|
||||
值得一提的是，如果您在设计中并未使用 PSRAM，则 GPIO16 和 GPIO17 也可以用来输出参考时钟。更多细节，请参见 :ref:`CONFIG_ETH_RMII_CLK_OUT_GPIO`。
|
||||
值得一提的是，如果设计中并未使用 PSRAM，则 GPIO16 和 GPIO17 也可以用来输出参考时钟。更多细节，请参见 :ref:`CONFIG_ETH_RMII_CLK_OUT_GPIO`。
|
||||
|
||||
如果配置 RMII 时钟模式为 ``CONFIG_ETH_RMII_CLK_INPUT``，那么有且只有 ``GPIO0`` 可以用来输入 ``REF_CLK`` 信号。请注意， ``GPIO0`` 同时也是 ESP32 上一个重要的 strapping GPIO 管脚。如果 GPIO0 在上电时采样为低电平，ESP32 将进入下载模式，需进行手动复位重启系统。解决这个问题的方法是，在硬件中默认禁用 ``REF_CLK``，从而避免 strapping 管脚在启动阶段受到其他信号的干扰。随后，再在以太网驱动安装阶段重新启用 ``REF_CLK``。
|
||||
|
||||
可以通过以下方法禁用 ``REF_CLK`` 信号：
|
||||
|
||||
* 禁用或关闭晶体振荡器的电源（对应图中的选项 *b*）。
|
||||
* 禁用或关闭晶体振荡器的电源（对应图中的选项 **b**）。
|
||||
|
||||
* 强制复位 PHY 设备（对应图中的选项 *a*）。 **此种方法并不适用于所有 PHY 设备**，即便处于复位状态，某些 PHY 设备仍会向 GPIO0 输出信号。
|
||||
* 强制复位 PHY 设备（对应图中的选项 **a**）。 **此种方法并不适用于所有 PHY 设备**，即便处于复位状态，某些 PHY 设备仍会向 GPIO0 输出信号。
|
||||
|
||||
**无论选择哪种 RMII 时钟模式，都请确保硬件设计中 REF_CLK 的信号完整性！** 信号线越短越好，并请保持信号线与 RF 设备和电感器元件的距离。
|
||||
|
||||
@@ -144,7 +144,7 @@ ESP-IDF 提供一系列功能强大且兼具一致性的 API，为内部以太
|
||||
|
||||
在数据平面使用的信号通过 MUX 连接至特定的 GPIO，这些信号无法配置至其他 GPIO。在控制平面使用的信号则可以通过 Matrix 矩阵路由到任何空闲 GPIO。相关的硬件设计示例，请参考 :doc:`ESP32-Ethernet-Kit <../../hw-reference/esp32/get-started-ethernet-kit>`。
|
||||
|
||||
根据您的以太网板设计，需要分别为 MAC 和 PHY 配置必要的参数，通过两者完成驱动程序的安装。
|
||||
根据以太网板设计，需要分别为 MAC 和 PHY 配置必要的参数，通过两者完成驱动程序的安装。
|
||||
|
||||
MAC 的相关配置可以在 :cpp:class:`eth_mac_config_t` 中找到，具体包括：
|
||||
|
||||
@@ -166,13 +166,13 @@ PHY 的相关配置可以在 :cpp:class:`eth_phy_config_t` 中找到，具体包
|
||||
|
||||
.. list::
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::phy_addr`：同一条 SMI 总线上可以存在多个 PHY 设备，所以有必要为各个 PHY 设备分配唯一地址。通常，这个地址是在硬件设计期间，通过拉高/拉低一些 PHY strapping 管脚来配置的。根据不同的以太网开发板，可配置值为 0 到 15。需注意，如果 SMI 总线上仅有一个 PHY 设备，将该值配置为 -1，即可使驱动程序自动检测 PHY 地址。
|
||||
* :cpp:member:`eth_phy_config_t::phy_addr`：同一条 SMI 总线上可以存在多个 PHY 设备，所以有必要为各个 PHY 设备分配唯一地址。通常，这个地址是在硬件设计期间，通过拉高/拉低一些 PHY strapping 管脚来配置的。根据不同的以太网开发板，可配置值为 ``0`` 到 ``15``。需注意，如果 SMI 总线上仅有一个 PHY 设备，将该值配置为 ``-1``，即可使驱动程序自动检测 PHY 地址。
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::reset_timeout_ms`：复位超时值，单位为毫秒。通常，PHY 复位应在 100 ms 内完成。
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::autonego_timeout_ms`：自动协商超时值，单位为毫秒。以太网驱动程序会自动与对等的以太网节点进行协商，以确定双工和速度模式。此值通常取决于您电路板上 PHY 设备的性能。
|
||||
* :cpp:member:`eth_phy_config_t::autonego_timeout_ms`：自动协商超时值，单位为毫秒。以太网驱动程序会自动与对等的以太网节点进行协商，以确定双工和速度模式。此值通常取决于电路板上 PHY 设备的性能。
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::reset_gpio_num`：如果您的开发板同时将 PHY 复位管脚连接至了任意 GPIO 管脚，请使用该字段进行配置。否则，配置为 -1。
|
||||
* :cpp:member:`eth_phy_config_t::reset_gpio_num`：如果开发板同时将 PHY 复位管脚连接至了任意 GPIO 管脚，请使用该字段进行配置。否则，配置为 ``-1``。
|
||||
|
||||
ESP-IDF 在宏 :c:macro:`ETH_MAC_DEFAULT_CONFIG` 和 :c:macro:`ETH_PHY_DEFAULT_CONFIG` 中为 MAC 和 PHY 提供了默认配置。
|
||||
|
||||
@@ -279,9 +279,9 @@ SPI-Ethernet 模块
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::check_link_period_ms`：以太网驱动程序会启用操作系统定时器来定期检查链接状态。该字段用于设置间隔时间，单位为毫秒。
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::stack_input`：在大多数的以太网物联网应用中，驱动器接收的以太网帧会被传递到上层（如 TCP/IP 栈）。经配置，该字段为负责处理传入帧的函数。您可以在安装驱动程序后，通过函数 :cpp:func:`esp_eth_update_input_path` 更新该字段。该字段支持在运行过程中进行更新。
|
||||
* :cpp:member:`esp_eth_config_t::stack_input`：在大多数的以太网物联网应用中，驱动器接收的以太网帧会被传递到上层（如 TCP/IP 栈）。经配置，该字段为负责处理传入帧的函数。可以在安装驱动程序后，通过函数 :cpp:func:`esp_eth_update_input_path` 更新该字段。该字段支持在运行过程中进行更新。
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::on_lowlevel_init_done` 和 :cpp:member:`esp_eth_config_t::on_lowlevel_deinit_done`： 这两个字段用于指定钩子函数，当去初始化或初始化低级别硬件时，会调用钩子函数。
|
||||
* :cpp:member:`esp_eth_config_t::on_lowlevel_init_done` 和 :cpp:member:`esp_eth_config_t::on_lowlevel_deinit_done`：这两个字段用于指定钩子函数，当去初始化或初始化低级别硬件时，会调用钩子函数。
|
||||
|
||||
ESP-IDF 在宏 :c:macro:`ETH_DEFAULT_CONFIG` 中为安装驱动程序提供了一个默认配置。
|
||||
|
||||
@@ -293,7 +293,7 @@ ESP-IDF 在宏 :c:macro:`ETH_DEFAULT_CONFIG` 中为安装驱动程序提供了
|
||||
esp_eth_handle_t eth_handle = NULL; // 驱动程序安装完毕后，将得到驱动程序的句柄
|
||||
esp_eth_driver_install(&config, ð_handle); // 安装驱动程序
|
||||
|
||||
以太网驱动程序包含事件驱动模型，该模型会向用户空间发送有用及重要的事件。安装以太网驱动程序之前，需要首先初始化事件循环。有关事件驱动编程的更多信息，请参考 :doc:`ESP Event <../system/esp_event>`.
|
||||
以太网驱动程序包含事件驱动模型，该模型会向用户空间发送有用及重要的事件。安装以太网驱动程序之前，需要首先初始化事件循环。有关事件驱动编程的更多信息，请参考 :doc:`事件循环库 <../system/esp_event>`。
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
@@ -421,7 +421,7 @@ ESP-IDF 在宏 :c:macro:`ETH_DEFAULT_CONFIG` 中为安装驱动程序提供了
|
||||
|
||||
受 RAM 大小限制，在网络拥堵时，MCU 上的以太网通常仅能处理有限数量的帧。发送站的数据传输速度可能快于对等端的接收能力。以太网数据流量控制机制允许接收节点向发送方发出信号，要求暂停传输，直到接收方跟上。这项功能是通过暂停帧实现的，该帧定义在 IEEE 802.3x 中。
|
||||
|
||||
暂停帧是一种特殊的以太网帧，用于携带暂停命令，其 EtherType 字段为 0x8808，控制操作码为 0x0001。只有配置为全双工操作的节点组可以发送暂停帧。当节点组希望暂停链路的另一端时，它会发送一个暂停帧到 48 位的保留组播地址 01-80-C2-00-00-01。暂停帧中也包括请求暂停的时间段，以两字节的整数形式发送，值的范围从 0 到 65535。
|
||||
暂停帧是一种特殊的以太网帧，用于携带暂停命令，其 EtherType 字段为 ``0x8808``，控制操作码为 ``0x0001``。只有配置为全双工操作的节点组可以发送暂停帧。当节点组希望暂停链路的另一端时，它会发送一个暂停帧到 48 位的保留组播地址 ``01-80-C2-00-00-01``。暂停帧中也包括请求暂停的时间段，以两字节的整数形式发送，值的范围从 ``0`` 到 ``65535``。
|
||||
|
||||
安装以太网驱动程序后，数据流量控制功能默认禁用，可以通过以下方式启用此功能：
|
||||
|
||||
@@ -460,7 +460,7 @@ ESP-IDF 在宏 :c:macro:`ETH_DEFAULT_CONFIG` 中为安装驱动程序提供了
|
||||
好在 IEEE 802.3 在其 22.2.4 管理功能部分对 EMAC 和 PHY 之间的管理接口进行了标准化。该部分定义了所谓的 ”MII 管理接口”规范，用于控制 PHY 和收集 PHY 的状态，还定义了一组管理寄存器来控制芯片行为、链接属性、自动协商配置等。在 ESP-IDF 中，这项基本的管理功能是由 :component_file:`esp_eth/src/esp_eth_phy_802_3.c` 实现的，这也大大降低了创建新的自定义 PHY 芯片驱动的难度。
|
||||
|
||||
.. note::
|
||||
由于一些 PHY 芯片可能不符合 IEEE 802.3 第 22.2.4 节的规定，所以请首先查看 PHY 数据手册。不过，就算芯片不符合规定，您依旧可以创建自定义 PHY 驱动程序，只是由于需要自行定义所有的 PHY 管理功能，这个过程将变得较为复杂。
|
||||
由于一些 PHY 芯片可能不符合 IEEE 802.3 第 22.2.4 节的规定，所以请首先查看 PHY 数据手册。不过，就算芯片不符合规定，依旧可以创建自定义 PHY 驱动程序，只是由于需要自行定义所有的 PHY 管理功能，这个过程将变得较为复杂。
|
||||
|
||||
ESP-IDF 以太网驱动程序所需的大部分 PHY 管理功能都已涵盖在 :component_file:`esp_eth/src/esp_eth_phy_802_3.c` 中。不过对于以下几项，可能仍需针对不同芯片开发具体的管理功能：
|
||||
|
||||
@@ -479,7 +479,7 @@ ESP-IDF 以太网驱动程序所需的大部分 PHY 管理功能都已涵盖在
|
||||
3. 定义针对芯片的特定管理回调功能。
|
||||
4. 初始化 IEEE 802.3 父对象并重新分配针对芯片的特定管理回调功能。
|
||||
|
||||
实现新的自定义 PHY 驱动程序后，你可以通过 `IDF组件管理中心 <https://components.espressif.com/>`_ 将驱动分享给其他用户。
|
||||
实现新的自定义 PHY 驱动程序后，你可以通过 `ESP-IDF 组件管理中心 <https://components.espressif.com/>`_ 将驱动分享给其他用户。
|
||||
|
||||
.. ---------------------------- API Reference ----------------------------------
|
||||
|
||||
|
||||
@@ -160,16 +160,16 @@ ESP-NETIF L2 TAP 接口使用手册
|
||||
^^^^^^^^^^^^^^
|
||||
要使用 ESP-NETIF L2 TAP 接口，需要首先通过 Kconfig 配置 :ref:`CONFIG_ESP_NETIF_L2_TAP` 启用接口，随后通过 :cpp:func:`esp_vfs_l2tap_intf_register()` 注册。请在完成上述步骤后再使用 VFS 函数。
|
||||
|
||||
open()
|
||||
^^^^^^
|
||||
``open()``
|
||||
^^^^^^^^^^
|
||||
ESP-NETIF L2 TAP 注册完成后，可使用路径名 "/dev/net/tap" 访问。同一路径名最多可以被打开 :ref:`CONFIG_ESP_NETIF_L2_TAP_MAX_FDS` 次，多个具有不同配置的文件描述符可以访问数据链路层的各个帧。
|
||||
|
||||
ESP-NETIF L2 TAP 可以使用 ``O_NONBLOCK`` 文件状态标志打开，确保 ``read()`` 不会阻塞。请注意，在当前实现中，当访问网络接口时，由于网络接口被多个 ESP-NETIF L2 TAP 文件描述符和 IP 栈共享，且缺乏列队机制，因此 ``write()`` 可能会受阻塞。使用 ``fcntl()`` 检索和修改文件状态标志。
|
||||
|
||||
成功时，``open()`` 返回新的文件描述符（非负整数）。出错时，返回 -1，并设置 ``errno`` 以标识错误。
|
||||
|
||||
ioctl()
|
||||
^^^^^^^
|
||||
``ioctl()``
|
||||
^^^^^^^^^^^
|
||||
由于新打开的 ESP-NETIF L2 TAP 文件描述符尚未绑定任意网络接口或配置任意帧类型过滤器，使用前，用户需通过以下选项完成配置：
|
||||
|
||||
* ``L2TAP_S_INTF_DEVICE`` - 将文件描述符绑定到特定网络接口的选项，该网络接口由其 ``if_key`` 标识。 ESP-NETIF 网络接口的 ``if_key`` 作为第三个参数传输给 ``ioctl()``。 ESP-IDF 中，默认网络接口 ``if_key`` 的使用存放在 :component_file:`esp_netif/include/esp_netif_defaults.h` 头文件中。
|
||||
@@ -194,8 +194,8 @@ ioctl()
|
||||
| * ENODEV - 此文件描述符尝试分配给的网络接口不存在。
|
||||
| * ENOSYS - 不支持该操作，传递的配置选项不存在。
|
||||
|
||||
fcntl()
|
||||
^^^^^^^
|
||||
``fcntl()``
|
||||
^^^^^^^^^^^
|
||||
``fcntl()`` 配置已开启的 ESP-NETIF L2 TAP 文件描述符属性。
|
||||
|
||||
以下命令调控与文件描述符相关的状态标志：
|
||||
@@ -207,16 +207,16 @@ fcntl()
|
||||
| * EBADF - 文件描述符无效。
|
||||
| * ENOSYS - 不支持该命令。
|
||||
|
||||
read()
|
||||
^^^^^^
|
||||
``read()``
|
||||
^^^^^^^^^^
|
||||
已开启并完成配置的 ESP-NETIF L2 TAP 文件描述符可通过 ``read()`` 获取入站帧。读取可以是阻塞或非阻塞的，具体取决于 ``O_NONBLOCK`` 文件状态标志的实际状态。当文件状态标志设置为阻塞时，读取程序将等待，直到接收到帧，并将上下文切换到其他任务。当文件状态标志设置为非阻塞时，立即返回读取程序。在此情况下，如果已经帧已经入队，则返回一帧，否则函数指示队列为空。与文件描述符关联的队列帧数量受 :ref:`CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE` Kconfig 选项限制。一旦队列里帧的数量达到配置的阈值，新到达的帧将被丢弃，直到队列有足够的空间接受传入的流量（队尾丢弃队列管理）。
|
||||
|
||||
| 成功时，read() 函数返回读取的字节数。当目标缓冲区的大小为 0 时，函数返回 0。出错时，函数返回 -1，并设置 ``errno`` 以指示错误类型。
|
||||
| * EBADF - 文件描述符无效。
|
||||
| * EAGAIN - 文件描述符标记为非阻塞 (``O_NONBLOCK``)，但读取受阻塞。
|
||||
|
||||
write()
|
||||
^^^^^^^
|
||||
``write()``
|
||||
^^^^^^^^^^^
|
||||
通过已开启并完成配置的 ESP-NETIF L2 TAP 文件描述符可以将原始数据链路层帧发送到网络接口，用户应用程序负责构建除物理接口设备自动添加的字段外的整个帧。在以太网链路中，用户应用程序需要构建以下字段：源或目的 MAC 地址、以太网类型、实际协议头和用户数据，字段长度如下表：
|
||||
|
||||
.. list-table::
|
||||
@@ -240,15 +240,15 @@ write()
|
||||
| * EBADMSG - 帧的以太网类型与文件描述符配置的过滤器不同。
|
||||
| * EIO - 网络接口不可用或正忙。
|
||||
|
||||
close()
|
||||
^^^^^^^
|
||||
``close()``
|
||||
^^^^^^^^^^^
|
||||
已开启的 ESP-NETIF L2 TAP 文件描述符可以通过 ``close()`` 函数关闭，释放其分配到的资源。ESP-NETIF L2 TAP 实现的 ``close()`` 函数可能会受阻塞，但它是线程安全的，可以从与实际使用文件描述符的任务不同的任务中调用。如果出现一个任务在 I/O 操作中被阻塞、另一个任务试图关闭文件描述符的情况，则第一个任务会解除阻塞，其读取程序以错误结束。
|
||||
|
||||
| 成功时，``close()`` 返回 0。出错时，则返回 -1， 并设置 ``errno`` 以指示错误类型。
|
||||
| * EBADF - 文件描述符无效。
|
||||
|
||||
select()
|
||||
^^^^^^^^
|
||||
``select()``
|
||||
^^^^^^^^^^^^
|
||||
``select()`` 函数按标准方法使用，启用 :ref:`CONFIG_VFS_SUPPORT_SELECT` 即可使用该函数。
|
||||
|
||||
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
ESP-NOW
|
||||
========
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
ESP-NOW 是一种由乐鑫公司定义的无连接 Wi-Fi 通信协议。在 ESP-NOW 中，应用程序数据被封装在各个供应商的动作帧中，然后在无连接的情况下，从一个 Wi-Fi 设备传输到另一个 Wi-Fi 设备。
|
||||
|
||||
CTR 与 CBC-MAC 协议 (CCMP) 可用来保护动作帧的安全。ESP-NOW 广泛应用于智能照明、远程控制、传感器等领域。
|
||||
|
||||
帧格式
|
||||
@@ -24,7 +25,7 @@ ESP-NOW 使用各个供应商的动作帧传输数据，默认比特率为 1 Mbp
|
||||
24 字节 1 字节 3 字节 4 字节 7~257 字节 4 字节
|
||||
|
||||
- 分类代码：分类代码字段可用于指示各个供应商的类别（比如 127）。
|
||||
- 组织标识符：组织标识符包含一个唯一标识符 (比如 0x18fe34)，为乐鑫指定的 MAC 地址的前三个字节。
|
||||
- 组织标识符：组织标识符包含一个唯一标识符（比如 0x18fe34），为乐鑫指定的 MAC 地址的前三个字节。
|
||||
- 随机值：防止重放攻击。
|
||||
- 供应商特定内容：供应商特定内容包含供应商特定字段，如下所示：
|
||||
|
||||
@@ -39,7 +40,7 @@ ESP-NOW 使用各个供应商的动作帧传输数据，默认比特率为 1 Mbp
|
||||
|
||||
- 元素 ID：元素 ID 字段可用于指示特定于供应商的元素。
|
||||
- 长度：长度是组织标识符、类型、版本和正文的总长度。
|
||||
- 组织标识符：组织标识符包含一个唯一标识符 (比如 0x18fe34)，为乐鑫指定的 MAC 地址的前三个字节。
|
||||
- 组织标识符：组织标识符包含一个唯一标识符（比如 0x18fe34），为乐鑫指定的 MAC 地址的前三个字节。
|
||||
- 类型：类型字段设置为 4，代表 ESP-NOW。
|
||||
- 版本：版本字段设置为 ESP-NOW 的版本。
|
||||
- 正文：正文包含 ESP-NOW 数据。
|
||||
@@ -50,6 +51,7 @@ ESP-NOW 使用各个供应商的动作帧传输数据，默认比特率为 1 Mbp
|
||||
--------
|
||||
|
||||
ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参考 IEEE Std. 802.11-2012。Wi-Fi 设备维护一个初始主密钥 (PMK) 和若干本地主密钥 (LMK)，长度均为 16 个字节。
|
||||
|
||||
* PMK 可使用 AES-128 算法加密 LMK。请调用 :cpp:func:`esp_now_set_pmk()` 设置 PMK。如果未设置 PMK，将使用默认 PMK。
|
||||
* LMK 可通过 CCMP 方法对供应商特定的动作帧进行加密，最多拥有 6 个不同的 LMK。如果未设置配对设备的 LMK，则动作帧不进行加密。
|
||||
|
||||
@@ -59,12 +61,13 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
|
||||
------------------------------------
|
||||
|
||||
调用 :cpp:func:`esp_now_init()` 初始化 ESP-NOW，调用 :cpp:func:`esp_now_deinit()` 反初始化 ESP-NOW。ESP-NOW 数据必须在 Wi-Fi 启动后传输，因此建议在初始化 ESP-NOW 之前启动 Wi-Fi，并在反初始化 ESP-NOW 之后停止 Wi-Fi。
|
||||
|
||||
当调用 :cpp:func:`esp_now_deinit()` 时，配对设备的所有信息都将被删除。
|
||||
|
||||
添加配对设备
|
||||
-----------------
|
||||
|
||||
在将数据发送到其他设备之前，请先调用 :cpp:func:`esp_now_add_peer()` 将其添加到配对设备列表中。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 Softap 接口发送。确保在发送 ESP-NOW 数据之前已启用该接口。
|
||||
在将数据发送到其他设备之前，请先调用 :cpp:func:`esp_now_add_peer()` 将其添加到配对设备列表中。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 SoftAP 接口发送。确保在发送 ESP-NOW 数据之前已启用该接口。
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
@@ -74,7 +77,7 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
|
||||
|
||||
配对设备的最大数量是 20，其中加密设备的数量不超过 17，默认值是 7。如果想要修改加密设备的数量，在 Wi-Fi menuconfig 设置 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`。
|
||||
|
||||
在发送广播数据之前必须添加具有广播 MAC 地址的设备。配对设备的信道范围是从 0 ～14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
|
||||
在发送广播数据之前必须添加具有广播 MAC 地址的设备。配对设备的信道范围是从 0 ~ 14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
|
||||
|
||||
发送 ESP-NOW 数据
|
||||
-----------------
|
||||
@@ -94,15 +97,15 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
|
||||
|
||||
.. only:: esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3
|
||||
|
||||
调用 :cpp:func:`esp_wifi_config_espnow_rate()` 配置指定接口的 ESPNOW 速率。确保在配置速率之前使能接口。这个 API 应该在 :cpp:func:`esp_wifi_start()` 之后调用。
|
||||
调用 :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的 ESPNOW 速率。确保在配置速率之前添加peer。这个 API 应该在 :cpp:func:`esp_wifi_start()` 和 :cpp:func:`esp_now_add_peer()` 之后调用。
|
||||
调用 :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::
|
||||
|
||||
:cpp:func:`esp_wifi_config_espnow_rate()` 已经被废弃了，请用 :cpp:func:`esp_now_set_peer_rate_config()`
|
||||
:cpp:func:`esp_wifi_config_espnow_rate()` 已弃用，请使用 :cpp:func:`esp_now_set_peer_rate_config()`
|
||||
|
||||
配置 ESP-NOW 功耗参数
|
||||
----------------------
|
||||
|
||||
@@ -43,6 +43,7 @@ Thread
|
||||
esp_openthread
|
||||
|
||||
Thread 是一种基于 IPv6 的物联网网状网络技术。
|
||||
|
||||
本部分的Thread API 示例代码存放在 ESP-IDF 示例项目的 :example:`openthread` 目录下。
|
||||
|
||||
IP 网络层协议
|
||||
|
||||
Reference in New Issue
Block a user