Esp-Monitor: архитектура и развертывание self-hosted IoT-платформы для микроконтроллеров ESP

Одним из самых вдохновляющих моментов в разработке микроконтроллерных устройств является их первая установка и запуск в локальной сети. И этот же момент может превратиться в настоящий ад, когда процедуру приходится повторять десятки или сотни раз. Множество однотипных контроллеров, развертываемых одновременно, требуют часов монотонного конфигурирования — времени, которое любому инженеру хотелось бы провести с большей творческой пользой.

Для решения этой проблемы был разработан легкий open-source сервис с открытым исходным кодом и условным названием «esp-monitor».

Проблема конфигурации и выбор протокола

Одним из самых популярных (и что немаловажно, дешевых — стоимостью около $2) микроконтроллеров является Wemos D1 Mini на базе чипа ESP8266. Он быстрый, в меру надежный и обладает широчайшей экосистемой дополнительных модулей. Именно такие контроллеры массово используются в бытовой технике и DIY-проектах благодаря колоссальным возможностям внедрения в датчики и системы домашней автоматизации.

Однако они же являются одними из самых неудобных в конфигурировании: базово из беспроводных интерфейсов «на борту» присутствует только Wi-Fi. А значит, подключение к новой беспроводной точке доступа превращается в очередные «танцы с бубном».

Казалось бы, задачу можно решить классическим пробросом портов наружу из локальной Wi-Fi сети. Но в большинстве сценариев это тупиковый путь:

• требуется административный доступ к Wi-Fi роутеру;

• необходимо обеспечивать эксклюзивный доступ к каждому устройству, спрятанному за NAT;

• отсутствует единый центр управления семейством устройств — к каждому девайсу придется обращаться индивидуально по его собственному адресу;

• возникают постоянные вопросы к безопасности системы.

Гораздо более изящное и практичное решение — использование внешнего MQTT-брокера за пределами локальной сети. Устройство само подключается к брокеру, передает ему текущее состояние и ожидает от него исполняемые команды.

MQTT (Message Queuing Telemetry Transport) — это очень легкий двунаправленный протокол для передачи телеметрии. В отличие от WebSockets, он не требует удержания постоянного тяжелого соединения, что делает его идеальным стандартом для IoT. Запустить MQTT-брокер можно на любом микрокомпьютере (включая Raspberry Pi 3), арендовать в облаке или развернуть на базе публичных бесплатных сервисов.

Архитектура Esp-Server

Инструмент управления esp-server — это легковесный сервис, написанный на Go со встроенной базой данных SQLite. Его можно развернуть в облаке на любой системе с поддержкой Docker либо собрать из исходного кода везде, где есть среда выполнения Go (Windows, Linux, macOS).

Сервер централизованно управляет устройствами, автоматизируя сложные конфигурации, которые включают в себя настройки Wi-Fi, MDNS, стандартный стек SSDP (с HTTP-портом для чтения данных), а также параметры подключения к MQTT-брокеру. Всю остальную логику инженер может легко реализовать стандартными средствами MQTT.

В репозитории проекта, помимо серверной части, содержатся прошивки для ESP8266 и ESP32, которые легко адаптируются под любые задачи — от простого датчика до умного хаба домашней автоматизации.

Первичная посадка в сеть и API

Пользователь взаимодействует с esp-server либо через публичное REST API, либо через веб-интерфейс в браузере. Мобильные приложения удобнее, но веб-интерфейс выигрывает в универсальности.

Для сопряжения микроконтроллеров с локальной сетью можно использовать нативное iOS-приложение(исходный код которого также есть в репозитории). В нем достаточно один раз прописать конфигурационные параметры, а затем отправлять их на устройство, находящееся в режиме точки доступа (AP), по нажатию одной кнопки. Однако политика Apple усложняет жизнь инженерам: для сборки приложения потребуется среда разработки Xcode и аккаунт разработчика.

Для тех, кто использует Android или предпочитает универсальные методы, предложен альтернативный и максимально простой способ — отправка параметров через обычный cURL-запрос (POST REST):

Bash

curl -X POST 192.168.4.1:80/config 
  -H "Content-Type: application/json" 
  -d '{
  "WIFI_SSID": "<wi-fi SSID>",
  "WIFI_PASS": "wi-fi pass",
  "MDNS": "<mdns identifier, e.g. local.esp>",
  "SSDP": "SSDP name",
  "HTTP_PORT": "80",
  "MQTT_HOST": "<HOST>",
  "MQTT_PORT": "1883",
  "MQTT_USER": "",
  "MQTT_PASS": "",
  "MQTT_ROOT": "<root topic>"
  }'

