README.en.md

HomeAssistant Mosoblgaz sensors

Provide information about current state of your Mosoblgaz contracts.

This custom component provides Mosoblgaz API polling capabilities to HomeAssistant.

Screenshots

Contract sensor

Meter sensors

Invoice sensor

Installation

Via HACS

1. Open HACS (via Extensions in the sidebar)
2. Add a new custom repository:
   1. Select Integration as custom repository type
   2. Enter custom repository URL: https://github.com/alryaz/hass-mosoblgaz
   3. Press Add button
   4. Wait until repository gets added
   5. You should now see Mosoblgaz (Мособлгаз) integration available in the list of newly added integrations
3. Click Install button to view available versions
4. Install latest version by pressing Install

NOTE: It is not recommended to install master branch. It is intended for development only.

Manually

Clone the repository to a temporary directory, then create a custom_components directory inside your HomeAssistant config folder (if it doesn't exist yet). Then, move Mosoblgaz folder from custom_components folder of the repository to the custom_components folder inside your HomeAssistant configuration.
An example (assuming HomeAssistant configuration is available at /mnt/homeassistant/config) for Unix-based systems is available below:

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

Configuration

Basic configuration example

mosoblgaz:
  username: !secret mosoblgaz_username
  password: !secret mosoblgaz_password

Multiple users

mosoblgaz:
    # First user
  - username: !secret first_mosoblgaz_username
    password: !secret first_mosoblgaz_password

    # Second user
  - username: !secret second_mosoblgaz_username
    password: !secret second_mosoblgaz_password

    # Third user
  - username: !secret third_mosoblgaz_username
    password: !secret third_mosoblgaz_password 

Update only specific contracts

mosoblgaz:
  ...
  contracts:
    # Update every part of the contract (including meters, invoices, and what's to come)
    135112512: True
    
    # Disable contract completely
    5612341421: False

    # Add only account and invoice sensors, but not meters.
    512124124:
      invoices: True
      meters: False

Change update schedule

Default scan_interval: 1 hour

mosoblgaz:
  ...
  # Interval for entity updates
  scan_interval:
    hours: 6

  # ... also possible to set via seconds
  scan_interval: 21600

Custom names for entities

Currently, naming entities supports basic formatting based on python str.format(...) method. Changing these parameters (assuming setup without explicit overrides via Customize interface or alike) will have effect both on entity IDs and friendly names.

Supported replacements are: code, group (only for invoices)

Default contract_name: MOG Contract {code} (ex.: MOG Contract 214651241)
Default meter_name: MOG Meter {code} (ex. MOG Meter 214651241)
Default invoice_name: MES {group} Invoice {code} (ex. MOG Gas Invoice 214651241)

mosoblgaz:
  ...
  # Custom contract name format
  contract_name: 'My super {code} contract'

  # Custom meter name format
  meter_name: 'Ultimate {code} gasification'

  # Custom invoice name format
  invoice_name: 'What {group} costs on {code}'

Invert invoice values

By default, invoice entities display overpayment in positive. If you would like it to show up another way (to display amount left to pay in positive), supply an invert_invoice key with true as value to your configuration:

mosoblgaz:
  ...
  # Invert invoice values
  invert_invoices: true