ESP8266:Прошивки/Arduino/Библиотеки/Библиотека ESP8266WiFi/Класс станции
Класс станции в библиотеке ESP8266WiFi[1]
Количество функций, которые 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()
Примечания:
- Станция должна быть уже подключена к точке доступа. Если не подключена, функция ничего не сделает и вернет false.
- Если функция вернула 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, который можно скачать по этой ссылке.
