Kelompok telemetri

Secara bawaan semua metrik dikirim bersama dalam satu pesan tiap telemetry_interval_ms (10 detik). Dengan puluhan perangkat Modbus, pesan menjadi besar dan banyak nilai yang jarang berubah ikut terkirim. Kelompok telemetri memungkinkan tiap himpunan metrik dikirim dengan jadwal dan ambang sendiri.

Firmware 0.21

Fitur ini ada di firmware 0.21.x dan belum diuji di perangkat. Lihat Status fitur. Tanpa pesan tgroups, perilaku sama persis seperti sebelumnya.

Konsep

• Kelompok: himpunan metrik dengan pengaturan kirim yang sama. Tiap metrik tepat di satu kelompok.
• Snapshot: bila sebuah kelompok jatuh tempo, semua metrik kelompok itu yang punya nilai ikut dikirim, bukan hanya yang berubah, dengan waktu sampel yang sama.
• Satu putaran: semua kelompok yang jatuh tempo digabung dalam satu pesan (satu q); bila melebihi anggaran ukuran, dipecah per kelompok.

Sebuah kelompok terpicu oleh salah satu:

1. berkala: interval_s sejak kirim terakhir (selalu aktif, jadi sekaligus batas diam paling lama);
2. ambang perubahan: salah satu metrik anggota berubah melebihi delta-nya terhadap nilai terakhir yang terkirim (dibatasi min_s);
3. muncul / hilangnya nilai sebuah metrik;
4. on_change: ada metrik boolean yang berubah.

Kelompok bawaan

Kelompok	Isi	Prioritas	Pemicu bawaan
alarm	alarm_level, semua alarm_*	crit	berkala + segera saat berubah. Hanya interval_s yang boleh diatur; tidak bisa dipecah
io	input digital, output, expander_ok, maintenance, keadaan rule (rule_<id>), flag	crit	berkala
temp	suhu DS18B20, temp_ambient, humidity	normal	berkala; ambang dari temp_report_delta_c
power	voltage, current, power_draw, energy, frequency, power_factor (PZEM-004T)	normal	berkala; ambang dari power_report_delta_w
system	uptime, heap_free	low	berkala
src	metrik sumber Modbus yang tidak menyebut group	normal	berkala

Catatan

alarm_level dan semua alarm_* selalu berada dalam satu pesan utuh, supaya server dapat menutup alarm dengan benar. Kelompok alarm tidak dapat dinonaktifkan, tidak punya delta, dan sumber tidak boleh menamai metriknya alarm_*.

Pesan tgroups

Topik m/<workspace>/c/<channel>/<mac>/tgroups (retained, QoS 1); laporan di tgroups/reported; isi tersimpan di tgroups/current (balasan cmd get_tgroups). Pesan mengganti seluruh set.

{
  "tgroups_ver": 3,
  "confirm_s": 60,
  "groups": [
    {"id": "temp",   "interval_s": 60},
    {"id": "system", "interval_s": 300},
    {"id": "rak1",   "interval_s": 30, "min_s": 5, "prio": "normal"},
    {"id": "rak2",   "interval_s": 30, "min_s": 5},
    {"id": "energi", "interval_s": 300, "prio": "low"}
  ]
}

Entri dengan id bawaan mengatur kelompok bawaan itu; id lain membuat kelompok kustom.

Properti	Rentang	Bawaan	Arti
id	[a-z0-9_], 1–16 karakter, huruf pertama huruf	wajib	nama kelompok; tidak boleh berawalan alarm_
en	boolean	true	false = kelompok tidak dikirim (tidak berlaku untuk alarm)
interval_s	0 atau 5 … 3600	0	0 = ikut telemetry_interval_ms
min_s	1 … 3600	2	jarak minimal antar-kirim yang dipicu ambang atau on_change; tidak boleh lebih besar dari interval_s efektif
on_change	boolean	false	metrik boolean yang berubah memicu kirim
prio	crit, normal, low	sesuai tabel; normal untuk kustom	urutan saat pesan harus dipecah
delta_ch	objek id kanal → angka, maks. 8 entri	kosong	menimpa delta profil untuk anggota kelompok ini

