TCP/IP Adapter

The purpose of TCP/IP Adapter 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.
  • The APIs it provides are thread safe, even if the underlying TCP/IP stack APIs are not.

ESP-IDF currently implements TCP/IP Adapter for the 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.

In many cases, applications do not need to call TCP/IP Adapter APIs directly as they are called from the default network event handlers.

API Reference

Functions

void tcpip_adapter_init(void)

Initialize the underlying TCP/IP stack.

Note
This function should be called exactly once from application code, when the application starts up.

esp_err_t tcpip_adapter_eth_start(uint8_t *mac, tcpip_adapter_ip_info_t *ip_info)

Cause the TCP/IP stack to start the Ethernet interface with specified MAC and IP.

Note
This function should be called after the Ethernet MAC hardware is initialized. In the default configuration, application code does not need to call this function - it is called automatically by the default handler for the SYSTEM_EVENT_ETH_START event.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_NO_MEM
Parameters
  • mac: Set MAC address of this interface
  • ip_info: Set IP address of this interface

esp_err_t tcpip_adapter_sta_start(uint8_t *mac, tcpip_adapter_ip_info_t *ip_info)

Cause the TCP/IP stack to start the Wi-Fi station interface with specified MAC and IP.

Note
This function should be called after the Wi-Fi Station hardware is initialized. In the default configuration, application code does not need to call this function - it is called automatically by the default handler for the SYSTEM_EVENT_STA_START event.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_NO_MEM
Parameters
  • mac: Set MAC address of this interface
  • ip_info: Set IP address of this interface

esp_err_t tcpip_adapter_ap_start(uint8_t *mac, tcpip_adapter_ip_info_t *ip_info)

Cause the TCP/IP stack to start the Wi-Fi AP interface with specified MAC and IP.

DHCP server will be started automatically when this function is called.

Note
This function should be called after the Wi-Fi AP hardware is initialized. In the default configuration, application code does not need to call this function - it is called automatically by the default handler for the SYSTEM_EVENT_AP_START event.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_NO_MEM
Parameters
  • mac: Set MAC address of this interface
  • ip_info: Set IP address of this interface

esp_err_t tcpip_adapter_stop(tcpip_adapter_if_t tcpip_if)

Cause the TCP/IP stack to stop a network interface.

Causes TCP/IP stack to clean up this interface. This includes stopping the DHCP server or client, if they are started.

Note
This API is called by the default Wi-Fi and Ethernet event handlers if the underlying network driver reports that the interface has stopped.
Note
To stop an interface from application code, call the network-specific API (esp_wifi_stop() or esp_eth_stop()). The driver layer will then send a stop event and the event handler should call this API. Otherwise, the driver and MAC layer will remain started.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: Interface which will be stopped

esp_err_t tcpip_adapter_up(tcpip_adapter_if_t tcpip_if)

Cause the TCP/IP stack to bring up an interface.

Note
This function is called automatically by the default event handlers for the Wi-Fi Station and Ethernet interfaces, in response to the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events, respectively.
Note
This function is not normally used with Wi-Fi AP interface. If the AP interface is started, it is up.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: Interface to bring up

esp_err_t tcpip_adapter_down(tcpip_adapter_if_t tcpip_if)

Cause the TCP/IP stack to shutdown an interface.

Note
This function is called automatically by the default event handlers for the Wi-Fi Station and Ethernet interfaces, in response to the SYSTEM_EVENT_STA_DISCONNECTED and SYSTEM_EVENT_ETH_DISCONNECTED events, respectively.
Note
This function is not normally used with Wi-Fi AP interface. If the AP interface is stopped, it is down.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: Interface to shutdown

esp_err_t tcpip_adapter_get_ip_info(tcpip_adapter_if_t tcpip_if, tcpip_adapter_ip_info_t *ip_info)

Get interface’s IP address information.

If the interface is up, IP information is read directly from the TCP/IP stack.

If the interface is down, IP information is read from a copy kept in the TCP/IP adapter library itself.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: Interface to get IP information
  • ip_info: If successful, IP information will be returned in this argument.

