node-red-ermangizer-modbus 1.2.0

Node-RED node for ERMANGIZER Modbus RTU protocol decoding

npm install node-red-ermangizer-modbus

Русский · English

Node-RED ERMANGIZER Modbus

Кастомный узел Node-RED для декодирования и формирования сообщений протокола Modbus RTU частотных преобразователей ERMANGIZER (ER-G-220-03, ER-G-220-04, ER-G-380-02) согласно официальной спецификации протокола.

Возможности

• 🚀 Несколько форматов входа: Buffer, hex-строка и массив чисел
• 🔍 Автоопределение: автоматическое определение типа входа
• 📊 Два формата вывода: подробный (полные метаданные) и упрощённый (только значения)
• ✅ Проверка CRC: контроль целостности данных по CRC-16
• 🛡️ Обработка ошибок: понятные сообщения об ошибках
• 📤 Узел-энкодер команд: собирает кадры Modbus из человекочитаемых команд ({command:"start"}, {write:"set_pressure", value:3.5}) — без ручной сборки hex
• 📋 Полная поддержка протокола: декодирует все регистры ERMANGIZER
• 🌐 Локализация: справка и метки редактора на русском и английском
• 🌐 TypeScript: написан на TypeScript

Поддерживаемые регистры

Узел декодирует все регистры протокола Modbus RTU ERMANGIZER:

Регистры только для чтения

• output_frequency — текущая выходная частота (0.1 Гц)
• output_current — текущий выходной ток (0.1 А)
• input_voltage — текущее входное напряжение (В)
• temperature — текущая температура (°C)
• pressure — фактическое давление (0.01 бар)
• error_code — код ошибки с описанием
• status_code — код статуса с побитовой расшифровкой

Регистры чтения/записи

• factory_reset — сброс к заводским настройкам
• initial_pressure_diff — перепад давления для сна/пробуждения (0.01 бар)
• water_shortage_pressure — давление сухого хода (0.01 бар)
• water_shortage_time — время сухого хода (с)
• carrier_frequency — несущая частота (см. параметр P014 в руководстве)
• accel_decel_time — время разгона и торможения (0.1 мс)
• pressure_tolerance — допустимая погрешность давления (0.01 бар)
• min_shutdown_freq — минимальная частота (0.1 Гц)
• continuous_operation — отключение режима сна (непрерывная работа)
• measurement_range — выбор диапазона датчика давления (бар)
• overheat_setting — порог тревоги по температуре (°C)
• direction_setting — направление вращения (для ER-G-380-02)
• local_address — локальный адрес Modbus

Примечание: имена выходных ключей регистров (например, water_shortage_pressure, continuous_operation) сохранены для обратной совместимости; их описания соответствуют редакции протокола 2026 года, где часть терминов переформулирована (нехватка воды → сухой ход, непрерывная работа ↔ отключение сна).

Управляющие регистры

• set_pressure — заданное давление (0.01 бар)
• status_command — код команды статуса

Установка

Установка через npm

cd ~/.node-red
npm install node-red-ermangizer-modbus

Затем перезапустите Node-RED.

Использование

Базовая настройка

1. Добавьте узел в flow из палитры (категория «parser»)
2. Настройте параметры:
   • Имя: необязательное имя узла
   • Тип входа: автоопределение или явный формат
   • Формат вывода: подробный или упрощённый
3. Подключите вход: к любому узлу, отдающему данные Modbus RTU
4. Подключите выход: обрабатывайте декодированные данные далее

Форматы входа

Узел принимает три формата входа:

1. Buffer (рекомендуется)

// Из последовательного порта или TCP-соединения Modbus
msg.payload = buffer; // объект Buffer

2. Hex-строка

// Шестнадцатеричная строка (пробелы необязательны)
msg.payload = "3f0300010016911a";
// или
msg.payload = "3f 03 00 01 00 16 91 1a";

3. Массив чисел

// Массив байт
msg.payload = [0x3f, 0x03, 0x00, 0x01, 0x00, 0x16, 0x91, 0x1a];

Форматы вывода

Подробный формат (по умолчанию)

{
  "slave_address": 63,
  "function_code": 3,
  "function_name": "Read Holding Registers",
  "raw_data": "3F0300010016911A",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "registers": {
    "output_frequency": {
      "value": 50.0,
      "raw_value": 500,
      "unit": "0.1 Hz",
      "description": "Current output frequency value",
      "address": 1,
      "read_only": true
    },
    "error_code": {
      "code": 0,
      "description": "No error",
      "raw_value": 0
    }
    // ... другие регистры
  }
}

