forked from espressif/esp-idf
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,8 +1,11 @@
|
||||
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.
|
||||
Easy Connect brings many benefits in the User Experience:
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
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
|
||||
- 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.
|
||||
|
||||
{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™.
|
||||
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.
|
||||
{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.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Example on how to provision {IDF_TARGET_NAME} using a supported smartphone: :example:`wifi/wifi_easy_connect/dpp-enrollee`.
|
||||
|
||||
|
||||
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` 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.
|
||||
|
||||
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 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 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _esp-netif structure:
|
||||
|
||||
ESP-NETIF Architecture
|
||||
----------------------
|
||||
|
||||
|
||||
@@ -1,21 +1,23 @@
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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_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.
|
||||
|
||||
@@ -23,18 +25,18 @@ The receiving function on the other hand gets called from the I/O driver, so tha
|
||||
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
|
||||
|
||||
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
|
||||
* 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
|
||||
|
||||
@@ -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``.
|
||||
|
||||
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
|
||||
|
||||
@@ -67,7 +69,8 @@ So when the :cpp:func:`esp_netif_attach()` gets called from the initialization c
|
||||
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:
|
||||
|
||||
.. code:: c
|
||||
@@ -83,11 +86,10 @@ An example of such a default handler is provided below:
|
||||
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.
|
||||
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)
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
@@ -1,26 +1,27 @@
|
||||
Thread
|
||||
==========
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
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
|
||||
--------------------
|
||||
|
||||
The :example:`openthread` directory of ESP-IDF examples contains the following applications:
|
||||
|
||||
- The OpenThread interactive shell :example:`openthread/ot_cli`.
|
||||
- The Thread border router :example:`openthread/ot_br`.
|
||||
- The Thread radio co-processor :example:`openthread/ot_rcp`.
|
||||
- The OpenThread interactive shell :example:`openthread/ot_cli`
|
||||
- The Thread Border Router :example:`openthread/ot_br`
|
||||
- The Thread Radio Co-Processor :example:`openthread/ot_rcp`
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
For manipulating the Thread network, the OpenThread API shall be used.
|
||||
The OpenThread API docs can be found at the `OpenThread official website <https://openthread.io/reference>`_.
|
||||
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>`_.
|
||||
|
||||
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
|
||||
===========
|
||||
|
||||
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.
|
||||
|
||||
@@ -11,10 +13,10 @@ If you are looking for other options to provision your {IDF_TARGET_NAME} devices
|
||||
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
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_smartconfig.inc
|
||||
.. include-build-file:: inc/esp_smartconfig.inc
|
||||
Reference in New Issue
Block a user