Пример этого запроса находится в каталоге ./clients/curl проекта.

Важные нюансы работы с устройствами:

1. Первый запуск: При первом включении ESP-устройство поднимает собственную точку доступа (Access Point) по стандартному адресу 192.168.4.1 (в сетях esp8266-setup или esp32-setup в зависимости от чипа). Задача инженера — отправить REST-запрос на этот адрес. После успешного получения параметров устройство перезагружается, подключается к домашней Wi-Fi сети и связывается с MQTT-брокером.

2. Аварийный сброс: Если что-то пошло не так, сбросить некорректную конфигурацию можно физически — удерживая кнопку на пине D4 более 3 секунд.

3. Идентификация (SSDP name): Это ключевое поле, по которому устройство идентифицируется на стороне esp-server. Если его оставить пустым, имя сгенерируется автоматически на основе типа чипа и его MAC-адреса. При необходимости использовать Unix-время вместо MAC-адреса можно переопределить метод createMacAddress() прямо в прошивке.

4. MQTT_ROOT: Если вы контролируете собственный MQTT-брокер, здесь достаточно указать короткое имя (например, root). Если же используется публичный брокер вроде test.mosquitto.org, в качестве корня лучше прописать уникальный идентификатор (например, UUID, сгенерированный на специальном сайте), чтобы ваши топики не пересекались с чужими.

Эволюция проекта: от статического импорта к интерактивности

Изначально предполагалось, что базовый сценарий будет выглядеть так: инженер заносит конфигурации контроллеров в таблицу Excel, экспортирует её в .csv, загружает на сервер, а при подключении устройства видит статус успешного сетапа.

Однако практика показала, что простого мониторинга списка недостаточно — конфигурацию устройств хочется менять оперативно и «на лету».

Важно понимать: сами ESP-устройства ничего не знают про существование esp-server — они работают только с MQTT-брокером. В свою очередь, esp-server тоже не знает внутренней схемотехники ESP — он лишь читает и пишет в топики, определенные в конфигурационном файле сервера .env.

Для обмена данными используются два основных топика:

• <root>/<ssdp_name>/state — отправка текущего состояния пинов от ESP к серверу.

• <root>/<ssdp_name>/action — передача управляющих команд от сервера к ESP.

В прошивке установлено ограничение на отправку данных в топик state — не чаще одного раза в секунду, чтобы не перегружать сеть (при необходимости лимит можно снять). Сервер считает устройство активным (online), если от него поступали сообщения в течение последней минуты. Поскольку ESP32 аппаратно стабильнее и реже страдает от «дребезга контактов» без нагрузки, важно предусмотреть, чтобы прошивка ESP32 отправляла хотя бы минимальный пинг-пакет раз в минуту для поддержания статуса сети.

Интерфейс и безопасность

Добавление новых устройств происходит автоматически: как только сервер видит новое сообщение в топике <root>, он извлекает имя <ssdp_name> и регистрирует новое устройство в базе данных SQLite.

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

Поскольку сервер должен смотреть в интернет, но права на управление им должны быть монопольными, была реализована простая и надежная авторизация в стиле Linux:

• В конфигурационном файле сервера задается секретный параметр xtoken.

• Кто имеет физический доступ к конфигурационному файлу сервера («доступ к телу») — тот и управляет системой. Пользователь вводит данный токен на странице авторизации, и сессия сохраняется в браузере.

Возможности авторизованного пользователя:

• Просмотр расширенного реестра (дата активации, время старта, дата последнего обновления).

• Фильтрация устройств по имени SSDP или MDNS (удобно для администрирования разных семейств устройств на одном сервере).

• Импорт устройств через .csv на стартовой странице.

• Переход в детальную карту устройства: просмотр состояния пинов, истории последних событий (action), удаление неактивных девайсов (находящихся в таймауте).

• Конфигурирование («Configure device»): Возможность переопределить любые параметры устройства прямо с экрана мобильного телефона.

Конфигурации развертывания (Deploy Tiers)

И на этом мы только подходим к «кроличьей норе» архитектуры проекта. Esp-Monitor поддерживает 5 основных конфигураций развертывания в зависимости от масштаба и задач вашей сети:

Что выбрать: Docker или Kubernetes?

В репозитории папка deploy разделена на два направления:

1. docker — содержит конфигурационные файлы для развертывания ярусов от Tiny до Large.

2. k8s — содержит скрипты для настройки локального окружения Minikube и манифесты запуска кластера Kubernetes.

Плюсы и минусы Kubernetes:

• Достоинства: Самовосстанавливающаяся и легко масштабируемая платформа. Если один из сервисов падает — K8s перезапускает его автоматически. Компоненты можно разносить на разные физические серверы или запускать десятки реплик воркеров под разные сегменты данных. При этом все упаковано в единые манифесты.

• Недостатки: Высокий порог входа. Потребуется потратить «пару килограмм нервных клеток» на базовую настройку.

Примечание: Для упрощения в проект включены готовые автоматизированные скрипты установки. Вам не придется глубоко погружаться в дебри Docker CLI или Kubernetes API — развертывание и перезапуск происходят буквально парой команд. Кроме того, Minikube из коробки предоставляет удобный веб-дашборд.

Если вы выберете классический Docker, вы получите другие преимущества: готовые легковесные образы на Docker Hub собраны сразу под три архитектуры (amd64, arm64 и arm). Это позволяет запускать систему на ПК, Mac с чипами Apple Silicon и энергоэффективных платах уровня Raspberry Pi.

Как это устроено внутри: Kafka и воркеры (Medium+)

Вы могли заметить, что сам по себе esp-server хранит лишь последнее состояние пинов и последнюю команду. Но если вы выбираете ярус Medium и выше, раскрывается вся мощь архитектуры: esp-server транслирует абсолютно все события в Kafka. Там они могут храниться и накапливаться неделями.

На данный момент в Kafka предопределены 5 топиков:

1. root — системные события (например, запуск самого esp-server).

2. logs — диагностические сообщения, ошибки, логи подключений к брокеру и шине.

3. pins — детальная хронология изменения состояний пинов микроконтроллеров.

4. actions — отправленные команды и обновления конфигураций.

5. anomalies — аномалии в работе устройств, выявляемые внешними обработчиками.

В топик anomalies пишет специализированный сервис — ai-worker.

Всего в проекте из коробки поставляется три типа воркеров:

• kworker — строит агрегированные таблицы, отображая изменения состояний пинов ESP в реальном времени.

• ai-worker — отправляет потоковые агрегированные данные на анализ искусственному интеллекту для поиска аномалий и пишет результаты обратно в Kafka.

• hworker — забирает зафиксированные аномалии из Kafka и передает их на следующий уровень бизнес-логики (например, в сценарии автоматизации платформы n8n).

Благодаря такой распределенной схеме воркеры можно масштабировать горизонтально: запустить ровно столько экземпляров, сколько партиций создано в топиках Kafka, распределив нагрузку. Исходный код всех воркеров находится в каталоге services и полностью открыт для кастомизации.

Осциллограмма пинов в реальном времени (Large+)

Для детального анализа физических показателей датчиков используется связка Vector + VictoriaMetrics + Grafana.

Агент Vector читает «сырые» данные об изменении пинов из Kafka, преобразует их во временные ряды (Time Series) и пишет в высокопроизводительную СУБД VictoriaMetrics. Подключив к ней Grafana, вы можете строить красивые графики, отслеживать дребезг контактов и создавать полноценные инженерные дашборды мониторинга вашей квартиры или производства.

Быстрый запуск

Требования:

1. Установленный Docker (актуально и для запуска Kubernetes через Minikube).

2. Настройка окружения: В каталогах deploy/docker и deploy/k8s находится файл my.env.example. Скопируйте его с именем .env и заполните параметры (токены, адреса брокеров) по аналогии с примерами внутри файла.

Команды запуска:

• Tiny: docker compose -f deploy/docker/tiny.yaml up -d

• Small: docker compose -f deploy/docker/small.yaml up -d

• Medium: docker compose -f deploy/docker/medium.yaml up -d

• Large: docker compose -f deploy/docker/large.yaml up -d

• Huge (Kubernetes):

  1. Выполните скрипт инициализации: sh ./setup-k8s-cluster.sh

  2. Запустите кластер скриптом en-start-cluster или ru-start-cluster (это простые bash-скрипты, структуру которых вы можете изучить в текстовом редакторе).

  3. Обратите внимание: При запуске Minikube-туннеля система попросит ввести пароль sudo. Это необходимо для проброса (маппинга) внутренних портов кластера на ваш хост-компьютер, чтобы вы могли открыть веб-интерфейсы esp-server, Grafana, Kafdrop и Minikube Dashboard в обычном браузере.

Документация и исходный код

Проект детально документирован: практически в каждой папке находится свой файл README.md. В каталоге docs/arch представлена подробнейшая архитектурная документация, состоящая из 11 глав на русском и английском языках.

Проект активно развивается, и его исходный код полностью открыт.

• GitHub Репозиторий: https://github.com/DemonSoft/esp-monitor.git