Skip to content

Latest commit

 

History

History
807 lines (646 loc) · 41.4 KB

README.md

File metadata and controls

807 lines (646 loc) · 41.4 KB

ЕЛК ЖКХ «Интер РАО» для Home Assistant

Логотип интеграции

Предоставление информации о текущем состоянии ваших аккаунтов в ЕЛК ЖКХ.

Information retrieval from Inter RAO personal cabinets.

hacs_badge Лицензия Поддержка

Пожертвование Yandex Пожертвование PayPal

Установка

Посредством HACS

✔️️ Рекомендуемый метод

  1. Установите HACS (инструкция по установке на оф. сайте)
  2. Найдите lkcomu_interrao (или Интер РАО) в поиске по интеграциям 1
  3. Установите последнюю версию компонента, нажав на кнопку Установить (Install)
  4. Перезапустите Home Assistant

Вручную

⚠️ Не рекомендуется

  1. Скачайте архив с исходным кодом дополнения
  2. Извлеките папку lkcomu_interrao из архива в папку custom_components внутри папки с конфигурацией Home Assistant (создайте её, если она отсутствует)
  3. Перезапустите Home Assistant

Настройка

Через раздел интеграции

  1. Перейдите в подраздел "Интеграции" в разделе "Настройки"
  2. Нажмите кнопку "Добавить интеграцию"
  3. Введите в поисковую строку: Личный кабинет Интер РАО (Энергосбыт) (англ. Inter RAO Personal Cabinet (Energosbyt))
  4. Выберите найденную интеграцию
  5. Следуйте инструкциям мастера по добавлению

Примечание: Поле Заголовок User-Agent (англ. User-Agent header) генерируется автоматически.

Описание конфигурационной схемы

# Файл `configuration.yaml`
lkcomu_interrao:

  # Тип выбранного ЛК
  # Значение по умолчанию: moscow
  # Перечень возможных значений:
  # - altai (ЛК Алтай (АО «АлтайЭнергосбыт»))
  # - bashkortostan (ЛКК ЭСКБ (Башэлектросбыт))
  # - moscow (ЕЛК ЖКХ (АО «Мосэнергосбыт», МосОблЕИРЦ, ПАО «Россети Московский регион»))
  # - oryol (ЛКК Орел (ООО «Орловский энергосбыт»))
  # - saratov (ЛК Саратов (ПАО «Саратовэнерго»))
  # - sevesk (ЕЛК Вологда (Северная сбытовая компания))
  # - tambov (ЛК ТЭСК (Тамбовская энергосбытовая компания))
  # - tomsk (ЕЛК Томск (Томскэнергосбыт / Томск РТС))
  # - volga (ЛКК ЭСВ (Энергосбыт Волга))
  type: "..."

  # Имя пользователя
  # Обязательный параметр
  username: "..."

  # Пароль
  # Обязательный параметр
  password: "..."

  # Конфигурация по умолчанию для лицевых счетов
  # Необязательный параметр
  #  # Данная конфигурация применяется, если отсутствует  # конкретизация, указанная в разделе `accounts`.
  default:

    # Получать ли ссылки на логотипы
    # Значение по умолчанию: истина (true)
    logos: true | false

    # Добавлять ли объект(-ы): Информация о лицевом счёте
    # Значение по умолчанию: истина (true)
    accounts: true | false

    # Добавлять ли объект(-ы): Счётчик коммунальных услуг
    # Значение по умолчанию: истина (true)
    meters: true | false

    # Добавлять ли объект(-ы): Последний зарегистрированный платёж
    # Значение по умолчанию: истина (true)
    last_payment: true | false

    # Добавлять ли объект(-ы): Последняя выпущенная квитанция
    # Значение по умолчанию: истина (true)
    last_invoice: true | false

  # Настройки для отдельных лицевых счетов
  # Необязательный параметр
  accounts:

    # Номер лицевого счёта
    "...":

      # Конфигурация по конкретным лицевым счетам выполняется аналогично
      # конфигурации по умолчанию для лицевых счетов (раздел `default`).
      ...

Вариант конфигурации "Чёрный список"

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

...
lkcomu_interrao:
  ...
  # Выборочное исключение лицевых счетов
  accounts:
    # Все указанные ниже лицевые счета будут добавлены
    "12345-678-90": false
    "98765-432-10": false
    "111000111000": false

Вариант конфигурации "Белый список"

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

