Đồng hồ đo điện năng MQTT cho Home Assistant: Thiết lập YAML thủ công

Cấu hình thủ công đồng hồ đo điện năng MQTT trong Home Assistant

Một đồng hồ đo điện năng MQTT có thể công bố điện áp, dòng điện, công suất tác dụng và điện năng đã tiêu thụ/đã phát lên một broker trong mạng nội bộ của bạn. Home Assistant đăng ký dữ liệu đó và chuyển các giá trị JSON thành các thực thể cảm biến (sensor entity) có thể dùng trong dashboard, automation và Energy Dashboard.

Hướng dẫn này giải thích phương pháp MQTT thủ công cho các đồng hồ đo điện năng IAMMETER:

1. cấu hình MQTT broker trong WebUI của đồng hồ;
2. kết nối Home Assistant với cùng broker đó;
3. khai báo các cảm biến MQTT cần thiết trong YAML;
4. thêm điện năng đã tiêu thụ và đã phát vào Energy Dashboard.

MQTT thủ công cho bạn toàn quyền kiểm soát tên thực thể, topic, template và metadata. Nếu bạn muốn Home Assistant tự động tạo thiết bị và thực thể, hãy dùng MQTT Discovery thay thế.

MQTT thủ công và MQTT Discovery là hai phương pháp khác nhau

Cả hai phương pháp đều dùng MQTT broker, nhưng cách thiết lập trong Home Assistant thì khác nhau.

Trong hướng dẫn này, hãy để HA MQTT Discovery ở trạng thái tắt trong WebUI của đồng hồ. Công tắc đó chỉ cần thiết khi bạn muốn Home Assistant tự động phát hiện thiết bị.

Những gì bạn cần

• một đồng hồ đo điện năng IAMMETER với firmware hiện hành;
• một MQTT broker mà cả đồng hồ và Home Assistant đều truy cập được;
• địa chỉ, cổng, tên người dùng và mật khẩu của broker;
• số sê-ri của đồng hồ;
• quyền truy cập vào cấu hình YAML của Home Assistant.

Broker có thể chạy trên cùng máy với Home Assistant, trong add-on Mosquitto broker, trên một máy chủ LAN khác hoặc trên một máy chủ từ xa. Hãy dùng broker nội bộ nếu bạn muốn toàn bộ đường truyền dữ liệu nằm trong mạng LAN.

Tất cả các đồng hồ IAMMETER hiện hành đều hỗ trợ MQTT thủ công. Các model một pha, hai kênh và ba pha công bố cấu trúc mảng JSON khác nhau, vì vậy template giá trị phải khớp với payload thực tế.

Bước 1: Cấu hình MQTT broker trong WebUI của đồng hồ

Mở WebUI nội bộ của đồng hồ và vào Settings. Cấu hình:

Lưu các cài đặt và để đồng hồ kết nối lại.

WebUI của firmware hiện hành hỗ trợ trực tiếp các cài đặt broker này. Bạn không cần cấu hình tên người dùng và mật khẩu thông qua quy trình API nội bộ trước đây.

Để xem hướng dẫn cấu hình đầy đủ phía đồng hồ và các bước dành cho firmware cũ, hãy đọc công bố dữ liệu IAMMETER lên MQTT broker.

Chế độ MQTT và IAMMETER Cloud

Khi Run Mode của đồng hồ được đổi sang MQTT, đồng hồ sẽ công bố dữ liệu đo lên broker của bạn thay vì tải lên IAMMETER Cloud. Vì vậy, MQTT thủ công và IAMMETER Cloud không thể chạy đồng thời trên cùng một đồng hồ.

Nếu bạn cần dùng Home Assistant và IAMMETER Cloud cùng lúc, hãy dùng tích hợp HTTP nội bộ hoặc Modbus TCP thay thế. So sánh các phương pháp hiện có trong hướng dẫn tích hợp đồng hồ đo điện năng với Home Assistant.

Bước 2: Kiểm tra MQTT topic và payload

IAMMETER công bố dữ liệu đo theo thời gian thực tới:

device/{SN}/realtime

Thay {SN} bằng số sê-ri của đồng hồ. Ví dụ:

device/80123456/realtime

Trước khi cấu hình cảm biến Home Assistant, hãy đăng ký topic bằng một MQTT client và xác nhận rằng các bản tin đang đến. Điều này giúp tránh việc xử lý lỗi YAML bị lẫn với các vấn đề về broker, thông tin đăng nhập, tường lửa hoặc topic.

JSON của đồng hồ một pha

Đồng hồ một pha dùng mảng Data. Năm giá trị đầu tiên là:

Ví dụ:

{
  "method": "uploadsn",
  "SN": "12345678",
  "Data": [228.91, 1.61, 225, 15066.47, 0]
}

JSON của đồng hồ nhiều kênh và ba pha

