A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/lwip.html below:

Website Navigation


lwIP - ESP32 - — ESP-IDF Programming Guide latest documentation

lwIP

[中文]

ESP-IDF uses the open source lwIP lightweight TCP/IP stack. The ESP-IDF version of lwIP (esp-lwip) has some modifications and additions compared to the upstream project.

Supported APIs

ESP-IDF supports the following lwIP TCP/IP stack functions:

Adapted APIs

Warning

When using any lwIP API other than the BSD Sockets API, please make sure that the API is thread-safe. To check if a given API call is thread-safe, enable the CONFIG_LWIP_CHECK_THREAD_SAFETY configuration option and run the application. This enables lwIP to assert the correct access of the TCP/IP core functionality. If the API is not accessed or locked properly from the appropriate lwIP FreeRTOS Task, the execution will be aborted. The general recommendation is to use the ESP-NETIF component to interact with lwIP.

Some common lwIP app APIs are supported indirectly by ESP-IDF:

Note

DNS server configuration in lwIP is global, not interface-specific. If you are using multiple network interfaces with distinct DNS servers, exercise caution to prevent inadvertent overwrites of one interface's DNS settings when acquiring a DHCP lease from another interface.

BSD Sockets API

The BSD Sockets API is a common cross-platform TCP/IP sockets API that originated in the Berkeley Standard Distribution of UNIX but is now standardized in a section of the POSIX specification. BSD Sockets are sometimes called POSIX Sockets or Berkeley Sockets.

As implemented in ESP-IDF, lwIP supports all of the common usages of the BSD Sockets API. However, not all operations are fully thread-safe, and simultaneous reads and writes from multiple threads may require additional synchronization mechanisms, see Limitations for more details.

References

A wide range of BSD Sockets reference materials are available, including:

Application Examples

A number of ESP-IDF examples show how to use the BSD Sockets APIs:

Supported Functions

The following BSD socket API functions are supported. For full details, see lwip/lwip/src/include/lwip/sockets.h.

Non-standard functions:

Note

Some lwIP application sample code uses prefixed versions of BSD APIs, e.g., lwip_socket(), instead of the standard socket(). Both forms can be used with ESP-IDF, but using standard names is recommended.

Socket Error Handling

BSD Socket error handling code is very important for robust socket applications. Normally, socket error handling involves the following aspects:

In lwIP, we have two different scenarios for handling socket errors:

Socket API Errors

Error detection

Get the error reason code

Example:

int err;
int sockfd;

if (sockfd = socket(AF_INET,SOCK_STREAM,0) < 0) {
    // the error code is obtained from errno
    err = errno;
    return err;
}
select() Errors

Error detection

Get the error reason code

Note

The getsockopt() function has the following prototype: int getsockopt(int s, int level, int optname, void *optval, socklen_t *optlen). Its purpose is to get the current value of the option of any type, any state socket, and store the result in optval. For example, when you get the error code on a socket, you can get it by getsockopt(sockfd, SOL_SOCKET, SO_ERROR, &err, &optlen).

Example:

int err;

if (select(sockfd + 1, NULL, NULL, &exfds, &tval) <= 0) {
    err = errno;
    return err;
} else {
    if (FD_ISSET(sockfd, &exfds)) {
        // select() exception set using getsockopt()
        int optlen = sizeof(int);
        getsockopt(sockfd, SOL_SOCKET, SO_ERROR, &err, &optlen);
        return err;
    }
}
Socket Error Reason Code

Below is a list of common error codes. For a more detailed list of standard POSIX/C error codes, please see newlib errno.h and the platform-specific extensions newlib/platform_include/sys/errno.h.

Error code

Description

ECONNREFUSED

Connection refused

EADDRINUSE

Address already in use

ECONNABORTED

Software caused connection abort

ENETUNREACH

Network is unreachable

ENETDOWN

Network interface is not configured

ETIMEDOUT

Connection timed out

EHOSTDOWN

Host is down

EHOSTUNREACH

Host is unreachable

EINPROGRESS

Connection already in progress

EALREADY

Socket already connected

EDESTADDRREQ

