157 lines
9.7 KiB
Markdown
157 lines
9.7 KiB
Markdown
# ТЗ: Дашборд доступности устройств в Home Assistant
|
||
|
||
## Цель
|
||
Дашборд, показывающий **uptime устройств** в процентах за три периода: день, неделю, месяц. С сортировкой по убыванию доступности.
|
||
|
||
## Метрика
|
||
**Доступность** = время в статусе «доступен» / общее время периода × 100%
|
||
|
||
- «Доступен» — любой статус, кроме `unavailable` и `unknown`
|
||
- «Недоступен» — статус `unavailable` или `unknown`
|
||
- Результат: процент (0%–100%), один знак после точки
|
||
|
||
## Периоды
|
||
| Период | Формула | Обновление |
|
||
|--------|---------|------------|
|
||
| День | за последние 24 часа | каждые 5 мин |
|
||
| Неделя | за последние 7 дней | каждые 30 мин |
|
||
| Месяц | за последние 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. Вычисление доступности — через长期的 sensor
|
||
Для каждого отслеживаемого устройства создать **template sensor** (или один Python-скрипт через REST), который:
|
||
1. Запрашивает историю из `/api/history/period/<start>?filter_entity_id=<id>&minimal_response&no_attributes`
|
||
2. Считает суммарное время в `unavailable`/`unknown`
|
||
3. Вычисляет процент доступности
|
||
4. Записывает результат как sensor state
|
||
|
||
### 2. Варианты реализации
|
||
|
||
#### Вариант A: Utility Meter + Template Sensor (нативный HA)
|
||
- На каждое устройство — `binary_sensor` доступности (доступен/нет)
|
||
- `utility_meter` считает время в каждом статусе
|
||
- Template sensor вычисляет процент
|
||
- ❌ **Минус:** нужен `custom:utility_meter` или `history_stats` — много entity на каждое устройство, сложная конфигурация при 180+ устройствах
|
||
|
||
#### Вариант B: Python-скрипт + AppDaemon (рекомендуемый)
|
||
- Один Python-скрипт, работающий по расписанию
|
||
- Читает историю через HA API для всех устройств сразу
|
||
- Вычисляет доступность за все 3 периода
|
||
- Создаёт/обновляет `sensor.availability_<entity_id>_<period>` через `states` API
|
||
- ✅ **Плюсы:** один скрипт, легко масштабировать, минимальная нагрузка на HA
|
||
- ⚠️ **Требует:** AppDaemon или HA Python script / custom component
|
||
|
||
#### Вариант C: Custom HA Integration (HACS)
|
||
- Кастомная интеграция, регистрирует sensor-ы через `async_setup_platform`
|
||
- Берёт данные из recorder напрямую (SQL)
|
||
- ✅ **Плюсы:** максимально нативно, работает через recorder без API
|
||
- ⚠️ **Минусы:** сложнее разработка, нужен доступ к БД recorder
|
||
|
||
#### Вариант D: SQL Sensor + Jinja (самый простой)
|
||
- `sql` integration — прямые запросы к MariaDB/SQLite recorder
|
||
- Один sensor на устройство×период с SQL-запросом
|
||
- ✅ **Плюсы:** без внешних зависимостей, работает из коробки
|
||
- ❌ **Минусы:** 180 устройств × 3 периода = 540 SQL-запросов по расписанию — нагрузка на БД
|
||
|
||
### Рекомендация: Вариант B (AppDaemon / Python-скрипт)
|
||
Оптимальный баланс сложности и производительности. Один скрипт, batch-обработка, минимальная нагрузка.
|
||
|
||
## Дашборд
|
||
|
||
### Карточка: таблица доступности
|
||
```
|
||
┌──────────────────────────┬────────┬────────┬────────┐
|
||
│ Устройство │ День │ Неделя │ Месяц │
|
||
├──────────────────────────┼────────┼────────┼────────┤
|
||
│ 💡 Бра в спальне │ 99.8% │ 98.5% │ 95.2% │
|
||
│ 🔌 Лесной колодец насос │ 100.0% │ 99.1% │ 97.8% │
|
||
│ 🌡️ Улица температура │ 85.3% │ 92.1% │ 88.7% │
|
||
│ ... │ ... │ ... │ ... │
|
||
└──────────────────────────┴────────┴────────┴────────┘
|
||
```
|
||
|
||
**Функциональность:**
|
||
- Сортировка по любому столбцу (по умолчанию — по месячной доступности, убывание)
|
||
- Цветовая индикация:
|
||
- 🟢 99-100% — зелёный
|
||
- 🟡 95-99% — жёлтый
|
||
- 🟠 90-95% — оранжевый
|
||
- 🔴 <90% — красный
|
||
- Фильтр по домену (switch, sensor, light...)
|
||
- Обновление: при загрузке дашборда + по расписанию
|
||
|
||
### Карточка: сводка
|
||
```
|
||
┌──────────────────────────────────┐
|
||
│ 📊 Доступность устройств │
|
||
│ │
|
||
│ Средняя за день: 97.3% │
|
||
│ Средняя за неделю: 96.1% │
|
||
│ Средняя за месяц: 94.8% │
|
||
│ │
|
||
│ Устройств <95% (месяц): 5 │
|
||
│ Устройств <90% (месяц): 2 │
|
||
└──────────────────────────────────┘
|
||
```
|
||
|
||
## Технические детали
|
||
|
||
### Источник данных
|
||
- HA History API: `/api/history/period/<start>?filter_entity_id=<ids>&minimal_response&no_attributes`
|
||
- Возвращает массив пар `(state, last_changed)` — достаточно для расчёта времени
|
||
|
||
### Расчёт (алгоритм)
|
||
```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>_<period>`
|
||
- Атрибуты: `entity_id`, `period`, `availability_%`, `last_updated`
|
||
- Группировка: `group.availability_day`, `group.availability_week`, `group.availability_month`
|
||
|
||
### Нагрузка
|
||
- ~180 устройств
|
||
- History API batch-запрос (можно передать несколько entity_id через запятую)
|
||
- За день: ~180 × 3 = 540 точек данных (при batch — 3 API-вызова)
|
||
- За неделю/месяц: данные уже рассчитаны, обновляются реже
|
||
|
||
## Ограничения
|
||
- `purge_keep_days` в recorder — по умолчанию 10 дней. Для месячной статистики нужно **увеличить до 35 дней**
|
||
- Если устройство добавлено недавно — показывать доступность с момента добавления (не с начала периода)
|
||
- Если устройство удалено — перестать показывать на дашборде
|
||
|
||
## Что нужно от Славы
|
||
1. Подтвердить вариант реализации (рекомендую B — AppDaemon/Python)
|
||
2. Увеличить `purge_keep_days` до 35 (иначе не будет данных за месяц)
|
||
3. Установить AppDaemon (если выбран вариант B) — или подтвердить другой вариант
|
||
4. Подтвердить список исключений (какие entity не отслеживать)
|