ESP-NETIF Печать
Добавил(а) microsin   

Библиотека ESP-NETIF предназначена для решения двух задач:

• Предоставить слой абстракции для приложений, работающих поверх стека TCP/IP. Это позволит приложениям в будущем выбирать между стеками IP.
• Предоставить потокобезопасное API (thread-safe), даже если нижележащий API-стек TCP/IP не является потокобезопасным.

В настоящее время (на момент перевода документации [1], версия ESP-IDF v5.0.1) система разработки ESP-IDF реализует ESP-NETIF только для API-стека lwIP TCP/IP. Однако адаптер сам по себе не привязан к конкретной реализации TCP/IP, и позволяет использовать различные реализации.

Также можно применять пользовательский стек TCP/IP с ESP-IDF при условии, что он реализует BSD API. Дополнительную информацию о создании ESP-IDF без lwIP см. components/esp_netif_stack/README.md.

Некоторые API-функции ESP-NETIF предназначены для вызова из кода приложения. Например, чтобы получить или установить интерфейс IP-адресов и конфигурировать DHCP. Другие функции предназначены для внутреннего использования слоем сетевого драйвера ESP-IDF.

Во многих случаях приложениям не нужно напрямую вызывать API-функции ESP-NETIF, поскольку они вызываются обработчиками по умолчанию для сетевых событий (default network event handlers).

Архитектура библиотеки ESP-NETIF:

                       |          (A) КОД ПОЛЬЗОВАТЕЛЯ          |
                       |                 Apps                   |
      .................| init          settings      events     |
      .                +----------------------------------------+
      .                   .                |           *
      .                   .                |           *
  --------+            +===========================+   *     +-----------------------+
          |            | new/config   get/set/apps |   *     | init                  |
          |            |                           |...*.....| Apps (DHCP, SNTP)     |
          |            |---------------------------|   *     |                       |
    init  |            |                           |****     |                       |
    start |************|  event handler            |*********|  DHCP                 |
    stop  |            |                           |         |                       |
          |            |---------------------------|         |                       |
          |            |                           |         |    NETIF              |
    +-----|            |                           |         +-----------------+     |
    | glue|---<----|---|  esp_netif_transmit       |--<------| netif_output    |     |
    |     |        |   |                           |         |                 |     |
    |     |--->----|---|  esp_netif_receive        |-->------| netif_input     |     |
    |     |        |   |                           |         + ----------------+     |
    |     |...<....|...|  esp_netif_free_rx_buffer |...<.....| буфер пакета          |
    +-----|     |  |   |                           |         |                       |
          |     |  |   |                           |         |         (D)           |
    (B)   |     |  |   |          (C)              |         +-----------------------+
  --------+     |  |   +===========================+
КОММУНИКАЦИОННЫЙ|  |                                               СЕТЕВОЙ СТЕК
ДРАЙВЕР         |  |             ESP-NETIF
                |  |                                         +------------------+
                |  |   +---------------------------+.........| open/close       |
                |  |   |                           |         |                  |
                |  -<--|  l2tap_write              |-----<---|  write           |
                |      |                           |         |                  |
                ---->--|  esp_vfs_l2tap_eth_filter |----->---|  read            |
                       |                           |         |                  |
                       |            (E)            |         +------------------+
                       +---------------------------+
                                                               КОД ПОЛЬЗОВАТЕЛЯ
                             ESP-NETIF L2 TAP

Легенда потока событий событиями:

......... Линия инициализации из кода пользователя для ESP-NETIF и коммуникационного драйвера.
--<--->-- Пакеты данных, поступающих из среды обмена в стек TCP/IP и уходящих обратно.
********* События, агрегированные в ESP-NETIF, распространяются на драйвер, код пользователя и сетевой стек.
|         Настройки пользователя и runtime-конфигурация.

[Взаимодействие с библиотекой ESP-NETIF]

Шаблон кода пользователя. Все взаимодействие приложения с определенным драйвером IO для среды обмена и сконфигурированным стеком TCP/IP абстрагировано API-вызовами ESP-NETIF следующим образом:

A) Код инициализации.

1a. Инициализирует IO-драйвер.

2a. Создает новый экземпляр ESP-NETIF и конфигурирует его со следующими объектами:

- Специфические для ESP-NETIF опции (флаги, поведение, имя).
- Опции сетевого стека (инициализация сетевого интерфейса и входных функций, недоступных публично).
- Опции, специфичные для IO-драйвера (функции передачи, освобождения буфера приема, дескриптор IO-драйвера).

3a. Связывается дескриптор IO-драйвера с экземпляром ESP-NETIF, созданном шагами выше.

4a. Конфигурируются обработчики событий.

- Используются обработчики по умолчанию для общих интерфейсов, определенных в драйверах IO; либо определяется специальный обработчик для пользовательского поведения или новых интерфейсов.
- Регистрируются обработчики для событий, связанных с приложением (таких как потеря или получение IP).

B) Взаимодействие с сетевыми интерфейсами через ESP-NETIF API.

1b. Извлекаются и устанавливаются параметры, связанные с TCP/IP (DHCP, IP, и т. д.).

2b. Принимаются события IP (connect или disconnect).

3b. Осуществляется управление времени жизни приложения (поднять или опустить сетевой интерфейс).

