Raspberry Pi MQTT Eğitimi: Python ile Publish, Subscribe ve Otomasyon

Bu Raspberry Pi MQTT eğitimi sizi temiz bir Raspberry Pi OS kurulumundan; sensör okumalarını yayımlayan, komutları dinleyen ve bir GPIO pinini her yerden kontrol eden bir Python programına götürür. Her şeyi broker.connectmq.com adresindeki ücretsiz public broker üzerinde test edecek, ardından aynı kodu birkaç ortam değişkeniyle TLS ile korunan özel bir broker'a taşıyacaksınız. Bu süreçte Pi tabanlı bir IoT cihazını dakikalarca değil aylarca güvenilir tutan kalıpları öğreneceksiniz.

Ne Geliştireceksiniz?

Bu rehberin sonunda Raspberry Pi'niz dört şey yapan tek bir Python servisi çalıştıracak:

1. Bir MQTT broker'a bağlanır ve Wi-Fi kopmalarından veya yeniden başlatmalardan sonra otomatik olarak yeniden bağlanır.
2. Her on saniyede bir CPU sıcaklığı, yük ortalaması ve isteğe bağlı olarak bir oda sensörü içeren bir JSON telemetri mesajı yayımlar.
3. Bir komut topic'ine abone olur ve GPIO17'deki bir LED'i (veya röleyi) açıp kapatır.
4. Diğer client'ların Pi'nin ortadan kaybolduğunu bilmesi için bir MQTT last will kullanarak retained bir çevrimiçi/çevrimdışı durum yayımlar.

Topic düzeni her şeyi benzersiz tek bir önek altında tutar; bu, paylaşımlı bir public broker'da önemlidir:

Topic, retained message veya last will gibi terimler sizin için yeniyse başlamadan önce bir MQTT broker'ın ne yaptığına göz atın. Kısaca: broker bir postanedir, Pi'niz ve dizüstü bilgisayarınız client'lardır, topic'ler ise adreslerdir.

Ön Koşullar

Bu Raspberry Pi MQTT eğitimi için çok az donanıma ihtiyacınız var:

• Ağ bağlantısı olan herhangi bir Raspberry Pi: Pi 3, Pi 4, Pi 5 veya Zero 2 W. Kod hepsinde aynıdır.
• SSH etkin ve ağ erişimi olan Raspberry Pi OS Bookworm (Lite yeterlidir).
• GPIO17'ye (fiziksel pin 11) ve GND'ye (pin 9) bağlı 330 ohm dirençli bir LED veya bir röle modülü. Bu olmadan da kod çalışır ve yalnızca komutları loglar.
• İsteğe bağlı: bir DHT22 veya DS18B20 sensörü. Hiçbir ek donanım gerekmemesi için dahili CPU sıcaklığıyla başlıyoruz.
• Test için mosquitto_sub ve mosquitto_pub yüklü ikinci bir makine (Linux'ta mosquitto-clients paketini kurun veya macOS'ta Homebrew kullanın).

Satın almadan önce kartları mı karşılaştırıyorsunuz? Raspberry Pi ve ESP32 karşılaştırması tam bir Linux bilgisayarının ne zaman bir mikrodenetleyiciden üstün olduğunu ve ne zaman gereğinden fazla kaçtığını açıklar.

Adım 1: Raspberry Pi'de Python'u Hazırlayın

Bookworm sistem Python'unu korur; bu yüzden sanal ortam dışında pip install "externally managed environment" hatasıyla başarısız olur. Bu iyi bir şeydir: sanal ortam proje bağımlılıklarınızı izole ve tekrarlanabilir tutar. Bir proje klasöründe bir tane oluşturun:

sudo apt update
sudo apt install -y python3-venv python3-lgpio mosquitto-clients
mkdir -p ~/pi-mqtt && cd ~/pi-mqtt
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install "paho-mqtt>=2.0" gpiozero

