Format payload

Celestian menerima tiga format isi pesan. SenML dan SenFlat menghasilkan metrik yang sama di dalam platform (nilai terakhir, agregasi, grafik, alarm). JSON bebas hanya dilihat dan difilter.

Format	Bentuk	Cocok untuk
SenML	Array record	Standar terbuka, perangkat pihak ketiga
SenFlat v1	Satu objek datar	Perangkat dengan memori kecil, payload ringkas
SenFlat v2	Banyak sumber dan titik waktu	Gateway, data riwayat
JSON bebas	Apa saja	Payload khusus

SenML

Standar RFC 8428: array JSON dari record.

[
  {"bn": "ruang-a1:", "bt": 1790000000, "n": "temp_inlet", "u": "Cel", "v": 22.4},
  {"n": "humidity", "u": "%RH", "v": 48.3},
  {"n": "door_open", "vb": false},
  {"n": "status", "vs": "OK"}
]

Field	Arti
`n`	Nama metrik (wajib, maksimal 200 karakter).
`u`	Satuan.
`v`, `vb`, `vs`, `vd`, `s`	Nilai angka, boolean, teks (maksimal 500 karakter), data (base64), dan sum.
`t`, `bt`	Waktu. Kurang dari 2^28 detik dianggap relatif terhadap waktu terima; selain itu epoch detik. Tanpa waktu, dipakai waktu terima broker.
`bn`, `bu`, `bv`	Base name, base unit, base value; berlaku untuk record berikutnya. Nama akhir = `bn` + `n` (`ruang-a1:temp_inlet`).

Maksimal 1000 record per pesan.

SenFlat v1

Objek JSON datar, lebih ringkas daripada SenML. Hasilnya identik di dalam platform.

{
  "f": "flat", "v": 1, "id": "001a2b3c4d5e", "t": 1790000000,
  "m": { "temp_inlet": 22.44, "voltage": 230.1, "door_front_open": false, "state": "online" }
}

Field	Wajib	Arti
`f`	ya	Persis `"flat"`. Satu-satunya penentu format.
`v`	ya	Versi format: `1`.
`id`	tidak	Identitas sumber (padanan `bn` tanpa `:`). Tanpa `id`, sumbernya adalah publisher itu sendiri.
`t`	tidak	Waktu pengukuran, epoch detik UTC (boleh pecahan). Aturan waktunya sama dengan SenML.
`m`	ya	Metrik: nama → nilai. Minimal satu.

Aturan nilai di m:

Nilai JSON	Disimpan sebagai	Padanan SenML
Angka terhingga	Angka	`v`
`true` atau `false`	Boolean	`vb`
String	Teks (dipotong 500 karakter)	`vs`
`null`, objek, array, `NaN`, `Infinity`	Tidak valid

Sensor yang gagal dibaca tidak disertakan (jangan kirim null atau penanda seperti -1).

Beberapa sumber atau waktu: kirim array objek, semuanya SenFlat (tidak boleh dicampur dengan SenML).

[
  {"f":"flat","v":1,"id":"001a2b3c4d5e","t":1790000000,"m":{"temp_inlet":22.4}},
  {"f":"flat","v":1,"id":"001a2b3c4d5f","t":1790000000,"m":{"temp_inlet":23.1}}
]

Setara dengan SenML:

[{"bn":"001a2b3c4d5e:","bt":1790000000,"n":"temp_inlet","v":22.44},
 {"n":"voltage","v":230.1}, {"n":"door_front_open","vb":false}, {"n":"state","vs":"online"}]

Contoh ukuran untuk 16 metrik telemetri: SenML 624 byte, SenFlat 373 byte.

Nama metrik tersimpan dan satuan

Metrik tersimpan dengan nama <id>:<nama> bila id ada (001a2b3c4d5e:power_draw), atau <nama> saja. Nama ini dipakai di filter Messages dan widget dashboard.
Nama disarankan ^[a-z][a-z0-9_]*$ dan ditulis lengkap (temp_inlet, bukan ti).
Satuan tidak ikut payload. Diisi dari Katalog Metrik saat disimpan lewat Internal DB dan saat nilai terakhir ditampilkan.
Pesan tanpa f (misalnya config atau cmd) bukan metrik; tetap dihitung untuk Last Seen dan terlihat di tab Pesan terakhir.

Cara format dikenali

Objek dengan "f":"flat" → SenFlat.
Array yang elemen pertamanya objek "f":"flat" → SenFlat gabungan.
Array lain → SenML.
Selain itu → bukan metrik.

Mode ketat dan longgar

Payload dari device dibaca longgar: bagian yang tidak valid dilewati. Hasil logic di rule dibaca ketat: satu bagian tidak valid menolak seluruhnya.

Kondisi	Longgar	Ketat
`v` bukan 1	Bukan metrik	Ditolak
Elemen array tanpa `"f":"flat"`	Dilewati	Ditolak
`m` kosong atau bukan objek	Tidak ada record	Ditolak
Nilai metrik tidak valid	Metrik dilewati	Ditolak
Lebih dari 1000 record	Dipotong di 1000	Ditolak

JSON bebas

Diterima bila rule memakai output Internal DB (JSON):

{"suhu": 23.5, "kelembapan": 41, "lokasi": "ruang-a1"}

Bisa dilihat dan difilter di tab JSON pada Messages, tetapi tidak diagregasi atau digrafikkan.

Waktu pengukuran

Waktu di payload	Perlakuan
Tidak ada atau `0`	Waktu terima broker.
Nilai kecil (< 2^28)	Relatif terhadap waktu terima.
Epoch di luar rentang −1 tahun sampai +1 hari dari waktu terima	Tidak dipercaya; dipakai waktu terima.

Untuk perangkat dengan jam yang tidak selalu sinkron, SenFlat v2 menandai waktu yang tidak tepercaya secara eksplisit.

Membaca payload di rule

Format	Path di Comparison dan Lua
SenML	`message.payload[1].v` (indeks mulai dari 1)
SenFlat v1	`message.payload.m.temp_inlet`
JSON bebas	`message.payload.suhu`