API Riwayat Energi Lokal untuk Pembacaan kWh

title: API Riwayat Energi Lokal untuk Pembacaan kWh

abstract: Baca riwayat kWh setengah jam secara lokal untuk analisis offline.

language: id

author: Jessica

Pendahuluan

Bagi pengguna yang membangun dashboard, otomatisasi, atau alat analisis offline sendiri, data energi nyata lebih berguna bila tersedia pada interval yang stabil. Satu pembacaan daya real-time hanya menunjukkan apa yang terjadi saat ini, sedangkan riwayat kWh setengah jam membantu pengguna memahami bagaimana impor dan ekspor listrik berubah seiring waktu.

Mulai dari versi firmware i.91.063TS8.bin yang dirilis pada 2 Juni 2026, IAMMETER mendukung API lokal baru: GET /api/energyhistory. API ini mengembalikan pembacaan kWh yang di-cache secara lokal dan disampel di sekitar batas setengah jam UTC, sehingga lebih mudah menganalisis pemakaian energi terbaru tanpa hanya bergantung pada riwayat di sisi cloud.

Ini sangat berguna untuk pemantauan surya, pemantauan energi rumah, dan alur kerja manajemen energi khusus ketika pengguna ingin membandingkan data energi impor, ekspor, dan per fasa. IAMMETER bukan sekadar alat pemantau; tujuan pengumpulan data ini adalah membantu pengguna mengoptimalkan pemakaian energi, meningkatkan konsumsi mandiri (self-consumption) surya, dan menekan tagihan listrik.

Apa yang Disediakan API Riwayat Energi

Endpoint barunya adalah:

GET /api/energyhistory

API ini mengembalikan pembacaan energi dalam kWh, yang disampel di sekitar batas setengah jam UTC berikut:

00:00
00:30
01:00
01:30
dan seterusnya

Firmware menyimpan hingga 96 catatan, setara dengan 48 jam riwayat pada interval 30 menit. Catatan tersebut disimpan di RAM modul Wi-Fi, sehingga hilang setelah perangkat di-restart.

Respons yang umum mencakup:

utc: stempel waktu UTC modul saat ini
timeSynced: apakah modul memiliki waktu UTC yang valid
interval: interval pengambilan sampel, saat ini 1800 detik
count: jumlah catatan riwayat yang tersedia
order: saat ini newest_first
unit: saat ini kWh
channels: nama kanal yang sesuai dengan setiap nilai
Datas: catatan riwayat setengah jam

Setiap item dalam Datas menyertakan stempel waktu UTC dan array nilai kWh. Urutan nilai mengikuti urutan array channels.

Mengapa Riwayat kWh Setengah Jam Penting

Data energi setengah jam bersifat praktis karena memberi pengguna gambaran yang ringkas namun bermakna tentang perilaku energi. Alih-alih menyimpan setiap titik real-time, pengguna dapat menganalisis nilai impor dan ekspor terakumulasi pada slot waktu yang tetap.

Sebagai contoh, pengguna dapat memanfaatkan data lokal untuk:

Meninjau energi impor dan ekspor terbaru tanpa menunggu laporan cloud.
Mengekspor pembacaan kWh 48 jam terakhir ke database lokal atau file CSV.
Membandingkan pola ekspor surya dengan konsumsi rumah tangga.
Memeriksa apakah strategi otomatisasi mengubah pemakaian listrik pada periode tertentu.
Membuat dashboard lokal untuk riwayat energi terbaru.

Untuk skenario pemantauan surya yang lebih luas, lihat Solusi Pemantauan Energi Surya IAMMETER. Untuk pemantauan listrik rumah tangga, lihat Solusi Pemantauan Energi Rumah IAMMETER.

Tata Letak Kanal yang Didukung

Field channels memberi tahu klien cara menafsirkan nilai pada setiap catatan riwayat. Konfigurasi meter yang berbeda mengembalikan tata letak kanal yang berbeda.

Fasa Tunggal

["imp", "exp"]

Split Phase

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

Tiga Fasa

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

Tiga Fasa dengan Net Metering Aktif

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

Karena nama kanal dikembalikan dalam respons, perangkat lunak kustom sebaiknya membaca array channels terlebih dahulu, lalu memetakan setiap nilai di Datas[].values sesuai urutan tersebut.

Contoh Respons API Asli

Dua contoh berikut menunjukkan nilai respons API asli untuk respons kosong dan respons berisi data.

Contoh Respons Kosong

Setelah perangkat menyala, array riwayat bisa kosong sampai tersedia waktu UTC yang valid dan frame meter yang valid. Dalam kasus ini, API dapat mengembalikan count: 0 dan array Datas yang kosong.

{
  "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": []
}

Respons ini normal setelah perangkat menyala. Dashboard atau skrip lokal harus menangani kondisi ini dan menunggu sampel setengah jam berikutnya.

Contoh Respons Berisi Data

Contoh berikut menunjukkan dua catatan setengah jam dari meter tiga fasa. Respons diurutkan dari yang terbaru ke yang terlama.

{
  "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]
    }
  ]
}

Pada catatan terbaru, a_imp bernilai 11.337 kWh, a_exp bernilai 11.201 kWh, dan seterusnya. Arti setiap nilai ditentukan oleh array channels.

Menggunakan Nilai Respons di Perangkat Lunak

Contoh respons asli di atas sudah cukup untuk membangun logika analisis lokal sederhana. Kuncinya adalah membaca channels terlebih dahulu, lalu menerapkan urutan tersebut pada setiap item di Datas.

