IAMMETER Đồng hồ đo điện năng Wi-Fi: API cục bộ và giao diện mở

IAMMETER Đồng hồ đo điện năng Wi-Fi: API cục bộ và giao diện mở

Các đồng hồ đo điện năng Wi-Fi của IAMMETER hỗ trợ IAMMETER-Cloud cũng như các tích hợp cục bộ và của bên thứ ba.

Các giao diện khả dụng bao gồm:

• API HTTP cục bộ qua mạng LAN
• Truyền dữ liệu qua MQTT và MQTTS
• Modbus TCP
• Tải dữ liệu lên qua TCP/TLS
• Tải dữ liệu lên qua HTTP/HTTPS
• Vận hành cục bộ độc lập

Những giao diện này cho phép đồng hồ IAMMETER hoạt động như một nguồn dữ liệu mở cho:

• Home Assistant và các nền tảng nhà thông minh khác
• Tự động hóa với Node-RED
• Bảng điều khiển tự lưu trữ
• Hệ thống PLC và SCADA
• Hệ thống quản lý năng lượng (EMS) tùy chỉnh
• Hệ thống quản lý tòa nhà (BMS) tùy chỉnh
• Máy chủ dữ liệu của bên thứ ba

Hướng dẫn này mô tả firmware và WebUI hiện hành trước tiên. Ảnh chụp màn hình và phương thức cấu hình cho các firmware cũ hơn được giữ lại trong phần Legacy ở cuối bài.

Để xem một ứng dụng sẵn sàng sử dụng được xây dựng trên những khả năng này, hãy xem Giám sát năng lượng gia đình, Giám sát năng lượng mặt trời, hoặc giám sát cục bộ không cần Internet.

1) Cập nhật lên firmware mới nhất

Firmware của IAMMETER được cập nhật liên tục. Trước khi cấu hình một tích hợp, hãy kiểm tra bản phát hành hiện tại và khả năng tương thích với từng model:

• Trang phát hành firmware IAMMETER

WebUI của firmware mới nhất hiển thị trực tiếp các tùy chọn cấu hình thường dùng. Các lệnh gọi API cấu hình thủ công được giữ lại ở phần sau của bài viết này chủ yếu hữu ích khi bạn cần duy trì các hệ thống lắp đặt cũ.

2) Chọn chế độ hoạt động trong WebUI hiện hành

Hãy chọn chế độ hoạt động tùy theo nơi đồng hồ cần gửi dữ liệu đến hoặc cách đồng hồ cần vận hành cục bộ.

Chế độ hoạt động điều khiển hành vi tải dữ liệu lên. Khả năng dùng API cục bộ và Modbus TCP vẫn cần được kiểm tra theo model đồng hồ, firmware và tích hợp đã chọn.

3) Vì sao các giao diện mở lại quan trọng

Giao diện mở cho phép người dùng quyết định nơi dữ liệu điện năng được xử lý và lưu trữ.

Những lý do điển hình bao gồm:

• Giữ dữ liệu đo lường trong mạng cục bộ
• Gửi dữ liệu đo đến một máy chủ đã có sẵn
• Kết nối dữ liệu năng lượng với Home Assistant hoặc Node-RED
• Xây dựng bảng điều khiển và cảnh báo tùy chỉnh
• Kết hợp dữ liệu điện năng với biểu giá, năng lượng mặt trời hoặc logic điều khiển phụ tải
• Vận hành tại địa điểm có kết nối Internet hạn chế hoặc không ổn định

Truy cập qua cloud và truy cập cục bộ không nhất thiết loại trừ lẫn nhau. Kiến trúc phù hợp phụ thuộc vào việc dự án cần báo cáo từ IAMMETER-Cloud, một nền tảng cục bộ, một máy chủ bên thứ ba, hay kết hợp cả ba.

4) Đẩy dữ liệu đến máy chủ của bên thứ ba

4.1 TCP và TLS

IAMMETER có thể đẩy dữ liệu đo đến một endpoint TCP hoặc TLS.

Trong WebUI hiện hành:

1. Chọn chế độ hoạt động TCP.
2. Nhập địa chỉ đích.
3. Cấu hình khoảng thời gian tải lên.
4. Lưu cài đặt và kiểm tra dữ liệu tại máy chủ nhận.

Đối với máy chủ TCP, hãy dùng:

{domain-or-ip}:{port}

Ví dụ:

abc.com:12345

Đối với máy chủ TLS, hãy dùng:

tls://{domain-or-ip}:{port}

Ví dụ:

tls://abc.com:12345

Tổng quan về firmware hiện hành ghi rõ khoảng thời gian tải lên tối thiểu là 2 giây. Hãy xác nhận firmware hiện tại và khả năng của máy chủ nhận trước khi chọn khoảng thời gian ngắn.

4.2 MQTT và MQTTS

IAMMETER có thể truyền dữ liệu đo trực tiếp đến broker MQTT thông thường hoặc dùng MQTTS để truyền được mã hóa trên các firmware hỗ trợ.

Trong WebUI hiện hành:

1. Chọn chế độ hoạt động MQTT.
2. Nhập địa chỉ IP hoặc tên miền của broker cùng cổng, theo đúng định dạng MQTT hoặc MQTTS tương ứng.
3. Nhập tên đăng nhập và mật khẩu của broker khi cần xác thực.
4. Cấu hình khoảng thời gian tải lên.
5. Lưu và kiểm tra rằng các bản tin đã đến broker.

Với MQTT thông thường, hãy nhập địa chỉ và cổng của broker mà không có tiền tố mqtt://:

192.168.11.163:1883

Với MQTTS, hãy thêm tiền tố mqtts://:

mqtts://{mqtt-broker-address}:{port}

Ví dụ:

mqtts://broker.example.com:8883

Tính năng MQTTS được mô tả trong bản cập nhật firmware tháng 11 năm 2025 có những hạn chế hiện tại sau:

• Hỗ trợ TLS 1.2 và các phiên bản thấp hơn.
• Không hỗ trợ tải lên chứng chỉ CA tùy chỉnh.
• Không hỗ trợ xác minh tên máy chủ.
• Không hỗ trợ chứng chỉ phía máy khách cho xác thực TLS lẫn nhau (mutual TLS).

Những hạn chế này rất quan trọng khi chọn broker và đánh giá yêu cầu bảo mật của hệ thống triển khai.

Tổng quan về firmware hiện hành ghi rõ khoảng thời gian tải lên tối thiểu là 2 giây.

Home Assistant MQTT Discovery là một chức năng khám phá bổ sung dành cho Home Assistant; chức năng này không bắt buộc với mọi tích hợp MQTT. Xem:

• Hướng dẫn tích hợp MQTT với IAMMETER
• MQTT Discovery trong Home Assistant

Thay đổi uploadInterval từ xa qua MQTT/MQTTS

Với firmware được mô tả trong bản cập nhật tháng 11 năm 2025, một đồng hồ đang chạy ở chế độ MQTT sẽ tự động đăng ký nhận (subscribe) topic:

device/{sn}/config

Hãy truyền JSON sau từ một MQTT client khác để thay đổi khoảng thời gian tải lên từ xa:

{"uploadInterval": 10}

Hãy thay 10 bằng khoảng thời gian mong muốn tính theo giây và thay {sn} bằng số sê-ri của đồng hồ trong topic.

Cách cấu hình MQTT từ xa này khác với phương thức cục bộ /api/uploadinterval cũ được giữ lại trong phần Legacy.

4.3 HTTP và HTTPS

IAMMETER có thể gửi dữ liệu đến một máy chủ HTTP/HTTPS tùy chỉnh.

Trong WebUI hiện hành:

1. Chọn chế độ hoạt động HTTP.
2. Nhập địa chỉ và cổng của máy chủ.
3. Cấu hình khoảng thời gian tải lên.
4. Lưu và kiểm tra các yêu cầu tại máy chủ.

Firmware hiện hành hỗ trợ cả cổng HTTPS mặc định và cổng HTTPS tùy chỉnh.

Hãy dùng một trong các định dạng sau:

• HTTP thông thường không chỉ định cổng: {address} — mặc định dùng cổng 80.
• HTTP thông thường với cổng tùy chỉnh: {address}:{port}.
• HTTPS không chỉ định cổng: https://{address} — mặc định dùng cổng 443.
• HTTPS với cổng tùy chỉnh: https://{address}:{port} — dùng cổng được chỉ định.

Tiền tố https:// dùng để chọn HTTPS. Cổng 443 không còn là cổng duy nhất khả dụng cho HTTPS.

Ví dụ:

api.example.com
api.example.com:8080
https://api.example.com
https://api.example.com:8443

Xem Firmware mới bổ sung MQTTS, cấu hình từ xa và cổng HTTPS tùy chỉnh để biết ghi chú phát hành firmware.

Về cách xử lý payload phía máy chủ, hãy xem thêm Tích hợp IAMMETER với máy chủ của bên thứ ba.

