fgl-aircon/docs/PLAN_CORE_LIBRARY.md

План: базовая библиотека fgl-aircon (C++20, Linux + ESP-IDF) в монорепозитории

Целевая аудитория — агенты-реализаторы. Протокольные детали — в PROTOCOL.md (ссылки вида «§N»; факты помечены [ПРОВЕРЕНО НА ПРИБОРЕ]). Причины проектных решений — LEGACY_ANALYSIS.md.

0. Монорепозиторий

Все три компонента живут в одном репозитории:

/                             # CMakeLists.txt базовой библиотеки — в корне
  include/fgl-aircon/         # публичный API (уровень aircon)
  src/
    ayla/                     # реализация протокола + главный цикл сообщений
      platform/
        posix/                # сокеты/std::thread/timerfd/getrandom
        esp-idf/              # lwip-сокеты/esp_timer/esp_random
    aircon/                   # конверсии, шаблоны, реализация публичного API
  third_party/jsmn/           # вендоренный JSON-парсер (MIT)
  components/fglair/          # ESPHome external component (см. PLAN_ESPHOME)
  custom_components/fglair/   # HA custom component (см. PLAN_HOME_ASSISTANT)
  tests/
    ayla/                     # тесты протокола (KDF, envelope, http, сессия+mock)
    aircon/                   # тесты конверсий и шаблонов
    acceptance/               # скрипты приёмки ESPHome<->HA (см. §11)
  tools/                      # probe_reference.py, probe_mdns.py, fglair-discover
  docs/

Подключение к сборке:

• ESP-IDF: корень репозитория регистрируется как компонент (idf_component.yml/CMakeLists.txt с idf_component_register); ESPHome- компонент (components/fglair) подключает его через EXTRA_COMPONENT_DIRS / relative path.
• POSIX: cmake -S . -B build && cmake --build build — статическая библиотека fgl-aircon + цели тестов.

1. Слои библиотеки (логическое разделение, сборка — одна)

приложение (HA / ESPHome / fglctl)
   │  include/fgl-aircon/*.hpp      — публичный API
   ▼
src/aircon   — свойства и их семантика: таблицы шаблонов A/B/F,
               конверсии (шаблонные/линейные/функцией), кэш значений,
               адаптация к публичному API. Не знает про сеть.
   │  src/ayla/session.hpp (внутренний интерфейс)
   ▼
src/ayla     — протокол Ayla LAN: crypto/KDF, envelope, HTTP-сервер/клиент
               (mini-httpd/httpc), очередь команд с coalescing и pacing,
               главный цикл сообщений (один поток/задача), re-key, слоты,
               keep-alive. Не знает про свойства кондиционера.
   │
   ▼
src/ayla/platform/*  — сокеты, таймеры, CSPRNG, лог (posix | esp-idf)

Правила слоёв:

• aircon → ayla → platform, зависимости только вниз.
• ayla оперирует «непрозрачными» именами свойств (строки) и целыми — вся семантика (°C, режимы, флаги, битмаски) — в aircon.
• Публичный API — только include/fgl-aircon/; внутренние заголовки лежат рядом с реализациями (src/ayla/*.hpp, src/aircon/*.hpp).

2. Цели и не-цели

Цели:

1. Реализовать LAN-протокол FGLair/Ayla (сторона «приложения») по PROTOCOL.md, поведение — как у APK и подтверждено живыми тестами.
2. Портативность: ESP-IDF (esp32/esp32s3/esp32c3, только IDF-фреймворк) и POSIX (Linux) из одной кодовой базы.
3. Малый footprint: без heap после init(), без исключений/RTTI наружу, логирование через callback, статические буферы.
4. Интеграция «как у climate-модулей ESPHome»: асинхронный API, колбэки.
5. Устойчивость: re-key (модуль ротирует ключи каждые ≈44–60 с), перезагрузка модуля, слоты/503, режим «KE без активации»; жёсткий rate-control.

Не-цели (первая версия):

• Облако в рантайме. lanip_key статичен (зашит в модуль, 5 лет без ротаций); провижининг — Python CLI tools/fglair-discover. Несовпадение key_id → устойчивое состояние ошибки до правки конфига вручную.
• Узловые устройства, setup-режим (RSA), OTA.
• Hisense-свойства (t_power и пр.) — только шаблоны A/B/F.

3. Публичный API (эскиз include/fgl-aircon/)

// types.hpp
enum class fgl_state { idle, registering, online, recovering, offline, key_error };
enum class fgl_prop { operation_mode, fan_speed, adjust_temperature,
                      display_temperature, af_vertical_direction, af_vertical_swing,
                      af_horizontal_direction, af_horizontal_swing, economy_mode,
                      powerful_mode, coil_dry_mode, min_heat, outdoor_low_noise,
                      indoor_fan_control, human_det_auto_save, wifi_led_enable,
                      op_status, error_code, device_capabilities, demand_control,
                      get_prop, device_name, building_name /* ...PROTOCOL §8.2 */ };
