Personal household electricity consumption query – based on Docker and Homeassistant

This application can help you connect the electricity bill and electricity consumption data of the State Grid to homeassistant, and realize real-time tracking of household electricity consumption; and can save the daily electricity consumption to the database, and the history can be traced. Specifically, two types of data are provided:

1. Shown as entity in homeassistant:

   Entity entity_id	Description
   sensor.last_electricity_usage	Electricity consumption in the last day, unit KWH, kWh. The attribute contains present_date (the date of querying the power representative)
   sensor.electricity_charge_balance	Prepaid shows the balance of the electricity charge, otherwise it shows the electricity charge that should be paid in the previous month, the unit is yuan
   sensor.yearly_electricity_usage	Total electricity consumption this year, unit KWH, degree.
   sensor.yearly_electricity_charge	Total electricity cost this year, unit yuan

2. Optional, daily power consumption data (mongodb database) for the past 30 days, for example:

1. Scope of application

1. Applicable to users outside the provinces covered by China Southern Power Grid. That is to say, users in Guangdong, Guangxi, Yunnan, Guizhou, Hainan and other provinces can use this application to obtain electricity and electricity bill data.

2. No matter what kind of homeassistant is installed, as long as it can run python, has about 1G hard disk space and 500M running memory, it can be deployed in this warehouse.

This image supports architectures:

• linux/amd64: suitable for Linux systems with x86-64 (amd64) architecture, such as windows computers.
• linux/arm64: suitable for ARMv8-based Linux systems, such as Raspberry Pi and N1 boxes.
• linux/arm/v7: suitable for Linux systems with ARMv7 architecture, such as Wankeyun.
• Other architectures move to the github warehouse to build by themselves.

2. Implementation process

The data of the national grid is obtained through the selenium package of python, and the REST API provided by the homeassistant will use the POST request to update the entity status to the homeassistant.

3. Install

1) Method 1 (recommended): docker image deployment, fast

1. Install docker and homeassistant, Homeassistant minimalist installation method.

2. Create project folder

 mkdir sgcc_electricity
   cd sgcc_electricity

3. Create an environment variable file

vim.env

Write the .env file with reference to the following files

# The following items need to be modified
# State Grid login information
PHONE_NUMBER="xxx" # Change to your own login account
PASSWORD="xxxx" # Change to your own login password

# Database configuration
ENABLE_DATABASE_STORAGE=True # or False does not enable the database to store daily power consumption data.
# The database can fill in the existing mongodb database
MONGO_URL="mongodb://USERNAME:PASSWORD@mongo-for-sgcc:27017/" # Database address Modify USERNAME PASSWORD to be consistent with mongo-for-sgcc and mongo container names
DB_NAME="homeassistant" # database name, the default is homeassistant
# COLLECTION_NAME defaults to electricity_daily_usage_{National Grid user id}, which cannot be modified.

# homeassistant configuration
HASS_URL="http://localhost:8123/" # Change your localhost to your homeassistant address

HASS_TOKEN="eyxxxxx" # long term token for homeassistant

# selenium running parameters
JOB_START_TIME="07:00" # Task start time, 24-hour format, for example, "07:00" is executed at 7 am every day, and if the first startup program is later than 7 am, it will be executed immediately .

## Other default parameters
DRIVER_IMPLICITY_WAIT_TIME=60 # Browser default waiting time, seconds.
RETRY_TIMES_LIMIT=5 # login retry times
LOGIN_EXPECTED_TIME=60 # Login timeout time, seconds
RETRY_WAIT_TIME_OFFSET_UNIT=10
FIRST_SLEEP_TIME=10 # Waiting time for the first run, seconds

# log level
LOG_LEVEL="INFO" # For example, "DUBUG" can check the error situation

4. Write docker-compose.yml file

version: "3"

services:
  app:
    env_file:
      - .env
    depends_on:
      -mongo
    image: renhai/sgcc_electricity:latest # The image of the armv7 32 architecture is armv7-latest
    container_name: sgcc_electricity
    networks:
      sgcc_network:
    environment:
      - SET_CONTAINER_TIMEZONE=true
      - CONTAINER_TIMEZONE=Asia/Shanghai
    restart: unless-stopped
    command: python3 main.py

# By default, nearly 30 days of data will be written into the mongo database for easy query
  mongo:
    image: mongo:4.4.18
    restart: always
    container_name: mongo-for-sgcc
    networks:
      sgcc_network:
    environment:
      MONGO_INITDB_ROOT_USERNAME: USERNAME # Change to your own username
      MONGO_INITDB_ROOT_PASSWORD: PASSWORD #Change to your own password
      MONGODB_DATABASE: "homeassistant" # Change to your own database name, which is consistent with the database name in .env
      CONTAINER_TIMEZONE: Asia/Shanghai
    volumes:
      - ./db:/data/db

networks:
   sgcc_network:

5. run

   docker compose up --build
   # Or run in the background
   docker compose up -d --build
   

### 2) Method 2: Build the container locally