Communication Driver, IO Driver и Media Driver. Драйвер коммуникации играет следующие 2 важные роли, относящиеся к ESP-NETIF:

1. Обработчики событий (event handlers): определяет шаблоны поведения при взаимодействии с ESP-NETIF (например ethernet link-up -> включить netif).

2. Пристыковка (Glue) слоя IO: адаптация входных или выходных функций для использования ESP-NETIF передачи, приема и освобождения буфера приема.

- Устанавливает driver_transmit для соответствующего объекта ESP-NETIF, чтобы уходящие из сетевого стека пакеты передавались драйверу IO.
- Вызывает esp_netif_receive(), чтобы передать приходящие данные сетевому стеку.

ESP-NETIF. Библиотека ESP-NETIF обрабатывает взаимодействие между драйвером IO и сетевым стеком, передавая данные пакета между ними. Она предоставляет набор интерфейсов для подсоединения драйвера к объекту ESP-NETIF во время работы кода (runtime) и конфигурирует сетевой стек во время компиляции. Дополнительно предоставляется набор API-функций для управления временем жизни сетевого интерфейса и его свойствами TCP/IP. В качестве обзора, публичный интерфейс ESP-NETIF можно поделить на 6 групп:

1. API-функции инициализации (для создания и конфигурирования экземпляра ESP-NETIF).

2. API ввода и вывода (для перемещения данных между драйвером IO и сетевым стеком).

3. Event или Action API.

- Используется для управления циклом жизни сетевого интерфейса.
- ESP-NETIF предоставляет готовые блоки для разработки обработчиков событий.

4. API-функции для установки/извлечения (set/get) базовых свойств сетевого интерфейса.

5. API абстракции от сетевого стека: позволяет организовать взаимодействие со стеком TCP/IP для пользователя.

- Включение/выключение сетевого интерфейса (up/down).
- API для сервера DHCP и клиента API.
- DNS API.
- SNTP API.

6. Driver conversion utilities API.

Network Stack. Сетевой стек не имеет общего взаимодействия с кодом приложения в контексте общедоступных интерфейсов, и он должен полностью абстрагироваться через API ESP-NETIF.

Интерфейс ESP-NETIF L2 TAP. Интерфейс ESP-NETIF L2 TAP это механизм ESP-IDF, используемый для доступа к слою обмена данными (Data Link Layer, L2 в модели OSI/ISO), когда кадр принимается или передается приложением пользователя. Его типичным использованием в мире встраиваемых систем может быть реализация протоколов, не связанных с IP, например, PTP, Wake on LAN. Следует отметить, что в настоящее время поддерживается только Ethernet (IEEE 802.3).

С точки зрения пользователя к интерфейсу ESP-NETIF L2 TAP осуществляется доступ с помощью дескрипторов файла VFS, когда предлагается взаимодействие по принципу работы с файлами (с использованием функций наподобие open(), read(), write(), и т. д.). Подробности см. в описании компонента виртуальной файловой системы (Virtual FileSystem, VFS) [2].

Доступно только одно устройство интерфейса ESP-NETIF L2 TAP (path name). Однако можно одновременно открыть несколько дескрипторов файла с различными конфигурациями, поскольку интерфейс ESP-NETIF L2 TAP может понять традиционную точку входа в инфраструктуру Layer 2. Важно иметь специфичную конфигурацию конкретного дескриптора файла. Он может быть сконфигурирован для предоставления доступа к определенному сетевому интерфейсу, идентифицированному if_key (например, ETH_DEF), и фильтрации только определенных кадров на основе их типа (например, типа Ethernet в случае IEEE 802.3). Фильтрация только определенных кадров имеет решающее значение, поскольку TAP ESP-NETIF L2 должен существовать вместе со стеком IP, и поэтому трафик, связанный с IP (IP, ARP и т. д.), не должен передаваться непосредственно пользовательскому приложению. Несмотря на то, что эта опция по-прежнему является конфигурируемой, она не рекомендуется в стандартных сценариях использования. Фильтрация также выгодна с точки зрения приложения пользователя, поскольку оно получает доступ только к интересным для приложения типам кадров, а оставшийся трафик либо передается другим дескрипторам файлов ТАР L2, либо стеку IP.

[Руководство по использованию интерфейса ESP-NETIF L2 TAP]

Инициализация. Чтобы можно было использовать интерфейс ESP-NETIF L2 TAP, он должен быть предварительно разрешен в Kconfig опцией CONFIG_ESP_NETIF_L2_TAP, и затем зарегистрирован esp_vfs_l2tap_intf_register() до того, как будет применена любая из функций VFS [2].

open(). Как только ESP-NETIF L2 TAP был зарегистрирован, его можно открыть по указанному пути "/dev/net/tap" (path name). Один и тот же путь можно открыть несколько раз до величины CONFIG_ESP_NETIF_L2_TAP_MAX_FDS, и несколько файловых дескрипторов могут получить доступ к кадрам Data Link Layer (L2).

ESP-NETIF L2 TAP может быть открыт с флагом статуса файла O_NONBLOCK, чтобы вызов read() не был блокирующим. Имейте в виду, что в текущей реализации вызов write() может заблокировать работу кода, когда происходит доступ к сетевому интерфейсу, потому что он является общим ресурсом для нескольких дескрипторов файла ESP-NETIF L2 TAP и стеком IP, и в настоящий момент не реализован механизм очередей. Флаг статуса файла можно получить и изменить с помощью fcntl().