enum class fgl_template { A, B, F };
struct fgl_value { enum kind { boolean, integer, string } type;
                   bool b; int32_t i; const char* s; };

// --- конверсии: шаблон по умолчанию, коэффициенты или функция (см. §4) ---
enum class fgl_conv_kind { template_default, linear, custom_fn };
struct fgl_linear { int32_t num, den, offset; };     // disp = raw*num/den + offset
struct fgl_conversion {
  fgl_conv_kind kind = fgl_conv_kind::template_default;
  fgl_linear linear{};                               // при kind == linear
  int32_t (*fn)(int32_t raw, void* ctx) = nullptr;   // при kind == custom_fn
  void* ctx = nullptr;
};
struct fgl_prop_override {           // точечная настройка одного свойства
  fgl_prop prop;
  bool has_range = false; int32_t min = 0, max = 0;
  fgl_conversion to_display{};       // raw -> инженерные единицы
  fgl_conversion from_input{};       // ввод -> raw
};

struct fgl_config {
  const char* host;           // DNS-имя или IP ("ac.local" / "192.168.0.42")
  const char* dsn;            // "AC000W00XXXXXXX"
  const char* lanip_key;      // base64-строка как есть
  uint32_t    lanip_key_id;
  fgl_template template_;
  uint16_t    listen_port;    // 0 => 10275
  uint32_t    keepalive_ms;   // 0 => 15000
  uint8_t     max_queue;      // 0 => 16
  const fgl_prop_override* overrides = nullptr;   // nullptr-terminated
};
struct fgl_callbacks {
  void (*on_state)(void* user, fgl_state st, int err);
  void (*on_property)(void* user, fgl_prop p, const fgl_value* v);
  void (*on_log)(void* user, int level, const char* msg, size_t len);
  void* user;
};

// session.hpp (C++-классы; c_api.h — extern "C" шейм для cffi/HA)
class FglSession {
 public:
  static FglSession* create(const fgl_config&, const fgl_callbacks&);
  int start(); int stop();          // stop() шлёт delete_session (≤2с)
  fgl_state state() const;
  int set_bool(fgl_prop, bool); int set_int(fgl_prop, int32_t);
  int get_prop(fgl_prop);
  int batch_begin(); int batch_commit();
  bool cached(fgl_prop, fgl_value* out) const;
};

// templates.hpp — интроспекция шаблонов (для превью в HA, тестов, CLI):
//   список свойств шаблона, base_type, RO, диапазоны, примеры конверсии
const fgl_template_info* fgl_template_info_get(fgl_template);
int32_t fgl_convert_to_display(fgl_template, fgl_prop, int32_t raw,
                               const fgl_prop_override* ov);
int32_t fgl_convert_from_input(fgl_template, fgl_prop, int32_t disp,
                               const fgl_prop_override* ov);

4. Конверсии (требование: задаются руками при необходимости)

Каждое числовое свойство имеет конверсию по умолчанию из таблицы шаблона (adjust_temperature: ×0.1 °C; display_temperature: (v−5000)/100; направления: 0..N−1; перечисления — словари). Конфиг сессии может переопределить её для любого свойства одним из способов:

1. Коэффициенты fgl_linear {num, den, offset} — для линейных величин (температуры, проценты). Без кода, доступно из HA UI и YAML.
2. Функция-указатель int32_t (*)(int32_t raw, void* ctx) — произвольная логика; ctx для захваченных данных. ESPHome-лямбды компилируются в функции и передаются напрямую (пример — PLAN_ESPHOME §2); HA ограничен коэффициентами (и выбором шаблона).
3. Диапазоны (min/max) переопределяются независимо от конверсии.

Конверсия применяется в src/aircon на границе API: наружу — «инженерные» единицы (0.1 °C уже умножено? — НЕТ: наружу отдаётся значение в единицах конверсии, см. ниже), в протокол — raw. Договорённость о единицах наружу фиксируется в README: наружу отдаётся результат to_display (для шаблона A температуры — °C×1 float-friendly int? — принимаем: наружу int32 в «инженерных» единицах, кратность задаёт конверсия; для HA cffi этого достаточно, ESPHome при желании делит сам через лямбду).

5. Поведенческие требования (обязательны к точной реализации)

5.1. Установка сессии

