Архитектура Node-RED на контроллере

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

Ключевые компоненты: Runtime, Editor, Flows

В основе работы Node-RED на контроллере HI лежит четкая и логичная трехуровневая архитектура. Понимание каждого из этих уровней является критически важным для проектирования, развертывания и обслуживания надежных систем автоматизации.

> 💡 Подсказка: Рекомендуется регулярно создавать резервные копии директории `/home/hi-user/.node-red/`, так как она содержит всю вашу конфигурацию, установленные узлы и, самое главное, файлы потоков.

Архитектуру Node-RED можно представить в виде трех взаимосвязанных компонентов:

Среда выполнения (Runtime)

Визуальный редактор (Editor)

Файлы потоков (Flows)

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

Среда выполнения (Runtime)

Runtime — это сердце и мозг вашей системы автоматизации. Это серверный процесс, построенный на платформе Node.js, который непрерывно работает на контроллере HI. Именно Runtime отвечает за:

Исполнение логики: Он загружает ваши потоки (flows) из файла и выполняет всю заложенную в них логику: опрашивает датчики, обрабатывает события, отправляет команды на исполнительные устройства.
Управление состоянием: Runtime хранит и обрабатывает контекстные переменные (`flow` и `global`), которые используются для реализации сложных сценариев, например, с использованием паттерна "Конечный автомат" (FSM).
Взаимодействие с оборудованием: Через специализированные узлы Runtime обращается к аппаратным интерфейсам контроллера (RS-485, CAN, 1-Wire, реле) и сетевым протоколам (MQTT, Modbus TCP).
Обслуживание редактора: Runtime запускает легкий веб-сервер, который предоставляет доступ к визуальному редактору через браузер.

Важно понимать, что Runtime работает абсолютно независимо от редактора. Вы можете закрыть браузер, выключить свой компьютер, но пока на контроллер подается питание, Runtime будет продолжать выполнять свою работу 24/7. Это обеспечивает автономность и надежность системы автоматизации.

Визуальный редактор (Editor)

Editor — это ваш основной рабочий инструмент, графический интерфейс для взаимодействия с Runtime. Он представляет собой веб-приложение, доступное по IP-адресу контроллера в локальной сети (например, `http://192.168.1.10:1880`).

Ключевые функции редактора:

Создание и изменение потоков: С помощью интуитивно понятного drag-and-drop интерфейса вы можете перетаскивать узлы из палитры на рабочее поле, соединять их и настраивать их свойства.
Конфигурация узлов: Двойной клик на любом узле открывает диалоговое окно для настройки его параметров: MQTT-топика, адреса Modbus-регистра, логики в узле `Function` и т.д.
Развертывание (Deploy): После внесения изменений вы нажимаете кнопку "Deploy". В этот момент редактор отправляет обновленную конфигурацию потоков в формате JSON на Runtime, который, в свою очередь, плавно перезапускает измененные потоки, не прерывая работу остальных.
Отладка: Панель отладки (Debug) в боковой панели является незаменимым инструментом для мониторинга сообщений (`msg`), проходящих между узлами, и для просмотра ошибок.

Редактор — это клиент, который подключается к серверу (Runtime). Вся "магия" происходит на контроллере, а редактор лишь предоставляет удобный способ управления этой магией.

Файлы потоков (Flows)

Каждый узел, каждая связь и каждая настройка, которую вы создаете в редакторе, в конечном итоге сохраняется в текстовом виде. Flows — это и есть эти файлы, которые представляют собой структурированное описание вашей логики в формате JSON (JavaScript Object Notation).

Основной файл потоков: По умолчанию вся ваша работа хранится в одном файле: `/home/hi-user/.node-red/flows.json`. Этот файл содержит массив объектов, где каждый объект описывает узел: его тип, ID, координаты в редакторе, свойства и связи с другими узлами.
Файл учетных данных: Конфиденциальная информация (пароли от баз данных, API-ключи, токены) хранится отдельно в зашифрованном виде в файле `flows_cred.json`. Это повышает безопасность, так как вы можете делиться основным файлом `flows.json` без риска утечки секретов.

Понимание того, что ваши потоки — это просто текстовый файл, открывает возможности для продвинутого управления:

