trvqhuy / nestup_evn

A simple yet efficient custom component to fetch data from EVN Vietnam for Home Assistant
https://github.com/trvqhuy/nestup_evn
Apache License 2.0
65 stars 29 forks source link
electricity-meter hacs-default hacs-integration home-assistant homeassistant homeassistant-custom-component polling-service

hacs Project Maintenance Code Style

Công cụ theo dõi điện năng tiêu thụ từ EVN Việt Nam dành cho HomeAssistant

English | Tiếng Việt

Từ việc sử dụng các phương thức có sẵn của module AIOHTTP thông qua những giao thức HTTP(S) cơ bản, công cụ cho phép theo dõi dữ liệu điện năng tiêu thụ từ EVN trực tiếp trên UI Home Assistant, hiện tại đã hỗ trợ cho tất cả vùng miền tại Việt Nam cùng với chi nhánh EVN tương ứng (xem tại danh sách phía dưới).

Các tính năng cơ bản

  1. Thiết lập và theo dõi nhiều mã khách hàng cùng một lúc, trên cùng một máy chủ HA.
  2. Cài đặt và chỉnh sửa trực tiếp bằng UI (thông qua HACS), quản lí các thông số điện năng thông qua các thiết bị theo dõi tập trung.
  3. Hỗ trợ cho tất cả chi nhánh EVN toàn quốc (bao gồm 5 tổng công ty và hơn 400 chi nhánh lớn nhỏ).
  4. Tự động xác định máy chủ EVN.
  5. Tương thích với tất cả platform HA: Core, Supervisors, Hass OS.

Các điểm hạn chế

  1. Chưa hoàn toàn hỗ trợ thêm sensor vào Energy.
  2. Chưa hỗ trợ đối tượng khác ngoài các hộ sinh hoạt tiêu thụ điện 2 pha thông thường.
  3. Sensors về tiền điện ngày / tháng chỉ mang tính chất tham khảo, được tính một cách thủ công theo giá bán lẻ bên dưới, vì vậy khả năng sai sốrất cao.
  4. Các thông tin không được cập nhật tức thì từ dữ liệu mới nhất của EVN, mà luôn được cập nhật theo chu kì cố định.

Từ phiên bản v2.1.0, công cụ hỗ trợ theo dõi các thông số sau thông qua các sensors:

  1. Sản lượng ngày mới nhất và ngày trước đó, cùng với sản lượng tháng hiện tại (tạm chốt).
  2. Số tiền được (tạm) tính từ 3 sản lượng phía trên.
  3. Tình trạng hóa đơn nợ và số tiền nợ (nếu có).
  4. Chỉ số mới nhất và chỉ số cũ từ ngày đầu kì (ngày bắt đầu hóa đơn tháng).
  5. Ngày cập nhật dữ liệu mới nhất cùng với ngày đầu kì.

    Xem thêm Ý nghĩa của các sensors phía dưới để hiểu rõ chức năng / hạn chế của từng thông số trên.

Lưu ý trước khi cài đặt

1. Phiên bản Home Assistant: tối thiểu 2022.7.0

2. Công tơ điện EVN

Công cụ chỉ hỗ trợ cho loại công tơ điện tử đo xa ghi theo ngày:

3. Mã khách hàng và tài khoản EVN

Hiện tại tất cả chi nhánh, vùng miền đều cần phải có tài khoản EVN tương ứng với mã khách hàng để sử dụng công cụ.

Tài khoản EVN hợp lệ sẽ bao gồm:

  1. Tên tài khoản / Username (thông thường sẽ là mã khách hàng hoặc số điện thoại)
  2. Mật khẩu / Password.

Mã khách hàng của bạn phải thỏa những điều kiện sau:

  1. Chứa từ 11 tới 13 kí tự.
  2. Bắt đầu bằng chữ 'P'.

Chú ý: Kiểm tra ở bảng phía dưới, liên hệ với TTCSKH (Trung tâm Chăm sóc Khách Hàng) để xin thông tin đăng nhập nếu chưa có:

Chi nhánh EVN Khu vực Đang được hỗ trợ Đăng nhập TTCSKH
EVNHANOI Thủ đô Hà Nội ☑️ Link Link
EVNHCMC Thành phố Hồ Chí Minh ☑️ Link Link
EVNNPC Khu vực miền Bắc Link Link
EVNCPC Khu vực miền Trung ☑️ Link Link
EVNSPC Khu vực miền Nam ☑️ Link Link

Cài đặt

Chú ý: Sử dụng 1 trong những cách phía dưới để cài đặt công cụ vào HA.

Cách 1: Cài đặt thông qua HACS (khuyến nghị).

  1. Tải repository package về máy chủ HA.

HACS > Integrations > ➕ Explore & download repositories > EVN Data Fetcher > Chọn phiên bản mới nhất > Download this repository

  1. Khởi động lại HomeAssistant.
  2. Cài đặt thành công, tiếp theo đến bước Config để hoàn thành.

Cách 2: Cài đặt thủ công thông qua Samba / SFTP

  1. Tải phiên bản mới nhất của công cụ thông qua Github.

  2. Giải nén thư mục custom_components/nestup_evn vào thư mục custom_components trong HomeAssistant của bạn.

    • Thư mục custom_components phụ thuộc vào thư mục cài đặt HomeAssistant của bạn.
    • Thông thường, thư mục cài đặt HomeAssistant sẽ là ~/homeassistant/.
    • Nói cách khác, thư mục cài đặt HomeAssistant là thư mục chứa file configuration.yaml.
    • Sau khi cài đặt đúng, đường dẫn sẽ có dạng:

      └── ...
      └── configuration.yaml
      └── secrets.yaml
      └── custom_components
          └── nestup_evn
              └── __init__.py
              └── sensor.py
              └── nestup_evn.py
              └── ...

      Chú ý: nếu thư mục custom_components không tồn tại, bạn phải tự tạo nó.

