API Lịch sử Năng lượng Cục bộ cho các chỉ số kWh

title: API Lịch sử Năng lượng Cục bộ cho các chỉ số kWh

abstract: Đọc lịch sử kWh nửa giờ ngay tại thiết bị để phân tích ngoại tuyến.

language: vi

author: Jessica

Giới thiệu

Với những người dùng tự xây dựng bảng điều khiển, hệ thống tự động hóa hoặc công cụ phân tích ngoại tuyến, dữ liệu năng lượng thực tế sẽ hữu ích hơn khi được cung cấp ở một khoảng thời gian ổn định. Một chỉ số công suất tức thời chỉ cho biết điều gì đang diễn ra ngay lúc này, nhưng lịch sử kWh nửa giờ giúp người dùng hiểu được năng lượng nhập và xuất thay đổi như thế nào theo thời gian.

Bắt đầu từ phiên bản firmware i.91.063TS8.bin, phát hành ngày 2 tháng 6 năm 2026, IAMMETER hỗ trợ một API cục bộ mới: GET /api/energyhistory. API này trả về các chỉ số kWh được lưu đệm cục bộ, lấy mẫu quanh các mốc nửa giờ theo UTC, giúp việc phân tích mức tiêu thụ năng lượng gần đây trở nên dễ dàng hơn mà không chỉ phụ thuộc vào lịch sử trên cloud.

Điều này đặc biệt hữu ích cho giám sát năng lượng mặt trời, giám sát năng lượng hộ gia đình và các quy trình quản lý năng lượng tùy chỉnh, khi người dùng muốn so sánh dữ liệu năng lượng nhập, xuất và theo từng pha. IAMMETER không chỉ là một thiết bị giám sát; mục đích của việc thu thập dữ liệu này là giúp người dùng tối ưu hóa việc sử dụng năng lượng, nâng cao mức tự tiêu thụ điện mặt trời và giảm hóa đơn tiền điện.

API Lịch sử Năng lượng cung cấp những gì

Endpoint mới là:

GET /api/energyhistory

Nó trả về các chỉ số năng lượng theo đơn vị kWh, được lấy mẫu quanh các mốc nửa giờ UTC sau:

00:00
00:30
01:00
01:30
v.v.

Firmware lưu tối đa 96 bản ghi, tương đương 48 giờ lịch sử với khoảng thời gian 30 phút. Các bản ghi được lưu trong RAM của module Wi-Fi, vì vậy chúng sẽ mất sau khi thiết bị khởi động lại.

Một phản hồi điển hình bao gồm:

utc: dấu thời gian UTC hiện tại của module
timeSynced: module đã có thời gian UTC hợp lệ hay chưa
interval: khoảng thời gian lấy mẫu, hiện là 1800 giây
count: số bản ghi lịch sử hiện có
order: hiện là newest_first
unit: hiện là kWh
channels: tên các kênh tương ứng với từng giá trị
Datas: các bản ghi lịch sử nửa giờ

Mỗi mục trong Datas bao gồm một dấu thời gian UTC và một mảng các giá trị kWh. Các giá trị tuân theo đúng thứ tự của mảng channels.

Vì sao lịch sử kWh nửa giờ lại quan trọng

Dữ liệu năng lượng nửa giờ rất thiết thực vì nó mang lại cái nhìn cô đọng nhưng có ý nghĩa về hành vi sử dụng năng lượng. Thay vì lưu từng điểm dữ liệu thời gian thực, người dùng có thể phân tích các giá trị năng lượng nhập và xuất tích lũy theo những khung thời gian cố định.

Ví dụ, người dùng có thể dùng dữ liệu cục bộ để:

Xem lại năng lượng nhập và xuất gần đây mà không cần chờ báo cáo từ cloud.
Xuất 48 giờ chỉ số kWh mới nhất ra cơ sở dữ liệu cục bộ hoặc tệp CSV.
So sánh mô hình xuất điện mặt trời với mức tiêu thụ của hộ gia đình.
Kiểm tra xem một chiến lược tự động hóa có làm thay đổi việc sử dụng điện trong những khoảng thời gian cụ thể hay không.
Xây dựng bảng điều khiển cục bộ cho lịch sử năng lượng gần đây.

Để biết thêm các tình huống giám sát năng lượng mặt trời tổng quát, xem Giải pháp Giám sát Năng lượng Mặt trời của IAMMETER. Để giám sát điện năng hộ gia đình, xem Giải pháp Giám sát Năng lượng Hộ gia đình của IAMMETER.

Các kiểu bố trí kênh được hỗ trợ

Trường channels cho ứng dụng khách biết cách diễn giải các giá trị trong mỗi bản ghi lịch sử. Các cấu hình đồng hồ khác nhau trả về bố trí kênh khác nhau.

