279 lines
17 KiB
Markdown
279 lines
17 KiB
Markdown
# ТЗ: Дашборд доступности устройств в Home Assistant
|
||
|
||
## Цель
|
||
Дашборд, показывающий **uptime устройств** в процентах за три периода: день, неделю, месяц. С сортировкой по убыванию доступности.
|
||
|
||
## Метрика
|
||
**Доступность** = время в статусе «доступен» / общее время периода × 100%
|
||
|
||
- «Доступен» — любой статус, кроме `unavailable` и `unknown`. **Важно:** статус `off` (выключенное устройство) считается доступным — выключено ≠ недоступно
|
||
- «Недоступен» — статус `unavailable` или `unknown`
|
||
- Результат: процент (0%–100%), один знак после точки
|
||
|
||
## Периоды
|
||
По умолчанию: **7 дней**. В дашборде — переключатель: 24ч / 7д / 30д.
|
||
|
||
| Период | Обновление | Описание |
|
||
|--------|------------|----------|
|
||
| 24ч | каждые 5 мин | Оперативный мониторинг |
|
||
| 7д | каждые 15 мин | Основной режим по умолчанию |
|
||
| 30д | каждые 2 часа | Долгосрочная статистика |
|
||
|
||
Переключение периода пересчитывает все данные на лету из истории. Храним кэш для всех трёх периодов, чтобы переключение было мгновенным.
|
||
|
||
## Какие устройства отслеживать
|
||
Все entity из доменов физических устройств:
|
||
- `binary_sensor`, `sensor`, `switch`, `light`
|
||
- `climate`, `cover`, `lock`, `media_player`
|
||
- `device_tracker`, `vacuum`, `fan`, `humidifier`
|
||
- `water_heater`, `siren`, `button`
|
||
|
||
**Исключения** (не показывать на дашборде):
|
||
- Вспомогательные entity Zigbee2MQTT (`sensor.*_update_state`, `update.*`, `button.zigbee2mqtt_*`)
|
||
- Entity с суффиксами `_battery_low`, `_battery`, `_linkquality`, `_update`, `_identify`
|
||
- Виртуальные/template сенсоры (без device_id)
|
||
- Автоматически создаваемые Select/Number для Zigbee-устройств (настройки radar_sensitivity и т.п.)
|
||
|
||
## Архитектура решения
|
||
|
||
### 1. Вычисление доступности
|
||
**Один Python-скрипт** (AppDaemon или HA Python custom component):
|
||
1. Периодически (по расписанию для каждого периода) запрашивает историю из HA API
|
||
2. Batch-запрос: несколько entity_id через запятую (`filter_entity_id=id1,id2,id3`)
|
||
3. Считает для каждого устройства:
|
||
- Процент доступности за выбранный период
|
||
- Частоту падений (количество переходов в unavailable/unknown)
|
||
- Максимальный непрерывный даунтайм
|
||
- Sparkline данные (7 точек — по одной за день)
|
||
- Сравнение с предыдущим периодом (тренд)
|
||
4. Записывает результаты как sensor-ы: `sensor.avail_<sanitized_id>` с атрибутами
|
||
|
||
### 2. Структура sensor-ов
|
||
Каждый отслеживаемый device → один sensor с атрибутами:
|
||
|
||
```yaml
|
||
sensor.avail_light_bra_v_spalne:
|
||
state: 97.8 # текущий % доступности
|
||
attributes:
|
||
entity_id: light.bra_v_spalne
|
||
friendly_name: "Бра в спальне"
|
||
domain: light
|
||
period: 7d # выбранный период
|
||
availability_pct: 97.8
|
||
down_count: 5
|
||
max_downtime_minutes: 102
|
||
sparkline: [100, 100, 98, 95, 99, 100, 97.8] # 7 точек
|
||
trend: "down" # down/up/stable vs прошлая неделя
|
||
last_downtime: "2026-04-14T15:32:00+03:00"
|
||
color: "green" # green/yellow/orange/red
|
||
```
|
||
|
||
### 3. Варианты реализации
|
||
|
||
#### Вариант A: AppDaemon (рекомендуемый)
|
||
- Отдельный Python-скрипт в AppDaemon
|
||
- Работает по расписанию, batch-обработка
|
||
- Легко читать/обновлять, не зависит от HA Core
|
||
- ✅ **Плюсы:** изоляция, легко отлаживать, минимум нагрузки на HA
|
||
- ⚠️ **Требует:** установка AppDaemon как HA addon
|
||
|
||
#### Вариант B: HA Custom Component
|
||
- Кастомная интеграция, регистрирует dynamic sensor-ы
|
||
- Работает как часть HA, доступ к recorder напрямую
|
||
- ✅ **Плюсы:** нативно, без доп. зависимостей
|
||
- ⚠️ **Минусы:** сложнее разработка, перезагрузка при изменениях
|
||
|
||
#### Вариант C: HA Python Scripts + REST Command
|
||
- Python-скрипт через `python_script` integration
|
||
- Запускается по automation, сохраняет результаты через REST
|
||
- ✅ **Плюсы:** без AppDaemon
|
||
- ❌ **Минусы:** `python_script` ограничен в импортах, сложнее batch
|
||
|
||
### Рекомендация: Вариант A (AppDaemon) ✅ ВЫБРАН
|
||
Оптимальный баланс. Изолированный Python-скрипт, batch-обработка, легко масштабировать.
|
||
|
||
**Установлено:** AppDaemon 4.5.13, HA 2026.4.2, Python 3.12.13
|
||
**Путь конфига:** `/addon_configs/a0d7b954_appdaemon/appdaemon.yaml`
|
||
**Путь приложений:** `/addon_configs/a0d7b954_appdaemon/apps/`
|
||
**Путь apps.yaml:** `/addon_configs/a0d7b954_appdaemon/apps/apps.yaml`
|
||
**Slug аддона:** `a0d7b954_appdaemon`
|
||
**Подключение к HA:** автоматическое через SUPERVISOR_TOKEN (WebSocket), ha_url/token НЕ указывать
|
||
|
||
### Первая фаза: только light + switch
|
||
Начинаем с минимального набора — только домены `light` и `switch`. После обкатки расширяем на остальные.
|
||
|
||
**Устройств после фильтрации:** ~32 (2 light + 30 switch)
|
||
|
||
**Дополнительные исключения для switch (настройки реле — не основные устройства):**
|
||
- `*_delayed_power_on_state`
|
||
- `*_detach_relay_mode`
|
||
- `*_network_indicator`
|
||
- `*_turbo_mode`
|
||
- `*_do_not_disturb`
|
||
- `switch.zigbee2mqtt_bridge_permit_join`
|
||
|
||
После этих исключений — ~18 основных устройств.
|
||
|
||
### Cold-start (первичная загрузка и перезапуск)
|
||
При запуске AppDaemon (или после перезапуска HA) — **полный пересчёт текущего активного периода** для всех устройств. Не ждать следующего расписания — данные должны быть актуальны сразу.
|
||
|
||
**Rate-limit при batch-запросах:** 180 устройств × 30 дней истории — ощутимая нагрузка на HA API. Разбивать на батчи по ~20 entity_id с паузой 1 сек между запросами. Показывать прогресс: `sensor.avail_calc_progress` с состоянием `"47/180"` или `"idle"`.
|
||
|
||
## Дашборд
|
||
|
||
### Группировка по комнатам/зонам
|
||
Устройства группируются по **HA areas** (комнатам). Если у устройства нет area — группа «Без комнаты».
|
||
|
||
- Каждая группа — **сворачиваемая секция** с заголовком: `🛏️ Спальня (12 устройств, 97.2%)`
|
||
- В заголовке: иконка комнаты, средняя доступность по группе, количество устройств
|
||
- По умолчанию: проблемные комнаты (средний % < 95%) раскрыты, остальные свёрнуты
|
||
- Сортировка комнат: сначала проблемные, потом по средней доступности (по убыванию)
|
||
|
||
### Мобильная адаптация
|
||
На экранах < 768px (мобильный вид):
|
||
- **Убрать sparkline** — не помещается
|
||
- **Компактная строка:** иконка + friendly name + цветной процент (крупный)
|
||
- **Прогресс-бар** — тонкий, одна линия (не блок)
|
||
- **Сводка падений** — скрыта, раскрывается по тапу (expandable)
|
||
- **Группы комнат** — свёрнуты по умолчанию, тап раскрывает список
|
||
|
||
Десктопный вид — как описано ниже (полный).
|
||
|
||
### Карточка: список устройств с визуалом (десктоп)
|
||
|
||
**Прогресс-бар + сводка для каждого устройства:**
|
||
```
|
||
💡 Бра в спальне ████████████████████░ 97.8%
|
||
📉 100 100 98 95 99 100 98
|
||
5 падений, макс. даунтайм 1ч 42мин
|
||
```
|
||
|
||
**Строка устройства:**
|
||
- **Friendly name** + иконка домена (💡, 🔌, 🌡️ и т.д.)
|
||
- **Прогресс-бар** — заполненность = доступность (%). Цвет по диапазону:
|
||
- 🟢 `≥99%` — зелёный
|
||
- 🟡 `95-99%` — жёлтый
|
||
- 🟠 `90-95%` — оранжевый
|
||
- 🔴 `<90%` — красный
|
||
- **Процент** — справа от прогресс-бара, крупный шрифт
|
||
- **Sparkline** — мини-график из 7 точек под прогресс-баром, тренд стрелкой (📈/📉/➡️)
|
||
- **Сводка падений** — одна строка: `N падений, макс. даунтайм Xч Yмин`
|
||
- **Время последнего падения** — если <24ч: "X минут/часов назад"
|
||
|
||
**Переключатель периода** — вверху дашборда: [24ч] [7д] [30д]. По умолчанию 7д.
|
||
|
||
### Карточка: сводка
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 📊 Доступность за 7 дней │
|
||
│ │
|
||
│ ██████████████████████░ Средняя: 96.4% │
|
||
│ │
|
||
│ 🔴 Проблемных (<95%): 4 │
|
||
│ 💡 Бра в спальне — 87.2% │
|
||
│ 🔌 Б.колодец насос — 91.3% │
|
||
│ 🌡️ Ванна температура — 82.7% │
|
||
│ 🔒 Замок входной — 94.1% │
|
||
│ │
|
||
│ 📉 Хуже чем прошлую неделю: 3 │
|
||
│ 📈 Лучше чем прошлую неделю: 8 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**Функциональность:**
|
||
- Проблемные (<95%) — отдельная сворачиваемая секция
|
||
- Тренд: сравнение с предыдущим периодом (предыдущие 7 дней)
|
||
- Клик на проблемное устройство — скролл к нему в таблице
|
||
- Цветовая индикация средней доступности (прогресс-бар в сводке)
|
||
- Кнопка "Обновить" — принудительный пересчёт
|
||
|
||
## Технические детали
|
||
|
||
### Путь приложения AppDaemon
|
||
```
|
||
/addon_configs/a0d7b954_appdaemon/apps/
|
||
├── apps.yaml # регистрация приложений
|
||
├── availability.py # основной модуль расчёта доступности
|
||
└── availability_utils.py # вспомогательные функции (фильтрация, форматирование)
|
||
```
|
||
|
||
### Источник данных
|
||
- HA History API: `/api/history/period/<start>?filter_entity_id=<ids>&minimal_response&no_attributes`
|
||
- Возвращает массив пар `(state, last_changed)` — достаточно для расчёта времени
|
||
- AppDaemon подключён к HA через WebSocket — использует `self.get_entity_history()` или REST API через `self.hass`
|
||
|
||
### Расчёт (алгоритм)
|
||
```python
|
||
def calc_availability(history_entries, period_start, period_end):
|
||
unavailable_seconds = 0
|
||
for entry in history_entries:
|
||
state = entry['state']
|
||
changed = parse_datetime(entry['last_changed'])
|
||
|
||
if state in ('unavailable', 'unknown'):
|
||
# Сколько времени устройство было в этом статусе
|
||
# до следующего изменения или до period_end
|
||
next_change = get_next_change(entry) or period_end
|
||
unavailable_seconds += (next_change - changed).total_seconds()
|
||
|
||
total_seconds = (period_end - period_start).total_seconds()
|
||
availability = (1 - unavailable_seconds / total_seconds) * 100
|
||
return round(availability, 1)
|
||
```
|
||
|
||
### Хранение результатов
|
||
- Каждый результат — `sensor.avail_<sanitized_id>` (один sensor, период в атрибуте)
|
||
- Атрибуты: `entity_id`, `period`, `availability_pct`, `area`, `down_count`, `max_downtime_minutes`, `sparkline`, `trend`, `last_downtime`, `color`, `last_updated`
|
||
- Группировка по комнатам: `sensor.avail_area_<sanitized_name>`
|
||
- Прогресс расчёта: `sensor.avail_calc_progress` (`"47/180"` или `"idle"`)
|
||
|
||
### Дашборд: имеющиеся кастомные карточки
|
||
Установлены через HACS:
|
||
- **mini-graph-card** — для sparkline
|
||
- **auto-entities** — автоподхват устройств
|
||
- **card-mod** — кастомный CSS (мобильная адаптация)
|
||
- **stack-in-card** — группировка карточек
|
||
|
||
**Нужно доустановить:**
|
||
- **button-card** — для строк устройств с прогресс-баром
|
||
- **custom:hui-element** — для input_select на дашборде (или использовать стандартный entities card)
|
||
|
||
### AppDaemon: как писать приложение
|
||
|
||
```python
|
||
import appdaemon.plugins.hass.hassapi as hass
|
||
|
||
class Availability(hass.Hass):
|
||
def initialize(self):
|
||
# Cold-start: сразу пересчёт
|
||
self.run_in(self.calc_all, 30) # через 30 сек после старта
|
||
|
||
# Расписания
|
||
self.run_every(self.calc_24h, "now+30", 5 * 60) # каждые 5 мин
|
||
self.run_every(self.calc_7d, "now+60", 15 * 60) # каждые 15 мин
|
||
self.run_every(self.calc_30d, "now+120", 2 * 3600) # каждые 2 часа
|
||
|
||
# Подписка на переключение периода
|
||
self.listen_state(self.period_changed, "input_select.avail_period")
|
||
```
|
||
|
||
### Нагрузка
|
||
- ~180 устройств
|
||
- History API batch-запрос (можно передать несколько entity_id через запятую)
|
||
- За день: ~180 × 3 = 540 точек данных (при batch — 3 API-вызова)
|
||
- За неделю/месяц: данные уже рассчитаны, обновляются реже
|
||
|
||
## Ограничения
|
||
- `purge_keep_days` в recorder — по умолчанию 10 дней. Для месячной статистики нужно **увеличить до 35 дней**
|
||
- Если устройство добавлено недавно — показывать доступность с момента добавления (не с начала периода)
|
||
- Если устройство удалено — перестать показывать на дашборде
|
||
|
||
## Что нужно от Славы
|
||
1. ~~Подтвердить вариант реализации~~ → ✅ AppDaemon (Вариант A)
|
||
2. Увеличить `purge_keep_days` до 35 (иначе не будет данных за месяц)
|
||
3. ~~Установить AppDaemon~~ → ✅ Установлен (4.5.13)
|
||
4. ~~Подтвердить список исключений~~ → ✅ Согласовано (см. выше)
|
||
5. Доустановить **button-card** через HACS
|
||
6. Создать `input_select.avail_period` (опции: 24ч, 7д, 30д)
|