Destination address required

EPROTONOSUPPORT

Unknown protocol

Socket Options

The getsockopt() and setsockopt() functions allow getting and setting per-socket options respectively.

Not all standard socket options are supported by lwIP in ESP-IDF. The following socket options are supported:

Common Options

Used with level argument SOL_SOCKET.

IP Options

Used with level argument IPPROTO_IP.

For multicast UDP sockets:

TCP Options

TCP sockets only. Used with level argument IPPROTO_TCP.

Options relating to TCP keepalive probes:

IPv6 Options

IPv6 sockets only. Used with level argument IPPROTO_IPV6.

For multicast IPv6 UDP sockets:

fcntl()

The fcntl() function is a standard API for manipulating options related to a file descriptor. In ESP-IDF, the Virtual Filesystem Component layer is used to implement this function.

When the file descriptor is a socket, only the following fcntl() values are supported:

ioctl()

The ioctl() function provides a semi-standard way to access some internal features of the TCP/IP stack. In ESP-IDF, the Virtual Filesystem Component layer is used to implement this function.

When the file descriptor is a socket, only the following ioctl() values are supported:

Netconn API

lwIP supports two lower-level APIs as well as the BSD Sockets API: the Netconn API and the Raw API.

The lwIP Raw API is designed for single-threaded devices and is not supported in ESP-IDF.

The Netconn API is used to implement the BSD Sockets API inside lwIP, and it can also be called directly from ESP-IDF apps. This API has lower resource usage than the BSD Sockets API. In particular, it can send and receive data without firstly copying it into internal lwIP buffers.

Important

Espressif does not test the Netconn API in ESP-IDF. As such, this functionality is enabled but not supported. Some functionality may only work correctly when used from the BSD Sockets API.

For more information about the Netconn API, consult lwip/lwip/src/include/lwip/api.h and part of the **unofficial** lwIP Application Developers Manual.

lwIP FreeRTOS Task

lwIP creates a dedicated TCP/IP FreeRTOS task to handle socket API requests from other tasks.

A number of configuration items are available to modify the task and the queues (mailboxes) used to send data to/from the TCP/IP task:

IPv6 Support

Both IPv4 and IPv6 are supported in a dual-stack configuration and are enabled by default. Both IPv6 and IPv4 may be disabled separately if they are not needed, see Minimum RAM Usage.

IPv6 support is limited to Stateless Autoconfiguration only. Stateful configuration is not supported in ESP-IDF, nor in upstream lwIP.

IPv6 Address configuration is defined by means of these protocols or services:

None of these two types of address configuration is enabled by default, so the device uses only Link Local addresses or statically-defined addresses.

Stateless Autoconfiguration Process

To enable address autoconfiguration using the Router Advertisement protocol, please enable:

This configuration option enables IPv6 autoconfiguration for all network interfaces, which differs from the upstream lwIP behavior, where the autoconfiguration needs to be explicitly enabled for each netif with netif->ip6_autoconfig_enabled=1.

DHCPv6

DHCPv6 in lwIP is very simple and supports only stateless configuration. It could be enabled using:

Since the DHCPv6 works only in its stateless configuration, the Stateless Autoconfiguration Process has to be enabled as well via CONFIG_LWIP_IPV6_AUTOCONFIG.

Moreover, the DHCPv6 needs to be explicitly enabled from the application code using:

dhcp6_enable_stateless(netif);
DNS Servers in IPv6 Autoconfiguration

In order to autoconfigure DNS server(s), especially in IPv6-only networks, we have these two options:

ESP-lwIP Custom Modifications Additions

The following code is added, which is not present in the upstream lwIP release:

Thread-Safe Sockets

It is possible to close() a socket from a different thread than the one that created it. The close() call blocks, until any function calls currently using that socket from other tasks have returned.

It is, however, not possible to delete a task while it is actively waiting on select() or poll() APIs. It is always necessary that these APIs exit before destroying the task, as this might corrupt internal structures and cause subsequent crashes of the lwIP. These APIs allocate globally referenced callback pointers on the stack so that when the task gets destroyed before unrolling the stack, the lwIP could still hold pointers to the deleted stack.