...
lkcomu_interrao:
  ...
  # Отключение добавление лицевых счетов по умолчанию
  default: false

  # Выборочное включение лицевых сченов
  accounts:
    # Все указанные ниже лицевые счета будут добавлены
    "12345-678-90": true
    "98765-432-10": true
    "111000111000": true

Также возможно использовать укороченную запись:

...
lkcomu_interrao:
  ...
  # Данный пример функционально эквивалентен предыдущему примеру
  default: false
  accounts: ["12345-678-90", "98765-432-10", "111000111000"]

Доступные объекты

Все объекты гарантируют наличие и полноту следующих атрибутов:

  • account_code: str - Номер лицевого счёта
  • account_id: int - Внутренний идентификатор лицевого счёта

Лицевые счета — lkcomu_interrao_account

Домен объектов: sensor

Объект лицевого счёта отображает основную информацию о лицевом счёте, а также его баланс (положительное значение) или имеющуюся задолженность (отрицательное значение) 1.

Состояние объекта может принимать следующие значения:

  • unknown - Информация о состоянии баланса не была предоставлена
  • число - Текущее состояние баланса

1 ... в том случае, если лицевой счёт предоставляет информацию о балансе

Сопутствующие службы

Данные службы применимы только к объектам лицевых счетов

set_description — Установить описание лицевого счёта

Устанавливает описание для лицевого счёта и провоцирует его обновление.

Параметры
  • description: str | None - (опционально) Новое описание для лицевого счёта
Результат

Событие с идентификатором lkcomu_interrao_set_description и следующими значениями:

  • success: bool - Если установка описания была выполнена успешно
  • description: str | None - Описание, с которым была вызвана служба
  • previous: str | None - Описание, которым обладал (или, в случае ошибки, обладает) лицевой счёт
  • account_id: int - Внутренний идентификатор лицевого счёта
  • account_code: str - Номер лицевого счёта
get_invoices — Получение квитанций по периодам

Только для объектов, поддерживающих данный функционал

Параметры
  • start: str | None - (опционально) Дата начала периода
  • end: str | None - (опционально) Дата окончания периода
Результат

Событие с идентификатором lkcomu_interrao_get_invoices и следующими значениями:

  • sum: float - сумма всех квитанций за указанный период
  • period: str - период квитанции
  • invoice_id: str - идентификатор квитанции
  • total: float - сумма к оплате по квитанции
  • paid: float | None - сумма оплат, учтённых к квитанции
  • initial: float | None - задолженность/избыток на начало периода
  • charged: float | None - начислено за период
  • insurance: float | None - добровольное страхование
  • benefits: float | None - льготы
  • penalty: float | None - штрафы
  • service: float | None - тех. обслуживание
get_payments — Получение платежей по периодам

Только для объектов, поддерживающих данный функционал

Параметры
  • start: str | None - (опционально) Дата начала периода
  • end: str | None - (опционально) Дата окончания периода
Результат

Событие с идентификатором lkcomu_interrao_get_payments и следующими значениями:

  • sum: float - сумма всех платежей за указанный период
  • amount: float - объём платежа
  • paid_at: str - дата/время платежа
  • period: str - период, за который платёж был выполнен
  • status: str | None - состояние платежа
  • agent: str | None - банк-обработчик платежа
  • group: str | None - группа платежа (для лицевых счетов с несколькими типами платежей)

Счётчики — lkcomu_interrao_meter

Домен объектов: sensor

Объект счётчика отображает информацию о счётчике, а также сведения о последних переданных показаниях и диапазоне периода передачи показаний1.

Состояние объекта может принимать следующие значения:

  • ok - Текстовое описание состояния отсутствует
  • текст - Текстовое описание состояние счётчика (может быть любой длины, и содержать в себе любой набор символов, в т.ч. HTML-теги)

Объект гарантирует наличие и полноту следующих атрибутов:

  • meter_code - Номер счётчика
  • install_date - Дата установки
  • submit_period_start - Дата начала периода передачи показаний (в текущем месяце) 1
  • submit_period_end - Дата окончания периода передачи показаний (в текущем месяце) 1
  • submit_period_active - Флаг активности периода передачи показаний 1
  • zone_t[N]_name - Наименование тарифной зоны / тарифа
  • zone_t[N]_last_indication - Последнее показание по тарифной зоне 2

