Tutorial MQTT Python: Publish & Subscribe dengan Paho dan Mosquitto

MQTT Python adalah cara paling cepat untuk memahami MQTT secara praktik: cukup satu komputer, broker Mosquitto, dan library paho-mqtt. Di tutorial ini Anda akan menginstal broker Mosquitto, membuat program publisher dan subscriber Python, mengirim data sensor berformat JSON, lalu menambahkan fitur penting seperti retained message, Last Will, dan reconnect otomatis. Semua kode sudah diuji dengan paho-mqtt 2.x dan Mosquitto 2.x.

Belum paham konsep publish/subscribe, topik, dan QoS? Baca dulu panduan protokol MQTT. Ingin memakai broker cloud yang aman? Lihat tutorial HiveMQ Cloud Python.

Daftar isi:

• Alur yang akan dibuat
• Langkah 1–2: Instal dan uji broker Mosquitto
• Langkah 3: Instal paho-mqtt
• Langkah 4: Program subscriber Python
• Langkah 5: Program publisher Python
• Langkah 7: Retained message, Last Will, dan reconnect
• Mengakses broker dari perangkat lain
• Troubleshooting
• FAQ

Alur MQTT Python yang Akan Dibuat

Program publisher.py mensimulasikan sensor dan mengirim data ke broker Mosquitto di komputer Anda. Broker meneruskan data ke semua client yang berlangganan topik yang sama — program subscriber.py dan terminal mosquitto_sub. Program ketiga, status_perangkat.py, menunjukkan cara melaporkan status online/offline perangkat.

Persiapan

• Python 3.8 atau lebih baru (cek dengan python --version).
• Komputer Windows, Linux, macOS, atau Raspberry Pi.
• Text editor atau IDE (VS Code, Thonny, PyCharm).

Langkah 1 – Instal Broker Mosquitto

Panduan bergambar tersedia di artikel instalasi Mosquitto dan Node-RED di Windows dan instalasi Mosquitto di Raspberry Pi / Linux. Secara default broker mendengarkan di port 1883.

Langkah 2 – Uji Broker dengan mosquitto_sub dan mosquitto_pub

Sebelum menulis kode Python, pastikan broker berjalan. Buka dua terminal:

# Terminal 1 – subscribe (menunggu pesan)
mosquitto_sub -h localhost -t "bisaioti/lab/#" -v

# Terminal 2 – publish (mengirim pesan)
mosquitto_pub -h localhost -t "bisaioti/lab/test" -m "Halo MQTT"

Jika Terminal 1 menampilkan bisaioti/lab/test Halo MQTT, broker sudah siap. Biarkan Terminal 1 tetap terbuka.

Langkah 3 – Instal Library paho-mqtt

python -m venv venv
# Windows: venv\Scripts\activate   |   Linux/macOS: source venv/bin/activate
pip install "paho-mqtt>=2.0"

Penting untuk paho-mqtt 2.x: pembuatan client wajib menyertakan versi callback: mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="..."). Contoh lama seperti mqtt.Client("Subscriber1") akan error. Callback versi 2 juga memakai parameter reason_code dan properties.

Langkah 4 – Program Subscriber MQTT Python

Simpan sebagai subscriber.py. Program ini berlangganan semua topik di bawah bisaioti/lab/ dengan wildcard # dan menampilkan data JSON dengan rapi.

import json
import paho.mqtt.client as mqtt

BROKER = "localhost"      # atau IP komputer yang menjalankan Mosquitto
PORT   = 1883
TOPIC  = "bisaioti/lab/#" # '#' = semua sub-topik di bawah bisaioti/lab


def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code == 0:
        print("Terhubung ke broker, subscribe ke", TOPIC)
        client.subscribe(TOPIC, qos=1)
    else:
        print("Gagal terhubung:", reason_code)


def on_message(client, userdata, msg):
    teks = msg.payload.decode()
    try:
        data = json.loads(teks)
        print(f"[{msg.topic}] suhu={data['suhu']} °C, kelembapan={data['kelembapan']} %")
    except (json.JSONDecodeError, KeyError):
        print(f"[{msg.topic}] {teks}")


client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="monitor-pc-01")
client.on_connect = on_connect
client.on_message = on_message