В случае успеха open() вернет новый дескриптор файла (неотрицательное целое число). В случае ошибки будет возвращено значение -1, и установится переменная errno для обозначения причины ошибки.

ioctl(). Новый открытый дескриптор файла ESP-NETIF L2 TAP перед использованием нужно сконфигурировать для своего применения, потому что он пока что не привязан ни к какому сетевому интерфейсу, и для него не сконфигурирован фильтр типа кадра. Для этого доступны следующие опции конфигурации:

L2TAP_S_INTF_DEVICE - привязывает дескриптор файла к определенному сетевому интерфейсу, который идентифицируется по его if_key. ESP-NETIF Network Interface if_key передается в ioctl() через третий параметр. Обратите внимание, что if_key сетевого интерфейса в ESP-IDF можно найти в esp_netif/include/esp_netif_defaults.h.

L2TAP_S_DEVICE_DRV_HNDL - другой способ привязать дескриптор файла к определенному сетевому интерфейсу. В этом случае сетевой интерфейс идентифицируется напряму по его дескриптору драйвера ввода/вывода (IO Driver handle, например esp_eth_handle_t в случае интерфейса Ethernet). Дескриптор драйвера IO передается в ioctl() через третий параметр.

L2TAP_S_RCV_FILTER - установит фильтр на кадры по типу, чтобы они передавались дескриптору файла. В случае кадров Ethernet, кадры фильтруются на основе поля длины Length и типа Ethernet. В случае, когда значение фильтра установлено меньше или равным 0x05DC, поле типа Ethernet учитывается для представления IEEE802.3 Length Field, и все кадры со значениями в интервале < 0, 0x05DC> в этом поле передаются в дескриптор файла. Тогда ожидается, что разрешение логического управления на слое соединения (IEEE802.2 logical link control, LLC) выполняется приложением пользователя. В случае, когда значение фильтра больше 0x05DC, поле типа Ethernet учитывается для представления идентификации протокола, и дескриптору файла передаются только те кадры, у которых совпадает это значение.

Все упомянутые выше опции конфигурации имеют комплементарные функции для установки и чтения текущих настроек.

Предупреждение: дескриптор файла должен быть сначала привязан к определенному сетевому интерфейсу через L2TAP_S_INTF_DEVICE или L2TAP_S_DEVICE_DRV_HNDL, чтобы сделать доступной опцию L2TAP_S_RCV_FILTER.

Замечания:

1. Кадры, помеченные как VLAN, в текущей реализации не распознаются. Если пользователю надо обрабатывать кадры VLAN, то для них нужно установить фильтр, соответствующий тегу VLAN (например 0x8100 или 0x88A8), и обрабатывать кадры с метками VLAN в приложении пользователя.
2. L2TAP_S_DEVICE_DRV_HNDL в частности полезно, когда приложение пользователя не требует использования стека IP, так что не требуется также инициализировать ESP-NETIF. В результате сетевой интерфейс не может быть идентифицирован по его if_key, и как следствие должен идентифицироваться напрямую по его дескриптору драйвера (IO Driver handle).

В случае успеха ioctl() вернет 0. В случае ошибки будет возвращено значение -1, и установится errno для индикации ошибки.

* EBADF - недопустимый дескриптор файла.
* EACCES - в этом состоянии изменение опций запрещено (например, дескриптор файла еще не был привязан к сетевому интерфейсу).
* EINVAL - недопустимый аргумент конфигурации. Фильтр типа Ethernet уже используется другими дескрипторами файла на том же самом сетевом интерфейсе.
* ENODEV - отсутствует такой сетевой интерфейс, который должен быть назначен дескриптору файла.
* ENOSYS - неподдерживаемая операция, передаваемая опция конфигурации не существует.

fcntl(). Функция fcntl() используется для манипуляций над свойствами открытого дескриптора файла ESP-NETIF L2 TAP.

Следующие команды управляют флагами статуса, связанными с дескриптором файла:

F_GETFD - функция возвратит флаги дескриптора файла, и третий аргумент игнорируется.
F_SETFD - установит флаги дескриптора файла, которые указаны третьим аргументом. Функция возвратит 0.

В случае успеха ioctl() возвратит 0. В случае ошибки будет возвращено значение -1, и установится errno для индикации ошибки.

* EBADF - недопустимый дескриптор файла.
* ENOSYS - неподдерживаемая команда.

read(). К открытому и сконфигурированному дескриптору файла ESP-NETIF L2 TAP можно обращаться вызовами read(), чтобы получить приходящие кадры. Операция чтения (read) может быть либо блокирующей, либо неблокирующей, базируясь на реальном состоянии флага статуса файла O_NONBLOCK. Когда этот флаг статуса файла установлен для блокирования, операция чтения ждет, пока не будет принят кадр, и контекст переключится на другие задачи. Когда флаг статуса файла установлен на non-blocking, операция чтения выполнит немедленный возврат. В таком случае либо будет сразу возвращен кадр, если он уже находится в очереди приема, либо функция покажет, что очередь приема пуста. Количество постановок в очередь кадров, связанных с одним дескриптором файла, ограничивается Kconfig-опцией CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE. Как только количество поставленных в очередь кадров достигнет сконфигурированного порога, новые поступающие кадры отбрасываются, пока очередь не освободиться настолько, чтобы принять поступающий трафик (Tail Drop queue management).

