# RT Key Integration for Home Assistant

[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-Integration-blue)](https://www.home-assistant.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Интеграция для работы с камерами и домофонами **Ростелеком Key** в Home Assistant.

## 📋 Возможности

### 📹 Камеры
- **Live-стрим** с камер в реальном времени
- **Периодические скриншоты** с настраиваемым интервалом
- **Автоматическое обновление токенов** при ошибках доступа
- **Отслеживание доступности** камер (online/offline)

### 🏢 Домофоны
- **Удалённое открытие** двери через кнопку
- **Отслеживание событий**:
  - Открытие по ключу (с определением владельца ключа)
  - Открытие через приложение
  - Открытие по коду/DTMF
- **Скриншоты событий** — фото на момент события
- **Архивное видео** — запись с камеры на момент события

### ️ Настройки
- Гибкая настройка через UI
- Выбор качества скриншотов
- Настраиваемый уровень логирования
- Интервал обновления скриншотов (0 = отключено)

## 📦 Установка

### Вариант 1: Через HACS (рекомендуется)

1. Откройте **HACS** в Home Assistant
2. Перейдите в раздел **Интеграции**
3. Нажмите **⋮** (три точки) → **Пользовательские репозитории**
4. Добавьте URL вашего репозитория
5. Установите интеграцию **RT Key**
6. Перезапустите Home Assistant

### Вариант 2: Вручную

1. Скопируйте папку `rtkey` в директорию `/config/custom_components/`
2. Перезапустите Home Assistant
3. Перейдите в **Настройки** → **Устройства и службы**
4. Нажмите **Добавить интеграцию**
5. Найдите **RT Key**

## 🔑 Получение токена доступа

Для работы интеграции необходим токен доступа к API Ростелеком Key.

### Пошаговая инструкция:

1. **Авторизуйтесь** на портале Ростелеком Key:  
   [https://key.rt.ru/main/pwa/dashboard](https://key.rt.ru/main/pwa/dashboard)

2. **Откройте инструменты разработчика**:
   - Нажмите `F12` (или `Ctrl+Shift+I` / `Cmd+Option+I` на Mac)
   - Перейдите на вкладку **Network** (Сеть)

3. **Отфильтруйте запросы**:  
   В поле фильтра введите:
   - `household.key.rt.ru`
   - или `keyapis.key.rt.ru`

4. **Обновите страницу** (`F5`) — появятся запросы к API

5. **Выберите любой запрос** из списка (например, `intercom` или `camera_video_data/list`)

6. **Скопируйте токен**:
   - Перейдите во вкладку **Headers** (Заголовки)
   - Найдите заголовок `Authorization`
   - Скопируйте значение **после слова `Bearer`** (без пробела)
   
   Пример:
   ```
   Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
                         ↑ скопируйте отсюда
   ```

7. **Вставьте токен** при настройке интеграции в Home Assistant

> ⚠️ **Важно**: Токен чувствителен к регистру! Копируйте полностью, без пробелов и переносов строк.

## ⚙️ Настройка интеграции

После добавления интеграции откройте её настройки:

### Основные параметры

| Параметр | Описание | По умолчанию |
|----------|----------|--------------|
| **Название** | Уникальное имя интеграции | RT Key |
| **Токен** | Токен доступа (см. выше) | — |
| **Интервал скриншотов** | Частота обновления (сек), 0 = отключено | 60 сек |
| **Качество скриншотов** | Маленькое / Среднее / Большое / Точное | Среднее |
| **Уровень логов** | DEBUG / INFO / WARNING / ERROR | INFO |

### Настройки событий

| Параметр | Описание | По умолчанию |
|----------|----------|--------------|
| **Отслеживание событий** | Включить мониторинг событий | ✅ Вкл |
| **Интервал опроса** | Частота проверки событий | 15 сек |
| **Задержка времени камеры** | Лаг синхронизации (сек) | 25 сек |
| **Секунд до события** | Показывать видео до события | 10 сек |
| **Скриншот события** | Создавать сущность скриншота | ✅ Вкл |
| **Архив события** | Создавать камеру архива | ✅ Вкл |
| **Сенсор события** | Создавать сенсор последнего события | ✅ Вкл |

##  Сущности

После настройки интеграция создаст следующие сущности:

### Для каждой камеры

| Сущность | Тип | Описание |
|----------|-----|----------|
| `{name}` | Camera | Live-стрим с камеры |
| `Скриншот {name}` | Image | Периодический скриншот |

### Для каждого домофона

| Сущность | Тип | Описание |
|----------|-----|----------|
| `Открыть {name}` | Button | Кнопка открытия двери |
| `Последнее событие {name}` | Sensor | Информация о последнем событии |
| `Скриншот события {name}` | Image | Скриншот на момент события (диагностика) |
| `Архив события {name}` | Camera | Архивное видео события (диагностика) |

> 💡 **Совет**: Сущности из раздела "Диагностика" можно переместить на основную панель через настройки устройства.

## 🎯 Использование

### Просмотр камер

1. Откройте **Панель управления** → **Обзор**
2. Добавьте карточку **Camera** или **Picture Entity**
3. Выберите нужную камеру

### Открытие домофона

1. Найдите сущность `button.{name}_open`
2. Нажмите на кнопку в интерфейсе
3. Или используйте в автоматизациях:
   ```yaml
   service: button.press
   target:
     entity_id: button.my_intercom_open
   ```

### Автоматизации

Примеры использования в автоматизациях:

#### Уведомление при открытии двери ключом

```yaml
automation:
  - alias: "Уведомление об открытии двери"
    trigger:
      platform: state
      entity_id: sensor.my_intercom_last_event
    condition:
      condition: template
      value_template: "{{ 'Ключ' in trigger.to_state.state }}"
    action:
      - service: notify.mobile_app
        data:
          message: "Дверь открыл: {{ trigger.to_state.state }}"
          title: "🚪 Домофон"
```

#### Включение света при открытии двери вечером

```yaml
automation:
  - alias: "Свет при открытии двери"
    trigger:
      platform: state
      entity_id: sensor.my_intercom_last_event
    condition:
      - condition: sun
        after: sunset
      - condition: template
        value_template: "{{ 'Ключ' in trigger.to_state.state }}"
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway
```

#### Отправка скриншота события в Telegram

```yaml
automation:
  - alias: "Скриншот события в Telegram"
    trigger:
      platform: state
      entity_id: sensor.my_intercom_last_event
    action:
      - service: telegram_bot.send_photo
        data:
          url: >-
            {{ state_attr('image.my_intercom_event_screenshot', 'entity_picture') }}
          caption: "Событие: {{ trigger.to_state.state }}"
```

## 🔧 Диагностика

### Проверка доступности камер

Если камера отображается как **недоступна** (серая в интерфейсе):

1. **Проверьте атрибуты сущности**:
   ```yaml
   Статус:  Нет связи
   ```

2. **Посмотрите логи Home Assistant**:
   ```
    Камера "Название камеры" (xxx-xxx-xxx) недоступна (404), помечаем как offline
   ```

3. **Камера автоматически восстановится** при появлении связи:
   ```
   ✅ Камера "Название камеры" (xxx-xxx-xxx) снова доступна
   ```

### Обновление токенов

При получении ошибки **403 Forbidden** интеграция автоматически:
1. Обнаруживает протухший токен
2. Запрашивает новые токены из API
3. Повторяет неудачный запрос

**Пример в логах:**
```
⚠️ Токен для Камера 1 (xxx-xxx) протух (403), запускаем обновление...
 Принудительное обновление токенов...
✅ Токены обновлены для N устройств
```

### Уровень логирования

Измените уровень в настройках интеграции для более детальной отладки:

| Уровень | Когда использовать |
|---------|-------------------|
| **DEBUG** | При проблемах с интеграцией — подробная информация о всех запросах |
| **INFO** | Повседневное использование (рекомендуется) |
| **WARNING** | Только предупреждения и ошибки |
| **ERROR** | Только критические ошибки |

### Просмотр событий в реальном времени

Для отладки отслеживания событий установите уровень **DEBUG** и ищите в логах:

```
 Запущен цикл опроса событий (интервал 15.0с)
✅ Загружено N домофонов: ['intercom_id_1', 'intercom_id_2']
🔔 Новое событие для домофона intercom_id_1: Ключ {имя} в 2026-01-01 12:00:00
✅ Скриншот события получен xxxxxxxx-... (NNNNN байт)
```

## 🐛 Решение проблем

### ❌ Интеграция не добавляется

**Симптом**: Ошибка "Invalid token" или "Authentication failed"

**Решение**:
1. ✅ Убедитесь, что токен скопирован **полностью** (начинается с `eyJ...`)
2. ✅ Проверьте, что в токене **нет пробелов и переносов строк**
3. ✅ Убедитесь, что вы скопировали токен **без слова `Bearer`**
4. ✅ Попробуйте получить новый токен (старый мог истечь)

### ❌ Камеры не показывают видео

**Симптом**: Чёрный экран или ошибка загрузки

**Решение**:
1. Проверьте статус камеры в атрибутах (`❌ Нет связи`)
2. Убедитесь, что камера работает в **приложении Ростелеком Key**
3. Перезагрузите интеграцию
4. Проверьте логи на наличие ошибок `403` или `404`

### ❌ Скриншоты не обновляются

**Симптом**: Изображение не меняется в карточке

**Решение**:
1. Проверьте **интервал обновления** в настройках (не установлен ли `0`)
2. Увеличьте интервал (минимум 30 сек)
3. Проверьте логи на наличие ошибок

### ❌ События не отслеживаются

**Симптом**: Сенсор событий показывает "Нет событий"

**Решение**:
1. Убедитесь, что в настройках включено **"Отслеживание событий"**
2. Проверьте **интервал опроса** (рекомендуется 15 сек)
3. Посмотрите логи — должны быть сообщения `🔔 Новое событие для домофона...`
4. Проверьте, что домофон в списке: `✅ Загружено N домофонов: [...]`

### ❌ Неправильное время событий

**Симптом**: Время события не совпадает с реальным

**Решение**:
1. Убедитесь, что в Home Assistant правильно настроен **часовой пояс**  
   (**Настройки** → **Система** → **Общее** → **Часовой пояс**)
2. Проверьте параметр **"Задержка времени камеры"** в настройках  
   (по умолчанию 25 сек — может отличаться для разных камер)

## 📊 Структура проекта

```
custom_components/rtkey/
├── __init__.py              # Основной модуль, API клиент
├── button.py                # Кнопки открытия домофона
├── camera.py                # Live-камеры и архив событий
── config_flow.py           # Настройка через UI
├── image.py                 # Скриншоты камер и событий
├── sensor.py                # Сенсоры событий
├── manifest.json            # Метаданные интеграции
├── translations/
│   ├── en.json              # Английские переводы
│   └── ru.json              # Русские переводы
└── README.md                # Документация
```

### Ключевые API endpoints

| Endpoint | Назначение |
|----------|-----------|
| `keyapis.key.rt.ru/vc/api/v1/camera_video_data/list` | Список всех камер и домофонов |
| `household.key.rt.ru/api/v2/app/devices/intercom` | Информация о домофонах |
| `household.key.rt.ru/api/v2/app/devices/{id}/open` | Открытие домофона |
| `events.key.rt.ru/api/v2/events/list` | События (открытие, звонки) |
| `key.rt.ru/screenshot/image/...` | Скриншоты камер |
| `live-vdk4.camera.rt.ru/stream/...` | Live-стрим и архивное видео |

## 🔐 Безопасность

- ✅ **Токен хранится** в зашифрованном хранилище Home Assistant
- ⚠️ **Не передавайте** токен третьим лицам
- 🔄 **Регулярно обновляйте** токен (рекомендуется раз в 3-6 месяцев)
- 👤 Используйте **отдельный аккаунт** для интеграции, если возможно
- 🚫 **Не публикуйте** токен в публичных репозиториях или логах

## 📝 Changelog

### Версия 1.0.0 (2026)
- ✅ Добавлена поддержка камер и домофонов
- ✅ Автоматическое обновление токенов при 403
- ✅ Отслеживание доступности камер (404)
- ✅ События с маппингом ключей
- ✅ Скриншоты и архивное видео событий
- ✅ Гибкие настройки через UI (слайдеры, dropdown)
- ✅ Настраиваемый уровень логирования
- ✅ Переводы на русский и английский
- ✅ Корректная конвертация UTC → локальное время HA

## 🤝 Вклад в развитие

Приветствуются:
- 🐛 Bug reports (с логами и описанием)
- 💡 Feature requests
- 🔧 Pull requests
- 📚 Улучшение документации
- 🌍 Новые языковые переводы

## 📄 Лицензия

MIT License — используйте на свой страх и риск.

## 🙏 Благодарности

- **Ростелеком** за API домофонов
- **Сообществу Home Assistant** за отличную платформу
- **Всем тестировщикам** за помощь в отладке и обратную связь

---

<div align="center">

**Разработано с ❤️ для Home Assistant**

[ Наверх](#rt-key-integration-for-home-assistant)

</div>