ESP-NETIF

The purpose of ESP-NETIF 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 ESP-NETIF for the lwIP TCP/IP stack only. However, the adapter itself is TCP/IP implementation agnostic and different implementations are possible.

Some ESP-NETIF 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 ESP-NETIF APIs directly as they are called from the default network event handlers.

ESP-NETIF component is a successor of the tcpip_adapter, former network interface abstraction, which has become deprecated since IDF v4.1. Please refer to the TCP/IP 适配器迁移指南 section in case existing applications to be ported to use the esp-netif API instead.

ESP-NETIF architecture

                 |          (A) USER CODE                 |
                 |                                        |
    .............| init          settings      events     |
    .            +----------------------------------------+
    .               .                |           *
    .               .                |           *
--------+        +===========================+   *     +-----------------------+
        |        | new/config     get/set    |   *     |                       |
        |        |                           |...*.....| init                  |
        |        |---------------------------|   *     |                       |
  init  |        |                           |****     |                       |
  start |********|  event handler            |*********|  DHCP                 |
  stop  |        |                           |         |                       |
        |        |---------------------------|         |                       |
        |        |                           |         |    NETIF              |
  +-----|        |                           |         +-----------------+     |
  | glue|----<---|  esp_netif_transmit       |--<------| netif_output    |     |
  |     |        |                           |         |                 |     |
  |     |---->---|  esp_netif_receive        |-->------| netif_input     |     |
  |     |        |                           |         + ----------------+     |
  |     |....<...|  esp_netif_free_rx_buffer |...<.....| packet buffer         |
  +-----|        |                           |         |                       |
        |        |                           |         |         (D)           |
  (B)   |        |          (C)              |         +-----------------------+
--------+        +===========================+
communication                                                NETWORK STACK
DRIVER                   ESP-NETIF

Data and event flow in the diagram

  • ........ Initialization line from user code to ESP-NETIF and communication driver

  • --<--->-- Data packets going from communication media to TCP/IP stack and back

  • ******** Events aggregated in ESP-NETIF propagates to driver, user code and network stack

  • | User settings and runtime configuration

ESP-NETIF interaction

A) User code, boiler plate

Overall application interaction with a specific IO driver for communication media and configured TCP/IP network stack is abstracted using ESP-NETIF APIs and outlined as below:

  1. Initialization code

  1. Initializes IO driver

  2. Creates a new instance of ESP-NETIF and configure with

  • ESP-NETIF specific options (flags, behaviour, name)

  • Network stack options (netif init and input functions, not publicly available)

  • IO driver specific options (transmit, free rx buffer functions, IO driver handle)

  1. Attaches the IO driver handle to the ESP-NETIF instance created in the above steps

  2. Configures event handlers

  • use default handlers for common interfaces defined in IO drivers; or define a specific handlers for customised behaviour/new interfaces

  • register handlers for app related events (such as IP lost/acquired)

  1. Interaction with network interfaces using ESP-NETIF API

  • Getting and setting TCP/IP related parameters (DHCP, IP, etc)

  • Receiving IP events (connect/disconnect)

  • Controlling application lifecycle (set interface up/down)

B) Communication driver, IO driver, media driver

Communication driver plays these two important roles in relation with ESP-NETIF:

  1. Event handlers: Define behaviour patterns of interaction with ESP-NETIF (for example: ethernet link-up -> turn netif on)

  2. Glue IO layer: Adapts the input/output functions to use ESP-NETIF transmit, receive and free receive buffer

  • Installs driver_transmit to appropriate ESP-NETIF object, so that outgoing packets from network stack are passed to the IO driver

  • Calls esp_netif_receive() to pass incoming data to network stack

C) ESP-NETIF, former tcpip_adapter

