Ваш первый поток: «Hello, World!» на контроллере

Урок 3 · Node-RED: установка, flows, msg/JSON, отладка · 30 мин · theory

Введение: создаем первый поток Node-RED

Добро пожаловать в практическую часть нашего курса. Ранее мы изучили архитектуру и интерфейс Node-RED на контроллере HI, и теперь пришло время применить эти знания на практике. В этом уроке мы создадим свой первый поток (Flow) — эквивалент программы «Hello, World!» в мире автоматизации. Эта простая, но фундаментальная задача научит вас основам создания, тестирования и отладки логики на платформе.

Цель нашего урока — создать поток, который по ручной команде генерирует сообщение (Message, msg) и выводит его содержимое в отладочную панель (Debug sidebar). Для этого мы будем использовать всего два типа узлов (Node):

Узел inject (`inject`): Наш "генератор сигнала" или "виртуальная кнопка". Он позволяет инициировать поток вручную, отправляя сообщение с заданными параметрами. Это незаменимый инструмент для тестирования логики без реального физического оборудования.

Узел debug (`debug`): Наш "микроскоп" или "логгер". Он перехватывает сообщения, проходящие через него, и отображает их содержимое на боковой панели отладки, позволяя нам увидеть, что именно происходит внутри потока.

Создание потока «Hello, World!» — это не просто учебный пример. Это базовый навык, который вы будете использовать ежедневно для прототипирования новых сценариев, проверки гипотез и диагностики неисправностей. Освоив взаимодействие узлов `inject` и `debug`, вы заложите прочный фундамент для работы с более сложными системами автоматизации.

---

Узел Inject: ручная инициация потока

Узел inject является отправной точкой для большинства тестовых и отладочных потоков. Его основная задача — создать и "вбросить" в поток новое сообщение по клику на кнопке узла или по расписанию. Это позволяет эмулировать события от внешних систем, таких как нажатие настенного выключателя, срабатывание датчика движения или получение команды по сети.

> 💡 Подсказка: Используйте узел `inject` для симуляции сообщений от устройств (датчиков, кнопок), что позволяет тестировать логику без физического оборудования. Это ключевой принцип автономной разработки и модульного тестирования.

Давайте разместим наш первый узел на рабочем поле. Найдите узел `inject` в левой части палитры (обычно он находится вверху секции "Общие") и перетащите его на центральную рабочую область. Дважды щелкните по узлу, чтобы открыть диалог его настроек.

Настройка полезной нагрузки (msg.payload)

Основное, что нужно настроить, — это полезная нагрузка (Payload, msg.payload). Это поле определяет, какие данные будут содержаться в главном свойстве сообщения. Узел `inject` позволяет отправлять данные различных типов. Рассмотрим основные из них:

| Тип данных | Описание и пример | Как настроить в узле `inject` |

| :--------- | :------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |

| `timestamp` | (По умолчанию). Отправляет текущее время в формате Unix Epoch (миллисекунды). Например: `1678886400000`. | Выбрать "timestamp" в выпадающем списке. |

| `string` | Текстовая строка. Например: `"Hello, World!"`. | Выбрать "string" и ввести текст в поле. |

| `number` | Числовое значение (целое или с плавающей точкой). Например: `25.5`. | Выбрать "number" и ввести число. |

| `boolean` | Логическое значение `true` или `false`. | Выбрать "boolean" и выбрать `true` или `false`. |

| `JSON` | Структурированный объект в формате JSON. Это наиболее предпочтительный тип для сложных данных. | Выбрать "JSON" и ввести валидный JSON-объект в редактор. |

Для нашего первого потока давайте настроим узел на отправку простой текстовой строки.

В поле `msg.payload` выберите из выпадающего списка тип `string` (обозначается как `A-Z`).

В текстовом поле справа введите: `Привет, мир автоматизации!`.

Конфигурация темы (msg.topic)

Поле `msg.topic` играет важную роль в маршрутизации сообщений. Хотя в нашем простом примере оно не является строго обязательным, привыкайте задавать его с самого начала. Топик — это как "тема письма", которая помогает узлам-фильтрам (например, `Switch`) понять, к какой категории относится сообщение.

Найдите поле `msg.topic` в настройках узла.

Введите в него семантически понятное имя, например, `test/greeting/manual`.

После завершения настроек нажмите кнопку "Готово" (Done). Вы увидите, что под узлом `inject` появилось описание его полезной нагрузки, что делает поток более читаемым.

