PubSubClient: установка библиотеки и первый скетч

Мой первый скетч с MQTT компилировался с первого раза, загружался, печатал в Serial бодрые строки — и брокер не видел ни одного сообщения. Час я менял адрес брокера, перезапускал Mosquitto, перепрошивал плату. Ошибка была в одном слове: я писал client.publish(...) и не смотрел, что он вернул. А возвращает publish значение bool: единица — пакет ушёл, ноль — пакет не ушёл, и никакой другой индикации нет. Ноль мой скетч печатал исправно, час подряд, прямо мне в лицо.

С тех пор у меня правило: каждый вызов, который может не сработать, — connect, publish, subscribe — проверяется на месте. Диагноз потом занял секунды: в логе брокера не было ни одного подключения с именем моей платы, а publish молча возвращал ноль. Один print после каждого вызова — и время поиска сжимается с часа до минуты; эта привычка стоит одной строки кода. PubSubClient — библиотека честная: она молчит, когда ей что-то не нравится, но всё говорит в кодах возврата и в client.state(), просто читать её надо уметь.

Весь этот урок я делаю на ESP32, но на Uno с Ethernet-шилдом W5500 всё то же самое: меняется только сетевой класс под обёрткой. Пара слов о том, что у нас под ногами: брокер из прошлого урока уже слушает 1883-й порт на 0.0.0.0, плата уже умеет подключаться к Wi-Fi — я беру за основу каркас из урока про подключение ESP32 к роутеру. Дальше только MQTT. План урока: ставим библиотеку, собираем минимальный рабочий скетч — connect, publish, loop — и учимся диагностировать отказ за минуту, а не за час.

Библиотека ставится штатно: Tools — Manage Libraries — в поиске PubSubClient — ставим ту, что от Nick O'Leary, на момент моих последних проектов версия 2.8. Она тянет за собой примеры — File — Examples — PubSubClient, — и самый полезный из них называется mqtt_esp8266: не пугайтесь имени, на ESP32 он работает с той же логикой, там меняется только заголовок Wi-Fi. Установка из ZIP с GitHub ничем не лучше, а обновляться через менеджер удобнее — установка библиотек в один клик была отдельным уроком, там и вспомните, если менеджер ругнётся.

Одно знание, которое стоит получить до скетча: PubSubClient не умеет в сеть сам. Ему нужен уже готовый клиентский класс — WiFiClient на ESP32/ESP8266, EthernetClient на шилдах W5100/W5500. Поэтому в скетче всегда пара: сетевой клиент и обёрнутый в него PubSubClient. Именно эта пара — причина, почему библиотека жива больше десяти лет: она не привязана к радиомодулю, и под неё подходит всё, что умеет TCP, включая экзотику вроде SIM800 через TinyGsm.

И тонкость для перфекционистов: PubSubClient разговаривает на протоколе 3.1.1, а не на 5.0 — свежие фичи вроде reason-кодов и properties ему недоступны. Для домашней телеметрии это без разницы: брокеры совместимы со всеми версиями, и мой Mosquitto из прошлого урока принимает 3.1.1 не моргнув.

После установки загляните в примеры — File, Examples, PubSubClient. Кроме mqtt_esp8266 там живут mqtt_reconnect_nonblocking с неблокирующим переподключением и mqtt_publish_in_callback с разбором входящих. Листать их полезно как справочник: автор писал примеры под себя, и в них видны все четыре-пять приёмов, которыми я пользуюсь до сих пор. Версию менеджер показывает прямо в карточке; за последней я не гонюсь — 2.8 стабильна годами.

Разбор по строчкам, потому что здесь каждая строка — чьё-то набитое ребро. setServer() вызывается один раз в setup: адрес и порт брокера. connect() принимает один обязательный аргумент — имя клиента, оно обязано быть уникальным на весь брокер: два устройства с одним clientId начнут выкидывать друг друга, и соединение будет жить секунду. У меня имена честные: first-sketch для урока, esp32-balcony для балкона, dacha-pump для насоса.

client.loop() — сердце библиотеки, и вызывать его нужно в каждом обороте loop без пауз. Внутри него две работы: уходит keepalive-пинг (окно по умолчанию 15 секунд — при длинных delay брокер отрежет соединение, об этом был подробный разбор в уроке про публикацию с ESP32), и разбираются входящие пакеты — то, ради чего живут подписки. Забытый loop — вторая по популярности причина «сначала работает, потом молчит».

Публикация в примере проверена с двух сторон: перед publish смотрим client.connected() — жива ли связь, — а после publish смотрим код возврата: ушёл ли пакет. Число с условием: publish возвращает 0 не только при мёртвой связи, но и при переполнении буфера — сообщение длиннее 256 байт по умолчанию молча не уходит; длинные JSON отправляются после client.setBufferSize(512) в setup.

Что публиковать и в каком виде — вопрос, на который я отвечаю правилом: числа строками, единицы в имени топика, никаких составных сообщений там, где хватает одного числа. 45 в home/humidity читается любой системой, а конструкция вида «h=45;p=60» придётся парсить руками и на плате-подписчике, и в дашборде. Если единицы важны — они едут в топике: home/temp/c в цельсиях, home/temp/f в фаренгейтах. Разница между «45» и «45.0» для брокера — просто два разных текста; подписчик на Arduino превращает строку обратно в число через toInt() или atof(), и для целых значений это работает ровно.

Если connect вернул ноль, внятного текста ошибки не будет — будет число из client.state(). Таблица ниже — моя шпаргалка, которую я перенёс на стикер к монитору. Логика чтения простая: отрицательные числа — проблемы транспорта, сети; положительные — проблемы логики протокола, и брокер честно назвал причину отказом в CONNACK.

Разберу диагностику как сценарий. Печатаем state после неудачного connect: минус два — сеть есть, а соединения нет, идём в конфиг брокера смотреть listener; минус четыре — адрес или порт, пингуем малину; четвёрка — пароль; пятёрка — анонимов не пускают, а мы их и не представили. Три минуты по этому дереву — и причина найдена. Без кода состояния те же три минуты превращаются в три часа блужданий: брокер молчит одинаково на все ошибки. Держите таблицу под рукой первые две недели — потом коды запомнятся сами.

Скелет готов и проверен: connect с диагностикой, publish с кодом возврата, loop без пауз. Дальше в разделе всё наращивается на этот каркас: retained-сообщения и last will, чтобы дом узнавал о статусе плат мгновенно, порт 8883 с TLS, когда брокер выйдет наружу, и callback с подписками, когда команды пойдут в обратную сторону. Если захочется разобрать каркас до костей — в уроке про публикацию с ESP32 этот же скетч вырастает во взрослого: с reconnect-логикой и millis-таймерами из урока про millis вместо delay. А если брокера у вас ещё нет — вернитесь на шаг назад, к установке Mosquitto: без собственной доски объявлений проверять скетч будет не на что. И проверка на владение: не глядя в код, назовите три кода state из таблицы — если выходит, скетч вы уже чувствуете, а не просто переписали.