ESP-NETIF is an intermediary between an IO driver and a network stack, connecting packet data path between these two. As that it provides a set of interfaces for attaching a driver to ESP-NETIF object (runtime) and configuring a network stack (compile time). In addition to that a set of API is provided to control network interface lifecycle and its TCP/IP properties. As an overview, the ESP-NETIF public interface could be divided into these 6 groups:

  1. Initialization APIs (to create and configure ESP-NETIF instance)

  2. Input/Output API (for passing data between IO driver and network stack)

  3. Event or Action API

  • Used for network interface lifecycle management

  • ESP-NETIF provides building blocks for designing event handlers

  1. Setters and Getters for basic network interface properties

  2. Network stack abstraction: enabling user interaction with TCP/IP stack

  • Set interface up or down

  • DHCP server and client API

  • DNS API

  1. Driver conversion utilities

D) Network stack

Network stack has no public interaction with application code with regard to public interfaces and shall be fully abstracted by ESP-NETIF API.

ESP-NETIF programmer’s manual

Please refer to the example section for basic initialization of default interfaces:

For more specific cases please consult this guide: ESP-NETIF Custom I/O Driver.

WiFi default initialization

The initialization code as well as registering event handlers for default interfaces, such as softAP and station, are provided in two separate APIs to facilitate simple startup code for most applications:

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 as a consequence, means that:

  • The created object has to be destroyed if a network de-initialization is provided by an application using esp_netif_destroy_default_wifi().

  • These default interfaces must not be created multiple times, unless the created handle is deleted using esp_netif_destroy().

  • When using Wifi in AP+STA mode, both these interfaces has to be created.

API Reference

Functions

esp_err_t esp_netif_init(void)

Initialize the underlying TCP/IP stack.

备注

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

返回

  • ESP_OK on success

  • ESP_FAIL if initializing failed

esp_err_t esp_netif_deinit(void)

Deinitialize the esp-netif component (and the underlying TCP/IP stack)

Note: Deinitialization is not supported yet

返回

  • ESP_ERR_INVALID_STATE if esp_netif not initialized

  • ESP_ERR_NOT_SUPPORTED otherwise

esp_netif_t *esp_netif_new(const esp_netif_config_t *esp_netif_config)

Creates an instance of new esp-netif object based on provided config.

参数

esp_netif_config[in] pointer esp-netif configuration

返回

  • pointer to esp-netif object on success

  • NULL otherwise

void esp_netif_destroy(esp_netif_t *esp_netif)

Destroys the esp_netif object.

参数

esp_netif[in] pointer to the object to be deleted

esp_err_t esp_netif_set_driver_config(esp_netif_t *esp_netif, const esp_netif_driver_ifconfig_t *driver_config)

Configures driver related options of esp_netif object.

参数
  • esp_netif[inout] pointer to the object to be configured

  • driver_config[in] pointer esp-netif io driver related configuration

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS if invalid parameters provided

esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle)

Attaches esp_netif instance to the io driver handle.

Calling this function enables connecting specific esp_netif object with already initialized io driver to update esp_netif object with driver specific configuration (i.e. calls post_attach callback, which typically sets io driver callbacks to esp_netif instance and starts the driver)

参数
  • esp_netif[inout] pointer to esp_netif object to be attached

  • driver_handle[in] pointer to the driver handle

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED if driver’s pot_attach callback failed

esp_err_t esp_netif_receive(esp_netif_t *esp_netif, void *buffer, size_t len, void *eb)

Passes the raw packets from communication media to the appropriate TCP/IP stack.

This function is called from the configured (peripheral) driver layer. The data are then forwarded as frames to the TCP/IP stack.

参数
  • esp_netif[in] Handle to esp-netif instance

  • buffer[in] Received data

  • len[in] Length of the data frame

  • eb[in] Pointer to internal buffer (used in Wi-Fi driver)

返回

  • ESP_OK