Memetakan `channels` ke `values`

Saat membangun perangkat lunak di sekitar API ini, hindari hard-code posisi kecuali konfigurasi meter bersifat tetap. Pendekatan yang lebih aman adalah mengubah daftar kanal dan array nilai menjadi objek bernama.

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);

Untuk contoh respons tiga fasa di atas, latestByChannel akan berisi:

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

Ini membuat data lebih mudah disimpan, ditampilkan, atau diekspor ke alat analisis lokal.

Menghitung Perubahan kWh Setengah Jam

Jika Anda menggunakan nilai kWh yang dikembalikan sebagai pembacaan energi terakumulasi, perubahan antara dua catatan yang berdekatan dapat dihitung dengan mengurangkan nilai lama dari nilai baru pada kanal yang sama.

Dengan contoh tiga fasa di atas:

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

Perhitungan semacam ini dapat membantu pengguna membuat laporan impor/ekspor terbaru, membandingkan perubahan energi per fasa, atau memeriksa berapa banyak energi yang diimpor atau diekspor selama slot setengah jam tertentu.

Perilaku Pengambilan Sampel yang Penting

Riwayat energi dihasilkan secara lokal oleh modul Wi-Fi. Perilaku pengambilan sampel ini penting saat membangun integrasi atau alat analisis:

Pengambilan sampel didorong oleh frame meter UART yang valid.
Modul menyimpan sampel yang paling dekat dengan setiap batas setengah jam UTC.
Waktu UTC harus valid sebelum catatan riwayat disimpan.
Jika timeSynced bernilai 0, tidak ada sampel riwayat baru yang dicatat.
Setelah perangkat menyala, Datas bisa kosong sampai cukup banyak sampel valid yang terkumpul.
Penyimpanan saat ini berbasis RAM, sehingga API ini ditujukan untuk riwayat lokal terbaru, bukan penyimpanan jangka panjang.

Ini membuat API cocok untuk polling lokal, analisis jangka pendek, dan pengujian integrasi. Untuk laporan energi jangka panjang, pengguna tetap perlu menyimpan sumber data yang persisten, seperti data cloud IAMMETER atau database milik sendiri.

Contoh Ide Integrasi

Pengembang dan pengguna tingkat lanjut dapat menggunakan /api/energyhistory sebagai sumber data lokal sederhana untuk riwayat kWh terbaru.

Salah satu pendekatan yang umum adalah melakukan polling endpoint secara berkala, membaca daftar channels, lalu menyimpan catatan Datas baru ke database lokal. Ini dapat mendukung dashboard lokal, laporan khusus, atau skrip analisis offline.

Skenario lain yang berguna adalah analisis konsumsi mandiri surya. Dengan membandingkan nilai kWh impor dan ekspor pada slot setengah jam, pengguna dapat lebih memahami kapan beban rumah tangga mengonsumsi pembangkit surya secara lokal dan kapan energi berlebih diekspor. Ini dapat mendukung keputusan otomatisasi yang lebih baik, misalnya menggeser beban fleksibel ke periode dengan hasil surya lebih tinggi.

Jika Anda membangun integrasi lokal, lihat juga API Lokal, Modbus/TCP dan MQTT dan IAMMETER Local API Explorer.

Posisinya dalam Manajemen Energi

Nilai dari API riwayat energi bukan hanya karena menyediakan lebih banyak data. Poin utamanya adalah apa yang dapat dilakukan pengguna dengan data tersebut.

Dengan riwayat kWh setengah jam, pengguna dapat menganalisis impor dan ekspor listrik terbaru, mengidentifikasi pola pemakaian, dan menilai apakah strategi surya atau pengendalian beban benar-benar membantu. Ini mendukung tujuan IAMMETER yang lebih luas: mengubah data pemantauan energi menjadi keputusan praktis yang meningkatkan efisiensi energi dan menekan tagihan listrik.

Bagi pengguna yang menggabungkan IAMMETER dengan platform otomatisasi, riwayat energi lokal juga dapat menjadi lapisan data yang praktis untuk menguji dan memvalidasi logika kontrol. Sebagai contoh, pengguna Home Assistant yang mengoptimalkan pemanfaatan kelebihan surya dapat meninjau perubahan kWh terbaru bersama perilaku otomatisasinya. Lihat Otomatisasi Energi Surya Home Assistant dengan IAMMETER untuk kasus penggunaan terkait.

FAQ

Apakah API ini dapat menggantikan riwayat energi jangka panjang?

Tidak. API ini menyimpan maksimal 96 catatan, atau 48 jam data setengah jam, di RAM. API ini dirancang untuk riwayat lokal terbaru. Data akan hilang setelah perangkat di-restart.

Mengapa `Datas` kosong setelah perangkat menyala?

Setelah perangkat menyala, modul memerlukan waktu UTC yang valid dan frame meter yang valid sebelum sampel riwayat dapat dicatat. Sampai cukup sampel valid terkumpul, API dapat mengembalikan array Datas yang kosong.

Apakah stempel waktunya berdasarkan waktu lokal?

Tidak. Slot pengambilan sampel diselaraskan dengan batas setengah jam UTC.

Bagaimana perangkat lunak seharusnya menafsirkan array values?

Selalu baca field channels terlebih dahulu. Nilai dalam setiap array Datas[].values mengikuti urutan nama kanal yang sama.