Skip to content
This repository has been archived by the owner on Jun 16, 2021. It is now read-only.
/ hass-mosenergosbyt Public archive

Home Assistant Mosenergosbyt personal cabinet data and statistics sensor

License

Notifications You must be signed in to change notification settings

alryaz/hass-mosenergosbyt

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

59 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

❗❗❗ ВНИМАНИЕ ❗❗❗

Данный репозиторий является архивным. Последующее развитие концепции доступа к ЛК доступно в проекте: alryaz/hass-lkcomu-interrao.

Интеграция lkcomu_interrao обладает аналогичным функционалом, и поддерживает гораздо больше поставщиков и личных кабинетов. Среди них:

  • Томскэнергосбыт / ТомскРТС
  • Саратовэнерго
  • Башэнергосбыт (Уфа)
  • Тамбовский энергосбыт
  • Алтайский энергосбыт (г. Барнаул и др.)
  • Энергосбыт "Волга" (г. Владимир)
  • Северная Сбытовая Компания (ССК) (г. Вологда)

Благодарю всех, кто участвовал в развитии данного проекта.

❗❗❗ ВНИМАНИЕ ❗❗❗

Мосэнергосбыт для HomeAssistant

Предоставление информации о текущем состоянии ваших аккаунтов в Мосэнергосбыт.

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

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

Данная интеграция предоставляет возможность системе HomeAssistant опрашивать API Мосэнергосбыта.

Скриншоты

(Возможно увеличить, нажав на картинку и перейдя по ссылке)

Лицевой счёт Счётчик МЭС Счётчик МЭС+ТКО Квитанция

Поддержка провайдеров

Данный список исчерпывающе описывает совместимость. Если для Вас интеграция не заработала, создайте issue.

Провайдер kd_provider_id Лицевой счёт Счётчики Счета Передача показаний
MES 1 Да Да Да Да
MOE 2 Да Да Да Да
TMK_NRG 3 Нет Нет Нет Нет
TMK_RTS 4 Нет Нет Нет Нет
UFA 5 Нет Нет Нет Нет
TKO 6 Да Нет Нет
VLG 7 Нет Нет Нет Нет
ORL 8 Нет Нет Нет Нет
ORL_EPD 9 Нет Нет Нет Нет
ALT 10 Нет Нет Нет Нет
TMB 11 Нет Нет Нет Нет
VLD 12 Нет Нет Нет Нет
SAR 13 Нет Нет Нет Нет
KSG 14 Да Да Да Да

Пометка "Да" означает полную поддержку, "Нет" - отсутствие поддержки, и "—" - отсутствие технической возможности передавать показания (даже через ЛК).

Установка

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

  1. Откройте HACS (через Extensions в боковой панели)
  2. Добавьте новый произвольный репозиторий:
    1. Выберите Integration (Интеграция) в качестве типа репозитория
    2. Введите ссылку на репозиторий: https://github.com/alryaz/hass-mosenergosbyt
    3. Нажмите кнопку Add (Добавить)
    4. Дождитесь добавления репозитория (занимает до 10 секунд)
    5. Теперь вы должны видеть доступную интеграцию Mosenergosbyt (Мосэнергосбыт) в списке новых интеграций.
  3. Нажмите кнопку Install чтобы увидеть доступные версии
  4. Установите последнюю версию нажатием кнопки Install
  5. Перезапустите HomeAssistant

Примечание: Не рекомендуется устанавливать ветку master. Она используется исключительно для разработки.

Вручную

Клонируйте репозиторий во временный каталог, затем создайте каталог custom_components внутри папки конфигурации вашего HomeAssistant (если она еще не существует). Затем переместите папку mosenergosbyt из папки custom_components репозитория в папку custom_components внутри папки конфигурации HomeAssistant. Пример (при условии, что конфигурация HomeAssistant доступна по адресу /mnt/homeassistant/config) для Unix-систем:

git clone https://github.com/alryaz/hass-mosenergosbyt.git hass-mosenergosbyt
mkdir -p /mnt/homeassistant/config/custom_components
mv hass-mosenergosbyt/custom_components/mosenergosbyt /mnt/homeassistant/config/custom_components

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

Лицевой счёт — mosenergosbyt_account

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

Параметры, доступные для форматирования названий: code, account_code, service_name, service_id, service_type_id, service_type_name, provider_name.

Ключ конфигурации для иерархичных параметров: accounts.

Доступные атрибуты

