[2026-09-17] eagle: family/how-to/zont-config-compiler.md family/tech/zont-api.md family/tech/zont-config-object-types.md family/tech/zont-scenario-logic-11109.md

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

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/<method>
+Header: X-ZONT-Client: <email>            (обязательный)
+Auth:   Basic <login:password>  ИЛИ  X-ZONT-Token: <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/<method>` → **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)

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]] — расследование зависаний хоста (не связано напрямую, но тот же контур)

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 и регистры