void esp_netif_action_start(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver start event Creates network interface, if AUTOUP enabled turns the interface on, if DHCPS enabled starts dhcp server.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_stop(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver stop event.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_connected(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver connected event.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_disconnected(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver disconnected event.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_got_ip(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon network got IP event.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_join_ip6_multicast_group(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 multicast group join.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_leave_ip6_multicast_group(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 multicast group leave.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_add_ip6_address(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 address added by the underlying stack.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

void esp_netif_action_remove_ip6_address(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 address removed by the underlying stack.

备注

This API can be directly used as event handler

参数
  • esp_netif[in] Handle to esp-netif instance

  • base

  • event_id

  • data

esp_err_t esp_netif_set_mac(esp_netif_t *esp_netif, uint8_t mac[])

Set the mac address for the interface instance.

参数
  • esp_netif[in] Handle to esp-netif instance

  • mac[in] Desired mac address for the related network interface

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_NOT_SUPPORTED - mac not supported on this interface

esp_err_t esp_netif_get_mac(esp_netif_t *esp_netif, uint8_t mac[])

Get the mac address for the interface instance.

参数
  • esp_netif[in] Handle to esp-netif instance

  • mac[out] Resultant mac address for the related network interface

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_NOT_SUPPORTED - mac not supported on this interface

esp_err_t esp_netif_set_hostname(esp_netif_t *esp_netif, const char *hostname)

Set the hostname of an interface.

The configured hostname overrides the default configuration value CONFIG_LWIP_LOCAL_HOSTNAME. Please note that when the hostname is altered after interface started/connected the changes would only be reflected once the interface restarts/reconnects

参数
  • esp_netif[in] Handle to esp-netif instance

  • hostname[in] New hostname for the interface. Maximum length 32 bytes.

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error

esp_err_t esp_netif_get_hostname(esp_netif_t *esp_netif, const char **hostname)

Get interface hostname.

参数
  • esp_netif[in] Handle to esp-netif instance

  • hostname[out] 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_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error

bool esp_netif_is_netif_up(esp_netif_t *esp_netif)

Test if supplied interface is up or down.

参数

esp_netif[in] Handle to esp-netif instance

返回

  • true - Interface is up

  • false - Interface is down

esp_err_t esp_netif_get_ip_info(esp_netif_t *esp_netif, esp_netif_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 ESP-NETIF instance

参数
  • esp_netif[in] Handle to esp-netif instance

  • ip_info[out] If successful, IP information will be returned in this argument.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_get_old_ip_info(esp_netif_t *esp_netif, esp_netif_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.

参数
  • esp_netif[in] Handle to esp-netif instance

  • ip_info[out] If successful, IP information will be returned in this argument.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_set_ip_info(esp_netif_t *esp_netif, const esp_netif_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 ESP-NETIF instance is also updated (this copy is returned if the IP is queried while the interface is still down.)

备注

DHCP client/server must be stopped (if enabled for this interface) before setting new IP information.

备注

Calling this interface for may generate a SYSTEM_EVENT_STA_GOT_IP or SYSTEM_EVENT_ETH_GOT_IP event.

参数
  • esp_netif[in] Handle to esp-netif instance

  • ip_info[in] IP information to set on the specified interface

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED If DHCP server or client is still running

esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info)

Set interface old IP information.

This function is called from the DHCP client (if enabled), 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.

参数
  • esp_netif[in] Handle to esp-netif instance

  • ip_info[in] Store the old IP information for the specified interface

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

int esp_netif_get_netif_impl_index(esp_netif_t *esp_netif)

Get net interface index from network stack implementation.

备注

This index could be used in setsockopt() to bind socket with multicast interface

参数

esp_netif[in] Handle to esp-netif instance

返回

implementation specific index of interface represented with supplied esp_netif

esp_err_t esp_netif_get_netif_impl_name(esp_netif_t *esp_netif, char *name)

Get net interface name from network stack implementation.

备注

This name could be used in setsockopt() to bind socket with appropriate interface

参数
  • esp_netif[in] Handle to esp-netif instance

  • name[out] Interface name as specified in underlying TCP/IP stack. Note that the actual name will be copied to the specified buffer, which must be allocated to hold maximum interface name size (6 characters for lwIP)

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_dhcps_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op, esp_netif_dhcp_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP server option.

参数
  • esp_netif[in] Handle to esp-netif instance

  • opt_op[in] ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.

  • opt_id[in] Option index to get or set, must be one of the supported enum values.

  • opt_val[inout] Pointer to the option parameter.

  • opt_len[in] Length of the option parameter.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

esp_err_t esp_netif_dhcpc_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op, esp_netif_dhcp_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP client option.

参数
  • esp_netif[in] Handle to esp-netif instance

  • opt_op[in] ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.

  • opt_id[in] Option index to get or set, must be one of the supported enum values.

  • opt_val[inout] Pointer to the option parameter.

  • opt_len[in] Length of the option parameter.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

esp_err_t esp_netif_dhcpc_start(esp_netif_t *esp_netif)

Start DHCP client (only if enabled in interface object)

备注

The default event handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events call this function.

参数

esp_netif[in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

  • ESP_ERR_ESP_NETIF_DHCPC_START_FAILED

esp_err_t esp_netif_dhcpc_stop(esp_netif_t *esp_netif)

Stop DHCP client (only if enabled in interface object)

备注

Calling action_netif_stop() will also stop the DHCP Client if it is running.

参数

esp_netif[in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_IF_NOT_READY

esp_err_t esp_netif_dhcpc_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status)

Get DHCP client status.

参数
  • esp_netif[in] Handle to esp-netif instance

  • status[out] If successful, the status of DHCP client will be returned in this argument.

返回

  • ESP_OK

esp_err_t esp_netif_dhcps_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status)

Get DHCP Server status.

参数
  • esp_netif[in] Handle to esp-netif instance

  • status[out] If successful, the status of the DHCP server will be returned in this argument.

返回

  • ESP_OK

esp_err_t esp_netif_dhcps_start(esp_netif_t *esp_netif)

Start DHCP server (only if enabled in interface object)

参数

esp_netif[in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

esp_err_t esp_netif_dhcps_stop(esp_netif_t *esp_netif)

Stop DHCP server (only if enabled in interface object)

参数

esp_netif[in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_IF_NOT_READY

esp_err_t esp_netif_set_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type, esp_netif_dns_info_t *dns)

Set DNS Server information.

This function behaves differently if DHCP server or client is enabled

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.

If DHCP server is enabled, 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 typically the IP of the DHCP server itself.

  • This function can override it by setting server type ESP_NETIF_DNS_MAIN.

  • Other DNS Server types are not supported for the DHCP server.

  • To propagate the DNS info to client, please stop the DHCP server before using this API.

参数
  • esp_netif[in] Handle to esp-netif instance

  • type[in] Type of DNS Server to set: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK

  • dns[in] DNS Server address to set

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params

esp_err_t esp_netif_get_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type, esp_netif_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 esp_netif_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.

参数
  • esp_netif[in] Handle to esp-netif instance

  • type[in] Type of DNS Server to get: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK

  • dns[out] DNS Server result is written here on success

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params

esp_err_t esp_netif_create_ip6_linklocal(esp_netif_t *esp_netif)

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.

参数

esp_netif[in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_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.

参数
  • esp_netif[in] Handle to esp-netif instance

  • if_ip6[out] IPv6 information will be returned in this argument if successful.

返回

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

esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_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.

参数
  • esp_netif[in] Handle to esp-netif instance

  • if_ip6[out] IPv6 information will be returned in this argument if successful.

返回

  • ESP_OK

  • ESP_FAIL If interface is down, does not have a global IPv6 address, or the global IPv6 address is not a preferred address.

int esp_netif_get_all_ip6(esp_netif_t *esp_netif, esp_ip6_addr_t if_ip6[])

Get all IPv6 addresses of the specified interface.

参数
  • esp_netif[in] Handle to esp-netif instance

  • if_ip6[out] Array of IPv6 addresses will be copied to the argument

返回

number of returned IPv6 addresses

void esp_netif_set_ip4_addr(esp_ip4_addr_t *addr, uint8_t a, uint8_t b, uint8_t c, uint8_t d)

Sets IPv4 address to the specified octets.

参数
  • addr[out] IP address to be set

  • a – the first octet (127 for IP 127.0.0.1)

  • b

  • c

  • d

char *esp_ip4addr_ntoa(const esp_ip4_addr_t *addr, char *buf, int buflen)

Converts numeric IP address into decimal dotted ASCII representation.

参数
  • addr – ip address in network order to convert

  • buf – target buffer where the string is stored

  • buflen – length of buf

返回

either pointer to buf which now holds the ASCII representation of addr or NULL if buf was too small

uint32_t esp_ip4addr_aton(const char *addr)

Ascii internet address interpretation routine The value returned is in network order.

参数

addr – IP address in ascii representation (e.g. “127.0.0.1”)

返回

ip address in network order

esp_err_t esp_netif_str_to_ip4(const char *src, esp_ip4_addr_t *dst)

Converts Ascii internet IPv4 address into esp_ip4_addr_t.

参数
  • src[in] IPv4 address in ascii representation (e.g. “127.0.0.1”)

  • dst[out] Address of the target esp_ip4_addr_t structure to receive converted address

返回

  • ESP_OK on success

  • ESP_FAIL if conversion failed

  • ESP_ERR_INVALID_ARG if invalid parameter is passed into

esp_err_t esp_netif_str_to_ip6(const char *src, esp_ip6_addr_t *dst)

Converts Ascii internet IPv6 address into esp_ip4_addr_t Zeros in the IP address can be stripped or completely ommited: “2001:db8:85a3:0:0:0:2:1” or “2001:db8::2:1”)

参数
  • src[in] IPv6 address in ascii representation (e.g. “”2001:0db8:85a3:0000:0000:0000:0002:0001”)

  • dst[out] Address of the target esp_ip6_addr_t structure to receive converted address

返回

  • ESP_OK on success

  • ESP_FAIL if conversion failed

  • ESP_ERR_INVALID_ARG if invalid parameter is passed into

esp_netif_iodriver_handle esp_netif_get_io_driver(esp_netif_t *esp_netif)

Gets media driver handle for this esp-netif instance.

参数

esp_netif[in] Handle to esp-netif instance

返回

opaque pointer of related IO driver

esp_netif_t *esp_netif_get_handle_from_ifkey(const char *if_key)

Searches over a list of created objects to find an instance with supplied if key.

参数

if_key – Textual description of network interface

返回

Handle to esp-netif instance

esp_netif_flags_t esp_netif_get_flags(esp_netif_t *esp_netif)

Returns configured flags for this interface.

参数

esp_netif[in] Handle to esp-netif instance

返回

Configuration flags

const char *esp_netif_get_ifkey(esp_netif_t *esp_netif)

Returns configured interface key for this esp-netif instance.

参数

esp_netif[in] Handle to esp-netif instance

返回

Textual description of related interface

const char *esp_netif_get_desc(esp_netif_t *esp_netif)

Returns configured interface type for this esp-netif instance.

参数

esp_netif[in] Handle to esp-netif instance

返回

Enumerated type of this interface, such as station, AP, ethernet

int esp_netif_get_route_prio(esp_netif_t *esp_netif)

Returns configured routing priority number.

参数

esp_netif[in] Handle to esp-netif instance

返回

Integer representing the instance’s route-prio, or -1 if invalid paramters

int32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_t event_type)

Returns configured event for this esp-netif instance and supplied event type.

参数
  • esp_netif[in] Handle to esp-netif instance

  • event_type – (either get or lost IP)

返回

specific event id which is configured to be raised if the interface lost or acquired IP address -1 if supplied event_type is not known

esp_netif_t *esp_netif_next(esp_netif_t *esp_netif)

Iterates over list of interfaces. Returns first netif if NULL given as parameter.

参数

esp_netif[in] Handle to esp-netif instance

返回

First netif from the list if supplied parameter is NULL, next one otherwise

size_t esp_netif_get_nr_of_ifs(void)

Returns number of registered esp_netif objects.

返回

Number of esp_netifs

void esp_netif_netstack_buf_ref(void *netstack_buf)

increase the reference counter of net stack buffer

参数

netstack_buf[in] the net stack buffer

void esp_netif_netstack_buf_free(void *netstack_buf)

free the netstack buffer

参数

netstack_buf[in] the net stack buffer

esp_err_t esp_netif_tcpip_exec(esp_netif_callback_fn fn, void *ctx)

Utility to execute the supplied callback in TCP/IP context.

参数
  • fn – Pointer to the callback

  • ctx – Parameter to the callback

返回

The error code (esp_err_t) returned by the callback

Macros

_ESP_NETIF_SUPPRESS_LEGACY_WARNING_

Type Definitions

typedef esp_err_t (*esp_netif_callback_fn)(void *ctx)

TCPIP thread safe callback used with esp_netif_tcpip_exec()

WiFi default API reference

Functions

esp_err_t esp_netif_attach_wifi_station(esp_netif_t *esp_netif)

Attaches wifi station interface to supplied netif.

参数

esp_netif – instance to attach the wifi station to

返回

  • ESP_OK on success

  • ESP_FAIL if attach failed

esp_err_t esp_netif_attach_wifi_ap(esp_netif_t *esp_netif)

Attaches wifi soft AP interface to supplied netif.

参数

esp_netif – instance to attach the wifi AP to

返回

  • ESP_OK on success

  • ESP_FAIL if attach failed

esp_err_t esp_wifi_set_default_wifi_sta_handlers(void)

Sets default wifi event handlers for STA interface.

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_err_t esp_wifi_set_default_wifi_ap_handlers(void)

Sets default wifi event handlers for AP interface.

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_err_t esp_wifi_clear_default_wifi_driver_and_handlers(void *esp_netif)

Clears default wifi event handlers for supplied network interface.

参数

esp_netif – instance of corresponding if object

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_netif_t *esp_netif_create_default_wifi_ap(void)

Creates default WIFI AP. In case of any init error this API aborts.

备注

The API creates esp_netif object with default WiFi access point config, attaches the netif to wifi and registers default wifi handlers.

返回

pointer to esp-netif instance

esp_netif_t *esp_netif_create_default_wifi_sta(void)

Creates default WIFI STA. In case of any init error this API aborts.

备注

The API creates esp_netif object with default WiFi station config, attaches the netif to wifi and registers default wifi handlers.

返回

pointer to esp-netif instance

void esp_netif_destroy_default_wifi(void *esp_netif)

Destroys default WIFI netif created with esp_netif_create_default_wifi_…() API.

备注

This API unregisters wifi handlers and detaches the created object from the wifi. (this function is a no-operation if esp_netif is NULL)

参数

esp_netif[in] object to detach from WiFi and destroy

esp_netif_t *esp_netif_create_wifi(wifi_interface_t wifi_if, esp_netif_inherent_config_t *esp_netif_config)

Creates esp_netif WiFi object based on the custom configuration.

Attention

This API DOES NOT register default handlers!

参数
  • wifi_if[in] type of wifi interface

  • esp_netif_config[in] inherent esp-netif configuration pointer

返回

pointer to esp-netif instance

esp_err_t esp_netif_create_default_wifi_mesh_netifs(esp_netif_t **p_netif_sta, esp_netif_t **p_netif_ap)

Creates default STA and AP network interfaces for esp-mesh.

Both netifs are almost identical to the default station and softAP, but with DHCP client and server disabled. Please note that the DHCP client is typically enabled only if the device is promoted to a root node.

Returns created interfaces which could be ignored setting parameters to NULL if an application code does not need to save the interface instances for further processing.

参数
  • p_netif_sta[out] pointer where the resultant STA interface is saved (if non NULL)

  • p_netif_ap[out] pointer where the resultant AP interface is saved (if non NULL)

返回

ESP_OK on success