WebServer на ESP32: ручки-эндпоинты и управление светодиодом

Гирлянда на балконе два года жила на сыром WiFiServer из базового урока про мини-сервер: прочитать запрос-строку, найти indexOf("GET /on"), собрать ответ построчно. Работало, но каждая новая команда добавляла ещё один if и очередную копипасту заголовков ответа; к четвёртой ручке — свет, полив, подсветка аквариума, температура — скетч распух настолько, что я сам путался, какая ветка за что отвечает. Тогда я переехал на WebServer.h: класс, который входит в пакет плат ESP32 и держит пару «маршрут — обработчик» в одной строке. Экономия не косметическая: обработчик не парсит запрос руками, не собирает заголовки и не думает про 404 — класс делает рутину, мне остаётся бизнес-логика. Из четырёх маршрутов в скетче ниже ни один не знает про заголовки HTTP — это ровно тот уровень абстракции, которого мне не хватало.

Разбор сырого HTTP — то, что браузер реально шлёт плате, — остаётся в уроке про первый HTML из скетча, маршруты с параметрами вроде /set?bright=120 — отдельная история в уроке про маршруты и обработчики. Здесь минимум, с которого я советую начинать любой пульт: три эндпоинта — корень, /led/on, /led/off, страница с кнопками и одна дисциплина на весь проект — handleClient() в каждом проходе loop(). На этом минимуме у меня держится половина плат с веб-мордой, и он же — фундамент для всего остального.

Про скорость, чтобы вы понимали бюджет. Секундомер из millis() вокруг server.send() показывал на моём DevKit 6-12 мс на страницу-пульт и до 40-50 мс, когда WiFi-стек был параллельно занят держанием связи. Клик по кнопке в браузере телефона отрабатывает быстрее моргания: это локальный HTTP без выхода за роутер, и ни один облачный сервис такой отзывчивости не даст. Если у вас ответ приходит через секунды — где-то в loop() притаился delay, и это уже сюжет грабли ниже. Замер я держу прямо в обработчике на время отладки: пять строк, а правда на экране, а не в ощущениях.

Маршрут в WebServer.h — это вызов server.on(путь, функция): пришли по /led/on — выполнится vkl(), пришли по /led/off — vykl(). Внутри обработчика ровно два дела: перевернуть состояние платы и ответить — server.send(200, "text/html", stranica()). Первый аргумент — код статуса, второй — MIME-тип, третий — тело страницы. Состояние я держу в глобальной булевой, а страницу рисует функция, которая читает её на каждый запрос: пульт всегда показывает то, что плата делает прямо сейчас, а не то, что делала пять минут назад.

Кнопка на странице — обычная ссылка вида <a href='/led/on'><button>ВКЛЮЧИТЬ</button></a>: браузер кликом уходит по пути, плата переворачивает светодиод и отдаёт свежую страницу. Механика та же, что у ссылок в уроке про управление светодиодом из браузера, только ссылки здесь висят на именованных маршрутах, а не на разборе подстрок. JavaScript для переключения не нужен: без него страница честнее и дешевле, а до живых данных без перезагрузки доберётесь через WebSocket-поток в браузер — там другая ступень.

Один нюанс смущает всех на второй минуте: после открытия страницы в журнале два запроса вместо одного — браузер сам просит /favicon.ico, иконку сайта. У платы её нет, и честнее всего отвечать коротким 404 через server.onNotFound(): иконку всё равно никто не ждёт, а плодить для неё целую страницу — гонять лишние байты. Базовый урок отдавал favicon главную страницу — безвредно, но с WebServer.h я всегда вывожу 404: в журнале сразу видно мусорные пути и опечатки в URL.

Порядок в setup() жёсткий: WiFi.begin(), статусный цикл, регистрация маршрутов, server.begin(). Обработчики при этом не бегут сами по себе — их по очереди вызывает server.handleClient() из loop(), когда в сокет кто-то постучался. Это функция-диспетчер: прошла по таблице маршрутов, нашла совпадение, вызвала обработчик, отправила ответ, вернулась. Весь проход занимает единицы миллисекунд, поэтому звать handleClient() можно хоть тысячу раз в секунду — без клиентов он стоит почти ничего. Регистрация маршрутов в setup — это просто заполнение таблицы: сами функции не выполняются, пока диспетчер их не позовёт.