Системы контроля версий: Вы можете хранить `flows.json` в Git для отслеживания изменений, совместной работы и отката к предыдущим версиям.
Программная генерация: Теоретически, можно генерировать файлы `flows.json` автоматически для развертывания типовых конфигураций на множестве объектов.

📋 Ключевые понятия:

Node-RED Runtime: Фоновый серверный процесс на Node.js, исполняющий логику.
Node-RED Editor: Веб-интерфейс для создания и отладки потоков.
flows.json: JSON-файл, хранящий описание всех потоков, созданных в редакторе.

---

Интеграция Node-RED в ОС контроллера HI (Debian)

На контроллерах HI платформа Node-RED интегрирована в операционную систему Debian как системный сервис. Это обеспечивает ее автоматический запуск при старте контроллера, стабильную работу и удобное управление жизненным циклом.

> ⚠️ Внимание: Никогда не запускайте Node-RED от имени root-пользователя. Это создает серьезную уязвимость в системе безопасности и может привести к непредсказуемому поведению при доступе к оборудованию.

Node-RED как сервис systemd

systemd — это система инициализации и менеджер служб в современных дистрибутивах Linux, включая Debian. Управление сервисом Node-RED осуществляется через стандартную утилиту `systemctl` из командной строки (при подключении к контроллеру по SSH).

Вот основные команды, которые вам понадобятся:

Проверить статус сервиса:

sudo systemctl status nodered.service

Эта команда покажет, запущен ли сервис (`active (running)`), время его запуска, последние записи в логе и его Process ID (PID).

Перезапустить сервис:

sudo systemctl restart nodered.service

Это необходимо после внесения изменений в конфигурационный файл `settings.js` или при установке/удалении узлов, требующих перезагрузки.

Остановить сервис:

sudo systemctl stop nodered.service

Запустить сервис:

sudo systemctl start nodered.service

Включить автозапуск при старте системы (на контроллерах HI включено по умолчанию):

sudo systemctl enable nodered.service

Пользователь 'hi-user' и безопасность

Для соблюдения принципа наименьших привилегий сервис `nodered.service` на контроллере HI сконфигурирован для работы от имени специального, непривилегированного пользователя — `hi-user`. Это означает, что:

Права доступа к файлам: Все файлы конфигурации, потоков и установленных узлов находятся в домашней директории этого пользователя: `/home/hi-user/.node-red/`. Процесс Node-RED имеет полные права на чтение и запись внутри этой директории, но ограничен в доступе к остальной файловой системе.

Доступ к портам: По умолчанию в Linux процессы, запущенные не от имени `root`, не могут использовать порты ниже 1024. Именно поэтому стандартный порт для редактора Node-RED — `1880`.

Доступ к оборудованию: Для работы с аппаратными интерфейсами, такими как RS-485 (`/dev/ttyUSB0`), пользователь `hi-user` специально добавлен в соответствующие системные группы (например, `dialout`, `gpio`), которые предоставляют необходимые права доступа.

Диагностика и просмотр логов

Если Node-RED не запускается или ведет себя непредсказуемо, первым делом нужно проверить системные логи. Для этого используется команда `journalctl`.

Просмотр логов в реальном времени:

sudo journalctl -f -u nodered.service

Ключ `-f` (follow) позволяет видеть новые сообщения по мере их появления. Это чрезвычайно полезно при отладке проблем со стартом сервиса. Вы увидите сообщения о загрузке потоков, инициализации узлов и возможные ошибки.

Пример лога при успешном запуске:

