11 KiB
aliases, created, namespace, related, tags, title, type, updated
| aliases | created | namespace | related | tags | title | type | updated | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2026-09-17 | family |
|
|
⚙️ ZONT Config Compiler — конвертеры .txt ⇄ .yml | how-to | 2026-09-17 |
⚙️ ZONT Config Compiler — конвертеры .txt ⇄ .yml
Двусторонние конвертеры между конфигом контроллера ZONT (.txt) и читаемым YAML.
Позволяют править конфиг руками — имена реле, адреса Modbus, интервалы опроса, датчики — не заходя в UI контроллера.
| Проект (Mac) | /Users/admin/Automation/HA-ZONT-Modbus |
| Repo (private) | https://git.mallexxx.duckdns.org/git_admin/HA-ZONT-Modbus |
| Скрипты | config-to-yml.py (TXT → YAML) · yml-to-config.py (YAML → TXT) |
| Конфиги | zont_config/ — свежие · zont_config/archive/ — историчные |
| Типы объектов | family/tech/zont-config-object-types |
| ZONT в общем контуре | family/how-to/home-automation §6 |
1. Формат конфига ZONT
Текстовый файл, одна запись = одна строка, разделитель строк CRLF, кодировка windows-1251:
#Z<id>=<тип>,<поле>,<поле>,…
#S<id>=<значение>
| Префикс | Что это | Пример |
|---|---|---|
#Z<id> |
объект конфига: реле, датчик, сценарий, Modbus-устройство | #Z12=14,'Спальня левый',… — id 12, тип 14 (реле) |
#S<id> |
системная настройка | #S7=H2000_PRO 723 678 — модель и версии ПО |
- Тип объекта — первое поле после
=. - Строки — в
'одинарных кавычках', списки —[...], числа — как есть. #Z<id>=*— служебный маркер (пустой/унаследованный объект).- Порядок строк значим и сохраняется при конвертации.
2. Как работает
config-to-yml.py — TXT → YAML
- Читает файл, определяет кодировку: UTF-8, при неудаче — windows-1251.
- Парсит строки регекспом
^#([ZS])(\d+)=(.*)$(хвостовые пробелы в payload сохраняются). split_payload()— режет payload по запятым с учётом кавычек и вложенных[…].parse_atom()— пусто/''→None,'строка'→ строка,[…]→ список, иначе int → float → строка.- Раскладывает объекты по секциям YAML. Вложенное прячет под родителя: Modbus-регистры (тип 52) → внутрь своего устройства (тип 51).
system_settings(#S…) выводит в начало файла, чтобы было видно при правке.
yml-to-config.py — YAML → TXT
- Загружает YAML (UTF-8) и собирает строки
#Z<id>=…обратно, в порядке типов. - Форматирование: числа без кавычек, строки в
'…', bool →0/1, пустая строка →'', списки →[…]. - Разворачивает вложенное: регистры типа 52 снова становятся отдельными строками после своего устройства.
validate_config()проверяет структуру до вывода. При ошибках —❌ VALIDATION ERRORS, exit 4, файл не отдаётся.- Вывод: windows-1251, переводы строк CRLF, финальный перевод строки как в оригинале.
Коды возврата
| Скрипт | Код | Значение |
|---|---|---|
config-to-yml.py |
1 | неверное число аргументов |
| 2 | ParseError — неизвестный формат строки или неразбираемое значение |
|
yml-to-config.py |
1 | файл не найден |
| 2 | ConversionError — нет raw или неизвестный тип объекта |
|
| 3 | прочее исключение | |
| 4 | ❌ ошибки валидации (файл не выдан) |
Неизвестный тип объекта — падение с ошибкой, а не тихий пропуск. Сделано намеренно: молча потерять объект хуже, чем не отдать файл.
3. Как пользоваться
Требования: python3 + PyYAML. Проверка: python3 -c 'import yaml; print(yaml.__version__)'
cd /Users/admin/Automation/HA-ZONT-Modbus
# 1. Снять текущий конфиг с контроллера → в zont_config/
# имя файла: config_<SN>_<SN>_<YYYY-MM-DD_HH-MM-SS>.txt
# 2. TXT → YAML
python3 config-to-yml.py zont_config/config_XXXX.txt > /tmp/zont.yml
# 3. Править YAML: имена, адреса, интервалы опроса, пороги
# ⚠️ id объектов и их порядок значимы — не переставлять без нужды
# 4. YAML → TXT
python3 yml-to-config.py /tmp/zont.yml > /tmp/zont_new.txt
# 5. Сверить число объектов до/после
grep -c '^#Z' /tmp/zont_new.txt
# 6. Загрузить /tmp/zont_new.txt в контроллер (UI / облако ZONT)
🔴 Главное правило: raw не трогать
В YAML часть полей декодирована (адрес, интервал опроса, регистры), часть лежит как raw / raw_params / raw_field_N — это страховка от потери данных.
Если у объекта пустой raw, скрипт подставит жёстко зашитые дефолты (тип 0 — набор из 16 полей, тип 36 — [],[],[],10,0), и исходные настройки будут потеряны молча.
✅ Правь декодированные поля.
raw-поля не удаляй и не «чисти». Если поле не декодировано — правка возможна только с пониманием исходного формата.
Поддерживаемые типы
1, 3, 4, 5, 6, 7, 9, 10, 11, 14, 16, 20, 24, 25, 27, 28, 42, 46, 49, 51, 52, 53, 57
➕ дополнительно обрабатываются 0 (дискретные датчики — индикаторы состояния реле) и 36 (их вложенные конфиги).
Полная таблица с полями — family/tech/zont-config-object-types.
4. Проверка целостности (round-trip)
README_converters.md заявляет round-trip 130/130 объектов: TXT → YAML → TXT даёт идентичный файл.
Команда для проверки на любом конфиге:
cd /tmp && rm -rf zont-rt && mkdir zont-rt && cd zont-rt
SRC=/Users/admin/Automation/HA-ZONT-Modbus/zont_config/<файл>.txt
python3 /Users/admin/Automation/HA-ZONT-Modbus/config-to-yml.py "$SRC" > a.yml
python3 /Users/admin/Automation/HA-ZONT-Modbus/yml-to-config.py a.yml > b.txt
tr -d '\r' < "$SRC" > A.txt; tr -d '\r' < b.txt > B.txt
diff A.txt B.txt # пусто = round-trip чистый
grep -c '^#Z' A.txt B.txt # счётчик объектов
📌 Нюанс кодировки: источник бывает в UTF-8, а
yml-to-config.pyвсегда пишет windows-1251 → наивныйdiffпокажет различия на кириллице. Сравнивать структуру и числовые поля, либо нормализовать кодировку с обеих сторон.
5. Питфоллы
| # | Питфолл | Как обойти |
|---|---|---|
| 1 | 🔴 Вывод yml-to-config.py — windows-1251 + CRLF, не UTF-8 |
Редирект в файл и передавать байтами. Не копипастить из терминала, не пересохранять в редакторе |
| 2 | 🔴 Пустой raw у типов 0/36 → молчаливая подстановка дефолтов |
Не трогать raw*-поля |
| 3 | 🔴 Правка #S… в YAML бессмысленна — они хранятся как raw_payload |
Системные настройки менять только через UI контроллера |
| 4 | YAML на входе yml-to-config.py — строго UTF-8; выход — windows-1251. Плюс автоопределение кодировки при чтении .txt (UTF-8 → windows-1251) |
Править YAML в UTF-8. Исходный .txt не пересохранять в редакторе |
| 5 | Неизвестный тип объекта → exit 2, файл не создаётся | Смотреть stderr — там причина |
| 6 | validate_config() → exit 4 |
Печатает ❌ VALIDATION ERRORS + список причин; файл намеренно не выдан (вывод пустой) |
| 7 | Регистр без своего устройства / аналоговый выход с битой ссылкой | WARNING в stderr, конвертация продолжается — проверить ссылки вручную |
| 8 | Загрузка конфига в контроллер — руками, скрипты только конвертируют | Конвертер не имеет доступа к ZONT |
| 9 | INFRASTRUCTURE.md, docker-compose.yml, docker run.txt в проекте — исторический TrueNAS-стек |
Актуальный контур — family/how-to/home-automation. Не искать modbus-bridge/mbusd на NAS |
| 10 | Дополнительных зависимостей нет | Только pyyaml — jsonschema/ruamel не нужны |
6. Связанные заметки
- family/tech/zont-config-object-types — таблица типов объектов (0, 1…57, 36) и
#S-настройки - family/how-to/home-automation — контур автоматизации, ZONT, Modbus slave ID и регистры (§6)
- family/how-to/gitea-config — Gitea: креды, создание репо, питфоллы
- family/how-to/ha-automations — автоматизации HA