1. start(): HTTP-сервер слушает listen_port (10275). Разрешение host: getaddrinfo (lwip DNS); для *.local — Ayla-mDNS запрос A-записи на 224.0.0.251:10276 (модуль НЕ отвечает на :5353 — проверено). Ретраи разрешения при недоступности.
2. POST /local_reg.json?dsn=<DSN> с notify=0 (PROTOCOL §4.1). Ответы: 202 — ок; 503 — нет слотов (2 заняты) → offline/FGL_E_NO_SLOT, повтор 30–60 с; отказ соединения → offline, backoff 1→60 с.
3. Дождаться key exchange (<1 с): ver/proto==1, sec=="" (иначе 426), сверка key_id (несовпадение → 412 + key_error до правки конфига). random_2 — 16 симв. [A-Za-z0-9], time_2 — наносекунды аптайма; вывести ключи (§3.2 PROTOCOL), ответить 200.
4. Активация = «пустой» опрос commands.json в течение ~0.5 с. Нет опроса 5 с → сессия не активировалась (известный режим зависания модуля): тишина + recovering с паузой 30–60 с (НЕ долбить local_reg).
5. После активации — пакет GET-команд свойств + ОДИН local_reg notify=1.

5.2. Keep-alive и re-key

• Таймер keepalive_ms (default 15000); по истечении — PUT local_reg c notify=(очередь непуста). Каждый commands.json перезапускает таймер.
• Re-key — событие по инициативе модуля (при зазоре local_reg ≥ ~44–50 с, [ПРОВЕРЕНО НА ПРИБОРЕ]; при штатном keep-alive НЕ происходит): обработать как обычный KE (перегенерация шифров/цепочек), сессию не пересоздавать, начальную синхронизацию не повторять; seq_no приложения продолжает глобальный счётчик.
• Восстановление при ошибке расшифровки: тишина > порога (50 с по умолчанию) и возврат — модуль гарантированно ре-кает [ПРОВЕРЕНО НА ПРИБОРЕ].
• Анти-спам: ≤1 local_reg/с; notify=1 — один на пакет команд.

5.3. Очередь команд

• Лимит max_queue (16); coalescing (write замещает write, GET-дубликаты отбрасываются). commands.json: одна команда из головы; 206/200; шифрование строго последовательно; паддинг Java-вариант (≥1 NUL).
• Записи не эхируются (проверено): оптимистичное обновление кэша; опционально GET-подтверждение через 1–2 с.

5.4. Входящие сообщения

• Datapoint push: расшифровка, подпись; seq_no не проверяется. Query ?cmd_id=N&status=200 — сопоставление GET-ожиданий. Ошибка расшифровки → 401 (APK-совместимость) + recovering (самолечение — ближайший keep-alive/re-key, ≤15 с).
• Ответы на GET также доставляются через datapoint push (в ayla они прозрачны наверх как обновления свойства).

5.5. Завершение

• stop(): DELETE local_reg.json/delete_session, выдача ≤2 с, закрыть сервер. Слот освобождается немедленно (проверено).

6. Криптография

mbedtls (в ESP-IDF встроен; POSIX — системный или FetchContent): AES-256-CBC с персистентным IV-состоянием между сообщениями (mbedtls_aes_crypt_cbc обновляет iv-буфер на месте — использовать его как состояние цепочки), HMAC-SHA256 через mbedtls_md. KDF — PROTOCOL §3.2; тестовые векторы — эталон tools/probe_reference.py (проверен на приборе).

7. HTTP и JSON: оценка готовых библиотек (решение)

Требования: no-heap после init, один код для ESP-IDF и POSIX, точный контроль поведения (keep-alive/RST-quirks модуля измерены на приборе), малый footprint.

JSON (парсер):

Кандидат	Оценка
ESP-IDF cJSON/esp_json	DOM + malloc на узлы → конфликтует с no-heap; IDF-only
ArduinoJson (есть в ESPHome)	v7 лишился zero-alloc-режима (StaticJsonDocument удалён); тянет зависимость ESPHome
RapidJSON (SAX + custom allocator)	Подходит технически, но тяжеловат (~10k строк) для наших 5 форматов сообщений
jsmn (MIT, 2 файла, ~300 строк)	Принято: токеновый парсер без аллокаций, стандарт де-факто embedded, раньше входил в ESP-IDF. Вендорим в third_party/jsmn/ — единый код для обеих платформ

Writer — собственный, с фиксированным буфером (~100 строк; наши данные не требуют сложного экранирования).

HTTP-сервер (входящие от модуля) и HTTP-клиент (local_reg):