esp_err_t tcpip_adapter_set_ip_info(tcpip_adapter_if_t tcpip_if, const tcpip_adapter_ip_info_t *ip_info)

Set interface’s IP address information.

This function is mainly used to set a static IP on an interface.

If the interface is up, the new IP information is set directly in the TCP/IP stack.

The copy of IP information kept in the TCP/IP adapter library is also updated (this copy is returned if the IP is queried while the interface is still down.)

Note
DHCP client/server must be stopped before setting new IP information.
Note
Calling this interface for the Wi-Fi STA or Ethernet interfaces may generate a SYSTEM_EVENT_STA_GOT_IP or SYSTEM_EVENT_ETH_GOT_IP event.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_DHCP_NOT_STOPPED If DHCP server or client is still running
Parameters
  • tcpip_if: Interface to set IP information
  • ip_info: IP information to set on the specified interface

esp_err_t tcpip_adapter_set_dns_info(tcpip_adapter_if_t tcpip_if, tcpip_adapter_dns_type_t type, tcpip_adapter_dns_info_t *dns)

Set DNS Server information.

This function behaves differently for different interfaces:

  • For Wi-Fi Station interface and Ethernet interface, up to three types of DNS server can be set (in order of priority):

    • Main DNS Server (TCPIP_ADAPTER_DNS_MAIN)
    • Backup DNS Server (TCPIP_ADAPTER_DNS_BACKUP)
    • Fallback DNS Server (TCPIP_ADAPTER_DNS_FALLBACK)

    If DHCP client is enabled, main and backup DNS servers will be updated automatically from the DHCP lease if the relevant DHCP options are set. Fallback DNS Server is never updated from the DHCP lease and is designed to be set via this API.

    If DHCP client is disabled, all DNS server types can be set via this API only.

  • For Wi-Fi AP interface, the Main DNS Server setting is used by the DHCP server to provide a DNS Server option to DHCP clients (Wi-Fi stations).

    • The default Main DNS server is the IP of the Wi-Fi AP interface itself.
    • This function can override it by setting server type TCPIP_ADAPTER_DNS_MAIN.
    • Other DNS Server types are not supported for the Wi-Fi AP interface.

Return
  • ESP_OK on success
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS invalid params
Parameters
  • tcpip_if: Interface to set DNS Server information
  • type: Type of DNS Server to set: TCPIP_ADAPTER_DNS_MAIN, TCPIP_ADAPTER_DNS_BACKUP, TCPIP_ADAPTER_DNS_FALLBACK
  • dns: DNS Server address to set

esp_err_t tcpip_adapter_get_dns_info(tcpip_adapter_if_t tcpip_if, tcpip_adapter_dns_type_t type, tcpip_adapter_dns_info_t *dns)

Get DNS Server information.

Return the currently configured DNS Server address for the specified interface and Server type.

This may be result of a previous call to tcpip_adapter_set_dns_info(). If the interface’s DHCP client is enabled, the Main or Backup DNS Server may be set by the current DHCP lease.

Return
  • ESP_OK on success
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS invalid params
Parameters
  • tcpip_if: Interface to get DNS Server information
  • type: Type of DNS Server to get: TCPIP_ADAPTER_DNS_MAIN, TCPIP_ADAPTER_DNS_BACKUP, TCPIP_ADAPTER_DNS_FALLBACK
  • dns: DNS Server result is written here on success

esp_err_t tcpip_adapter_get_old_ip_info(tcpip_adapter_if_t tcpip_if, tcpip_adapter_ip_info_t *ip_info)

Get interface’s old IP information.

Returns an “old” IP address previously stored for the interface when the valid IP changed.

If the IP lost timer has expired (meaning the interface was down for longer than the configured interval) then the old IP information will be zero.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: Interface to get old IP information
  • ip_info: If successful, IP information will be returned in this argument.

esp_err_t tcpip_adapter_set_old_ip_info(tcpip_adapter_if_t tcpip_if, const tcpip_adapter_ip_info_t *ip_info)

Set interface old IP information.

This function is called from the DHCP client for the Wi-Fi STA and Ethernet interfaces, before a new IP is set. It is also called from the default handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events.