On-Demand Timers

lwIP IGMP and MLD6 feature both initialize a timer in order to trigger timeout events at certain times.

The default lwIP implementation is to have these timers enabled all the time, even if no timeout events are active. This increases CPU usage and power consumption when using automatic Light-sleep mode. ESP-lwIP default behavior is to set each timer on demand, so it is only enabled when an event is pending.

To return to the default lwIP behavior, which is always-on timers, disable CONFIG_LWIP_TIMERS_ONDEMAND.

lwIP Timers API

When not using Wi-Fi, the lwIP timer can be turned off via the API to reduce power consumption.

The following API functions are supported. For full details, see lwip/lwip/src/include/lwip/timeouts.h.

Additional Socket Options IP Layer Features NAPT and Port Forwarding

IPV4 network address port translation (NAPT) and port forwarding are supported. However, the enabling of NAPT is limited to a single interface.

Default lwIP Hooks

ESP-IDF port layer provides a default hook file, which is included in the lwIP build process. This file is located at lwip/port/include/lwip_default_hooks.h and defines several hooks that implement default ESP-IDF behavior of lwIP stack. These hooks could be further modified by choosing one of these options:

DHCP Extra Option Hook

ESP-IDF allows applications to define a hook for handling extra DHCP options. This can be useful for implementing custom DHCP-based behaviors, such as retrieving specific vendor options. To enable this feature, configure CONFIG_LWIP_HOOK_DHCP_EXTRA_OPTION either to Default (weak implementation is provided which could be replaced by custom implementation) or Custom (you will have to implement the hook and define its link dependency to lwip)

Example Usage

An application can define the following function to handle a specific DHCP option (e.g., captive portal URI):

#include "esp_netif.h"
#include "lwip/dhcp.h"

void lwip_dhcp_on_extra_option(struct dhcp *dhcp, uint8_t state,
                               uint8_t option, uint8_t len,
                               struct pbuf* p, uint16_t offset)
{
    if (option == ESP_NETIF_CAPTIVEPORTAL_URI) {
        char *uri = (char *)p->payload + offset;
        ESP_LOGI(TAG, "Captive Portal URI: %s", uri);
    }
}

Other Default Hooks

ESP-IDF provides additional lwIP hooks that can be overridden. These include:

Each of these hooks can be configured in menuconfig, allowing selection of default, custom, or no implementation.

Customized lwIP Hooks

The original lwIP supports implementing custom compile-time modifications via LWIP_HOOK_FILENAME. This file is already used by the ESP-IDF port layer, but ESP-IDF users could still include and implement any custom additions via a header file defined by the macro ESP_IDF_LWIP_HOOK_FILENAME. Here is an example of adding a custom hook file to the build process, and the hook is called my_hook.h, located in the project's main folder:

idf_component_get_property(lwip lwip COMPONENT_LIB)
target_compile_options(${lwip} PRIVATE "-I${PROJECT_DIR}/main")
target_compile_definitions(${lwip} PRIVATE "-DESP_IDF_LWIP_HOOK_FILENAME=\"my_hook.h\"")
Customized lwIP Options From ESP-IDF Build System

The most common lwIP options are configurable through the component configuration menu. However, certain definitions need to be injected from the command line. The CMake function target_compile_definitions() can be employed to define macros, as illustrated below:

idf_component_get_property(lwip lwip COMPONENT_LIB)
target_compile_definitions(${lwip} PRIVATE "-DETHARP_SUPPORT_VLAN=1")

This approach may not work for function-like macros, as there is no guarantee that the definition will be accepted by all compilers, although it is supported in GCC. To address this limitation, the add_definitions() function can be utilized to define the macro for the entire project, for example: add_definitions("-DFALLBACK_DNS_SERVER_ADDRESS(addr)=\"IP_ADDR4((addr), 8,8,8,8)\"").

Alternatively, you can define your function-like macro in a header file which will be pre-included as an lwIP hook file, see Customized lwIP Hooks.

Limitations

