RT Key Integration for Home Assistant

Интеграция для работы с камерами и домофонами Ростелеком 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

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. Или используйте в автоматизациях:

   service: button.press
   target:
     entity_id: button.podezd_no1_open
   

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

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

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

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

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

automation:
  - alias: "Свет при открытии двери"
    trigger:
      platform: state
      entity_id: sensor.podezd_no1_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.prikhozhaya

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

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

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

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

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

1. Проверьте атрибуты сущности:

   Статус: ❌ Нет связи
   

2. Посмотрите логи Home Assistant:

   📷 Камера "Лифт 1" (xxx-xxx-xxx) недоступна (404), помечаем как offline
   

3. Камера автоматически восстановится при появлении связи:

   ✅ Камера "Лифт 1" (xxx-xxx-xxx) снова доступна
   

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

При получении ошибки 403 Forbidden интеграция автоматически:

1. Обнаруживает протухший токен
2. Запрашивает новые токены из API
3. Повторяет неудачный запрос

Пример в логах:

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

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

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

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

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

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

🔄 Запущен цикл опроса событий (интервал 15.0с)
✅ Загружено 2 домофонов: ['39810', '39809']
🔔 Новое событие для домофона 35810: Ключ Вася в 2026-06-26 18:58:19
✅ Скриншот события получен 9dc4eff5-... (61588 байт)

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

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

Симптом: Ошибка "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 за отличную платформу
• Всем тестировщикам за помощь в отладке и обратную связь

---

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

⬆ Наверх

```