Networking
Wi-Fi
Callback function type esp_now_recv_cb_t
Previously, the first parameter of esp_now_recv_cb_t
was of type const uint8_t *mac_addr
, which only included the address of ESP-NOW peer device.
This now changes. The first parameter is of type esp_now_recv_info_t
, which has members src_addr
, des_addr
and rx_ctrl
. Therefore, the following updates are required:
Redefine ESP-NOW receive callback function.
src_addr
can be used to replace originalmac_addr
.
des_addr
is the destination MAC address of ESP-NOW packet, which can be unitcast or broadcast address. Withdes_addr
, the user can distinguish unitcast and broadcast ESP-NOW packets where broadcast ESP-NOW packets can be non-encrypted even when encryption policy is configured for the ESP-NOW.
rx_ctrl
is Rx control info of the ESP-NOW packet, which provides more information about the packet.
Please refer to the ESP-NOW example: wifi/espnow/main/espnow_example_main.c
Ethernet
esp_eth_ioctl() API
Previously, the esp_eth_ioctl()
API had the following issues:
The third parameter (which is of type
void *
) would accept anint
/bool
type arguments (i.e., not pointers) as input in some cases. However, these cases were not documented properly.To pass
int
/bool
type argument as the third parameter, the argument had to be “unnaturally” casted to avoid *
type, to prevent a compiler warning as demonstrated in the code snippet below. This casting could lead to misuse of theesp_eth_ioctl()
function.
esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, (void *)true);
Therefore, the usage of esp_eth_ioctl()
is now unified. Arguments to the third parameter must be passed as pointers to a specific data type to/from where data will be stored/read by esp_eth_ioctl()
. The code snippets below demonstrate the usage of esp_eth_ioctl()
.
Usage example to set Ethernet configuration:
eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF;
esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode);
Usage example to get Ethernet configuration:
eth_duplex_t duplex_mode;
esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);
KSZ8041/81 and LAN8720 Driver Update
The KSZ8041/81 and LAN8720 drivers are updated to support more devices (i.e., generations) from their associated product families. The drivers can recognize particular chip numbers and their potential support by the driver.
As a result, the specific “chip number” functions calls are replaced by generic ones as follows:
Removed
esp_eth_phy_new_ksz8041()
andesp_eth_phy_new_ksz8081()
, and useesp_eth_phy_new_ksz80xx()
insteadRemoved
esp_eth_phy_new_lan8720()
, and useesp_eth_phy_new_lan87xx()
instead
ESP NETIF Glue Event Handlers
esp_eth_set_default_handlers()
and esp_eth_clear_default_handlers()
functions are removed. Registration of the default IP layer handlers for Ethernet is now handled automatically. If you have already followed the suggestion to fully initialize the Ethernet driver and network interface before registering their Ethernet/IP event handlers, then no action is required (except for deleting the affected functions). Otherwise, you may start the Ethernet driver right after they register the user event handler.
PHY Address Auto-detect
The Ethernet PHY address auto-detect function esp_eth_detect_phy_addr()
is renamed to esp_eth_phy_802_3_detect_phy_addr()
and its header declaration is moved to esp_eth/include/esp_eth_phy_802_3.h.
SPI-Ethernet Module Initialization
The SPI-Ethernet Module initialization is now simplified. Previously, you had to manually allocate an SPI device using spi_bus_add_device()
before instantiating the SPI-Ethernet MAC.
Now, you no longer need to call spi_bus_add_device()
as SPI devices are allocated internally. As a result, the eth_dm9051_config_t
, eth_w5500_config_t
, and eth_ksz8851snl_config_t
configuration structures are updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ETH_DM9051_DEFAULT_CONFIG
, ETH_W5500_DEFAULT_CONFIG
, and ETH_KSZ8851SNL_DEFAULT_CONFIG
configuration initialization macros are updated to accept new input parameters. Refer to Ethernet API Reference Guide for an example of SPI-Ethernet Module initialization.
SPI-Ethernet Modules Initialization
The SPI-Ethernet Module’s initialization has been simplified. The previous initialization process required you to manually allocate an SPI device using spi_bus_add_device()
before instantiating the SPI-Ethernet MAC.
Now, you no longer need to call spi_bus_add_device()
as the allocation of the SPI device is done internally. As a result, the eth_dm9051_config_t
, eth_w5500_config_t
, and eth_ksz8851snl_config_t
configuration structures were updated to include members for SPI device configuration (e.g., to allow fine tuning of SPI timing which may be dependent on PCB design). Likewise, the ETH_DM9051_DEFAULT_CONFIG
, ETH_W5500_DEFAULT_CONFIG
, and ETH_KSZ8851SNL_DEFAULT_CONFIG
configuration initialization macros have been updated to accept new input parameters. Refer to the Ethernet API-Reference Guide for an example of SPI-Ethernet Module initialization
Ethernet Driver
APIs for creating MAC instances (esp_eth_mac_new_*()) have been reworked to accept two parameters, instead of one common configuration. Now, the configuration includes
Vendor specific MAC configuration
Ethernet driver MAC configuration
This is applicable to internal Ethernet MAC esp_eth_mac_new_esp32()
as well as to external MAC devices, such as esp_eth_mac_new_ksz8851snl()
, esp_eth_mac_new_dm9051()
, and esp_eth_mac_new_w5500()
TCP/IP Adapter
The TCP/IP Adapter was a network interface abstraction component used in ESP-IDF prior to v4.1. This section outlines migration from tcpip_adapter API to its successor ESP-NETIF.
Updating Network Connection Code
Network Stack Initialization
You may simply replace
tcpip_adapter_init()
withesp_netif_init()
. However, please should note that theesp_netif_init()
function now returns standard error codes. See ESP-NETIF for more details.The
esp_netif_deinit()
function is provided to de-initialize the network stack.You should also replace
#include "tcpip_adapter.h"
with#include "esp_netif.h"
.
Network Interface Creation
Previously, the TCP/IP Adapter defined the following network interfaces statically:
WiFi Station
WiFi Access Point
Ethernet
This now changes. Network interface instance should be explicitly constructed, so that the ESP-NETIF can connect to the TCP/IP stack. For example, after the TCP/IP stack and the event loop are initialized, the initialization code for WiFi must explicitly call esp_netif_create_default_wifi_sta();
or esp_netif_create_default_wifi_ap();
.
Please refer to the example initialization code for these three interfaces:
WiFi Station: wifi/getting_started/station/main/station_example_main.c
WiFi Access Point: wifi/getting_started/softAP/main/softap_example_main.c
Other tcpip_adapter API Replacement
All the tcpip_adapter functions have their esp-netif counter-part. Please refer to the esp_netif.h grouped into these sections:
The TCP/IP Adapter API tcpip_adapter_get_sta_list()
that was used to acquire a list of associated Wi-Fi stations to the Software Access Point (softAP) has been moved to the Wi-Fi component and renamed to esp_wifi_ap_get_sta_list_with_ip()
, which is a special case of the ESP-NETIF API esp_netif_dhcps_get_clients_by_mac()
that could be used more generally to provide a list of clients connected to a DHCP server no matter which network interface the server is running on.
Default Event Handlers
Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, as all events should be handled in the same way. Please note that for IP-related event handlers, application code usually receives IP addresses in the form of an esp-netif specific struct instead of the LwIP structs. However, both structs are binary compatible.
This is the preferred way to print the address:
ESP_LOGI(TAG, "got ip:" IPSTR "\n", IP2STR(&event->ip_info.ip));
Instead of
ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
Since ip4addr_ntoa()
is a LwIP API, the esp-netif provides esp_ip4addr_ntoa()
as a replacement. However, the above method using IP2STR()
is generally preferred.
IP Addresses
You are advised to use esp-netif defined IP structures. Please note that with default compatibility enabled, the LwIP structs will still work.
Next Steps
To port an application which may fully benefit from the ESP-NETIF, you also need to disable the tcpip_adapter compatibility layer in the component configuration option. Please go to ESP NETIF Adapter
> Enable backward compatible tcpip_adapter interface
. After that, check if your project compiles.
The TCP/IP adapter includes many dependencies. Thus, disabling its compatibility might help separate the application from using specific TCP/IP stack API directly.