Упрощённый формат

{
  "slave": 63,
  "function": "Read Holding Registers",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "output_frequency": 50.0,
  "error_code": 0,
  "temperature": 45,
  "pressure": 2.5
  // ... другие значения регистров
}

Отправка команд (узел ermangizer-modbus-encode)

Парный узел ERMANGIZER Encode превращает человекочитаемый объект-команду в готовый к отправке кадр Modbus RTU (с CRC) — не нужно собирать hex-строки руками. Подключите его выход к вашему узлу serial/Modbus-out.

Задайте msg.payload одним из вариантов:

// Семантические команды (запись регистра 0x1001)
{ command: "start" }                       // пуск
{ command: "stop" }                        // стоп
{ command: "reset_error" }                 // сброс ошибки
{ command: "set_pressure", value: 3.5 }    // уставка давления в барах

// Запись любого регистра чтения/записи по имени (значение в инженерных единицах)
{ write: "min_shutdown_freq", value: 30 }  // 30 Гц  -> raw 300 (scale 0.1)
{ write: "measurement_range", value: 10 }  // датчик 10 бар
{ write: "carrier_frequency", value: "H" } // 'H' или сырой числовой код

// Запрос на чтение (функция 0x03)
{ read: "all" }                            // адреса 1..22
{ read: "monitoring" }                     // адреса 1..7
{ read: ["output_frequency", "pressure"] } // минимальный диапазон, покрывающий имена
{ read: { start: 11, count: 4 } }          // явный диапазон

Масштаб (scale) регистра применяется автоматически (например, бары → единицы 0.01 бар), а запись в read-only регистры, неизвестные имена и значения вне диапазона отклоняются с понятной ошибкой. Необязательное поле slave переопределяет настроенный адрес узла для одного сообщения: { command: "start", slave: 12 }.

Настройки узла

• Адрес (slave) — адрес устройства по умолчанию (0–247). По умолчанию 1; заводской адрес ERMANGIZER — 63, выставьте его под своё устройство.
• Выход — Buffer (по умолчанию) или Hex-строка в верхнем регистре.

Связка чтения с декодером

Для команд read узел также выставляет msg.modbus_start_address — адрес первого запрашиваемого регистра. Передайте это сообщение в узел-декодер ERMANGIZER Modbus, и он сопоставит регистры ответа с правильными адресами (при отсутствии msg.modbus_start_address декодер использует адрес 1).

Программное использование

const { ModbusCommandEncoder } = require('node-red-ermangizer-modbus/ermangizer-modbus-encode');
const cmd = new ModbusCommandEncoder();

cmd.encode({ command: "start" }, 0x3F).frame;          // Buffer, адрес 63
cmd.encode({ write: "set_pressure", value: 4.0 }).frame;
cmd.encode({ read: "all", slave: 0x3F });              // { frame, function_code, start_address, description }

Примеры

Пример 1. Чтение нескольких регистров

// Входное сообщение (hex-строка)
msg.payload = "3f03002c3f032c01f4000100ea0020000000000001000000000001001e000a001e004c0014000a00f00000000600550000003f38ee";

// Вывод (упрощённый формат):
{
  "slave": 63,
  "function": "Read Holding Registers",
  "output_frequency": 50.0,
  "output_current": 5.0,
  "input_voltage": 234,
  "temperature": 32,
  "pressure": 0.0,
  "error_code": 0,
  "status_code": 0
}

Пример 2. Ответ-исключение

// Пример ответа-исключения
msg.payload = "3f8302a13d";

// Вывод:
{
  "slave_address": 63,
  "function_code": 131,
  "function_name": "Error Response",
  "error": {
    "code": 2,
    "description": "Modbus Error: Illegal Data Address",
    "modbus_error": true
  }
}

Коды ошибок

Узел декодирует все коды ошибок ERMANGIZER:

Расшифровка кода статуса

Регистр статуса (0x0007) раскладывается на отдельные биты:

{
  "running": true,          // Бит 0 (RS): 0=стоп, 1=работа
  "water_shortage": false,  // Бит 1 (LS): 0=нет сухого хода, 1=сухой ход
  "raw_value": 1            // Исходное значение регистра
}

Сборка из исходников

Если вы правите исходники на TypeScript:

1. Установите зависимости:

   npm install
   

