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

Содержание

Введение

Модули

AT-команды

Прошивки

Примеры

Проекты

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

Библиотеки

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

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

Черновик

Класс станции в библиотеке ESP8266WiFi

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

Описание класса станции будет разбито на четыре части. В первой будут описаны функции для подключения к точке доступа. Во второй – функции для управления подключением вроде reconnect() и isConnected(). Третья – функции для получения информации о подключении вроде MAC-адреса или IP-адреса. Наконец, четвертая – это альтернативные функции для подключения вроде стандарта Wi-Fi Protected Setup (WPS).

К каждой функции прилагается описание и фрагменты кода, демонстрирующие ее использование. Другие примеры использования функций, входящих в класс станции, ищите по [ссылка этой ссылке].

Подключение

Переключение ESP8266 в режим станции выполняется при помощи функции begin(). Параметрами для этой функции служат SSID и пароль к ней, чтобы чип можно было подключить к определенной точке доступа.

WiFi.begin(ssid, password)

По умолчанию, если ESP8266 будет отключен от WiFi-сети, то потом снова попробует к ней подключиться. Писать для этого отдельный код не нужно. Имитировать отключение можно, к примеру, просто сбросив точку доступа. ESP8266 сообщит об отключении, а потом попробует автоматически подключиться.

begin()

В библиотеке ESP8266WiFi представлено несколько вариантов функции begin(). Процесс совмещения нескольких функций в одной называют «перегрузкой функции». Один вариант был показан выше – это WiFi.begin(ssid, password). Перегрузка дает гибкость в количестве и типе параметров, задаваемых в функции.

Самый простой вариант функции begin() – это...

WiFi.begin()

Вызов этой функции скомандует ESP8266 переключиться в режим станции и подключиться к последней использованной точке доступа на основе данных, сохраненных во flash-памяти.

Ниже – синтаксис еще одного варианта функции begin() со всеми возможными параметрами:

WiFi.begin(ssid, password, channel, bssid, connect)

Параметр ssid – символьная строка, содержащая SSID точки доступа, к которой мы хотим подключиться (может содержать не более 32 символов). Параметр password – это пароль к точке доступа в виде символьной строки, которая может содержать от 8 до 64 символов. Параметр channel – канал точки доступа; на тот случай, если вы хотите работать через специальный канал (в противном случае этот параметр нужно проигнорировать). Параметр bssid – MAC-адрес точки доступа (тоже опционально). Параметр connect – это параметр с булевым значением; если задать в нем false, это скомандует модулю сохранить другие параметры, не подключаясь к точке доступа.

config()

Отключает DHCP-клиент (от «dynamic host configuration protocol», что значит «протокол динамической настройки узла») и выставляет IP-настройки станции на пользовательские значения. Эти IP-настройки, в отличие от настроек DHCP, будут статическими.

WiFi.config(local_ip, gateway, subnet, dns1, dns2)

При успешном изменении настроек функция вернет true. Если настройки задать нельзя (например, если чип не переключен в режим станции или станции + точки доступа), функция вернет false.

В функции можно указать следующую информацию:

• local_ip – IP-адрес для стационарного интерфейса ESP8266
• gateway – IP-адрес шлюза (роутера) для доступа к внешним сетям
• subnet – маска подсети, диапазон IP-адресов в локальной сети
• dns1, dns2 – опциональные параметры для IP-адресов DNS-серверов, которые хранят директории доменных имен (вроде www.google.co.uk) и преобразовывают их в IP-адреса

Пример:

#include <ESP8266WiFi.h>

const char* ssid = "********";
const char* password = "********";

IPAddress staticIP(192,168,1,22);
IPAddress gateway(192,168,1,9);
IPAddress subnet(255,255,255,0);

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

  Serial.printf("Connecting to %s\n", ssid);     //  "Подключение к "
  WiFi.begin(ssid, password);
  WiFi.config(staticIP, gateway, subnet);
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  Serial.print("Connected, IP address: ");       //  "Подключено, IP-адрес: "
  Serial.println(WiFi.localIP());
}

void loop() {}

Пример данных, которые могут быть показаны в мониторе порта:

Connecting to sensor-net
.
Connected, IP address: 192.168.1.22