5) Đọc dữ liệu cục bộ qua HTTP

Hãy kết nối đồng hồ với mạng LAN và gửi yêu cầu dữ liệu đến địa chỉ IP cục bộ của đồng hồ. Những yêu cầu này không cần IAMMETER-Cloud.

Kiểm thử API tương tác：Mở IAMMETER Local API Explorer, nhập địa chỉ IP cục bộ của đồng hồ và chọn trang kiểm thử WEM API. Công cụ khám phá theo phong cách Swagger này liệt kê các API cục bộ khả dụng và cho phép bạn gửi yêu cầu kiểm thử trực tiếp từ trình duyệt. Trình duyệt của bạn và đồng hồ IAMMETER phải nằm trong cùng một mạng LAN.

5.1 GET /api/monitorjson

Trả về các giá trị đo điện theo thời gian thực.

Dữ liệu tiêu chuẩn bao gồm các giá trị như:

• Điện áp
• Dòng điện
• Công suất tác dụng
• kWh thuận/nhập
• kWh ngược/xuất
• Tần số
• Hệ số công suất

Ví dụ phản hồi:

{
  "method": "uploadsn",
  "mac": "B0F8933C4F94",
  "version": "i.75.97.9",
  "server": "em",
  "SN": "3E0BAF87",
  "Datas": [
    [220.0, 9.99, 2198, 11.337, 11.201, 49.99, 1.00],
    [222.5, 9.99, 1100, 11.039, 10.908, 49.99, 0.50],
    [263.5, 9.99, 1213, 10.975, 10.846, 49.99, 0.55]
  ]
}

Số lượng mảng đo phụ thuộc vào model đồng hồ và số kênh đo.

Nếu chức năng đo công suất phản kháng được bật trên model/firmware được hỗ trợ, định dạng phản hồi có thể chứa thêm các trường khác. Xem Định dạng dữ liệu đo công suất phản kháng.

5.2 GET /api/monitor

Trả về phản hồi mở rộng theo thời gian thực, bao gồm cả thông tin Wi-Fi như:

• ssid — tên điểm truy cập (access point) đang kết nối
• sig — cường độ tín hiệu Wi-Fi

Hãy dùng endpoint này khi tích hợp cần cả dữ liệu đo điện và trạng thái Wi-Fi cơ bản.

5.3 GET /api/wifidata

Trả về thông tin về firmware, thiết bị và cấu hình mạng.

Ví dụ:

{
  "version": "i.75.97.9",
  "SN": "3E0BAF87",
  "mac": "B0F8933C4F94",
  "type": "PM",
  "ssid": "example-wifi",
  "ip": "192.168.11.62",
  "netmask": "255.255.255.0",
  "gw": "192.168.11.1",
  "dns": "192.168.11.1",
  "dhcp": 1,
  "runMode": "tcp",
  "uploadinterval": 60
}

Không công bố các phản hồi chứa số sê-ri thiết bị, địa chỉ MAC, địa chỉ mạng nội bộ hoặc thông tin Wi-Fi trừ khi các giá trị đó đã được loại bỏ/xử lý ẩn danh.

6) Định dạng JSON giữa các chế độ tải lên

IAMMETER dùng một cấu trúc JSON đo lường cốt lõi nhất quán trên HTTP, TCP, MQTT và API cục bộ. Điều này giúp giảm công sức cần thiết khi một hệ thống nhận hỗ trợ nhiều phương thức truyền tải.

Tuy nhiên, phương thức truyền tải và phần bao (envelope) vẫn có thể ảnh hưởng đến cách hệ thống nhận kết nối, xác thực hoặc đóng gói bản tin. Hãy triển khai hệ thống nhận theo định dạng đã được tài liệu hóa cho chế độ bạn chọn.

• Định nghĩa giá trị JSON của đồng hồ đo điện năng IAMMETER

7) Modbus TCP

Đồng hồ IAMMETER hỗ trợ Modbus TCP để tích hợp trực tiếp trong mạng LAN với các client tương thích.

Các client điển hình bao gồm:

• Home Assistant
• PLC
• Hệ thống SCADA
• Gateway công nghiệp
• Ứng dụng Modbus tùy chỉnh

Tài liệu tham khảo:

• Tổng quan về Modbus TCP của IAMMETER
• Tổng quan tích hợp Home Assistant

Hãy xác nhận model đồng hồ, firmware, định nghĩa thanh ghi, chu kỳ đọc (polling interval) và hành vi của client trước khi triển khai.