Кандидат	Оценка
ESP-IDF esp_http_server	Есть, но: IDF-only (нужна вторая реализация для POSIX); роутинг по IP клиента — хак (httpd_req_to_sockfd + getpeername); меньше контроля над keep-alive/RK-quirks
cpp-httplib (POSIX)	Удобен, но heap + вторая ветка кода; LGPL/MIT ок
mongoose / civetweb / libmicrohttpd	Лицензии/вес избыточны

Решение: собственный мини-httpd + мини-httpc в src/ayla (~300+100 строк) поверх BSD-сокетов — lwip на ESP32 и glibc дают идентичный API, одна реализация, полный контроль. esp_http_server/третьилицевые httpd НЕ используем. HTTP-клиент (один POST/PUT с Content-Length) — тривиален.

Conan: не нужен — единственная внешняя зависимость (jsmn) вендорится. Если позже появятся POSIX-only зависимости (например, TLS для облачного инструмента) — подключить conan только для POSIX-ветки.

8. Таблицы свойств и конверсии (src/aircon)

constexpr-массивы на шаблон: {enum, имя, base_type, RO, диапазон raw, конверсия по умолчанию, словари перечислений}. Битовые декодеры op_status/device_capabilities (PROTOCOL §8.4–8.5). Точка расширения — fgl_prop_override (§4). Интроспекция fgl_template_info_get используется HA-превью (PLAN_HOME_ASSISTANT §4) и тестами.

9. Тесты (разделение как у src)

• tests/ayla/ — протокол: KDF-векторы; envelope roundtrip (оба паддинга); CBC-цепочка (3 сообщения); мини-httpd/httpc (запросы модуля, keep-alive, RST); очередь/coalescing/pacing; машина состояний с mock-модулем (tests/ayla/mock_ac.py — развитие probe_reference.py): обычная сессия, re-key по возрасту, 503-слоты, «KE без poll», потеря сообщения → 401 → восстановление, delete_session.
• tests/aircon/ — конверсии и шаблоны: все свойства всех шаблонов; линейные/функциональные override; диапазоны; битмаски; согласованность таблиц с PROTOCOL §8 (значения из APK).
• CI: gcc+clang -Wall -Werror, asan/ubsan, ctest; idf-сборка esp32.

10. Этапы

#	Содержимое	Критерии приёмки
M0 ✅	Монорепо-каркас: CMake (корень) + IDF-подключение, платслой, лог, CI	Собирается linux+esp-idf; пустой httpd отвечает 404
M1 ✅	src/ayla: crypto+envelope, мини-httpd/httpc, jsmn-вендор	Векторы зелёные; httpd-тесты; совместимость с probe_reference.py
M2 ✅	src/ayla: сессия (установка/активация/keep-alive/re-key/слоты/503/delete) с mock-модулем	Все сценарии mock; на приборе: активация ≤5 с; семантика re-key: при зазоре local_reg ≥ ~44–50 с (при честном keep-alive 15 с — 0 re-key за 100 с; при 50 с — 3 re-key)
M3	src/aircon: шаблоны, конверсии+override, публичный API, batch	tests/aircon зелёные; на приборе: чтение всех свойств, batch=1 notify
M4	fglctl-пример, tools/fglair-discover (в т.ч. --format esphome-secrets), README библиотеки (сборка IDF/POSIX, тесты)	24 ч на приборе: 0 рассинхронов; README готов
M5	(Опция) FglHub N устройств; mDNS-резолвер как опция host-разрешения	Два устройства одновременно

README.md библиотеки (после M4, для людей): сборка в ESP-IDF (как компонент), сборка POSIX (cmake), запуск тестов (ctest + mock), краткий пример API. Максимально коротко.

11. Приёмка ESPHome↔HA (скрипт в tests/acceptance/)

Полуавтоматизированный тест сквозной согласованности двух интеграций, работающих с одним кондиционером (занимают оба слота модуля — скрипт сам третью сессию НЕ открывает). Детали и авторизация — PLAN_ESPHOME §8 / PLAN_HOME_ASSISTANT §7 (HA long-lived access token + REST API — проверено, стандартный механизм; ESPHome — официальный aioesphomeapi). Режимы: quick (матрица изменений burst/не-burst, обе стороны, с возвратом) и --long (24 ч, раз в час одно изменение с проверкой и возвратом; CSV-отчёт). Запускается вручную; входит в чек-лист релиза.

12. Риски

• Режим «KE без poll» (PROTOCOL §4.4 п.6) — причина не идентифицирована; стратегия (пауза 30–60 с) эмпирическая; заложить телеметрию.
• Порог re-key ≈44 с (границы 39–44 с) — не опираться на точное значение.
• Конверсии через int32_t num/den — следить за переполнением (int64 промежуточно).