ESP8266:Прошивки/Arduino/Библиотеки/Библиотека ESP8266WiFi

Содержание

Введение

Модули

AT-команды

Прошивки

Примеры

Проекты

Типовые проблемы

Библиотеки

Перевод: Максим Кузьмин

Проверка/Оформление/Редактирование: Мякишев Е.А.

Библиотека ESP8266WiFi

Главная область применения ESP8266 – проекты, использующие WiFi. Эта статья подойдет и для новичков, которые только-только купили новый ESP8266 и хотят научиться, как с его помощью осуществлять передачу данных, и для продвинутых пользователей, которые уже знакомы с основами и хотят опробовать углубленный WiFi-функционал.

Введение

Библиотека ESP8266WiFi разработана на базе SDK ESP8266 с использованием соглашения о названиях и прочих принципов, использовавшихся при создании Arduino-библиотеки WiFi Shield. Со временем объем WiFi-функций, портированных из SDK в библиотеку ESP8266WiFi, перерос объем функций «родной» Arduino-библиотеки WiFi, поэтому все изменения и дополнения было решено перенести на отдельную страницу, которую вы и видите перед собой.

Эта статья рассказывает о классах, функциях и свойствах библиотеки ESP8266WiFi. Если вы новичок в C++ и Arduino, ничего страшного. Мы начнем с общих концептов и постепенно перейдем к более детальному описанию каждого класса, включая примеры использования.

Функционал библиотеки ESP8266WiFi обширен и разнообразен, поэтому в этой статье мы ограничимся лишь общим описанием классов, а более подробные описания, с примерами и описанием функций, будут выведены в отдельные статьи.

Быстрый старт

Надеемся, вы уже знаете, как загрузить на ESP8266 скетч «Blink.io» и управлять миганием светодиода. Если нет, ознакомьтесь с этим руководством о HUZZAH ESP8266 или этим руководством о ESP8266 Thing.

Чтобы подключить ESP8266 к WiFi (как мобильный телефон к точке доступа), потребуется вот такой код:

#include <ESP8266WiFi.h>

void setup()
{
  Serial.begin(115200);
  Serial.println();

  WiFi.begin("network-name", "pass-to-network");

  Serial.print("Connecting");  //  "Подключение"
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();

  Serial.print("Connected, IP address: ");
           //  "Подключились, IP-адрес: "
  Serial.println(WiFi.localIP());
}

void loop() {}

В строчке WiFi.begin("network-name", "pass-to-network") вместо network-name и pass-to-network впишите название и пароль к WiFi-сети, к которой вы хотите подключиться. Затем загрузите скетч на ESP8266 и откройте монитор порта. В нем будет примерно следующее:

Как это работает? В первой строчке мы пишем #include <ESP8266WiFi.h>, подключая к скетчу библиотеку ESP8266WFi. Она нужна нам, т.к. содержит функции, с помощью которых ESP8266 осуществляет подключение к WiFi.

Подключение к WiFi инициализируется вот этой строчкой:

WiFi.begin("network-name", "pass-to-network");

Процесс подключения может занять несколько секунд. Проверка подключения выполняется в этом цикле:

while (WiFi.status() != WL_CONNECTED)
{
  delay(500);
  Serial.print(".");
}

Цикл while() будет прокручивать функцию WiFi.status() до тех пор, пока она не вернет значение WL_CONNECTED. Другими словами, этот цикл завершится только тогда, когда статус WiFi-подключения поменяется на WL_CONNECTED.

Последняя строчка печатает IP-адрес, который DHCP присвоил ESP8266:

Serial.println(WiFi.localIP());

Если в мониторе порта вместо строчки с IP-адресом появляется лишь все больше и больше точек, то это значит, возможно, что вы указали неправильные название сети или пароль к ней. Проверить название и пароль можно, подключившись к этой WiFi-сети с помощью компьютера или смартфона.

Примечание: Если соединение было установлено, а потом по какой-то причине потеряно, то ESP8266 автоматически переподключится к последней рабочей точке доступа, когда она снова будет доступна. Это будет выполнено автоматически самой WiFi-библиотекой, без вмешательства пользователя.

Вот и все, что нужно для подключения ESP8266 к WiFi. Ниже мы расскажем о том, на что способен ESP8266, будучи уже подключенным к WiFi-сети.

Кто есть кто

Устройства, подключаемые к WiFi-сети, называются станциями (STA). Подключение к WiFi предлагает точка доступа (AP, что значит «access point»), которая служит хабом для одной или нескольких станций. Сама точка подключена к проводной сети. Точка доступа, как правило, интегрирована с роутером, что обеспечивает доступ из WiFi-сети к интернету. Каждая точка доступа имеет SSID (что значит «Service Set IDentifier», что можно перевести как «идентификатор служебного устройства»), который является, в сущности, названием сети, которую вы выбрали при подключении устройства (станции) к WiFi.