1. Clone the repository

   ```bash
   git clone https://github.com/renhaiidea/sgcc_electricity.git
   cd sgcc_electricity

2. Refer to example.env to write the .env file

   cp example.env ./env
   

3. Check the docker-compose file, no modification is required by default

4. run

   docker compose up --build
   # Or run in the background
   docker compose up -d --build
   

3) Method 3, do not install docker, run directly after installing the python environment:

After cloning the warehouse, refer to the Dockerfile command, configure and install the chrome browser and selenium browser driver by yourself, install mongodb, copy the example.env file as the .env file to the scripts folder, and then run main.py file.

4. Configuration and use

1) For the first run, you need to create and fill in the .env file, and fill it in according to the file instructions.

2) (Optional) modify entity

Fill in the configuration file of homeassistant

Since the sensor is created using the REST API method, there is no entity registration, so it cannot be edited in the webui. If necessary, you can add the following configuration under configuration.yaml and restart HA, so that you can edit the corresponding entity in the webUI, so that the entity with the _entity suffix can be modified.

• If you have an account number, refer to the following configuration:

# Example configuration.yaml entry
# There can only be one template in the file
template:
  # Reference document: https://www.home-assistant.io/integrations/template
  - trigger:
      - platform: event
        event_type: "state_changed"
        event_data:
          entity_id: sensor.electricity_charge_balance
    sensor:
      - name: electricity_charge_balance_entity
        unique_id: electricity_charge_balance_entity
        state: "{<!-- -->{ states('sensor.electricity_charge_balance') }}"
        state_class: measurement
        unit_of_measurement: "CNY"
        device_class: monetary
        
  - trigger:
      - platform: event
        event_type: "state_changed"
        event_data:
          entity_id: sensor.last_electricity_usage
    sensor:
      - name: electricity consumption in the last day
        unique_id: last_electricity_usage_entity
        state: "{<!-- -->{ states('sensor.last_electricity_usage') }}"
        attributes:
          present_date: "{<!-- -->{ state_attr('sensor.last_electricity_usage', 'present_date') }}"
          last_updated: "{<!-- -->{ state_attr('sensor.last_electricity_usage', 'last_updated') }}"
        state_class: total
        unit_of_measurement: "kWh"
        device_class: energy
        
  - trigger:
      - platform: event
        event_type: "state_changed"
        event_data:
          entity_id: sensor.yearly_electricity_usage
    sensor:
      - name: yearly_electricity_usage_entity
        unique_id: yearly_electricity_usage_entity
        state: "{<!-- -->{ states('sensor.yearly_electricity_usage') }}"
        state_class: total_increasing
        unit_of_measurement: "kWh"
        device_class: energy

  - trigger:
      - platform: event
        event_type: "state_changed"
        event_data:
          entity_id: sensor.yearly_electricity_charge
    sensor:
      - name: yearly_electricity_charge_entity
        unique_id: yearly_electricity_charge_entity
        state: "{<!-- -->{ states('sensor.yearly_electricity_charge') }}"
        state_class: total_increasing
        unit_of_measurement: "CNY"
        device_class: monetary

• If you have multiple account numbers, refer to the configuration.yaml configuration for each account number.

  **Note: If you have one account number, it is the above entity name in HA;**If you have multiple account numbers, the entity name should be suffixed with “_account number”, for example: sensor.last_electricity_usage_1234567890< /strong>

type: custom: mini-graph-card
entities:
  - entity: sensor.last_electricity_usage_entity
    name: State Grid daily power consumption
    aggregate_func: first
    show_state: true
    show_points: true
group_by: date
hour24: true
hours_to_show: 240

# There can only be one sensor in the file
sensor:
  # Real-time electricity price
  - platform: template #platform name
    sensors: #sensor list
      real_time_electricity_price: #Entity name: only lowercase, underscore
        unique_id: "real_time_electricity_price" #UID (required)
        friendly_name: 'real-time electricity price' #Sensor nickname displayed on the front end (optional)
        unit_of_measurement: "CNY/kWh" #The unit of the sensor value (optional)
        icon_template: mdi:currency-jpy #default icon
        value_template: > #Define a template for obtaining sensor status (required) The following 6 and 22 refer to 6 o'clock and 22 o'clock, "1""2""3" refers to step 123, 6 prices They are the peak and valley prices of the three steps
          {<!-- -->% if now().strftime("%H")| int >= 6 and now().strftime("%H")|int < 22 and states(\ "sensor.current_ladder")=="1" %}
            0.617
          {<!-- -->%elif now().strftime("%H")| int >= 6 and now().strftime("%H")|int < 22 and states(\ "sensor.current_ladder")=="2" %}
            0.677
          {<!-- -->%elif now().strftime("%H")| int >= 6 and now().strftime("%H")|int < 22 and states(\ "sensor.current_ladder")=="3" %}
            0.977
          {<!-- -->% elif states("sensor.current_ladder")=="1" %}
            0.307
          {<!-- -->% elif states("sensor.current_ladder")=="2" %}
            0.337
          {<!-- -->% elif states("sensor.current_ladder")=="3" %}
            0.487
          {<!-- -->% endif %}

# current ladder
  - platform: template
    sensors:
      current_ladder:
        unique_id: "current_ladder"
        friendly_name: 'Current ladder'
        unit_of_measurement: "Level"
        icon_template: mdi:elevation-rise
        value_template: > #Here are the values of the three steps in Shanghai, the second step is 3120, the third step is 4800
          {<!-- -->% if states("sensor.yearly_electricity_usage_entity") | float <= 3120 %}
          1
          {<!-- -->% elif states("sensor.yearly_electricity_usage_entity") | float >3120 and states("sensor.yearly_electricity_usage_entity") | float <= 4800 %}
          2
          {<!-- -->% else %}
          3
          {<!-- -->% endif %}