В случае успеха read() возвратит количество прочитанных байт. Будет возвращено значение 0, когда размер буфера назначения 0. В случае ошибки будет возвращено значение -1, и установится errno для индикации ошибки.

* EBADF - недопустимый дескриптор файла.
* EAGAIN - дескриптор файла был помещен как non-blocking (O_NONBLOCK), и чтение сделало бы блокировку.

write(). Сырой кадр Data Link Layer (L2) может быть передан в сетевой интерфейс через открытый и сконфигурированный дескриптор файла ESP-NETIF L2 TAP. Приложение пользователя отвечает за конструирование всего кадра целиком кроме полей, которые автоматически будут добавлены на слое устройства физического интерфейса. Приложением пользователя должны быть сконструированы следующие поля в случае линка Ethernet: MAC-адреса источника/назначения, тип Ethernet, реальный заголовок протокола, и данные пользователя. Длина этих полей следующая:

MAC назначения MAC источника Тип/Длина Полезная нагрузка (заголовок протокола/данные)
6 байт 6 байт 2 байта 0 .. 1486 байт

Другими словами, интерфейсом ESP-NETIF L2 TAP не производится никакая дополнительная обработка кадра. Делается только проверка, что тип Ethernet кадра такой же, что и в фильтре, сконфигурированном в дескрипторе файла. Если тип Ethernet отличается, то будет возвращена ошибка, и кадр не будет отправлен. Обратите внимание, что write() может заблокировать выполнение кода, потому что в текущей реализации сетевой интерфейс является общим ресурсом между несколькими дескрипторами файла ESP-NETIF L2 TAP и стеком IP, и для этого в текущей реализации используется механизм очередей.

В случае успеха write() вернет количество записанных байт. Будет возвращен 0, когда размер входного буфера нулевой. В случае ошибки будет возвращено значение -1, и установится errno для индикации ошибки.

* EBADF - недопустимый дескриптор файла.
* EBADMSG - тип Ethernet кадра отличается от сконфигурированного фильтра для дескриптора файла.
* EIO - сетевой интерфейс недоступен или занят.

close(). Открытый дескриптор файла ESP-NETIF L2 TAP может быть закрыт вызовом close(), чтобы освободить выделенные для этого ресурсы. Реализация ESP-NETIF L2 TAP может заблокировать выполнение кода при вызове close(). С другой стороны, если библиотека thread-safe, и вызов close() может быть из другой задачи, отличающейся от той, где реально используется дескриптор файла. Если произошла такая ситуация, и одна задача заблокирована в операции ввода/вывода, и другая задача пытается закрыть дескриптор файла, то первая задача разблокируется, и операция чтения первой задачи завершится с ошибкой.

В случае успеха close() возвратит. В случае ошибки будет возвращено значение -1, и установится errno для индикации ошибки.

* EBADF - недопустимый дескриптор файла.

select(). Эта операция используется по стандарту, просто нужно разрешить опцию CONFIG_VFS_SUPPORT_SELECT, чтобы функция select() была доступна.

[SNTP API]

Краткое общее описание SNTP, его код инициализации и базовые режимы приведены в секции "Синхронизация времени SNTP" документации [3].

В этой секции приведены дополнительные подробности, касающиеся специальных случаев использования службы SNTP, такие как статически сконфигурированные серверы, или использование серверов, сконфигурированных через DHCP, или оба этих сконфигурированных варианта. Рабочий процесс обычно очень прост:

1. Инициализируется и конфигурируется служба с помощью вызова esp_netif_sntp_init().

2. Служба запускается вызовом esp_netif_sntp_start(). Этот шаг не нужен, если мы задали использовать автоматически запускаемую службу на предыдущем шаге (по умолчанию). Полезно запускать службу явно после соединения, если мы хотим использовать сервера времени, получаемые через DHCP. Обратите внимание, что эта опция должна быть разрешена перед подключением, однако служба SNTP должна быть запущена после подключения.

3. Ожидание момента синхронизации времени с помощью вызова esp_netif_sntp_sync_wait() (только если это необходимо).

4. Остановка и уничтожение службы с помощью esp_netif_sntp_deinit().

Basic Mode со статически определенным сервером (серверами). Инициализируйте модуль с конфигурацией по умолчанию после подключения к сети. Обратите внимание, что есть возможность предоставить несколько серверов NTP в структуре конфигурации:

esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(2,
                           ESP_SNTP_SERVER_LIST("time.windows.com", "pool.ntp.org"));
esp_netif_sntp_init(&config);

Примечание: если мы хотим конфигурировать несколько серверов SNTP, то должны обновить lwIP-конфигурацию CONFIG_LWIP_SNTP_MAX_SERVERS.

Использование серверов SNTP, полученных через DHCP. Сначала мы должны обновить опцию конфигурации CONFIG_LWIP_DHCP_GET_NTP_SRV библиотеки lwIP. Затем нужно инициализировать модуль SNTP с опцией DHCP, и без указания сервера NTP:

esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(0, {} );
config.start = false;                       // явный запуск службы SNTP
config.server_from_dhcp = true;             // принять предложение (опцию) NTP от сервера DHCP
esp_netif_sntp_init(&config);

Затем, как произошел connect, мы могли бы запустить службу:

esp_netif_sntp_start();

Примечание: также можно запустить эту службу во время инициализации (по умолчанию config.start=true). Это вероятно вызовет сбой начального запроса SNTP (поскольку мы еще не подключены к сети), и приведет к некоторому времени ожидания для последующих запросов.

Использование и статических, и динамических серверов. Этот вариант очень похож на показанный выше сценарий (когда DHCP предоставляет адрес сервера SNTP), но в этой конфигурации нам нужно убедиться, что была обновлена статическая конфигурация сервера, когда адреса серверов NTP были получены через DHCP. Нижележащий код lwIP очистит остаток списка серверов NTP, когда принята информация, предоставленная DHCP. Таким образом, модуль ESP-NETIF SNTP сохраняет статически сконфигурированный сервер (серверы), и переконфигурирует список серверов после получения лизинга DHCP.

Типовая конфигурация может выглядеть примерно так, как показано ниже, с предоставлением специального события IP_EVENT для обновления конфигурации в структуре config и индекса первого сервера для переконфигурирования (например, установка config.index_of_first_server=1 сохранит предоставленный через DHCP сервер по индексу 0, и статически сконфигурированный сервер по индексу 1).

esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG("pool.ntp.org");
// Запуск сервиса SNTP будет осуществляться специальным API-вызовом (после соединения с сетью):
config.start = false;
// Принимать адреса серверов NTP, предоставленные лизингом DHCP:
config.server_from_dhcp = true;
// Позволить esp-netif обновить сконфигурированный сервер (серверы) SNTP после получения
// лизинга DHCP:
config.renew_servers_after_new_IP = true;
// Обновить время из сервера 1, не трогая сервер 0 (полученный от DHCP):
config.index_of_first_server = 1;
// IP-событие, на котором мы обновляем конфигурацию:
config.ip_event_to_renew = IP_EVENT_STA_GOT_IP;

В этом случае мы запустим службу SNTP вызовом esp_netif_sntp_start(), когда произойдет подключение к сети.

[Руководство по программированию с применением ESP-NETIF]

Просмотрите следующие примеры, чтобы понимать процесс инициализации интерфейса по умолчанию:

• Wi-Fi Station: wifi/getting_started/station/main/station_example_main.c
• Ethernet: ethernet/basic/main/ethernet_example_main.c
• L2 TAP: protocols/l2tap/main/l2tap_main.c
• Wi-Fi Access Point: wifi/getting_started/softAP/main/softap_example_main.c

Для более специфических случаев обратитесь к руководству [4].

Инициализация Wi-Fi по умолчанию. Код инициализации, как и регистрация обработчиков для интерфейсов по умолчанию, таких как softAP (точка доступа Wi-Fi, режим STA) и station (станция Wi-Fi, режим AP), предоставляется в отдельных API-функциях, чтобы упростить обычный код запуска (startup code) для большинства приложений:

• esp_netif_create_default_wifi_sta()
• esp_netif_create_default_wifi_ap()

Обратите внимание, что эти функции возвратят дескриптор (handle) esp_netif, например указатель на объект сетевого интерфейса, выделенный и сконфигурированный настройками по умолчанию, что как следствие означает:

• Созданный объект должен быть уничтожен, если приложением предоставлена деинициализация сети, с помощью вызова esp_netif_destroy_default_wifi().
• Эти интерфейсы по умолчанию не должны быть созданы несколько раз, за исключением случая, когда созданный дескриптор (handle) удаляется с помощью esp_netif_destroy().
• Когда используется Wi-Fi в режиме AP+STA, должны быть созданы оба этих интерфейса.

[Справочник по API-функциям ESP-NETIF]

Заголовочный файл: components/esp_netif/include/esp_netif.h. Ниже приведено общее описание назначения функций. Более подробное описание функций и их параметров, а также описание используемых типов данных, структур и макросов см. в документации [1].