-- Logs begin at ... --
Nov 15 10:00:01 hi-controller systemd[1]: Started Node-RED.
Nov 15 10:00:05 hi-controller Node-RED[1234]: 15 Nov 10:00:05 - [info]
Nov 15 10:00:05 hi-controller Node-RED[1234]: Welcome to Node-RED
Nov 15 10:00:05 hi-controller Node-RED[1234]: ===================
Nov 15 10:00:05 hi-controller Node-RED[1234]: 15 Nov 10:00:05 - [info] Node-RED version: v3.0.2
Nov 15 10:00:05 hi-controller Node-RED[1234]: 15 Nov 10:00:05 - [info] Node.js  version: v16.17.1
Nov 15 10:00:05 hi-controller Node-RED[1234]: 15 Nov 10:00:05 - [info] Linux 5.15.61-v8+ arm64 LE
Nov 15 10:00:07 hi-controller Node-RED[1234]: 15 Nov 10:00:07 - [info] Loading palette nodes
Nov 15 10:00:12 hi-controller Node-RED[1234]: 15 Nov 10:00:12 - [info] Settings file  : /home/hi-user/.node-red/settings.js
...
Nov 15 10:00:15 hi-controller Node-RED[1234]: 15 Nov 10:00:15 - [info] Starting flows
Nov 15 10:00:16 hi-controller Node-RED[1234]: 15 Nov 10:00:16 - [info] Started flows
Nov 15 10:00:16 hi-controller Node-RED[1234]: 15 Nov 10:00:16 - [info] Server now running at http://127.0.0.1:1880/

Предустановленные палитры узлов

Контроллеры HI поставляются с набором предустановленных узлов (палитр), которые необходимы для работы с типовым оборудованием. Это избавляет вас от необходимости устанавливать их вручную. В стандартный набор входят:

`node-red-contrib-modbus`: для работы с протоколом Modbus (RTU и TCP).
`node-red-contrib-dali`: для управления освещением по шине DALI через шлюз.
`node-red-contrib-knx-ultimate`: для интеграции с системами KNX.
`node-red-dashboard`: для создания простых пользовательских интерфейсов.
`node-red-node-mysql`: для взаимодействия с базой данных MySQL, доступной на контроллере.

---

Файловая структура и конфигурационный файл settings.js

Вся конфигурация и логика вашего проекта Node-RED хранится в специальной директории в домашнем каталоге пользователя `hi-user`. Понимание структуры этой директории и назначения ключевых файлов — обязательное условие для эффективного администрирования системы.

🔗 Связанный материал: Подробное описание процесса установки дополнительных узлов и управления зависимостями рассматривается в уроке `COURSE-06-M02-L01: Управление палитрами и узлами`.

Исследование директории ~/.node-red

Основная рабочая директория — `/home/hi-user/.node-red/`. Символ `~` является сокращением для домашней директории текущего пользователя.

Структура этой папки выглядит следующим образом:

/home/hi-user/.node-red/
├── flows.json          # Основной файл с описанием ваших потоков
├── flows_cred.json     # Зашифрованные учетные данные (пароли, ключи)
├── settings.js         # Главный конфигурационный файл Node-RED
├── package.json        # Список установленных узлов (зависимостей)
├── package-lock.json   # Файл с зафиксированными версиями зависимостей
├── node_modules/       # Директория, куда физически установлены все узлы
└── lib/                # Место для хранения пользовательских библиотек, файлов

Ключевые файлы и их назначение:

| Файл/Директория | Назначение |

| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |

| `flows.json` | "Исходный код" вашей автоматизации. Содержит всю логику, созданную в редакторе. Критически важен для резервного копирования. |

| `flows_cred.json` | Хранит чувствительные данные (например, пароль от MQTT брокера) в зашифрованном виде. Ключ для шифрования находится в `settings.js`. |

| `settings.js` | Главный конфигурационный файл. Позволяет настроить почти все аспекты поведения Node-RED. |

| `package.json` | Стандартный для Node.js файл, который перечисляет все дополнительно установленные модули (узлы) и их версии. |

| `node_modules/` | Физическое хранилище кода všech установленных узлов. Эта папка может занимать значительное место. |

Файл settings.js: Ключ к настройке

`settings.js` — это исполняемый JavaScript-файл, который экспортирует объект с настройками. Вы можете редактировать его с помощью любого текстового редактора в консоли, например `nano`:

nano /home/hi-user/.node-red/settings.js

После внесения изменений и сохранения файла необходимо перезапустить сервис Node-RED, чтобы они вступили в силу: `sudo systemctl restart nodered.service`.

Рассмотрим наиболее важные параметры:

`uiPort`: Задает порт, на котором будет доступен веб-интерфейс редактора. По умолчанию: `1880`.

    // Пример в settings.js
    uiPort: process.env.PORT || 1880,

