petr.polezhaev
8013781e09
- custom_components/fglair/README.md: HACS-установка, cloud/ручной/импорт, превью шаблона, сущности, ключ для ESPHome (reconfigure/CLI), диагностика и troubleshoot; заглушки screenshots/step-1..8.png (сгенерированы) - tests/acceptance/test_esphome_ha.py: quick/burst/long через REST API HA (long-lived token), адаптивная матрица по capabilities, возврат исходного состояния, CSV-отчёт long, опциональный ESPHome-канал (aioesphomeapi) - self-test приёмки на моке HA REST (6 тестов, без железа) - hacs.json; README: раздел Home Assistant; docs/RELEASE_HA.md: публикация pyfglair на PyPI (wheel/sdist, auditwheel), HACS-релиз, приёмка - scripts/py-ci.sh: tests/acceptance; план H5 отмечен
135 lines
7.3 KiB
Markdown
135 lines
7.3 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.
|
||
|
||
## Установка через HACS
|
||
|
||
1. HACS → ⋮ → **Custom repositories** → URL репозитория, категория
|
||
**Integration** → **Add**.
|
||
|
||
|
||
|
||
*Должно быть видно: диалог добавления custom repository с заполненным URL
|
||
и выбранной категорией Integration.*
|
||
|
||
2. Найдите **FGLair** в HACS → **Download** → перезапустите Home Assistant.
|
||
|
||
|
||
|
||
*Должно быть видно: страница загрузки интеграции с кнопкой Download и
|
||
версией.*
|
||
|
||
## Добавление устройства
|
||
|
||
3. Settings → Devices & Services → **Add Integration** → «FGLair».
|
||
|
||
|
||
|
||
*Должно быть видно: диалог поиска интеграции с введённым «FGLair» и
|
||
выделенным результатом.*
|
||
|
||
4. **Вход в облако** (шаг 1A): e-mail/пароль FGLair и регион. Облако
|
||
используется один раз — получить статический LAN-ключ модуля.
|
||
|
||
|
||
|
||
*Должно быть видно: форма с заполненными регионом EU и e-mail, пароль
|
||
скрыт.*
|
||
|
||
5. **Выбор устройства**: список найденных кондиционеров (имя, модель, IP).
|
||
|
||
|
||
|
||
*Должно быть видно: список с одним устройством (имя, модель, host).*
|
||
|
||
6. **Проверка шаблона с превью** (шаг 3): форма-предпросмотр рассчитанных
|
||
значений (режимы, диапазон температур, пример конверсии) и, при
|
||
необходимости, ручные коэффициенты/диапазон уставки. Сверьте с
|
||
приложением FGLair и подтвердите.
|
||
|
||
|
||
|
||
*Должно быть видно: таблица превью — режимы, диапазон 16–30 °C, шаг,
|
||
текущая температура, capabilities, кнопки Submit.*
|
||
|
||
7. **Готово**: карточка устройства с сущностями climate/switch/select/
|
||
sensor/binary_sensor.
|
||
|
||
|
||
|
||
*Должно быть видно: страница устройства с созданными сущностями.*
|
||
|
||
## Где взять ключ для ESPHome
|
||
|
||
Download diagnostics на странице устройства показывает `dsn`,
|
||
`lanip_key_id`, `host` и **маску** ключа. Полный ключ (для
|
||
`secrets.yaml` ESPHome) получите явным действием:
|
||
|
||
* **Настроить заново** (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
|
||
```
|