petr.polezhaev
a03458f9bc
- critical: README честно описывает HACS (только публичный GitHub-зеркало)
+ ручная установка копированием; RELEASE_HA — шаг зеркала и codeowners
- critical: ESPHome-канал приёмки реализован реально (aioesphomeapi:
connect/list_entities/climate_command для режима и уставки; fan/swing —
только HA); unit-тест на фейковом модуле
- major: quick/long восстанавливают исходное состояние в finally даже при
сбое; quick ждёт восстановления; ошибки шага пишутся в результат (rc 1),
а не фаталят (rc 2)
- major: RELEASE_HA — manylinux через auditwheel repair (PyPI отклоняет
linux_x86_64), build/twine, aarch64, корректные проверки .so, тег/версия
- major: полный ключ для ESPHome теперь реально виден в options flow
(«Настройка» на карточке интеграции, поле LAN IP key, можно заменить) —
README/diagnostics синхронизированы
- minor: non-JSON ответ → rc 2; CSV quick+long и инкрементальная запись;
допуск _matches в long; --settle-timeout; hacs.json homeassistant=2025.1;
brand/{icon,logo}.png заглушки; план §6/§7 уточнён
- тесты: acceptance self-test 11 (restore-after-failure, long fail, non-JSON,
esphome channel), options flow (2), всего 28+11+49
131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
# fglair-core
|
||
|
||
Local-control library for Fujitsu General air conditioners (FGLair / Ayla LAN
|
||
protocol). One C++20 codebase — Linux and ESP-IDF (ESP32) — with the full
|
||
protocol reconstructed from the official APK and verified on real hardware.
|
||
|
||
See [`docs/PROTOCOL.md`](docs/PROTOCOL.md) for the protocol reference and
|
||
[`docs/PLAN_CORE_LIBRARY.md`](docs/PLAN_CORE_LIBRARY.md) for the design.
|
||
|
||
## Layout
|
||
|
||
```
|
||
include/fgl-aircon/ public API (types, templates, session, C API for cffi)
|
||
src/ayla/ Ayla LAN protocol: crypto, envelope, HTTP, session loop
|
||
src/aircon/ property templates A/B/F, conversions, API implementation
|
||
pyfglair/ Python bindings (cffi) for Home Assistant (docs/PLAN_HOME_ASSISTANT.md)
|
||
components/ ESPHome external component (planned, docs/PLAN_ESPHOME.md)
|
||
custom_components/ Home Assistant custom component (docs/PLAN_HOME_ASSISTANT.md)
|
||
tests/ ayla (protocol), aircon (conversions), pyfglair, tools
|
||
examples/cli/ fglctl — sample CLI
|
||
tools/ fglair-discover, protocol probes
|
||
```
|
||
|
||
## Build (Linux / POSIX)
|
||
|
||
Requirements: CMake ≥ 3.16, Ninja (or Make), g++/clang with C++20, Mbed TLS
|
||
(system `libmbedcrypto`; otherwise it is fetched and built automatically).
|
||
|
||
```sh
|
||
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
|
||
cmake --build build
|
||
# CLI:
|
||
./build/fglctl <config.json> status
|
||
```
|
||
|
||
## Build (ESP-IDF component)
|
||
|
||
The repository root is an ESP-IDF component. Put it on `EXTRA_COMPONENT_DIRS`
|
||
(or copy into your project's `components/`):
|
||
|
||
```cmake
|
||
set(EXTRA_COMPONENT_DIRS "/path/to/aircon")
|
||
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
|
||
project(my_app)
|
||
```
|
||
|
||
```cmake
|
||
# main/CMakeLists.txt
|
||
idf_component_register(SRCS "main.cpp" PRIV_REQUIRES aircon)
|
||
```
|
||
|
||
```cpp
|
||
#include "fgl-aircon/session.hpp"
|
||
extern "C" void app_main() {
|
||
fgl::aircon::Config cfg{};
|
||
cfg.host = "ac.local"; // DNS name or IP
|
||
cfg.dsn = "..."; // from fglair-discover
|
||
cfg.lanip_key = "..."; // from fglair-discover (static per module)
|
||
cfg.lanip_key_id = 12345;
|
||
cfg.tmpl = fgl::aircon::template_detect("AP-WC1E");
|
||
fgl::aircon::Callbacks cbs{};
|
||
auto* s = fgl::aircon::Session::create(cfg, cbs);
|
||
s->start();
|
||
}
|
||
```
|
||
|
||
Tested with ESP-IDF v5.5 (esp32); no Arduino support.
|
||
|
||
## Tests
|
||
|
||
```sh
|
||
./scripts/ci.sh # Release + ASan/UBSan + clang builds, all tests
|
||
# or:
|
||
ctest --test-dir build --output-on-failure
|
||
```
|
||
|
||
`tests/ayla` covers the protocol (KDF vectors from the APK, envelope, HTTP,
|
||
session scenarios against a Python mock of the module).
|
||
`tests/aircon` covers template tables and conversions.
|
||
No hardware needed.
|
||
|
||
## pyfglair (Home Assistant)
|
||
|
||
`pyfglair/` — python-пакет (cffi, ABI-режим) поверх того же C-ядра: сессия с
|
||
доставкой событий в asyncio, интроспекция шаблонов и облачный discovery.
|
||
|
||
```sh
|
||
pip install . # wheel: cmake собирает libfgl-aircon.so
|
||
python -m pyfglair discover --region eu --email you@example.com
|
||
python -m pyfglair monitor --config config_home.json --duration 60
|
||
```
|
||
|
||
Тесты (без железа: mock-модуль + мок-облако):
|
||
`scripts/py-ci.sh --setup && scripts/py-ci.sh` (или `pytest tests/pyfglair`).
|
||
|
||
## Home Assistant
|
||
|
||
Компонент `custom_components/fglair/` (HACS custom repository) — climate,
|
||
switch/select/sensor/binary_sensor, config flow с превью шаблона, repair
|
||
для несовпадения ключа и диагностика. Установка: HACS (нужно публичное
|
||
GitHub-зеркало) или ручное копирование `custom_components/fglair/`.
|
||
Инструкция: [`custom_components/fglair/README.md`](custom_components/fglair/README.md);
|
||
приёмка на живом стенде — `tests/acceptance/test_esphome_ha.py`.
|
||
|
||
## Getting the key (`lanip_key`)
|
||
|
||
The key is static (baked into the AC module; only served by the Ayla cloud):
|
||
|
||
```sh
|
||
tools/fglair-discover --region eu --email you@example.com
|
||
# prints one config JSON per device, or a secrets block:
|
||
tools/fglair-discover --region eu --email you@example.com --format esphome-secrets
|
||
```
|
||
|
||
## fglctl
|
||
|
||
```sh
|
||
fglctl config.json status # session check + cached temperature
|
||
fglctl config.json monitor 60 # follow all events for 60 s
|
||
fglctl config.json get OperationMode FanSpeed
|
||
fglctl config.json set AdjustTemperature 220 # 22.0 °C (unit 0.1 °C)
|
||
```
|
||
|
||
Values are in API units: temperatures in 0.1 °C, `DisplayTemperature`
|
||
converted from the module's 0.01 °C+5000 format.
|
||
|
||
## License / provenance
|
||
|
||
Protocol documentation and code reconstructed from the FGLair 3.4.3 APK for
|
||
interoperability; `third_party/jsmn` is MIT.
|