MQTT

Экран MQTT — клиент MQTT для просмотра брокера и изменения того, что в нём хранится. Подключитесь, и по умолчанию он подпишется на #: все топики, которые есть у брокера, собираются в дерево с последним значением каждого. Отсюда можно опубликовать сообщение, снять retained-значение, сохранить топик как сигнал или превратить его в узел эксперимента.

Signal Lab работает по MQTT 3.1.1 поверх обычного TCP, с QoS 0, 1 и 2 для подписки, публикации и завещания. MQTT 5 и TLS не поддерживаются: брокер, который принимает только mqtts:// или клиентов MQTT 5, недоступен.

Подключение

1. Откройте MQTT.
2. Заполните поля Хост брокера и Порт.
3. Не меняйте поле ID клиента, если брокер не ждёт определённого значения. Поля Пользователь и Пароль заполняйте, только если брокер их запрашивает.
4. Нажмите Подключиться.

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

Поле	Что это	По умолчанию
Хост брокера	IP-адрес или имя хоста брокера	127.0.0.1
Порт	Порт брокера	1883
ID клиента	Имя вашего клиента у брокера. Не должно быть пустым и должно быть уникальным: второй клиент с тем же id вытесняет первого.	signal-lab- и шесть случайных шестнадцатеричных цифр, новые при каждом запуске приложения
Пользователь, Пароль	Отправляются, только если нужны брокеру, — открытым текстом, поскольку TLS нет. Пароль без имени пользователя не отправляется вовсе: MQTT 3.1.1 не может его передать.	пусто
Keepalive (с)	Сколько секунд соединение может молчать. Signal Lab пингует брокера каждую половину этого срока; брокер отключает клиента, который молчит в 1,5 раза дольше. 0 выключает пинги.	60
чистая сессия	Включено: каждое соединение начинается без сохранённых подписок и очереди сообщений. Выключено — просьба к брокеру хранить их для этого id клиента между соединениями.	включено
Подписка при подключении и его QoS	Фильтр, на который подписываются, как только соединение установлено; # — все топики. Пусто — никакого.	#, QoS 0
опубликовать сообщение за меня при обрыве	Дать брокеру завещание (ниже)	выключено

У брокера есть 6 секунд, чтобы принять TCP-соединение, и ещё 6, чтобы ответить на рукопожатие.

Завещание (Last Will)

Завещание — это сообщение, которое брокер хранит за вас и публикует сам, если ваше соединение обрывается без нормального прощания. Так обычно строят признак присутствия: устройство публикует online в свой топик состояния, а его завещание переводит тот же топик в off.

Когда отмечен флажок опубликовать сообщение за меня при обрыве, задайте поля Куда публиковать и Что публиковать (по умолчанию off). Завещание публикуется с QoS 2 и как retained. Без топика завещание не отправляется.

Подписка

Фильтр, заданный для подписки при подключении, подписывается сразу при соединении. Чтобы подписаться на что-то ещё:

1. В поле Добавить фильтр введите фильтр топиков.
2. Выберите его QoS.
3. Нажмите Подписаться или Enter.

Фильтр — это топик с подстановочными символами:

Символ	Что заменяет	Пример
+	ровно один уровень	sensors/+/state подходит к sensors/door/state
#	все уровни ниже, только как последний символ	sensors/# подходит к sensors/door/state и sensors

Список Подписки показывает каждый фильтр с тем, что выдал брокер: qos0, qos1 или qos2 — брокер может выдать меньше, чем вы просили, — либо отказ. Кнопка снять отменяет одну подписку.

QoS	Доставка
0	Не более одного раза: отправлено и забыто
1	Не менее одного раза: подтверждается, может прийти дважды
2	Ровно один раз: двухэтапное рукопожатие; повторная доставка не показывается дважды

Дерево топиков

Каждое пришедшее сообщение попадает в панель Топики — дерево уровней топиков. У топика показаны его последнее значение, R, если это значение retained, и число полученных сообщений, если их больше одного. Щёлкните уровень, чтобы открыть или закрыть его.

• Введите текст в поле над деревом, чтобы показать только топики, в пути или последнем значении которых он есть.
• Над деревом — число топиков, сколько из них хранят retained-значение и, пока есть соединение, брокер, которого вы слушаете.
• Содержимое показывается как текст; байты, не являющиеся UTF-8, отображаются символами замены.
• Кнопка Очистить очищает дерево. Больше ничто его не очищает: при переключении экранов или отключении оно остаётся как есть до закрытия приложения.

Сообщения доходят до экрана пачками, десять раз в секунду. Когда брокер присылает больше 4000 сообщений за десятую долю секунды, самые старые из этой пачки в дерево не попадают и учитываются над ним как «не показано».

Панель топика

Выберите топик со значением, и под деревом появятся поля Значение, QoS, retain, Байты, Сообщений и Последнее. Кнопки панели:

Кнопка	Что делает
Подставить в отправку	Копирует топик, значение, QoS и флаг retain в блок Отправка
Ждать это	Добавляет в открытый эксперимент узел Ждать MQTT на этом топике, на этом брокере, с любым содержимым и тайм-аутом 2000 мс
Снять retained	Удаляет retained-значение (ниже)
Сохранить как сигнал	Сохраняет топик и его последнее значение как сигнал в папке Захвачено

Публикация

1. Подключитесь.
2. В блоке Отправка введите Топик и Полезная нагрузка.
3. Выберите QoS и отметьте retain, если брокер должен сохранить сообщение как значение топика для каждого клиента, который подпишется позже.
4. Нажмите Опубликовать.