Đồng hồ nhiều kênh và ba pha dùng mảng Datas. Mỗi mảng lồng nhau đại diện cho một pha hoặc một kênh đo:

Datas[0] → pha/kênh A
Datas[1] → pha/kênh B
Datas[2] → pha/kênh C, nếu có

Trong mỗi mảng pha/kênh, các vị trí phổ biến là:

Luôn kiểm tra bản tin MQTT thực tế từ model và firmware của bạn trước khi sao chép template. Xem định nghĩa đầy đủ dữ liệu JSON của IAMMETER.

Bước 3: Kết nối Home Assistant với broker

Trong Home Assistant:

1. Vào Settings → Devices & services.
2. Chọn Add integration.
3. Tìm MQTT.
4. Nhập đúng địa chỉ, cổng, tên người dùng và mật khẩu của broker mà đồng hồ đang dùng.
5. Xác nhận rằng tích hợp MQTT kết nối thành công.

Nếu Home Assistant đã dùng broker này, đừng thêm một tích hợp MQTT trùng lặp. Các cảm biến khai báo thủ công sẽ dùng kết nối broker sẵn có.

Bước 4: Thêm cảm biến MQTT thủ công trong YAML

Các ví dụ dưới đây dùng cấu trúc cấu hình mqtt: sensor: hiện hành của Home Assistant. Hãy thay số sê-ri trong mọi state_topic.

YAML cho đồng hồ đo điện năng một pha

mqtt:
  sensor:
    - name: "IAMMETER Voltage"
      unique_id: "iammeter_12345678_voltage"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[0] | float(0) }}"
      unit_of_measurement: "V"
      device_class: voltage
      state_class: measurement

    - name: "IAMMETER Current"
      unique_id: "iammeter_12345678_current"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[1] | float(0) }}"
      unit_of_measurement: "A"
      device_class: current
      state_class: measurement

    - name: "IAMMETER Active Power"
      unique_id: "iammeter_12345678_active_power"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[2] | float(0) }}"
      unit_of_measurement: "W"
      device_class: power
      state_class: measurement

    - name: "IAMMETER Imported Energy"
      unique_id: "iammeter_12345678_import_energy"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[3] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

    - name: "IAMMETER Exported Energy"
      unique_id: "iammeter_12345678_export_energy"
      state_topic: "device/12345678/realtime"
      value_template: "{{ value_json.Data[4] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

unique_id cho phép Home Assistant quản lý cài đặt thực thể trong giao diện. Hãy giữ mọi ID duy nhất và ổn định. Đừng thay đổi ID chỉ để đổi tên thực thể hiển thị.

YAML cho đồng hồ đo điện năng ba pha

Ví dụ sau tạo các thực thể cho pha A. Hãy sao chép khối này cho pha B và C, đổi Datas[0] thành Datas[1] và Datas[2], đồng thời dùng tên và unique_id riêng biệt.

mqtt:
  sensor:
    - name: "IAMMETER Voltage A"
      unique_id: "iammeter_80123456_voltage_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][0] | float(0) }}"
      unit_of_measurement: "V"
      device_class: voltage
      state_class: measurement

    - name: "IAMMETER Current A"
      unique_id: "iammeter_80123456_current_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][1] | float(0) }}"
      unit_of_measurement: "A"
      device_class: current
      state_class: measurement

    - name: "IAMMETER Active Power A"
      unique_id: "iammeter_80123456_active_power_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][2] | float(0) }}"
      unit_of_measurement: "W"
      device_class: power
      state_class: measurement

    - name: "IAMMETER Imported Energy A"
      unique_id: "iammeter_80123456_import_energy_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][3] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

    - name: "IAMMETER Exported Energy A"
      unique_id: "iammeter_80123456_export_energy_a"
      state_topic: "device/80123456/realtime"
      value_template: "{{ value_json.Datas[0][4] | float(0) }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing

Với WEM2067 và các model nhiều kênh khác, chỉ tạo số khối kênh tương ứng với payload Datas thực tế.

Tránh hai khối mqtt: cấp cao nhất

Nếu configuration.yaml đã có một mục mqtt:, hãy thêm các cảm biến vào mục sẵn có. YAML không thể chứa an toàn hai khóa cấp cao nhất cùng tên.

Với cấu hình lớn, bạn có thể giữ các cảm biến MQTT trong một tệp được include, nhưng phải tuân theo cấu trúc include và quy tắc thụt lề của Home Assistant.

Bước 5: Kiểm tra cấu hình và nạp các cảm biến

Sau khi lưu YAML:

1. chạy kiểm tra cấu hình của Home Assistant;
2. sửa mọi lỗi về YAML, thụt lề hoặc template;
3. khởi động lại Home Assistant nếu cần;
4. mở Developer tools → States;
5. xác nhận rằng mỗi thực thể MQTT có giá trị, đơn vị, device class và state class hợp lý.