Отсюда правило, которое я считаю главным в этом уроке: в loop() нет ничего, что могло бы задержать handleClient(). Никаких delay(), никаких длинных циклов — периодические дела планирую по millis(), как в уроке про millis вместо delay. Балконный скетч держит в loop() три строчки — handleClient, проверка таймера опроса температуры, чтение кнопки, — и каждая укладывается в пару миллисекунд, потому страница отвечает мгновенно при любом раскладе. Опрос датчика по таймеру раз в десять секунд живёт в той же таблице планировщика, что и мигание светодиода статуса, — два if по millis(), и веб-морда больше ничему не мешает.

Имена путей — половина удобства. /led/on и /led/off читаются сами по себе: в журнале, в закладках и в истории браузера видно, что за команда прошла, — набор вроде /1 и /2 экономит шесть символов и стоит вечер расшифровки через полгода. Когда плата обслуживает и человека, и скрипт из Node-RED, я вывожу машинные ручки под префикс /api/: человек кликает /led/on, скрипт дёргает /api/led/on — логи не путаются. Экономия на одной букве в имени пути не окупает ни одной минуты отладки.

Сколько клиентов выдержит такой сервер: он однопоточный, второй браузер ждёт, пока ответит первый. Для пульта с ответами за 5-50 мс это невидимо, но страницу я держу в пару килобайт — текст и кнопки, никаких картинок и тяжёлых стилей: десятикилобайтная графика на трёх клиентах превращает плату в очередь. Мой балконный пульт весит около девятисот байт и открывается быстрее, чем мигает индикатор WiFi. Отсюда и правило про тело ответа: одна страница или одна строка статуса — не обе вещи разом.

Перезагрузка страницы после клика — обычная цена за пульт без JavaScript. Но помните: пульт на GET-ручках повторяет последнюю команду при обновлении страницы кнопкой F5. Для светодиода безвредно — включённый свет не сломается, — а для реле замка или калитки это уже сюжет: там я либо перехожу на POST с формой, либо вешаю одноразовый токен в путь. Правило у меня простое: GET-ручки — только для идемпотентных действий, повтор которых безвреден.

Про границы: сервер без пароля прекрасен внутри квартиры и не должен выходить наружу. Проброс 80-го порта на роутере открывает пульт всему интернету — боты сканируют диапазоны постоянно, и голый сервер они находят за считанные минуты. Если управление нужно с работы, я либо поднимаю VPN до дома, либо добавляю в путь ключ вида /led/on?k=sekret и проверяю его в обработчике — костыльно, но честнее открытой двери. А чтобы адрес платы вообще перестал быть набором цифр — добро пожаловать в следующий урок про имя kotel.local.

Маршрутов WiFi в движке симулятора нет, и притворяться я не буду: ту же диспетчеризацию крутим на поддерживаемом API. Путь из браузера заменяет строка из Serial-монитора, а функция otvet() работает ровно как handleClient — сверила путь с таблицей, выполнила дело, ответила. На живой плате эту же строку шлёт браузер, когда вы кликаете кнопку страницы из скетча выше, — логика совпадает до символа, меняется только транспорт.

Сценарий проверки короткий. Отправьте в монитор строку / — увидите пульт и текущее состояние света; пошлите /led/on — светодиод зажжётся, а в журнале появится метка времени ответа; попробуйте кривой путь и /favicon.ico — получите 404. Секундомер в модели считает те же 5-50 мс, что и живая плата, только «сеть» здесь помещается в один вызов функции. Если сомневаетесь в каком-то маршруте, прогоните все пути подряд — на живой плате я делаю то же самое скриптом из пяти curl-команд перед тем, как считать пульт готовым.