sirmrak/RTKey
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Загрузить файлы в «/»

Browse Source
This commit is contained in:
sirmrak
2026-06-28 13:40:22 +03:00
commit f749579e96
3 changed files with 486 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+396
View File
@@ -0,0 +1,396 @@
# 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>