Консоль подтверждает каждую публикацию: сразу для QoS 0, а для QoS 1 и 2 — когда брокер её подтвердил. Топик для публикации не бывает пустым и не содержит подстановочных символов: топик с + или # отклоняется до отправки с тем же сообщением, что выдают сигнал, узел и signallab send mqtt, а соединение остаётся как было. Фильтры с подстановочными символами принимает только подписка.

Снятие retained-значения

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

Кнопка Снять retained в панели топика делает именно это: нажмите её, затем Снять?. Она публикует пустое retained-содержимое с QoS 1 по вашему соединению. Она доступна только при установленном соединении и если последнее значение топика — retained. То же можно сделать вручную: пустое поле Полезная нагрузка при отмеченном retain.

WARNING

Снятие меняет состояние брокера сразу для всех клиентов.

В Инспекторе

Когда захват включён, трафик MQTT появляется с протоколом mqtt:

Источник	Что это	Сколько
mqtt	То, что публикует соединение экрана; у пустой retained-публикации вердикт clears retained	каждая
mqtt	Сообщения, которые получает соединение	не более одного за 200 мс
mqtt-send	Публикация, у которой было своё соединение: сигнал, отправленный, пока экран не подключён к брокеру сигнала, узел, signallab send mqtt (вердикт one-shot)	каждая
experiment-wait	Сообщения, которые получает подписка узла Ждать MQTT, за исключением повторно доставленных retained-значений	каждое

Сводка выглядит как topic = payload, с QoS и retained, когда они применимы. См. Инспектор.

Сохранение и повторное использование

• Сохранить как сигнал. Кнопка Сохранить… под блоком Отправка сохраняет в библиотеке сигналов брокер (из Хост брокера и Порт соединения), топик, содержимое, QoS и флаг retain; Ctrl+S в панели публикации делает то же самое и обновляет сигнал, когда панель с ним связана. См. Сигналы.
• Отправка MQTT-сигнала. Пока этот экран подключён к брокеру, названному в сигнале (тот же хост без учёта регистра и тот же порт; 1883, если в сигнале порта нет), сигнал, отправленный из библиотеки, уходит по этому соединению — с его id клиента и учётными данными. Иначе — если соединения нет или оно с другим брокером — сигнал открывает собственное соединение со своим брокером (новый id клиента, без имени пользователя), публикует, ждёт подтверждения, которого требует его QoS, и отключается. Имена не разрешаются, поэтому localhost и 127.0.0.1 считаются разными брокерами. Библиотека не хранит пароль.
• В эксперименте. Сохранённый MQTT-сигнал можно выбрать в группе Сохранённые сигналы в меню Добавить нод эксперимента — он станет узлом Публикация MQTT.

В экспериментах

Узел	Что он делает
Публикация MQTT	Подключается, публикует одно сообщение и отключается — без имени пользователя и пароля, с чистой сессией, в течение 15 секунд. Подробнее
Ждать MQTT	Подписывается при старте запуска и ждёт сообщения по фильтру топиков, содержимое которого подходит; retained-значения, повторно доставленные при подписке, игнорируются. Подробнее
Эмулятор	Собственный MQTT-брокер запуска. Подробнее

Узлы публикации и ожидания не авторизуются, поэтому им нужен брокер, который принимает клиентов без имени пользователя.

Эмулятор брокера

Signal Lab может и сам быть брокером: эмулятор MQTT-брокер передаёт то, что публикуют клиенты, всем подписавшимся — 3.1.1, обычный TCP, QoS 0, 1 и 2, retained-сообщения, завещания, необязательный логин — и отвечает по правилам, как устройство. Направьте на него своё оборудование и этот экран, чтобы тестировать без настоящего брокера. См. Эмуляторы.

Из командной строки

signallab send mqtt публикует одно сообщение по собственному соединению:

signallab send mqtt 127.0.0.1:1883 lab/light/1/set on --qos 1
signallab send mqtt 127.0.0.1:1883 lab/light/1/state "" --retain

✔ lab/light/1/set → 127.0.0.1:1883 · 2 B · qos1

Вторая команда снимает retained-значение. Если порт не указан, брокер на 1883. Учётные данные команда не использует. Код завершения: 0, если брокер принял сообщение, 1, если до него не удалось достучаться или он отказал. См. Командная строка.

Проблемы

Что вы видите	Обычная причина
… refused the connection — nothing is listening on that port	По этому адресу и порту нет брокера.
… accepted the connection but did not answer in time — is it an MQTT broker?	Там что-то слушает, но не говорит на MQTT или говорит на нём поверх TLS.
… answered with something other than MQTT 3.1.1	Это не брокер MQTT, или брокер прислал то, что Signal Lab не может прочитать.
… does not accept MQTT 3.1.1 clients	Брокер принимает только MQTT 5.
… rejected the client ID — choose another one	Идентификатор слишком длинный или содержит символы, которые брокер не принимает.
… rejected the username or password	Неверные учётные данные или пароль без имени пользователя.
… did not authorize this client — check its access rules	Правила доступа брокера отказывают этому клиенту.
… is unavailable right now — try again later	Брокер работает, но не принимает клиентов.
Enter a client ID — brokers refuse an empty one	Поле ID клиента пусто.
A publish topic cannot contain the wildcards + or #	В топике, куда вы публикуете, есть + или #. Они нужны для подписки; публикуйте в один топик за раз.
Рядом с фильтром написано отказ	Правила доступа брокера его запрещают, или фильтр составлен неверно (# не последний, + делит уровень с другими символами).
Соединение обрывается сразу после подключения	Подключился другой клиент с тем же ID клиента.
В дереве ничего не появляется	Фильтр подписки при подключении пуст, или брокер не разрешает этому клиенту ничего видеть.

Все сообщения об ошибках перечислены в разделе Сообщения об ошибках.