Название Описание Тип Условие доступности
account_code Номер лицевого счёта str Всегда
address Адрес, по которому зарегистрирован лицевой счёт str Всегда
service_type Буквенный код типа предоставляемых услуг str Всегда
description Пользовательский комментарий к аккаунту (изменяется в боковой панели в ЛК) str/None Всегда
provider_name Название провадера услуг str Всегда
service_name Наименование предоставляемых услуг str Всегда
status Текущее состояние аккаунта (ok или locked) str Всегда
reason Причина блокировки аккаунта str Если status == locked
last_payment_date Дата (и время) последнего платежа str(datetime)/None Всегда
last_payment_amount Объём последнего платежа float/None Всегда
last_payment_status Состояние последнего платежа str/None Всегда
submit_period_active Флаг возможности передавать показания за текущий период bool/None Всегда
remaining_days Количество дней до следующего изменения возможности передавать показания int/None Всегда

Связанные службы

Название Описание Доп. параметры
update Полное обновление указанного объекта (аналогично службе homeassistant.update) Отсутствуют
update_account Обновление информации об аккаунте Отсутствуют
update_last_indications Обновление информации о последних переданных показаниях Отсутствуют
update_submission_availability Обновление информации о возможности передачи показаний Отсутствуют

Счётчик — mosenergosbyt_meter

Доступные атрибуты

Название Описание Тип Условие доступности
meter_code Номер счётчика str Всегда
account_code Номер лицевого счёта str Всегда
model Модель счётчика str Если счётчик поддерживает отображение информации о модели
install_date Дата установки счётчика str(date)/None Если счётчик поддерживает отображение даты установки счётчика
submit_period_start Дата начала периода передачи показаний str(date)/None Если счётчик поддерживает отображение даты начала периода передачи показаний
submit_period_end Дата окончания периода передачи показаний str(date)/None Если счётчик поддерживает отображение даты окончания периода передачи показаний
tariff_{ID}_name Наименование тарифа {ID} str/None Если счётчик предоставляет информацию о тарифах
tariff_{ID}_cost Стоимость тарифа {ID} за единицу str/None Если счётчик предоставляет информацию о тарифах
tariff_{ID}_description Описание тарифа {ID} str/None Если счётчик предоставляет информацию о тарифах
tariff_{ID}_unit Единица измерения тарифа {ID} str/None Если счётчик предоставляет информацию о тарифах
last_submit_date Дата последней передачи показаний str/None Если счётчик поддерживает отображение даты последней передачи показаний
last_value_{ID} Показание тарифа {ID}, переданное в последний раз float/None Если счётчик поддерживает тарифы и показания
submitted_value_{ID} Показание тарифа {ID}, переданное за текущий период float/None Если счётчик поддерживает тарифы и показания
today_value_{ID} Показание тарифа {ID}, переданное за сегодняшний день float/None Если счётчик поддерживает тарифы и показания

Связанные службы

Название Описание Доп. параметры
update Полное обновление указанного объекта (аналогично службе homeassistant.update) Отсутствуют
update_meter Обновление информации о счётчике Отсутствуют
Службы подсчёта и передачи показаний

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

Вызов каждой из служб регламентируется следующим набором параметров:

Параметр Описание По умолчанию
indications* Список значений по показаниям (список длиной количества тарифов целевого счётчика из целых или дробных чисел)
ignore_period Не учитывать ограничения по периоду false
учитывать ограничения
ignore_indications Не учитывать ограничения по показаниям false
учитывать ограничения
incremental Прибавлять указанные значения поверх последних переданных 1 false
передавать показания без изменений
notification Показывать уведомление при успешном подсчёте начислений3 false
не показывать)

1 Последние переданные показания включают в себя те, что отображаются под submitted_value_t[1,2,3]
2 Будут возвращены значения, полученные после прибавления последних предыдущих показаний
3 Для уведомлений возможно использовать формат службы persistent_notification.create. Будут заменены все значения в тексте, которые имеют вид {имя_переменной} из списка переменных выше. !!! Это НЕ шаблоны Home Assistant / Jinja2 !!!

В ответ, службы посылают событие, которое содержит следующие значения (актуально для обеих служб):

Параметр Описание Тип Условие доступности
entity_id Идентификатор объекта str Всегда
meter_code Номер счётчика str Всегда
call_params Словарь параметров вызова службы (без изменений) Dict[str,Any] Всегда
success Флаг если операция была успешной bool Всегда
indications Список нормальзованных показаний List[float]/None После успешной нормализации показаний
indications_dict Словарь показаний: ID тарифа -> показание Dict[str,float]/None После успешной нормализации показаний
comment Комментарий/сообщение, переданное сервером, или описание возникшей ошибки str/None При наличии ответа сервера/при возникновении ошибки
Подсчёт начислений до передачи показаний — mosenergosbyt.calculate_indications

Идентификатор события ответа: mosenergosbyt_calculation_result

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

Параметр Описание Тип Условие доступности
period Период передачи показаний str(date)/None После успешного подсчёта показаний
charged Размер начислений по переданным показаниям float/None После успешного подсчёта показаний
correct Если показания были приняты сервером как безошибочные bool/None После успешного подсчёта показаний