Функция Описание
esp_netif_init Инициализирует нижележащий стек TCP/IP. Эта функция должна быть явно вызвана из кода приложения, когда оно запускается.
esp_netif_deinit Деинициализирует компонент esp-netif (и нижележащий стек TCP/IP). Замечание: деинициализация пока не поддерживается.
esp_netif_new Создает экземпляр нового объекта esp-netif на основе предоставленной конфигурации.
esp_netif_destroy Удалит объект esp_netif.
esp_netif_set_driver_config Конфигурирует опции объекта esp_netif, относящиеся к драйверу.
esp_netif_attach Подсоединяет любой экземпляр esp_netif к дескриптору драйвера ввода/вывода (IO driver handle). Вызов этой функции разрешает соединение определенного объекта esp_netif с уже инициализированным драйвером, чтобы обновит объект esp_netif конфигурацией, специфичной для драйвера (например вызовет callback-функцию post_attach, которая обычно устанавливает callback-и драйвера IO для экземпляра esp_netif и запускает драйвер).
esp_netif_receive Передает сырые пакеты из communication media в соответствующий стек TCP/IP. Эта функция вызывается из слоя драйвера сконфигурированного периферийного устройства. Данные затем перенаправляются в виде кадров в стек TCP/IP.
esp_netif_action_start Стандартный блок по умолчанию для действий сетевого интерфейса при событии запуска драйвера IO. Создает сетевой интерфейс, включает его если разрешено AUTOUP, и запустит сервер DHCP, если разрешена опция DHCPS(*).
esp_netif_action_stop Стандартный блок по умолчанию для действий сетевого интерфейса при событии останова драйвера IO(*).
esp_netif_action_connected Стандартный блок по умолчанию для действий сетевого интерфейса при событии подключения к сети драйвера IO(*).
esp_netif_action_disconnected Стандартный блок по умолчанию для действий сетевого интерфейса при событии отключения драйвера IO от сети(*).
esp_netif_action_got_ip Стандартный блок по умолчанию для действий сетевого интерфейса при событии получения IP-адреса сети(*).
esp_netif_action_join_ip6_multicast_group Стандартный блок по умолчанию для действий сетевого интерфейса при подключении к multicast-группе IPv6(*).
esp_netif_action_leave_ip6_multicast_group Стандартный блок по умолчанию для действий сетевого интерфейса при выходе из multicast-группы IPv6(*).
esp_netif_action_add_ip6_address Стандартный блок по умолчанию для действий сетевого интерфейса при добавлении адреса IPv6 нижележащим стеком(*).
esp_netif_action_remove_ip6_address Стандартный блок по умолчанию для действий сетевого интерфейса при удалении адреса IPv6 нижележащим стеком(*).
esp_netif_set_default_netif Ручная конфигурация сетевого интерфейса (netif) по умолчанию. Эта API-функция отменяет автоматическую конфигурацию интерфейса по умолчанию, основанную на route_prio. Если выбранный netif установлен по умолчанию с помощью этой API-функции, то никакой другой интерфейс не может быть установлен по умолчанию без учета его номера route_prio (если только выбранный netif не будет уничтожен).
esp_netif_get_default_netif Функция извлечения netif по умолчанию. Этот API-вызов вернет выбранный по умолчанию сетевой интерфейс.
esp_netif_join_ip6_multicast_group Приведет к подключению стека TCP/IP в multicast-группу IPv6.
esp_netif_leave_ip6_multicast_group Приведет к покиданию стеком TCP/IP multicast-группы IPv6.
esp_netif_set_mac Установит MAC-адрес для экземпляра интерфейса.
esp_netif_get_mac Извлечет MAC-адрес для экземпляра интерфейса.
esp_netif_set_hostname Установит имя хоста интерфейса. Сконфигурированное hostname отменит конфигурационное значение по умолчанию CONFIG_LWIP_LOCAL_HOSTNAME. Обратите внимание, что когда hostname изменено после того, как интерфейс запущен/подключился к сети, это изменение будет применено только когда интерфейс будет перезапущен/подключится заново.
esp_netif_get_hostname Извлечет сетевое имя интерфейса.
esp_netif_is_netif_up Проверит, поднят или опущен предоставленный интерфейс.
esp_netif_get_ip_info Извлечет информацию IP-адреса интерфейса. Если интерфейс поднят, то информация IP вычитывается напрямую из стека TCP/IP. Если интерфейс опущен, то информация IP вычитывается из копии, которая хранится в экземпляре ESP-NETIF.
esp_netif_get_old_ip_info Извлечет старую информацию IP для интерфейса. Возвратит "старый" IP-адрес, который был ранее сохранен для интерфейса, когда поменялся достоверный IP-адрес. Если истек таймер потери адреса (IP lost timer, это означает, что интерфейс был опущен дольше, чем сконфигурированный интервал), то старая информация IP будет обнулена.
esp_netif_set_ip_info Установит информацию IP-адреса интерфейса. Эта функция используется главным образом для установки статического IP на интерфейсе. Если интерфейс поднят, то новая информация установится напрямую в стек TCP/IP. Копия информации IP, которая хранится в экземпляре ESP-NETIF, также будет обновлена (эта копия возвращается, если IP запрашивается, когда интерфейс все еще опущен).