Объект гарантирует наличие, но не полноту следующих атрибутов:

  • model - Модель счётчика
  • last_indications_date - Дата последней передачи показаний
  • zone_t[N]_description - Описание тарифной зоны / тарифа
  • zone_t[N]_today_indication - Значение переданного сегодня показания по тарифной зоне
  • zone_t[N]_invoice_indication - Значение последнего показания по тарифной зоне, учтённому в квитанции
  • zone_t[N]_period_indication - Значение переданного за период показания по тарифной зоне 1
  • zone_t[N]_invoice_name - Наименование тарифной зоны, указанное в последней квитанции

1 ... в том случае, если счётчик поддерживает передачу показаний
2 При отсутствии фактического значения атрибут примет значение 0.0

Сопутствующие службы

Данные службы применимы только к объектам счётчиков

push_indications — Передача показаний

Только для объектов, поддерживающих данный функционал

Служба передачи показаний позволяет отправлять показания по счётчикам в личный кабинет, и имеет следующий набор параметров:

Название Описание
target Выборка целевых объектов, для которых требуется передавать показания
data.indications Список / именованный массив показаний, передаваемых в ЛК
data.incremental Суммирование текущих показаний с передаваемыми
data.ignore_period Игнорировать период передачи показаний
data.ignore_indications Игнорировать ограничения по значениям
1. Обычная передача показаний
  • Например, если передача показаний активна с 15 по 25 число, а сегодня 11, то показания не будут отправлены1.
  • Например, если текущие, последние или принятые значения по счётчику – 321, 654 и 987 по зонам Т1, Т2 и Т3 соответственно, то показания не будут отправлены1.
service: lkcomu_interrao.push_indications
data:
  indications: "123, 456, 789"
target:
  entity_id: sensor.1243145122_meter_123456789

... или, с помощью именованного массива:

service: lkcomu_interrao.calculate_indications
data:
  indications:
    t1: 123
    t2: 456
    t3: 789
target:
  entity_id: sensor.1243145122_meter_123456789

... или, с помощью списка:

service: lkcomu_interrao.calculate_indications
data:
  indications: [123, 456, 789]
target:
  entity_id: sensor.1243145122_meter_123456789
2. Форсированная передача показаний

Отключение всех ограничений по показаниям.

  • Например, если передача показаний активна с 15 по 25 число, а сегодня 11, то показания будут отправлены1.
  • Например, если текущие, последние или принятые значения по счётчику – 321, 654 и 987 по зонам Т1, Т2 и Т3 соответственно, то показания будут отправлены1.
service: lkcomu_interrao.calculate_indications
data_template:
  indications: [123, 456, 789]
  ignore_indications: true
  ignore_periods: true
target:
  entity_id: sensor.1243145122_meter_123456789
3. Сложение показаний
  • Например, если передача показаний активна с 15 по 25 число, а сегодня 11, то показания не будут отправлены1.
  • Например, если текущие, последние или принятые значения по счётчику – 321, 654 и 987 по зонам Т1, Т2 и Т3 соответственно, то показания будут отправлены1.

Внимание: в данном примере будут отправлены показания 444, 1110 и 1776, а не 123, 456 и 789.

service: lkcomu_interrao.calculate_indications
data_template:
  indications: [123, 456, 789]
  incremental: true
target:
  entity_id: sensor.1243145122_meter_123456789
calculate_indications — Подсчёт показаний

Только для объектов, поддерживающих данный функционал


Последние платежи — lkcomu_interrao_last_payment

Домен объектов: binary_sensor

Объект последнего платежа отображает информацию о последнем зарегистрированном платеже, связанном с лицевым счётом.

Состояние объекта может принимать следующие значения:

  • on - Платёж был обработан
  • off - Платёж ещё не обработан
  • unknown - Последний платёж не был найден

Объект гарантирует наличие и полноту следующих атрибутов:

  • amount: float - Сумма платежа
  • paid_at: str - Дата и время платежа
  • period: str - Период, за который был выполнен платёж

Объект гарантирует наличие, но не полноту, следующих атрибутов:

  • status: str | None - Состояние платежа
  • agent: str | None - Банк, проводящий платёж
  • group: str | None - Группа платежа (для лицевых счетов с несколькими источниками платежей)

Последние квитанции — lkcomu_interrao_last_invoice

Домен объектов: sensor

@ TODO @


Поддерживаемые ЛК

Ниже предъявлен перечень поддерживаемых ЛК с их внутренними идентификаторами. Данные идентификаторы используются как значение для поля type.

