Карты сигналов Bridge
Формат JSON для импорта в OPC to MQTT Bridge и Modbus to MQTT Bridge: поля, типы, адресация и готовые примеры.
Карта, конфигурация и сообщение
Карта задаёт, что читать и куда передавать результат. Файл содержит только schemaVersion: 1 и непустой массив mappings. Не добавляйте endpoint, mqttServerId, пароли или сертификаты: подключение и защита задаются в экземпляре. MQTT payload USEPI — другой формат, который формирует Bridge; файл карты не публикуют в брокер.
Интерфейс импорта обоих Bridge принимает JSON в UTF-8, не Excel и не CSV. Парсеры также умеют CSV для отдельных инструментов, но это не означает поддержку CSV кнопкой импорта. Имена полей, значения перечислений и USEPI/ чувствительны к регистру; неизвестные поля, комментарии и завершающие запятые недопустимы.
Общие поля каждой строки
В топиках нельзя использовать +, #, *, обратный слеш, управляющие символы, пустые сегменты, а также сегменты из одной или двух точек. Каждый сегмент ограничен 256 байтами. Дополнительно соблюдайте пределы общего входного контракта USEPI: для совместимости не используйте root и более 32 сегментов после префикса.
Например, topic USEPI/examples/opc/pump-1 и signalId pressure дают лист examples/opc/pump-1/pressure/value под выбранным зарегистрированным MQTT-источником. Сам внутренний ID источника выбирается отдельно в интерфейсе. name: Pressure этот путь не меняет.
| Поле | Что записать |
|---|---|
| name | Необязательная подпись сигнала, до 256 байт; она не задаёт ID документа или адрес ноды. |
| source | Обязательный объект источника. Его поля различаются у OPC и Modbus; структуры нельзя смешивать. |
| topic | Обязательный точный MQTT-топик с USEPI/ и непустым хвостом; до 1024 байт. В одной карте топики не повторяются. |
| signalId | Обязательный ID, от 1 до 64 ASCII-символов: буквы, цифры, _ и -. Первый символ — буква или цифра. |
| payloadFormat | Задайте usepi явно. Значение по умолчанию у OPC не подходит Bridge; другой формат отклоняется. |
| enabled | Логическое true или false, по умолчанию true. Отключённые строки тоже проходят проверку. |
| retain | Логическое true или false. Явно выберите нужное поведение: по умолчанию false у OPC и true у Modbus. |
Источник OPC UA
Допустимые dataType: auto, Boolean, SByte, Byte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Float, Double, String, DateTime, Guid, ByteString, XmlElement, NodeId, ExpandedNodeId, StatusCode, QualifiedName, LocalizedText, ExtensionObject, DataValue, Variant и DiagnosticInfo.
Не составляйте NodeId из отображаемого имени или номера строки Excel. Получите реальный идентификатор, BrowseName и URI пространства имён у владельца сервера. Квалифицированный путь не является автоматическим поиском всех нод; все его сегменты должны быть известны заранее.
| Поле | Что записать |
|---|---|
| source.kind = nodeId | source.value содержит реальный NodeId: например ns=2;s=Pressure или ns=2;i=1001. s= — строковый, i= — числовой идентификатор. |
| source.namespaceUri | Необязательный URI пространства имён для nodeId. Bridge находит его текущий индекс по NamespaceArray сервера; это не адрес endpoint. |
| source.kind = browsePath | Вместо value задайте segments: последовательность объектов namespaceUri и name, от папки Objects до переменной; от 1 до 64 сегментов. |
| dataType | По умолчанию auto; либо точное имя OPC UA типа. Выбранный тип проверяется, не преобразуется с потерями. |
| shape | auto (по умолчанию), scalar, array или matrix. Это форма значения ноды, не число строк карты. |
Источник Modbus TCP
Обозначение 40001 в документации производителя не означает, что в карту надо вписать address: 40001. Сначала определите таблицу и принятую производителем нумерацию: для первого holding register используйте address: 0 с базой 0 или address: 1 с базой 1. Последний элемент диапазона тоже должен укладываться в адресное пространство.
В простой скачиваемой карте второй сигнал читает Float32 из inputRegisters: address: 3 с addressBase: 1 означает протокольный адрес 2 и два соседних регистра. Это учебный пример порядка слов, не универсальная настройка датчика.
| Поле | Что записать |
|---|---|
| source.table | holdingRegisters (FC3), inputRegisters (FC4), coils (FC1) или discreteInputs (FC2). |
| source.address / source.addressBase | addressBase: 0 — адрес 0…65535; addressBase: 1 — номер 1…65536, из которого вычитается 1. По умолчанию база 0. |
| source.unitId | ID устройства в диапазоне 0…255; явный выбор по карте и настройкам оборудования, не номер TCP-порта. |
| dataType | Boolean для coils/discreteInputs; для регистров — Bit, BitField, Int16, UInt16, Int32, UInt32, Int64, UInt64, Float32, Float64, String, BCD16, BCD32 или BCD64. |
| count | Число элементов 1…4096, по умолчанию 1. Это не число 16-битных регистров: Float32 занимает 2 регистра на элемент. Один сигнал ограничен суммарно 4096 битами или регистрами. |
| byteOrder / wordOrder | bigEndian или littleEndian, по умолчанию bigEndian. Порядок байтов внутри регистра и порядок регистров многорегистрового значения задаются отдельно. |
| scale / offset | Числовой результат = raw × scale + offset; по умолчанию 1 и 0. Boolean, Bit и String требуют scale: 1, offset: 0. |
Биты, строки, BCD и массивы Modbus
Расширенный пример содержит Bit, BitField, строку UTF-8, BCD64, массив четырёх Float32 и массив двенадцати coils. Удалите ненужные строки и замените адреса, Unit ID, длины и топики. Большой массив может читаться несколькими запросами и не является атомарным снимком.
| Тип или поле | Параметры |
|---|---|
| Bit / BitField | bitOffset: 0…15; bitWidth: 1…16, по умолчанию 1. Сумма offset и width не больше 16; для Bit ширина только 1. Бит 0 — младший. |
| String | stringLength: 1…8192 байта, по умолчанию 2; stringEncoding: ascii, utf8, utf16Be или utf16Le. Для UTF-16 длина должна быть чётной. |
| stringTermination | nullTerminated (по умолчанию) или fixedLength. Порядок байтов регистра и кодировка строки — разные настройки; для String wordOrder только bigEndian. |
| BCD16 / BCD32 / BCD64 | Беззнаковое десятичное число, соответственно 1, 2 или 4 регистра; каждая тетрада должна содержать цифру 0…9. |
| count > 1 | Массив элементов одного типа. Для String длина задана на один элемент; разные типы оформляйте отдельными строками карты. |
Проверка и загрузка карты
Обе карты ограничены 4096 строками. OPC принимает файл до 2 МиБ; Modbus — до 128 КиБ. Разобранная карта и окончательная конфигурация должны дополнительно уложиться в ограничения формы и Host. Даже отключённая ошибочная строка препятствует успешной проверке; частичный набор строк не объявляется корректной картой.
- Скачайте пример своего Bridge, измените его в текстовом редакторе и сохраните JSON в UTF-8. Для каждого нового сигнала скопируйте объект внутри mappings, разделяя объекты запятыми.
- В настройках экземпляра выберите «Импорт карты», загрузите файл, просмотрите строки и ошибки. Подтверждение заменяет карту в форме, а не объединяет её со старой; отдельно сохраните настройки и запустите экземпляр.
- После запуска проверьте реальные изменяющиеся значения и качество в дереве MQTT-источника, затем свяжите поля модели. Проверка формата файла не заменяет проверку оборудования, разрешений и результата.
Примеры синтетические и не являются картой вашего оборудования. Не загружайте их поверх рабочей карты без сохранения исходного файла и согласования. Не запускайте два писателя одних и тех же топиков.
| Ошибка или симптом | Что проверить |
|---|---|
| *_IMPORT_JSON_INVALID / *_SCHEMA_UNSUPPORTED | JSON-синтаксис, schemaVersion: 1, массив mappings и отсутствие неизвестных полей. |
| OPCUA_TOPIC_DUPLICATE / MODBUS_DUPLICATE_DESTINATION | Уникальные точные топики. Две строки карты не должны перезаписывать retained-состояние друг друга. |
| OPCUA_SIGNAL_ID_INVALID / MODBUS_SIGNAL_ID_REQUIRED | Допустимые ASCII-символы signalId; name не заменяет signalId. |
| OPCUA_SOURCE_INVALID / MODBUS_VALUE_SIZE_INVALID | NodeId или квалифицированный путь; для Modbus — count, границы адресов и параметры выбранного типа. |
| Карта принята, но данных нет | Существование источника, доступ, состояние экземпляра, выбранный MQTT и фактические USEPI-листья; импорт не запускает чтение. |