TCPIP Adapter

API Reference

Functions

void tcpip_adapter_init(void)

Initialize tcpip adapter.

This will initialize TCPIP stack inside.

esp_err_t tcpip_adapter_start(tcpip_adapter_if_t tcpip_if, uint8_t *mac, tcpip_adapter_ip_info_t *ip_info)

Start the Wi-Fi station/AP interface with specific MAC and IP.

Station/AP interface will be initialized, connect WiFi stack with TCPIP stack.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS ESP_ERR_NO_MEM
Parameters
  • tcpip_if: Station/AP interface
  • 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)

Stop an interface.

The interface will be cleanup in this API, if DHCP server/client are started, will be stopped.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: the interface which will be started

esp_err_t tcpip_adapter_up(tcpip_adapter_if_t tcpip_if)

Bring up an interface.

Only station interface need to be brought up, since station interface will be shut down when disconnect.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: the interface which will be up

esp_err_t tcpip_adapter_down(tcpip_adapter_if_t tcpip_if)

Shut down an interface.

Only station interface need to be shut down, since station interface will be brought up when connect.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: the interface which will be down

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 information.

There has an IP information copy in adapter library, if interface is up, get IP information from interface, otherwise get from copy.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: the interface which we want 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, tcpip_adapter_ip_info_t *ip_info)

Set interface’s IP information.

There has an IP information copy in adapter library, if interface is up, also set interface’s IP. DHCP client/server should be stopped before set new IP information.

This function is mainly used for setting static IP.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: the interface which we want to set IP information
  • ip_info: store the IP information which needs to be set to 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’s information.

There has an DNS Server information copy in adapter library, set DNS Server for appointed interface and type.

1.In station mode, if dhcp client is enabled, then only the fallback DNS server can be set(TCPIP_ADAPTER_DNS_FALLBACK). Fallback DNS server is only used if no DNS servers are set via DHCP. If dhcp client is disabled, then need to set main/backup dns server(TCPIP_ADAPTER_DNS_MAIN, TCPIP_ADAPTER_DNS_BACKUP).

2.In soft-AP mode, the DNS Server’s main dns server offered to the station is the IP address of soft-AP, if the application don’t want to use the IP address of soft-AP, they can set the main dns server.

This function is mainly used for setting static or Fallback DNS Server.

Return
  • ESP_OK on success
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS invalid params
Parameters
  • tcpip_if: the interface which we want to set DNS Server information
  • type: the type of DNS Server,including TCPIP_ADAPTER_DNS_MAIN, TCPIP_ADAPTER_DNS_BACKUP, TCPIP_ADAPTER_DNS_FALLBACK
  • dns: the DNS Server address to be 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’s information.

When set the DNS Server information successfully, can get the DNS Server’s information via the appointed tcpip_if and type

This function is mainly used for getting DNS Server information.

Return
  • ESP_OK on success
  • ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS invalid params
Parameters
  • tcpip_if: the interface which we want to get DNS Server information
  • type: the type of DNS Server,including TCPIP_ADAPTER_DNS_MAIN, TCPIP_ADAPTER_DNS_BACKUP, TCPIP_ADAPTER_DNS_FALLBACK
  • dns: the DNS Server address to be get

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.

When the interface successfully gets a valid IP from DHCP server or static configured, a copy of the IP information is set to the old IP information. When IP lost timer expires, the old IP information is reset to 0.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: the interface which we want 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, tcpip_adapter_ip_info_t *ip_info)

Set interface’s old IP information.

When the interface successfully gets a valid IP from DHCP server or static configured, a copy of the IP information is set to the old IP information. When IP lost timer expires, the old IP information is reset to 0.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: the interface which we want to set old IP information
  • ip_info: store the IP information which needs to be set to specified interface

esp_err_t tcpip_adapter_create_ip6_linklocal(tcpip_adapter_if_t tcpip_if)

create interface’s linklocal IPv6 information

Note
this function will create a linklocal IPv6 address about input interface, if this address status changed to preferred, will call event call back , notify user linklocal IPv6 address has been verified
Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • tcpip_if: the interface which we want to set IP information