Thiết lập và Chỉnh sửa

Cách thiết lập công cụ

1. Tìm công cụ EVN Data Fetcher trong những công cụ đã tải về.

Settings > Devices and Services > Integrations > Add Integrations > Tìm EVN Data Fetcher

2. Điền Mã khách hàng.

Yêu cầu: Mã khách hàng của bạn phải thỏa những điều kiện sau:

3. Điền Tài khoản EVN và chọn Ngày bắt đầu hóa đơn.

Chú ý: ngày bắt đầu hóa đơn là ngày đầu tiên trong hóa đơn điện hàng tháng (xem hóa đơn các kì trước để chắc chắn).

4. Hoàn thành, bây giờ bạn có thể thấy thiết bị theo dõi của mình ở phần Devices.

Home Assistant

Cách tạo Automation thông báo điện năng tiêu thụ mỗi ngày

Lưu ý: thay thế tên thiết bị của bạn (unique_id) vào 5 phần ten_device_cua_ban ở phía dưới.

alias: Thông báo điện năng tiêu thụ mỗi ngày
mode: single

trigger:
# Tùy chỉnh thời gian cố định mỗi ngày để thông báo (ví dụ 8:00 sáng mỗi ngày)
  - platform: time
    at: "08:00:00"

condition:
  - condition: template
    value_template: >-
# Thông thường dữ liệu điện tiêu thụ mới nhất sẽ là của ngày trước đó, 
#   ví dụ hôm nay ngày 09/09/2022 thì dữ liệu mới nhất là của ngày 08/09/2022
        {{ states('sensor.ten_device_cua_ban_to_date') == (now() - timedelta(days=1)).strftime('%d/%m/%Y')}}

# Nếu như ở khu vực của bạn, dữ liệu điện tiêu thụ từ EVN luôn cập nhật trễ hơn, 
#   xin hãy thay bằng template phía dưới, với X là số ngày trễ hơn:
# Ví dụ hôm nay là ngày 09/09/2022, dữ liệu mới nhất là của ngày 06/09/2022, 
#   luôn trễ hơn 3 ngày, thì X = 3.
#       {{ states('sensor.ten_device_cua_ban_to_date') == (now() - timedelta(days=X)).strftime('%d/%m/%Y')}}

action:
# Tùy chình bằng service notify của bạn
  - service: notify.notify
    data:
      title: Điện tiêu thụ @ Saigon Home
      message: >
        Dữ liệu ngày
        {{states('sensor.ten_device_cua_ban_to_date')}}:{{'\n'}} -
        Sản lượng:
        {{states('sensor.ten_device_cua_ban_econ_daily_new')}}
        kWh{{'\n'}} - Thành tiền:
        {{'{0:_.0f}'.format(states('sensor.ten_device_cua_ban_ecost_daily_new')|int).replace('_','.')}} VNĐ

Chỉnh sửa thông số

Hiện tại, sau khi đã thiết lập, các thông số của công cụ chưa thể chỉnh sửa, có thể tính năng này sẽ được cập nhật trong tương lai, hoặc có thể không.

Tuy nhiên, những thông số này "có vẻ như" sẽ không cần phải chỉnh sửa, hiện tại đã được gán mặc định như bên dưới.

1. Ý nghĩa của các sensor được tạo sẵn:

Do thiếu sự đồng bộ về các khái niệm chỉ số điện năng giữa các chi nhánh và tổng công ty EVN, các sensors sẽ được thống nhất như bên dưới:

Để thuận tiện hơn trong việc theo dõi điện tiêu thụ hàng ngày (ví dụ ước lượng số tiền điện mình sử dụng trong ngày). 2 sensors bên dưới chỉ mang tính chất tham khảo, không được lấy trực tiếp từ dữ liệu EVN, mà được tính theo giá bán lẻ bên dưới nên khả năng **sai số là rất cao***

2. Giá bán lẻ điện EVN:

Mặc dù có nhiều loại biểu giá tùy vào mục đích sử dụng điện, nhưng dự án này sẽ mặc định tính giá tiền điện theo biểu giá bán lẻ của nhóm đối tượng Sinh Hoạt.

Truy cập link này để xem biểu giá bán lẻ tiền điện của EVN.

3. Chu kì cập nhật dữ liệu mới từ EVN:

6 tiếng là chu kì mặc định giữa các lần cập nhật dữ liệu điện năng tiêu thụ từ EVN.

Việc cập nhật dữ liệu theo chu kì, không cố định 1 mốc thời gian cụ thể, lí do là:

  • Để các sensors luôn cập nhật được dữ liệu mới nhất từ EVN.
  • Thời điểm cập nhật dữ liệu điện năng của hơn 400 chi nhánh EVN toàn quốc là không cố định.

Dành cho dự án

Xin phép được gửi lời cảm ơn đến:

Không có những người kể trên, repo nestup_evn sẽ không ở đây, trở thành một dự án open-source tới cộng đồng HA Việt Nam.

Lời cuối, tác giả cũng muốn tự cảm ơn bản thân vì đã tạo ra integration này dành cho tất cả mọi người.