Станции с статическими IP-адресами, как правило, быстрее подключаются к сети. У кода выше подключение занимает примерно 500 мс (в мониторе порта показана только одна точка). Дело в том, что получение IP-настроек при помощи DHCP-клиента отнимает время, а в нашем случае этот шаг попросту пропущен. Если во всех трех параметрах (local_ip, gateway и subnet) указать «0.0.0.0», это снова активирует DHCP. Снова подключитесь к устройству, чтобы получить новые IP-адреса.

Управление подключением

reconnect()

Повторное подключение станции к точке доступа. Чип отключается от точки доступа, а затем инициирует с нею повторное подключение.

WiFi.reconnect()

Примечания:

1. Станция должна быть уже подключена к точке доступа. Если не подключена, функция ничего не сделает и вернет false.
2. Если функция вернула true, это значит, что последовательность действий для подключения была начата успешно. После этого пользователь должен проверить статус подключения и подождать, пока функция не вернет WL_CONNECTED:

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

disconnect()

Выставляет текущие SSID и пароль на null, а затем отключает станцию от точки доступа.

WiFi.disconnect(wifioff)

Параметр wifioff – опциональное булево значение. Если выставить в нем true, это выключит режим станции.

isConnected()

Возвращает true, если станция подключена к точке доступа, или false, если не подключена.

WiFi.isConnected()

setAutoConnect()

Настраивает чип, чтобы он при включении питания автоматически подключался к последней использованной точке доступа.

WiFi.setAutoConnect(autoConnect)

Параметр autoConnect – опциональный. Если выставить в нем false, автоматическое подключение будет деактивировано. Если пропустить его или выставить на true, автоматическое подключение будет активировано.

getAutoConnect()

Это функция-компаньон для setAutoConnect(). Она возвращает true, если у модуля активировано автоматическое подключение к последней использованной точке доступа, и false, если деактивировано.

WiFi.getAutoConnect()

setAutoReconnect()

Задает, сделает ли модуль, будучи отключенным, попытку повторного подключения к точке доступа.

WiFi.setAutoReconnect(autoReconnect)

Если параметр autoReconnect выставлен на true, модуль сделает повторное подключение, а если false, то нет.

Примечание: Если вызвать функцию setAutoReconnect() при отключенном модуле, он не подключится к точке доступа. В таком случае используйте reconnect().

waitForConnectResult()

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

WiFi.waitForConnectResult()

Эта функция может вернуть следующие значения:

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

Получение информации о настройках

macAddress()

Извлекает данные о MAC-адресе стационарного интерфейса ESP8266.

WiFi.macAddress(mac)

Параметр mac – это указатель на место в памяти (массив uint8_t размером в 6 элементов), где хранится MAC-адрес. Такое же значение указателя возвращается самой функцией.

Пример кода:

if (WiFi.status() == WL_CONNECTED)
{
  uint8_t macAddr[6];
  WiFi.macAddress(macAddr);
  Serial.printf("Connected, mac address: %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
            //  "Подключено, MAC-адрес: "
}

Пример данных, которые могут быть показаны в мониторе порта:

Mac address: 5C:CF:7F:08:11:17

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

WiFi.macAddress()

Пример кода:

if (WiFi.status() == WL_CONNECTED)
{
  Serial.printf("Connected, mac address: %s\n", WiFi.macAddress().c_str());
            //  "Подключено, MAC-адрес: "
}

localIP()

Извлечение IP-адреса стационарного интерфейса ESP8266.

WiFi.localIP()

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

Примера кода:

if (WiFi.status() == WL_CONNECTED)
{
  Serial.print("Connected, IP address: ");
           //  "Подключено, MAC-адрес: "
  Serial.println(WiFi.localIP());
}

Пример данных, которые могут быть показаны в мониторе порта:

Connected, IP address: 192.168.1.10

subnetMask()

Извлечение информации о маске посети из стационарного интерфейса ESP8266.

WiFi.subnetMask()

Чтобы извлечь данные о маске подсети, модуль должен быть подключен к точке доступа.

Пример кода:

Serial.print("Subnet mask: ");
         //  "Маска подсети: "
Serial.println(WiFi.subnetMask());

Пример данных, которые могут быть показаны в мониторе порта:

Subnet mask: 255.255.255.0

gatewayIP()

Извлечение данных об IP-адресе шлюза.

WiFi.gatewayIP()

Пример кода:

Serial.printf("Gataway IP: %s\n", WiFi.gatewayIP().toString().c_str());
          //  "IP-адрес шлюза: "

Пример данных, которые могут быть показаны в мониторе порта:

Gataway IP: 192.168.1.9

dnsIP()

Извлечение данных об IP-адресах DNS-серверов.

WiFi.dnsIP(dns_no)

При помощи параметра dns_no указывается то, IP-адрес какого DNS-сервера вам нужен. Допустимые значения для этого параметра – «0», «1» или никакого. Если параметр не указать, функция вернет IP-адрес первого DNS-сервера.

Примера кода:

Serial.print("DNS #1, #2 IP: ");
         //  "IP-адреса первого и второго DNS-серверов: "
WiFi.dnsIP().printTo(Serial);
Serial.print(", ");
WiFi.dnsIP(1).printTo(Serial);
Serial.println();

Пример данных, которые могут быть показаны в мониторе порта:

DNS #1, #2 IP: 62.179.1.60, 62.179.1.61

hostname()

Извлечение данных об имени хоста, которое DNS-сервер присвоил станции ESP8266.

WiFi.hostname()

Эта функция возвращает данные типа String. По умолчанию имя хоста выражено в формате «ESP_24xMAC», где «24xMAC» – это последние 24 бита MAC-адреса модуля. Но имя хоста можно поменять, использую следующую функцию:

WiFi.hostname(aHostname)

Данные в параметре aHostname могут быть типа char*, const char* или String. Максимальный размер для имени хоста – 32 символа. В зависимости от результата функция возвращает false или true. Например, если ограничение в 32 символа будет превышено, функция вернет false, не присвоив ESP8266 нового имени хоста.

Пример кода:

Serial.printf("Default hostname: %s\n", WiFi.hostname().c_str());
          //  "Имя хоста по умолчанию: "
WiFi.hostname("Station_Tester_02");
Serial.printf("New hostname: %s\n", WiFi.hostname().c_str());
          //  "Новое имя хоста: "

Пример данных, которые могут быть показаны в мониторе порта:

Default hostname: ESP_081117
New hostname: Station_Tester_02

status()

Возвращает статус WiFi-соединения.

WiFi.status()

Эта функция может вернуть следующие значения:

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

Возвращаемый тип данных – это wl_status_t, заданный в этом заголовочном файле.

Пример кода:

#include <ESP8266WiFi.h>

void setup(void)
{
  Serial.begin(115200);
  Serial.printf("Connection status: %d\n", WiFi.status());
            //  "Статус подключения: "
  Serial.printf("Connecting to %s\n", ssid);
            //  "Подключение к "
  WiFi.begin(ssid, password);
  Serial.printf("Connection status: %d\n", WiFi.status());
            //  "Статус подключения: "
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.printf("\nConnection status: %d\n", WiFi.status());
            //  "Статус подключения: "
  Serial.print("Connected, IP address: ");
           //  "Подключено, IP-адрес: "
  Serial.println(WiFi.localIP());
}

void loop() {}

Пример данных, которые могут быть показаны в мониторе порта:

Connection status: 6
Connecting to sensor-net
Connection status: 6
......
Connection status: 3
Connected, IP address: 192.168.1.10

Подробное описание статусов 3 и 6 можно посмотреть в заголовочном файле «wl_definitions.h»:

3 - WL_CONNECTED
6 - WL_DISCONNECTED

Диагностическая информация выше означает, что модуль изначально был отключен от сети, поэтому скетч возвращает статус 6 - WL_DISCONNECTED. Затем модуль был отключен сразу же после вызова функции WiFi.begin(ssid, password). Спустя 3 секунды (об этом можно судить по количеству точек, каждая из которых означает 500 мс) модуль, наконец, подключается к сети и возвращает статус 3 - WL_CONNECTED.

SSID()

Возвращает название WiFi-сети или SSID (от «service set identifier», что значит «идентификатор служебного устройства»).

WiFi.SSID()

Тип возвращаемого значения – String.

Пример кода:

Serial.printf("SSID: %s\n", WiFi.SSID().c_str());

Пример данных, которые могут быть показаны в мониторе порта:

SSID: sensor-net

psk()

Возвращает PSK (от «pre-shared key», т.е. «предварительно выданный ключ»), привязанный к WiFi-сети.

WiFi.psk()

Возвращаемое значение имеет тип данных String.

BSSID()

Возвращает MAC-адрес точки доступа, к которой подключен модуль ESP8266. Этот адрес называют, как правило, BSSID (от «basic service set identifier», что значит «идентификатор базового служебного устройства»).

WiFi.BSSID()

Возвращает указатель к месту в памяти (массив uint8_t размером в 6 элементов), куда сохранен BSSID.

Ниже – альтернативная версия этой функции, у которого возвращаемое значение имеет тип String.

WiFi.BSSIDstr()

Пример кода:

Serial.printf("BSSID: %s\n", WiFi.BSSIDstr().c_str());

Пример данных, которые могут быть показаны в мониторе порта:

BSSID: 00:1A:70:DE:C1:68

RSSI()

Возвращает мощность сигнала WiFI-сети, которую называют, как правило, RSSI (от «received signal strength indication», что значит «показатель уровня принимающего сигнала»).

WiFi.RSSI()

RSSI – это значение в дБм (децибел/милливатт). Тип возвращаемого значения – int32_t.

Пример кода:

Serial.printf("RSSI: %d dBm\n", WiFi.RSSI());

Пример данных, которые могут быть показаны в мониторе порта:

RSSI: -68 dBm

Альтернативные функции для подключения к WiFi

SDK ESP8266 предусматривает альтернативные методы для подключения станции ESP8266 к точке доступа. Аддон ESP8266 для IDE Arduino поддерживает два из них – WPS и Smart Config.

WPS

Функция beginWPSConfig() позволяет подключаться к WiFi-сети при помощи стандарта WPS (от «WiFi protected setup», что значит «защищенная настройка WiFi»). На данный момент (SDK 1.5.4) поддерживается только режим WPS_TYPE_PBC (настройка нажатием одной кнопки).

WiFi.beginWPSConfig()

В зависимости от результата функция вернет true или false (возвращаемое значение имеет тип boolean).

Пример кода:

#include <ESP8266WiFi.h>

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

  Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");
            //  "WiFi переключен в режим станции" :
            //   "Переключиться не удалось!"
  Serial.print("Begin WPS (press WPS button on your router) ... ");
           //  "Запуск WPS (нажмите кнопку WPS на роутере) ... "
  Serial.println(WiFi.beginWPSConfig() ? "Success" : "Failed");
                                     //  "Успешно" : 
                                     //  "Запустить WPS не удалось"
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  Serial.print("Connected, IP address: ");
           //  "Подключено, IP-адрес: "
  Serial.println(WiFi.localIP());
}

void loop() {}

Пример данных, которые могут быть показаны в мониторе порта:

Wi-Fi mode set to WIFI_STA
Begin WPS (press WPS button on your router) ... Success
.........
Connected, IP address: 192.168.1.102

Smart Config

Smart Config (можно перевести как «умная настройка») – это тип подключения модуля ESP8266 к точке доступа, который выполняется путем прослушки специальных пакетов, содержащих SSID и пароль. Для этого у мобильного устройства или компьютера должен быть функционал для трансляции зашифрованных SSID и пароля.

Для Smart Config в библиотеке ESP8266WiFi есть три функции.

Первая – для того, чтобы запустить режим Smart Config, который начнет прослушивать специальные пакеты, содержащие SSID и пароль к точке доступа. В зависимости от результата функция вернет true или false.

beginSmartConfig()

Вторая – для запроса статуса Smart Config, чтобы понять, когда остановить настройку. Возвращает true или false.

smartConfigDone()

Третья – для остановки Smart Config. Очищает буфер, занятый beginSmartConfig(). В зависимости от результата возвращает true или false.

stopSmartConfig()

Более подробно о Smart Config читайте в документации к протоколу ESP-TOUCH, который можно скачать по этой ссылке.