Замечания: клиент/сервер DHCP должен быть остановлен (если такой функционал разрешен на этом интерфейсе) перед установки новой информации IP. Вызов функции esp_netif_set_ip_info() может генерировать событие SYSTEM_EVENT_STA_GOT_IP или SYSTEM_EVENT_ETH_GOT_IP.
esp_netif_set_old_ip_info Установит старую информацию IP. Эта функция вызывается из клиента DHCP (если этот функционал разрешен) перед установкой нового IP. Она также вызывается из обработчиков по умолчанию для событий SYSTEM_EVENT_STA_CONNECTED и SYSTEM_EVENT_ETH_CONNECTED. Вызов этой функции сохранит ранее сконфигурированный IP, который может использоваться для определения в будущем, был ли изменен IP. Если интерфейс отключен, или был опущен слишком долго, то истечет "IP lost timer" (после сконфигурированного интервала) и установится в ноль информация старого IP.
esp_netif_get_netif_impl_index Извлечет индекс сетевого интерфейса из реализации сетевого стека. Этот индекс мог быть использован для привязки сокета функцией setsockopt() к multicast-интерфейсу.
esp_netif_get_netif_impl_name Извлечет имя сетевого интерфейса из реализации сетевого стека. Это имя могло бы использоваться в setsockopt() для привязки сокета к подходящему интерфейсу.
esp_netif_napt_enable Разрешает NAPT на интерфейсе. Замечание: операция разрешения может быть выполнена только на одном интерфейсе. В текущей реализации NAPT не может быть разрешен на нескольких интерфейсах.
esp_netif_napt_disable Запретит NAPT на интерфейсе.
esp_netif_dhcps_option Установит или извлечет опцию сервера DHCP.
esp_netif_dhcpc_option Установит или извлечет опцию клиента DHCP.
esp_netif_dhcpc_start Запустит клиента DHCP (только если это разрешено в объекте интерфейса). Эту функцию вызовут обработчики событий умолчанию для событий SYSTEM_EVENT_STA_CONNECTED и SYSTEM_EVENT_ETH_CONNECTED.
esp_netif_dhcpc_stop Остановит клиента DHCP (только если это разрешено в объекте интерфейса). Вызов action_netif_stop() также остановит клиента DHCP, если он запущен.
esp_netif_dhcpc_get_status Извлечет статус клиента DHCP.
esp_netif_dhcps_get_status Извлечет статус сервера DHCP.
esp_netif_dhcps_start Запустит сервер DHCP (только если это разрешено в объекте интерфейса).
esp_netif_dhcps_stop Остановит сервер DHCP (только если это разрешено в объекте интерфейса).
esp_netif_dhcps_get_clients_by_mac Заполнит IP-адреса клиентов, подключенных к серверу DHCP, по их MAC-адресам.
esp_netif_set_dns_info Установит информацию сервера DNS. Эта функция ведет себя по-другому, если разрешен сервер DHCP или клиент DHCP. Если разрешен клиент DHCP, то основные (main DNS) и резервные (backup DNS) сервера имен обновляются автоматически из лизинга DHCP, если установлены соответствующие опции DHCP. Fallback DNS Server никогда не обновляется из лизинга DHCP, и это разработано для установки через API-функцию esp_netif_set_dns_info. Если запрещен клиент DHCP, то все типы сервера DNS могут быть установлены только через эту API-функцию esp_netif_set_dns_info. Если разрешен сервер DHCP, то сервером DHCP используется настройка Main DNS Server для предоставления клиентам DHCP (станциям Wi-Fi) опции сервера DNS.
• Main DNS сервер по умолчанию это обычно IP самого сервера DHCP.
• Функция esp_netif_set_dns_info может отменить это путем установки типа сервера ESP_NETIF_DNS_MAIN.
• Другие типы DNS Server для сервера DHCP не поддерживаются.
• Чтобы распространить информацию DNS на клиента, остановите сервер DHCP перед использованием функции esp_netif_set_dns_info().
esp_netif_get_dns_info Извлекает информацию сервера DNS. Возвратит сконфигурированный в настоящий момент адрес сервера DNS для указанного интерфейса и типа сервера. Это может быть результатом предыдущего вызова esp_netif_set_dns_info(). Если разрешен интерфейс клиента DHCP, то может быть установлен Main или Backup DNS сервер, установленный текущей арендой адреса DHCP.
esp_netif_create_ip6_linklocal Создает интерфейс link-local адреса IPv6. Заставит стек TCP/IP создать link-local адрес IPv6 для указанного интерфейса. Эта функция также регистрирует callback для указанного интерфейса, так что если адрес link-local становится проверенным в качестве предпочтительного адреса, то будет отправлено событие SYSTEM_EVENT_GOT_IP6.
esp_netif_get_ip6_linklocal Извлечет адрес IPv6 link-local интерфейса. Если указанный интерфейс поднят, и предпочтительный адрес link-local IPv6 был создан для интерфейса, то будет возвращена его копия.
esp_netif_get_ip6_global Извлечет глобальный адрес IPv6 интерфейса. Если указанный интерфейс поднят, и для интерфейса был создан предпочтительный глобальный адрес IPv6, то будет возвращена его копия.
esp_netif_get_all_ip6 Извлечет все адреса IPv6 указанного интерфейса.
esp_netif_set_ip4_addr Установит адрес IPv4 для указанных байт.
esp_ip4addr_ntoa Преобразует цифровой IP-адрес в десятичное ASCII-представление с точками.
esp_ip4addr_aton Подпрограмма интерпретации ASCII-адреса интернет. Значение возвращается с сетевым порядком байт.
esp_netif_str_to_ip4 Преобразует ASCII-адрес IPv4 интернет в esp_ip4_addr_t.
esp_netif_str_to_ip6 Преобразует ASCII-адрес IPv6 интернет в esp_ip4_addr_t. Нули в IP-адресе могут быть вырезаны или полностью пропущены: "2001:db8:85a3:0:0:0:2:1" или "2001:db8::2:1").
esp_netif_get_io_driver Извлечет дескриптор драйвера media для этого экземпляра esp-netif.
esp_netif_get_handle_from_ifkey Ищет по списку созданных объектов, чтобы найти экземпляр с предоставленным ключом интерфейса.
esp_netif_get_flags Возвратит сконфигурированные флаги для этого интерфейса.
esp_netif_get_ifkey Возвратить сконфигурированный ключ интерфейса для этого экземпляра esp-netif.
esp_netif_get_desc Возвратит сконфигурированный тип интерфейса для этого экземпляра esp-netif.
esp_netif_get_route_prio Возвратит сконфигурированный номер приоритета маршрута.
esp_netif_get_event_id Возвратит сконфигурированное событие для этого экземпляра esp-netif и предоставленного типа события.
esp_netif_next Просматривает список интерфейсов. Возвратит первый netif, если в качестве параметра предоставлен NULL.
esp_netif_get_nr_of_ifs Возвратит количество зарегистрированных объектов esp_netif.
esp_netif_netstack_buf_ref Увеличит счетчик ссылок буфера сетевого стека.
esp_netif_netstack_buf_free Освободит буфер сетевого стека.
esp_netif_tcpip_exec Утилита для выполнения предоставленной callback-функции в контексте TCP/IP.