--system-site-packages bayrağı, sanal ortamın apt ile kurulan lgpio paketini görmesini sağlar; gpiozero güncel Raspberry Pi OS'ta bunu pin backend'i olarak kullanır (eski RPi.GPIO kütüphanesinin çalışmadığı Pi 5'te ise zorunludur). Modelinizin pin dizilimi için resmî Raspberry Pi GPIO belgelerine bakın.

Kurulu client sürümünü kontrol edin. Bu rehber, internette bulabileceğiniz eski eğitimlerden farklı olan paho-mqtt 2.x callback API'sini kullanır:

python -c "import paho.mqtt; print(paho.mqtt.__version__)"

Adım 2: İlk Publish ve Subscribe İşleminiz

Tam programı yazmadan önce ağ yolunun çalıştığını kanıtlayın. Topic'lerinizin public broker'daki başkalarınınkiyle çakışmaması için rastgele bir cihaz ID'si seçin. Bir terminalde (dizüstü bilgisayarınızda veya Pi'de) abone olun:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-laptop-7f3a -v -t "connectmq/demo/pi-7f3a/#"

İkinci bir terminalde bir test mesajı yayımlayın:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-pi-7f3a -t "connectmq/demo/pi-7f3a/hello" -m "hello from the pi"

Abone topic'i ve mesajı hemen yazdırır. Her client'ın boş olmayan, benzersiz bir client ID'ye ihtiyacı vardır; iki client aynı ID'yi paylaşırsa broker eski olanın bağlantısını keser ve kafa karıştırıcı bir bağlan-kop döngüsü görürsünüz. Ücretsiz public MQTT broker, topic'inizi tahmin eden herkes tarafından okunabilir; bu yüzden asla parola, kişisel veri veya herkese açık paylaşmayacağınız herhangi bir şey göndermeyin.

Adım 3: Eksiksiz Python MQTT Client'ı

Aşağıdakini ~/pi-mqtt/pi_mqtt.py olarak kaydedin. Tüm ayarları ortam değişkenlerinden okur; böylece aynı dosya bugün public broker için, daha sonra da özel bir broker için çalışır.

#!/usr/bin/env python3
"""Raspberry Pi MQTT client: telemetry, GPIO control and online status."""
import json
import os
import signal
import ssl
import threading
import time
import uuid

import paho.mqtt.client as mqtt

try:
    from gpiozero import LED
    led = LED(int(os.getenv("LED_PIN", "17")))
except Exception as exc:  # GPIO yok (ör. dizüstü bilgisayarda test)
    print(f"GPIO unavailable, running without LED: {exc}")
    led = None

HOST = os.getenv("MQTT_HOST", "broker.connectmq.com")
PORT = int(os.getenv("MQTT_PORT", "1883"))
USE_TLS = os.getenv("MQTT_TLS", "0") == "1"
USERNAME = os.getenv("MQTT_USERNAME")
PASSWORD = os.getenv("MQTT_PASSWORD")
DEVICE_ID = os.getenv("DEVICE_ID", f"pi-{uuid.uuid4().hex[:6]}")
CLIENT_ID = os.getenv("MQTT_CLIENT_ID", DEVICE_ID)
PREFIX = os.getenv("TOPIC_PREFIX", f"connectmq/demo/{DEVICE_ID}")
INTERVAL = float(os.getenv("PUBLISH_INTERVAL", "10"))

T_TELEMETRY = f"{PREFIX}/telemetry"
T_LED_SET = f"{PREFIX}/led/set"
T_LED_STATE = f"{PREFIX}/led/state"
T_STATUS = f"{PREFIX}/status"

stop_event = threading.Event()


def read_cpu_temp() -> float:
    with open("/sys/class/thermal/thermal_zone0/temp") as f:
        return round(int(f.read().strip()) / 1000.0, 1)


def publish_led_state(client: mqtt.Client) -> None:
    state = "ON" if (led and led.is_lit) else "OFF"
    client.publish(T_LED_STATE, state, qos=1, retain=True)


def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print(f"Connect failed: {reason_code}")
        return
    print(f"Connected to {HOST}:{PORT} as {CLIENT_ID}")
    client.publish(T_STATUS, "online", qos=1, retain=True)
    client.subscribe(T_LED_SET, qos=1)
    publish_led_state(client)


def on_disconnect(client, userdata, disconnect_flags, reason_code, properties):
    print(f"Disconnected ({reason_code}), paho will retry automatically")