Calling this function stores the previously configured IP, which can be used to determine if the IP changes in the future.

If the interface is disconnected or down for too long, the “IP lost timer” will expire (after the configured interval) and set the old IP information to zero.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: Interface to set old IP information
  • ip_info: Store the old IP information for the specified interface

esp_err_t tcpip_adapter_create_ip6_linklocal(tcpip_adapter_if_t tcpip_if)

Create interface link-local IPv6 address.

Cause the TCP/IP stack to create a link-local IPv6 address for the specified interface.

This function also registers a callback for the specified interface, so that if the link-local address becomes verified as the preferred address then a SYSTEM_EVENT_GOT_IP6 event will be sent.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: Interface to create a link-local IPv6 address

esp_err_t tcpip_adapter_get_ip6_linklocal(tcpip_adapter_if_t tcpip_if, ip6_addr_t *if_ip6)

Get interface link-local IPv6 address.

If the specified interface is up and a preferred link-local IPv6 address has been created for the interface, return a copy of it.

Return
  • ESP_OK
  • ESP_FAIL If interface is down, does not have a link-local IPv6 address, or the link-local IPv6 address is not a preferred address.
Parameters
  • tcpip_if: Interface to get link-local IPv6 address
  • if_ip6: IPv6 information will be returned in this argument if successful.

esp_err_t tcpip_adapter_get_ip6_global(tcpip_adapter_if_t tcpip_if, ip6_addr_t *if_ip6)

Get interface global IPv6 address.

If the specified interface is up and a preferred global IPv6 address has been created for the interface, return a copy of it.

Return
  • ESP_OK
  • ESP_FAIL If interface is down, does not have a global IPv6 address.
Parameters
  • tcpip_if: Interface to get global IPv6 address
  • if_ip6: IPv6 information will be returned in this argument if successful.

esp_err_t tcpip_adapter_dhcps_get_status(tcpip_adapter_if_t tcpip_if, tcpip_adapter_dhcp_status_t *status)

Get DHCP Server status.

Return
  • ESP_OK
Parameters
  • tcpip_if: Interface to get status of DHCP server.
  • status: If successful, the status of the DHCP server will be returned in this argument.