lwIP in ESP-IDF supports thread safety in certain scenarios, but with limitations. It is possible to perform read, write, and close operations from different threads on the same socket simultaneously. However, performing multiple reads or multiple writes from more than one thread on the same socket at the same time is not supported. Applications that require simultaneous reads or writes from multiple threads on the same socket must implement additional synchronization mechanisms, such as locking around socket operations.

ESP-IDF additions to lwIP still suffer from the global DNS limitation, described in Adapted APIs. To address this limitation from application code, the FALLBACK_DNS_SERVER_ADDRESS() macro can be utilized to define a global DNS fallback server accessible from all interfaces. Alternatively, you have the option to maintain per-interface DNS servers and reconfigure them whenever the default interface changes.

The number of IP addresses returned by network database APIs such as getaddrinfo() and gethostbyname() is restricted by the macro DNS_MAX_HOST_IP. By default, the value of this macro is set to 1.

In the implementation of getaddrinfo(), the canonical name is not available. Therefore, the ai_canonname field of the first returned addrinfo structure will always refer to the nodename argument or a string with the same contents.

The getaddrinfo() system call in lwIP within ESP-IDF has a limitation when using AF_UNSPEC, as it defaults to returning only an IPv4 address in dual stack mode. This can cause issues in IPv6-only networks. To handle this, a workaround involves making two sequential calls to getaddrinfo(): the first with AF_INET to query for IPv4 addresses, and the second with AF_INET6 to retrieve IPv6 addresses. To provide a more robust solution, the custom esp_getaddrinfo() function has been added to the lwIP port layer to handle both IPv4 and IPv6 addresses when AF_UNSPEC is used. The CONFIG_LWIP_USE_ESP_GETADDRINFO option, available when both IPv4 and IPv6 are enabled, controls whether esp_getaddrinfo() or getaddrinfo() is used. It is disabled by default.

Calling send() or sendto() repeatedly on a UDP socket may eventually fail with errno equal to ENOMEM. This failure occurs due to the limitations of buffer sizes in the lower-layer network interface drivers. If all driver transmit buffers are full, the UDP transmission will fail. For applications that transmit a high volume of UDP datagrams and aim to avoid any dropped datagrams by the sender, it is advisable to implement error code checking and employ a retransmission mechanism with a short delay.

Increasing the number of TX buffers in the Wi-Fi or Ethernet project configuration as applicable may also help.

Performance Optimization

TCP/IP performance is a complex subject, and performance can be optimized toward multiple goals. The default settings of ESP-IDF are tuned for a compromise between throughput, latency, and moderate memory usage.

Maximum Throughput

Espressif tests ESP-IDF TCP/IP throughput using the iperf test application: https://iperf.fr/, please refer to Improving Network Speed for more details about the actual testing and using the optimized configuration.

Important

Suggest applying changes a few at a time and checking the performance each time with a particular application workload.

If using a Wi-Fi network interface, please also refer to Wi-Fi Buffer Usage.

Minimum Latency

Except for increasing buffer sizes, most changes that increase throughput also decrease latency by reducing the amount of CPU time spent in lwIP functions.

Minimum RAM Usage

Most lwIP RAM usage is on-demand, as RAM is allocated from the heap as needed. Therefore, changing lwIP settings to reduce RAM usage may not change RAM usage at idle, but can change it at peak.

If using Wi-Fi, please also refer to Wi-Fi Buffer Usage.

Peak Buffer Usage

The peak heap memory that lwIP consumes is the theoretically-maximum memory that the lwIP driver consumes. Generally, the peak heap memory that lwIP consumes depends on:

So, the peak heap memory that the lwIP consumes can be calculated with the following formula:

lwip_dynamic_peek_memory = (lwip_udp_con_num * lwip_udp_conn) + (lwip_tcp_con_num * (lwip_tcp_tx_win_size + lwip_tcp_rx_win_size + lwip_tcp_conn))

Some TCP-based applications need only one TCP connection. However, they may choose to close this TCP connection and create a new one when an error occurs (e.g., a sending failure). This may result in multiple TCP connections existing in the system simultaneously, because it may take a long time for a TCP connection to close, according to the TCP state machine, refer to RFC793.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4