`flowFile`: Имя файла, в котором хранятся потоки. Позволяет использовать разные файлы для разных проектов.

// Пример в settings.js flowFile: 'flows.json',

`credentialSecret`: Строка или ключ, используемый для шифрования файла `flows_cred.json`. Это самый важный параметр для безопасности! Если этот ключ утерян, все сохраненные учетные данные станут недоступны.

// Пример в settings.js credentialSecret: "a-very-secret-key-that-you-should-change",

При первой установке Node-RED генерирует случайный ключ. Если вы переносите проект на другой контроллер, вам необходимо скопировать и `settings.js` (с этим ключом), и `flows_cred.json`.

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

Практический пример: Смена порта редактора

Представим, что на контроллере запущен другой сервис, который уже использует порт 1880. Чтобы избежать конфликта, мы можем изменить порт для Node-RED.

Подключитесь к контроллеру по SSH.

Откройте `settings.js` для редактирования:

    nano ~/.node-red/settings.js

Найдите строку `uiPort`: Она может быть закомментирована (начинаться с `//`).

// The port that the Node-RED web server is listening on. //uiPort: process.env.PORT || 1880,

Раскомментируйте ее и измените значение, например, на `1881`:

// The port that the Node-RED web server is listening on. uiPort: process.env.PORT || 1881,

Сохраните файл (в `nano`: `Ctrl+O`, `Enter`) и выйдите из редактора (`Ctrl+X`).

Перезапустите сервис Node-RED:

sudo systemctl restart nodered.service

Проверьте доступ: Теперь редактор Node-RED будет доступен в вашем браузере по новому адресу: `http://:1881`.

---

Сетевое взаимодействие и доступ к оборудованию

Node-RED — это, в первую очередь, интеграционная платформа. Ее главная задача — служить мостом между различными системами, протоколами и устройствами. На контроллере HI это достигается за счет тесного взаимодействия с сетевой и аппаратной подсистемами ОС Debian.

> ℹ️ Информация: Все узлы, работающие с низкоуровневыми протоколами (например, Modbus, KNX), являются обертками над системными вызовами Linux. Понимание базовой диагностики на уровне ОС (`ping`, `netstat`, `dmesg`) — ключ к успешной отладке.

Привязка к сетевым интерфейсам

Контроллер HI оснащен как минимум одним Ethernet-портом и, опционально, Wi-Fi модулем. Node-RED, как и любое сетевое приложение, использует эти интерфейсы для обмена данными.

Исходящие соединения: Когда вы настраиваете узел `MQTT Out` для подключения к облачному брокеру или `HTTP Request` для обращения к API, Node-RED использует стандартный сетевой стек Linux для установления TCP-соединения через доступный шлюз в интернет.
Входящие соединения: Узлы `HTTP In`, `TCP In` или `Modbus Server` "слушают" входящие подключения на определенных портах. Доступность этих портов извне зависит от сетевой конфигурации (проброс портов на роутере, настройки файрвола).

Взаимодействие с MQTT-брокером

Как мы рассматривали в курсе по MQTT, архитектура с центральным брокером является наиболее гибкой и масштабируемой. На контроллере HI может быть запущен локальный MQTT-брокер (например, Mosquitto), либо Node-RED может подключаться к внешнему. Node-RED выступает в роли MQTT-клиента.

Пример: Поток для отправки показаний температуры в MQTT.

Узел `Modbus-Getter` считывает данные с датчика.

Узел `Function` форматирует сообщение в соответствии с "Контрактом сообщения".

Узел `MQTT Out` публикует это сообщение.

Код в узле `Function`:

// Входящее сообщение от Modbus-узла: msg.payload = [255] (25.5°C)
let temp = msg.payload[0] / 10.0;

// Формируем payload по стандартному контракту
msg.payload = {
    "value": temp,
    "source": "modbus-sensor-room101",
    "ts": Date.now(),
    "unit": "°C"
};

// Задаем топик для публикации
msg.topic = "hi-office/room101/temperature/state";

return msg;

Это сообщение публикуется узлом `MQTT Out` в брокере. Любое другое устройство или сервис, подписанный на топик `hi-office/room101/temperature/state`, немедленно получит эти данные.

Прямой доступ к аппаратным интерфейсам