esp_err_t tcpip_adapter_dhcps_option(tcpip_adapter_dhcp_option_mode_t opt_op, tcpip_adapter_dhcp_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP server option.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STOPPED
  • ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STARTED
Parameters
  • opt_op: TCPIP_ADAPTER_OP_SET to set an option, TCPIP_ADAPTER_OP_GET to get an option.
  • opt_id: Option index to get or set, must be one of the supported enum values.
  • opt_val: Pointer to the option parameter.
  • opt_len: Length of the option parameter.

esp_err_t tcpip_adapter_dhcps_start(tcpip_adapter_if_t tcpip_if)

Start DHCP server.

Note
Currently DHCP server is only supported on the Wi-Fi AP interface.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STARTED
Parameters
  • tcpip_if: Interface to start DHCP server. Must be TCPIP_ADAPTER_IF_AP.

esp_err_t tcpip_adapter_dhcps_stop(tcpip_adapter_if_t tcpip_if)

Stop DHCP server.

Note
Currently DHCP server is only supported on the Wi-Fi AP interface.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STOPPED
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: Interface to stop DHCP server. Must be TCPIP_ADAPTER_IF_AP.

esp_err_t tcpip_adapter_dhcpc_get_status(tcpip_adapter_if_t tcpip_if, tcpip_adapter_dhcp_status_t *status)

Get DHCP client status.

Return
  • ESP_OK
Parameters
  • tcpip_if: Interface to get status of DHCP client
  • status: If successful, the status of DHCP client will be returned in this argument.

esp_err_t tcpip_adapter_dhcpc_option(tcpip_adapter_dhcp_option_mode_t opt_op, tcpip_adapter_dhcp_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP client’s option.

Note
This function is not yet implemented
Return
  • ESP_ERR_NOT_SUPPORTED (not implemented)
Parameters
  • opt_op: TCPIP_ADAPTER_OP_SET to set an option, TCPIP_ADAPTER_OP_GET to get an option.
  • opt_id: Option index to get or set, must be one of the supported enum values.
  • opt_val: Pointer to the option parameter.
  • opt_len: Length of the option parameter.

esp_err_t tcpip_adapter_dhcpc_start(tcpip_adapter_if_t tcpip_if)

Start DHCP client.

Note
DHCP Client is only supported for the Wi-Fi station and Ethernet interfaces.
Note
The default event handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events call this function.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STARTED
  • ESP_ERR_TCPIP_ADAPTER_DHCPC_START_FAILED
Parameters
  • tcpip_if: Interface to start the DHCP client

esp_err_t tcpip_adapter_dhcpc_stop(tcpip_adapter_if_t tcpip_if)

Stop DHCP client.

Note
DHCP Client is only supported for the Wi-Fi station and Ethernet interfaces.
Note
Calling tcpip_adapter_stop() or tcpip_adapter_down() will also stop the DHCP Client if it is running.
Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
  • ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STOPPED
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: Interface to stop the DHCP client

esp_err_t tcpip_adapter_eth_input(void *buffer, uint16_t len, void *eb)

Receive an Ethernet frame from the Ethernet interface.

This function will automatically be installed by esp_eth_init(). The Ethernet driver layer will then call this function to forward frames to the TCP/IP stack.

Note
Application code does not usually need to use this function directly.
Return
  • ESP_OK
Parameters
  • buffer: Received data
  • len: Length of the data frame
  • eb: Pointer to internal Wi-Fi buffer (ignored for Ethernet)

esp_err_t tcpip_adapter_sta_input(void *buffer, uint16_t len, void *eb)

Receive an 802.11 data frame from the Wi-Fi Station interface.

This function should be installed by calling esp_wifi_reg_rxcb(). The Wi-Fi driver layer will then call this function to forward frames to the TCP/IP stack.

Note
Installation happens automatically in the default handler for the SYSTEM_EVENT_STA_CONNECTED event.
Note
Application code does not usually need to call this function directly.
Return
  • ESP_OK
Parameters
  • buffer: Received data
  • len: Length of the data frame
  • eb: Pointer to internal Wi-Fi buffer

esp_err_t tcpip_adapter_ap_input(void *buffer, uint16_t len, void *eb)

Receive an 802.11 data frame from the Wi-Fi AP interface.

This function should be installed by calling esp_wifi_reg_rxcb(). The Wi-Fi driver layer will then call this function to forward frames to the TCP/IP stack.

Note
Installation happens automatically in the default handler for the SYSTEM_EVENT_AP_START event.
Note
Application code does not usually need to call this function directly.
Return
  • ESP_OK
Parameters
  • buffer: Received data
  • len: Length of the data frame
  • eb: Pointer to internal Wi-Fi buffer

esp_interface_t tcpip_adapter_get_esp_if(void *dev)

Get network interface index.

Get network interface from TCP/IP implementation-specific interface pointer.

Return
  • ESP_IF_WIFI_STA
  • ESP_IF_WIFI_AP
  • ESP_IF_ETH
  • ESP_IF_MAX - invalid parameter
Parameters
  • dev: Implementation-specific TCP/IP stack interface pointer.

esp_err_t tcpip_adapter_get_sta_list(const wifi_sta_list_t *wifi_sta_list, tcpip_adapter_sta_list_t *tcpip_sta_list)

Get IP information for stations connected to the Wi-Fi AP interface.

Return
  • ESP_OK
  • ESP_ERR_TCPIP_ADAPTER_NO_MEM
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • wifi_sta_list: Wi-Fi station info list, returned from esp_wifi_ap_get_sta_list()
  • tcpip_sta_list: IP layer station info list, corresponding to MAC addresses provided in wifi_sta_list

esp_err_t tcpip_adapter_set_hostname(tcpip_adapter_if_t tcpip_if, const char *hostname)

Set the hostname of an interface.

Return
  • ESP_OK - success
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY - interface status error
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS - parameter error
Parameters
  • tcpip_if: Interface to set the hostname
  • hostname: New hostname for the interface. Maximum length 32 bytes.

esp_err_t tcpip_adapter_get_hostname(tcpip_adapter_if_t tcpip_if, const char **hostname)

Get interface hostname.

Return
  • ESP_OK - success
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY - interface status error
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS - parameter error
Parameters
  • tcpip_if: Interface to get the hostname
  • hostname: Returns a pointer to the hostname. May be NULL if no hostname is set. If set non-NULL, pointer remains valid (and string may change if the hostname changes).

esp_err_t tcpip_adapter_get_netif(tcpip_adapter_if_t tcpip_if, void **netif)

Get the TCP/IP stack-specific interface that is assigned to a given interface.

Note
For lwIP, this returns a pointer to a netif structure.
Return
  • ESP_OK - success
  • ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY - interface status error
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS - parameter error
Parameters
  • tcpip_if: Interface to get the implementation-specific interface
  • netif: Pointer to the implementation-specific interface

bool tcpip_adapter_is_netif_up(tcpip_adapter_if_t tcpip_if)

Test if supplied interface is up or down.

Return
  • true - Interface is up
  • false - Interface is down
Parameters
  • tcpip_if: Interface to test up/down status

Structures

struct tcpip_adapter_dns_info_t

DNS server info.

Public Members

ip_addr_t ip

IPV4 address of DNS server

Macros

ESP_ERR_TCPIP_ADAPTER_BASE
ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
ESP_ERR_TCPIP_ADAPTER_DHCPC_START_FAILED
ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STARTED
ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STOPPED
ESP_ERR_TCPIP_ADAPTER_NO_MEM
ESP_ERR_TCPIP_ADAPTER_DHCP_NOT_STOPPED
TCPIP_HOSTNAME_MAX_SIZE

Type Definitions

typedef tcpip_adapter_dhcp_option_mode_t tcpip_adapter_option_mode_t
typedef tcpip_adapter_dhcp_option_id_t tcpip_adapter_option_id_t

Enumerations

enum tcpip_adapter_if_t

Values:

TCPIP_ADAPTER_IF_STA = 0

Wi-Fi STA (station) interface

TCPIP_ADAPTER_IF_AP

Wi-Fi soft-AP interface

TCPIP_ADAPTER_IF_ETH

Ethernet interface

TCPIP_ADAPTER_IF_MAX
enum tcpip_adapter_dns_type_t

Type of DNS server.

Values:

TCPIP_ADAPTER_DNS_MAIN = 0

DNS main server address

TCPIP_ADAPTER_DNS_BACKUP

DNS backup server address (Wi-Fi STA and Ethernet only)

TCPIP_ADAPTER_DNS_FALLBACK

DNS fallback server address (Wi-Fi STA and Ethernet only)

TCPIP_ADAPTER_DNS_MAX
enum tcpip_adapter_dhcp_status_t

Status of DHCP client or DHCP server.

Values:

TCPIP_ADAPTER_DHCP_INIT = 0

DHCP client/server is in initial state (not yet started)

TCPIP_ADAPTER_DHCP_STARTED

DHCP client/server has been started

TCPIP_ADAPTER_DHCP_STOPPED

DHCP client/server has been stopped

TCPIP_ADAPTER_DHCP_STATUS_MAX
enum tcpip_adapter_dhcp_option_mode_t

Mode for DHCP client or DHCP server option functions.

Values:

TCPIP_ADAPTER_OP_START = 0
TCPIP_ADAPTER_OP_SET

Set option

TCPIP_ADAPTER_OP_GET

Get option

TCPIP_ADAPTER_OP_MAX
enum tcpip_adapter_dhcp_option_id_t

Supported options for DHCP client or DHCP server.

Values:

TCPIP_ADAPTER_DOMAIN_NAME_SERVER = 6

Domain name server

TCPIP_ADAPTER_ROUTER_SOLICITATION_ADDRESS = 32

Solicitation router address

TCPIP_ADAPTER_REQUESTED_IP_ADDRESS = 50

Request specific IP address

TCPIP_ADAPTER_IP_ADDRESS_LEASE_TIME = 51

Request IP address lease time

TCPIP_ADAPTER_IP_REQUEST_RETRY_TIME = 52

Request IP address retry counter