Support soundbox firmware MQTT topics

18-mqtt-broker-mosquitto-debian13.md

@@ -11,7 +11,7 @@ Keputusan arsitektur terkait:
 - Broker: Eclipse Mosquitto.
 - Domain: `broker.bizone.id`.
 - MQTT TLS publik: `8883/tcp`.
-- MQTT local-only: `1883/tcp` pada `127.0.0.1`.
+- MQTT non-TLS pilot: `1883/tcp`, default disarankan local-only; boleh dibuka publik sementara jika firmware device belum support SSL/TLS.
 - TLS: Let's Encrypt.
 - Auth: username/password.
 - Authorization: ACL topic per user/device.
@@ -48,7 +48,28 @@ sudo ufw enable
 sudo ufw status verbose
 ```
 
-Jangan buka `1883/tcp` ke internet. Listener `1883` hanya untuk localhost/internal test.
+Default paling aman: jangan buka `1883/tcp` ke internet. Listener `1883` cukup untuk localhost/internal test.
+
+Jika firmware device belum support SSL/TLS dan harus memakai MQTT non-SSL, port `1883/tcp` boleh dibuka untuk pilot dengan risiko credential MQTT lewat clear-text. Pastikan:
+
+- `allow_anonymous false`;
+- password kuat dan unik;
+- ACL aktif;
+- tidak memakai credential admin/backend untuk device;
+- segera pindah ke `8883` setelah firmware support TLS.
+
+Untuk pilot public non-TLS:
+
+```bash
+sudo ufw allow 1883/tcp
+sudo ufw status verbose
+```
+
+Jika sumber IP device bisa diprediksi, batasi firewall:
+
+```bash
+sudo ufw allow from <DEVICE_OR_NAT_PUBLIC_IP> to any port 1883 proto tcp
+```
 
 ## Sertifikat TLS
 
@@ -131,12 +152,22 @@ Isi awal:
 ```conf
 user qris-backend
 topic readwrite devices/#
+topic readwrite soundbox/#
 
 pattern write devices/%u/uplink/#
 pattern read devices/%u/downlink/#
 pattern write devices/%u/heartbeat
+pattern read soundbox/%u/down
 ```
 
+Untuk firmware QF100 sample saat ini, config server mengembalikan topic berbasis serial number:
+
+```text
+soundbox/{dev-sn}/down
+```
+
+Jika masih memakai user MQTT bersama `qris-backend` untuk pilot, rule `topic readwrite soundbox/#` wajib ada. Jika nanti per-device credential memakai username sama dengan `dev-sn`, rule `pattern read soundbox/%u/down` bisa dipakai untuk membatasi tiap device hanya membaca topic miliknya sendiri.
+
 Permission:
 
 ```bash
@@ -172,6 +203,21 @@ password_file /etc/mosquitto/passwd
 acl_file /etc/mosquitto/acl
 ```
 
+Untuk device yang belum support SSL/TLS dan harus connect dari internet, ubah listener `1883` menjadi publik:
+
+```conf
+listener 1883 0.0.0.0
+protocol mqtt
+allow_anonymous false
+password_file /etc/mosquitto/passwd
+acl_file /etc/mosquitto/acl
+```
+
+Jangan jalankan dua listener `1883` sekaligus. Pilih salah satu:
+
+- `listener 1883 127.0.0.1` untuk local-only;
+- `listener 1883 0.0.0.0` untuk pilot public non-TLS.
+
 Catatan Debian:
 - Jangan set ulang `persistence`, `persistence_location`, `log_dest`, atau `log_type` di `conf.d/qris.conf` jika sudah ada di `/etc/mosquitto/mosquitto.conf`.
 - Jika muncul error `Duplicate persistence_location value`, hapus `persistence` dan `persistence_location` dari `qris.conf`.
@@ -198,7 +244,7 @@ sudo ss -lntp | grep mosquitto
 
 Expected:
 - `0.0.0.0:8883`
-- `127.0.0.1:1883`
+- `127.0.0.1:1883` untuk local-only, atau `0.0.0.0:1883` untuk pilot public non-TLS.
 
 ## Test Publish Subscribe
 
@@ -240,6 +286,61 @@ mosquitto_pub \
 
 Pesan ke topic device lain harus ditolak atau tidak sampai ke subscriber.
 
+## Test Non-TLS 1883
+
+Jika port `1883` dibuka untuk device non-SSL, test tanpa parameter TLS:
+
+Terminal 1, subscribe sebagai backend:
+
+```bash
+mosquitto_sub \
+  -h broker.bizone.id \
+  -p 1883 \
+  -u qris-backend \
+  -P 'PASSWORD_BACKEND' \
+  -t 'devices/DEVICE_UUID_FROM_PLATFORM/uplink/#' \
+  -v
+```
+
+Terminal 2, publish sebagai device:
+
+```bash
+mosquitto_pub \
+  -h broker.bizone.id \
+  -p 1883 \
+  -u DEVICE_UUID_FROM_PLATFORM \
+  -P 'PASSWORD_DEVICE' \
+  -t 'devices/DEVICE_UUID_FROM_PLATFORM/uplink/dynamic-qr/request' \
+  -m '{"request_id":"test-1883","amount":10000}'
+```
+
+Jika device memakai config server `/speaker/dev-config`, set app server agar response MQTT ke device memakai port 1883:
+
+```env
+QF100_MQTT_BROKER_HOST=broker.bizone.id
+QF100_MQTT_BROKER_PORT=1883
+QF100_MQTT_USERNAME=qris-backend
+QF100_MQTT_PASSWORD=...
+```
+
+Response config device akan mengirim topic:
+
+```json
+{
+  "mqtt": {
+    "client-id": "soundbox-DEVICE_SN",
+    "subscribe-topic": "soundbox/DEVICE_SN/down",
+    "publish-topic": "soundbox/DEVICE_SN/up"
+  }
+}
+```
+
+Jika firmware tidak bisa resolve domain, isi `QF100_MQTT_BROKER_HOST` dengan IP broker:
+
+```bash
+dig +short broker.bizone.id
+```
+
 ## Monitoring
 
 ```bash
@@ -268,6 +369,13 @@ MQTT_CONNECT_TIMEOUT_MS=5000
 MQTT_TLS=true
 ```
 
+Backend sebaiknya tetap memakai TLS `8883`. Untuk device non-SSL, cukup ubah env khusus response config device:
+
+```env
+QF100_MQTT_BROKER_HOST=broker.bizone.id
+QF100_MQTT_BROKER_PORT=1883
+```
+
 Topic kontrak yang harus dipertahankan:
 
 ```text
@@ -277,6 +385,8 @@ devices/{deviceId}/downlink/payment/success
 devices/{deviceId}/downlink/config/push
 devices/{deviceId}/uplink/config/ack
 devices/{deviceId}/heartbeat
+soundbox/{dev-sn}/down
+soundbox/{dev-sn}/up
 ```
 
 ## Provisioning Credential Device