Для работы с промышленными шинами, такими как RS-485 или CAN, Node-RED обращается к ним через файлы устройств в директории `/dev` операционной системы.

RS-485 (Modbus RTU): USB-адаптер RS-485 на контроллере представляется системе как последовательный порт, например `/dev/ttyUSB0`. При настройке узла `Modbus-Read` вы указываете именно этот путь в качестве COM-порта. Runtime Node-RED открывает этот файл, настраивает параметры порта (скорость, четность) и начинает отправлять и принимать байты данных в соответствии с протоколом Modbus RTU.

* Права доступа: Как упоминалось ранее, чтобы это работало, пользователь `hi-user` должен состоять в группе `dialout`, которая имеет права на работу с последовательными портами.

1-Wire: Аналогично, шина 1-Wire, к которой подключены датчики DS18B20, доступна через виртуальную файловую систему. Узел `ds18b20` читает данные из файлов вида `/sys/bus/w1/devices/28-xxxxxxxxxxxx/w1_slave`.

Работа с протоколами на базе TCP/IP

Многие современные промышленные протоколы имеют версии, работающие поверх стандартной сети Ethernet.

Modbus TCP: Вместо последовательного порта, узел `Modbus-Read` настраивается на IP-адрес и TCP-порт (стандартно 502) конечного устройства (например, счетчика электроэнергии или модуля ввода-вывода).
DALI через шлюз: Система управления освещением DALI является двухпроводной шиной. Для ее интеграции в IP-сеть используются шлюзы DALI-IP. Узел `node-red-contrib-dali` отправляет команды на IP-адрес этого шлюза, который уже транслирует их в команды на шине DALI.

Node-RED абстрагирует сложность этих взаимодействий. Ваша задача — правильно настроить IP-адрес в узле, а Runtime возьмет на себя всю работу по установлению TCP-соединения и обмену пакетами данных.

---

Итоги: Архитектура Node-RED на контроллере в действии

В этом уроке мы разобрали архитектуру Node-RED на контроллере HI, от высокоуровневых концепций до низкоуровневого взаимодействия с операционной системой и оборудованием.

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

Клиент-серверная модель: Вы работаете в редакторе (клиент в браузере), но вся логика исполняется автономным Runtime (сервер на контроллере). Это разделение обеспечивает надежность и непрерывность работы системы автоматизации.

Интеграция с Linux: Node-RED не существует в вакууме. Он глубоко интегрирован в ОС Debian: запускается как сервис `systemd`, работает от имени `hi-user` и использует стандартные механизмы Linux для доступа к сети и аппаратным портам (`/dev/ttyUSBx`).

Конфигурация через файлы: Вся ваша система описана в текстовых файлах (`flows.json`, `settings.js`), что делает ее прозрачной, легко копируемой и управляемой. Понимание их назначения и расположения — основа администрирования.

Node-RED как "клей": Главная сила платформы — в ее способности связывать воедино разнородные технологии.

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

Событие: Контакты настенной кнопки замыкаются.
Аппаратный уровень: Сигнал поступает на дискретный вход `UI-10` контроллера HI.
Драйвер ОС: Ядро Linux регистрирует изменение состояния GPIO.
Runtime Node-RED: Узел `rpi gpio in`, настроенный на пин `UI-10`, получает уведомление от ОС и генерирует сообщение `msg`.
Flow (Поток): Сообщение `msg` проходит через логику вашего потока (например, узел `trigger` для обработки однократного нажатия).
Runtime Node-RED: Узел `Modbus-Write` получает команду, формирует Modbus-пакет (например, `Write Single Coil`).
Аппаратный уровень: Runtime через драйвер ОС отправляет последовательность байт в порт `/dev/ttyUSB0`.
Физический уровень: Преобразователь RS-485 отправляет электрические импульсы по витой паре на релейный модуль.
Действие: Релейный модуль получает команду и замыкает реле, зажигая свет.

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

Что дальше?

В следующем модуле мы перейдем от архитектуры к более углубленной практике. В уроке `COURSE-06-M02-L01: Управление палитрами и узлами` мы научимся находить, устанавливать и управлять дополнительными узлами из библиотеки Node-RED, расширяя возможности нашего контроллера.