Пример настроенного `msg.payload` в формате JSON, который мы будем использовать в дальнейших примерах:

{
    "value": true,
    "source": "manual-inject-button-01",
    "ts": 1678886500000,
    "user": "admin"
}

Этот формат соответствует "Контракту сообщения", который является стандартом для всех наших систем.

---

Узел Debug: отладка и просмотр сообщений

Узел debug — это ваши глаза и уши внутри системы Node-RED. Без него разработка превращается в гадание на кофейной гуще. Его единственная функция — отображать содержимое сообщений, которые через него проходят.

Найдите узел `debug` в палитре (он также находится в секции "Общие" и имеет иконку с изображением жука) и перетащите его на рабочую область правее узла `inject`.

Дважды щелкните по узлу `debug`, чтобы открыть его настройки. Здесь нас интересует один ключевой параметр: `Вывод` (Output).

Настройка вывода: `msg.payload` vs. полный объект `msg`

По умолчанию узел `debug` показывает только содержимое `msg.payload`. Это удобно для быстрой проверки основного значения, но часто этой информации недостаточно для полноценной отладки.

| Настройка вывода | Что вы увидите | Когда использовать |

| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |

| `msg.payload` | Только значение, хранящееся в свойстве `payload`. Например: `"Привет, мир автоматизации!"`. | Для быстрой проверки результата работы одного узла, когда контекст не важен. |

| `complete msg object` | (Рекомендуется) Весь объект `msg` целиком, включая `payload`, `topic`, `_msgid` (уникальный ID сообщения) и любые другие свойства, которые были добавлены предыдущими узлами. Это дает полное представление о состоянии потока. | Практически всегда. Это единственный способ увидеть все данные, передаваемые между узлами, и найти причину ошибки. |

> ℹ️ Информация: Уникальный идентификатор `_msgid` присваивается каждому сообщению, когда оно входит в поток (например, через узел `inject`). Это позволяет отслеживать путь одного и того же сообщения через сложные цепочки узлов в отладочной панели.

Для нашего урока давайте сразу привыкать к лучшим практикам.

В настройках узла `debug` измените значение поля `Вывод` (Output) на `complete msg object`.

Вы можете дать узлу имя, например, "Вывод сообщения", чтобы сделать поток понятнее.

Нажмите кнопку "Готово" (Done).

Теперь узел готов принимать сообщения и показывать их полную структуру. В правой части интерфейса Node-RED откройте боковую панель и перейдите на вкладку отладки (с иконкой жука). Именно здесь будут появляться все наши отладочные сообщения.

---

Сборка и развертывание: соединяем узлы и запускаем поток

Теперь, когда у нас есть два настроенных узла, нам нужно соединить их, чтобы создать поток. В Node-RED потоки данных движутся слева направо. Сообщения "выходят" из серых квадратиков (портов вывода) на правой стороне узлов и "входят" в порты на левой стороне.

Процесс "связывания" (wiring) узлов

Наведите курсор мыши на порт вывода (серый квадрат) узла `inject`. Курсор изменит свой вид.

Нажмите левую кнопку мыши и, не отпуская ее, протяните линию ("провод") к порту ввода узла `debug`.

Когда порт ввода подсветится оранжевой рамкой, отпустите кнопку мыши.

Поздравляем, вы только что создали свой первый поток! Визуально он представляет собой два узла, соединенных серой линией. Это означает, что любое сообщение, сгенерированное узлом `inject`, будет передано на вход узла `debug`.

Концепция "Развертывания" (Deploy)

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

> ⚠️ Внимание: Всегда будьте осторожны при развертывании на работающей системе. Опция "Измененные потоки" обычно самая безопасная, но полная перезагрузка (Full Deploy) может потребоваться после установки новых узлов.

Кнопка "Развернуть" (Deploy) находится в правом верхнем углу интерфейса. Нажмите на стрелку рядом с ней, чтобы увидеть доступные варианты:

Полное (Full): Останавливает все потоки, развертывает все с нуля. Самый надежный, но и самый "разрушительный" способ.
Измененные потоки (Modified Flows): Перезапускает только те потоки (вкладки), в которые были внесены изменения. Оптимальный вариант для большинства случаев.
Измененные узлы (Modified Nodes): Перезапускает только измененные узлы. Самый быстрый, но может привести к неконсистентному состоянию, если логика сильно зависит от контекста потока.

Нажмите красную кнопку "Развернуть" (Deploy).