8) Các tình huống tích hợp

9) Tóm tắt giao diện hiện hành và tài nguyên

Tài nguyên bổ sung:

• Firmware mới nhất
• Ghi chú firmware về MQTTS và cổng HTTPS tùy chỉnh
• Video hướng dẫn
• Định nghĩa dữ liệu JSON
• Tổng quan Modbus TCP
• Tự phát triển hệ thống của bạn
• Giám sát không cần truy cập Internet

Các API cục bộ và giao thức mở của IAMMETER cho phép bạn bắt đầu với việc giám sát thời gian thực, rồi sau đó bổ sung EMS tùy chỉnh, bảng điều khiển tự lưu trữ hoặc luồng tự động hóa.

10) Các trang firmware Legacy và phương thức cấu hình cũ

Phần nội dung sau chỉ được giữ lại cho những đồng hồ vẫn chạy firmware cũ hơn hoặc cho người dùng đang duy trì một tích hợp đã có. Với hệ thống lắp đặt mới, hãy cập nhật lên firmware mới nhất và sử dụng WebUI hiện hành ở mọi nơi có tùy chọn cần thiết.

10.1 Trang chọn chế độ hoạt động (Legacy)

Firmware cũ hơn dùng trang chọn chế độ hoạt động sau:

Bố cục và tên tùy chọn có thể không khớp với WebUI hiện hành được hiển thị ở phần trước của hướng dẫn này.

10.2 Trang TCP/TLS (Legacy)

Các tích hợp trên firmware cũ hơn có thể tham chiếu trang cấu hình TCP/TLS này và hướng dẫn liên quan:

• Hướng dẫn tích hợp máy chủ bên thứ ba (Legacy)
• Video tải dữ liệu lên máy chủ (Legacy)

10.3 Trang MQTT (Legacy)

Tài liệu MQTT cũ sử dụng giao diện cấu hình sau:

Đối với quy trình hiện hành, hãy dùng hướng dẫn WebUI hiện hành ở phần trước của bài viết này và Hướng dẫn tích hợp MQTT đã được cập nhật.

10.4 Trang HTTP/HTTPS (Legacy)

Firmware cũ hơn dùng trang cấu hình đích HTTP/HTTPS sau:

Hướng dẫn tích hợp cũ được giữ lại tại Tải dữ liệu lên qua HTTP/HTTPS.

Trong quy trình cũ này, HTTPS được gắn với cổng mặc định 443 và không yêu cầu tiền tố https://. Firmware hiện hành thì dùng tiền tố https:// để chọn HTTPS và hỗ trợ cả cổng mặc định 443 lẫn cổng tùy chỉnh được chỉ định rõ ràng.

10.5 Các API cấu hình cũ

Những lệnh gọi API cục bộ sau từng xuất hiện trong các quy trình cấu hình trước đây. Với firmware hiện hành, các cài đặt tương ứng thường nên được cấu hình qua WebUI khi tùy chọn đó khả dụng.

/api/uploadinterval?x=<seconds>

Phương thức cũ để đặt khoảng thời gian tải lên không dùng Cloud.

/api/mqtt

Phương thức cũ để cấu hình thông tin xác thực MQTT.

/api/netmetring

Phương thức cũ để bật hoặc tắt chế độ Net Energy Metering.

• Tài liệu tham khảo về Net Energy Metering

/api/ctcratio

Phương thức cũ để áp dụng hệ số nhân pha C (Phase-C) được tài liệu hóa trong các tình huống chia pha cụ thể hoặc tình huống cân bằng.

• Tài liệu tham khảo về tỷ lệ CTC

/api/reactive

Phương thức cũ để bật hoặc tắt việc đo công suất phản kháng và điện năng phản kháng trên các firmware/model được hỗ trợ.

• Tài liệu tham khảo về công suất phản kháng

/api/ratio — chỉ dành cho WEM3046T

WEM3046T sử dụng CT bên ngoài với đầu ra thứ cấp 5 A. Hướng dẫn cấu hình cũ đặt tỷ lệ CT bằng:

/api/ratio?x={ct_ratio}

Ví dụ:

/api/ratio?x=400

Endpoint này chỉ dành riêng cho WEM3046T và không hợp lệ với các model IAMMETER khác. Với firmware hiện hành, hãy dùng cấu hình WebUI hiện tại của model khi có sẵn.

Nội dung Legacy được giữ lại để tham khảo ngược; các hệ thống lắp đặt hiện nay nên tuân theo WebUI của firmware mới nhất.