esp_err_t tcpip_adapter_dhcps_get_status(tcpip_adapter_if_t tcpip_if, tcpip_adapter_dhcp_status_t *status)

Get DHCP server’s status.

Return
ESP_OK
Parameters
  • tcpip_if: the interface which we will get status of DHCP server
  • status: If successful, the status of DHCP server will be return in this argument.

esp_err_t tcpip_adapter_dhcps_option(tcpip_adapter_option_mode_t opt_op, tcpip_adapter_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP server’s 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: option operate type, 1 for SET, 2 for GET.
  • opt_id: option index, 32 for ROUTER, 50 for IP POLL, 51 for LEASE TIME, 52 for REQUEST TIME
  • opt_val: option parameter
  • opt_len: option length

esp_err_t tcpip_adapter_dhcps_start(tcpip_adapter_if_t tcpip_if)

Start DHCP server.

Note
Currently DHCP server is bind to softAP interface.
Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STARTED
Parameters
  • tcpip_if: the interface which we will start DHCP server

esp_err_t tcpip_adapter_dhcps_stop(tcpip_adapter_if_t tcpip_if)

Stop DHCP server.

Note
Currently DHCP server is bind to softAP interface.
Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STOPED ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: the interface which we will stop DHCP server

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: the interface which we will get status of DHCP client
  • status: If successful, the status of DHCP client will be return in this argument.

esp_err_t tcpip_adapter_dhcpc_option(tcpip_adapter_option_mode_t opt_op, tcpip_adapter_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP client’s option.

Note
This function is not implement now.
Return
ESP_OK
Parameters
  • opt_op: option operate type, 1 for SET, 2 for GET.
  • opt_id: option index, 32 for ROUTER, 50 for IP POLL, 51 for LEASE TIME, 52 for REQUEST TIME
  • opt_val: option parameter
  • opt_len: option length

esp_err_t tcpip_adapter_dhcpc_start(tcpip_adapter_if_t tcpip_if)

Start DHCP client.

Note
Currently DHCP client is bind to station interface.
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: the interface which we will start DHCP client

esp_err_t tcpip_adapter_dhcpc_stop(tcpip_adapter_if_t tcpip_if)

Stop DHCP client.

Note
Currently DHCP client is bind to station interface.
Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS ESP_ERR_TCPIP_ADAPTER_DHCP_ALREADY_STOPED ESP_ERR_TCPIP_ADAPTER_IF_NOT_READY
Parameters
  • tcpip_if: the interface which we will stop DHCP client

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

Get data from station interface.

This function should be installed by esp_wifi_reg_rxcb, so WiFi packets will be forward to TCPIP stack.

Return
ESP_OK
Parameters
  • buffer: the received data point
  • len: the received data length
  • eb: parameter

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

Get data from softAP interface.

This function should be installed by esp_wifi_reg_rxcb, so WiFi packets will be forward to TCPIP stack.

Return
ESP_OK
Parameters
  • buffer: the received data point
  • len: the received data length
  • eb: parameter

esp_interface_t tcpip_adapter_get_esp_if(void *dev)

Get WiFi interface index.

Get WiFi interface from TCPIP interface struct pointer.

Return
ESP_IF_WIFI_STA ESP_IF_WIFI_AP ESP_IF_ETH ESP_IF_MAX
Parameters
  • dev: adapter interface

esp_err_t tcpip_adapter_get_sta_list(wifi_sta_list_t *wifi_sta_list, tcpip_adapter_sta_list_t *tcpip_sta_list)

Get the station information list.

Return
ESP_OK ESP_ERR_TCPIP_ADAPTER_NO_MEM ESP_ERR_TCPIP_ADAPTER_INVALID_PARAMS
Parameters
  • wifi_sta_list: station list info
  • tcpip_sta_list: station list info

esp_err_t tcpip_adapter_set_hostname(tcpip_adapter_if_t tcpip_if, const char *hostname)

Set the hostname to the 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: the interface which we will set the hostname
  • hostname: the host name for set the interface, the max length of hostname is 32 bytes

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

Get the hostname from the 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: the interface which we will get the hostname
  • hostname: the host name from the interface

esp_err_t tcpip_adapter_get_netif(tcpip_adapter_if_t tcpip_if, void **netif)

Get the LwIP netif* that is assigned to the 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: the interface which we will get the hostname
  • netif: pointer to fill the resulting interface

bool tcpip_adapter_is_netif_up(tcpip_adapter_if_t tcpip_if)

Test if supplied interface is up or down.

Return
true: tcpip_if is UP false: tcpip_if id DOWN
Parameters
  • tcpip_if: the interface which we will get the hostname

esp_err_t tcpip_adapter_set_default_wifi_handlers()

Install default event handlers for Wi-Fi interfaces (station and AP)

Return
  • ESP_OK on success
  • one of the errors from esp_event on failure

esp_err_t tcpip_adapter_clear_default_wifi_handlers()

Uninstall default event handlers for Wi-Fi interfaces (station and AP)

Return
  • ESP_OK on success
  • one of the errors from esp_event on failure

int tcpip_adapter_get_netif_index(tcpip_adapter_if_t tcpip_if)

Search nefit index through netif interface.

Return
  • netif_index on success
  • -1 if an invalid parameter is supplied
Parameters
  • tcpip_if: Interface to search for netif index

Structures

struct tcpip_adapter_ip_info_t

TCP-IP adapter IPV4 address information.

Public Members

ip4_addr_t ip

TCP-IP adatpter IPV4 addresss

ip4_addr_t netmask

TCP-IP adatpter IPV4 netmask

ip4_addr_t gw

TCP-IP adatpter IPV4 gateway

struct tcpip_adapter_ip6_info_t

TCP-IP adapter IPV6 address information if disable IPV6 of LwIP.

Public Members

uint32_t addr[4]

TCP-IP adatpter IPV4 addresss data

struct tcpip_adapter_ip6_info_t::[anonymous] ip

TCP-IP adatpter IPV4 addresss

struct tcpip_adapter_sta_info_t

TCP-IP adapter station information.

Public Members

uint8_t mac[6]

TCP-IP adatpter station MAC address

ip4_addr_t ip

TCP-IP adatpter station IPV4 addresss

struct tcpip_adapter_sta_list_t

TCP-IP adapter station information table.

Public Members

tcpip_adapter_sta_info_t sta[ESP_WIFI_MAX_CONN_NUM]

adapter station information array

int num

adapter station information number

struct tcpip_adapter_dns_info_t

TCP-IP adapter DNS server information.

Public Members

ip_addr_t ip

DNS IP addresss

struct ip_event_ap_staipassigned_t

Event structure for IP_EVENT_AP_STAIPASSIGNED event

Public Members

ip4_addr_t ip

IP address which was assigned to the station

struct ip_event_got_ip_t

Event structure for IP_EVENT_STA_GOT_IP, IP_EVENT_ETH_GOT_IP events

Public Members

tcpip_adapter_if_t if_index

Interface for which the event is received

tcpip_adapter_ip_info_t ip_info

IP address, netmask, gatway IP address

bool ip_changed

Whether the assigned IP has changed or not

struct ip_event_got_ip6_t

Event structure for IP_EVENT_GOT_IP6 event

Public Members

tcpip_adapter_if_t if_index

Interface for which the event is received

tcpip_adapter_ip6_info_t ip6_info

IPv6 address of the interface

struct tcpip_adapter_api_msg_s

TCP-IP adapter async messsage.

Public Members

int type

TCP-IP adatpter API message type

int ret

TCP-IP adatpter API message process result

tcpip_adapter_api_fn api_fn

TCP-IP adatpter API message function

tcpip_adapter_if_t tcpip_if

TCP-IP adatpter API message interface type

tcpip_adapter_ip_info_t *ip_info

TCP-IP adatpter API message IP information

uint8_t *mac

TCP-IP adatpter API message MAC address

void *data

TCP-IP adatpter API message MAC private data

struct tcpip_adapter_dns_param_s

TCP-IP adapter DNS parameters.

Public Members

tcpip_adapter_dns_type_t dns_type

DNS type

tcpip_adapter_dns_info_t *dns_info

DNS information

struct tcpip_adatper_ip_lost_timer_s

TCP-IP adapter IP lost checking timer.

Public Members

bool timer_running

check if the timer if running

Macros

CONFIG_TCPIP_LWIP

TCPIP adapter library.

The aim of this adapter is to provide an abstract layer upon TCPIP stack. With this layer, switch to other TCPIP stack is possible and easy in ESP8266_RTOS_SDK.

If users want to use other TCPIP stack, all those functions should be implemented by using the specific APIs of that stack.

tcpip_adapter_init should be called in the start of app_main for only once.

Currently most adapter APIs are called in event_default_handlers.c.

We recommend users only use set/get IP APIs, DHCP server/client APIs, get free station list APIs in application side. Other APIs are used in ESP8266_RTOS_SDK internal, otherwise the state maybe wrong.

TODO: ipv6 support will be added, use menuconfig to disable CONFIG_TCPIP_LWIP

CONFIG_DHCP_STA_LIST
TCPIP_ADAPTER_IPV6
IP2STR(ipaddr)
IPSTR
IPV62STR(ipaddr)
IPV6STR
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_ADAPTER_TRHEAD_SAFE
TCPIP_ADAPTER_IPC_LOCAL
TCPIP_ADAPTER_IPC_REMOTE
TCPIP_HOSTNAME_MAX_SIZE

Type Definitions

typedef dhcps_lease_t tcpip_adapter_dhcps_lease_t
typedef int (*tcpip_adapter_api_fn)(struct tcpip_adapter_api_msg_s *msg)
typedef struct tcpip_adapter_api_msg_s tcpip_adapter_api_msg_t

TCP-IP adapter async messsage.

typedef struct tcpip_adapter_dns_param_s tcpip_adapter_dns_param_t

TCP-IP adapter DNS parameters.

typedef struct tcpip_adatper_ip_lost_timer_s tcpip_adapter_ip_lost_timer_t

TCP-IP adapter IP lost checking timer.

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_TEST

tcpip stack test interface

TCPIP_ADAPTER_IF_MAX
enum tcpip_adapter_dns_type_t

Values:

TCPIP_ADAPTER_DNS_MAIN = 0
TCPIP_ADAPTER_DNS_BACKUP

DNS main server address

TCPIP_ADAPTER_DNS_FALLBACK

DNS backup server address,for STA only,support soft-AP in future

TCPIP_ADAPTER_DNS_MAX

DNS fallback server address,for STA only Max DNS

enum tcpip_adapter_dhcp_status_t

Values:

TCPIP_ADAPTER_DHCP_INIT = 0

DHCP client/server in initial state

TCPIP_ADAPTER_DHCP_STARTED

DHCP client/server already been started

TCPIP_ADAPTER_DHCP_STOPPED

DHCP client/server already been stopped

TCPIP_ADAPTER_DHCP_STATUS_MAX
enum tcpip_adapter_option_mode_t

Values:

TCPIP_ADAPTER_OP_START = 0
TCPIP_ADAPTER_OP_SET

set option mode

TCPIP_ADAPTER_OP_GET

get option mode

TCPIP_ADAPTER_OP_MAX
enum tcpip_adapter_option_id_t

Values:

TCPIP_ADAPTER_SUBNET_MASK = 1

network mask

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 IP address pool

TCPIP_ADAPTER_IP_ADDRESS_LEASE_TIME = 51

request IP address lease time

TCPIP_ADAPTER_IP_REQUEST_RETRY_TIME = 52

request IP address retry counter

enum ip_event_t

IP event declarations

Values:

IP_EVENT_STA_GOT_IP

station got IP from connected AP

IP_EVENT_STA_LOST_IP

station lost IP and the IP is reset to 0

IP_EVENT_AP_STAIPASSIGNED

soft-AP assign an IP to a connected station

IP_EVENT_GOT_IP6

station or ap or ethernet interface v6IP addr is preferred