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
151 lines
8.2 KiB
Markdown
151 lines
8.2 KiB
Markdown
# FGLair — интеграция Home Assistant
|
||
|
||
Локальное управление кондиционерами Fujitsu General (FGLair / Ayla LAN)
|
||
без облака в рантайме. Вся протокольная логика — в C++-ядре
|
||
[`fgl-aircon`](../../README.md) через python-пакет `pyfglair` (cffi).
|
||
|
||
> Скриншоты `screenshots/step-N.png` — заглушки-плейсхолдеры: владелец
|
||
> заменит их реальными снимками, описания «что должно быть видно» даны
|
||
> рядом с каждым шагом.
|
||
|
||
## Требования
|
||
|
||
* Home Assistant ≥ 2025.1 (Linux x86_64/aarch64).
|
||
* Пакет `pyfglair` (манифест ставит его автоматически из PyPI).
|
||
До публикации на PyPI установите wheel вручную в python-окружение HA:
|
||
`pip install pyfglair-*.whl` (см. `docs/RELEASE_HA.md`).
|
||
* Модуль кондиционера в той же LAN. Модуль поддерживает **2 LAN-сессии**:
|
||
телефон с FGLair и HA уживаются; третья (например, ESPHome) получит 503.
|
||
|
||
## Установка
|
||
|
||
### Вариант A: HACS (нужно GitHub-зеркало)
|
||
|
||
HACS работает только с публичными репозиториями на **GitHub**; GitLab/Gitea
|
||
(включая текущий хостинг проекта) напрямую не поддерживаются. Зеркалируйте
|
||
репозиторий на GitHub и добавьте зеркало в HACS:
|
||
|
||
1. HACS → ⋮ → **Custom repositories** → URL GitHub-зеркала, категория
|
||
**Integration** → **Add**.
|
||
|
||
|
||
|
||
*Должно быть видно: диалог добавления custom repository с заполненным URL
|
||
и выбранной категорией Integration.*
|
||
|
||
2. Найдите **FGLair** в HACS → **Download** → перезапустите Home Assistant.
|
||
|
||
|
||
|
||
*Должно быть видно: страница загрузки интеграции с кнопкой Download и
|
||
версией.*
|
||
|
||
### Вариант B: вручную (любой хостинг)
|
||
|
||
Скопируйте каталог `custom_components/fglair/` в
|
||
`<config>/custom_components/fglair/` вашего HA и перезапустите Home
|
||
Assistant. Убедитесь, что `pyfglair` установлен в python-окружение HA
|
||
(см. «Требования»).
|
||
|
||
## Добавление устройства
|
||
|
||
3. Settings → Devices & Services → **Add Integration** → «FGLair».
|
||
|
||
|
||
|
||
*Должно быть видно: диалог поиска интеграции с введённым «FGLair» и
|
||
выделенным результатом.*
|
||
|
||
4. **Вход в облако**: e-mail/пароль FGLair и регион. Облако
|
||
используется один раз — получить статический LAN-ключ модуля.
|
||
|
||
|
||
|
||
*Должно быть видно: форма с заполненными регионом EU и e-mail, пароль
|
||
скрыт.*
|
||
|
||
5. **Выбор устройства**: список найденных кондиционеров (имя, модель, IP).
|
||
|
||
|
||
|
||
*Должно быть видно: список с одним устройством (имя, модель, host).*
|
||
|
||
6. **Проверка шаблона с превью**: форма-предпросмотр рассчитанных
|
||
значений (режимы, диапазон температур, пример конверсии) и, при
|
||
необходимости, ручные коэффициенты/диапазон уставки. Сверьте с
|
||
приложением FGLair и подтвердите.
|
||
|
||
|
||
|
||
*Должно быть видно: таблица превью — режимы, диапазон 16–30 °C, шаг,
|
||
текущая температура, capabilities, кнопки Submit.*
|
||
|
||
7. **Готово**: карточка устройства с сущностями climate/switch/select/
|
||
sensor/binary_sensor.
|
||
|
||
|
||
|
||
*Должно быть видно: страница устройства с созданными сущностями.*
|
||
|
||
## Где взять ключ для ESPHome
|
||
|
||
Download diagnostics на странице устройства показывает `dsn`,
|
||
`lanip_key_id`, `host` и **маску** ключа. Полный ключ (для
|
||
`secrets.yaml` ESPHome) получите явным действием:
|
||
|
||
* **Настройка** (шестерёнка → Configure) на карточке интеграции: поле
|
||
«LAN IP key» содержит полный ключ — скопируйте его (там же можно
|
||
заменить ключ без облака); либо
|
||
* **Настроить заново** (Reconfigure) — повторный вход в облако FGLair
|
||
обновит ключ; либо
|
||
* `python -m pyfglair discover --region eu --email you@example.com
|
||
--format esphome-secrets` на хосте HA.
|
||
|
||
|
||
|
||
*Должно быть видно: страница Diagnostics с полями dsn/lanip_key_id/host
|
||
и маской lanip_key.*
|
||
|
||
Альтернатива без облака — ручной ввод параметров (host, dsn, lanip_key,
|
||
lanip_key_id) или импорт `config_*.json` от `fglair-discover`/`fglctl`.
|
||
|
||
## Сущности
|
||
|
||
| Платформа | Что создаётся |
|
||
|---|---|
|
||
| climate | режим (off/cool/dry/fan/heat/auto), скорость, swing (верт./гориз.), preset ECO/BOOST, уставка, текущая температура |
|
||
| switch | economy, powerful, coil dry, min heat, outdoor low noise, human det auto save, Wi-Fi LED, indoor fan control (по шаблону и capabilities) |
|
||
| select | положение вертикальной/горизонтальной заслонки (0…N−1) |
|
||
| sensor | температура в помещении, код ошибки, диагностическое состояние связи |
|
||
| binary_sensor | connectivity + флаги op_status (defrost, maintenance, oil recovery, pump down, check operation, …) |
|
||
|
||
Список зависит от шаблона устройства (A/B/F) и маски `device_capabilities`;
|
||
режимы, которыми прибор не управляет, не создаются.
|
||
|
||
## Диагностика и известные ситуации
|
||
|
||
* **503 / оба слота заняты** — в LAN уже две сессии (телефон + ESPHome).
|
||
Освободите один слот и перезапустите интеграцию.
|
||
* **key_error** — LAN-ключ не совпал (`key_id` изменился). В HA появится
|
||
Repair; нажмите **Настроить заново** и повторите вход в облако (или
|
||
вставьте новый `config_*.json`).
|
||
* **unavailable** — модуль недоступен (сеть/питание) или нет слотов;
|
||
диагностический сенсор «Состояние связи» показывает детали
|
||
(idle/registering/online/recovering/offline/key_error).
|
||
* Записи не эхо-подтверждаются модулем: состояние обновляется
|
||
оптимистично и подтверждается push-обновлением.
|
||
|
||
## Приёмка на живом стенде
|
||
|
||
`tests/acceptance/test_esphome_ha.py` (stdlib) прогоняет матрицу изменений
|
||
через REST API HA по long-lived token, с возвратом к исходному состоянию:
|
||
|
||
```sh
|
||
python tests/acceptance/test_esphome_ha.py quick \
|
||
--ha-url http://homeassistant.local:8123 --ha-token TOKEN \
|
||
--entity climate.ac
|
||
python tests/acceptance/test_esphome_ha.py long \
|
||
--ha-url ... --ha-token ... --entity climate.ac \
|
||
--hours 24 --interval 3600 --report acceptance.csv
|
||
```
|