doc: Rearrange wifi & ethernet docs into a common "network" doc
This commit is contained in:
Angus Gratton
committed by
Angus Gratton
Angus Gratton
parent
5436be94b6
commit
6a4955ef74
@@ -0,0 +1,47 @@
|
||||
Ethernet
|
||||
========
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Ethernet example: :example:`ethernet/ethernet`.
|
||||
|
||||
PHY Interfaces
|
||||
--------------
|
||||
|
||||
The configured PHY model(s) are set in software by configuring the eth_config_t structure for the given PHY.
|
||||
|
||||
Headers include a default configuration structure. These default configurations will need some members overriden or re-set before they can be used for a particular PHY hardware configuration. Consult the Ethernet example to see how this is done.
|
||||
|
||||
* :component_file:`ethernet/include/eth_phy/phy.h` (common)
|
||||
* :component_file:`ethernet/include/eth_phy/phy_tlk110.h`
|
||||
* :component_file:`ethernet/include/eth_phy/phy_lan8720.h`
|
||||
|
||||
PHY Configuration Constants
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. doxygenvariable:: phy_tlk110_default_ethernet_config
|
||||
.. doxygenvariable:: phy_lan8720_default_ethernet_config
|
||||
|
||||
|
||||
API Reference - Ethernet
|
||||
------------------------
|
||||
|
||||
.. include:: /_build/inc/esp_eth.inc
|
||||
|
||||
API Reference - PHY Common
|
||||
--------------------------
|
||||
|
||||
.. include:: /_build/inc/phy.inc
|
||||
|
||||
API Reference - PHY TLK110
|
||||
--------------------------
|
||||
|
||||
.. include:: /_build/inc/phy_tlk110.inc
|
||||
|
||||
API Reference - PHY LAN8720
|
||||
---------------------------
|
||||
|
||||
.. include:: /_build/inc/phy_lan8720.inc
|
||||
|
||||
|
||||
@@ -0,0 +1,335 @@
|
||||
ESP-MESH Programming Guide
|
||||
==========================
|
||||
|
||||
This is a programming guide for ESP-MESH, including the API reference and coding examples. This guide is split into the following parts:
|
||||
|
||||
1. :ref:`mesh-programming-model`
|
||||
|
||||
2. :ref:`mesh-writing-mesh-application`
|
||||
|
||||
3. :ref:`mesh-self-organized-behavior`
|
||||
|
||||
4. :ref:`mesh-application-examples`
|
||||
|
||||
5. :ref:`mesh-api-reference`
|
||||
|
||||
For documentation regarding the ESP-MESH protocol, please see the :doc:`ESP-MESH API Guide<../../api-guides/mesh>`.
|
||||
|
||||
|
||||
.. ---------------------- ESP-MESH Programming Model --------------------------
|
||||
|
||||
.. _mesh-programming-model:
|
||||
|
||||
ESP-MESH Programming Model
|
||||
--------------------------
|
||||
|
||||
Software Stack
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The ESP-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-MESH software stack.
|
||||
|
||||
.. _mesh-going-to-software-stack:
|
||||
|
||||
.. figure:: ../../../_static/mesh-software-stack.png
|
||||
:align: center
|
||||
:alt: ESP-MESH Software Stack
|
||||
:figclass: align-center
|
||||
|
||||
ESP-MESH Software Stack
|
||||
|
||||
System Events
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
An application interfaces with ESP-MESH via **ESP-MESH Events**. Since ESP-MESH is built atop the Wi-Fi stack, it is also possible for the application to interface with the Wi-Fi driver via the **Wi-Fi Event Task**. The following diagram illustrates the interfaces for the various System Events in an ESP-MESH application.
|
||||
|
||||
.. figure:: ../../../_static/mesh-events-delivery.png
|
||||
:align: center
|
||||
:alt: ESP-MESH System Events Delivery
|
||||
:figclass: align-center
|
||||
|
||||
ESP-MESH System Events Delivery
|
||||
|
||||
The :cpp:type:`mesh_event_id_t` defines all possible ESP-MESH system events and can indicate events such as the connection/disconnection of parent/child. Before ESP-MESH system events can be used, the application must register a **Mesh Event Callback** via :cpp:func:`esp_mesh_set_config`. The callback is used to receive events from the ESP-MESH stack as well as the LwIP Stack and should contain handlers for each event relevant to the application.
|
||||
|
||||
Typical use cases of system 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:`MESH_EVENT_ROOT_GOT_IP` and :cpp:enumerator:`MESH_EVENT_ROOT_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-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-MESH's self-organizing behavior**. Therefore, user's 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-MESH
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
The application can access the ESP-MESH stack directly without having to go through the LwIP stack. The LwIP stack is only required by the root node to transmit/receive data to/from an external IP network. However, since every node can potentially become the root node (due to automatic root node selection), each node must still initialize the LwIP stack.
|
||||
|
||||
**Each node is required to initialize LwIP by calling** :cpp:func:`tcpip_adapter_init`. In order to prevent non-root node access to LwIP, the application should stop the following services after LwIP initialization:
|
||||
|
||||
- DHCP server service on the softAP interface.
|
||||
- DHCP client service on the station interface.
|
||||
|
||||
The following code snippet demonstrates how to initialize LwIP for ESP-MESH applications.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* tcpip initialization */
|
||||
tcpip_adapter_init();
|
||||
/*
|
||||
* for mesh
|
||||
* stop DHCP server on softAP interface by default
|
||||
* stop DHCP client on station interface by default
|
||||
*/
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
|
||||
/* do not specify system event callback, use NULL instead. */
|
||||
ESP_ERROR_CHECK(esp_event_loop_init(NULL, NULL));
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-MESH requires a root node to be connected with a router. Therefore, in the event that a node becomes the root, **the corresponding handler must start the DHCP client service and immediately obtain an IP address**. Doing so will allow other nodes to begin transmitting/receiving packets to/from the external IP network. However, this step is unnecessary if static IP settings are used.
|
||||
|
||||
|
||||
.. ---------------------- Writing a Mesh Application --------------------------
|
||||
|
||||
.. _mesh-writing-mesh-application:
|
||||
|
||||
Writing an ESP-MESH Application
|
||||
-------------------------------
|
||||
|
||||
The prerequisites for starting ESP-MESH is to initialize LwIP and Wi-Fi, The following code snippet demonstrates the necessary prerequisite steps before ESP-MESH itself can be initialized.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
tcpip_adapter_init();
|
||||
/*
|
||||
* for mesh
|
||||
* stop DHCP server on softAP interface by default
|
||||
* stop DHCP client on station interface by default
|
||||
*/
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
|
||||
/* do not specify system event callback, use NULL instead. */
|
||||
ESP_ERROR_CHECK(esp_event_loop_init(NULL, NULL));
|
||||
|
||||
/* Wi-Fi initialization */
|
||||
wifi_init_config_t config = WIFI_INIT_CONFIG_DEFAULT();
|
||||
ESP_ERROR_CHECK(esp_wifi_init(&config));
|
||||
ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_FLASH));
|
||||
ESP_ERROR_CHECK(esp_wifi_start());
|
||||
|
||||
After initializing LwIP and Wi-Fi, the process of getting an ESP-MESH network up and running can be summarized into the following three steps:
|
||||
|
||||
1. :ref:`mesh-initialize-mesh`
|
||||
2. :ref:`mesh-configuring-mesh`
|
||||
3. :ref:`mesh-start-mesh`
|
||||
|
||||
.. _mesh-initialize-mesh:
|
||||
|
||||
Initialize Mesh
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
The following code snippet demonstrates how to initialize ESP-MESH
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* mesh initialization */
|
||||
ESP_ERROR_CHECK(esp_mesh_init());
|
||||
|
||||
.. _mesh-configuring-mesh:
|
||||
|
||||
Configuring an ESP-MESH Network
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. todo - Add note about unified configuration
|
||||
|
||||
ESP-MESH is configured via :cpp:func:`esp_mesh_set_config` which receives its arguments using the :cpp:type:`mesh_cfg_t` structure. The structure contains the following parameters used to configure ESP-MESH:
|
||||
|
||||
+------------------+-------------------------------------+
|
||||
| Parameter | Description |
|
||||
+==================+=====================================+
|
||||
| Channel | Range from 1 to 14 |
|
||||
+------------------+-------------------------------------+
|
||||
| Event Callback | Callback for Mesh Events, |
|
||||
| | see :cpp:type:`mesh_event_cb_t` |
|
||||
+------------------+-------------------------------------+
|
||||
| Mesh ID | ID of ESP-MESH Network, |
|
||||
| | see :cpp:type:`mesh_addr_t` |
|
||||
+------------------+-------------------------------------+
|
||||
| Router | Router Configuration, |
|
||||
| | see :cpp:type:`mesh_router_t` |
|
||||
+------------------+-------------------------------------+
|
||||
| Mesh AP | Mesh AP Configuration, |
|
||||
| | see :cpp:type:`mesh_ap_cfg_t` |
|
||||
+------------------+-------------------------------------+
|
||||
| Crypto Functions | Crypto Functions for Mesh IE, |
|
||||
| | see :cpp:type:`mesh_crypto_funcs_t` |
|
||||
+------------------+-------------------------------------+
|
||||
|
||||
The following code snippet demonstrates how to configure ESP-MESH.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Enable the Mesh IE encryption by default */
|
||||
mesh_cfg_t cfg = MESH_INIT_CONFIG_DEFAULT();
|
||||
/* mesh ID */
|
||||
memcpy((uint8_t *) &cfg.mesh_id, MESH_ID, 6);
|
||||
/* mesh event callback */
|
||||
cfg.event_cb = &mesh_event_handler;
|
||||
/* channel (must match the router's channel) */
|
||||
cfg.channel = CONFIG_MESH_CHANNEL;
|
||||
/* router */
|
||||
cfg.router.ssid_len = strlen(CONFIG_MESH_ROUTER_SSID);
|
||||
memcpy((uint8_t *) &cfg.router.ssid, CONFIG_MESH_ROUTER_SSID, cfg.router.ssid_len);
|
||||
memcpy((uint8_t *) &cfg.router.password, CONFIG_MESH_ROUTER_PASSWD,
|
||||
strlen(CONFIG_MESH_ROUTER_PASSWD));
|
||||
/* mesh softAP */
|
||||
cfg.mesh_ap.max_connection = CONFIG_MESH_AP_CONNECTIONS;
|
||||
memcpy((uint8_t *) &cfg.mesh_ap.password, CONFIG_MESH_AP_PASSWD,
|
||||
strlen(CONFIG_MESH_AP_PASSWD));
|
||||
ESP_ERROR_CHECK(esp_mesh_set_config(&cfg));
|
||||
|
||||
.. _mesh-start-mesh:
|
||||
|
||||
Start Mesh
|
||||
^^^^^^^^^^
|
||||
|
||||
The following code snippet demonstrates how to start ESP-MESH.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* mesh start */
|
||||
ESP_ERROR_CHECK(esp_mesh_start());
|
||||
|
||||
After starting ESP-MESH, the application should check for ESP-MESH events to determine when it has connected to the network. After connecting, the application can start transmitting and receiving packets over the ESP-MESH network using :cpp:func:`esp_mesh_send` and :cpp:func:`esp_mesh_recv`.
|
||||
|
||||
|
||||
.. --------------------- ESP-MESH Application Examples ------------------------
|
||||
|
||||
.. _mesh-self-organized-behavior:
|
||||
|
||||
Self Organized Networking
|
||||
-------------------------
|
||||
|
||||
Self organized networking is a feature of ESP-MESH where nodes can autonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-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-MESH network are able to carryout 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-MESH stack will internally make calls to Wi-Fi driver APIs. Therefore, **the application layer should not make any calls to Wi-Fi driver APIs whilst self organized networking is enabled as doing so would risk interfering with ESP-MESH**.
|
||||
|
||||
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:
|
||||
|
||||
- ``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.
|
||||
|
||||
Disabling Self Organized Networking
|
||||
"""""""""""""""""""""""""""""""""""
|
||||
The following code snippet demonstrates how to disable self organized networking.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Disable self organized networking
|
||||
esp_mesh_set_self_organized(false, false);
|
||||
|
||||
ESP-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
|
||||
""""""""""""""""""""""""""""""""""
|
||||
|
||||
ESP-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 |
|
||||
+===============+==============+==================================================================================================================+
|
||||
| N | N | - Nodes already connected to a parent node will remain connected. |
|
||||
| | | - Nodes previously scanning for a parent nodes will stop scanning. Call :cpp:func:`esp_mesh_connect` to restart. |
|
||||
| +--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| | Y | - A root node already connected to router will stay connected. |
|
||||
| | | - A root node disconnected from router will need to call :cpp:func:`esp_mesh_connect` to reconnect. |
|
||||
+---------------+--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| Y | N | - Nodes without a parent node will automatically select a preferred parent and connect. |
|
||||
| | | - Nodes already connected to a parent node will disconnect, reselect a preferred parent node, and connect. |
|
||||
| +--------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| | Y | - For a root node to connect to a parent node, it must give up it's role as root. Therefore, a root node will |
|
||||
| | | 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.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Enable self organized networking and select a new parent
|
||||
esp_mesh_set_self_organized(true, true);
|
||||
|
||||
...
|
||||
|
||||
//Enable self organized networking and manually reconnect
|
||||
esp_mesh_set_self_organized(true, false);
|
||||
esp_mesh_connect();
|
||||
|
||||
|
||||
Calling Wi-Fi Driver API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
There can be instances in which an application may want to directly call Wi-Fi driver API whilst using ESP-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 driver APIs**. This will prevent the ESP-MESH stack from attempting to call any Wi-Fi driver APIs and potentially interfering with the application's calls.
|
||||
|
||||
Therefore, application calls to Wi-Fi driver 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-MESH.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
//Disable self organized networking
|
||||
esp_mesh_set_self_organized(0, 0);
|
||||
|
||||
//Stop any scans already in progress
|
||||
esp_wifi_scan_stop();
|
||||
//Manually start scan. Will automatically stop when run to completion
|
||||
esp_wifi_scan_start();
|
||||
|
||||
//Process scan results
|
||||
|
||||
...
|
||||
|
||||
//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
|
||||
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
|
||||
esp_mesh_connect(); //Manually reconnect to router
|
||||
|
||||
|
||||
.. --------------------- ESP-MESH Application Examples ------------------------
|
||||
|
||||
.. _mesh-application-examples:
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
ESP-IDF contains these ESP-MESH example projects:
|
||||
|
||||
:example:`The Internal Communication Example<mesh/internal_communication>` demonstrates how to setup a ESP-MESH network and have the root node send a data packet to every node within the network.
|
||||
|
||||
:example:`The Manual Networking Example<mesh/manual_networking>` demonstrates how to use ESP-MESH without the self-organizing features. This example shows how to program a node to manually scan for a list of potential parent nodes and select a parent node based on custom criteria.
|
||||
|
||||
|
||||
.. ------------------------- ESP-MESH API Reference ---------------------------
|
||||
|
||||
.. _mesh-api-reference:
|
||||
|
||||
API Reference
|
||||
--------------
|
||||
|
||||
.. include:: /_build/inc/esp_mesh.inc
|
||||
@@ -0,0 +1,103 @@
|
||||
ESP-NOW
|
||||
=======
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP-NOW is a kind of connectionless WiFi communication protocol which is defined by Espressif. In ESP-NOW, application data is
|
||||
encapsulated in vendor-specific action frame and then transmitted from one WiFi 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
|
||||
------------
|
||||
|
||||
ESP-NOW uses vendor-specific action frame to transmit ESP-NOW data. The format of vendor-specific action frame is as follows:
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
----------------------------------------------------------------------------------------
|
||||
| MAC Header | Category Code | Organization Identifier | Vendor Specific Content | FCS |
|
||||
----------------------------------------------------------------------------------------
|
||||
1 byte 3 bytes 7~255 bytes
|
||||
|
||||
- Category Code: The Category 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.
|
||||
- Vendor Specific Content: The Vendor Specific Content contains vendor-specific field as follows:
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
| Element ID | Length | Organization Identifier | Type | Version | Body |
|
||||
-------------------------------------------------------------------------------
|
||||
1 byte 1 byte 3 bytes 1 byte 1 byte 0~250 bytes
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
As ESP-NOW is connectionless, the MAC header is a little different from that of standard frames. The FromDS and ToDS bits of
|
||||
FrameControl field are both 0. The first address field is set to the destination address. The second address field is set to
|
||||
the source address. The third address field is set to broadcast address(0xff:0xff:0xff:0xff:0xff:0xff).
|
||||
|
||||
Security
|
||||
--------
|
||||
|
||||
ESP-NOW use CCMP method which can be referenced in IEEE Std. 802.11-2012 to protect the vendor-specific action frame. The WiFi
|
||||
device maintains a Primary Master Key(PMK) and several Local Master Keys(LMK). The lengths of them are 16 bytes. PMK is used
|
||||
to encrypt LMK with AES-128 algorithm. Call ``esp_now_set_pmk()`` to set PMK. If PMK is not set, a default PMK will be used.
|
||||
If LMK of the paired device is set, it will be used to encrypt the vendor-specific action frame with CCMP method. The maximum
|
||||
number of different LMKs is six. Do not support encrypting multicast vendor-specific action frame.
|
||||
|
||||
Initialization and De-initialization
|
||||
------------------------------------
|
||||
|
||||
Call ``esp_now_init()`` to initialize ESP-NOW and ``esp_now_deinit()`` to de-initialize ESP-NOW. ESP-NOW data must be transmitted
|
||||
after WiFi is started, so it is recommended to start WiFi before initializing ESP-NOW and stop WiFi after de-initializing ESP-NOW.
|
||||
When ``esp_now_deinit()`` is called, all of the information of paired devices will be deleted.
|
||||
|
||||
Add Paired Device
|
||||
-----------------
|
||||
|
||||
Before sending data to other device, call ``esp_now_add_peer()`` to add it to the paired device list first. The maximum number of
|
||||
paired devices is twenty. If security is enabled, the LMK must be set. ESP-NOW data can be sent from station or softap interface.
|
||||
Make sure that the interface is enabled before sending ESP-NOW data. A device with broadcast MAC address must be added before
|
||||
sending broadcast data. The range of the channel of paired device is from 0 to 14. If the channel is set to 0, data will be sent
|
||||
on the current channel. Otherwise, the channel must be set as the channel that the local device is on.
|
||||
|
||||
Send ESP-NOW Data
|
||||
-----------------
|
||||
|
||||
Call ``esp_now_send()`` to send ESP-NOW data and ``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 MAC layer. Otherwise, it will return
|
||||
`ESP_NOW_SEND_FAIL`. There are several reasons failing to send ESP-NOW data, for example, the destination device doesn't exist, the
|
||||
channels of the devices are not the same, the action frame is lost when transmiting 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 timeout
|
||||
happens, retransmit the ESP-NOW data. A sequence number can also be assigned to ESP-NOW data to drop the duplicated data.
|
||||
|
||||
If there is a lot of ESP-NOW data to send, call ``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 datas 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 previous sending has returned. The sending
|
||||
callback function runs from a high-priority WiFi task. So, do not do lengthy operations in the callback function. Instead, post
|
||||
necessary data to a queue and handle it from a lower priority task.
|
||||
|
||||
Receiving ESP-NOW Data
|
||||
----------------------
|
||||
|
||||
Call ``esp_now_register_recv_cb`` to register receiving callback function. When receiving ESP-NOW data, receiving callback function
|
||||
is called. The receiving callback function also runs from WiFi task. So, do not do lengthy operations in the callback function.
|
||||
Instead, post necessary data to a queue and handle it from a lower priority task.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_now.inc
|
||||
@@ -0,0 +1,7 @@
|
||||
Smart Config
|
||||
============
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_smartconfig.inc
|
||||
@@ -0,0 +1,33 @@
|
||||
Wi-Fi
|
||||
=====
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi networking functionality. This includes configuration for:
|
||||
|
||||
- Station mode (aka STA mode or WiFi client mode). ESP32 connects to an access point.
|
||||
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32.
|
||||
- Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access point).
|
||||
|
||||
- Various security modes for the above (WPA, WPA2, WEP, etc.)
|
||||
- Scanning for access points (active & passive scanning).
|
||||
- Promiscuous mode monitoring of IEEE802.11 WiFi packets.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
See :example:`wifi` directory of ESP-IDF examples that contains the following applications:
|
||||
|
||||
* Simple application showing how to connect ESP32 module to an Access Point - `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
|
||||
|
||||
* Using power save mode of Wi-Fi - :example:`wifi/power_save`.
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/esp_wifi.inc
|
||||
.. include:: /_build/inc/esp_wifi_types.inc
|
||||
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
Networking APIs
|
||||
***************
|
||||
|
||||
Wi-Fi
|
||||
=====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Wi-Fi <esp_wifi>
|
||||
Smart Config <esp_smartconfig>
|
||||
ESP-NOW <esp_now>
|
||||
ESP Mesh <esp_mesh>
|
||||
|
||||
Example code for the Wi-Fi API is provided in :example:`wifi` directory of ESP-IDF examples.
|
||||
|
||||
Example code for ESP Mesh is provided in :example:`mesh` directory of ESP-IDF examples.
|
||||
|
||||
Ethernet
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Ethernet <esp_eth>
|
||||
|
||||
Example code for the Ethernet API is provided in :example:`ethernet` directory of ESP-IDF examples.
|
||||
|
||||
IP Network Layer
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
TCP/IP Adapter <tcpip_adapter.rst>
|
||||
|
||||
Example code for TCP/IP socket APIs is provided in :example:`protocols/sockets` directory of ESP-IDF examples.
|
||||
|
||||
Application Layer
|
||||
=================
|
||||
|
||||
Documentation for application layer network protocols (above the IP network layer) is provided in :doc:`../protocols/index`.
|
||||
@@ -0,0 +1,8 @@
|
||||
lwIP TCP/IP API
|
||||
***************
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Example code for TCP/IP socket APIs is provided in :example:`protocols/sockets` directory of ESP-IDF examples.
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
TCP/IP Adapter
|
||||
==============
|
||||
|
||||
The purpose of TCP/IP Adapter library is twofold. First, it provides an abstraction layer for the application on top of the IP stack, to allow applications to choose between IP stacks in the future. Second, the APIs it provides are thread safe, even if the underlying IP stack APIs are not.
|
||||
|
||||
In many cases, application does not need to call TCP/IP Adapter APIs itself. A few cases when such calls are needed are related to :doc:`event handling <../../api-guides/event-handling>`.
|
||||
|
||||
|
||||
The aim of this adapter is to provide an abstraction layer between the TCP/IP stack and the network interface layer (currently Wi-Fi or Ethernet), and general network interface management.
|
||||
|
||||
ESP-IDF currently implements TCP/IP Adapter for the :doc:`lwIP <lwip>` TCP/IP stack only. However, the adapter itself is TCP/IP implementation agnostic and different implementations are possible.
|
||||
|
||||
Some TCP/IP Adapter API functions are intended to be called by application code, for example to get/set interface IP addresses, configure DHCP. Other functions are intended for internal ESP-IDF use by the network driver layer.
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include:: /_build/inc/tcpip_adapter.inc
|
||||
.. include:: /_build/inc/tcpip_adapter_lwip.inc
|
||||
Reference in New Issue
Block a user