Вы увидите уведомление "Успешно развернуто" в верхней части экрана. Синие точки над измененными узлами исчезнут. Это означает, что ваш новый поток теперь активен на контроллере.

Запуск потока и анализ результата

Теперь самое интересное.

Найдите на своем потоке узел `inject`. Слева от него есть небольшая кнопка.

Нажмите на эту кнопку.

В этот момент узел `inject` сгенерировал сообщение и отправил его по "проводу" в узел `debug`. Переключите свое внимание на отладочную панель справа. Вы должны увидеть новое событие.

Если вы нажмете на него, раскроется полная структура объекта `msg`:

{
  "_msgid": "a4f8b2e3.1c9d2",
  "topic": "test/greeting/manual",
  "payload": "Привет, мир автоматизации!"
}

Проанализируем результат:

`_msgid`: Уникальный идентификатор, автоматически присвоенный сообщению.
`topic`: Наша тема, которую мы задали в настройках — `test/greeting/manual`.
`payload`: Наша полезная нагрузка — `"Привет, мир автоматизации!"`.

Вы успешно создали, развернули и запустили свой первый поток!

---

Пример: работа с разными типами данных

Чтобы закрепить материал, создадим более сложный пример. Наша цель — посмотреть, как узел `debug` отображает различные типы данных. Мы создадим поток, в котором несколько узлов `inject` отправляют данные разных типов в один общий узел `debug`.

Удалите предыдущий узел `inject` или просто измените его.

Создайте четыре узла `inject` и расположите их вертикально один под другим.

Настройте каждый из них на отправку своего типа данных. Дайте им понятные имена.

Inject 1: "Отправить строку"

* `msg.payload`: `string`, `"Статус: OK"`

* `msg.topic`: `system/status`

Inject 2: "Отправить число"

* `msg.payload`: `number`, `24.7`

* `msg.topic`: `telemetry/temperature`

Inject 3: "Отправить boolean"

* `msg.payload`: `boolean`, `true`

* `msg.topic`: `command/light/set`

Inject 4: "Отправить JSON"

* `msg.payload`: `JSON`, объект:

{ "value": 45.8, "unit": "%", "source": "sensor-humidity-room1" }

* `msg.topic`: `telemetry/humidity`

Перетащите на рабочую область один узел `debug`. Убедитесь, что он настроен на вывод `complete msg object`.

Соедините выходной порт каждого из четырех узлов `inject` с входным портом одного и того же узла `debug`.

Нажмите кнопку "Развернуть" (Deploy).

Теперь поочередно нажимайте на кнопки каждого из узлов `inject` и наблюдайте за результатом в отладочной панели. Вы увидите, как для каждого сообщения меняется `msg.topic` и тип `msg.payload`, что наглядно демонстрирует гибкость системы.

После нажатия "Отправить строку":

`payload: "Статус: OK"` (тип `string`)

После нажатия "Отправить число":

`payload: 24.7` (тип `number`)

После нажатия "Отправить boolean":

`payload: true` (тип `boolean`)

После нажатия "Отправить JSON":

`payload: object` (можно раскрыть, чтобы увидеть `value`, `unit`, `source`)

Этот простой, но наглядный пример показывает, как потоки Node-RED оперируют типизированными данными и как важен `msg.topic` для их идентификации.

---

Итоги и следующие шаги

В этом уроке мы сделали первый и самый важный шаг в освоении Node-RED. Мы научились создавать простейший поток, состоящий из узлов `inject` и `debug`, и поняли их фундаментальную роль в процессе разработки и тестирования.

Ключевые моменты, которые мы усвоили:

Узел `inject` служит для ручной инициации потоков и эмуляции сигналов от устройств.
Узел `debug` является незаменимым инструментом для анализа содержимого сообщений, особенно при выводе полного объекта `msg`.
Любые изменения в потоках требуют развертывания (Deploy) для их активации на контроллере.
Объект `msg` является основной единицей передачи данных, а его свойства `msg.payload` и `msg.topic` несут основную смысловую и маршрутизирующую нагрузку.

Поздравляем! Вы овладели базовым рабочим циклом в Node-RED: создание -> связывание -> настройка -> развертывание -> тестирование. Этот цикл будет повторяться снова и снова при создании любых, даже самых сложных систем автоматизации.

> 🔗 Связанный материал: В следующем уроке, `COURSE-06-M01-L05`, мы сделаем наш поток интерактивным. Мы углубимся в структуру объекта `msg` и научимся программно изменять его содержимое с помощью узла `change`, что позволит нам преобразовывать данные и строить более сложную логику.