Pandora Car Alarm System для Home Assistant

Автоматизация управления охранными системами Pandora™ и PanDECT^® в Home Assistant.

>= Home Assistant 2021.12.0

Техническая поддержка

Вдохновитель, оригинальный разработчик

Автомобиль тоже может быть частью умного дома. С помощью этого компонента вы сможете отслеживать состояние, управлять и автоматизировать свой автомобиль, если он оборудован охранной системой Pandora. После настройки ваши устройства Pandora™ и PanDECT^® автоматически добавятся в Home Assistant.

Компонент реализует доступ к API официального приложения Pandora, Pandora Connect, и реализует часть его функционала. Для настройки Вам следует использовать те же авторизационные данные, что вы используете на сайте Pandora (pro.p-on.ru), или в мобильном приложении Pandora Online / Connect / Pro.

На данный момент компонент поддерживает:

• Device Tracker: Местоположение автомобиля.
• Sensors: Температура, скорость, тахометр и т.д.
• Binary Sensors: Статусы открытия, движения, и т.д.
• Switches: Работа двигателя, активная охрана, и т.д.
• Lock: Постановка на охрану
• Services: Команды, например: открыть/закрыть, завести/заглушить и др.

Компонент успешно протестирован и отработан на системах:

• PanDECT X-1900 BT
• Pandora DXL-5570
• PanDECT X-1700 BT
• Pandora DX-9X LoRa + NAV-10
• Pandora DX-4G
• Pandora DX-90BT + NAV-10
• Сообщите о Вашем успехе!

Панель со всеми поддерживаемыми элементами

Раздел управления

Подготовка собственной конфигурации

Конфигурация существует трёх видов:

• Карточка (содержит только графическое изображение транспортного средства)
• Стек (карточка + элементы управления + сенсоры)
• Панель (карта по левую сторону, стек по правую)

Чтобы подготовить собственную конфигурацию, выполните следующие действия:

1. Открыть папку с подготовленными конфигурациями
2. Выбрать файл с желаемым типом конфигурации
3. Скопировать содержимое файла в текстовый редактор
4. Заменить все вхождения REPLACE_WITH_PANDORA_ID на идентификатор автомобиля (device_id на сенсорах)

Установка

Посредством HACS (рекомендованый способ)

1. Установить HACS
2. Установить компонент Pandora Car Alarm System
3. Выполнить конфигурацию одним из нижеупомянутых способов
4. (опционально, для YAML) Перезапустить Home Assistant

Ручная установка

1. Скачать репозиторий:
   1. Посредством Git:
      git clone https://github.com/alryaz/hass-pandora-cas.git hass-pandora-cas
   2. Через браузер: ссылка
      Разархивировать папку hass-pandora-cas-master внутри архива в любую папку
2. Перенести содержимое подпапки custom_components в аналогичную папку конфигурации Home Assistant (при отсутствии папки custom_components в конфигурации, создать таковую)
3. Выполнить конфигурацию одним из нижеупомянутых способов
4. (опционально, для YAML) Перезапустить Home Assistant

Настройка

Через интерфейс "Интеграции"

Поддерживается базовый функционал конфигурации через веб-интерфейс Home Assistant. Конфигурация данным способов возможна без перезагрузки Home Assistant.

Вручную (если кнопка выше не работает)

Для перехода к настройке, выполните следующие действия:

1. Перейдите в раздел Настройки ⟶ Интеграции (`/config/integrations`)
2. Нажмите на круглую кнопку с плюсом внутри в нижнем правом углу экрана
3. Во всплывшем окне, введите в верхнем поле поиска: Pandora; одним из результатов должен оказаться Pandora Car Alarm System (с соответствующим логотипом торговой марки Pandora Car Alarm System)
4. Нажмите на предложенный результат
5. Введите имя пользователя и пароль в соответствующие поля
6. Нажмите внизу справа на кнопку Подтвердить. В случае обнаружения системой каких-либо ошибок, они будут отображены в окошке
7. Обновление займёт не более 5-10 секунд (проверено на Raspberry Pi 4), элементы в конфигурации по-умолчанию должны появиться на главном экране (при использовании конфигурациии Lovelace по-умолчанию)

Базовая конфигурация

