mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
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
commit
23095c7633
@ -1,8 +1,11 @@
|
|||||||
Wi-Fi Easy Connect\ :sup:`TM` (DPP)
|
Wi-Fi Easy Connect\ :sup:`TM` (DPP)
|
||||||
===================================
|
===================================
|
||||||
|
|
||||||
Wi-Fi Easy Connect\ :sup:`TM`, also known as Device Provisioning Protocol (DPP) or Easy Connect, is a provisioning protocol certified by Wi-Fi Alliance. It is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. With Easy Connect adding a new device to a network is as simple as scanning a QR Code. This reduces complexity and enhances user experience while onboarding devices without UI like Smart Home and IoT products. Unlike old protocols like WiFi Protected Setup (WPS), Wi-Fi Easy Connect incorporates strong encryption through public key cryptography to ensure networks remain secure as new devices are added.
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
Easy Connect brings many benefits in the User Experience:
|
|
||||||
|
Wi-Fi Easy Connect\ :sup:`TM`, also known as Device Provisioning Protocol (DPP) or Easy Connect, is a provisioning protocol certified by Wi-Fi Alliance. It is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. With Easy Connect, adding a new device to a network is as simple as scanning a QR Code. This reduces complexity and enhances user experience while onboarding devices without UI like Smart Home and IoT products. Unlike old protocols like Wi-Fi Protected Setup (WPS), Wi-Fi Easy Connect in corporates strong encryption through public key cryptography to ensure networks remain secure as new devices are added.
|
||||||
|
|
||||||
|
Easy Connect brings many benefits in the user experience:
|
||||||
|
|
||||||
- Simple and intuitive to use; no lengthy instructions to follow for new device setup
|
- Simple and intuitive to use; no lengthy instructions to follow for new device setup
|
||||||
- No need to remember and enter passwords into the device being provisioned
|
- No need to remember and enter passwords into the device being provisioned
|
||||||
@ -11,16 +14,16 @@ Easy Connect brings many benefits in the User Experience:
|
|||||||
|
|
||||||
Please refer to Wi-Fi Alliance's official page on `Easy Connect <https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect>`_ for more information.
|
Please refer to Wi-Fi Alliance's official page on `Easy Connect <https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect>`_ for more information.
|
||||||
|
|
||||||
{IDF_TARGET_NAME} supports Enrollee mode of Easy Connect with QR Code as the provisioning method. A display is required to display this QR Code. Users can scan this QR Code using their capable device and provision the {IDF_TARGET_NAME} to their Wi-Fi network. The provisioning device needs to be connected to the AP which need not support Wi-Fi Easy Connect™.
|
{IDF_TARGET_NAME} supports Enrollee mode of Easy Connect with QR Code as the provisioning method. A display is required to display this QR Code. Users can scan this QR Code using their capable device and provision the {IDF_TARGET_NAME} to their Wi-Fi network. The provisioning device needs to be connected to the AP which need not support Wi-Fi Easy Connect\ :sup:`TM`.
|
||||||
Easy Connect is still an evolving protocol. Of known platforms that support the QR Code method are some Android smartphones with Android 10 or higher. To use Easy Connect no additional App needs to be installed on the supported smartphone.
|
|
||||||
|
Easy Connect is still an evolving protocol. Of known platforms that support the QR Code method are some Android smartphones with Android 10 or higher. To use Easy Connect, no additional App needs to be installed on the supported smartphone.
|
||||||
|
|
||||||
Application Example
|
Application Example
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
Example on how to provision {IDF_TARGET_NAME} using a supported smartphone: :example:`wifi/wifi_easy_connect/dpp-enrollee`.
|
Example on how to provision {IDF_TARGET_NAME} using a supported smartphone: :example:`wifi/wifi_easy_connect/dpp-enrollee`.
|
||||||
|
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
.. include-build-file:: inc/esp_dpp.inc
|
.. include-build-file:: inc/esp_dpp.inc
|
||||||
@ -1,20 +1,20 @@
|
|||||||
Wi-Fi Aware\ :sup:`TM` (NAN)
|
Wi-Fi Aware\ :sup:`TM` (NAN)
|
||||||
===================================
|
===================================
|
||||||
|
|
||||||
Wi-Fi Aware\ :sup:`TM` or NAN (Neighbor Awareness Networking) is a protocol that allows Wi-Fi devices to discover services in their proximity. Typically, location-based services are based on querying servers for information about the environment and the location knowledge is based on GPS or other location reckoning techniques. However NAN does not require real-time connection to servers, GPS or other geo-location, but instead uses direct device-to-device Wi-Fi to discover and exchange information. NAN scales effectively in dense Wi-Fi environments and complements the connectivity of Wi-Fi by providing information about people and services in the proximity.
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
Multiple NAN devices which are in the vicinity form a NAN cluster which allows them to communicate with each other. Devices within a NAN cluster can advertise (Publish method) or look for (Subscribe method) services using NAN Service Discovery protocols. Matching of services is done by service name, once a match is found a device can either send a message or establish an IPv6 datapath with the peer.
|
Wi-Fi Aware\ :sup:`TM` or NAN (Neighbor Awareness Networking) is a protocol that allows Wi-Fi devices to discover services in their proximity. Typically, location-based services are based on querying servers for information about the environment and the location knowledge is based on GPS or other location reckoning techniques. However, NAN does not require real-time connection to servers, GPS or other geo-location, but instead uses direct device-to-device Wi-Fi to discover and exchange information. NAN scales effectively in dense Wi-Fi environments and complements the connectivity of Wi-Fi by providing information about people and services in the proximity.
|
||||||
|
|
||||||
|
Multiple NAN devices which are in the vicinity form a NAN cluster which allows them to communicate with each other. Devices within a NAN cluster can advertise (Publish method) or look for (Subscribe method) services using NAN Service Discovery protocols. Matching of services is done by service name, once a match is found, a device can either send a message or establish an IPv6 Datapath with the peer.
|
||||||
|
|
||||||
{IDF_TARGET_NAME} supports Wi-Fi Aware in standalone mode with support for both Service Discovery and Datapath. Wi-Fi Aware is still an evolving protocol. Please refer to Wi-Fi Alliance's official page on `Wi-Fi Aware <https://www.wi-fi.org/discover-wi-fi/wi-fi-aware>`_ for more information. Many Android smartphones with Android 8 or higher support Wi-Fi Aware. Refer to Android's developer guide on Wi-Fi Aware `Wi-Fi Aware <https://www.wi-fi.org/discover-wi-fi/wi-fi-aware>`_ for more information.
|
{IDF_TARGET_NAME} supports Wi-Fi Aware in standalone mode with support for both Service Discovery and Datapath. Wi-Fi Aware is still an evolving protocol. Please refer to Wi-Fi Alliance's official page on `Wi-Fi Aware <https://www.wi-fi.org/discover-wi-fi/wi-fi-aware>`_ for more information. Many Android smartphones with Android 8 or higher support Wi-Fi Aware. Refer to Android's developer guide on Wi-Fi Aware `Wi-Fi Aware <https://www.wi-fi.org/discover-wi-fi/wi-fi-aware>`_ for more information.
|
||||||
|
|
||||||
Application Example
|
Application Example
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
A pair of examples for a Publisher-Subscriber use case: :example:`wifi/wifi_aware/nan_publisher` and :example:`wifi/wifi_aware/nan_subscriber`.
|
A pair of examples for a Publisher-Subscriber use case: :example:`wifi/wifi_aware/nan_publisher` and :example:`wifi/wifi_aware/nan_subscriber`. A user interactive console example to explore full functionality of Wi-Fi Aware: :example:`wifi/wifi_aware/nan_console`. Please check the `README` for more details in respective example directories.
|
||||||
A user interactive console example to explore full functionality of Wi-Fi Aware: :example:`wifi/wifi_aware/nan_console`.
|
|
||||||
Please check the `README` for more details in respective example directories.
|
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
.. include-build-file:: inc/esp_nan.inc
|
.. include-build-file:: inc/esp_nan.inc
|
||||||
@ -16,6 +16,9 @@ Some ESP-NETIF API functions are intended to be called by application code, for
|
|||||||
|
|
||||||
In many cases, applications do not need to call ESP-NETIF APIs directly as they are called by the default network event handlers.
|
In many cases, applications do not need to call ESP-NETIF APIs directly as they are called by the default network event handlers.
|
||||||
|
|
||||||
|
|
||||||
|
.. _esp-netif structure:
|
||||||
|
|
||||||
ESP-NETIF Architecture
|
ESP-NETIF Architecture
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
|||||||
@ -1,21 +1,23 @@
|
|||||||
ESP-NETIF Custom I/O Driver
|
ESP-NETIF Custom I/O Driver
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
This section outlines implementing a new I/O driver with esp-netif connection capabilities.
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
By convention, the I/O driver has to register itself as an esp-netif driver, and thus holds a dependency on esp-netif component and is responsible for providing data path functions, post-attach callback and in most cases, also default event handlers to define network interface actions based on driver's lifecycle transitions.
|
This section outlines implementing a new I/O driver with ESP-NETIF connection capabilities.
|
||||||
|
|
||||||
|
By convention, the I/O driver has to register itself as an ESP-NETIF driver, and thus holds a dependency on ESP-NETIF component and is responsible for providing data path functions, post-attach callback and in most cases, also default event handlers to define network interface actions based on driver's lifecycle transitions.
|
||||||
|
|
||||||
|
|
||||||
Packet Input/Output
|
Packet Input/Output
|
||||||
^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
As shown in the diagram, the following three API functions for the packet data path must be defined for connecting with esp-netif:
|
According to the diagram shown in the :ref:`esp-netif structure` part, the following three API functions for the packet data path must be defined for connecting with ESP-NETIF:
|
||||||
|
|
||||||
* :cpp:func:`esp_netif_transmit()`
|
* :cpp:func:`esp_netif_transmit()`
|
||||||
* :cpp:func:`esp_netif_free_rx_buffer()`
|
* :cpp:func:`esp_netif_free_rx_buffer()`
|
||||||
* :cpp:func:`esp_netif_receive()`
|
* :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.
|
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.
|
||||||
|
|
||||||
@ -23,18 +25,18 @@ The receiving function on the other hand gets called from the I/O driver, so tha
|
|||||||
Post Attach Callback
|
Post Attach Callback
|
||||||
^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
A final part of the network interface initialization consists of attaching the esp-netif instance to the I/O driver, by means of calling the following API:
|
A final part of the network interface initialization consists of attaching the ESP-NETIF instance to the I/O driver, by means of calling the following API:
|
||||||
|
|
||||||
.. code:: c
|
.. code:: c
|
||||||
|
|
||||||
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle);
|
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle);
|
||||||
|
|
||||||
It is assumed that the ``esp_netif_iodriver_handle`` is a pointer to driver's object, a struct derived from ``struct esp_netif_driver_base_s``, so that the first member of I/O driver structure must be this base structure with pointers to
|
It is assumed that the ``esp_netif_iodriver_handle`` is a pointer to driver's object, a struct derived from ``struct esp_netif_driver_base_s``, so that the first member of I/O driver structure must be this base structure with pointers to:
|
||||||
|
|
||||||
* post-attach function callback
|
* post-attach function callback
|
||||||
* related esp-netif instance
|
* related ESP-NETIF instance
|
||||||
|
|
||||||
As a consequence the I/O driver has to create an instance of the struct per below:
|
As a result, the I/O driver has to create an instance of the struct per below:
|
||||||
|
|
||||||
.. code:: c
|
.. code:: c
|
||||||
|
|
||||||
@ -45,7 +47,7 @@ As a consequence the I/O driver has to create an instance of the struct per belo
|
|||||||
|
|
||||||
with actual values of ``my_netif_driver_t::base.post_attach`` and the actual drivers handle ``my_netif_driver_t::h``.
|
with actual values of ``my_netif_driver_t::base.post_attach`` and the actual drivers handle ``my_netif_driver_t::h``.
|
||||||
|
|
||||||
So when the :cpp:func:`esp_netif_attach()` gets called from the initialization code, the post-attach callback from I/O driver's code gets executed to mutually register callbacks between esp-netif and I/O driver instances. Typically the driver is started as well in the post-attach callback. An example of a simple post-attach callback is outlined below:
|
So when the :cpp:func:`esp_netif_attach()` gets called from the initialization code, the post-attach callback from I/O driver's code gets executed to mutually register callbacks between ESP-NETIF and I/O driver instances. Typically the driver is started as well in the post-attach callback. An example of a simple post-attach callback is outlined below:
|
||||||
|
|
||||||
.. code:: c
|
.. code:: c
|
||||||
|
|
||||||
@ -67,7 +69,8 @@ So when the :cpp:func:`esp_netif_attach()` gets called from the initialization c
|
|||||||
Default Handlers
|
Default Handlers
|
||||||
^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
I/O drivers also typically provide default definitions of lifecycle behaviour of related network interfaces based on state transitions of I/O drivers. For example *driver start* ``->`` *network start*, etc.
|
I/O drivers also typically provide default definitions of lifecycle behavior of related network interfaces based on state transitions of I/O drivers. For example *driver start* ``->`` *network start*, etc.
|
||||||
|
|
||||||
An example of such a default handler is provided below:
|
An example of such a default handler is provided below:
|
||||||
|
|
||||||
.. code:: c
|
.. code:: c
|
||||||
@ -83,11 +86,10 @@ An example of such a default handler is provided below:
|
|||||||
Network Stack Connection
|
Network Stack Connection
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
The packet data path functions for transmitting and freeing the rx buffer (defined in the I/O driver) are called from the esp-netif, specifically from its TCP/IP stack connecting layer.
|
The packet data path functions for transmitting and freeing the rx buffer (defined in the I/O driver) are called from the ESP-NETIF, specifically from its TCP/IP stack connecting layer.
|
||||||
|
|
||||||
Note, that ESP-IDF provides several network stack configurations for the most common network interfaces, such as for the WiFi station or Ethernet.
|
Note that ESP-IDF provides several network stack configurations for the most common network interfaces, such as for the Wi-Fi station or Ethernet. These configurations are defined in :component_file:`esp_netif/include/esp_netif_defaults.h` and should be sufficient for most network drivers. In rare cases, expert users might want to define custom lwIP based interface layers; it is possible, but an explicit dependency to lwIP needs to be set.
|
||||||
These configurations are defined in :component_file:`esp_netif/include/esp_netif_defaults.h` and should be sufficient for most network drivers. (In rare cases, expert users might want to define custom lwIP based interface layers; it is possible, but an explicit dependency to lwIP needs to be set)
|
|
||||||
|
|
||||||
The following API reference outlines these network stack interaction with the esp-netif:
|
The following API reference outlines these network stack interaction with the ESP-NETIF:
|
||||||
|
|
||||||
.. include-build-file:: inc/esp_netif_net_stack.inc
|
.. include-build-file:: inc/esp_netif_net_stack.inc
|
||||||
|
|||||||
@ -1,26 +1,27 @@
|
|||||||
Thread
|
Thread
|
||||||
==========
|
==========
|
||||||
|
|
||||||
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
Introduction
|
Introduction
|
||||||
------------
|
------------
|
||||||
|
|
||||||
`Thread <https://www.threadgroup.org>`_ is a IP-based mesh networking protocol. It is based on the 802.15.4 physical and MAC layer.
|
`Thread <https://www.threadgroup.org>`_ is an IP-based mesh networking protocol. It is based on the 802.15.4 physical and MAC layer.
|
||||||
|
|
||||||
Application Examples
|
Application Examples
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
The :example:`openthread` directory of ESP-IDF examples contains the following applications:
|
The :example:`openthread` directory of ESP-IDF examples contains the following applications:
|
||||||
|
|
||||||
- The OpenThread interactive shell :example:`openthread/ot_cli`.
|
- The OpenThread interactive shell :example:`openthread/ot_cli`
|
||||||
- The Thread border router :example:`openthread/ot_br`.
|
- The Thread Border Router :example:`openthread/ot_br`
|
||||||
- The Thread radio co-processor :example:`openthread/ot_rcp`.
|
- The Thread Radio Co-Processor :example:`openthread/ot_rcp`
|
||||||
|
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
For manipulating the Thread network, the OpenThread API shall be used.
|
For manipulating the Thread network, the OpenThread API shall be used. The OpenThread API docs can be found at the `OpenThread API docs <https://openthread.io/reference>`_.
|
||||||
The OpenThread API docs can be found at the `OpenThread official website <https://openthread.io/reference>`_.
|
|
||||||
|
|
||||||
ESP-IDF provides extra APIs for launching and managing the OpenThread stack, binding to network interfaces and border routing features.
|
ESP-IDF provides extra APIs for launching and managing the OpenThread stack, binding to network interfaces and border routing features.
|
||||||
|
|
||||||
|
|||||||
@ -1,7 +1,9 @@
|
|||||||
SmartConfig
|
SmartConfig
|
||||||
===========
|
===========
|
||||||
|
|
||||||
The SmartConfig\ :sup:`TM` is a provisioning technology developed by TI to connect a new Wi-Fi device to a Wi-Fi network. It uses a mobile app to broadcast the network credentials from a smartphone, or a tablet, to an un-provisioned Wi-Fi device.
|
:link_to_translation:`zh_CN:[中文]`
|
||||||
|
|
||||||
|
The SmartConfig\ :sup:`TM` is a provisioning technology developed by TI to connect a new Wi-Fi device to a Wi-Fi network. It uses a mobile application to broadcast the network credentials from a smartphone, or a tablet, to an un-provisioned Wi-Fi device.
|
||||||
|
|
||||||
The advantage of this technology is that the device does not need to directly know SSID or password of an Access Point (AP). This information is provided using the smartphone. This is particularly important to headless device and systems, due to their lack of a user interface.
|
The advantage of this technology is that the device does not need to directly know SSID or password of an Access Point (AP). This information is provided using the smartphone. This is particularly important to headless device and systems, due to their lack of a user interface.
|
||||||
|
|
||||||
@ -11,10 +13,10 @@ If you are looking for other options to provision your {IDF_TARGET_NAME} devices
|
|||||||
Application Example
|
Application Example
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
Connect {IDF_TARGET_NAME} to target AP using SmartConfig: :example:`wifi/smart_config`.
|
Connect {IDF_TARGET_NAME} to the target AP using SmartConfig: :example:`wifi/smart_config`.
|
||||||
|
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
.. include-build-file:: inc/esp_smartconfig.inc
|
.. include-build-file:: inc/esp_smartconfig.inc
|
||||||
@ -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 的 API，它们会由默认网络事件句柄调用。
|
||||||
|
|
||||||
|
|
||||||
|
.. _esp-netif structure:
|
||||||
|
|
||||||
ESP-NETIF 架构
|
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` 目录下。
|
本部分的 Thread API 示例代码存放在 ESP-IDF 示例项目的 :example:`openthread` 目录下。
|
||||||
|
|
||||||
IP 网络层协议
|
ESP-NETIF
|
||||||
================
|
=========
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user