def on_message(client, userdata, msg):
    command = msg.payload.decode("utf-8", errors="ignore").strip().upper()
    print(f"Command on {msg.topic}: {command}")
    if led is None:
        return
    if command == "ON":
        led.on()
    elif command == "OFF":
        led.off()
    elif command == "TOGGLE":
        led.toggle()
    else:
        print("Unknown command, ignoring")
        return
    publish_led_state(client)


def build_client() -> mqtt.Client:
    client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=CLIENT_ID)
    if USERNAME:
        client.username_pw_set(USERNAME, PASSWORD)
    if USE_TLS:
        client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
    client.will_set(T_STATUS, "offline", qos=1, retain=True)
    client.reconnect_delay_set(min_delay=1, max_delay=60)
    client.on_connect = on_connect
    client.on_disconnect = on_disconnect
    client.on_message = on_message
    return client


def main() -> None:
    client = build_client()
    client.connect_async(HOST, PORT, keepalive=30)
    client.loop_start()

    signal.signal(signal.SIGTERM, lambda *_: stop_event.set())
    signal.signal(signal.SIGINT, lambda *_: stop_event.set())

    while not stop_event.is_set():
        if client.is_connected():
            payload = {
                "cpu_temp": read_cpu_temp(),
                "load": round(os.getloadavg()[0], 2),
                "ts": int(time.time()),
            }
            client.publish(T_TELEMETRY, json.dumps(payload), qos=0)
        stop_event.wait(INTERVAL)

    client.publish(T_STATUS, "offline", qos=1, retain=True).wait_for_publish(2)
    client.loop_stop()
    client.disconnect()


if __name__ == "__main__":
    main()

Hangi topic'leri izleyeceğinizi bilmek için sabit bir cihaz ID'siyle çalıştırın:

cd ~/pi-mqtt && source .venv/bin/activate
DEVICE_ID=pi-7f3a python pi_mqtt.py

Kod nasıl çalışır?

Birkaç tasarım tercihini anlamaya değer; çünkü Pi projelerinin çoğu tam da bu noktalarda ters gider:

• connect_async ile loop_start ağ döngüsünü bir arka plan thread'inde çalıştırır ve paho'nun ilk bağlantıyı da yeniden denemesini sağlar. Düz bir connect(), ağ henüz hazır değilse bir istisna fırlatır ve betiği sonlandırır; bu, açılıştan hemen sonra yaygın bir durumdur.
• Last will (will_set) broker tarafından bağlantı anında saklanır. Pi'nin gücü kesilirse, keepalive süresi dolduktan sonra broker sizin yerinize offline yayımlar. Düzgün kapatma yolu ise offline'ı açıkça yayımlar.
• Retained durum topic'leri, daha sonra bağlanan bir dashboard'un bir sonraki değişikliği beklemeden güncel LED durumunu ve çevrimiçi durumu hemen görmesi demektir.
• on_connect içinde abone olmak, her yeniden bağlantıdan sonra aboneliği geri yükler. connect()'ten sonra bir kez abone olmak, ilk ağ dalgalanmasından sonra komutları sessizce durduran klasik bir hatadır.
• Komutlar ve durum için QoS 1, telemetri için QoS 0 makul bir varsayılandır. Periyodik bir okumayı kaybetmek zararsızdır; bir OFF komutunu kaybetmek ise değildir. MQTT QoS seviyeleri rehberimiz ödünleşimleri derinlemesine açıklar.

Adım 4: GPIO'yu MQTT Üzerinden Kontrol Edin

Betik çalışırken dizüstü bilgisayarınızdan komut gönderin:

mosquitto_pub -h broker.connectmq.com -p 1883 -i cmd-laptop-7f3a -q 1 -t "connectmq/demo/pi-7f3a/led/set" -m "ON"
mosquitto_pub -h broker.connectmq.com -p 1883 -i cmd-laptop-7f3a -q 1 -t "connectmq/demo/pi-7f3a/led/set" -m "TOGGLE"