Во-первых, ESP8266 может работать в качестве станции, т.е. может подключаться к WiFi-сетям. Во-вторых, ESP8266 также может работать в качестве программной точки доступа (soft-AP), сам становясь WiFi-сетью, к которой могут подключаться другие устройства (станции). В третьих, ESP8266 может работать одновременно в режимах станции и программной точки доступа. Это позволяет создавать, к примеру, сети с ячеистой топологией.

Библиотека ESP8266WiFi содержит большой набор функций и свойств языка C++, используемых для настройки и поддержания ESP8266 в режиме станции и/или программной точки доступа. Все они будут описаны ниже.

Описание классов

Библиотека ESP8266WiFi разбита на несколько классов. Как правило, при написании кода программисту эта классификация не нужна. Мы воспользуемся ею, чтобы разбить описание библиотеки на отдельные кусочки – для удобства восприятия.

Главы ниже являются общим описанием классов, более подробную информацию (описание функций и примеры) ищите по ссылкам. В примерах демонстрируется, как функции используются на практике.

Режим станции

Режим станции (STA) используется для подключения ESP8266 к WiFi-сети, которую раздает некая точка доступа.

Этот класс оснащен несколькими функциями для управления WiFi-соединением. Если соединение будет потеряно, ESP8266 автоматически переподключится к рабочей точке доступа, когда она снова будет доступна. То же самое происходит и после перезагрузки модуля. Это возможно благодаря тому, что ESP сохраняет данные о последней рабочей точке доступа во flash-памяти, которая при отключении питания не стирается. Кроме того, сохранение данных также позволяет ESP8266 переподключится к сети, если вы загрузили другой скетч, но WiFi-сеть и пароль к ней остались теми же.

Более подробно о классе станции читайте тут.

О примерах читайте тут.

Режим программной точки доступа

Точка доступа (AP) – это устройство, которое обеспечивает доступ к WiFi-сети для других устройств (станций), а затем подключает их к проводной сети. ESP8266 тоже может работать в режиме точки доступа, но за тем исключением, что у него нет интерфейса для подключения к проводной сети. Такой режим называют «программной точкой доступа» или soft-AP. Максимальное количество станций, которые могут быть подключены к ESP8266 в режиме программной точки доступа – пять.

Этот режим часто используется как промежуточный шаг для подключения ESP8266 к WiFi-сети в стационарном режиме – в ситуации, когда ESP8266 не знает SSID и пароль к сети. В этом случае ESP8266 сначала загружается в режиме точки доступа, чтобы мы могли подключиться к нему при помощи ноутбука или смартфона, а затем задать SSID и пароль. После этого ESP8266 переключается в режим станции и может подсоединиться к заданной WiFi-сети.

Еще один вариант использования режима программной точки доступа – это сети с ячеистой топологией. ESP8266 может быть и станцией, и точкой доступа, благодаря чему может выступать узлом такой сети. Более подробно о классе программной точки доступа читайте тут.

О примерах читайте тут.

Сканирование

Чтобы подключить мобильный телефон к точке доступа, вы, как правило, открываете меню WiFi-настроек, видите список доступных WiFi-сетей, а затем выбираете ту, к которой хотите подключиться. Далее вы вводите пароль (или не вводите, если сеть открытая) и все – вы в сети. То же самое можно делать и при помощи ESP8266. Функционал для сканирования и выведения списка доступных сетей реализован именно в этом классе – классе для сканирования.

Более подробно о классе сканирования читайте тут.

О примерах читайте тут.

Клиент

Этот класс создает клиентов, способных получить доступ к сервисам, предоставляемым серверами. Подключившись к серверу, клиент может передавать/получать от него данные, а также получает доступ к функционалу, который предоставляет сервер (например, к обработке данных).

Более подробно о классе клиента читайте тут.

О примерах читайте тут.

Защищенный клиент

Этот класс – расширение класса клиента. В нем подключение и обмен данными с серверами осуществляется при помощи защитного протокола TLS. Версия TLS 1.1 поддерживается, версия TLS 1.2 не поддерживается.

Некоторые проекты снабжены дополнительными памятью и вычислительными ресурсами, необходимыми для работы криптографических алгоритмов. Чем сильнее ключ сертификата, тем больше нужно «надбавки». На практике запустить одновременно больше одного защищенного клиента невозможно. Проблема в RAM-памяти, которую мы добавить не можем, а размер flash-памяти проблемой, как правило, не является. Если вам интересно, как разрабатывался класс защищенного клиента, доступ к каким серверам тестировался и как разработчикам удалось обойти ограничения памяти, то об этом можно почитать в этом отчете о проблемах.

Более подробно о классе защищенного клиента читайте тут.

О примерах читайте тут.

Сервер

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

Клиенты подключаются к серверам, чтобы получать/отправлять им данные, а также чтобы получить доступ к функционалу, который предлагают эти серверы.

Более подробно о классе сервера читайте тут.

О примерах читайте тут.

UDP

Этот класс позволяет отправлять и получать UDP-сообщения (от «user datagram protocol», что значит «протокол пользовательских датаграмм»). Протокол UDP использует очень простой принцип, который можно описать как «отправил и забыл». Он не гарантирует стопроцентную доставку, правильный порядок присланных сообщений и защиту от дубликатов. Для обеспечения целостности данных в UDP используется контрольная сумма. Также поддерживаются номера портов – для обращения к разным функциям в пункте назначения.