Batas: 24 kelompok kustom, pesan maks. 4096 byte. Properti yang tidak berlaku atau di luar rentang menolak entri itu saja, dengan alasan di rejected.

Keanggotaan: atribut group pada sumber

Hanya sumber yang menjadi anggota kelompok kustom. Di pesan sources, isi "group": "rak1" pada sumber untuk memasukkan semua metriknya ke kelompok itu. group_ch menaruh kanal tertentu di kelompok lain (mis. energi yang lambat ke kelompok energi). Sumber yang menyebut kelompok yang tidak ada dilaporkan di group_missing.

Pola yang dipakai untuk 8 rak per node: satu kelompok per rak (rak1 … rak8), plus satu kelompok energi berinterval panjang untuk energi kumulatif.

Ambang perubahan (delta)

Ambang ditentukan per metrik, dalam satuan metrik itu sendiri (selisih mutlak, bukan persen). Metrik memicu bila |nilai sekarang − nilai terakhir yang terkirim| ≥ delta. 0 atau tidak ada = tanpa ambang. Metrik boolean tidak memakai delta (pemicunya on_change).

Urutan penentuan untuk metrik sumber, dari yang menang:

1. deltas pada sumber ("deltas": {"t": 0.1}) atau delta pada regs inline;
2. delta_ch pada kelompoknya ("delta_ch": {"t": 0.2, "v": 1}), dicocokkan dengan id kanal profil;
3. delta pada kanal di profil;
4. tanpa ambang.

Metrik bawaan memakai key temp_report_delta_c (suhu, °C) dan power_report_delta_w (daya, W).

Satu pemicu cukup: saat terpicu, snapshot seluruh kelompok dikirim dan nilai terakhir terkirim diperbarui untuk semua anggota yang ikut. Metrik tanpa delta tidak pernah memicu pengiriman awal; kelompoknya tetap terkirim berkala.

Nilai awal pada profil bawaan (untuk meter di rak, tune per pemasangan):

Kanal	SDM120	PZEM-016
tegangan v	2 V	2 V
arus i	0,5 A	0,5 A
daya p	20 W	20 W
faktor daya pf	0,05	0,05
frekuensi f	0,5 Hz	0,5 Hz
energi kumulatif	tanpa ambang	tanpa ambang

Laporan tgroups/reported

Diterbitkan saat tersambung, saat set diterapkan, ditolak, atau dibatalkan, dan pada cmd get_tgroups; tidak periodik.

Field	Arti
tgroups_ver, hash, bytes, previous_hash	seperti rules
count, rejected	jumlah dimuat dan alasan penolakan per entri
effective[]	nilai efektif tiap kelompok (bawaan dan kustom): interval_s, min_s, prio, delta_ch, members (metrik yang punya nilai saat ini), src_declared (metrik sumber yang dideklarasikan, dengan atau tanpa nilai), sends, causes
causes	periodic, delta, on_change, appear, gone, forced; jumlahnya bisa melebihi sends karena satu pengiriman bisa memiliki beberapa penyebab
group_missing	sumber yang menyebut kelompok yang tidak ada
limits	max_groups, max_delta_ch, max_bytes, rentang interval, confirm_s_min/max

Server dapat menandai metrik “usang” bila tidak ada titik lebih dari 2 × interval_s efektif kelompoknya.

Menerapkan

Tab Kelompok di antarmuka web: kelompok bawaan, Kelompok baru, dan uji dengan konfirmasi.

Sama dengan rules dan sumber: confirm_s (30 … 3600), cmd tgroups_confirm, cmd tgroups_rollback, cmd get_tgroups.

python3 Tools/celestianctl.py tgroups <mac> --file tgroups.json --confirm-s 120
python3 Tools/celestianctl.py tgroups <mac> --confirm <hash>
python3 Tools/celestianctl.py tgroups <mac> --get
python3 Tools/celestianctl.py tgroups <mac> --clear     # kembali ke kelompok bawaan

Di web, tab Kelompok menyediakan tabel kelompok, formulir, mode JSON, dan tombol Terapkan kelompok dengan uji confirm_s. Isian Group, Channel groups, dan Channel thresholds per sumber ada di tab Sumber.

Bridge gateway harus meneruskan +/tgroups, +/tgroups/reported, dan +/tgroups/current (Bridge ke Celestian).