LED durum değiştirir ve abone penceresi led/state üzerindeki yeni retained durumu gösterir. Aynı kalıp bir pompa, fan veya kapı kilidi için bir röleyi sürer; LED yerine gpiozero.OutputDevice kullanın ve aktif-düşük röle kartları için mantığı tersine çevirmeyi düşünün. Düğmeler, PWM ile kısma ve birden fazla pin için özel MQTT üzerinden Raspberry Pi GPIO rehberiyle devam edin; şebeke gerilimi anahtarlayan donanımlar için ise kablolama güvenliği açısından MQTT ile Raspberry Pi röle kontrolü yazısını okuyun.

Aktüatörler için pratik bir kural: doğruluğun sahibi dashboard değil, cihazdır. Her zaman donanımın gerçekte ulaştığı durumu yayımlayın ve kullanıcı arayüzlerinin komutun işe yaradığını varsaymak yerine bu durum topic'ini göstermesini sağlayın.

Adım 5: Gerçek Bir Sensör Ekleyin

CPU sıcaklığı veri hattını kanıtlar, ancak çoğu proje odayı ölçer. read_cpu_temp() fonksiyonunu bir sensör okuyucuyla değiştirin ve değerleri payload sözlüğüne ekleyin. Aşağıdaki tablo yaygın seçenekleri ve sonraki adımları özetler:

Sensör okumalarını MQTT callback'lerinin dışında tutun. Callback'ler ağ thread'inde çalışır ve orada yavaş bir sensör okuması keepalive yönetimini ve onayları geciktirir. Bloklayan her şey için doğru yer, yukarıdaki betiğin ana döngüsüdür.

Cihazlar arasında tutarlı bir JSON yapısı kullanın: sayısal değerler, anahtar adında veya ayrı bir unit alanında SI birimleri ve bir Unix zaman damgası. Grafana'dan Node-RED'e kadar daha sonra ekleyeceğiniz her tüketici size minnettar olacaktır.

Adım 6: MQTT Betiğini systemd ile Açılışta Çalıştırın

Bir SSH oturumundan başlatılan betik, oturumu kapattığınızda ölür. Açılışta başlaması ve hata durumunda yeniden başlaması için onu bir systemd servisine dönüştürün. /etc/systemd/system/pi-mqtt.service dosyasını oluşturun:

[Unit]
Description=Raspberry Pi MQTT client
After=network-online.target
Wants=network-online.target

[Service]
User=pi
WorkingDirectory=/home/pi/pi-mqtt
EnvironmentFile=/home/pi/pi-mqtt/.env
ExecStart=/home/pi/pi-mqtt/.venv/bin/python /home/pi/pi-mqtt/pi_mqtt.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

pi yerine kendi kullanıcı adınızı yazın, gerekirse kullanıcıyı gpio grubuna ekleyin (sudo usermod -aG gpio pi) ve .env dosyasını oluşturun:

cat > ~/pi-mqtt/.env <<'EOF'
DEVICE_ID=pi-7f3a
PUBLISH_INTERVAL=10
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now pi-mqtt
journalctl -u pi-mqtt -f

Betik SIGTERM'i ele aldığı için systemctl stop pi-mqtt çıkmadan önce düzgün bir offline durumu yayımlar. Log rotasyonu, watchdog'lar ve cron @reboot gibi alternatifler için bir Python MQTT betiğini açılışta çalıştırma yazısına bakın.

Adım 7: Public Broker'dan Özel Bir Broker'a Geçin

Public broker öğrenmek için mükemmeldir, ancak paylaşımlı, anonim ve hız sınırlıdır (örneğin client başına saniyede 10 mesaj ve mesaj başına 64 KB). Bağımlı olduğunuz her şey için kendi kimlik bilgilerinizi, şifrelemeyi ve izolasyonu istersiniz. İki seçeneğiniz var:

Mosquitto'yu yerelde çalıştırmak Raspberry Pi'ye Mosquitto kurulumu yazısında ele alınıyor. Barındırılan bir servisi seçerseniz ConnectMQ size birkaç dakika içinde özel bir broker verir: kaydolun, bir plan seçin, bir broker oluşturun; portal üretilmiş bir kullanıcı adı, parola ve client ID gösterir. Ardından yalnızca .env dosyasını düzenleyin:

cat > ~/pi-mqtt/.env <<'EOF'
MQTT_HOST=broker.connectmq.com
MQTT_PORT=8883
MQTT_TLS=1
MQTT_USERNAME=YOUR_USERNAME
MQTT_PASSWORD=YOUR_PASSWORD
MQTT_CLIENT_ID=YOUR_CLIENT_ID
DEVICE_ID=pi-7f3a
TOPIC_PREFIX=home/livingroom/pi-7f3a
EOF
sudo systemctl restart pi-mqtt

8883 portu herkesçe güvenilen bir Let's Encrypt sertifikasıyla TLS kullanır; bu yüzden tls_set() sertifikayı Raspberry Pi OS ile gelen CA paketiyle doğrular. Pi'ye sertifika dosyası kopyalamanız gerekmez. ConnectMQ'da client ID'ler verilen kimlik bilgilerine bağlıdır; bu yüzden rastgele bir ID yerine portaldaki client ID'yi kullanın. Dizüstü bilgisayarınızdan aynı kimlik bilgileriyle test edin:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID-cli -v -t "home/#"

Portal tek bir client ID verdiyse, Pi'ninkini yeniden kullanmak yerine dizüstü bilgisayar için ikinci bir kimlik bilgisi seti oluşturun; aynı ID'ye sahip iki bağlantı birbirini düşürür. Portal ayrıca tarayıcı içi bir MQTT client'ı ve canlı bir topic gezgini içerir; bu da hiçbir şey kurmadan Pi'nizin mesajlarının gelişini izlemenin çoğu zaman en hızlı yoludur.

Güvenilir Cihazlar İçin Raspberry Pi MQTT Eğitimi Kontrol Listesi

"Dün çalışıyordu" sorunlarının çoğu aynı kısa listeden kaynaklanır. Bir Pi'yi dolaba kapatmadan önce şunları gözden geçirin:

1. Bağlantı başına benzersiz client ID. Yinelenen ID'ler sonsuz yeniden bağlanma döngülerine neden olur.
2. Abonelikler on_connect içinde. Aksi hâlde komutlar ilk yeniden bağlantıdan sonra durur.
3. Last will ve retained durum. Dashboard'lar "sessiz" ile "ölü"yü ayırt edebilmelidir.
4. Laboratuvar dışındaki her şey için kimlik bilgileriyle 8883 portunda TLS. MQTT güvenliği en iyi uygulamalarının tam listesine bakın.
5. Restart=on-failure ile systemd ve journald'da loglar.
6. Boşluklar önemliyse çevrimdışıyken okumaları tamponlayın. Paho bağlantı yokken QoS 1 mesajlarını kuyruğa alır, ancak yalnızca bellekte; Python'da MQTT mesajlarını çevrimdışı tamponlama yeniden başlatmalardan sağ çıkan SQLite tabanlı bir yaklaşım gösterir.
7. İyi bir güç kaynağı ve kaliteli bir SD kart veya SSD'den açılış. Düşük voltaj, herhangi bir yazılım hatasından daha fazla rastgele bağlantı kopmasına neden olur.
8. İşletim sistemini sıkılaştırın: yalnızca SSH anahtarları, otomatik güvenlik güncellemeleri, varsayılan parola yok. Bir Raspberry Pi IoT cihazını güvenceye alma bunu adım adım anlatır.

Sorun Giderme

Connect failed: Not authorized, kullanıcı adının, parolanın veya client ID'nin broker'ın verdiğiyle eşleşmediği anlamına gelir. Bunları portaldan yeniden kopyalayın ve .env içinde sondaki boşlukları kontrol edin.

8883'te ConnectionRefusedError veya zaman aşımları genellikle bir güvenlik duvarının veya misafir ağının giden portları engellediği anlamına gelir. nc -vz broker.connectmq.com 8883 ile test edin. Bazı kurumsal ağlar yalnızca 443'e izin verir; bu durumda 8084 portundaki güvenli WebSocket üzerinden MQTT de engellenmiş olabilir, bu yüzden karar vermeden önce test edin.

ssl.SSLCertVerificationError neredeyse her zaman Pi saatinin yanlış olduğu anlamına gelir. TLS doğru bir tarih gerektirir; timedatectl ile kontrol edin ve NTP'nin etkin olduğundan emin olun.