Более подробно о классе UDP читайте тут.

О примерах читайте тут.

Generic

В библиотеке ESP8266WiFi есть несколько функций из SDK ESP8266, которых нет в оригинальной WiFi-библиотеке для IDE Arduino. Если функция из SDK не подходит ни к одному из классов, описанных выше, то она, скорее всего, относится к классу Generic. Среди них, к примеру, обработчик для управления WiFi-событиями вроде подключения, отключения, получения IP-адреса и смены WiFi-режима, а также функции для управления спящим режимом ESP8266, преобразования имени хоста в IP-адрес и т.д.

Более подробно о классе Generic читайте тут..

О примерах читайте тут..

Диагностика

Библиотека ESP8266 поддерживает несколько способов для диагностики и решения проблем, связанных с подключением к WiFi и поддержания WiFi-подключения.

Значения, возвращаемые функциями

Почти каждая функция библиотеки ESP8266WiFi возвращает определенную диагностическую информацию.

Это могут быть, например, простые булевы данные (true или false), сообщающие о том, была ли задача выполнена успешно или нет. Эта проверка может выглядеть следующим образом:

Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");

Некоторые функции умеют возвращать более подробную диагностическую информацию. Хороший пример – функция WiFi.status().

Serial.printf("Connection status: %d\n", WiFi.status());

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

• 0: WL_IDLE_STATUS – когда WiFi в процессе между сменой статусов
• 1: WL_NO_SSID_AVAIL – когда заданный SSID находится вне зоны доступа
• 3: WL_CONNECTED – после успешного подключения
• 4: WL_CONNECT_FAILED – когда задан неправильный пароль
• 6: WL_DISCONNECTED – когда ESP8266 не настроен на режим станции

Рекомендуем почаще показывать и проверять данные, возвращаемые функциями. Это значительно облегчает разработку проектов и решение проблем.

Использование функции printDiag()

В библиотеке ESP8266WiFi есть одна функция, печатающая основную диагностическую информацию о состоянии WiFi-подключения. Выглядит она следующим образом:

WiFi.printDiag(Serial);

Результат, возвращаемый этой функцией, может выглядеть примерно так:

Mode: STA+AP
PHY mode: N
Channel: 11
AP id: 0
Status: 5
Auto connect: 1
SSID (10): sensor-net
Passphrase (12): 123!$#0&*esP
BSSID set: 0

Используйте эту функцию для получения быстрого «снимка» о состояния WiFi-связи при работе над фрагментами кода, которые, на ваш взгляд, могут быть некорректными.

Включение WiFi-диагностики

По умолчанию, когда вы вызываете функцию Serial.begin(), вывод диагностической информации от WiFi-библиотек отключен. Чтобы включить его, вызовите функцию Serial.setDebugOutput(true). Чтобы перенаправить диагностическую информацию на Serial1, вызовите Serial1.setDebugOutput(true). Более подробно о диагностике через последовательные порты читайте тут.

Ниже – пример того, какую информацию будет выдавать скетч, о котором рассказывалось выше, в разделе «Быстрый старт», если вызвать в нем функцию Serial.setDebugOutput(true):

Connectingscandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt

connected with sensor-net, channel 6
dhcp client start...
chg_B1:-40
...ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
.
Connected, IP address: 192.168.1.10

Тот же скетч без функции Serial.setDebugOutput(true) покажет лишь следующее:

Connecting....
Connected, IP address: 192.168.1.10

Включение отладки в IDE Arduino

В IDE Arduino встроен удобный способ для отладки некоторых библиотек. Почитать о нем можно [ссылка тут].

Что внутри?

Если вы хотите детально проанализировать, из чего состоит ESP8266WiFi, пройдите по этой ссылке на GitHub-репозиторий библиотеки. Чтобы упростить анализ и не ковыряться в отдельных заголовочных и исходных файлах, воспользуйтесь бесплатным инструментом Doxygen, предназначенным для автоматической генерации документации. Разбивка классов в главе «Описание классов» (см. выше) выполнена за считанные секунды, и как раз с его помощью. Де факто это стандартный инструмент для генерации документации из комментированных исходников C++.

Doxygen пробегает по всем заголовочным и исходным файлам, собирая информацию из размеченных блоков, оснащенных комментариями. Если разработчик какого-то класса оставил комментарий к своей работе, то он будет выглядеть примерно так:

Если комментария нет, вы увидите прототип функции (включая типы аргументов) и ссылки, с помощью которых можно будет переместиться прямо к исходному коду, чтобы увидеть все собственными глазами. Doxygen – действительно очень удобный инструмент для навигации по отдельным компонентам библиотеки.

У нескольких классов ESP8266WiFi комментариев нет.

Так или иначе, Doxygen был очень полезен при подготовке этой статьи, т.к. позволял в мгновение ока переключаться между почти 30 файлами, из которых состоит эта библиотека.