Стоит отметить, что равенство параметра correct значению false не является достаточным условием невозможности передать показния. При передаче показаний с параметром ignore_indications, в некоторых случаях система может одобрить переданные показания, однако предупредить пользователя о потребности выполнить перерасчёт, ввиду чего сумма начислений может кардинально отличиться от ожидаемой.

Пример вызова 1: Вызов службы с применением шаблонов для подстановки значений

service: mosenergosbyt.calculate_indications
data_template:
  indications:
    - "{{ states('sensor.monthly_consumption_peak') + state_attr('sensor.mes_meter_123456789', 'last_value_t1') }}"
    - "{{ states('sensor.monthly_consumption_offpeak') + state_attr('sensor.mes_meter_123456789', 'last_value_t2') }}"
    - "{{ states('sensor.monthly_consumption_halfpeak') + state_attr('sensor.mes_meter_123456789', 'last_value_t3') }}"
target:
  entity: sensor.mes_meter_123456789

Пример вызова 2: Вызов службы со статическими значениями в режиме CSV (например, из интерфейса)

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

service: mosenergosbyt.calculate_indications
data_template:
  indications: "2, 2, 2"
  incremental: true
target:
  entity: sensor.mes_meter_123456789

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

automation:
  - id: respond_to_calculation
    trigger:
      platform: event
      event_type: mosenergosbyt_calculation_result
    action:
      service: persistent_notification.create
      data_template:
        title: "Результаты подсчётов"
        message: >
          Для счётчика {{ state_attr(trigger.event.data['entity_id'], 'meter_code') }}
          выполнен подсчёт за период {{ trigger.event.data['period'] }};
          будет начислено {{ trigger.event.data['charged'] }}
Передача показаний — mosenergosbyt.push_indications

Идентификатор события ответа: mosenergosbyt_push_result

Действия по вызову данной службы аналогичны вызову службы подсчёта показаний.

Выставленный счёт - mosenergosbyt_invoice

Связанные службы

Название Описание Доп. параметры
update Полное обновление указанного объекта (аналогично службе homeassistant.update) Отсутствуют
update_invoice Обновление информации о последнем выставленном счёте Отсутствуют

Конфигурация

Через интерфейс HomeAssistant

  1. Откройте Настройки -> Интеграции
  2. Нажмите внизу справа страницы кнопку с плюсом
  3. Введите в поле поиска Mosenergosbyt или Мосэнергосбыт
    1. Если по какой-то причине интеграция не была найдена, убедитесь, что HomeAssistant был перезапущен после установки интеграции.
  4. Выберите первый результат из списка
  5. Введите данные вашей учётной записи для ЛК "Мосэнергосбыт"
  6. Нажмите кнопку Продолжить
  7. Через несколько секунд начнётся обновление; проверяйте список ваших объектов на наличие объектов, чьи названия начинаются на MES.

Через configuration.yaml

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

Для настройки данной интеграции потребуются данные авторизации в ЛК Мосэнергосбыт.
username - Имя пользователя (телефон / адрес эл. почты)
password - Пароль

mosenergosbyt:
  username: !secret mosenergosbyt_username
  password: !secret mosenergosbyt_password

Несколько пользователей

Возможно добавить несколько пользователей. Для этого вводите данные, используя пример ниже:

mosenergosbyt:
    # First account
  - username: !secret first_mosenergosbyt_username
    password: !secret first_mosenergosbyt_password

    # Second account
  - username: !secret second_mosenergosbyt_username
    password: !secret second_mosenergosbyt_password

    # Third account
  - username: !secret third_mosenergosbyt_username
    password: !secret third_mosenergosbyt_password 

Авторитарное отключение объектов — entities

Из соображений минимизации количества добавляемых в Home Assistant объектов, возможно отключать объекты как все, так и выборочно (по номерам или классам). Отключённые объекты не будут добавляться в Home Assistant и отображаться в разделе отключённых объектов.

По умолчанию все объекты считаются допущенными к включению

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

Действия по авторитарному отключению объектов не влияют на встроенные механизмы отключения объектов в Home Assistant.

Пример 1: Отключение объектов конкретного класса

mosenergosbyt:
  ...
  entities:
      # Ни один объект класса лицевых счетов не будет добавлен
      accounts: false

Пример 2: Отключение объектов для всех классов одновременно

mosenergosbyt:
  ...
  # Это возможно, однако приводит к бессмысленной работе компонента
  entities: false

Пример 3: Задание отключения смешанным образом, и для конкретных объектов