Внимание: Поддерживаются только ЛК физических лиц. Поддержка ЛК юридических лиц не планируется.

ЕЛК ЖКХ (АО «Мосэнергосбыт», МосОблЕИРЦ, ПАО «Россети Московский регион») - moscow

Ссылка на личный кабинет "ЕЛК ЖКХ (АО «Мосэнергосбыт», МосОблЕИРЦ, ПАО «Россети Московский регион»)"

Пример конфигурации:

...
lkcomu_interrao:
  type: moscow
  username: username1
  password: password1

Поставщик MES — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

Поставщик KSG — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

Поставщик MOE — ЕПД

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

Поставщик TKO — ТКО

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Снимок экрана отсутствует
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Снимок экрана отсутствует

ЛКК Орел (ООО «Орловский энергосбыт») - oryol

Ссылка на личный кабинет "ЛКК Орел (ООО «Орловский энергосбыт»)"

Пример конфигурации:

...
lkcomu_interrao:
  type: oryol
  username: username1
  password: password1

Поставщик ORL_EPD — ЕПД

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последняя выпущенная квитанция Скриншот

Поставщик ORL — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЛКК ЭСВ (Энергосбыт Волга) - volga

Ссылка на личный кабинет "ЛКК ЭСВ (Энергосбыт Волга)"

Пример конфигурации:

...
lkcomu_interrao:
  type: volga
  username: username1
  password: password1

Поставщик VLD — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЕЛК Томск (Томскэнергосбыт / Томск РТС) - tomsk

Ссылка на личный кабинет "ЕЛК Томск (Томскэнергосбыт / Томск РТС)"

Пример конфигурации:

...
lkcomu_interrao:
  type: tomsk
  username: username1
  password: password1

Поставщик TMK_NRG — generic

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЛК ТЭСК (Тамбовская энергосбытовая компания) - tambov

Ссылка на личный кабинет "ЛК ТЭСК (Тамбовская энергосбытовая компания)"

Пример конфигурации:

...
lkcomu_interrao:
  type: tambov
  username: username1
  password: password1

Поставщик TMB — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЕЛК Вологда (Северная сбытовая компания) - sevesk

Ссылка на личный кабинет "ЕЛК Вологда (Северная сбытовая компания)"

Пример конфигурации:

...
lkcomu_interrao:
  type: sevesk
  username: username1
  password: password1

Поставщик VLG — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЛК Саратов (ПАО «Саратовэнерго») - saratov

Ссылка на личный кабинет "ЛК Саратов (ПАО «Саратовэнерго»)"

Пример конфигурации:

...
lkcomu_interrao:
  type: saratov
  username: username1
  password: password1

Поставщик SAR — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЛКК ЭСКБ (Башэлектросбыт) - bashkortostan

Ссылка на личный кабинет "ЛКК ЭСКБ (Башэлектросбыт)"

Пример конфигурации:

...
lkcomu_interrao:
  type: bashkortostan
  username: username1
  password: password1

Поставщик UFA — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

ЛК Алтай (АО «АлтайЭнергосбыт») - altai

Ссылка на личный кабинет "ЛК Алтай (АО «АлтайЭнергосбыт»)"

Пример конфигурации:

...
lkcomu_interrao:
  type: altai
  username: username1
  password: password1

Поставщик ALT — Электричество

Для поставщика реализована поддержка следующих объектов:

Информация о лицевом счёте Скриншот
Последний зарегистрированный платёж Скриншот
Последняя выпущенная квитанция Скриншот
Счётчик коммунальных услуг Скриншот

Дополнительная информация

Компонент находится в активной разработке. Примерная дорожная карта и план развития:

  • [0.0.1; 0.1.0) — первичная обкатка компонента на поддерживаемых поставщиках;
  • [0.1.0; 0.2.0) — разработка визуального конфигуратора для интеграции;
  • [0.2.0; 1.0.0) — выполнение задач по оптимизации и чистке кода;
  • [1.0.0; .....) — финальный выпуск компонента и исправление ошибок.

Увеличение старшей версии сопутствует:

  • изменениям в конфигурационной схеме;
  • удалению функционала;
  • расширению сферы применения интеграции.

Увеличение младшей версии сопутствует:

  • добавлению нового функционала;
  • исправлению значительных ошибок.

Увеличение номера сборки сопутствует:

  • исправлению мелких ошибок / выпуску хотфиксов;
  • изменениям во взаимодействии с основополагающей библиотекой (или её версии).