Начало работы

Установка SDK (ядра) для esp

Библиотека работает на актуальных версиях SDK. Не рекомендуется ставить версии ниже указанных в скобках. Ссылки для менеджера плат прилагаю

• ESP8266 v2.7+ https://arduino.esp8266.com/stable/package_esp8266com_index.json
• ESP32 v2+ https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Platformio

В свежих версиях в platformio.ini нужно добавить строку

lib_ldf_mode=deep

это подтягивает все необходимые зависимости

Режим работы WiFi

ESP с веб-интерфейсом может работать в обоих режимах WiFi:

• В локальной сети: esp подключается к роутеру, к этому же роутеру подключается смартфон/компьютер
• В режиме точки доступа: смартфон/компьютер подключается к esp

Нужно вызвать portal.start() для запуска сервера после организации связи в программе. Библиотека сама определит режим работы esp и настроит сервер.

Подключение к роутеру

  WiFi.mode(WIFI_STA);
  WiFi.begin("login", "pass");
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println(WiFi.localIP());
  // ...
  portal.start();   // запускаем портал

Для подключения к порталу нужно зайти в браузере на IP адрес платы, который выдал ей роутер. В примере выше этот адрес выводится в монитор порта.

Обнаружение mDNS

В версии 2.0 библиотеки появилась встроенная возможность запуска функции обнаружения mDNS: при запуске портала передаём имя без пробелов, например portal.start("my_esp"). Теперь для открытия портала вместо IP адреса можно использовать имя.local, из предыдущего примера - http://my_esp.local/. Данная фича работает на:

• Устройствах Apple
• Android 12+
• Windows 10+

Для старых версий ОС:

• Windows - установить утилитку Bonjour от Apple, ссылка на официальный сайт
• Android - скачать из Play Market приложение Service Browser, открыть пункт _http._tcp. (World Wide Web HTTP) и увидеть там IP адрес платы напротив указанного имени хоста

Создание ярлыка

Чтобы не вводить каждый раз IP адрес платы или её url, можно не просто добавить страницу веб-интерфейса в закладки, а сделать ярлык, как у приложения. У браузера Chrome это делается следующим образом:

Полученный ярлык открывает ваш веб-интерфейс в отдельном окне, это очень удобно!

Создание точки

  WiFi.mode(WIFI_AP);
  WiFi.softAP("My Portal");
  // ...
  portal.start();   // запускаем портал

Библиотека сама запустит DNS сервер для работы в таком режиме. На стандартных настройках IP адрес для подключения будет 192.168.4.1

Защита паролем

С версии 2.1 появилась защита веб-интерфейса паролем: нужно авторизироваться для отображения страницы. Для подключения авторизации достаточно вызвать функцию и указать логин-пароль

portal.enableAuth("login", "password");

Также авторизацию можно отключить:

portal.disableAuth();

Тикер

В GyverPortal используется стандартная библиотека ESP8266WebServer, поэтому для обеспечения работы сервера нужно вызывать portal.tick() в основном цикле программы loop(). Функция возвращает true, если сервер запущен в данный момент.

Подключение обработчиков

Взаимодействие между платой и браузером происходит по следующему сценарию: на esp запщуен сервер, браузер является клиентом.

• При открытии портала в браузере esp отправляет страницу, которая собирается в подключенной функции из компонентов конструктора. Нужно создать функцию вида void f() и подключить её в библиотеку - portal.attachBuild(f).
• При действиях пользователя (нажал на кнопку) или скриптов со стороны браузера (запрос данных) esp получает запрос, который можно обработать в подключенной функции. Нужно создать функцию вида void f() и подключить её в библиотеку - portal.attach(f).

Минимальный код

GyverPortal portal;

void build() {
  // конструктор страницы
}

void action() {
  // опрос действий
}

void setup() {
  // подключаемся к сети
  portal.attachBuild(build);
  portal.attach(action);
  portal.start();
}

void loop() {
  portal.tick();
}

В этом сценарии объект portal создан глобально и может вызываться в любом месте программы.

Минимальный код (локально)

В этом сценарии объект портала создан локально, внутри функции. Функции-обработчики действий и конструктора должны содержать переданный по ссылке объект портала, чтобы работать вне области определения!

void build(GyverPortal &p) {
  // конструктор страницы
  // здесь переменная p является ссылкой на portal (ниже)
  // можно обращаться к ней точно так же, if (p.uri())
}

void action(GyverPortal &p) {
  // опрос действий
  // здесь переменная p является ссылкой на portal (ниже)
  // можно обращаться к ней точно так же, if (p.click())
}

void f() {
  GyverPortal portal;
  portal.attachBuild(build);
  portal.attach(action);
  portal.start();

  while (portal.tick());
}

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