MQTT 5 Reason Code'ları: Nedenleri ve Çözümleriyle Eksiksiz Referans Tablosu

MQTT reason code'ları, MQTT 5 broker'larının ve client'larının tam olarak ne olduğunu belirtmek için onaylara ve DISCONNECT paketlerine koyduğu tek baytlık durum değerleridir. Bu referans her kodu, hangi paketlerin onu taşıyabileceğini, genellikle neyin tetiklediğini ve nasıl düzeltileceğini listeler; böylece loglarınızdaki anlaşılmaz bir 0x87 veya 0x97 değerini somut bir sonraki adıma dönüştürebilirsiniz.

MQTT Reason Code'ları Nasıl Çalışır?

MQTT 3.1.1'de yalnızca birkaç durum değeri vardı: altı CONNACK dönüş kodu ve SUBACK'te tek bir hata değeri (0x80). Reddedilen bir publish veya broker tarafında bir bağlantı kesme gibi diğer her şey sessizdi; bağlantı yalnızca kapanırdı. MQTT 5 bunu CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT ve AUTH genelinde kullanılan ortak bir reason code kümesiyle değiştirdi. Sahada cihaz işleten herkes için en pratik MQTT 5 özelliklerinden biridir.

İki kural tabloyu okumayı kolaylaştırır:

• 0x80'in altındaki değerler başarı veya hata olmayan bir sonuç anlamına gelir; örneğin "QoS 1 verildi" veya "eşleşen subscriber yok".
• 0x80 ve üzerindeki değerler hata anlamına gelir. Kodu taşıyan paket hangi işlemin başarısız olduğunu söyler.

Birçok paket ayrıca bir Reason String property'si, yani gönderenden gelen insan tarafından okunabilir bir açıklama taşıyabilir. Varsa her zaman loglayın; çoğu zaman aşılan sınırın tam olarak kendisini içerir.

Başarı ve Bilgilendirme Kodları

İstediğinizden daha düşük bir QoS veren bir SUBACK hata değildir. QoS 2 isteyip 0x01 alırsanız, broker'ın bağlantınız için maksimum QoS'u 1'dir ve mesajlar en fazla QoS 1 ile gelir.

Hata Reason Code'ları Referansı

0x8D ve 0x8E gibi bazı kodların yalnızca broker'ın gönderdiği bir DISCONNECT'te göründüğüne dikkat edin. 0x84 ile 0x88 arası gibi diğerleri ise bağlantının en başta neden reddedildiğini açıkladıkları için yalnızca CONNACK'te görünebilir.

MQTT 3.1.1 Dönüş Kodlarını MQTT 5'e Eşlemek

Her iki protokol sürümünü de destekliyorsanız bu eşleme hata işlemenizi tutarlı tutar. Ayrıntılı anlatım MQTT CONNACK dönüş kodları rehberinde.

Python'da MQTT Reason Code'larını Loglamak

paho-mqtt 2.x ve CallbackAPIVersion.VERSION2 ile her callback bir ReasonCode nesnesi alır. String biçimi spesifikasyondaki addır, .value ise sayısal koddur; loglarda tam olarak istediğiniz budur:

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    print(f"CONNACK: {reason_code} (0x{reason_code.value:02X})")
    if reason_code.is_failure:
        return
    client.subscribe("connectmq/demo/b7d2/#", qos=2)

def on_subscribe(client, userdata, mid, reason_code_list, properties):
    for rc in reason_code_list:
        print(f"SUBACK: {rc} (0x{rc.value:02X})")

def on_disconnect(client, userdata, flags, reason_code, properties):
    reason = getattr(properties, "ReasonString", None) if properties else None
    print(f"DISCONNECT: {reason_code} (0x{reason_code.value:02X}) {reason or ''}")

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="reason-demo-b7d2",
    protocol=mqtt.MQTTv5,
)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_disconnect = on_disconnect
client.connect("broker.connectmq.com", 1883, keepalive=30)
client.loop_forever()

