feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

docs(esp_netif): Update ESP-NETIF developers and programmers manual

Browse Source 
Made final fixed to both programming manuals and user guidelines
This commit is contained in:
David Cermak
2024-07-09 16:20:37 +02:00
parent ea76db704d
commit 9b550d77d4
5 changed files with 102 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
components/esp_netif/include/esp_netif.h
View File

@@ -595,12 +595,16 @@ esp_err_t esp_netif_napt_disable(esp_netif_t *esp_netif);
* @brief Set or Get DHCP server option
*
* @note Please note that not all combinations of identifiers and options are supported.
*
* Get operations:
*
* * IP_ADDRESS_LEASE_TIME
* * ESP_NETIF_SUBNET_MASK/REQUESTED_IP_ADDRESS (both options do the same, they reflect dhcps_lease_t)
* * ROUTER_SOLICITATION_ADDRESS
* * DOMAIN_NAME_SERVER
*
* Set operations:
*
* * IP_ADDRESS_LEASE_TIME
* * ESP_NETIF_SUBNET_MASK -- set operation is allowed only if the configured mask corresponds to the settings,
* if not, please use esp_netif_set_ip_info() to prevent misconfiguration of DHCPS.
@@ -631,10 +635,14 @@ esp_netif_dhcps_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_
* @brief Set or Get DHCP client option
*
* @note Please note that not all combinations of identifiers and options are supported.
*
* Get operations:
*
* * ESP_NETIF_IP_REQUEST_RETRY_TIME
* * ESP_NETIF_VENDOR_SPECIFIC_INFO -- only available if ESP_DHCP_DISABLE_VENDOR_CLASS_IDENTIFIER=n
*
* Set operations:
*
* * ESP_NETIF_IP_REQUEST_RETRY_TIME
* * ESP_NETIF_VENDOR_SPECIFIC_INFO -- only available if ESP_DHCP_DISABLE_VENDOR_CLASS_IDENTIFIER=n
* lwip layer creates its own copy of the supplied identifier.

77
docs/en/api-reference/network/esp_netif.rst
View File

