MQTT istemcisi

MQTT istemci sürücüsü bir MQTT broker'ına bağlanır, topic'lere abone olur ve mesajlarını sinyal değerlerine çevirir. Değerlerini MQTT ile yayınlayan IoT ağ geçitleri, uç cihazlar ve diğer sistemler için kullanın. Tüm sürücülerin ortak yanları için bkz. Sürücüler nasıl çalışır.

YTCC içinde bir broker çalıştırmak için bkz. MQTT broker.

Protokol ve rol

Rol	MQTT istemcisi. YTCC topic'lere abone olur ve komutları yayınlar.
Sürüm	TCP üzerinden MQTT 3.1.1
Varsayılan port	1883
Sürücü başına cihaz	Bir cihaz bir broker bağlantısıdır.
Sürücü tipi	MQTT (mqtt)

Değerler yayıncı gönderdiğinde gelir; sürücü tarama yapmaz. Saklanan (retained) bir mesaj, sürücü abone olur olmaz sinyale ilk değerini verir.

Cihaz parametreleri

Bunları Drivers → devices görünümünde cihaz üzerinde ayarlayın (bkz. Sürücü ve cihaz ekleme). Boş kutu, içinde gösterilen varsayılanı kullanır. Her parametrenin yanındaki yardım işareti kısa bir açıklama gösterir.

Parametre	Varsayılan	Anlamı
Host	— (zorunlu)	Broker'ın IP adresi ya da host adı.
Port	1883	Broker'ın TCP portu, 1–65535.
Client ID (İstemci kimliği)	ytcc- ve sürücü anahtarı	Bağlantının broker'daki adı.
Username, Password (Kullanıcı, Parola)	boş	Kimlik bilgileri; yalnız ikisi de doluysa kullanılır.
Keep alive secs (Canlı tutma)	30	Canlı tutma mesajlarının aralığı, saniye.
Clean session (Temiz oturum)	açık	Her bağlantıyı önceki oturumun abonelikleri ve mesajları olmadan başlat.
Max inflight (Bekleyen en çok mesaj)	100	Onay bekleyen en çok QoS 1 ve 2 mesajı.
Set invalid on disconnect (Kopunca geçersiz yap)	açık	Bağlantı kopunca tüm sinyalleri Bad · Not connected yapar.
Max future skew secs	5	Mesajdaki cihaz zamanının geliş zamanından en çok kaç saniye ileride olabileceği; daha ileridekini sürücü atar. Bkz. Cihaz zamanı ve biriktirilmiş veri.
Max backfill age secs	604800 (7 gün)	Cihaz zamanının geliş zamanından en çok kaç saniye geride olabileceği; daha eskisini sürücü atar.
Backfill lag secs	10	Cihaz zamanı geliş zamanından bundan fazla gerideyse değer biriktirilmiş veri sayılır. Yalnız bir sayacı besler, başka bir şeyi değiştirmez.
Clamp future ts	kapalı	Açık: cihaz zamanı Max future skew secs değerinden fazla ileride olan değer atılmaz. Geliş zamanını ve device time invalid zaman kaynağını alır.
Seq pointer	boş	JSON mesajda sıra numarasının yeri, örneğin /seq. Boş: kayıp mesajlar sayılmaz. Bkz. Kayıp mesajlar.
Device ID pointer	boş	Sıra numaraları cihaz başına sayılsın diye JSON mesajda cihaz adının yeri, örneğin /dev. Boş: her topic bir cihaz sayılır.

Client ID broker'da benzersiz olmalıdır: aynı adla ikinci bir bağlantı, örneğin bir test projesinde aynı sürücü anahtarı, ilkini koparır ve ikisi de sürekli yeniden bağlanır. Her YTCC sistemine kendi istemci kimliğini verin.

Broker'ı ve YTCC'yi korunan bir ağda tutun. YTCC'ye broker'da kendi kullanıcısını verin; broker topic izinlerini destekliyorsa bu kullanıcıyı yalnız gereken topic'lerle sınırlayın.

Sinyal adresi

Adresi sinyalin Value source (Değer kaynağı) sekmesinde, Address — MQTT altında ayarlayın:

Alan	Varsayılan	Anlamı
Topic	—	Topic'in tam adı, örneğin site/line1/pump1/current.
Payload (Yük)	Raw	Raw: mesaj, metin olarak değerin kendisidir. JSON: değer bir JSON mesajından alınır.
JSON pointer (JSON işaretçisi)	boş	JSON ile: değerin mesajdaki yeri, örneğin /value ya da /data/0/temp. Boş, mesajın tamamını kullanır.
QoS	0	Aboneliğin ve komutların hizmet kalitesi: 0, 1 ya da 2.
Time pointer (Zaman işaretçisi)	boş	JSON ile: cihaz zamanının mesajdaki yeri, örneğin /ts. Boş: değer geliş zamanını alır.
Time format (Zaman biçimi)	auto	auto, epoch ms, epoch s ya da RFC 3339. auto, 10^11'den büyük sayıyı 1970'ten (UTC) beri milisaniye, küçüğünü saniye olarak; metni saat dilimli RFC 3339 olarak okur, örneğin ...Z ya da ...+03:00.
Batch array (Toplu dizi)	boş	Değer listesi taşıyan mesajda listenin yeri, örneğin /values. JSON pointer ve Time pointer bu durumda listenin bir girişine göredir, örneğin /v ve /ts.
Batch ID field (Toplu kimlik alanı)	tag	Liste girişinde değerin adını taşıyan alan.
Batch ID (Toplu kimlik)	sinyal yolu	Bu sinyalin o alandaki adı, örneğin speed. Sayı metin olarak karşılaştırılır.

İçe aktarma dosyalarında topic'i address sütununa yazın; yük ve QoS varsayılanlarını, Raw ve 0, alır.

Yükler

Yük	Örnek mesaj	Değer
Raw	42.5	42.5
Raw	true, false	Açık ya da kapalı
Raw	RUN	Metin
JSON, işaretçi /value	{"value": 42.5, "unit": "A"}	42.5
JSON, işaretçi /state/run	{"state": {"run": true}}	Açık

Bir JSON değeri sayı, true ya da false veya metin olmalıdır. Çözülemeyen bir mesaj (metin değil, boş, geçersiz JSON, işaretçi bulunamadı ya da değer bir liste veya nesne) sinyali Bad yapar. Bad bir sinyalin değerini kullanmayın.

Her sinyalin kendi topic'i vardır. Tek bir JSON mesajından birkaç değer okumak için her değere aynı topic ve farklı JSON işaretçisiyle bir sinyal oluşturun.

Cihaz zamanı ve biriktirilmiş veri

Birçok saha cihazı, örneğin mobil ağdaki araç üstü birimler ve RTU'lar, bağlantı yokken değerlerini saklar ve bağlantı gelince onları özgün zamanlarıyla gönderir. Bu zamanı okumak için Time pointer'ı ayarlayın. İki mesaj biçimi okunur.

Zamanıyla tek bir değer (JSON pointer /v, Time pointer /ts):

{ "v": 42.5, "ts": 1760090400123 }