client.connect(BROKER, PORT, keepalive=60)
try:
    client.loop_forever()
except KeyboardInterrupt:
    client.disconnect()

• on_connect melakukan subscribe setiap kali koneksi berhasil, sehingga langganan otomatis dipulihkan setelah reconnect.
• on_message dipanggil setiap ada pesan; payload diubah dari bytes ke teks lalu ke dictionary Python.
• loop_forever() menjaga program tetap berjalan dan menangani reconnect otomatis.

Langkah 5 – Program Publisher MQTT Python (Data Sensor)

Simpan sebagai publisher.py. Data sensor disimulasikan dengan angka acak dan dikirim dalam format JSON setiap 5 detik.

import json
import random
import time

import paho.mqtt.client as mqtt

BROKER = "localhost"
PORT   = 1883
TOPIC  = "bisaioti/lab/sensor1"

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="sensor-sim-01")
client.connect(BROKER, PORT, keepalive=60)
client.loop_start()   # jalankan proses jaringan MQTT di background

try:
    while True:
        data = {
            "suhu": round(random.uniform(25, 32), 1),
            "kelembapan": round(random.uniform(55, 80), 1),
            "waktu": time.strftime("%Y-%m-%d %H:%M:%S"),
        }
        info = client.publish(TOPIC, json.dumps(data), qos=1)
        info.wait_for_publish()          # tunggu konfirmasi (PUBACK) dari broker
        print("Terkirim:", data)
        time.sleep(5)
except KeyboardInterrupt:
    print("Publisher berhenti")
finally:
    client.loop_stop()
    client.disconnect()

• loop_start() menjalankan proses jaringan MQTT di background thread.
• qos=1 berarti broker wajib mengirim konfirmasi (PUBACK); wait_for_publish() menunggu konfirmasi tersebut.
• Ganti bagian random.uniform() dengan pembacaan sensor sungguhan (misalnya DHT22 di Raspberry Pi atau data serial dari Arduino) tanpa mengubah bagian MQTT.

Langkah 6 – Jalankan dan Amati Hasilnya

1. Jalankan python subscriber.py di satu terminal.
2. Jalankan python publisher.py di terminal lain.
3. Perhatikan juga terminal mosquitto_sub dari Langkah 2 — data yang sama ikut muncul.

Contoh output publisher:

Terkirim: {'suhu': 25.9, 'kelembapan': 59.6, 'waktu': '2026-09-29 14:34:08'}
Terkirim: {'suhu': 29.4, 'kelembapan': 68.8, 'waktu': '2026-09-29 14:34:13'}

Contoh output subscriber:

Terhubung ke broker, subscribe ke bisaioti/lab/#
[bisaioti/lab/sensor1] suhu=25.9 °C, kelembapan=59.6 %
[bisaioti/lab/sensor1] suhu=29.4 °C, kelembapan=68.8 %

Langkah 7 – Retained Message, Last Will, dan Reconnect Otomatis

Di proyek nyata, dashboard perlu tahu apakah perangkat sedang online atau mati. Tiga fitur MQTT berikut menyelesaikannya:

import time
import paho.mqtt.client as mqtt

BROKER = "localhost"
TOPIC_STATUS = "bisaioti/lab/sensor1/status"

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="sensor-sim-02")

# 1) Last Will: dikirim broker otomatis jika program ini putus tidak normal
client.will_set(TOPIC_STATUS, "offline", qos=1, retain=True)

# 2) Reconnect otomatis dengan jeda 1 s/d 30 detik
client.reconnect_delay_set(min_delay=1, max_delay=30)


def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code == 0:
        # 3) Retained message: subscriber baru langsung tahu status terakhir
        client.publish(TOPIC_STATUS, "online", qos=1, retain=True)
        print("Online")


def on_disconnect(client, userdata, flags, reason_code, properties):
    print("Terputus:", reason_code, "- mencoba menyambung ulang...")


client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.connect(BROKER, 1883, keepalive=30)
client.loop_forever()   # loop_forever juga menangani reconnect otomatis