Giá trị của thực thể sẽ thay đổi sau khi có bản tin mới đến trên device/{SN}/realtime.

Bước 6: Thêm điện năng đã tiêu thụ và đã phát vào Energy Dashboard

Energy Dashboard của Home Assistant yêu cầu các thực thể điện năng tích lũy. Các ví dụ YAML dùng:

unit_of_measurement: "kWh"
device_class: energy
state_class: total_increasing

Vào Settings → Dashboards → Energy và chọn:

• IAMMETER Imported Energy cho điện năng tiêu thụ từ lưới;
• IAMMETER Exported Energy cho điện năng phát lên lưới.

Với đồng hồ ba pha, hãy chọn cấu trúc thực thể phù hợp với cách lắp đặt và thiết kế dashboard của Home Assistant. Bạn có thể hiển thị riêng điện năng từng pha hoặc tạo một thực thể tổng phù hợp, nhưng đừng cộng các giá trị lại với nhau khi chưa xác nhận cách đồng hồ báo cáo điện năng từng pha và điện năng thuần cho chế độ đấu dây đã chọn.

Đừng chọn thực thể công suất tác dụng đo bằng watt vào trường điện năng của Energy Dashboard. Công suất là tốc độ tức thời; dashboard yêu cầu giá trị kWh tích lũy.

Chọn chu kỳ công bố MQTT

Firmware IAMMETER hiện hành hỗ trợ chu kỳ công bố MQTT ngắn nhất là 2 giây. Chu kỳ ngắn nhất không phải lúc nào cũng là cài đặt tốt nhất.

Gợi ý để bắt đầu:

Hãy cân nhắc năng lực của broker, mức tăng của recorder trong Home Assistant, độ ổn định của mạng và số lượng thực thể. Một bản tin chứa nhiều giá trị pha có thể cập nhật nhiều cảm biến Home Assistant cùng lúc.

Các model IAMMETER được hỗ trợ

Tất cả đồng hồ đo điện năng IAMMETER hiện hành đều hỗ trợ MQTT thủ công. Khác biệt chính của chúng trong Home Assistant là cấu trúc payload và số kênh đo.

WEM3046T và WEM3046TE đo đầu ra thứ cấp 5 A của các CT ngoài. Hãy áp đúng tỷ số CT để có được giá trị phía sơ cấp. Đây là đặc điểm của hệ thống đo, không phải hạn chế của MQTT hay Home Assistant.

Xử lý sự cố

Không có bản tin MQTT nào đến

• Kiểm tra địa chỉ và cổng broker trong WebUI của đồng hồ.
• Xác nhận tên người dùng và mật khẩu.
• Kiểm tra log của broker để tìm lỗi xác thực hoặc kết nối.
• Xác nhận rằng đồng hồ có thể đến được broker qua các quy tắc tường lửa hoặc VLAN.
• Đăng ký topic device/{SN}/realtime bằng một MQTT client độc lập.

Bản tin đến nhưng các thực thể Home Assistant không khả dụng

• Xác nhận rằng Home Assistant đã kết nối với cùng broker.
• Kiểm tra chính xác topic và số sê-ri.
• So sánh Data với Datas theo payload thực tế.
• Kiểm tra thụt lề YAML và template.
• Kiểm tra log của Home Assistant sau khi reload hoặc khởi động lại.

Một số thực thể hiển thị 0 hoặc sai đại lượng đo

• Đừng sao chép template Data của đồng hồ một pha cho payload Datas.
• Kiểm tra vị trí trong mảng theo định nghĩa JSON.
• Xác nhận chỉ số pha/kênh.
• Với WEM3046T/WEM3046TE, xác nhận tỷ số CT ngoài.

Không thấy các thực thể điện năng trong Energy Dashboard

Xác nhận cả ba trường:

unit_of_measurement: "kWh"
device_class: energy
state_class: total_increasing

Đồng thời xác nhận rằng thực thể đã nhận dữ liệu số hợp lệ và xuất hiện trong Developer tools → States.

Xuất hiện thiết bị hoặc cảm biến trùng lặp

MQTT thủ công và MQTT Discovery có thể tạo ra các thực thể riêng biệt từ cùng một đồng hồ. Nếu bạn đang dùng phương pháp YAML, hãy giữ HA MQTT Discovery ở trạng thái tắt trừ khi bạn thực sự muốn cả hai bộ thực thể và đã dự kiến tên thực thể duy nhất.

Hướng dẫn liên quan

• Công bố dữ liệu IAMMETER lên MQTT broker của bạn
• Dùng MQTT Discovery thay cho YAML
• So sánh tất cả phương pháp tích hợp IAMMETER–Home Assistant
• Định nghĩa dữ liệu JSON của IAMMETER
• Nâng cấp firmware IAMMETER

Cập nhật: 19 tháng 7, 2026.