@@ -10,11 +10,7 @@ The purpose of the ESP-NETIF library is twofold:
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.
It is also possible to use a custom TCP/IP stack with ESP-IDF, provided it implements BSD API. For more information on building ESP-IDF without lwIP, please refer to :idf_file:`components/esp_netif_stack/README.md`.
Some ESP-NETIF API functions are intended to be called by application code, for example, to get or set interface IP addresses, and configure DHCP. Other functions are intended for internal ESP-IDF use by the network driver layer.
In many cases, applications do not need to call ESP-NETIF APIs directly as they are called by the default network event handlers.
Some ESP-NETIF API functions are intended to be called by application code, for example, to get or set interface IP addresses, and configure DHCP. Other functions are intended for internal ESP-IDF use by the network driver layer. In many cases, applications do not need to call ESP-NETIF APIs directly as they are called by the default network event handlers.
If you are only interested in using the most common network interfaces with default setting, please read :ref:`esp_netif_user` to see how you can initialize default interfaces and register event handlers.
@@ -29,7 +25,7 @@ If you would like to develop your own network driver, implement support for a ne
ESP-NETIF User's Manual
=======================
It is usually just enough to create a default network interface after startup and destroy it upon closing (see :ref:`esp_netif_init`). It is also necessary to receive a notification upon assigning a new IP address or losing it (see :ref:`esp-netif-ip-events`).
It is usually just enough to create a default network interface after startup and destroy it upon closing (see :ref:`esp_netif_init`). It is also useful to receive a notification upon assigning a new IP address or losing it (see :ref:`esp-netif-ip-events`).
.. _esp_netif_init:
@@ -37,7 +33,7 @@ It is usually just enough to create a default network interface after startup an
Initialization
--------------
Since the ESP-NETIF component uses system events, the typical network startup code looks like this (note, that error handling is omitted for clarity):
Since the ESP-NETIF component uses system events, the typical network startup code looks like this (note, that error handling is omitted for clarity, see :example_file:`ethernet/basic/main/ethernet_example_main.c` for complete startup code):
.. code-block:: c
@@ -48,7 +44,7 @@ Since the ESP-NETIF component uses system events, the typical network startup co
// 2) Create the network interface handle
esp_netif = esp_netif_new(&config);
// 3) Create the communication driver (e.g. Ethernet) and it's network layer glue
// 3) Create the network interface driver (e.g. Ethernet) and it's network layer glue
// and register the ESP-NETIF event (e.g. to bring the interface up upon link-up event)
esp_netif_glue_t glue = driver_glue(driver);
@@ -57,15 +53,15 @@ Since the ESP-NETIF component uses system events, the typical network startup co
// 5) Register user-side event handlers
esp_event_handler_register(DRIVER_EVENT, ...); // to observe driver states, e.g. link-up
esp_event_handler_register(IP_EVENT, ...); // to observer ESP-NETIF states, e.g. get an IP
esp_event_handler_register(IP_EVENT, ...); // to observe ESP-NETIF states, e.g. get an IP
.. note::
These 5 steps need to be performed in the exact order as shown above, mainly due to the default event loop, which is used by network interface drivers to register system events.
These steps must be performed in the exact order shown above, primarily due to the default event loop used by network interface drivers to register system events.
- Default event loop needs to be created **before** initializing an interface driver (as it typically needs register system even handlers)
- Registering application event handlers need to happen **after** calling :cpp:func:`esp_netif_attach`, because the event handlers are called in the order they were registered and we need to have the system handlers called first.
- The default event loop needs to be created **before** initializing an interface driver, as the driver typically needs to register system event handlers.
- Registering application event handlers must occur **after** calling :cpp:func:`esp_netif_attach`, because event handlers are called in the order they were registered. To ensure that system handlers are called first, you should register application handlers afterward.
Steps ``2)``, ``3)`` and ``4)`` are quite complex for most common use-cases, so ESP-NETIF provides some pre-configured interfaces and convenience functions that create the most common network interfaces in their most common configurations.
@@ -74,16 +70,16 @@ Since the ESP-NETIF component uses system events, the typical network startup co
Each network interface needs to be initialized separately, so if you would like to use multiple interfaces, you would have to run steps ``2)`` to ``5)`` for every interface. Set ``1)`` should be performed only once.
Creating and configuring the interface and attaching the communication driver to it (steps ``2)``, ``3)`` and ``4)``) is described in :ref:`create_esp_netif`.
Creating and configuring the interface and attaching the network interface driver to it (steps ``2)``, ``3)`` and ``4)``) is described in :ref:`create_esp_netif`.
Using the ESP-NETIF event handlers (step ``5)``) is described in :ref:`esp-netif-ip-events`.
.. _create_esp_netif:
Common network interfaces
Common Network Interfaces
^^^^^^^^^^^^^^^^^^^^^^^^^
As the initialization of network interfaces could be quite complex, ESP-NETIF provides some convenient methods of creating the most common onc, such as Wi-Fi and Ethernet.
As the initialization of network interfaces could be quite complex, ESP-NETIF provides some convenient methods of creating the most common ones, such as Wi-Fi and Ethernet.
Please refer to the following example to understand the initialization process of the default interface:
@@ -115,34 +111,34 @@ The initialization code as well as registering event handlers for default interf
.. only:: SOC_WIFI_SUPPORTED
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, 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()`.
* These *default* interfaces must not be created multiple times unless the created handle is deleted using :cpp:func:`esp_netif_destroy()`.
* These *default* interfaces must not be created multiple times unless the created handle is deleted using :cpp:func:`esp_netif_destroy_default_wifi()`.
.. only:: CONFIG_ESP_WIFI_SOFTAP_SUPPORT
* When using Wi-Fi in ``AP+STA`` mode, both these interfaces have to be created.
* When using Wi-Fi in ``AP+STA`` mode, both these interfaces have to be created. Please refer to the example :example_file:`wifi/softap_sta/main/softap_sta.c`
.. _esp-netif-ip-events:
IP Events
---------
In the last section of :ref:`esp_netif_init` code (step ``5)``), we register two sets of event handlers:
In the final section of :ref:`esp_netif_init` code (step ``5)``), you register two sets of event handlers:
* Communication driver events: To be notified about driver's lifecycle states, for example when Wi-Fi station joined an AP, or when it gets disconnected. Handling these events is out of the scope of ESP-NETIF component, it is only worth mentioning that the same events are also used by ESP-NETIF to set the network interface to a desired state of, so if an application uses the driver's events to assume specific states of the network interface, it need to register their handlers **after** registering system handlers (which typically happen when attaching the driver to the interface). That is why the handler registration is performed in the last step of the :ref:`esp_netif_init` code.
* **Network Interface Driver Events**: These events notify you about the driver's lifecycle states, such as when a Wi-Fi station joins an AP or gets disconnected. Handling these events is outside the scope of the ESP-NETIF component. It is worth noting that the same events are also used by ESP-NETIF to set the network interface to a desired state. Therefore, if your application uses the driver's events to determine specific states of the network interface, you should register these handlers **after** registering the system handlers (which typically happens when attaching the driver to the interface). This is why handler registration occurs in the final step of the :ref:`esp_netif_init` code.
* IP events: To be notified about IP address changes, that is when we get assigned a new address or when the valid address is lost. Specific types of these events are listed in :cpp:type:`ip_event_t`, each common interface has the related pair of ``GOT_IP`` and ``LOST_IP`` events.
* **IP Events**: These events notify you about IP address changes, such as when a new address is assigned or when a valid address is lost. Specific types of these events are listed in :cpp:type:`ip_event_t`. Each common interface has a related pair of ``GOT_IP`` and ``LOST_IP`` events.
Registering event handlers is crucial due to the asynchronous nature of networking, where changes in network state can occur unpredictably. By registering event handlers, applications can respond to these changes promptly, ensuring appropriate actions are taken in response to network events.
.. note::
Lost IP events are triggered by a timer configurable by :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`. The timer is started upon losing the IP address and the event will be raised after the configured interval, which is 120s by default. The event could be disabled when setting the interval to 0.
.. _esp-netif structure:
ESP-NETIF Architecture
@@ -175,26 +171,25 @@ ESP-NETIF Architecture
+-----| | | | | | |
| | | | | | (D) |
(B) | | | | (C) | +-----------------------+
--------+ | | +===========================+
COMMUNICATION | | NETWORK STACK
DRIVER | | ESP-NETIF
| | +------------------+
| | +---------------------------+.........| open/close |
--------+ | | +===========================+ NETWORK STACK
NETWORK | | ESP-NETIF
INTERFACE | |
DRIVER | | +---------------------------+ +------------------+
| | | |.........| open/close |
| | | | | |
| -<--| l2tap_write |-----<---| write |
| | | | |
---->--| esp_vfs_l2tap_eth_filter |----->---| read |
| | | |
| | | (A) |
| (E) | +------------------+
+---------------------------+
USER CODE
+---------------------------+ USER CODE
ESP-NETIF L2 TAP
Data and Event Flow in the Diagram
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``........`` Initialization line from user code to ESP-NETIF and communication driver
* ``........`` Initialization line from user code to ESP-NETIF and network interface driver
* ``--<--->--`` Data packets going from communication media to TCP/IP stack and back
@@ -208,7 +203,7 @@ ESP-NETIF Interaction
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:
Overall application interaction with a specific IO driver for the communication media (network interface driver) and configured TCP/IP network stack is abstracted using ESP-NETIF APIs and is outlined as below:
A) Initialization code
@@ -232,10 +227,10 @@ B) Interaction with network interfaces using ESP-NETIF API
3) Controls application lifecycle (set interface up or down)
B) Communication Driver, IO Driver, and Media Driver
''''''''''''''''''''''''''''''''''''''''''''''''''''
B) Network Interface Driver
'''''''''''''''''''''''''''
Communication driver plays these two important roles in relation to ESP-NETIF:
Network interface driver (also called I/O Driver, or Media Driver) plays these two important roles in relation to ESP-NETIF:
1) Event handlers: Defines behavior patterns of interaction with ESP-NETIF (e.g., ethernet link-up -> turn netif on)
@@ -276,18 +271,14 @@ The network stack has no public interaction with application code with regard to
E) ESP-NETIF L2 TAP Interface
'''''''''''''''''''''''''''''
The ESP-NETIF L2 TAP interface is a mechanism in ESP-IDF used to access Data Link Layer (L2 per OSI/ISO) for frame reception and transmission from the user application. Its typical usage in the embedded world might be the implementation of non-IP-related protocols, e.g., PTP, Wake on LAN. Note that only Ethernet (IEEE 802.3) is currently supported.
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.
The ESP-NETIF L2 TAP interface is a mechanism in ESP-IDF used to access Data Link Layer (L2 per OSI/ISO) for frame reception and transmission from the user application. Its typical usage in the embedded world might be the implementation of non-IP-related protocols, e.g., PTP, Wake on LAN. Note that only Ethernet (IEEE 802.3) is currently supported. Please read more about L2 TAP in :ref:`esp_netif_l2tap`.
.. _esp_netif_programmer:
ESP-NETIF Programmer's Manual
=============================
In same cases, it is not enough to simply initialize a network interface by default, start using it and connect to the local network. If so, please consult the programming guide: :doc:`/api-reference/network/esp_netif_programming`.
In some cases, it is not enough to simply initialize a network interface by default, start using it and connect to the local network. If so, please consult the programming guide: :doc:`/api-reference/network/esp_netif_programming`.
You would typically need to use specific sets of ESP-NETIF APIs in the following use-cases:
@@ -303,4 +294,4 @@ You would typically need to use specific sets of ESP-NETIF APIs in the following
ESP-NETIF Developer's Manual
============================
In some cases, user applications might need to customize ESP-NETIF, register custom drivers or even custom TCP/IP stacks. If so, please consult the programming guide: :doc:`/api-reference/network/esp_netif_driver`.
In some cases, user applications might need to customize ESP-NETIF, register custom drivers or even use a custom TCP/IP stack. If so, please consult the :doc:`/api-reference/network/esp_netif_driver`.

31
docs/en/api-reference/network/esp_netif_driver.rst
View File

@@ -1,8 +1,16 @@
ESP-NETIF Custom I/O Driver
===========================
ESP-NETIF Developer's manual
============================
:link_to_translation:`zh_CN:[中文]`
As shown in the :ref:`esp-netif structure` diagram, ESP-NETIF is in fact an intermediary between the I/O driver and the TCP/IP stack. This manual describes customization of these two sides, that is if you need to implement :ref:`esp_netif_custom_driver` or if you need to employ :ref:`esp_netif_tcpip_stack`.
.. _esp_netif_custom_driver:
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.
@@ -88,7 +96,24 @@ 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.
Note that ESP-IDF provides several network stack configurations for the most common network interfaces, such as for the Wi-Fi station or Ethernet. These configurations are defined in :component_file:`esp_netif/include/esp_netif_defaults.h` and should be sufficient for most network drivers. In rare cases, expert users might want to define custom lwIP based interface layers; it is possible, but an explicit dependency to lwIP needs to be set.
Note that ESP-IDF provides several network stack configurations for the most common network interfaces, such as for the Wi-Fi station or Ethernet. These configurations are defined in :component_file:`esp_netif/include/esp_netif_defaults.h` and should be sufficient for most network drivers.
In some cases, you might want to define a custom lwIP based interface, for example if you need to update :component_file:`esp_netif/lwip/netif/wlanif.c` with a specific packet pool. In that case, you would have to define an explicit dependency to lwIP and include :component_file:`esp_netif/include/lwip/esp_netif_net_stack.h` for the relevant lwIP configuration structures.
.. _esp_netif_tcpip_stack:
ESP-NETIF Custom TCP/IP Stack
-----------------------------
It is possible to use a custom TCP/IP stack with ESP-IDF, provided it implements BSD API. You can add support for your own TCP/IP stack, while using the generic ESP-NETIF functionality, so the application code can stay the same as with the lwIP.
In this case, please choose ``ESP_NETIF_PROVIDE_CUSTOM_IMPLEMENTATION`` in the ESP-NETIF component configuration menu. This option will disable lwIP implementation of the ESP-NETIF functions and provide only header files with declarations of types and API. You will have to supply the necessary implementation in your custom component. You can refer to the :component_file:`esp_netif/loopback/esp_netif_loopback.c` for example of dummy implementations of these functions.
It is also possible to build ESP-IDF without lwIP, please refer to :idf_file:`components/esp_netif_stack/README.md`.
API Reference
-------------
The following API reference outlines these network stack interaction with the ESP-NETIF:

51
docs/en/api-reference/network/esp_netif_programming.rst
View File

@@ -5,10 +5,10 @@ ESP-NETIF Programmers Manual
.. _esp_netif_set_ip:
Configure IP, GW and DNS
------------------------
Configure IP, Gateway, and DNS
------------------------------
We typically obtain IP addresses (including gateway, network mask, and DNS servers) automatically from DHCP or Router Advertisement services and receive notifications by means of ``IP_EVENT`` with IP address information. It is also possible to read the current address information using :cpp:func:`esp_netif_get_ip_info()`, which returns this address structure :cpp:type:`esp_netif_ip_info_t` containing IPv4 address of the network interface with the network mask and gateway address. Similarly, you can use :cpp:func:`esp_netif_get_all_ip6()` to obtain all IPv6 addresses of the interface.
Typically, IP addresses -- including the gateway, network mask, and DNS servers -- are automatically obtained through a DHCP server or Router Advertisement services. Notifications regarding IP address assignments are received via the ``IP_EVENT``, which provides the relevant IP address information. You can also retrieve the current address details using the function :cpp:func:`esp_netif_get_ip_info()`. This function returns a structure, :cpp:type:`esp_netif_ip_info_t`, that contains the IPv4 address of the network interface, along with its network mask and gateway address. Similarly, the function :cpp:func:`esp_netif_get_all_ip6()` can be used to obtain all IPv6 addresses associated with the interface.
In order to configure static IP addresses and DNS servers, it's necessary to disable or stop DHCP client (which is enabled by default on some network interfaces, such as the default Ethernet, or the default WiFi station). Please refer to the example :example:`/protocols/static_ip` for more details.
@@ -20,23 +20,25 @@ To configure DNS servers, please use :cpp:func:`esp_netif_set_dns_info()` API.
Configure DHCP options
----------------------
Some network interfaces are pre-configured to use either a DHCP client (typically the Ethernet interface) or a DHCP server (typically a WiFi software access point). When creating a custom network interface manually, these configuration flags :cpp:type:`esp_netif_flags_t` are used to specify the behavioral options of this interface, so adding :cpp:enumerator:`ESP_NETIF_DHCP_CLIENT` or :cpp:enumerator:`ESP_NETIF_DHCP_SERVER` will enable DHCP client or server respectively. Note that these two options are mutually exclusive and cannot be altered runtime, so an interface configured with the DHCP server on creating cannot be used to start a DHCP server.
Some network interfaces are pre-configured to use either a DHCP client (commonly for Ethernet interfaces) or a DHCP server (typically for Wi-Fi software access points). When manually creating a custom network interface, the configuration flags :cpp:type:`esp_netif_flags_t` are used to specify the behavior of the interface. Adding :cpp:enumerator:`ESP_NETIF_DHCP_CLIENT` or :cpp:enumerator:`ESP_NETIF_DHCP_SERVER` will enable the DHCP client or server, respectively.
In order to set or get a specific DHCP option, we use this common type :cpp:type:`esp_netif_dhcp_option_id_t` for both DHCP server and DHCP client, but not all options are supported for both server and client. Please refer to the API documentation of :cpp:func:`esp_netif_dhcpc_option()` to see which options are available for the DHCP client. Conversely, consult the API documentation of :cpp:func:`esp_netif_dhcps_option()` on the options available for the DHCP server.
It is important to note that these two options are mutually exclusive and cannot be changed at runtime. If an interface is configured as a DHCP client upon creation, it cannot later be used as a DHCP server. The only option is to destroy the existing network interface and create a new one with the desired configuration.
To set or get a specific DHCP option, the common type :cpp:type:`esp_netif_dhcp_option_id_t` is used for both the DHCP server and client. However, not all options are supported for both. For details on the available options for the DHCP client, refer to the API documentation for :cpp:func:`esp_netif_dhcpc_option()`. Similarly, for the options available for the DHCP server, consult the API documentation for :cpp:func:`esp_netif_dhcps_option()`.
.. _esp_netif-sntp-api:
SNTP Service
------------
You can find a brief introduction to SNTP in general, its initialization code, and basic modes in Section :ref:`system-time-sntp-sync` in :doc:`System Time </api-reference/system/system_time>`.
A brief introduction to SNTP, its initialization code, and basic modes can be found in Section :ref:`system-time-sntp-sync` in :doc:`System Time </api-reference/system/system_time>`.
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:
This section provides more details on specific use cases for the SNTP service, such as using statically configured servers, DHCP-provided servers, or both. The workflow is typically straightforward:
1) Initialize and configure the service using :cpp:func:`esp_netif_sntp_init()`. This operations can only be called once (unless the SNTP service has been destroyed by :cpp:func:`esp_netif_sntp_deinit()`)
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()`.
1. Initialize and configure the service using :cpp:func:`esp_netif_sntp_init()`. This function can only be called once unless the SNTP service has been destroyed using :cpp:func:`esp_netif_sntp_deinit()`.
2. Start the service with :cpp:func:`esp_netif_sntp_start()`. This step is not necessary if the service was auto-started in the previous step (default behavior). However, it can be useful to start the service explicitly after connecting if DHCP-provided NTP servers are being used. Note that this option needs to be enabled before connecting, but the SNTP service should only be started afterward.
3. Wait for the system time to synchronize using :cpp:func:`esp_netif_sntp_sync_wait()` (if required).
4. Stop and destroy the service using :cpp:func:`esp_netif_sntp_deinit()`.
Basic Mode with Statically Defined Server(s)
@@ -52,13 +54,13 @@ Initialize the module with the default configuration after connecting to the net
.. note::
If we want to configure multiple SNTP servers, we have to update the lwIP configuration :ref:`CONFIG_LWIP_SNTP_MAX_SERVERS`.
If you want to configure multiple SNTP servers, update the lwIP configuration option :ref:`CONFIG_LWIP_SNTP_MAX_SERVERS`.
Use DHCP-Obtained SNTP Server(s)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First of all, we have to enable the lwIP configuration option :ref:`CONFIG_LWIP_DHCP_GET_NTP_SRV`. Then we have to initialize the SNTP module with the DHCP option and without the NTP server:
First, you need to enable the lwIP configuration option :ref:`CONFIG_LWIP_DHCP_GET_NTP_SRV`. Then, initialize the SNTP module with the DHCP option, without specifying an NTP server.
.. code-block:: c
@@ -67,7 +69,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 are connected, we could start the service using:
Once connected, you can start the service using:
.. code-block:: c
@@ -75,13 +77,13 @@ Then, once we are connected, we could start the service using:
.. note::
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.
It is also possible to start the service during initialization (with the default ``config.start=true``). However, this may cause the initial SNTP request to fail since you are not connected yet, which could result in a back-off period for subsequent requests.
Use Both Static and Dynamic Servers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Very similar to the scenario above (DHCP provided SNTP server), but in this configuration, we need to make sure that the static server configuration is refreshed when obtaining NTP servers by DHCP. The underlying lwIP code cleans up the rest of the list of NTP servers when the DHCP-provided information gets accepted. Thus the ESP-NETIF SNTP module saves the statically configured server(s) and reconfigures them after obtaining a DHCP lease.
This scenario is similar to using DHCP-provided SNTP servers. However, in this configuration, you need to ensure that the static server configuration is refreshed when obtaining NTP servers via DHCP. The underlying lwIP code removes the existing list of NTP servers when DHCP-provided information is accepted. Therefore, the ESP-NETIF SNTP module retains the statically configured server(s) and appends them to the list after obtaining a DHCP lease.
The typical configuration now looks as per below, providing the specific ``IP_EVENT`` to update the config and index of the first server to reconfigure (for example setting ``config.index_of_first_server=1`` would keep the DHCP provided server at index 0, and the statically configured server at index 1).
@@ -92,15 +94,24 @@ The typical configuration now looks as per below, providing the specific ``IP_EV
config.server_from_dhcp = true; // accept the NTP offers from DHCP server
config.renew_servers_after_new_IP = true; // let esp-netif update the configured SNTP server(s) after receiving the DHCP lease
config.index_of_first_server = 1; // updates from server num 1, leaving server 0 (from DHCP) intact
config.ip_event_to_renew = IP_EVENT_STA_GOT_IP; // IP event on which we refresh the configuration
config.ip_event_to_renew = IP_EVENT_STA_GOT_IP; // IP event on which you refresh your configuration
Then we start the service normally with :cpp:func:`esp_netif_sntp_start()`.
Then you start the service normally with :cpp:func:`esp_netif_sntp_start()`.
.. _esp_netif_l2tap:
L2 TAP Interface Usage Manual
-----------------------------
L2 TAP Interface Usage
----------------------
The ESP-NETIF L2 TAP interface is used to access Data Link Layer, please refer to the :ref:`esp-netif structure` diagram to see how L2 TAP interacts with ESP-NETIF and application.
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, but you can open multiple file descriptors from it, each with its own unique configuration. Think of the ESP-NETIF L2 TAP interface as a general gateway to the Layer 2 network infrastructure. The key point is that each file descriptor can be individually configured, which is crucial. For example, a file descriptor can be set up to access a specific network interface identified by if_key (like ETH_DEF) and to filter specific types of frames (such as filtering by Ethernet type for IEEE 802.3 frames).
This filtering is essential because the ESP-NETIF L2 TAP works alongside the IP stack, meaning that IP-related traffic (like IP, ARP, etc.) should not be sent directly to your application. Although this option is still possible, it is not recommended in standard use cases. The benefit of filtering is that it allows your application to receive only the frame types it cares about, while other traffic is either routed to different L2 TAP file descriptors or handled by the IP stack.
Initialization
^^^^^^^^^^^^^^

2
docs/en/api-reference/network/index.rst
View File

@@ -59,8 +59,8 @@ ESP-NETIF
.. toctree::
:hidden:
esp_netif_driver
esp_netif_programming
esp_netif_driver
IP Network Layer
================