Формат импорта групповых адресов в ETS 6: подробный разбор

Таблица уже существует

К моменту, когда кто-то открывает ETS, адреса обычно уже где-то записаны — в таблице проекта, в тендерной документации, в списке, который прислал заказчик. Вбить две тысячи адресов вручную — это день работы и ошибки, которые всплывут через несколько месяцев на объекте.

ETS импортирует их из CSV за секунду. Загвоздка в том, что файл должен иметь ровно ту структуру, которую ожидает ETS, а эта структура плохо документирована.

Девять столбцов

Разделитель в файле — точка с запятой, структура фиксированная, из девяти столбцов:

Деталь, в которой ошибаются все

Уровень записи кодируется тем, в каком столбце стоит имя. Не отступом, не отдельным полем типа и не одним только адресом. Всё правило видно на трёх строках:

Main group     "Lighting"; ; ;"1/-/-";"";"";"";"";"Off"
Middle group    ; "Switch"; ;"1/0/-";"";"";"";"";"Auto"
Group address   ; ;"Kitchen ceiling";"1/0/3";"";"";"";"";"Auto"

Поставьте имя не в тот столбец — и ETS либо отклонит строку, либо создаст её не на том уровне, который вы задумали. Это самая частая причина, по которой составленный вручную файл не импортируется чисто.

Подводные камни, о которых стоит знать до генерации 2 000 строк

• Окончания строк должны быть CRLF. Файл только с LF не импортируется.
• Кавычки внутри имени экранируются удвоением — обычное правило CSV.
• Диапазоны: главная группа 0–31, средняя группа 0–7, групповой адрес 0–255. Если выйти за них в электронной таблице, ничто вас не предупредит.
• Задавайте тип точки данных при импорте. Формально он необязателен, но если его пропустить, позже придётся заново проходить по каждому адресу в ETS: пустой тип — это будущая ошибка.
• Кодировка: файл ниже — UTF-8 без BOM (метки порядка байтов). Если имена групп состоят только из символов ASCII, это не имеет значения. Если в них есть умляуты или тире, сначала сделайте один небольшой пробный импорт и посмотрите, как отображаются имена, и только потом генерируйте полный файл.

Описать дерево один раз, затем подавать адреса

Генератор делит работу на две части. Схема описывает форму дерева групповых адресов: какие есть главные группы, какие средние группы в них входят, какой тип точки данных у каждой. Таблица проекта затем поставляет адреса. Ничего из описания дерева не повторяется в каждой строке.

Именно это разделение даёт единообразие имён без лишних усилий: каждая средняя группа сохраняет своё значение во всём проекте, потому что объявлена один раз.

const schema = [{
  index: 1,
  name: 'Lighting — ground floor',
  middle: [
    { index: 0, name: 'Switch',        field: 'switch',       dpt: 'DPST-1-1', suffix: 'On/Off' },
    { index: 1, name: 'Switch status', field: 'switchStatus', dpt: 'DPST-1-1', suffix: 'On/Off St' },
    { index: 2, name: 'Dimming',       field: 'dim',          dpt: 'DPST-3-7', suffix: 'Dim' },
  ],
}];

Проверка — то, чего нет при ручной работе

Сгенерировать файл — простая половина задачи. Половина, которая окупается, — отказ генерировать файл с ошибками. Четыре ошибки в исходной таблице и то, что генератор возвращает в ответ:

- Lighting / Switch / Hall downlights: address 1/0/1 already used by "Kitchen ceiling On/Off"
- Lighting / Switch / Terrace: address 1/9/3 sits in middle group 9, but the schema places it in 0
- Lighting / Switch / ?: missing device name
- Lighting / Switch / Study: address 1/0/999 exceeds the 0–255 sub range

Дорогая из них — первая. Два групповых объекта на одном адресе в KNX допустимы и иногда делаются намеренно, но гораздо чаще это ошибка копирования в таблице. Найденная здесь, она не стоит ничего. Найденная на объекте, она стоит выезда, потому что симптом — две цепи, которые включаются вместе, а в проекте при этом всё выглядит правильно.

Весь цикл целиком

Таблица из семи устройств и одна команда. Ниже — ровно то, что выдаёт опубликованный пример: 26 адресов в двух главных группах, побайтно сверенных с файлом-образцом в репозитории.

"Lighting — ground floor"; ; ;"1/-/-";"";"";"";"";"Off"
 ;"Switch"; ;"1/0/-";"";"";"";"";"Auto"
 ; ;"Kitchen ceiling On/Off";"1/0/1";"";"";"";"DPST-1-1";"Auto"
 ; ;"Kitchen worktop On/Off";"1/0/2";"";"";"";"DPST-1-1";"Auto"
 ;"Switch status"; ;"1/1/-";"";"";"";"";"Auto"
 ; ;"Kitchen ceiling On/Off St";"1/1/1";"";"";"";"DPST-1-1";"Auto"

В ETS: Group Addresses → Import → CSV.

Чего этот инструмент не делает

Импорт создаёт групповые адреса. К коммуникационным объектам ваших устройств он их не привязывает — это остаётся ручной работой в ETS, а массовая привязка возможна только через ETS API.

Описанный здесь формат — тот, который принимает ETS 6. В ETS 5 другой набор столбцов, так что не рассчитывайте, что файл подойдёт и туда.

Одно ограничение самого инструмента: шаблон адреса допускает среднюю группу 0–9, тогда как KNX разрешает 0–7. Неверная средняя группа отлавливается, если она расходится со схемой, как в примере выше, — но если объявить индекс 8 в самой схеме, возражений не будет. Диапазон подгруппы 0–255 проверяется явно.

Забирайте

Без зависимостей, Node 18 или новее, лицензия MIT. Адаптируйте схему под своё именование — и всё заработает как есть.