Một pha

["imp", "exp"]

Hai pha (split phase)

["a_imp", "a_exp", "b_imp", "b_exp"]

Ba pha

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"]

Ba pha có bật đo đếm thuần (net metering)

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp", "nem_imp", "nem_exp"]

Vì tên kênh được trả về trong phản hồi, phần mềm tùy chỉnh nên đọc mảng channels trước rồi ánh xạ từng giá trị trong Datas[].values cho phù hợp.

Ví dụ giá trị trả về nguyên bản của API

Hai ví dụ sau minh họa giá trị trả về nguyên bản của API cho một phản hồi rỗng và một phản hồi có dữ liệu.

Ví dụ phản hồi rỗng

Sau khi thiết bị khởi động, mảng lịch sử có thể rỗng cho đến khi có thời gian UTC hợp lệ và các khung dữ liệu đồng hồ hợp lệ. Trong trường hợp này, API có thể trả về count: 0 và mảng Datas rỗng.

{
  "utc": 1780023600,
  "timeSynced": 1,
  "interval": 1800,
  "count": 0,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": []
}

Phản hồi này là bình thường sau khi khởi động. Bảng điều khiển hoặc script cục bộ nên xử lý trạng thái này và chờ các mẫu nửa giờ mới.

Ví dụ phản hồi có dữ liệu

Ví dụ sau hiển thị hai bản ghi nửa giờ từ một đồng hồ ba pha. Phản hồi được sắp xếp từ mới nhất đến cũ nhất.

{
  "utc": 1780023700,
  "timeSynced": 1,
  "interval": 1800,
  "count": 2,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": [
    {
      "utc": 1780023600,
      "values": [11.337, 11.201, 11.039, 10.908, 10.975, 10.846]
    },
    {
      "utc": 1780021800,
      "values": [11.330, 11.198, 11.030, 10.900, 10.970, 10.840]
    }
  ]
}

Trong bản ghi mới nhất, a_imp là 11.337 kWh, a_exp là 11.201 kWh, v.v. Ý nghĩa của từng giá trị được xác định bởi mảng channels.

Sử dụng các giá trị trả về trong phần mềm

Các ví dụ giá trị trả về nguyên bản ở trên đã đủ để xây dựng logic phân tích cục bộ đơn giản. Điểm mấu chốt là đọc channels trước, sau đó áp dụng thứ tự đó cho từng mục trong Datas.

Ánh xạ `channels` sang `values`

Khi xây dựng phần mềm quanh API này, hãy tránh việc cố định cứng vị trí trừ khi cấu hình đồng hồ là cố định. Cách an toàn hơn là chuyển danh sách kênh và mảng giá trị thành một đối tượng có tên.

const response = await fetch("http://<meter-ip>/api/energyhistory").then((res) => res.json());
const latest = response.Datas[0];

const latestByChannel = Object.fromEntries(
  response.channels.map((name, index) => [name, latest.values[index]])
);

console.log(latest.utc, latestByChannel);

Với phản hồi ba pha mẫu ở trên, latestByChannel sẽ chứa:

{
  "a_imp": 11.337,
  "a_exp": 11.201,
  "b_imp": 11.039,
  "b_exp": 10.908,
  "c_imp": 10.975,
  "c_exp": 10.846
}

Điều này giúp dữ liệu dễ lưu trữ, hiển thị hoặc xuất sang công cụ phân tích cục bộ hơn.

Tính mức thay đổi kWh trong nửa giờ

Nếu bạn dùng các giá trị kWh trả về như những chỉ số năng lượng tích lũy, mức thay đổi giữa hai bản ghi liền kề có thể được tính bằng cách lấy giá trị mới hơn trừ đi giá trị cũ hơn của cùng một kênh.

Dùng ví dụ ba pha ở trên:

a_imp change = 11.337 - 11.330 = 0.007 kWh
a_exp change = 11.201 - 11.198 = 0.003 kWh
b_imp change = 11.039 - 11.030 = 0.009 kWh
b_exp change = 10.908 - 10.900 = 0.008 kWh

Cách tính này có thể giúp người dùng xây dựng báo cáo nhập/xuất gần đây, so sánh mức thay đổi năng lượng theo từng pha, hoặc kiểm tra lượng năng lượng được nhập hay xuất trong một khung nửa giờ cụ thể.

Hành vi lấy mẫu quan trọng

Lịch sử năng lượng được tạo cục bộ bởi module Wi-Fi. Hành vi lấy mẫu rất quan trọng khi xây dựng các tích hợp hoặc công cụ phân tích:

Việc lấy mẫu được điều khiển bởi các khung dữ liệu đồng hồ UART hợp lệ.
Module lưu mẫu gần nhất với mỗi mốc nửa giờ UTC.
Thời gian UTC phải hợp lệ trước khi các bản ghi lịch sử được lưu.
Nếu timeSynced là 0, không có mẫu lịch sử mới nào được ghi lại.
Sau khi khởi động, Datas có thể rỗng cho đến khi thu được đủ số mẫu hợp lệ.
Bộ nhớ hiện tại là RAM, vì vậy API này dành cho lịch sử cục bộ gần đây, không phải lưu trữ dài hạn.

Điều này khiến API phù hợp cho việc polling cục bộ, phân tích ngắn hạn và kiểm thử tích hợp. Đối với báo cáo năng lượng dài hạn, người dùng vẫn nên duy trì một nguồn dữ liệu lâu dài, chẳng hạn như dữ liệu trên cloud của IAMMETER hoặc cơ sở dữ liệu riêng.

Ý tưởng tích hợp ví dụ

Các nhà phát triển và người dùng nâng cao có thể dùng /api/energyhistory như một nguồn dữ liệu cục bộ đơn giản cho lịch sử kWh gần đây.

Một cách làm phổ biến là định kỳ polling endpoint, đọc danh sách channels và lưu mọi bản ghi Datas mới vào cơ sở dữ liệu cục bộ. Điều này có thể hỗ trợ bảng điều khiển cục bộ, báo cáo tùy chỉnh hoặc script phân tích ngoại tuyến.

Một tình huống hữu ích khác là phân tích mức tự tiêu thụ điện mặt trời. Bằng cách so sánh các giá trị kWh nhập và xuất theo từng khung nửa giờ, người dùng có thể hiểu rõ hơn khi nào phụ tải trong nhà tiêu thụ điện mặt trời tại chỗ và khi nào năng lượng dư thừa được xuất lên lưới. Điều này hỗ trợ các quyết định tự động hóa tốt hơn, chẳng hạn như dịch chuyển các phụ tải linh hoạt sang những khoảng thời gian có sản lượng điện mặt trời cao hơn.

Nếu bạn đang xây dựng các tích hợp cục bộ, hãy xem thêm Local API, Modbus/TCP và MQTT và IAMMETER Local API Explorer.

Điều này phù hợp thế nào với quản lý năng lượng

Giá trị của một API lịch sử năng lượng không chỉ nằm ở việc nó cung cấp nhiều dữ liệu hơn. Điểm mấu chốt là người dùng có thể làm gì với dữ liệu đó.

Với lịch sử kWh nửa giờ, người dùng có thể phân tích năng lượng điện nhập và xuất gần đây, nhận diện các mô hình sử dụng và đánh giá liệu các chiến lược điện mặt trời hay điều khiển phụ tải có thực sự hiệu quả hay không. Điều này hướng tới mục tiêu rộng hơn của IAMMETER: biến dữ liệu giám sát năng lượng thành những quyết định thiết thực giúp nâng cao hiệu quả sử dụng năng lượng và giảm hóa đơn tiền điện.

Với những người dùng kết hợp IAMMETER với các nền tảng tự động hóa, lịch sử năng lượng cục bộ cũng có thể là một lớp dữ liệu thuận tiện để kiểm thử và xác thực logic điều khiển. Ví dụ, người dùng Home Assistant tối ưu hóa việc sử dụng năng lượng mặt trời dư thừa có thể xem lại các thay đổi kWh gần đây song song với hành vi tự động hóa. Xem Tự động hóa Năng lượng Mặt trời với Home Assistant và IAMMETER để biết một tình huống sử dụng liên quan.

Câu hỏi thường gặp

API này có thể thay thế lịch sử năng lượng dài hạn không?

Không. API lưu tối đa 96 bản ghi, tức 48 giờ dữ liệu nửa giờ, trong RAM. Nó được thiết kế cho lịch sử cục bộ gần đây. Dữ liệu sẽ mất sau khi khởi động lại.

Vì sao `Datas` rỗng sau khi khởi động?

Sau khi khởi động, module cần thời gian UTC hợp lệ và các khung dữ liệu đồng hồ hợp lệ trước khi có thể ghi các mẫu lịch sử. Cho đến khi thu được đủ số mẫu hợp lệ, API có thể trả về mảng Datas rỗng.

Dấu thời gian có dựa trên giờ địa phương không?

Không. Các khung lấy mẫu được căn theo các mốc nửa giờ UTC.

Phần mềm nên diễn giải mảng giá trị như thế nào?

Luôn đọc trường channels trước. Các giá trị trong mỗi mảng Datas[].values tuân theo đúng thứ tự của tên các kênh.