Bir değer listesi (Batch array /values, Batch ID field tag, JSON pointer /v, Time pointer /ts ve her sinyalde kendi Batch ID'si). Kendi ts'i olmayan giriş mesajın en üstündeki ts'i alır:

{
  "ts": 1760090400000,
  "values": [
    { "tag": "speed",       "ts": 1760090400123, "v": 42.5 },
    { "tag": "door_1_open", "ts": "2025-10-10T09:00:00.500Z", "v": true }
  ]
}

Adı hiçbir sinyale uymayan girişler atlanır, mesajda olmayan sinyaller olduğu gibi kalır. Değeri olmayan giriş sinyalini Bad yapar. Zaman alanı yoksa değer geliş zamanını alır; okunamayan zaman alanı geliş zamanını device time invalid zaman kaynağıyla verir.

Her değer sonra cihaz zamanına göre işlenir:

Cihaz zamanı	Tarihçe	Güncel değer	Canlı alarm, betik onChange
Yok	Geliş zamanıyla saklanır	Güncellenir	Evet
Sinyalin son cihaz zamanından eski değil	Cihaz zamanıyla saklanır	Güncellenir	Evet
Son cihaz zamanından eski (geç)	Özgün zamanıyla saklanır	Değişmez	Hayır
Gelişten Max future skew secs değerinden fazla ileride	Atılır	—	—
Aynısı, Clamp future ts açıkken	Geliş zamanıyla, device time invalid zaman kaynağıyla saklanır	Güncellenir	Evet
Gelişten Max backfill age secs değerinden fazla geride	Atılır	—	—
Aynı sinyal, zaman ve değer yeniden geldi, örneğin QoS 1 yeniden teslimi	Yeniden saklanmaz	—	—
Aynı sinyal ve zaman, başka bir değerle	Saklanır	Güncellenir (sonra gelen geçerli olur)	Evet

Geçerli ve geçersiz girişleri olan bir mesajda yalnız geçersizler atılır. Birden çok sinyal aynı topic'i kullanabilir; her biri mesajı okur.

• Atılan değerler sürücü günlüğüne, en çok dakikada bir ve atılan sayısıyla yazılır.
• Cihaz tarafı için: kalıcı oturumla QoS 1 kullanın, biriken değerleri eskiden yeniye 100 ile 500 arası gruplar halinde gönderin, canlı değerleri tampondan önce gönderin ve cihaz saatini senkronlayın. Saate güvenilemiyorsa zaman göndermeyin; YTCC geliş zamanını kullanır. İleri giden saati Max future skew secs'i büyüterek değil, saati düzelterek çözün. Saat düzeltilemiyor ama değerler gerekiyorsa Clamp future ts'i açın: değerler cihaz zamanı yerine geliş zamanıyla tutulur.

Geç gelen değerlerin ekranlarda, alarmlarda ve betiklerde nasıl işlendiği Zaman damgaları ve saat dilimleri sayfasında anlatılır.

Kayıp mesajlar

Mesajlarını numaralayan bir cihazda mesaj kaybı görünür olur, örneğin kesinti sırasında tamponu taştığında. Seq pointer'ı numaranın yerine ayarlayın, örneğin {"dev": "OBU-1", "seq": 918273, "values": [...]} mesajında /seq. Aynı topic'e birden çok cihaz yazıyorsa Device ID pointer'ı da ayarlayın, örneğin /dev; ayarlanmazsa topic cihaz yerine geçer.

Sürücü her cihazın son numarasını tutar ve sonraki mesajla karşılaştırır:

• Son numaranın bir fazlası beklenir. Daha büyük numara bir boşluk, aradaki numaralar kayıp mesaj sayılır.
• Daha büyük bir numaradan sonra gelen 0 ya da 1, cihazın yeniden başlaması sayılır.
• Daha küçük numara, örneğin QoS 1 yeniden teslimi, yok sayılır.
• Numara JSON sayısı ya da sayı içeren bir metin olabilir. Alanı olmayan mesaj sayılmaz.
• Sürücü başına en çok 100 000 cihaz izlenir; fazlası sayılmaz.

Sayım kayıp mesajları geri getirmez ve hiçbir değeri değiştirmez. Boşluk, cihaz ve kayıp mesaj sayısıyla, en çok dakikada bir uyarı olarak sürücü günlüğüne yazılır. Sürücü günlüğüne 60 saniyede bir, değiştiyse boşluk, kayıp mesaj ve yeniden başlama toplamları da cihaz zamanı sayaçlarıyla birlikte yazılır.

Yazma

Access'i Read / Write ya da Write only olan bir sinyal yazılabilir. Komut sinyalin topic'ine, onun QoS'iyle, saklanmadan, düz metin olarak yayınlanır: true ya da false, veya sayı ya da metin.

• Sonuç Unconfirmed'dır (Doğrulanmadı): broker'ın mesajı kabul etmesi cihazın onu uyguladığı anlamına gelmez.
• Cihazın durumunu görmek için durumu cihazın kendi durum topic'inde ayrı bir sinyale bağlayın.
• Broker bağlı değilken komut hemen reddedilir; komutlar saklanıp sonra gönderilmez.

Operatörlerin komutu nasıl gönderip onayladığı için bkz. Komut gönderme.

Kalite

Durum	Kalite
Mesaj çözüldü	Good
Mesaj çözülemedi	Bad
Broker bağlantısı koptu	Bad · Not connected (Set invalid on disconnect ile); son değer kalır

Time pointer ayarlı değilse bir değer geldiği anın zamanını alır (bkz. Cihaz zamanı ve biriktirilmiş veri). Yeniden bağlandıktan sonra bir sinyal bir sonraki mesajı gelene kadar Bad · Not connected kalır; saklanan mesaj hemen gelir.

Yeniden bağlanma

Bağlantı kopunca sürücü her 2 saniyede bir yeniden dener ve tüm topic'lere yeniden abone olur. Host, Port, istemci kimliği ya da kimlik bilgileri değişince yeniden bağlanır; sinyal eklemek ya da kaldırmak abonelikleri yeniden bağlanmadan değiştirir.

Tanılama

Değerler abonelikle geldiği için Read now broker'ı okumaz. Altındaki satır sinyalin son hatasını gösterir, örneğin:

Metin	Anlamı
Payload is not valid JSON: …	Payload JSON, mesaj değil
JSON pointer … not found in payload	İşaretçi mesaja uymuyor
JSON value at … is not a number, boolean or string	İşaretçi bir liste ya da nesneyi gösteriyor
Payload is not UTF-8 text, Empty payload	Mesaj ikili ya da boş

Belirti	Olası neden
Cihaz hiç bağlanmıyor	Yanlış host ya da port, broker kullanıcı istiyor, kullanıcı ya da parola yanlış
Bağlı, bir sinyal hiç değer almıyor	Topic farklı (büyük/küçük harf önemli) ya da sürücü başladığından beri yayın yapılmadı ve mesaj saklanan değil
Bağlantı birkaç saniyede bir kopuyor	Başka bir istemci aynı Client ID'yi kullanıyor
Bir sinyal Bad	Mesaj Payload ya da JSON pointer ile uyuşmuyor