Bunu herkese açık MQTT test broker'ına karşı çalıştırdığınızda bağlantıda Success ve SUBACK'te verilen bir QoS görürsünüz. 0x8F Topic Filter invalid kodunu iş başında görmek için connectmq/demo/b7d2/#/x gibi geçersiz bir filtreye subscribe olmayı deneyin. MQTT.js'te aynı bilgi connack.reasonCode içinde, subscribe callback'inin granted dizisinde ve disconnect olay paketinde bulunur.

Reason Code'a Göre Hata Ayıklama Akışı

Bir hatayı incelemek için pratik bir sıra:

1. Paketi belirleyin. CONNACK'teki bir kod bağlantı sorunu, SUBACK'teki bir subscription sorunu, DISCONNECT'teki ise çalışma zamanı sorunudur.
2. Reason String'i okuyun. Genellikle nedeni belirli bir sınıra veya kurala daraltır.
3. 0x85, 0x86 ve 0x87 için önce kimlik bilgilerini ve kimliği kontrol edin. MQTT connection refused: not authorized hatasını düzeltme rehberi bunu ayrıntılı olarak ele alır.
4. 0x93, 0x95, 0x96 ve 0x97 için sınırları kontrol edin: mesaj boyutu, hız, bağlantı sayısı ve iletimdeki mesajlar.
5. 0x8E için filo hijyenini kontrol edin: yinelenen client ID'ler, bağlantı kesme döngülerinin en yaygın nedenidir.

ConnectMQ'da Reason Code'lar

ConnectMQ MQTT 3.1.1 ve 5.0'ı destekler; bu yüzden MQTT 5 client'ları yukarıdaki reason code'ları alır. Plan kotaları 0x97 Quota exceeded olarak görünür; örneğin ücretsiz bir Serverless broker zaten maksimum 25 bağlantısına ulaşmışsa. Plan özellikleri de önemlidir: ücretsiz plan QoS 1'e kadar izin verir; bu yüzden bir QoS 2 subscription SUBACK'te daha düşük bir QoS ile verilir; QoS 2 ve shared subscription'lar ise ücretli Serverless planıyla gelir. Tekrarlanan başarısız girişler şüpheli kabul edilir ve kaynak IP engellenebilir; bu yüzden bir client'ı asla hatalı kimlik bilgileriyle sıkı bir döngüde yeniden denemeye bırakmayın.

Bir MQTT broker'ın bu kodlarla ne yaptığına dair arka plan veya protokolün bütün bağlamı için MQTT eğitimine bakın.

ConnectMQ ile Daha Hızlı Hata Ayıklayın

Tarayıcı içi istemcisi ve canlı topic gezgini olan yönetilen bir MQTT broker, başarısız bir publish'i veya subscription'ı yeniden üretmeyi çok daha hızlı hale getirir. app.connectmq.com adresinde, kredi kartı gerekmeden ücretsiz bir Serverless broker oluşturun ve hata işleme mantığınızı gerçek MQTT 5 yanıtlarına karşı test edin.

Sık Sorulan Sorular

Reason code ile return code arasındaki fark nedir?

Return code, altı CONNACK değeri için kullanılan MQTT 3.1.1 terimidir. MQTT 5 bu fikri, neredeyse her onayda ve DISCONNECT'te görünen reason code'lara genelleştirdi.

Hangi reason code'lar başarı anlamına gelir?

0x80'in altındaki her değer. Bunlara 0x00 Success, verilen QoS için 0x01 ve 0x02 ile 0x10 No matching subscribers gibi bilgilendirme değerleri dahildir.

MQTT reason code 0x97 ne anlama gelir?

0x97, Quota exceeded'dır: client maksimum bağlantı sayısı veya bir plan kısıtlaması gibi bir sınıra ulaşmıştır. Kullanımı azaltın veya daha yüksek sınırlara sahip bir plana geçin.

MQTT 3.1.1 client'ları MQTT 5 reason code'larını alır mı?

Hayır. Bir 3.1.1 bağlantısı yalnızca klasik CONNACK dönüş kodlarını ve 0x80 SUBACK hata değerini alır. Ayrıntılı reason code'ları almak için protokol sürümü 5 ile bağlanın.