Menyambungkan perangkat (MQTT)

Perangkat berbicara dengan Celestian lewat MQTT. Satu device cukup membutuhkan ID, key, dan alamat broker.

Yang dibutuhkan

Item	Nilai
Broker	<host>:1883 (MQTT 3.1.1) atau <host>:1884 (MQTT 5). Port bisa berbeda di instance Anda. Bila TLS diaktifkan, tersedia juga port MQTTS (misalnya 8883) untuk kedua versi.
Username	ID device (UUID dari halaman detail device).
Password	Device key (tampil sekali saat device dibuat atau key dibuat ulang).
Client ID	Di produksi harus diawali ID device, misalnya <id> atau <id>-2. Di development bebas.
Izin	Device harus punya koneksi publish (kirim) dan/atau subscribe (terima) ke channel.
Penyimpanan	Channel harus punya rule penyimpanan bila pesan ingin tersimpan.

Gunakan TLS di internet

MQTT biasa (port 1883) tidak terenkripsi. Untuk lalu lintas melewati internet, gunakan MQTTS bila disediakan administrator, atau lewatkan jaringan privat/VPN.

Tab Credentials di halaman detail device menghasilkan semua contoh di bawah dengan ID, topik, dan broker yang sudah terisi.

Topik

m/<workspace>/c/<channel>[/<subtopik>]

<workspace> dan <channel> boleh route atau UUID:

m/gudang-nusantara/c/telemetri-gudang
m/gudang-nusantara/c/telemetri-gudang/ruang-a1
m/gudang-nusantara/c/telemetri-gudang/lantai2/ruang-b1/suhu

• Identitas pengirim tidak ada di topik. Broker mencatat device yang terautentikasi sebagai publisher, sehingga tidak bisa dipalsukan.
• Subtopik bebas, bertingkat dengan /, dan hanya berfungsi sebagai label. Karakter terlarang: *, >, spasi, dan karakter kontrol.
• Wildcard + (satu tingkat) dan # (banyak tingkat) hanya untuk subscribe.
• Broker mencocokkan topik secara literal: pesan ke m/<uuid>/c/<uuid>/… tidak sampai ke device yang berlangganan m/<route>/c/<route>/…. Pakai bentuk topik yang sama di kedua sisi.

Contoh kode

mosquitto_pub

DEV=<id-device>
mosquitto_pub -h <alamat-broker> -p 1883 -V mqttv311 -q 1 -i "$DEV" -u "$DEV" -P '<device-key>' \
  -t 'm/gudang-nusantara/c/telemetri-gudang/ruang-a1' \
  -m '[{"n":"temp_inlet","u":"Cel","v":22.4}]'

Python (paho-mqtt 2.x)

import json
import paho.mqtt.client as mqtt

DEV, KEY = "<id-device>", "<device-key>"
c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=DEV)
c.username_pw_set(DEV, KEY)
c.connect("<alamat-broker>", 1883)
c.loop_start()
payload = json.dumps([{"n": "temp_inlet", "u": "Cel", "v": 22.4}])
c.publish("m/gudang-nusantara/c/telemetri-gudang/ruang-a1", payload, qos=1).wait_for_publish()
c.loop_stop()

Node.js

import mqtt from "mqtt"; // npm i mqtt
const c = mqtt.connect("mqtt://<alamat-broker>:1883", {
  clientId: "<id-device>", username: "<id-device>", password: "<device-key>",
});
c.on("connect", () =>
  c.publish("m/gudang-nusantara/c/telemetri-gudang/ruang-a1",
    JSON.stringify([{ n: "temp_inlet", u: "Cel", v: 22.4 }])));

ESP32 / ESP8266

client.setServer("<alamat-broker>", 1883);
client.connect(DEV_ID /*clientId*/, DEV_ID /*username*/, DEV_KEY /*password*/);
client.publish("m/gudang-nusantara/c/telemetri-gudang/ruang-a1",
               "[{\"n\":\"temp_inlet\",\"u\":\"Cel\",\"v\":22.4}]");
// panggil client.loop() di loop() agar koneksi tetap hidup

Menerima perintah

Beri device koneksi subscribe ke channel, lalu berlangganan:

mosquitto_sub -h <alamat-broker> -p 1883 -V mqttv311 -i "<id-device>-sub" -u "<id-device>" -P '<device-key>' \
  -t 'm/gudang-nusantara/c/telemetri-gudang/#' -v

Perintah bisa berasal dari API (messages/send), widget Switch atau Slider di dashboard, halaman Messages (Kirim pesan), atau output Channel Publisher sebuah rule.

Catatan

Bila akses sebuah device dicabut, langganan yang sedang aktif baru berhenti saat klien menyambung ulang.

Perilaku broker

Situasi	Hasil
Publish benar	Tersambung dan pesan diterima. Terlihat di Messages bila ada rule penyimpanan.
Password salah, device tidak dikenal, atau device nonaktif	Koneksi ditolak (bad user name or password).
Topik di luar izin (workspace atau channel lain, atau tanpa koneksi publish)	Koneksi diputus broker (klien melihat connection lost), tanpa pesan galat.
client_id tidak diawali ID device	Ditolak di produksi; diterima di development.
Channel, device, atau workspace nonaktif	Autentikasi atau otorisasi ditolak.

Status koneksi

Status online, kapan terakhir tersambung atau terputus, dan Last Seen tampil di halaman Devices. Celestian mencatat koneksi saat autentikasi dan pemutusan lewat webhook broker, ditambah rekonsiliasi berkala untuk menutup celah.

Pemecahan masalah

Gejala	Penyebab umum
Tidak bisa tersambung	Username atau password salah; client ID tidak diawali ID device (produksi); broker atau port salah.
Tersambung tetapi pesan tidak muncul di Messages	Belum ada rule penyimpanan untuk channel itu; payload bukan SenML/SenFlat padahal rule memakai output SenML; cek Rules → Executions.
Koneksi langsung putus saat publish	Device belum punya koneksi publish ke channel itu, atau topik salah.
Muncul di Last Seen tetapi tidak tersimpan	Sama seperti di atas: tanpa rule, pesan tidak disimpan.
Rule berjalan tetapi baris kosong	Record SenML tanpa n atau tanpa nilai dilewati.
Nilai terakhir atau grafik kosong	Payload JSON bebas (bukan SenML atau SenFlat).
quota.*_exceeded saat membuat device atau channel	Kuota pemilik workspace tercapai.

Uji cepat tanpa perangkat: kirim satu pesan dengan mosquitto_pub lalu buka Messages dengan mode Live, atau pakai simulator.