Merge branch 'docs/add_CN_trans_for_5_docs_in_api-reference/network' into 'master'
docs: Provide Chinese translation for 5 documents in api-reference/network Closes DOC-6014 See merge request espressif/esp-idf!25468
This commit is contained in:
Ren Pei Ying
@@ -1 +1,29 @@
|
||||
.. include:: ../../../en/api-reference/network/esp_dpp.rst
|
||||
Wi-Fi Easy Connect\ :sup:`TM` (DPP)
|
||||
===================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
Wi-Fi Easy Connect\ :sup:`TM` 是 Wi-Fi Alliance 认证的配网协议，也称为设备配网协议 (DPP) 或 Easy Connect，是一种安全和标准化的 Wi-Fi 设备配网协议。使用 Easy Connect 将新设备添加入网就像扫描二维码一样简单，特别是对于没有 UI 的智能家居和物联网产品而言，大大降低了联网复杂性，加强了的用户体验。与旧的协议如 Wi-Fi Protected Setup (WPS) 等旧协议相比，Wi-Fi Easy Connect 的公钥加密技术额外确保了添加新设备时的网络安全。
|
||||
|
||||
Easy Connect 从以下几个方面改善了用户体验：
|
||||
|
||||
- 操作简单直观，设置新设备时无需阅读冗长的指南
|
||||
- 无需记住需配网设备的密码或输入密码
|
||||
- 支持电子/打印的二维码以及其他人类可读的字符串
|
||||
- 同时支持 WPA2 和 WPA3 网络
|
||||
|
||||
如需了解更多信息，请参考 Wi-Fi Alliance 的官方介绍：`Easy Connect <https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect>`_。
|
||||
|
||||
{IDF_TARGET_NAME} 支持 Easy Connect 的二维码配网模式，用户需要使用显示器显示二维码，随后使用兼容的设备扫描此二维码，并将 {IDF_TARGET_NAME} 添加到自己的 Wi-Fi 网络中。此兼容设备需连接到无需支持 Wi-Fi Easy Connect\ :sup:`TM` 的 AP 上。
|
||||
|
||||
Easy Connect 协议仍在不断发展。目前已知支持二维码的平台为部分运行 Android 10 及更高系统版本的 Android 智能手机等。使用 Easy Connect 时，无需在智能手机上安装额外的应用程序。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
如需了解使用智能手机配置 {IDF_TARGET_NAME} 的示例，请前往 :example:`wifi/wifi_easy_connect/dpp-enrollee`。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_dpp.inc
|
||||
@@ -1 +1,20 @@
|
||||
.. include:: ../../../en/api-reference/network/esp_nan.rst
|
||||
Wi-Fi Aware\ :sup:`TM` (NAN)
|
||||
===================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
Wi-Fi Aware\ :sup:`TM`，也可称为 NAN (Neighbor Awareness Networking) 协议，其支持 Wi-Fi 设备发现附近的其他服务。通常情况下，基于位置的服务需通过服务器查询环境信息，并通过 GPS 或其他位置推算技术获取定位。不过，NAN 无需与服务器、GPS 或其他地理位置服务保持实时连接，即可支持设备之间通过 Wi-Fi 直接连接来交换信息。NAN 能够在 Wi-Fi 密集的环境中高效扩展，并通过提供附近人员和服务的信息来完善 Wi-Fi 连接性。
|
||||
|
||||
多个邻近的 NAN 设备组成一个 NAN 集群，集群中的设备能够相互通信。NAN 设备还可通过 NAN 服务发现协议，通过发布或订阅功能，在所处集群内提供或查找服务。通过服务名称可以完成服务匹配，一旦找到匹配，设备就可以发送信息，或与匹配到的设备间建立 IPv6 数据路径。
|
||||
|
||||
{IDF_TARGET_NAME} 支持独立模式下的 Wi-Fi Aware，同时支持服务发现协议和数据路径。Wi-Fi Aware 协议仍在改进中，如需了解更多信息，请前往 Wi-Fi Alliance 官网的 `Wi-Fi Aware <https://www.wi-fi.org/discover-wi-fi/wi-fi-aware>`_ 页面。大多数 Android 8 及更高版本的 Android 智能手机都支持 Wi-Fi Aware。如需了解更多信息，请参阅 Android 的开发者指南 `Wi-Fi Aware <https://www.wi-fi.org/discover-wi-fi/wi-fi-aware>`_。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
如需查看发布者和订阅者示例，请前往 :example:`wifi/wifi_aware/nan_publisher` 和 :example:`wifi/wifi_aware/nan_subscriber`。如需探索 Wi-Fi Aware 的全部功能，请参考用户交互界面控制台示例 :example:`wifi/wifi_aware/nan_console`。如需了解更多信息，请参考对应示例目录中的 `README` 文档。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_nan.inc
|
||||
@@ -16,6 +16,9 @@ ESP-IDF 支持实现了 BSD API 的自定义 TCP/IP 协议栈。有关不使用
|
||||
|
||||
应用程序通常无需直接调用 ESP-NETIF 的 API，它们会由默认网络事件句柄调用。
|
||||
|
||||
|
||||
.. _esp-netif structure:
|
||||
|
||||
ESP-NETIF 架构
|
||||
----------------------
|
||||
|
||||
|
||||
@@ -1 +1,95 @@
|
||||
.. include:: ../../../en/api-reference/network/esp_netif_driver.rst
|
||||
ESP-NETIF 自定义 I/O 驱动程序
|
||||
===============================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本节概述了如何配置具有 ESP-NETIF 连接功能的新 I/O 驱动程序。
|
||||
|
||||
通常情况下，I/O 驱动程序须注册为 ESP-NETIF 驱动程序。因此，它依赖于 ESP-NETIF 组件，并负责提供数据路径函数、后附回调函数，并在多数情况下用于设置默认事件处理程序，根据驱动程序的生命周期转换来定义网络接口操作。
|
||||
|
||||
|
||||
数据包 Input/Output
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
根据 :ref:`esp-netif structure` 章节提供的图表可以看出，须定义以下三个数据路径函数 API 以连接 ESP-NETIF：
|
||||
|
||||
* :cpp:func:`esp_netif_transmit()`
|
||||
* :cpp:func:`esp_netif_free_rx_buffer()`
|
||||
* :cpp:func:`esp_netif_receive()`
|
||||
|
||||
前两个函数可以传输和释放 RX 缓冲区，用作回调。它们由 ESP-NETIF（及其底层 TCP/IP 堆栈）调用，并由 I/O 驱动实现。
|
||||
|
||||
另一方面，接收函数由 I/O 驱动程序调用，因此驱动的代码只需在接收到新数据时调用 :cpp:func:`esp_netif_receive()` 函数。
|
||||
|
||||
|
||||
后附回调
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
网络接口初始化的最后一步是调用以下 API，将 ESP-NETIF 实例附加到 I/O 驱动程序上：
|
||||
|
||||
.. code:: c
|
||||
|
||||
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle);
|
||||
|
||||
假设 ``esp_netif_iodriver_handle`` 是指向驱动程序对象的指针，该对象是从 ``struct esp_netif_driver_base_s`` 衍生的结构体，那么 I/O 驱动结构体的第一个成员必须是此基础结构，并指向：
|
||||
|
||||
* 后附函数回调
|
||||
* 相关的 ESP-NETIF 实例
|
||||
|
||||
因此，I/O 驱动程序须创建以下结构体的实例：
|
||||
|
||||
.. code:: c
|
||||
|
||||
typedef struct my_netif_driver_s {
|
||||
esp_netif_driver_base_t base; /*!< 保留基本结构体作为 esp-netif 驱动 */
|
||||
driver_impl *h; /*!< 驱动实现 */
|
||||
} my_netif_driver_t;
|
||||
|
||||
此实例中包含 ``my_netif_driver_t::base.post_attach`` 的真实值和实际的驱动处理程序 ``my_netif_driver_t::h``。
|
||||
|
||||
从初始化代码调用 :cpp:func:`esp_netif_attach()` 时，将执行 I/O 驱动程序代码的后附回调，以在 ESP-NETIF 和 I/O 驱动程序实例之间相互注册回调。通常，后附回调中也会启动驱动程序。以下为一个简单的后附回调示例：
|
||||
|
||||
.. code:: c
|
||||
|
||||
static esp_err_t my_post_attach_start(esp_netif_t * esp_netif, void * args)
|
||||
{
|
||||
my_netif_driver_t *driver = args;
|
||||
const esp_netif_driver_ifconfig_t driver_ifconfig = {
|
||||
.driver_free_rx_buffer = my_free_rx_buf,
|
||||
.transmit = my_transmit,
|
||||
.handle = driver->driver_impl
|
||||
};
|
||||
driver->base.netif = esp_netif;
|
||||
ESP_ERROR_CHECK(esp_netif_set_driver_config(esp_netif, &driver_ifconfig));
|
||||
my_driver_start(driver->driver_impl);
|
||||
return ESP_OK;
|
||||
}
|
||||
|
||||
|
||||
默认处理程序
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
I/O 驱动程序通常还会根据 I/O 驱动程序的状态转换，为相关网络接口的生命周期行为提供默认定义，例如 *driver start* ``->`` *network start* 等。
|
||||
|
||||
以下是此类默认处理程序的一个示例：
|
||||
|
||||
.. code:: c
|
||||
|
||||
esp_err_t my_driver_netif_set_default_handlers(my_netif_driver_t *driver, esp_netif_t * esp_netif)
|
||||
{
|
||||
driver_set_event_handler(driver->driver_impl, esp_netif_action_start, MY_DRV_EVENT_START, esp_netif);
|
||||
driver_set_event_handler(driver->driver_impl, esp_netif_action_stop, MY_DRV_EVENT_STOP, esp_netif);
|
||||
return ESP_OK;
|
||||
}
|
||||
|
||||
|
||||
网络堆栈连接
|
||||
------------------------
|
||||
|
||||
用于传输和释放 RX 缓冲区的数据路径函数（在 I/O 驱动中定义）由 ESP-NETIF 的 TCP/IP 堆栈连接层调用。
|
||||
|
||||
注意，ESP-IDF 为最常见的网络接口（如 Wi-Fi station 或以太网）提供了几种网络堆栈配置。这些配置定义在 :component_file:`esp_netif/include/esp_netif_defaults.h` 中，能够满足大多数网络驱动程序的需求。在少数情况下，一些专家用户可能希望自定义基于 lwIP 的接口层，这需要额外设置 lwIP 依赖。
|
||||
|
||||
以下参考 API 概述了这些网络堆栈和 ESP-NETIF 的交互：
|
||||
|
||||
.. include-build-file:: inc/esp_netif_net_stack.inc
|
||||
|
||||
@@ -1 +1,32 @@
|
||||
.. include:: ../../../en/api-reference/network/esp_openthread.rst
|
||||
Thread
|
||||
======
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
----
|
||||
|
||||
`Thread <https://www.threadgroup.org>`_ 是一个基于 IP 的网状网络协议,它基于 802.15.4 物理层和 MAC 层。
|
||||
|
||||
应用示例
|
||||
--------------------
|
||||
|
||||
ESP-IDF 示例目录 :example:`openthread` 包含以下应用程序：
|
||||
|
||||
- OpenThread 交互 shell：:example:`openthread/ot_cli`
|
||||
- 边界路由器 (Thread Border Router)：:example:`openthread/ot_br`
|
||||
- Thread 无线电协处理器 (Thread Radio Co-Processor)：:example:`openthread/ot_rcp`
|
||||
|
||||
|
||||
API参考
|
||||
-------------
|
||||
|
||||
应使用 OpenThread API 操作 Thread 网络。请参考 `OpenThread API 文档 <https://openthread.io/reference>`_。
|
||||
|
||||
ESP-IDF 提供额外的 API，用于启动和管理 OpenThread 实现执行网络接口绑定和边界路由功能。
|
||||
|
||||
.. include-build-file:: inc/esp_openthread.inc
|
||||
.. include-build-file:: inc/esp_openthread_types.inc
|
||||
.. include-build-file:: inc/esp_openthread_lock.inc
|
||||
.. include-build-file:: inc/esp_openthread_netif_glue.inc
|
||||
.. include-build-file:: inc/esp_openthread_border_router.inc
|
||||
|
||||
@@ -1 +1,22 @@
|
||||
.. include:: ../../../en/api-reference/network/esp_smartconfig.rst
|
||||
SmartConfig
|
||||
===========
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
SmartConfig\ :sup:`TM` 是由 TI 开发的配网技术，用于将新的 Wi-Fi 设备连接到 Wi-Fi 网络。它使用移动应用程序将无线网凭据从智能手机或平板电脑端广播给未配网的 Wi-Fi 设备。
|
||||
|
||||
这项技术的优势在于，设备无需直接获知 AP 的 SSID 或密码，而是通过智能手机获取。这对于没有用户界面的无头设备和系统而言十分重要。
|
||||
|
||||
如需通过其他方式为 {IDF_TARGET_NAME} 设备配网，请参阅 :doc:`../provisioning/index`。
|
||||
|
||||
|
||||
应用示例
|
||||
------------
|
||||
|
||||
前往 :example:`wifi/smart_config`，查看使用 SmartConfig 将 {IDF_TARGET_NAME} 连接到目标 AP 的应用示例。
|
||||
|
||||
|
||||
API 参考
|
||||
----------
|
||||
|
||||
.. include-build-file:: inc/esp_smartconfig.inc
|
||||
@@ -48,9 +48,8 @@ Thread 是一种基于 IPv6 的物联网网状网络技术。
|
||||
|
||||
本部分的 Thread API 示例代码存放在 ESP-IDF 示例项目的 :example:`openthread` 目录下。
|
||||
|
||||
IP 网络层协议
|
||||
================
|
||||
|
||||
ESP-NETIF
|
||||
=========
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
|
||||
Reference in New Issue
Block a user