Mesajlar geliyor ama LED tepki vermiyor durumu GPIO izinlerine veya kablolamaya işaret eder. Pin durumunu görmek için güncel Raspberry Pi OS'ta pinctrl get 17 çalıştırın ve kullanıcının gpio grubunda olduğunu doğrulayın.

Birkaç saniyede bir yeniden bağlanma döngüsü, yinelenen bir client ID'dir veya betiğin ikinci bir kopyası hâlâ çalışıyordur. ps aux | grep pi_mqtt ile kontrol edin.

Sırada Ne Var?

Bu Raspberry Pi MQTT eğitimi size sağlam bir temel verir ve Raspberry Pi serimizin geri kalanı tam olarak bu betiğin üzerine kurulur:

• Modbus ve BLE kaynakları dahil Raspberry Pi IoT gateway rehberiyle Pi'yi bir protokol çeviricisine dönüştürün.
• Pil projeleri için daha küçük ve ucuz bir şeye mi ihtiyacınız var? MicroPython ile Raspberry Pi Pico W'da MQTT deneyin.
• Okumalarınızı Raspberry Pi'de Grafana ve InfluxDB ile saklayın ve grafiğe dökün.
• MQTT üzerinden Raspberry Pi sistem istatistikleri ile bütün bir filonun sağlık verilerini yayımlayın.

ConnectMQ ile Başlayın

Pi projeniz public test broker'ına sığmaz hâle geldiğinde ConnectMQ'da özel bir broker oluşturun. Ücretsiz Serverless plan kredi kartı gerektirmez, 25 bağlantıya kadar destekler ve kutudan çıktığı gibi 8883 portunda TLS, MQTT 5 ve WebSocket erişimi sunar; bu, bir ev laboratuvarı veya ilk pilot için fazlasıyla yeterlidir. Daha büyük filolar tek bir satır client kodunu değiştirmeden ücretli Serverless veya Dedicated planlara geçebilir. app.connectmq.com adresinde ücretsiz broker'ınızı oluşturun ve .env dosyanızı ona yönlendirin. Önce barındırma seçeneklerinin büyük resmini görmek isterseniz bulut MQTT broker seçimi hakkındaki genel bakışımızı okuyun.

Sık Sorulan Sorular

Raspberry Pi'de hangi MQTT kütüphanesini kullanmalıyım?

Python için paho-mqtt 2.x en yaygın kullanılandır ve bu rehberin kullandığı da odur. Node.js kullanıcıları MQTT.js kullanabilir; low-code kullanıcıları ise aynı broker ayarlarıyla Pi'de Node-RED çalıştırabilir.

Bir Raspberry Pi hem MQTT broker hem de client olabilir mi?

Evet. Pi'de Mosquitto çalıştırıp yerel betikleri localhost'a bağlayabilirsiniz, ancak bu durumda güvenliği, güncellemeleri ve uzaktan erişimi kendiniz yönetirsiniz. Birçok proje Pi'yi bir client olarak tutar ve farklı konumlardaki cihazların ve dashboard'ların birbirine ulaşabilmesi için barındırılan bir broker kullanır.

Pi'm neden sürekli bağlantısını kesip yeniden bağlanıyor?

En yaygın nedenler yinelenen bir client ID, betiğin çalışan ikinci bir kopyası veya kararsız bir güç kaynağıdır. Her bağlantının benzersiz bir ID kullandığını kontrol edin ve dmesg ile düşük voltaj uyarılarına bakın.

Public broker Raspberry Pi projem için güvenli mi?

Öğrenme ve demolar için güvenlidir, ancak herhangi bir client public topic'leri okuyabilir; bu yüzden asla kişisel veya hassas veri göndermeyin. Gerçek dağıtımlar için TLS ve kimlik bilgileri olan özel bir broker kullanın.

Bu kod Raspberry Pi 5'te çalışır mı?

Evet. Betik, Pi 5'i destekleyen lgpio backend'i ile gpiozero kullanır. RPi.GPIO gibi eski GPIO bellek register'larına yazan kütüphaneler Pi 5'te çalışmaz.