# aircon / FGLair local control

Реконструкция LAN-протокола FGLair (Fujitsu General, платформа Ayla) и планы
монорепозитория стека локального управления кондиционером: базовая C++
библиотека + интеграции ESPHome и Home Assistant.

## Состав репозитория (целевая структура)

```
CMakeLists.txt               # базовая библиотека (корень)
include/fgl-aircon/          # публичный API (уровень aircon: конверсии, шаблоны)
src/ayla/                    # протокол Ayla LAN + главный цикл сообщений
  platform/{posix,esp-idf}/  # платформенный слой
src/aircon/                  # конверсии, шаблоны A/B/F, реализация API
third_party/jsmn/            # вендоренный JSON-парсер (MIT)
components/fglair/           # ESPHome external component
custom_components/fglair/    # Home Assistant custom component
tests/{ayla,aircon}/         # тесты протокола / конверсий и шаблонов
tests/acceptance/            # полуавтоматическая приёмка ESPHome<->HA
tools/                       # probe_reference.py, probe_mdns.py, fglair-discover
docs/                        # документация (ниже) + материалы анализа
```

## Документация

| Файл | Назначение |
|------|-----------|
| `PROTOCOL.md` | Спецификация LAN-протокола: шифрование, эндпоинты, машина состояний, тайминги, свойства FGLair. Для людей и агентов. Факты помечены `[APK]` / `[LEGACY]` / `[ПРОВЕРЕНО НА ПРИБОРЕ]` / `[HYP]`. |
| `LEGACY_ANALYSIS.md` | Разбор legacy-скрипта: что верно, баги, причины «рассинхронизации ключей» и перегрузки модуля. |
| `PLAN_CORE_LIBRARY.md` | План C++20-библиотеки `fgl-aircon` (Linux + ESP-IDF): слои ayla/aircon, конверсии, оценка httpd/json-библиотек, монорепо-структура. |
| `PLAN_HOME_ASSISTANT.md` | План HA-интеграции: pyfglair (cffi wheel), config flow с превью шаблона, HACS-README со скриншотами. |
| `PLAN_ESPHOME.md` | План ESPHome-компонента: host+DNS, секреты, кастомные конверсии-лямбды, advanced-пример, приёмка. |
| `legacy/` | Изменённый legacy-скрипт (форк [gyro-labs/AirCon](https://github.com/gyro-labs/AirCon) / hisense_ac): `main.py` + пакет `aircon/`. Локальный `config_kata.json` не версионируется (содержит lanip_key). |
| `apk/` | Материалы анализа APK FGLair 3.4.3 (`manifest.json`; .apk-бинарники лежат локально, не версионируются). |

## Краткая выжимка протокола

* Модуль кондиционера (порт 80) сам подключается к серверу приложения (порт 10275):
  `local_reg.json` (keep-alive/notify) → `key_exchange.json` → poll
  `commands.json` + push `property/datapoint.json`.
* Шифрование: AES-256-CBC (no-padding, zero-pad) + HMAC-SHA256; ключи выводятся
  из облачного `lanip_key` и двух пар (random, time). **CBC-цепочка непрерывна
  в рамках сессии**.
* **Ключевая механика надёжности** (проверено на приборе): модуль игнорирует
  400/401-ответы; единственное самолечение — принудительный re-key, который
  модуль делает при получении `local_reg` для сессии старше ≈44 с. Поэтому
  keep-alive должен быть 10–15 с — тогда любая рассинхронизация живет секунды,
  а не 20 минут (как в legacy-скрипте с интервалом 1200 с).
* Максимум 2 LAN-сессии (телефон + сервер уживаются), третья — HTTP 503.
* Записи свойств не эхируются — состояние обновляется оптимистично,
  подтверждение через GET.
* Свойства FGLair (шаблоны A/B/F по oem_model): `operation_mode` (0..6),
  `fan_speed` (0..4), `adjust_temperature` (×0.1 °C), `display_temperature`
  ((v−5000)/100 °C), swing/заслонки, флаги economy/powerful/…, битмаски
  `op_status`, `device_capabilities`. Полные таблицы — в PROTOCOL.md §8.

## Ключевые решения (по уточнениям владельца)

* Монорепозиторий: библиотека в корне, `components/fglair` (ESPHome),
  `custom_components/fglair` (HA); тесты зеркалят слои (`tests/ayla`,
  `tests/aircon`); библиотека логически разделена на `src/ayla` (протокол)
  и `src/aircon` (конверсии/шаблоны/API), публичный интерфейс —
  `include/fgl-aircon/`.
* Конверсии свойств задаются шаблоном по умолчанию, коэффициентами
  (linear) или функцией-указателем (ESPHome — лямбды, HA — коэффициенты
  + превью рассчитанных значений при настройке).
* `lanip_key` **статичен** (зашит в модуль; за 5 лет ротаций не было).
  Облако — только provisioning (HA config flow, CLI `fglair-discover`);
  для ESPHome ключ копируется из диагностики HA или CLI. При несовпадении
  `key_id` — устойчивая ошибка, лечение правкой конфига вручную.
* ESPHome: везде ESP-IDF framework, подключение по `host` (DNS/mDNS), все
  чувствительные значения — через `!secret`.
* HTTP/JSON: собственный мини-httpd/httpc на BSD-сокетах (одна реализация
  для lwip/posix) + вендоренный jsmn; esp_http_server/cJSON/ArduinoJson
  отвергнуты (обоснование — PLAN_CORE §7). Conan не нужен.
* Приёмка: полуавтоматический скрипт `tests/acceptance/` (HA long-lived
  token + REST, ESPHome через aioesphomeapi; quick/burst и 24-часовой
  режимы).

## Порядок реализации

1. `fgl-aircon` (M0–M4) — ядро (ayla → aircon), mock-тесты; эталон
   `tools/probe_reference.py` уже проверен на приборе.
2. `pyfglair` + HA-интеграция (H1–H5) — параллельно с E1–E2.
3. ESPHome-компонент (E1–E4).
4. Приёмочные прогоны (quick + 24 ч), README компонентов.
5. Уточнение оставшихся неизвестных (PROTOCOL.md §10) по мере эксплуатации.

## Источники

* APK FGLair 3.4.3 (`apk/com.fujitsu.fglair.apk`): классы
  `com.aylanetworks.aylasdk.lan.*`, `com.fujitsugeneral.aylasdk.*`,
  `com.cafbit.netlib.dns.NetThread`, JS-бандл `assets/www/dist/build.js`.
* Legacy-скрипт (`legacy/`) — изменённый форк gyro-labs/AirCon (hisense_ac).
* Живые эксперименты на AP-WC1E (сентябрь 2026): сессии, re-key, 401/400,
  слоты/503, delete_session, записи, mDNS. Рабочие артефакты — `tools/`.