Чтобы активировать компонент, добавьте эти строки в файл configuration.yaml:

# Фрагмент файла configuration.yaml
pandora_cas:
  # Учётная запись на портале p-on.ru / pro.p-on.ru
  password: !secret YOUR_PASSWORD  # обязательно
  username: !secret YOUR_USERNAME  # обязательно

Использование нескольких учётных записей

Компонент поддерживает работу с несколькими учётными записями.

Внимание! При добавлении двух учётных записей с одинковыми именами пользователя будет использована первая разобранная системой конфигурация.

pandora_cas:
    # Первая учётная запись
  - username: !secret YOUR_USERNAME_1  # обязательно
    password: !secret YOUR_PASSWORD_1  # обязательно
    
    # Вторая учётная запись
  - username: !secret YOUR_USERNAME_2  # обязательно
    password: !secret YOUR_PASSWORD_2  # обязательно

Установка дополнительных параметров

pandora_cas:
  username: !secret YOUR_USERNAME  # обязательно
  password: !secret YOUR_PASSWORD  # обязательно
  
  # Произвольный формат названий объектов
  # Данная настройка позволяет задать шаблон названий объектов "из коробки"
  # Не распространяется на платформу `device_tracker`
  # Поддерживаются следующие переменные:
  #   - `device_id`: Идентификатор охранной системы
  #   - `device_name`: Имя охранной системы, данное пользователем в Pandora Online
  #   - `type_name`: Название типа объекта ('Engine', 'Active Protection', и т.д.)
  #   - `type`: Внутренний идентификатор типа объекта (`engine`, `moving`, и т.д.)
  #
  name_format: '{device_name} {type_name}'
  ...

Дополнительная конфигурация подключения платформ:

Следующие примеры отражают возможные способы предварительной конфигурации добавляемых в Home Assistant объектов. Ознакомиться со списком добавляемых объектов по-умолчанию (при первом запуске/добавлении конфигурации) Вы можете в следующем разделе инструкции. Возможность предварительной конфигурации реализована для сохранения портативности конфигурации при переносе её на другие платформы.

  ...
  # В данном примере платформа `sensor` будет добавлена со всеми объектами:
  #
  sensor: True

  # В данном примере платформа `device_tracker` не будет добавлена:
  #
  device_tracker: False

  # В данном примере, для всех устройств в аккаунте будут включены только указанные
  # объекты платформы `binary_sensor`:
  #
  binary_sensor: ['moving', 'left_front_door']

  # В данном примере, устройства:
  # - '00000001' будет обладать переключателями `engine`, `tracking` и `coolant_heater`
  # - '00000002' будет обладать всеми переключателями
  # - '00000003' не будет иметь переключателей
  # - '00000004' (не указано ниже) будет обладать переключателями `active_security` и `engine`,
  #   так как данные переключатели установлены параметром `default` для устройств, не имеющих
  #   конкретизированную конфигурацию платформы
  #
  switch:
    default: ['active_security', 'engine']
    '00000001': ['engine', 'tracking', 'coolant_heater']
    '00000002': True
    '00000003': False

N.B. Настоятельно рекомендуется оборачивать идентификаторы устройств в кавычки во избежание конвертации идентификаторов как числа, в некоторых случаях не соответствующие действительным идентификаторам.

N.B. Для платформы device_tracker отсутствует возможность конкретизации объектов в силу существования единственного объекта; допускается включение/отключение платформы для конкретных устройств одним из способов, указанных выше.

Управление объектами через интерфейс

Дополнительно имеется возможость (для всех вариантов конфигурации) использовать раздел устройств для управления включёнными объектами. Для этого:

1. Перейдите в раздел Настройки ⟶ Устройства (/config/devices/dashboard)
2. Найдите Ваше устройство (в колонке Интеграция будет написано Pandora Car Alarm System)
3. Нажмите на найденную строку с устройством
4. Прокрутите страницу вниз до обнаружения надписи +[N] скрытых объектов
5. Нажмите на данную надпись
6. Нажмите на любой из появившихся объектов
7. Во всплывающем окне, переместите переключатель Отображать объект в положение Вкл.
8. Нажмите на кнопку Обновить в нижнем правом углу всплывающего окна