mosenergosbyt:
  ...
  entities:
    meters:
      # Счётчик с номером "1254123123" не будет отключён
      "1254123123": true     
      # ...однако все остальные счётчики будут отключены по умолчанию
      default: false

    invoices:
      # Выставленный счёт с номером "123123123-123-123" будет отключён
      "123123123-123-123": false

      # Все остальные счета будут включены, так как это является состоянием
      # по умолчанию.

Пример 4: Применение чёрного/белого списков

mosenergosbyt:
  ...
  entities:
    # Перечисленные в списке счётчики будут добавляться в интерфейс (белый список)
    meters: ['321', '111', '123']

    # Добавление значения 'default' в перечень инвертирует его значения
    invoices: ['default', '321', '111', '123']

Данный подход так же распространяется на корневые значения:

mosenergosbyt:
  ...
  # Будет обеспечена поддержка только выставляемых счетов и счётчиков;
  # лицевые счета не будут доступны при данной конфигурации.
  entities: ['invoices', 'meters']

  # Добавление значения 'default' в список изменит действие в противоположную
  # сторону: выставляемые счета и счётчики добавляться не будут, а, например,
  # лицевые счета - да.

Настройка частоты обновления — scan_interval

Частота обновления может быть настроена как для всех объектов сразу, так и для каждого объекта или класса объектов отдельно. По умолчанию, частота обновления равна одному часу.

Минимальная частота обновления - 60 секунд. При задании частоты обновления меньшей, чем указанная минимальная частота, в лог будет выведено предупреждение об этом, а частота обновления будет автоматически заменена на значение минимальной частоты обновления.

Пример 1: Задание частоты обновления для каждого класса отдельно

mosenergosbyt:
  ...
  scan_interval:
      # Произвольная частота обновления для лицевых счетов
      accounts: 3600  # 3600 секунд
    
      # Произвольная частота обновления для счётчиков
      meters:
        minutes: 3  # 3 минуты
    
      # Произвольная частота обновления для квитанций
      invoices:
        days: 2  # 2 дня

Пример 2: Задание частоты обновления для всех классов одновременно

mosenergosbyt:
  ...
  scan_interval: 3600  # 3600 секунд

Пример 3: Задание частот обновления смешанным образом, и для конкретных объектов

mosenergosbyt:
  ...
  scan_interval:
    meters:
      # Частота обновления для счётчика с номером "1254123123"
      "1254123123": 123  # 123 секунды
      
      # Частота обновления по умолчанию для остальных счётчиков
      default: 10  # 10 секунд; автоматически будет заменено на 60 секунд

    invoices:
      # Частота обновления для счёта с номером "123123123-123-123"
      "123123123-123-123":
        hours: 4  # 4 часа

      # Все остальные счета будут применять частоту обновления по умолчанию

    # Лицевые счета, в силу отсутствия явно описанной частоты обновления,
    # будут применять частоту обновления по умолчанию.

Настройка имён объектов — name_format

На данный момент именование объектов происходит используя метод str.format(...) языка Python. Изменение следующих параметров влияет на ID создаваемых объектов и их имена.

Пример 1: Задание форматов для каждого класса отдельно

mosenergosbyt:
  ...
  name_format:
      # Произвольный формат для лицевых счетов
      accounts: 'Мой супер {code} лицевой счёт' 
    
      # Произвольный формат для счётчиков
      meters: 'Счётчик {code} жахает'
    
      # Произвольный формат для квитанций
      invoices: 'За {code} платим много!'

Пример 2: Задание форматов для всех классов одновременно

mosenergosbyt:
  ...
  name_format: 'Entity {type} - {code}'

Пример 3: Задание форматов смешанным образом, и для конкретных объектов

mosenergosbyt:
  ...
  name_format:
    meters:
      # Формат для счётчика с номером "1254123123"
      "1254123123": 'Cчётчик домашний'
      
      # Формат по умолчанию для остальных счётчиков
      default: 'Счётчик обычный {code}'

    invoices:
      # Формат для счёта с номером "123123123-123-123"
      "123123123-123-123": 'Счёт для меня'

      # Все остальные счета будут применять форматирование по умолчанию

    # Лицевые счета, в силу отсутствия явно описанного формата,
    # будут применять форматирование по умолчанию.

Использование другого "браузера" (UA) в запросах

По умолчанию модуль fake_useragent (ссылка) пробует создать уникальный заголовок User-Agent для использования на протяжении всего существования объекта работы с API. Если желаемо указание статичного заголовка, это возможно используя пример ниже:

mosenergosbyt:
  ...
  # Произвольный User-Agent
  user_agent: 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.2 (KHTML, like Gecko) Chrome/22.0.1216.0 Safari/537.2'
  
  # Тот же самый User-Agent, но в несколько строк
  user_agent: >
    Mozilla/5.0 (Windows NT 6.1)
    AppleWebKit/537.2 (KHTML, like Gecko)
    Chrome/22.0.1216.0
    Safari/537.2