Примечание (*): эта API-функция может напрямую использоваться как обработчик события (event handler).

Функции SNTP. Заголовочный файл: components/esp_netif/include/esp_netif_sntp.h.

 

Функция Описание
esp_netif_sntp_init Инициализирует SNTP с предоставленной структурой конфигурации.
esp_netif_sntp_start Запустит службу SNTP, если она не была запущена во время инициализации (config.start = false), или перезапустит её, если она уже была запущена.
esp_netif_sntp_deinit Отменяет инициализацию esp_netif модуля SNTP.
esp_netif_sntp_sync_wait Ждет события синхронизации времени.

Функции IP-адреса. Заголовочный файл: components/esp_netif/include/esp_netif_ip_addr.h.

Функция Описание
esp_netif_ip6_get_addr_type Извлечет тип адреса IPv6.
esp_netif_ip_addr_copy Сделает копию IP-адреса.

Функции L2 TAP. Заголовочный файл: components/esp_netif/include/esp_vfs_l2tap.h.

Функция Описание
esp_vfs_l2tap_intf_register Добавляет драйвер виртуальной файловой системы L2 TAP. Эта функция должна быть вызвана перед использованием интерфейса ESP-NETIF L2 TAP.
esp_vfs_l2tap_intf_unregister Удалит драйвер виртуальной файловой системы L2 TAP.
esp_vfs_l2tap_eth_filter Фильтрует принятые кадры Ethernet L2 в инфраструктуру L2 TAP.

Функции Wi-Fi. Заголовочный файл: components/esp_wifi/include/esp_wifi_default.h.

Функция Описание
esp_netif_attach_wifi_station Присоединяет интерфейс станции Wi-Fi (STA) к предоставленному сетевому интерфейсу netif.
esp_netif_attach_wifi_ap Присоединяет интерфейс Wi-Fi точки доступа (soft AP) к предоставленному сетевому интерфейсу netif.
esp_wifi_set_default_wifi_sta_handlers Установит обработчики событий Wi-Fi по умолчанию для интерфейса STA.
esp_wifi_set_default_wifi_ap_handlers Установит обработчики событий Wi-Fi по умолчанию для интерфейса AP.
esp_wifi_set_default_wifi_nan_handlers Установит обработчики событий Wi-Fi по умолчанию для интерфейса NAN.
esp_wifi_clear_default_wifi_driver_and_handlers Очистит обработчики событий Wi-Fi по умолчанию для предоставленного сетевого интерфейса.
esp_netif_create_default_wifi_ap Создаст точку доступа Wi-Fi (AP) по умолчанию. В случае любой ошибки инициализации эта API-функция прерывает работу. Функция создаст объект esp_netif с конфигурацией по умолчанию для точки доступа Wi-Fi, подключит сетевой интерфейс netif к wifi и зарегистрирует обработчики wifi по умолчанию.
esp_netif_create_default_wifi_sta Создаст станцию W-Fi (STA) по умолчанию. В случае любой ошибки инициализации эта API-функция прерывает работу. Функция создаст объект esp_netif с конфигурацией по умолчанию станции Wi-Fi, подключит сетевой интерфейс netif к wifi и зарегистрирует обработчики wifi по умолчанию.
esp_netif_create_default_wifi_nan Создаст Wi-Fi NAN по умолчанию. В случае любой ошибки инициализации эта API-функция прерывает работу. Функция создаст объект esp_netif с конфигурацией по умолчанию станции Wi-Fi, подключит сетевой интерфейс netif к wifi и зарегистрирует обработчики wifi по умолчанию.
esp_netif_destroy_default_wifi Уничтожит сетевой интерфейс по умолчанию Wi-Fi, который был создан вызовом API-функции esp_netif_create_default_wifi_...(). Функция esp_netif_destroy_default_wifi() отменит регистрацию обработчиков wifi и отсоединит созданный объект от wifi (эта функция ничего не делает, если esp_netif == NULL).
esp_netif_create_wifi Создаст объект esp_netif Wi-Fi на основе пользовательской конфигурации. Внимание: эта API-функция НЕ РЕГИСТРИРУЕТ обработчики по умолчанию!
esp_netif_create_default_wifi_mesh_netifs Создаст сетевые интерфейсы по умолчанию STA и AP для esp-mesh. Оба netifs почти идентичны для созданных по умолчанию станции и softAP, однако с клиентом DHCP и запрещенным сервером DHCP. Обратите внимание, что клиент DHCP обычно разрешен только если устройство переведено в корневой узел. Возвратит созданные интерфейсы, которые могут игнорироваться установкой параметров в NULL, если код приложения не нуждается в сохранении экземпляров интерфейса для последующей обработки.

[Ссылки]

1. ESP-NETIF site:espressif.com.
2. ESP VFS: виртуальная файловая система.
3. ESP-IDF System Time.
4. ESP-NETIF Custom I/O Driver site:espressif.com.