Пример того, как выглядит наполненная страница для устройства модели X-1911BT (нажмите для увеличения):

Датчики / Переключатели / Состояния

Для привязки к автомобилю в имени объекта сенсоров используется идентификатор PANDORA_ID, в то время как в человеко-читаемом названии используется название автомобиля с сайта Pandora. Это сделано для того, чтобы при изменении названия автомобиля на сайте не менялись имена объектов, а значит не будет необходимости перенастраивать lovelace UI и автоматизации.

ВНИМАНИЕ!
При добавлении объектов, компонент в отдельных случаях проверяет поддержку функционала конечным устройством. Во избежание неожиданных ситуаций, Вы можете ознакомиться с таблицами поддержки на официальном сайте Pandora: ссылка на документ.

ПРЕДУПРЕЖДЕНИЕ!
Общее количество различных объектов, доступных в компоненте, в скором времени перевалит за 40. Ввиду этого, по умолчанию отключены объекты, встречающиеся наиболее редко, такие как:

• Состояние зарядки и температура аккумулятора гибридных/электрических автомобилей
• Состояние поднятости стёкол и давление в шинах (TPMS), получаемые по CAN-шине

Такие объекты помечаются символом "⚠" в таблицах ниже. Если Вы уверены, что Ваш автомобиль вкупе с установленной на нём системой поддерживают данные функции, то Вы можете включить перечисленные объекты следуя инструкции выше.

Платформа sensor

Объект	Назначение	Примечание
sensor.PANDORA_ID_mileage	Пробег (по GPS устройства сигнализации)	км
sensor.PANDORA_ID_can_mileage	Пробег (штатный одометр, по шине CAN)	км
sensor.PANDORA_ID_fuel	Наполненность топливом 1	%
sensor.PANDORA_ID_interior_temperature	Температура салона	°C
sensor.PANDORA_ID_engine_temperature	Температура двигателя	°C
sensor.PANDORA_ID_exterior_temperature	Уличная температура	°C
sensor.PANDORA_ID_balance	Баланс СИМ-карты	Валюта SIM-карты
sensor.PANDORA_ID_speed	Скорость	км/ч
sensor.PANDORA_ID_tachometer	Тахометр (обороты двигателя)	rpm
sensor.PANDORA_ID_gsm_level	Уровень сигнала GSM	0 ... 3
sensor.PANDORA_ID_battery_voltage	Напряжение аккумулятора	В
⚠ sensor.PANDORA_ID_left_front_tire_pressure	Давление левой передней шины	кПа (?)
⚠ sensor.PANDORA_ID_right_front_tire_pressure	Давление правой передней шины	кПа (?)
⚠ sensor.PANDORA_ID_left_back_tire_pressure	Давление левой задней шины	кПа (?)
⚠ sensor.PANDORA_ID_right_back_tire_pressure	Давление правой задней шины	кПа (?)
⚠ sensor.PANDORA_ID_battery_temperature	Температура аккумулятора	°C

Дополнительно возможно адаптировать показания тахометра:

pandora_cas:
  ...
  rpm_coefficient: 1.5  # Умножит показание тахометра на два; коэффициент по умолчанию: 1.0
  rpm_offset: 100  # Увеличит показание тахометра на 100 об/м; сдвиг по умолчанию: 0.0

Также это возможно выполнить под каждое устройство:

pandora_cas:
  ...
  rpm_coefficient:
    '123412241': 1.5
    '124551222': 25.0
    '222212412': 0.333

Платформа binary_sensor