Coba jalankan status_perangkat.py, lalu hentikan paksa (tutup terminalnya). Subscriber akan menerima offline dari broker. Subscriber yang baru dijalankan pun langsung menerima status terakhir karena pesannya retained.

Tips QoS dan Penamaan Topik

• QoS 0 untuk data periodik yang tidak kritis, QoS 1 untuk data atau perintah penting, QoS 2 hanya bila pesan benar-benar tidak boleh ganda. Penjelasan lengkap ada di panduan protokol MQTT.
• Gunakan topik hierarkis seperti lokasi/perangkat/parameter. Wildcard + mewakili satu level (bisaioti/+/sensor1), # mewakili semua level di bawahnya.
• Topik bersifat case-sensitive, jangan diawali “/”, dan hindari spasi.
• Setiap program wajib memakai client ID unik. Dua client dengan ID sama akan saling memutus koneksi.

Mengakses Broker Mosquitto dari Perangkat Lain

Mosquitto 2.x secara default hanya menerima koneksi dari komputer itu sendiri. Agar ESP32, Raspberry Pi, atau laptop lain di jaringan yang sama bisa terhubung, tambahkan baris berikut di mosquitto.conf lalu restart Mosquitto:

listener 1883
allow_anonymous true

allow_anonymous true hanya untuk belajar di jaringan lokal. Untuk penggunaan nyata, buat user dengan mosquitto_passwd -c passwd nama_user, ganti dengan allow_anonymous false + password_file, lalu di Python tambahkan client.username_pw_set("nama_user", "password") sebelum connect(). Jangan lupa izinkan port 1883 di firewall.

Broker Publik atau Broker Cloud?

Untuk uji coba cepat tanpa instalasi, ganti BROKER dengan broker publik seperti test.mosquitto.org atau broker.hivemq.com (port 1883). Broker publik terbuka untuk siapa saja, jadi gunakan topik yang unik dan jangan kirim data sensitif. Untuk proyek yang diakses lewat internet, gunakan broker pribadi dengan TLS dan password — langkahnya ada di tutorial HiveMQ Cloud Python.

Troubleshooting MQTT Python

FAQ MQTT Python

Library apa yang dipakai untuk MQTT di Python?

Yang paling umum adalah paho-mqtt dari Eclipse Foundation. Versi saat ini adalah 2.x, yang mewajibkan parameter CallbackAPIVersion saat membuat client.

Apakah bisa tanpa menginstal Mosquitto?

Bisa, dengan broker publik (test.mosquitto.org, broker.hivemq.com) atau broker cloud gratis seperti HiveMQ Cloud. Namun broker lokal lebih cepat dan cocok untuk belajar serta proyek di jaringan internal.

Apa beda loop_forever() dan loop_start()?

loop_forever() memblokir program dan cocok untuk subscriber. loop_start() menjalankan proses MQTT di thread terpisah sehingga program utama tetap bisa melakukan hal lain, misalnya membaca sensor.

Bagaimana menghubungkan data ESP32 ke program Python?

Arahkan ESP32 ke broker yang sama dan gunakan topik yang sama. Panduannya ada di tutorial MQTT ESP32.

Penutup

Anda sudah membangun sistem MQTT Python lengkap: broker Mosquitto, publisher data sensor, subscriber, serta status perangkat dengan retained message dan Last Will. Langkah berikutnya, sambungkan perangkat nyata seperti ESP32 atau tampilkan data di dashboard Node-RED. Ingin belajar terarah dengan pendampingan? Ikuti Training IoT Profesional bisaioti.

Referensi

• Eclipse Paho, “paho-mqtt” – pypi.org/project/paho-mqtt
• Eclipse Paho, “Migrations (1.x ke 2.0)” – eclipse.dev/paho
• Eclipse Mosquitto, “mosquitto.conf man page” – mosquitto.org
• OASIS, “MQTT Version 5.0” – docs.oasis-open.org

Baca Juga:

• Protokol MQTT: Pengertian, Cara Kerja, QoS, dan Contoh Penerapan
• Tutorial HiveMQ Cloud Python: Kirim Data Sensor via MQTT
• MQTT ESP32: Kirim Data Sensor & Kontrol LED
• Training ESP32 Berbasis IoT: Pelatihan Praktis Pemula hingga Mahir