mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-08 04:02:27 +00:00
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
@@ -13,7 +13,7 @@ ESP-IDF provides several kinds of programming interfaces:
|
||||
* :doc:`Kconfig <kconfig>` options can be used in code and in the build system (``CMakeLists.txt``) files.
|
||||
* :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of the ESP-IDF interfaces.
|
||||
|
||||
ESP-IDF is made up of multiple components where these components either contain code specifically written for ESP chips, or contain a third-party library (i.e., a third-party component). In some cases, third-party components will contain an "ESP-IDF specific" wrapper in order to provide an interface that is either simpler or better integrated with the rest of ESP-IDF's features. In other cases, third-party components will present the original API of the underlying library directly.
|
||||
ESP-IDF is made up of multiple components where these components either contain code specifically written for ESP chips, or contain a third-party library (i.e., a third-party component). In some cases, third-party components contain an "ESP-IDF specific" wrapper in order to provide an interface that is either simpler or better integrated with the rest of ESP-IDF's features. In other cases, third-party components present the original API of the underlying library directly.
|
||||
|
||||
The following sections explain some of the aspects of ESP-IDF APIs and their usage.
|
||||
|
||||
@@ -137,7 +137,7 @@ ESP-IDF does not guarantee binary compatibility between releases. This means tha
|
||||
Other Exceptions from Compatibility
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between minor versions in an incompatible way. We appreciate issuing reports about any unintended breaking changes that don't fall into the categories below.
|
||||
While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between minor versions in an incompatible way. We appreciate issuing reports about any unintended breaking changes that do not fall into the categories below.
|
||||
|
||||
* :ref:`api_reference_private_apis`.
|
||||
* :ref:`api_reference_example_components`.
|
||||
|
||||
@@ -43,7 +43,7 @@ Format rules for Kconfig files are as follows:
|
||||
Format Checker
|
||||
--------------
|
||||
|
||||
``tools/ci/check_kconfigs.py`` is provided for checking Kconfig files against the above format rules. The checker checks all Kconfig and ``Kconfig.projbuild`` files in the ESP-IDF directory, and generates a new file with suffix ``.new`` with some suggestions about how to fix issues (if there are any). Please note that the checker cannot correct all format issues and the responsibility of the developer is to final check and make corrections in order to pass the tests. For example, indentations will be corrected if there isn't any misleading formatting, but it cannot come up with a common prefix for options inside a menu.
|
||||
``tools/ci/check_kconfigs.py`` is provided for checking Kconfig files against the above format rules. The checker checks all Kconfig and ``Kconfig.projbuild`` files in the ESP-IDF directory, and generates a new file with suffix ``.new`` with some suggestions about how to fix issues (if there are any). Please note that the checker cannot correct all format issues and the responsibility of the developer is to final check and make corrections in order to pass the tests. For example, indentations will be corrected if there is not any misleading formatting, but it cannot come up with a common prefix for options inside a menu.
|
||||
|
||||
.. _configuration-options-compatibility:
|
||||
|
||||
@@ -52,8 +52,8 @@ Backward Compatibility of Kconfig Options
|
||||
|
||||
The standard Kconfig_ tools ignore unknown options in ``sdkconfig``. So if a developer has custom settings for options which are renamed in newer ESP-IDF releases, then the given setting for the option would be silently ignored. Therefore, several features have been adopted to avoid this:
|
||||
|
||||
1. ``kconfgen`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else. For example, ``menuconfig`` would read them, so the settings for old options will be kept and not ignored.
|
||||
2. ``kconfgen`` recursively finds all ``sdkconfig.rename`` files in ESP-IDF directory which contain old and new ``Kconfig`` option names. Old options are replaced by new ones in the ``sdkconfig`` file. Renames that should only appear for a single target can be placed in a target-specific rename file ``sdkconfig.rename.TARGET``, where ``TARGET`` is the target name, e.g. ``sdkconfig.rename.esp32s2``.
|
||||
1. ``kconfgen`` is used by the tool chain to pre-process ``sdkconfig`` files before anything else. For example, ``menuconfig`` would read them, so the settings for old options is kept and not ignored.
|
||||
2. ``kconfgen`` recursively finds all ``sdkconfig.rename`` files in ESP-IDF directory which contain old and new ``Kconfig`` option names. Old options are replaced by new ones in the ``sdkconfig`` file. Renames that should only appear for a single target can be placed in a target-specific rename file ``sdkconfig.rename.TARGET``, where ``TARGET`` is the target name, e.g., ``sdkconfig.rename.esp32s2``.
|
||||
3. ``kconfgen`` post-processes ``sdkconfig`` files and generates all build outputs (``sdkconfig.h``, ``sdkconfig.cmake``, and ``auto.conf``) by adding a list of compatibility statements, i.e., the values of old options are set for new options after modification. If users still use old options in their code, this will prevent it from breaking.
|
||||
4. :ref:`configuration-deprecated-options` are automatically generated by ``kconfgen``.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
ESP-WIFI-MESH Programming Guide
|
||||
===================================
|
||||
===============================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
@@ -15,7 +15,7 @@ This is a programming guide for ESP-WIFI-MESH, including the API reference and c
|
||||
|
||||
5. :ref:`mesh-api-reference`
|
||||
|
||||
For documentation regarding the ESP-WIFI-MESH protocol, please see the :doc:`ESP-WIFI-MESH API Guide<../../api-guides/esp-wifi-mesh>`. For more information about ESP-WIFI-MESH Development Framework, please see `ESP-WIFI-MESH Development Framework <https://github.com/espressif/esp-mdf>`_.
|
||||
For documentation regarding the ESP-WIFI-MESH protocol, please see the :doc:`ESP-WIFI-MESH API Guide <../../api-guides/esp-wifi-mesh>`. For more information about ESP-WIFI-MESH Development Framework, please see `ESP-WIFI-MESH Development Framework <https://github.com/espressif/esp-mdf>`_.
|
||||
|
||||
|
||||
.. ---------------------- ESP-WIFI-MESH Programming Model --------------------------
|
||||
@@ -28,7 +28,7 @@ ESP-WIFI-MESH Programming Model
|
||||
Software Stack
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The ESP-WIFI-MESH software stack is built atop the Wi-Fi Driver/FreeRTOS and may use the LwIP Stack in some instances (i.e. the root node). The following diagram illustrates the ESP-WIFI-MESH software stack.
|
||||
The ESP-WIFI-MESH software stack is built atop the Wi-Fi Driver/FreeRTOS and may use the LwIP Stack in some instances (i.e., the root node). The following diagram illustrates the ESP-WIFI-MESH software stack.
|
||||
|
||||
.. _mesh-going-to-software-stack:
|
||||
|
||||
@@ -58,6 +58,7 @@ The :cpp:type:`mesh_event_id_t` defines all possible ESP-WIFI-MESH events and ca
|
||||
Typical use cases of mesh events include using events such as :cpp:enumerator:`MESH_EVENT_PARENT_CONNECTED` and :cpp:enumerator:`MESH_EVENT_CHILD_CONNECTED` to indicate when a node can begin transmitting data upstream and downstream respectively. Likewise, :cpp:enumerator:`IP_EVENT_STA_GOT_IP` and :cpp:enumerator:`IP_EVENT_STA_LOST_IP` can be used to indicate when the root node can and cannot transmit data to the external IP network.
|
||||
|
||||
.. warning::
|
||||
|
||||
When using ESP-WIFI-MESH under self-organized mode, users must ensure that no calls to Wi-Fi API are made. This is due to the fact that the self-organizing mode will internally make Wi-Fi API calls to connect/disconnect/scan etc. **Any Wi-Fi calls from the application (including calls from callbacks and handlers of Wi-Fi events) may interfere with ESP-WIFI-MESH's self-organizing behavior**. Therefore, users should not call Wi-Fi APIs after :cpp:func:`esp_mesh_start` is called, and before :cpp:func:`esp_mesh_stop` is called.
|
||||
|
||||
LwIP & ESP-WIFI-MESH
|
||||
@@ -188,45 +189,45 @@ After starting ESP-WIFI-MESH, the application should check for ESP-WIFI-MESH eve
|
||||
|
||||
.. _mesh-self-organized-behavior:
|
||||
|
||||
Self Organized Networking
|
||||
Self-Organized Networking
|
||||
-------------------------
|
||||
|
||||
Self organized networking is a feature of ESP-WIFI-MESH where nodes can autonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-WIFI-MESH network to operate with high degree of autonomy by making the network robust to dynamic network topologies and conditions. With self organized networking enabled, nodes in an ESP-WIFI-MESH network are able to carry out the following actions without autonomously:
|
||||
Self-organized networking is a feature of ESP-WIFI-MESH where nodes can autonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-WIFI-MESH network to operate with high degree of autonomy by making the network robust to dynamic network topologies and conditions. With self-organized networking enabled, nodes in an ESP-WIFI-MESH network are able to carry out the following actions without autonomously:
|
||||
|
||||
- Selection or election of the root node (see **Automatic Root Node Selection** in :ref:`mesh-building-a-network`)
|
||||
- Selection of a preferred parent node (see **Parent Node Selection** in :ref:`mesh-building-a-network`)
|
||||
- Automatic reconnection upon detecting a disconnection (see **Intermediate Parent Node Failure** in :ref:`mesh-managing-a-network`)
|
||||
|
||||
When self organized networking is enabled, the ESP-WIFI-MESH stack will internally make calls to Wi-Fi APIs. Therefore, **the application layer should not make any calls to Wi-Fi APIs whilst self organized networking is enabled as doing so would risk interfering with ESP-WIFI-MESH**.
|
||||
When self-organized networking is enabled, the ESP-WIFI-MESH stack will internally make calls to Wi-Fi APIs. Therefore, **the application layer should not make any calls to Wi-Fi APIs whilst self-organized networking is enabled as doing so would risk interfering with ESP-WIFI-MESH**.
|
||||
|
||||
Toggling Self Organized Networking
|
||||
Toggling Self-Organized Networking
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Self organized networking can be enabled or disabled by the application at runtime by calling the :cpp:func:`esp_mesh_set_self_organized` function. The function has the two following parameters:
|
||||
Self-organized networking can be enabled or disabled by the application at runtime by calling the :cpp:func:`esp_mesh_set_self_organized` function. The function has the two following parameters:
|
||||
|
||||
- ``bool enable`` specifies whether to enable or disable self organized networking.
|
||||
- ``bool enable`` specifies whether to enable or disable self-organized networking.
|
||||
|
||||
- ``bool select_parent`` specifies whether a new parent node should be selected when enabling self organized networking. Selecting a new parent has different effects depending the node type and the node's current state. This parameter is unused when disabling self organized networking.
|
||||
- ``bool select_parent`` specifies whether a new parent node should be selected when enabling self-organized networking. Selecting a new parent has different effects depending the node type and the node's current state. This parameter is unused when disabling self-organized networking.
|
||||
|
||||
Disabling Self Organized Networking
|
||||
Disabling Self-Organized Networking
|
||||
"""""""""""""""""""""""""""""""""""
|
||||
The following code snippet demonstrates how to disable self organized networking.
|
||||
The following code snippet demonstrates how to disable self-organized networking.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Disable self organized networking
|
||||
//Disable self-organized networking
|
||||
esp_mesh_set_self_organized(false, false);
|
||||
|
||||
ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when disabling self organized networking.
|
||||
ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when disabling self-organized networking.
|
||||
|
||||
- If the node was previously connected to other nodes, it will remain connected.
|
||||
- If the node was previously disconnected and was scanning for a parent node or router, it will stop scanning.
|
||||
- If the node was previously attempting to reconnect to a parent node or router, it will stop reconnecting.
|
||||
|
||||
Enabling Self Organized Networking
|
||||
Enabling Self-Organized Networking
|
||||
""""""""""""""""""""""""""""""""""
|
||||
|
||||
ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when enabling self organized networking. However, depending on the node type and whether a new parent is selected, the Wi-Fi state of the node can change. The following table shows effects of enabling self organized networking.
|
||||
ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when enabling self-organized networking. However, depending on the node type and whether a new parent is selected, the Wi-Fi state of the node can change. The following table shows effects of enabling self-organized networking.
|
||||
|
||||
+---------------+--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| Select Parent | Is Root Node | Effects |
|
||||
@@ -244,16 +245,16 @@ ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when enabl
|
||||
| | | disconnect from the router and all child nodes, select a preferred parent node, and connect. |
|
||||
+---------------+--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
The following code snipping demonstrates how to enable self organized networking.
|
||||
The following code snipping demonstrates how to enable self-organized networking.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Enable self organized networking and select a new parent
|
||||
//Enable self-organized networking and select a new parent
|
||||
esp_mesh_set_self_organized(true, true);
|
||||
|
||||
...
|
||||
|
||||
//Enable self organized networking and manually reconnect
|
||||
//Enable self-organized networking and manually reconnect
|
||||
esp_mesh_set_self_organized(true, false);
|
||||
esp_mesh_connect();
|
||||
|
||||
@@ -261,13 +262,13 @@ The following code snipping demonstrates how to enable self organized networking
|
||||
Calling Wi-Fi API
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
There can be instances in which an application may want to directly call Wi-Fi API whilst using ESP-WIFI-MESH. For example, an application may want to manually scan for neighboring APs. However, **self organized networking must be disabled before the application calls any Wi-Fi APIs**. This will prevent the ESP-WIFI-MESH stack from attempting to call any Wi-Fi APIs and potentially interfering with the application's calls.
|
||||
There can be instances in which an application may want to directly call Wi-Fi API whilst using ESP-WIFI-MESH. For example, an application may want to manually scan for neighboring APs. However, **self-organized networking must be disabled before the application calls any Wi-Fi APIs**. This will prevent the ESP-WIFI-MESH stack from attempting to call any Wi-Fi APIs and potentially interfering with the application's calls.
|
||||
|
||||
Therefore, application calls to Wi-Fi APIs should be placed in between calls of :cpp:func:`esp_mesh_set_self_organized` which disable and enable self organized networking. The following code snippet demonstrates how an application can safely call :cpp:func:`esp_wifi_scan_start` whilst using ESP-WIFI-MESH.
|
||||
Therefore, application calls to Wi-Fi APIs should be placed in between calls of :cpp:func:`esp_mesh_set_self_organized` which disable and enable self-organized networking. The following code snippet demonstrates how an application can safely call :cpp:func:`esp_wifi_scan_start` whilst using ESP-WIFI-MESH.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Disable self organized networking
|
||||
//Disable self-organized networking
|
||||
esp_mesh_set_self_organized(0, 0);
|
||||
|
||||
//Stop any scans already in progress
|
||||
@@ -279,18 +280,18 @@ Therefore, application calls to Wi-Fi APIs should be placed in between calls of
|
||||
|
||||
...
|
||||
|
||||
//Re-enable self organized networking if still connected
|
||||
//Re-enable self-organized networking if still connected
|
||||
esp_mesh_set_self_organized(1, 0);
|
||||
|
||||
...
|
||||
|
||||
//Re-enable self organized networking if non-root and disconnected
|
||||
//Re-enable self-organized networking if non-root and disconnected
|
||||
esp_mesh_set_self_organized(1, 1);
|
||||
|
||||
...
|
||||
|
||||
//Re-enable self organized networking if root and disconnected
|
||||
esp_mesh_set_self_organized(1, 0); //Don't select new parent
|
||||
//Re-enable self-organized networking if root and disconnected
|
||||
esp_mesh_set_self_organized(1, 0); //Do not select new parent
|
||||
esp_mesh_connect(); //Manually reconnect to router
|
||||
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ Ethernet is an asynchronous Carrier Sense Multiple Access with Collision Detect
|
||||
|
||||
Normal IEEE 802.3 compliant Ethernet frames are between 64 and 1518 bytes in length. They are made up of five or six different fields: a destination MAC address (DA), a source MAC address (SA), a type/length field, a data payload, an optional padding field and a Cyclic Redundancy Check (CRC). Additionally, when transmitted on the Ethernet medium, a 7-byte preamble field and Start-of-Frame (SOF) delimiter byte are appended to the beginning of the Ethernet packet.
|
||||
|
||||
Thus the traffic on the twist-pair cabling will appear as shown below:
|
||||
Thus the traffic on the twist-pair cabling appears as shown below:
|
||||
|
||||
.. rackdiag:: ../../../_static/diagrams/ethernet/data_frame_format.diag
|
||||
:caption: Ethernet Data Frame Format
|
||||
@@ -41,14 +41,14 @@ The preamble contains seven bytes of ``55H``. It allows the receiver to lock ont
|
||||
|
||||
The Start-of-Frame Delimiter (SFD) is a binary sequence ``10101011`` (as seen on the physical medium). It is sometimes considered to be part of the preamble.
|
||||
|
||||
When transmitting and receiving data, the preamble and SFD bytes will automatically be generated or stripped from the packets.
|
||||
When transmitting and receiving data, the preamble and SFD bytes will be automatically generated or stripped from the packets.
|
||||
|
||||
Destination Address
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The destination address field contains a 6-byte length MAC address of the device that the packet is directed to. If the Least Significant bit in the first byte of the MAC address is set, the address is a multicast destination. For example, 01-00-00-00-F0-00 and 33-45-67-89-AB-CD are multi-cast addresses, while 00-00-00-00-F0-00 and 32-45-67-89-AB-CD are not.
|
||||
|
||||
Packets with multi-cast destination addresses are designed to arrive and be important to a selected group of Ethernet nodes. If the destination address field is the reserved multicast address, i.e. FF-FF-FF-FF-FF-FF, the packet is a broadcast packet and it will be directed to everyone sharing the network. If the Least Significant bit in the first byte of the MAC address is clear, the address is a unicast address and will be designed for usage by only the addressed node.
|
||||
Packets with multi-cast destination addresses are designed to arrive and be important to a selected group of Ethernet nodes. If the destination address field is the reserved multicast address, i.e., FF-FF-FF-FF-FF-FF, the packet is a broadcast packet and it will be directed to everyone sharing the network. If the Least Significant bit in the first byte of the MAC address is clear, the address is a unicast address and will be designed for usage by only the addressed node.
|
||||
|
||||
Normally the EMAC controller incorporates receive filters which can be used to discard or accept packets with multi-cast, broadcast and/or unicast destination addresses. When transmitting packets, the host controller is responsible for writing the desired destination address into the transmit buffer.
|
||||
|
||||
@@ -68,12 +68,12 @@ The type/length field is a 2-byte field. If the value in this field is <= 1500 (
|
||||
* IPv6 = 86DDH
|
||||
* ARP = 0806H
|
||||
|
||||
Users implementing proprietary networks may choose to treat this field as a length field, while applications implementing protocols such as the Internet Protocol (IP) or Address Resolution Protocol (ARP), should program this field with the appropriate type defined by the protocol’s specification when transmitting packets.
|
||||
Users implementing proprietary networks may choose to treat this field as a length field, while applications implementing protocols such as the Internet Protocol (IP) or Address Resolution Protocol (ARP), should program this field with the appropriate type defined by the protocol's specification when transmitting packets.
|
||||
|
||||
Payload
|
||||
^^^^^^^
|
||||
|
||||
The payload field is a variable length field, anywhere from 0 to 1500 bytes. Larger data packets will violate Ethernet standards and will be dropped by most Ethernet nodes.
|
||||
The payload field is a variable length field, anywhere from 0 to 1500 bytes. Larger data packets violates Ethernet standards and will be dropped by most Ethernet nodes.
|
||||
|
||||
This field contains the client data, such as an IP datagram.
|
||||
|
||||
@@ -84,12 +84,12 @@ The padding field is a variable length field added to meet the IEEE 802.3 specif
|
||||
|
||||
The DA, SA, type, payload, and padding of an Ethernet packet must be no smaller than 60 bytes in total. If the required 4-byte FCS field is added, packets must be no smaller than 64 bytes. If the payload field is less than 46-byte long, a padding field is required.
|
||||
|
||||
The FCS field is a 4-byte field that contains an industry-standard 32-bit CRC calculated with the data from the DA, SA, type, payload, and padding fields. Given the complexity of calculating a CRC, the hardware normally will automatically generate a valid CRC and transmit it. Otherwise, the host controller must generate the CRC and place it in the transmit buffer.
|
||||
The FCS field is a 4-byte field that contains an industry-standard 32-bit CRC calculated with the data from the DA, SA, type, payload, and padding fields. Given the complexity of calculating a CRC, the hardware normally automatically generates a valid CRC and transmit it. Otherwise, the host controller must generate the CRC and place it in the transmit buffer.
|
||||
|
||||
Normally, the host controller does not need to concern itself with padding and the CRC which the hardware EMAC will also be able to automatically generate when transmitting and verify when receiving. However, the padding and CRC fields will be written into the receive buffer when packets arrive, so they may be evaluated by the host controller if needed.
|
||||
|
||||
.. note::
|
||||
Besides the basic data frame described above, there're two other common frame types in 10/100 Mbps Ethernet: control frames and VLAN-tagged frames. They're not supported in ESP-IDF.
|
||||
Besides the basic data frame described above, there are two other common frame types in 10/100 Mbps Ethernet: control frames and VLAN-tagged frames. They are not supported in ESP-IDF.
|
||||
|
||||
.. ------------------------------ Driver Operation --------------------------------
|
||||
|
||||
@@ -115,11 +115,11 @@ The Ethernet driver is composed of two parts: MAC and PHY.
|
||||
|
||||
In RMII mode, both the receiver and transmitter signals are referenced to the ``REF_CLK``. **REF_CLK must be stable during any access to PHY and MAC**. Generally, there are three ways to generate the ``REF_CLK`` depending on the PHY device in your design:
|
||||
|
||||
* Some PHY chips can derive the ``REF_CLK`` from its externally connected 25 MHz crystal oscillator (as seen the option *a* in the picture). In this case, you should select ``CONFIG_ETH_RMII_CLK_INPUT`` in :ref:`CONFIG_ETH_RMII_CLK_MODE`.
|
||||
* Some PHY chips can derive the ``REF_CLK`` from its externally connected 25 MHz crystal oscillator (as seen the option **a** in the picture). In this case, you should select ``CONFIG_ETH_RMII_CLK_INPUT`` in :ref:`CONFIG_ETH_RMII_CLK_MODE`.
|
||||
|
||||
* Some PHY chip uses an externally connected 50MHz crystal oscillator or other clock sources, which can also be used as the ``REF_CLK`` for the MAC side (as seen the option *b* in the picture). In this case, you still need to select ``CONFIG_ETH_RMII_CLK_INPUT`` in :ref:`CONFIG_ETH_RMII_CLK_MODE`.
|
||||
* Some PHY chip uses an externally connected 50MHz crystal oscillator or other clock sources, which can also be used as the ``REF_CLK`` for the MAC side (as seen the option **b** in the picture). In this case, you still need to select ``CONFIG_ETH_RMII_CLK_INPUT`` in :ref:`CONFIG_ETH_RMII_CLK_MODE`.
|
||||
|
||||
* Some EMAC controllers can generate the ``REF_CLK`` using an internal high-precision PLL (as seen the option *c* in the picture). In this case, you should select ``CONFIG_ETH_RMII_CLK_OUTPUT`` in :ref:`CONFIG_ETH_RMII_CLK_MODE`.
|
||||
* Some EMAC controllers can generate the ``REF_CLK`` using an internal high-precision PLL (as seen the option **c** in the picture). In this case, you should select ``CONFIG_ETH_RMII_CLK_OUTPUT`` in :ref:`CONFIG_ETH_RMII_CLK_MODE`.
|
||||
|
||||
.. note::
|
||||
``REF_CLK`` is configured via Project Configuration as described above by default. However, it can be overwritten from user application code by appropriately setting :cpp:member:`eth_esp32_emac_config_t::interface` and :cpp:member:`eth_esp32_emac_config_t::clock_config` members. See :cpp:enum:`emac_rmii_clock_mode_t` and :cpp:enum:`emac_rmii_clock_gpio_t` for more details.
|
||||
@@ -127,22 +127,22 @@ The Ethernet driver is composed of two parts: MAC and PHY.
|
||||
.. warning::
|
||||
If the RMII clock mode is selected to ``CONFIG_ETH_RMII_CLK_OUTPUT``, then ``GPIO0`` can be used to output the ``REF_CLK`` signal. See :ref:`CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0` for more information.
|
||||
|
||||
What's more, if you're not using PSRAM in your design, GPIO16 and GPIO17 are also available to output the reference clock. See :ref:`CONFIG_ETH_RMII_CLK_OUT_GPIO` for more information.
|
||||
What is more, if you are not using PSRAM in your design, GPIO16 and GPIO17 are also available to output the reference clock. See :ref:`CONFIG_ETH_RMII_CLK_OUT_GPIO` for more information.
|
||||
|
||||
If the RMII clock mode is selected to ``CONFIG_ETH_RMII_CLK_INPUT``, then ``GPIO0`` is the only choice to input the ``REF_CLK`` signal. Please note that ``GPIO0`` is also an important strapping GPIO on ESP32. If GPIO0 samples a low level during power-up, ESP32 will go into download mode. The system will get halted until a manually reset. The workaround for this issue is disabling the ``REF_CLK`` in hardware by default so that the strapping pin won't be interfered by other signals in the boot stage. Then, re-enable the ``REF_CLK`` in the Ethernet driver installation stage.
|
||||
If the RMII clock mode is selected to ``CONFIG_ETH_RMII_CLK_INPUT``, then ``GPIO0`` is the only choice to input the ``REF_CLK`` signal. Please note that ``GPIO0`` is also an important strapping GPIO on ESP32. If GPIO0 samples a low level during power-up, ESP32 will go into download mode. The system will get halted until a manually reset. The workaround for this issue is disabling the ``REF_CLK`` in hardware by default so that the strapping pin is not interfered by other signals in the boot stage. Then, re-enable the ``REF_CLK`` in the Ethernet driver installation stage.
|
||||
|
||||
The ways to disable the ``REF_CLK`` signal can be:
|
||||
|
||||
* Disable or power down the crystal oscillator (as the case *b* in the picture).
|
||||
* Disable or power down the crystal oscillator (as the case **b** in the picture).
|
||||
|
||||
* Force the PHY device to reset status (as the case *a* in the picture). **This could fail for some PHY device** (i.e. it still outputs signals to GPIO0 even in reset state).
|
||||
* Force the PHY device to reset status (as the case **a** in the picture). **This could fail for some PHY device** (i.e., it still outputs signals to GPIO0 even in reset state).
|
||||
|
||||
**No matter which RMII clock mode you select, you really need to take care of the signal integrity of REF_CLK in your hardware design!** Keep the trace as short as possible. Keep it away from RF devices and inductor elements.
|
||||
|
||||
.. note::
|
||||
ESP-IDF only supports the RMII interface (i.e. always select ``CONFIG_ETH_PHY_INTERFACE_RMII`` in the Kconfig option :ref:`CONFIG_ETH_PHY_INTERFACE`).
|
||||
ESP-IDF only supports the RMII interface (i.e., always select ``CONFIG_ETH_PHY_INTERFACE_RMII`` in the Kconfig option :ref:`CONFIG_ETH_PHY_INTERFACE`).
|
||||
|
||||
Signals used in the data plane are fixed to specific GPIOs via MUX, they can't be modified to other GPIOs. Signals used in the control plane can be routed to any free GPIOs via Matrix. Please refer to :doc:`ESP32-Ethernet-Kit <../../hw-reference/esp32/get-started-ethernet-kit>` for hardware design example.
|
||||
Signals used in the data plane are fixed to specific GPIOs via MUX, they can not be modified to other GPIOs. Signals used in the control plane can be routed to any free GPIOs via Matrix. Please refer to :doc:`ESP32-Ethernet-Kit <../../hw-reference/esp32/get-started-ethernet-kit>` for hardware design example.
|
||||
|
||||
You need to set up the necessary parameters for MAC and PHY respectively based on your Ethernet board design, and then combine the two together to complete the driver installation.
|
||||
|
||||
@@ -166,13 +166,13 @@ Configuration for PHY is described in :cpp:class:`eth_phy_config_t`, including:
|
||||
|
||||
.. list::
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::phy_addr`: multiple PHY devices can share the same SMI bus, so each PHY needs a unique address. Usually, this address is configured during hardware design by pulling up/down some PHY strapping pins. You can set the value from 0 to 15 based on your Ethernet board. Especially, if the SMI bus is shared by only one PHY device, setting this value to -1 can enable the driver to detect the PHY address automatically.
|
||||
* :cpp:member:`eth_phy_config_t::phy_addr`: multiple PHY devices can share the same SMI bus, so each PHY needs a unique address. Usually, this address is configured during hardware design by pulling up/down some PHY strapping pins. You can set the value from ``0`` to ``15`` based on your Ethernet board. Especially, if the SMI bus is shared by only one PHY device, setting this value to ``-1`` can enable the driver to detect the PHY address automatically.
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::reset_timeout_ms`: reset timeout value, in milliseconds. Typically, PHY reset should be finished within 100 ms.
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::autonego_timeout_ms`: auto-negotiation timeout value, in milliseconds. The Ethernet driver will start negotiation with the peer Ethernet node automatically, to determine to duplex and speed mode. This value usually depends on the ability of the PHY device on your board.
|
||||
* :cpp:member:`eth_phy_config_t::autonego_timeout_ms`: auto-negotiation timeout value, in milliseconds. The Ethernet driver starts negotiation with the peer Ethernet node automatically, to determine to duplex and speed mode. This value usually depends on the ability of the PHY device on your board.
|
||||
|
||||
* :cpp:member:`eth_phy_config_t::reset_gpio_num`: if your board also connects the PHY reset pin to one of the GPIO, then set it here. Otherwise, set this field to -1.
|
||||
* :cpp:member:`eth_phy_config_t::reset_gpio_num`: if your board also connects the PHY reset pin to one of the GPIO, then set it here. Otherwise, set this field to ``-1``.
|
||||
|
||||
ESP-IDF provides a default configuration for MAC and PHY in macro :c:macro:`ETH_MAC_DEFAULT_CONFIG` and :c:macro:`ETH_PHY_DEFAULT_CONFIG`.
|
||||
|
||||
@@ -263,23 +263,23 @@ SPI-Ethernet Module
|
||||
|
||||
|
||||
.. note::
|
||||
* When creating MAC and PHY instances for SPI-Ethernet modules (e.g. DM9051), the constructor function must have the same suffix (e.g. `esp_eth_mac_new_dm9051` and `esp_eth_phy_new_dm9051`). This is because we don't have other choices but the integrated PHY.
|
||||
* When creating MAC and PHY instances for SPI-Ethernet modules (e.g., DM9051), the constructor function must have the same suffix (e.g., `esp_eth_mac_new_dm9051` and `esp_eth_phy_new_dm9051`). This is because we don not have other choices but the integrated PHY.
|
||||
|
||||
* The SPI device configuration (i.e. `spi_device_interface_config_t`) may slightly differ for other Ethernet modules or to meet SPI timing on specific PCB. Please check out your module's specs and the examples in ESP-IDF.
|
||||
* The SPI device configuration (i.e., `spi_device_interface_config_t`) may slightly differ for other Ethernet modules or to meet SPI timing on specific PCB. Please check out your module's specs and the examples in ESP-IDF.
|
||||
|
||||
|
||||
Install Driver
|
||||
--------------
|
||||
|
||||
To install the Ethernet driver, we need to combine the instance of MAC and PHY and set some additional high-level configurations (i.e. not specific to either MAC or PHY) in :cpp:class:`esp_eth_config_t`:
|
||||
To install the Ethernet driver, we need to combine the instance of MAC and PHY and set some additional high-level configurations (i.e., not specific to either MAC or PHY) in :cpp:class:`esp_eth_config_t`:
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::mac`: instance that created from MAC generator (e.g. :cpp:func:`esp_eth_mac_new_esp32`).
|
||||
* :cpp:member:`esp_eth_config_t::mac`: instance that created from MAC generator (e.g., :cpp:func:`esp_eth_mac_new_esp32`).
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::phy`: instance that created from PHY generator (e.g. :cpp:func:`esp_eth_phy_new_ip101`).
|
||||
* :cpp:member:`esp_eth_config_t::phy`: instance that created from PHY generator (e.g., :cpp:func:`esp_eth_phy_new_ip101`).
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::check_link_period_ms`: Ethernet driver starts an OS timer to check the link status periodically, this field is used to set the interval, in milliseconds.
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::stack_input`: In most Ethernet IoT applications, any Ethernet frame received by a driver should be passed to the upper layer (e.g. TCP/IP stack). This field is set to a function that is responsible to deal with the incoming frames. You can even update this field at runtime via function :cpp:func:`esp_eth_update_input_path` after driver installation.
|
||||
* :cpp:member:`esp_eth_config_t::stack_input`: In most Ethernet IoT applications, any Ethernet frame received by a driver should be passed to the upper layer (e.g., TCP/IP stack). This field is set to a function that is responsible to deal with the incoming frames. You can even update this field at runtime via function :cpp:func:`esp_eth_update_input_path` after driver installation.
|
||||
|
||||
* :cpp:member:`esp_eth_config_t::on_lowlevel_init_done` and :cpp:member:`esp_eth_config_t::on_lowlevel_deinit_done`: These two fields are used to specify the hooks which get invoked when low-level hardware has been initialized or de-initialized.
|
||||
|
||||
@@ -293,7 +293,7 @@ ESP-IDF provides a default configuration for driver installation in macro :c:mac
|
||||
esp_eth_handle_t eth_handle = NULL; // after the driver is installed, we will get the handle of the driver
|
||||
esp_eth_driver_install(&config, ð_handle); // install driver
|
||||
|
||||
The Ethernet driver also includes an event-driven model, which will send useful and important events to user space. We need to initialize the event loop before installing the Ethernet driver. For more information about event-driven programming, please refer to :doc:`ESP Event <../system/esp_event>`.
|
||||
The Ethernet driver also includes an event-driven model, which sends useful and important events to user space. We need to initialize the event loop before installing the Ethernet driver. For more information about event-driven programming, please refer to :doc:`ESP Event <../system/esp_event>`.
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
@@ -347,7 +347,7 @@ After driver installation, we can start Ethernet immediately.
|
||||
Connect Driver to TCP/IP Stack
|
||||
------------------------------
|
||||
|
||||
Up until now, we have installed the Ethernet driver. From the view of OSI (Open System Interconnection), we're still on level 2 (i.e. Data Link Layer). While we can detect link up and down events and gain MAC address in user space, it's infeasible to obtain the IP address, let alone send an HTTP request. The TCP/IP stack used in ESP-IDF is called LwIP. For more information about it, please refer to :doc:`LwIP <../../api-guides/lwip>`.
|
||||
Up until now, we have installed the Ethernet driver. From the view of OSI (Open System Interconnection), we are still on level 2 (i.e., Data Link Layer). While we can detect link up and down events and gain MAC address in user space, it is infeasible to obtain the IP address, let alone send an HTTP request. The TCP/IP stack used in ESP-IDF is called LwIP. For more information about it, please refer to :doc:`LwIP <../../api-guides/lwip>`.
|
||||
|
||||
To connect the Ethernet driver to TCP/IP stack, follow these three steps:
|
||||
|
||||
@@ -385,7 +385,7 @@ For more information about the network interface, please refer to :doc:`Network
|
||||
esp_eth_start(eth_handle); // start Ethernet driver state machine
|
||||
|
||||
.. warning::
|
||||
It is recommended to fully initialize the Ethernet driver and network interface before registering the user's Ethernet/IP event handlers, i.e. register the event handlers as the last thing prior to starting the Ethernet driver. Such an approach ensures that Ethernet/IP events get executed first by the Ethernet driver or network interface so the system is in the expected state when executing the user's handlers.
|
||||
It is recommended to fully initialize the Ethernet driver and network interface before registering the user's Ethernet/IP event handlers, i.e., register the event handlers as the last thing prior to starting the Ethernet driver. Such an approach ensures that Ethernet/IP events get executed first by the Ethernet driver or network interface so the system is in the expected state when executing the user's handlers.
|
||||
|
||||
.. _misc-operation-of-driver:
|
||||
|
||||
@@ -421,7 +421,7 @@ Flow Control
|
||||
|
||||
Ethernet on MCU usually has a limitation in the number of frames it can handle during network congestion, because of the limitation in RAM size. A sending station might be transmitting data faster than the peer end can accept it. The ethernet flow control mechanism allows the receiving node to signal the sender requesting the suspension of transmissions until the receiver catches up. The magic behind that is the pause frame, which was defined in IEEE 802.3x.
|
||||
|
||||
Pause frame is a special Ethernet frame used to carry the pause command, whose EtherType field is 0x8808, with the Control opcode set to 0x0001. Only stations configured for full-duplex operation may send pause frames. When a station wishes to pause the other end of a link, it sends a pause frame to the 48-bit reserved multicast address of 01-80-C2-00-00-01. The pause frame also includes the period of pause time being requested, in the form of a two-byte integer, ranging from 0 to 65535.
|
||||
Pause frame is a special Ethernet frame used to carry the pause command, whose EtherType field is ``0x8808``, with the Control opcode set to ``0x0001``. Only stations configured for full-duplex operation may send pause frames. When a station wishes to pause the other end of a link, it sends a pause frame to the 48-bit reserved multicast address of ``01-80-C2-00-00-01``. The pause frame also includes the period of pause time being requested, in the form of a two-byte integer, ranging from ``0`` to ``65535``.
|
||||
|
||||
After the Ethernet driver installation, the flow control feature is disabled by default. You can enable it by:
|
||||
|
||||
@@ -432,7 +432,7 @@ After the Ethernet driver installation, the flow control feature is disabled by
|
||||
bool flow_ctrl_enable = true;
|
||||
esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, &flow_ctrl_enable);
|
||||
|
||||
One thing that should be kept in mind is that the pause frame ability will be advertised to the peer end by PHY during auto-negotiation. The Ethernet driver sends a pause frame only when both sides of the link support it.
|
||||
One thing that should be kept in mind is that the pause frame ability is advertised to the peer end by PHY during auto-negotiation. The Ethernet driver sends a pause frame only when both sides of the link support it.
|
||||
|
||||
.. -------------------------------- Examples -----------------------------------
|
||||
|
||||
@@ -460,7 +460,7 @@ There are multiple PHY manufacturers with wide portfolios of chips available. Th
|
||||
Luckily, a management interface between EMAC and PHY is standardized by IEEE 802.3 in Section 22.2.4 Management Functions. It defines provisions of the so-called “MII Management Interface” to control the PHY and gather status from the PHY. A set of management registers is defined to control chip behavior, link properties, auto-negotiation configuration, etc. This basic management functionality is addressed by :component_file:`esp_eth/src/esp_eth_phy_802_3.c` in ESP-IDF and so it makes the creation of a new custom PHY chip driver quite a simple task.
|
||||
|
||||
.. note::
|
||||
Always consult with PHY datasheet since some PHY chips may not comply with IEEE 802.3, Section 22.2.4. It does not mean you are not able to create a custom PHY driver, it will just require more effort. You will have to define all PHY management functions.
|
||||
Always consult with PHY datasheet since some PHY chips may not comply with IEEE 802.3, Section 22.2.4. It does not mean you are not able to create a custom PHY driver, but it just requires more effort. You will have to define all PHY management functions.
|
||||
|
||||
The majority of PHY management functionality required by the ESP-IDF Ethernet driver is covered by the :component_file:`esp_eth/src/esp_eth_phy_802_3.c`. However, the following may require developing chip-specific management functions:
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ 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.
|
||||
|
||||
Multiple NAN devices which are in the vicinity will 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.
|
||||
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.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ ESP-NETIF
|
||||
|
||||
The purpose of the ESP-NETIF library is twofold:
|
||||
|
||||
- It provides an abstraction layer for the application on top of the TCP/IP stack. This will allow applications to choose between IP stacks in the future.
|
||||
- It provides an abstraction layer for the application on top of the TCP/IP stack. This allows applications to choose between IP stacks in the future.
|
||||
- The APIs it provides are thread-safe, even if the underlying TCP/IP stack APIs are not.
|
||||
|
||||
ESP-IDF currently implements ESP-NETIF for the lwIP TCP/IP stack only. However, the adapter itself is TCP/IP implementation-agnostic and allows different implementations.
|
||||
@@ -76,7 +76,7 @@ Data and Event Flow in the Diagram
|
||||
ESP-NETIF Interaction
|
||||
---------------------
|
||||
|
||||
A) User code, boilerplate
|
||||
A) User Code, Boilerplate
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Overall application interaction with a specific IO driver for communication media and configured TCP/IP network stack is abstracted using ESP-NETIF APIs and is outlined as below:
|
||||
@@ -151,7 +151,7 @@ The ESP-NETIF L2 TAP interface is a mechanism in ESP-IDF used to access Data Lin
|
||||
|
||||
From a user perspective, the ESP-NETIF L2 TAP interface is accessed using file descriptors of VFS, which provides file-like interfacing (using functions like ``open()``, ``read()``, ``write()``, etc). To learn more, refer to :doc:`/api-reference/storage/vfs`.
|
||||
|
||||
There is only one ESP-NETIF L2 TAP interface device (path name) available. However multiple file descriptors with different configurations can be opened at a time since the ESP-NETIF L2 TAP interface can be understood as a generic entry point to the Layer 2 infrastructure. What is important is then the specific configuration of the particular file descriptor. It can be configured to give access to a specific Network Interface identified by ``if_key`` (e.g. `ETH_DEF`) and to filter only specific frames based on their type (e.g. Ethernet type in the case of IEEE 802.3). Filtering only specific frames is crucial since the ESP-NETIF L2 TAP needs to exist along with the IP stack and so the IP-related traffic (IP, ARP, etc.) should not be passed directly to the user application. Even though this option is still configurable, it is not recommended in standard use cases. Filtering is also advantageous from the perspective of the user’s application, as it only gets access to the frame types it is interested in, and the remaining traffic is either passed to other L2 TAP file descriptors or to the IP stack.
|
||||
There is only one ESP-NETIF L2 TAP interface device (path name) available. However multiple file descriptors with different configurations can be opened at a time since the ESP-NETIF L2 TAP interface can be understood as a generic entry point to the Layer 2 infrastructure. What is important is then the specific configuration of the particular file descriptor. It can be configured to give access to a specific Network Interface identified by ``if_key`` (e.g., `ETH_DEF`) and to filter only specific frames based on their type (e.g., Ethernet type in the case of IEEE 802.3). Filtering only specific frames is crucial since the ESP-NETIF L2 TAP needs to exist along with the IP stack and so the IP-related traffic (IP, ARP, etc.) should not be passed directly to the user application. Even though this option is still configurable, it is not recommended in standard use cases. Filtering is also advantageous from the perspective of the user's application, as it only gets access to the frame types it is interested in, and the remaining traffic is either passed to other L2 TAP file descriptors or to the IP stack.
|
||||
|
||||
ESP-NETIF L2 TAP Interface Usage Manual
|
||||
---------------------------------------
|
||||
@@ -160,21 +160,21 @@ Initialization
|
||||
^^^^^^^^^^^^^^
|
||||
To be able to use the ESP-NETIF L2 TAP interface, it needs to be enabled in Kconfig by :ref:`CONFIG_ESP_NETIF_L2_TAP` first and then registered by :cpp:func:`esp_vfs_l2tap_intf_register()` prior usage of any VFS function.
|
||||
|
||||
open()
|
||||
^^^^^^
|
||||
``open()``
|
||||
^^^^^^^^^^
|
||||
Once the ESP-NETIF L2 TAP is registered, it can be opened at path name “/dev/net/tap”. The same path name can be opened multiple times up to :ref:`CONFIG_ESP_NETIF_L2_TAP_MAX_FDS` and multiple file descriptors with a different configuration may access the Data Link Layer frames.
|
||||
|
||||
The ESP-NETIF L2 TAP can be opened with the ``O_NONBLOCK`` file status flag to make sure the ``read()`` does not block. Note that the ``write()`` may block in the current implementation when accessing a Network interface since it is a shared resource among multiple ESP-NETIF L2 TAP file descriptors and IP stack, and there is currently no queuing mechanism deployed. The file status flag can be retrieved and modified using ``fcntl()``.
|
||||
|
||||
On success, ``open()`` returns the new file descriptor (a nonnegative integer). On error, -1 is returned, and ``errno`` is set to indicate the error.
|
||||
|
||||
ioctl()
|
||||
^^^^^^^
|
||||
``ioctl()``
|
||||
^^^^^^^^^^^
|
||||
The newly opened ESP-NETIF L2 TAP file descriptor needs to be configured prior to its usage since it is not bounded to any specific Network Interface and no frame type filter is configured. The following configuration options are available to do so:
|
||||
|
||||
* ``L2TAP_S_INTF_DEVICE`` - bounds the file descriptor to a specific Network Interface that is identified by its ``if_key``. ESP-NETIF Network Interface ``if_key`` is passed to ``ioctl()`` as the third parameter. Note that default Network Interfaces ``if_key``'s used in ESP-IDF can be found in :component_file:`esp_netif/include/esp_netif_defaults.h`.
|
||||
* ``L2TAP_S_DEVICE_DRV_HNDL`` - is another way to bound the file descriptor to a specific Network Interface. In this case, the Network interface is identified directly by IO Driver handle (e.g. :cpp:type:`esp_eth_handle_t` in case of Ethernet). The IO Driver handle is passed to ``ioctl()`` as the third parameter.
|
||||
* ``L2TAP_S_RCV_FILTER`` - sets the filter to frames with the type to be passed to the file descriptor. In the case of Ethernet frames, the frames are to be filtered based on the Length and Ethernet type field. In case the filter value is set less than or equal to 0x05DC, the Ethernet type field is considered to represent IEEE802.3 Length Field, and all frames with values in interval <0, 0x05DC> at that field will be passed to the file descriptor. The IEEE802.2 logical link control (LLC) resolution is then expected to be performed by the user’s application. In case the filter value is set greater than 0x05DC, the Ethernet type field is considered to represent protocol identification and only frames that are equal to the set value are to be passed to the file descriptor.
|
||||
* ``L2TAP_S_DEVICE_DRV_HNDL`` - is another way to bound the file descriptor to a specific Network Interface. In this case, the Network interface is identified directly by IO Driver handle (e.g., :cpp:type:`esp_eth_handle_t` in case of Ethernet). The IO Driver handle is passed to ``ioctl()`` as the third parameter.
|
||||
* ``L2TAP_S_RCV_FILTER`` - sets the filter to frames with the type to be passed to the file descriptor. In the case of Ethernet frames, the frames are to be filtered based on the Length and Ethernet type field. In case the filter value is set less than or equal to 0x05DC, the Ethernet type field is considered to represent IEEE802.3 Length Field, and all frames with values in interval <0, 0x05DC> at that field are passed to the file descriptor. The IEEE802.2 logical link control (LLC) resolution is then expected to be performed by the user's application. In case the filter value is set greater than 0x05DC, the Ethernet type field is considered to represent protocol identification and only frames that are equal to the set value are to be passed to the file descriptor.
|
||||
|
||||
All above-set configuration options have a getter counterpart option to read the current settings.
|
||||
|
||||
@@ -182,20 +182,20 @@ All above-set configuration options have a getter counterpart option to read the
|
||||
The file descriptor needs to be firstly bounded to a specific Network Interface by ``L2TAP_S_INTF_DEVICE`` or ``L2TAP_S_DEVICE_DRV_HNDL`` to make ``L2TAP_S_RCV_FILTER`` option available.
|
||||
|
||||
.. note::
|
||||
VLAN-tagged frames are currently not recognized. If the user needs to process VLAN-tagged frames, they need a set filter to be equal to the VLAN tag (i.e. 0x8100 or 0x88A8) and process the VLAN-tagged frames in the user application.
|
||||
VLAN-tagged frames are currently not recognized. If the user needs to process VLAN-tagged frames, they need a set filter to be equal to the VLAN tag (i.e., 0x8100 or 0x88A8) and process the VLAN-tagged frames in the user application.
|
||||
|
||||
.. note::
|
||||
``L2TAP_S_DEVICE_DRV_HNDL`` is particularly useful when the user's application does not require the usage of an IP stack and so ESP-NETIF is not required to be initialized too. As a result, Network Interface cannot be identified by its ``if_key`` and hence it needs to be identified directly by its IO Driver handle.
|
||||
|
||||
| On success, ``ioctl()`` returns 0. On error, -1 is returned, and ``errno`` is set to indicate the error.
|
||||
| * EBADF - not a valid file descriptor.
|
||||
| * EACCES - options change is denied in this state (e.g. file descriptor has not been bounded to Network interface yet).
|
||||
| * EACCES - options change is denied in this state (e.g., file descriptor has not been bounded to Network interface yet).
|
||||
| * EINVAL - invalid configuration argument. Ethernet type filter is already used by other file descriptors on that same Network interface.
|
||||
| * ENODEV - no such Network Interface which is tried to be assigned to the file descriptor exists.
|
||||
| * ENOSYS - unsupported operation, passed configuration option does not exist.
|
||||
|
||||
fcntl()
|
||||
^^^^^^^
|
||||
``fcntl()``
|
||||
^^^^^^^^^^^
|
||||
``fcntl()`` is used to manipulate with properties of opened ESP-NETIF L2 TAP file descriptor.
|
||||
|
||||
The following commands manipulate the status flags associated with the file descriptor:
|
||||
@@ -207,17 +207,17 @@ The following commands manipulate the status flags associated with the file desc
|
||||
| * EBADF - not a valid file descriptor.
|
||||
| * ENOSYS - unsupported command.
|
||||
|
||||
read()
|
||||
^^^^^^
|
||||
``read()``
|
||||
^^^^^^^^^^
|
||||
Opened and configured ESP-NETIF L2 TAP file descriptor can be accessed by ``read()`` to get inbound frames. The read operation can be either blocking or non-blocking based on the actual state of the ``O_NONBLOCK`` file status flag. When the file status flag is set to blocking, the read operation waits until a frame is received and the context is switched to other tasks. When the file status flag is set to non-blocking, the read operation returns immediately. In such case, either a frame is returned if it was already queued or the function indicates the queue is empty. The number of queued frames associated with one file descriptor is limited by :ref:`CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE` Kconfig option. Once the number of queued frames reached a configured threshold, the newly arrived frames are dropped until the queue has enough room to accept incoming traffic (Tail Drop queue management).
|
||||
|
||||
| On success, ``read()`` returns the number of bytes read. Zero is returned when the size of the destination buffer is 0. On error, -1 is returned, and ``errno`` is set to indicate the error.
|
||||
| * EBADF - not a valid file descriptor.
|
||||
| * EAGAIN - the file descriptor has been marked non-blocking (``O_NONBLOCK``), and the read would block.
|
||||
|
||||
write()
|
||||
^^^^^^^
|
||||
A raw Data Link Layer frame can be sent to Network Interface via opened and configured ESP-NETIF L2 TAP file descriptor. The user’s application is responsible to construct the whole frame except for fields which are added automatically by the physical interface device. The following fields need to be constructed by the user's application in case of an Ethernet link: source/destination MAC addresses, Ethernet type, actual protocol header, and user data. The length of these fields is as follows:
|
||||
``write()``
|
||||
^^^^^^^^^^^
|
||||
A raw Data Link Layer frame can be sent to Network Interface via opened and configured ESP-NETIF L2 TAP file descriptor. The user's application is responsible to construct the whole frame except for fields which are added automatically by the physical interface device. The following fields need to be constructed by the user's application in case of an Ethernet link: source/destination MAC addresses, Ethernet type, actual protocol header, and user data. The length of these fields is as follows:
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
@@ -240,15 +240,15 @@ In other words, there is no additional frame processing performed by the ESP-NET
|
||||
| * EBADMSG - The Ethernet type of the frame is different from the file descriptor configured filter.
|
||||
| * EIO - Network interface not available or busy.
|
||||
|
||||
close()
|
||||
^^^^^^^
|
||||
``close()``
|
||||
^^^^^^^^^^^
|
||||
Opened ESP-NETIF L2 TAP file descriptor can be closed by the ``close()`` to free its allocated resources. The ESP-NETIF L2 TAP implementation of ``close()`` may block. On the other hand, it is thread-safe and can be called from a different task than the file descriptor is actually used. If such a situation occurs and one task is blocked in the I/O operation and another task tries to close the file descriptor, the first task is unblocked. The first's task read operation then ends with an error.
|
||||
|
||||
| On success, ``close()`` returns zero. On error, -1 is returned, and ``errno`` is set to indicate the error.
|
||||
| * EBADF - not a valid file descriptor.
|
||||
|
||||
select()
|
||||
^^^^^^^^
|
||||
``select()``
|
||||
^^^^^^^^^^^^
|
||||
Select is used in a standard way, just :ref:`CONFIG_VFS_SUPPORT_SELECT` needs to be enabled to make the ``select()`` function available.
|
||||
|
||||
|
||||
@@ -262,7 +262,7 @@ You can find a brief introduction to SNTP in general, its initialization code, a
|
||||
This section provides more details about specific use cases of the SNTP service, with statically configured servers, or use the DHCP-provided servers, or both. The workflow is usually very simple:
|
||||
|
||||
1) Initialize and configure the service using :cpp:func:`esp_netif_sntp_init()`.
|
||||
2) Start the service via :cpp:func:`esp_netif_sntp_start()`. This step is not needed if we auto-started the service in the previous step (default). It's useful to start the service explicitly after connecting if we want to use the DHCP-obtained NTP servers. Please note, this option needs to be enabled before connecting, but the SNTP service should be started after.
|
||||
2) Start the service via :cpp:func:`esp_netif_sntp_start()`. This step is not needed if we auto-started the service in the previous step (default). It is useful to start the service explicitly after connecting if we want to use the DHCP-obtained NTP servers. Please note, this option needs to be enabled before connecting, but the SNTP service should be started after.
|
||||
3) Wait for the system time to synchronize using :cpp:func:`esp_netif_sntp_sync_wait()` (only if needed).
|
||||
4) Stop and destroy the service using :cpp:func:`esp_netif_sntp_deinit()`.
|
||||
|
||||
@@ -270,7 +270,7 @@ This section provides more details about specific use cases of the SNTP service,
|
||||
Basic Mode with Statically Defined Server(s)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Initialize the module with the default configuration after connecting to the network. Note that it's possible to provide multiple NTP servers in the configuration struct:
|
||||
Initialize the module with the default configuration after connecting to the network. Note that it is possible to provide multiple NTP servers in the configuration struct:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -295,7 +295,7 @@ First of all, we have to enable the lwIP configuration option :ref:`CONFIG_LWIP_
|
||||
config.server_from_dhcp = true; // accept the NTP offer from the DHCP server
|
||||
esp_netif_sntp_init(&config);
|
||||
|
||||
Then, once we're connected, we could start the service using:
|
||||
Then, once we are connected, we could start the service using:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -303,7 +303,7 @@ Then, once we're connected, we could start the service using:
|
||||
|
||||
.. note::
|
||||
|
||||
It's also possible to start the service during initialization (default ``config.start=true``). This would likely to cause the initial SNTP request to fail (since we are not connected yet) and lead to some back-off time for subsequent requests.
|
||||
It is also possible to start the service during initialization (default ``config.start=true``). This would likely to cause the initial SNTP request to fail (since we are not connected yet) and lead to some back-off time for subsequent requests.
|
||||
|
||||
|
||||
Use Both Static and Dynamic Servers
|
||||
@@ -359,7 +359,7 @@ For more specific cases, please consult this guide: :doc:`/api-reference/network
|
||||
|
||||
* :cpp:func:`esp_netif_create_default_wifi_ap()`
|
||||
|
||||
Please note that these functions return the ``esp_netif`` handle, i.e. a pointer to a network interface object allocated and configured with default settings, as a consequence, which means that:
|
||||
Please note that these functions return the ``esp_netif`` handle, i.e., a pointer to a network interface object allocated and configured with default settings, as a consequence, which means that:
|
||||
|
||||
* The created object has to be destroyed if a network de-initialization is provided by an application using :cpp:func:`esp_netif_destroy_default_wifi()`.
|
||||
|
||||
|
||||
@@ -2,12 +2,11 @@ ESP-NETIF Custom I/O Driver
|
||||
===========================
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
@@ -16,25 +15,21 @@ As shown in the diagram, the following three API functions for the packet data p
|
||||
* :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.
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
@@ -49,9 +44,8 @@ As a consequence the I/O driver has to create an instance of the struct per belo
|
||||
} my_netif_driver_t;
|
||||
|
||||
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
|
||||
|
||||
@@ -70,11 +64,10 @@ as well in the post-attach callback. An example of a simple post-attach callback
|
||||
}
|
||||
|
||||
|
||||
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 behaviour 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
|
||||
@@ -87,15 +80,13 @@ 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 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 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)
|
||||
|
||||
The following API reference outlines these network stack interaction with the esp-netif:
|
||||
|
||||
|
||||
@@ -6,8 +6,9 @@ ESP-NOW
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif. In ESP-NOW, application data is encapsulated in a vendor-specific action frame and then transmitted from one Wi-Fi device to another without connection.
|
||||
CTR with CBC-MAC Protocol(CCMP) is used to protect the action frame for security. ESP-NOW is widely used in smart light, remote controlling, sensor, etc.
|
||||
ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif. In ESP-NOW, application data is encapsulated in a vendor-specific action frame and then transmitted from one Wi-Fi device to another without connection.
|
||||
|
||||
CTR with CBC-MAC Protocol (CCMP) is used to protect the action frame for security. ESP-NOW is widely used in smart light, remote controlling, sensor, etc.
|
||||
|
||||
Frame Format
|
||||
------------
|
||||
@@ -23,7 +24,7 @@ ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The defaul
|
||||
------------------------------------------------------------------------------------------------------------
|
||||
24 bytes 1 byte 3 bytes 4 bytes 7~257 bytes 4 bytes
|
||||
|
||||
- Category Code: The Category Code field is set to the value(127) indicating the vendor-specific category.
|
||||
- Category Code: The Category Code field is set to the value (127) indicating the vendor-specific category.
|
||||
- Organization Identifier: The Organization Identifier contains a unique identifier (0x18fe34), which is the first three bytes of MAC address applied by Espressif.
|
||||
- Random Value: The Random Value filed is used to prevents relay attacks.
|
||||
- Vendor Specific Content: The Vendor Specific Content contains vendor-specific fields as follows:
|
||||
@@ -39,7 +40,7 @@ ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The defaul
|
||||
|
||||
- Element ID: The Element ID field is set to the value (221), indicating the vendor-specific element.
|
||||
- Length: The length is the total length of Organization Identifier, Type, Version and Body.
|
||||
- Organization Identifier: The Organization Identifier contains a unique identifier(0x18fe34), which is the first three bytes of MAC address applied by Espressif.
|
||||
- Organization Identifier: The Organization Identifier contains a unique identifier (0x18fe34), which is the first three bytes of MAC address applied by Espressif.
|
||||
- Type: The Type field is set to the value (4) indicating ESP-NOW.
|
||||
- Version: The Version field is set to the version of ESP-NOW.
|
||||
- Body: The Body contains the ESP-NOW data.
|
||||
@@ -49,22 +50,24 @@ As ESP-NOW is connectionless, the MAC header is a little different from that of
|
||||
Security
|
||||
--------
|
||||
|
||||
ESP-NOW uses the CCMP method, which is described in IEEE Std. 802.11-2012, to protect the vendor-specific action frame. The Wi-Fi device maintains a Primary Master Key (PMK) and several Local Master Keys (LMK). The lengths of both PMK and LMk are 16 bytes.
|
||||
* PMK is used to encrypt LMK with the AES-128 algorithm. Call :cpp:func:`esp_now_set_pmk()` to set PMK. If PMK is not set, a default PMK will be used.
|
||||
ESP-NOW uses the CCMP method, which is described in IEEE Std. 802.11-2012, to protect the vendor-specific action frame. The Wi-Fi device maintains a Primary Master Key (PMK) and several Local Master Keys (LMK). The lengths of both PMK and LMk are 16 bytes.
|
||||
|
||||
* PMK is used to encrypt LMK with the AES-128 algorithm. Call :cpp:func:`esp_now_set_pmk()` to set PMK. If PMK is not set, a default PMK will be used.
|
||||
* LMK of the paired device is used to encrypt the vendor-specific action frame with the CCMP method. The maximum number of different LMKs is six. If the LMK of the paired device is not set, the vendor-specific action frame will not be encrypted.
|
||||
|
||||
|
||||
Encrypting multicast vendor-specific action frame is not supported.
|
||||
|
||||
Initialization and De-initialization
|
||||
Initialization and Deinitialization
|
||||
------------------------------------
|
||||
|
||||
Call :cpp:func:`esp_now_init()` to initialize ESP-NOW and :cpp:func:`esp_now_deinit()` to de-initialize ESP-NOW. ESP-NOW data must be transmitted after Wi-Fi is started, so it is recommended to start Wi-Fi before initializing ESP-NOW and stop Wi-Fi after de-initializing ESP-NOW.
|
||||
When :cpp:func:`esp_now_deinit()` is called, all of the information of paired devices will be deleted.
|
||||
|
||||
When :cpp:func:`esp_now_deinit()` is called, all of the information of paired devices are deleted.
|
||||
|
||||
Add Paired Device
|
||||
-----------------
|
||||
|
||||
Call :cpp:func:`esp_now_add_peer()` to add the device to the paired device list before you send data to this device. If security is enabled, the LMK must be set. You can send ESP-NOW data via both the Station and the SoftAP interface. Make sure that the interface is enabled before sending ESP-NOW data.
|
||||
Call :cpp:func:`esp_now_add_peer()` to add the device to the paired device list before you send data to this device. If security is enabled, the LMK must be set. You can send ESP-NOW data via both the Station and the SoftAP interface. Make sure that the interface is enabled before sending ESP-NOW data.
|
||||
|
||||
.. only:: esp32c2
|
||||
|
||||
@@ -79,7 +82,7 @@ A device with a broadcast MAC address must be added before sending broadcast dat
|
||||
Send ESP-NOW Data
|
||||
-----------------
|
||||
|
||||
Call :cpp:func:`esp_now_send()` to send ESP-NOW data and :cpp:func:`esp_now_register_send_cb()` to register sending callback function. It will return `ESP_NOW_SEND_SUCCESS` in sending callback function if the data is received successfully on the MAC layer. Otherwise, it will return `ESP_NOW_SEND_FAIL`. Several reasons can lead to ESP-NOW fails to send data. For example, the destination device doesn't exist; the channels of the devices are not the same; the action frame is lost when transmitting on the air, etc. It is not guaranteed that application layer can receive the data. If necessary, send back ack data when receiving ESP-NOW data. If receiving ack data timeouts, retransmit the ESP-NOW data. A sequence number can also be assigned to ESP-NOW data to drop the duplicate data.
|
||||
Call :cpp:func:`esp_now_send()` to send ESP-NOW data and :cpp:func:`esp_now_register_send_cb()` to register sending callback function. It will return `ESP_NOW_SEND_SUCCESS` in sending callback function if the data is received successfully on the MAC layer. Otherwise, it will return `ESP_NOW_SEND_FAIL`. Several reasons can lead to ESP-NOW fails to send data. For example, the destination device does not exist; the channels of the devices are not the same; the action frame is lost when transmitting on the air, etc. It is not guaranteed that application layer can receive the data. If necessary, send back ack data when receiving ESP-NOW data. If receiving ack data timeouts, retransmit the ESP-NOW data. A sequence number can also be assigned to ESP-NOW data to drop the duplicate data.
|
||||
|
||||
If there is a lot of ESP-NOW data to send, call :cpp:func:`esp_now_send()` to send less than or equal to 250 bytes of data once a time. Note that too short interval between sending two ESP-NOW data may lead to disorder of sending callback function. So, it is recommended that sending the next ESP-NOW data after the sending callback function of the previous sending has returned. The sending callback function runs from a high-priority Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post the necessary data to a queue and handle it from a lower priority task.
|
||||
|
||||
@@ -94,7 +97,7 @@ Config ESP-NOW Rate
|
||||
|
||||
.. only:: esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3
|
||||
|
||||
Call :cpp:func:`esp_wifi_config_espnow_rate()` to config ESPNOW rate of specified interface. Make sure that the interface is enabled before config rate. This API should be called after :cpp:func:`esp_wifi_start()`.
|
||||
Call :cpp:func:`esp_wifi_config_espnow_rate()` to config ESP-NOW rate of specified interface. Make sure that the interface is enabled before config rate. This API should be called after :cpp:func:`esp_wifi_start()`.
|
||||
|
||||
.. only:: esp32c6
|
||||
|
||||
@@ -111,7 +114,7 @@ Sleep is supported only when {IDF_TARGET_NAME} is configured as station.
|
||||
|
||||
Call :cpp:func:`esp_now_set_wake_window()` to configure Window for ESP-NOW RX at sleep. The default value is the maximum, which allowing RX all the time.
|
||||
|
||||
If Power-saving is needed for ESP-NOW, call :cpp:func:`esp_wifi_connectionless_module_set_wake_interval()` to configure Interval as well.
|
||||
If Power-saving is needed for ESP-NOW, call :cpp:func:`esp_wifi_connectionless_module_set_wake_interval()` to configure Interval as well.
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Thread
|
||||
Introduction
|
||||
------------
|
||||
|
||||
`Thread <https://www.threadgroup.org>`_ is a IP-based mesh networking protocol. It's based on the 802.15.4 physical and MAC layer.
|
||||
`Thread <https://www.threadgroup.org>`_ is a IP-based mesh networking protocol. It is based on the 802.15.4 physical and MAC layer.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
@@ -19,10 +19,10 @@ The :example:`openthread` directory of ESP-IDF examples contains the following a
|
||||
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 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.
|
||||
|
||||
.. include-build-file:: inc/esp_openthread.inc
|
||||
.. include-build-file:: inc/esp_openthread_types.inc
|
||||
|
||||
@@ -43,6 +43,7 @@ Thread
|
||||
esp_openthread
|
||||
|
||||
Thread is an IPv6-based mesh networking technology for IoT.
|
||||
|
||||
Code examples for the Thread API are provided in the :example:`openthread` directory of ESP-IDF examples.
|
||||
|
||||
ESP-NETIF
|
||||
@@ -63,7 +64,7 @@ IP Network Layer
|
||||
|
||||
Code examples for TCP/IP socket APIs are provided in the :example:`protocols/sockets` directory of ESP-IDF examples.
|
||||
|
||||
Application Layer
|
||||
Application Layer
|
||||
=================
|
||||
|
||||
Documentation for Application layer network protocols (above the IP Network layer) are provided in :doc:`../protocols/index`.
|
||||
|
||||
@@ -63,7 +63,7 @@ API Reference
|
||||
|
||||
2. Update is done on each documentation build by invoking Sphinx extension :`esp_extensions/run_doxygen.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/doxygen/Doxyfile`.
|
||||
|
||||
3. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that will be used to generate corresponding ``*.inc`` files::
|
||||
3. Each line of the ``INPUT`` statement (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that is used to generate corresponding ``*.inc`` files::
|
||||
|
||||
##
|
||||
## Wi-Fi - API Reference
|
||||
@@ -73,7 +73,7 @@ API Reference
|
||||
|
||||
4. When the headers are expanded, any macros defined by default in ``sdkconfig.h`` as well as any macros defined in SOC-specific ``include/soc/*_caps.h`` headers will be expanded. This allows the headers to include/exclude material based on the ``IDF_TARGET`` value.
|
||||
|
||||
5. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g. ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
|
||||
5. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g., ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
|
||||
|
||||
6. To show contents of ``*.inc`` file in documentation, include it as follows::
|
||||
|
||||
|
||||
Reference in New Issue
Block a user