Объект	Назначение	Примечание
binary_sensor.PANDORA_ID_connection_state	Связь с автомобилем1	есть / нет
binary_sensor.PANDORA_ID_moving	Статус движения	в движении / без движения
binary_sensor.PANDORA_ID_left_front_door	Левая передняя дверь	открыта / закрыта
binary_sensor.PANDORA_ID_right_front_door	Правая передняя дверь	открыта / закрыта
binary_sensor.PANDORA_ID_left_back_door	Левая задняя дверь	открыта / закрыта
binary_sensor.PANDORA_ID_right_back_door	Правая задняя дверь	открыта / закрыта
binary_sensor.PANDORA_ID_trunk	Багажник	открыт / закрыт
binary_sensor.PANDORA_ID_hood	Капот	открыт / закрыт
binary_sensor.PANDORA_ID_parking	Режим паркнинга	включен / выключен
binary_sensor.PANDORA_ID_brakes	Педаль тормоза	нажата / отпущена
⚠ binary_sensor.PANDORA_ID_left_front_glass	Левое переднее окно (водительское)2	открыто / закрыто
⚠ binary_sensor.PANDORA_ID_right_front_glass	Правое переднее окно (пассажирское)2	открыто / закрыто
⚠ binary_sensor.PANDORA_ID_left_back_glass	Левое заднее окно	открыто / закрыто
⚠ binary_sensor.PANDORA_ID_right_back_glass	Правое заднее окно	открыто / закрыто
⚠ binary_sensor.PANDORA_ID_ev_charging_connected	Зарядка аккумулятора электрокара	подключено / отключено

¹ Данный объект содержит полный перечень свойств, получаемых в момент обновления состояния автомобиля, и тем самым может быть запросто использован для template-выражений.
² Компонент не тестировался для праворульных транспортных средств. Может возникнуть ситуация, что из коробки данные сенсоры перепутаны местами.

Платформы lock и switch

Внимание! Через 10с после изменения состояния переключателя производится принудительное автоматическое обновление состояния автомобиля. Данный функционал вскоре будет возможно отключить вручную.

Объект	Назначение	Примечание
lock.PANDORA_ID_central_lock	Статус блокировки замка	разблокирован / заблокирован
switch.PANDORA_ID_active_security	Статус активной защиты	включена / выключена
switch.PANDORA_ID_coolant_heater	Статус предпускового подогревателя	включен / выключен
switch.PANDORA_ID_engine	Статус двигателя	запущен / заглушен
switch.PANDORA_ID_tracking	Статус отслеживания (GPS-трек)	включен / выключен
switch.PANDORA_ID_service_mode	Режим сервиса (обслуживания)	включен / выключен
switch.PANDORA_ID_ext_channel	Дополнительный канал 3	включить / выключить
switch.PANDORA_ID_status_output	Статусный выход (для нештатных иммобилайзеров)	включить / выключить

³ Состояние не остслеживается

Платформа device_tracker

Для каждого автомобиля будет создан объект device_tracker.pandora_PANDORA_ID, где PANDORA_ID уникальный идентификатор автомобиля в системе Pandora. Доступны все обычные действия для Device Tracker: отслеживание местоположения на карте, трекинг пути, контроль зон и т.д.

Пример отображения маркера на карте (цвет, поворот)

Объект обладает следующими атрибутами:

Параметр	Тип	Описание
latitude	float	Широта
longitude	float	Долгота
device_id	int	Идентификатор устройства
voltage	float	Бортовое напряжение
gsm_level	int	Уровень связи
direction	int	Направление (в градусах)
cardinal	str	Направление (в сторонах света)
key_number	int	Номер используемого ключа
tag_number	int	Номер используемой метки

События

За период наблюдения компонентом за автомобилем могут происходить некоторые события, чьи свойства не позволяют сделать из них удобные к использованию объекты платформ `sensor`, `binary_sensor` и пр. Ввиду этого, для поддержки дополнительных событий введены два новых внутренних делегата:

Делегат событий pandora_cas_event

Данное событие делегирует информацию из системы Pandora прямиком в Home Assistant. Следующие данные будут доступны при получении события:

Параметр	Тип	Описание
device_id	int	Идентификатор устройства
event_id_primary	int	Первичный код события
event_id_secondary	int	Вторичный код события
event_type	str	Код типа события
latitude	float	Широта
longitude	float	Долгота
gsm_level	int	Уровень связи
fuel	int	Уровень топлива
exterior_temperature	int	Температура за бортом
engine_temperature	int	Температура двигателя

Код типа события является строкой, которая поверхностно описывает смысл события (на английском языке). Полным списком кодов (кодификатором) возможно обзавестись в файле api.py проекта.

Делегат событий pandora_cas_command

Для всех команд будут выполняться события-уведомители. Данные события содержат следующие данные:

Параметр	Тип	Описание
device_id	int	Идентификатор устройства
command_id	int	Номер команды (см. раздел ниже)
result	int	Результат выполнения (0 - успех, любое другое значение - ошибка)
reply	int	Код описания ошибки (больше нуля, если код доступен)

Команды / Службы

Ключевые команды включения/выключения определённых функций вынесены в отдельные переключаемые объекты (пр. switch и lock). Если же имеется потребность выступить за рамки предопределённых конфигураций, существуют два способа передать дополнительные команды на охранную систему.

Для именованого способа требуется вызов службы в формате pandora_cas.<Постфикс>:

# Именованый способ вызова команд
- action: call-service
  service: pandora_cas.start_engine
  data:
    device_id: 1231234123

Для универсального способа идентификаторы команд (command_id) обязательно должны быть числовыми:

# Универсальный способ вызова команд
- action: call-service
  service: pandora_cas.remote_command
  data:
    device_id: 1234141243
    command_id: 1

Для справки, ниже представлена таблица доступных к выполнению команд (сгруппированых по смысловому признаку):

ID	Постфикс	Действие	Примечание
1	lock	Поставить на охрану	Может быть запрещено настройками блока сигнализации
2	unlock	Снять с охраны	Может быть запрещено настройками блока сигнализации
4	start_engine	Запустить двигатель
8	stop_engine	Остановить двигатель
16	enable_tracking	Включить GPS-трекинг	Поддерживается не всеми устройствами
32	disable_tracking	Выключить GPS-трекинг	Поддерживается не всеми устройствами
17	enable_active_security	Включить активную безопасность	Поддерживается не всеми устройствами
18	disable_active_security	Выключить активную безопасность	Поддерживается не всеми устройствами
21	turn_on_coolant_heater	Включить преднагреватель	Поддерживается не всеми устройствами
22	turn_off_coolant_heater	Выключить преднагреватель	Поддерживается не всеми устройствами
33	turn_on_ext_channel	Включить дополнительный канал	Поддерживается не всеми устройствами
34	turn_off_ext_channel	Выключить дополнительный канал	Поддерживается не всеми устройствами
40	enable_service_mode	Включить сервисный режим
41	disable_service_mode	Выключить сервисный режим
23	trigger_horn	Издать сигнал клаксона
24	trigger_light	Включить освещение
255	check	Команда CHECK	?
100	additional_command_1	Дополнительная команда №1	Настраивается инструментами конфигурации блока сигнализации
128	additional_command_2	Дополнительная команда №2	Настраивается инструментами конфигурации блока сигнализации
240	enable_connection	Продлить период коммуникации	?
15	disable_connection	Завершить период коммуникации	?
48	enable_status_output	Выключение статусного выхода	Подразумевается поддержка на стороне автомобиля
49	disable_status_output	Включение статусного выхода	Подразумевается поддержка на стороне автомобиля

Примеры использования команд

Вкладка с кнопкой запуска двигателя

  - badges: []
    cards:
      - hold_action:
          action: call-service
          service: pandora_cas.start_engine
          data:
            id: 1234567890
        icon: 'mdi:fan'
        name: Запуск двигателя
        show_icon: true
        show_name: true
        tap_action:
          action: more-info
        type: button
    icon: 'mdi:car'
    panel: false
    path: honda_pilot
    title: Honda Pilot

Автоматизация включения доп. канала по событию с условиями. Подробнее см. пример использования.

# Фрагмент файла automations.yaml
- id: switch_on_pilot_seat_heaters
  alias: Включить подогрев сидений
  trigger:
    platform: state
    entity_id: binary_sensor.1234567890_engine_state
    to: 'on'
  condition:
  - condition: time
    after: 05:58:00
    before: 06:12:00
    weekday:
    - mon
    - tue
    - wed
    - thu
    - fri
  action:
    service: pandora_cas.turn_on_ext_channel
    data_template:
      id: 1234567890

Отказ от ответственности

Данное программное обеспечение никак не связано и не одобрено ООО «НПО Телеметрия», владельца торговой марки Pandora. Используйте его на свой страх и риск. Автор ни при каких обстоятельствах не несет ответственности за порчу или утрату вашего имущества и возможного вреда в отношении третьих лиц.

Все названия брендов и продуктов принадлежат их законным владельцам.