diff --git a/family/how-to/zont-config-compiler.md b/family/how-to/zont-config-compiler.md index 357495d3..2df38513 100644 --- a/family/how-to/zont-config-compiler.md +++ b/family/how-to/zont-config-compiler.md @@ -380,9 +380,22 @@ diff A.txt B.txt # пусто = round-trip чистый --- -## 5c. 🔄 Переработка структуры YAML сценариев — СОГЛАСОВАНО, в работе (2026-09-17) +## 5c. 🔄 Переработка структуры YAML сценариев — ПРИОСТАНОВЛЕНО, ждёт решения (2026-09-17) -**Задача Alex:** «переписать блок парсинга/сборки сценариев чтобы он составлял синтаксис как у Home Assistant automations вместо текущей разбросанной структуры. с опциональными айдишниками у операторов». +> ⏸ **СТАТУС: РАБОТА НЕ НАЧАТА. Alex дал «стоп» и поставил под сомнение сам проект.** +> Причина — исследование облачного API ZONT ([[family/tech/zont-api]]): Alex предположил, что +> у ZONT есть свой API/формат, покрывающий датчики и автоматику, и спросил — доделывать конвертер +> или переписать всё с 0. +> +> **Результат исследования: API конфиг не поддерживает** (сценарии/реле/11/14/46/49 — в API нет, +> `scenario` в доке 0 раз). Переписывать с 0 **не на что**. Конвертер остаётся единственным путём +> к сценариям. **Новый открытый вопрос Alex'у:** нужен ли онлайн-мониторинг ZONT в HA +> (отдельный проект на API, дополняет конвертер). +> +> ⚠️ **Код конвертера НЕ тронут.** Коммит `199f2b1` — последнее рабочее состояние. +> Не начинать §5c без явного «делай» от Alex. + +**Задача Alex (исходная):** «переписать блок парсинга/сборки сценариев чтобы он составлял синтаксис как у Home Assistant automations вместо текущей разбросанной структуры. с опциональными айдишниками у операторов». ### 🔴 Правка постановки Alex'ом (ключевое — не повторять ошибку) @@ -497,6 +510,7 @@ scenarios: | одноимённый `.yml` | ✅ **пересобран, 80 472 байта / 4320 строк / 24 секции**, YAML валиден. **не в git** | | `zont_config/archive/` | **не в git** (`untracked`) — лежит в `.gitignore`-нейтральном состоянии | | `zont_config/H2000_PRO_config_actual-{2,3,4}.txt` / `.yml` | ✅ **перемещены в `archive/` и закоммичены** (`7ae0e32`) | +| `zont_api_docs/` | ✅ **новая папка** — локальная копия доки облачного API ZONT (`zont_api_docs.html` 250 KB, `zont_api_docs.txt` 99 KB, `convert.py`). **не в git**. Исследование — [[family/tech/zont-api]] | Не запушено: `origin/main..HEAD` = 3 коммита (`199f2b1`, `7ae0e32`, `12ba22b`). @@ -521,6 +535,7 @@ Alex их не добавлял. Не коммитить без команды. - [[family/tech/zont-config-object-types]] — таблица типов объектов (0, 1…57, 36) и `#S`-настройки - [[family/tech/zont-scenario-logic-11109]] — разобранная логика сценария «Передёрнуть Автомат Котельной» +- [[family/tech/zont-api]] — **облачный API ZONT: конфиг не поддерживает**; альтернатива конвертеру отсутствует - [[family/how-to/home-automation]] — контур автоматизации, ZONT, Modbus slave ID и регистры (§6) - [[family/how-to/gitea-config]] — Gitea: креды, создание репо, питфоллы - [[family/how-to/ha-automations]] — автоматизации HA diff --git a/family/tech/zont-api.md b/family/tech/zont-api.md new file mode 100644 index 00000000..3b0668cf --- /dev/null +++ b/family/tech/zont-api.md @@ -0,0 +1,224 @@ +--- +aliases: + - ZONT API + - zont-online API + - ZONT cloud API + - ZONT update_device +created: '2026-09-17' +namespace: family +related: + - '[[family/how-to/zont-config-compiler]]' + - '[[family/tech/zont-scenario-logic-11109]]' + - '[[family/tech/zont-config-object-types]]' + - '[[family/how-to/home-automation]]' +tags: + - family + - tech + - zont + - api + - reference +title: "\U0001F310 ZONT Cloud API — что умеет и чего в нём нет" +type: reference +updated: '2026-09-17' +--- + +# 🌐 ZONT Cloud API — что умеет и чего в нём нет + +> **Исследовано 2026-09-17** по запросу Alex: «У зонта есть api и вероятно свой какой-то формат +> включая все датчики и автоматику. Изучай подробно вопрос… что нам для комфортного управления +> контроллером на самом деле надо. Доделывать конвертер или переделать все с 0.» +> +> **Итог одной строкой:** облачный API ZONT **не работает с конфигом** (сценарии, реле, шаги, +> условия). Конвертер `.txt ⇄ .yml` — по-прежнему **единственный** путь к правке сценариев. +> API годится только для **мониторинга** и узкого набора настроек (отопление). + +--- + +## 1. Локальная копия доки (в проекте) + +Доки скачаны в проект, не в `/tmp` (указание Alex: «качай доки в папку в проекте а не в темп»): + +| Файл | Размер | Что это | +|---|---|---| +| `/Users/admin/Automation/HA-ZONT-Modbus/zont_api_docs/zont_api_docs.html` | 250 KB | полная дока как есть (одна страница) | +| `…/zont_api_docs.txt` | 99 KB / 3381 строка | читаемый текст, таблицы → ` \| ` | +| `…/convert.py` | — | воспроизводимая HTML→text конвертация | + +```bash +cd /Users/admin/Automation/HA-ZONT-Modbus/zont_api_docs +curl -s -L 'https://zont-online.ru/api/docs/' -o zont_api_docs.html # обновить +python3 convert.py # → zont_api_docs.txt +``` + +> 📌 **Вся дока — ОДНА страница.** Отдельных URL вида `/api/docs/update_device` **нет** (404). +> Ссылки `#update_device` — это внутренние якоря. Не пытаться качать методы по отдельности. + +--- + +## 2. Полный список методов API (всего 11) + +| Метод | Назначение | Пишет конфиг? | +|---|---|---| +| `get_authtoken` | получить токен (Basic auth → `X-ZONT-Token`) | — | +| `devices` | список устройств + **Настройки**; `load_io: true` → ещё и **Состояния** | — | +| `update_device` | **изменение Настроек** устройства | ⚠️ узкий набор, см. §4 | +| `set_io_port` | управление Состоянием: `guard-state`, `siren`, `engine-block`, `webasto` | — | +| `send_custom_command` | послать пользовательскую команду по `command_id` | — | +| `load_data` | **история** данных за период (типы: `temperature`, `events`, `z3k_*`…) | — | +| `raw_events` | история событий (обёртка над `load_data`) | — | +| `temperature` / `thermostat_work` / `custom_controls` / `ztc_state` | история / состояние | — | +| `generate_archive` / `download_generated_archive` | выгрузка архива | — | +| `add_device` / `delete_device` | добавить / удалить устройство | — | + +### Формат запроса + +``` +POST https://my.zont.online/api/ +Header: X-ZONT-Client: (обязательный) +Auth: Basic ИЛИ X-ZONT-Token: +Body: JSON (предпочтительно) / form-encoded / GET-параметры +Ответ: JSON, всегда поле "ok": true|false; при ошибке "error" + "error_ui" +``` + +Рекомендованный поток аутентификации: `get_authtoken` (с логином/паролем) → дальше по токену, +пароль не хранить. При `403` токен мог быть отозван — перезапросить. + +--- + +## 3. 🔴 Главный вывод: конфига в API НЕТ + +**Проверено фактом по локальной копии доки:** + +| Что искали | Найдено в доке | +|---|---| +| слово `scenario` | **0 раз** | +| слово `relay` | **1 раз** | +| `z3k_config` (конфиг контроллера) | **2 раза** — только как ссылка для ID | +| метод для чтения/записи `z3k_config` | **нет** | + +Наши объекты конфига — сценарии (**11**), реле (**14**), шаги (**46**), условия (**49**), +задержки (**45**) — в API **не представлены вообще**. Ни чтения, ни записи. + +`z3k_config` упоминается лишь как источник числовых ID: в `z3k_temperature` «ключом является +ID объекта из `z3k_config`», в `z3k_boiler_adapter` — «ID адаптера из `z3k_config` (например 4097, 4098)». +То есть API **ссылается** на конфиг, но **работать с ним не даёт**. + +> ⚠️ Это не «ещё не нашли метод» — это перебор **всех** 11 методов из оглавления доки. +> `send_custom_command` — не то: он шлёт заранее заданную в настроечной утилите команду по `command_id`. + +--- + +## 4. Что `update_device` реально умеет + +Единственный метод, который меняет Настройки. Доступные области (по разделам доки): + +| Раздел | Ключи настроек | +|---|---| +| Общие | `name`, `serial`, `timezone` | +| Беспроводная сеть | `balance` (`ussd`/`warning`/`limit`), `trusted_phones`, `gsm_roaming` | +| Управление отоплением (ZONT H) | `thermostat_mode`, `thermostat_mode_temps`, `thermostat_ext_mode`, `thermostat_ext_modes_config`, `tempschedule`, `thermometers`, `ot_*` (OpenTherm) | +| Пользовательские команды (ZTC-7xx, Mega SX) | `custom_controls` — **не наш случай** (H-2000 PRO) | +| Авто (ZTC) | `auto-ignition`, двери/капот/багажник | + +> 🔴 **Для H-2000 PRO через API доступно практически только отопление** — режимы, целевые +> температуры, расписание, параметры OpenTherm. Сценариев/реле там нет. + +**Семантика:** для составного параметра можно передать **часть** внутренних полей — остальные +сохранят прежние значения. Ответ содержит **только изменённые** параметры и их новые значения. + +```json +// запрос +{"device_id": 1580, "thermostat_mode_temps": {"comfort": 21}} +// ответ — изменилось только comfort, остальные вернулись как есть +{"ok": true, "thermostat_mode_temps": {"comfort": 21, "econom": 16, "idle": 5, "full_off": false}} +``` + +--- + +## 5. `load_data` — история (только чтение) + +```json +POST https://my.zont.online/api/load_data +{"requests": [ + {"device_id": 1580, "data_types": ["temperature", "events"], + "mintime": 1495011600, "maxtime": 1495022400} +]} +``` + +Ответ: `responses[]` в том же порядке, что `requests`, каждый с полями по имени типа данных. +Времена — **unix time** (секунды, UTC). Вложенные параметры → **только** `Content-Type: application/json`. + +**Формат значений — Delta-time Array (DTA):** массив пар `[delta_секунд, значение]`, где первая +метка абсолютная, последующие — **отрицательные смещения** назад во времени. + +**Типы данных (`data_types`), релевантные нашему контуру:** + +| Тип | Для чего | Модели | +|---|---|---| +| `temperature` | показания температурных датчиков | — | +| `events` | события | — | +| `z3k_temperature` | история датчиков, **ключ = ID объекта из `z3k_config`** | H-2000+, H-2000 PRO, Climatic, H1V.02, SMART NEW | +| `z3k_radio_sensor` | радиодатчики | по аналогии | +| `z3k_heating_circuit` | контуры отопления | по аналогии | +| `z3k_web_element` | пользовательские кнопки | по аналогии | +| `z3k_boiler_adapter` | котёл по OpenTherm / EMS / BSB — **шаг до 1 мин** | H-2000+ / PRO / PRO.V2 | +| `custom_controls` | пользовательские статусы (битовая маска) | Mega SX, H-1000, ZTC | +| `ztc_state` | питание, GSM, Wi-Fi | — | + +> `z3k_boiler_adapter` даёт те же ряды, что графики в личном кабинете: `s` (флаги состояния +> `ch`/`dhw`/`fl`/`cl`/`ch2`/`di`/`f`), `cs`/`cs2` (расчётная t теплоносителя), `bt` (фактическая), +> `rwt` (обратка), `dt` (ГВС), `ot` (улица), `rml` (модуляция горелки), `wp` (давление), +> `ff` (авария `{c, f}`), `rp`/`rt`/`rors`/`db`/`b` (уставки) и др. + +**`custom_controls` — битовая маска:** значение — целое, каждый бит = состояние статуса с этим id. +``` +[[1498710120, 0], [-86, 6], [-5, 2]] +→ все статусы выкл → через 86 с включились статусы 1 и 2 (6 = 110₂) → ещё через 5 с статус 2 выключился +``` + +--- + +## 6. Ответ на вопрос «доделывать или переделать с 0» + +**Переделать с 0 — не на что.** API не предоставляет доступа к сценариям/реле, поэтому +«переписать управление на API» технически невозможно. Переписать можно было бы только +**мониторинг**, и это дополнение, а не замена. + +| Путь | Что даёт | Ограничение | +|---|---|---| +| **1. Конвертер `.txt ⇄ .yml`** (текущий) | правка сценариев, реле, датчиков, Modbus | загрузка в контроллер **руками** | +| **2. API-обвязка (дополнение)** | онлайн-состояния (`devices?load_io=true`), история (`load_data`), отопление (`update_device`), сирена/охрана (`set_io_port`) | сценарии **недоступны** | +| **3. «Переделать с 0»** | ❌ не существует API, на который переписать | + +### Рекомендация (доложена Alex, решения пока нет) + +- **Конвертер не выкидывать** — он единственный путь к сценариям. Доделывать §5c + (`blocks/if/then`, см. [[family/how-to/zont-config-compiler]]) имеет смысл. +- **API-обвязка — отдельная задача на потом:** мониторинг реле/датчиков, графики из + `load_data`, правка режимов отопления. **Дополняет** конвертер, не заменяет. +- **Открытый вопрос Alex'у:** нужен ли онлайн-мониторинг ZONT в HA. От ответа зависит, + браться ли за API-часть вообще. + +--- + +## 7. Питфоллы + +| # | Питфолл | Как обойти | +|---|---|---| +| 1 | 🔴 Вся дока — **одна страница**; `/api/docs/` → **404** | Качать только `https://zont-online.ru/api/docs/` целиком | +| 2 | 🔴 `send_custom_command` **всегда возвращает `ok: true`**, даже если связи нет или отправка не удалась | Не считать `ok` подтверждением доставки | +| 3 | `load_data` принимает вложенные параметры → **только JSON**, не form-encoded | `Content-Type: application/json` обязателен | +| 4 | `mintime`/`maxtime` — **unix time в секундах, UTC** | Не путать с миллисекундами | +| 5 | `custom_controls` — **битовая маска**, не массив состояний | Разбирать побитово; биты считаются с нуля от младшего | +| 6 | DTA — вторая и последующие метки **отрицательные** (смещения назад) | Не читать их как абсолютное время | +| 7 | `update_device` при `403` — токен мог быть отозван | Перезапросить `get_authtoken` | +| 8 | Дока **обновляется**, часть функций может отсутствовать | При нехватке метода — писать на `admin@zont.online` | + +--- + +## 8. Связанные заметки + +- [[family/how-to/zont-config-compiler]] — конвертеры `.txt ⇄ .yml`; §5c — план переработки YAML +- [[family/tech/zont-scenario-logic-11109]] — структура сценариев 11/46/49/45 +- [[family/tech/zont-config-object-types]] — таблица типов объектов конфига +- [[family/how-to/home-automation]] — контур автоматизации, ZONT, Modbus (§6) diff --git a/family/tech/zont-config-object-types.md b/family/tech/zont-config-object-types.md index 2129164b..cc8f3767 100644 --- a/family/tech/zont-config-object-types.md +++ b/family/tech/zont-config-object-types.md @@ -131,5 +131,6 @@ Modbus-регистры (тип 52) в конфиге — **отдельные - [[family/how-to/zont-config-compiler]] — как пользоваться конвертерами, питфоллы, обход - [[family/tech/zont-scenario-logic-11109]] — структура сценариев 11/46/49/45, разбор «Передёрнуть Автомат Котельной» +- [[family/tech/zont-api]] — облачный API ZONT: конфиг через него недоступен - [[family/how-to/home-automation]] §6 — карта slave ID, регистры AT2/реле/заслонок в HA - [[family/tech/t610-hang-investigation]] — расследование зависаний хоста (не связано напрямую, но тот же контур) diff --git a/family/tech/zont-scenario-logic-11109.md b/family/tech/zont-scenario-logic-11109.md index a01474fb..5f6ed07c 100644 --- a/family/tech/zont-scenario-logic-11109.md +++ b/family/tech/zont-scenario-logic-11109.md @@ -194,12 +194,18 @@ scenarios: - {id: 11828, action: wait, ms: 0} # задержка из поля 2 сценария ``` -Полный план и открытые вопросы — [[family/how-to/zont-config-compiler]] §5c. +Полный план — [[family/how-to/zont-config-compiler]] §5c. + +> ⏸ **РАБОТА ПО §5c ПРИОСТАНОВЛЕНА (2026-09-17).** Alex дал «стоп» и запросил исследование облачного +> API ZONT — есть ли альтернатива конвертеру. **Ответ: API конфиг не поддерживает** (сценарии/реле/ +> 11/14/46/49 в API отсутствуют). Переписывать с 0 не на что, конвертер остаётся единственным путём. +> Разбор — [[family/tech/zont-api]]. Форма `blocks/if/then` выше — **предложение, в коде не реализовано**. --- ## 7. Связанные заметки - [[family/how-to/zont-config-compiler]] — конвертеры `.txt ⇄ .yml`; 2 шага и тип 45 **поддержаны с 2026-09-17** (§5b) +- [[family/tech/zont-api]] — облачный API ZONT: конфиг не поддерживает, альтернативы конвертеру нет - [[family/tech/zont-config-object-types]] — полная таблица типов объектов и `#S`-настройки - [[family/how-to/home-automation]] — контур автоматизации, ZONT, Modbus slave ID и регистры