2. Соберите проект:

   npm run build
   

3. Разработка с авто-пересборкой:

   npm run dev
   

Тесты

В пакете есть набор тестов без внешних зависимостей (test/test.js): проверяет CRC-16 на эталонных кадрах из документации, декодирование всех регистров и round-trip энкод→декод:

npm test   # сначала `tsc`, затем запуск тестов

Сборка кадров (энкодер)

Помимо декодирования, модуль экспортирует ModbusEncoder для сборки валидных кадров с автоматическим CRC — удобно для генерации запросов и тест-фикстур:

const { ModbusEncoder } = require('node-red-ermangizer-modbus');
const enc = new ModbusEncoder();

enc.encodeReadRequest(0x3F, 1, 22);        // чтение 22 регистров с адреса 1
enc.encodeWriteRequest(0x3F, 0x1000, 400); // установить давление 4.00 бар
enc.appendCRC(Buffer.from([0x3f, 0x06]));  // дописать CRC-16 к телу кадра

Также экспортируются ModbusDecoder, MODBUS_REGISTERS, ERROR_CODES, calculateCRC16 и appendCRC.

Устранение неполадок

Частые проблемы

1. «CRC check failed»

   • Убедитесь, что сообщение Modbus полное и не повреждено
   • Проверьте, что передаётся всё сообщение, включая CRC

2. «Message too short»

   • Во входе должно быть не менее 4 байт (адрес + код функции + CRC)

3. «Unsupported input type»

   • Используйте один из форматов: Buffer, hex-строка или массив чисел
   • При сомнениях включите автоопределение

4. Узел не появляется в палитре

   • Проверьте, что все файлы на месте
   • Убедитесь в отсутствии синтаксических ошибок
   • Полностью перезапустите Node-RED

Отладка

Включите отладочный вывод Node-RED для детальной информации:

1. Подключите узел debug к выходу узла ERMANGIZER Modbus
2. Включите отображение полного объекта сообщения
3. Смотрите логи Node-RED на наличие ошибок

Справка по протоколу

Узел реализует протокол Modbus RTU ERMANGIZER (ER-G-220-03, ER-G-220-04, ER-G-380-02; редакция 2026), описанный в:

• Документ: protocol_modbus_eg-g-220-03.pdf — https://www.ermangizer.ru/docs/220-03/protocol_modbus_eg-g-220-03.pdf (см. также https://www.ermangizer.ru/documentation.html)
• Скорость: 9600
• Биты данных: 8 бит + 1 стоп-бит
• Чётность: нет
• Диапазон адресов: 1–63
• Адрес по умолчанию: 63

Лицензия

Проект распространяется по лицензии MIT.

Поддержка

По вопросам и предложениям обращайтесь к сопровождающим или к документации протокола ERMANGIZER.

История изменений

v1.2.0

• Добавлен узел ermangizer-modbus-encode: сборка кадров Modbus RTU из человекочитаемых команд ({command:"start"}, {write:"set_pressure", value:3.5}, {read:"all"}) вместо ручных hex-строк — CRC и масштабирование регистров выполняются автоматически
• Вывод в Buffer или hex-строку; переопределение slave для сообщения
• Команды read выставляют msg.modbus_start_address; декодер теперь его учитывает, и чтение с любого адреса декодируется под правильными именами регистров
• Экспортируется ModbusCommandEncoder для программного использования
• Добавлена русская (ru) локализация редактора для обоих узлов; README теперь доступен на русском (по умолчанию) и английском

v1.1.0

• Согласовано с редакцией протокола 2026 (ER-G-220-03 / ER-G-220-04 / ER-G-380-02); обновлены описания регистров и коды ошибок
• Исправление: адреса регистров десятичные (1–22) — регистры 10–22 раньше декодировались как unknown
• Исправление: биты статуса были перепутаны (бит0=работа, бит1=сухой ход)
• Исправление: декодированные описания (например, error_code «No error») больше не затираются статическими метаданными
• Исправление: автоопределение больше не фиксирует формат входа навсегда после первого сообщения
• Упрощённый вывод теперь даёт скаляр на регистр (value → code → raw_value)
• Добавлен ModbusEncoder для сборки валидных кадров с автоматическим CRC
• Добавлен набор тестов без внешних зависимостей (npm test)

v1.0.0

• Первый выпуск
• Поддержка всех регистров Modbus ERMANGIZER
• Несколько форматов входа
• Проверка CRC
• Обработка ошибок