LoRaWAN için ChirpStack MQTT Entegrasyonu: Çözümlenmiş Uplink'leri Bulut Broker'a İletin

ChirpStack MQTT entegrasyonu, kendi ağ sunucunuzdaki her LoRaWAN olayını bir MQTT broker'a yayınlar; bu da onu saha sensörü verilerini panolara ve otomasyona aktarmak için doğal bir başlangıç noktası yapar. Bu eğitimde entegrasyonu ChirpStack v4'te yapılandıracak, payload'ları bir cihaz profili codec'iyle çözümleyecek ve çözümlenmiş uplink'leri iki yolla bir bulut broker'a ileteceksiniz: kod gerektirmeyen bir Mosquitto köprüsü ve verileri kendi topic ağacınıza göre yeniden biçimlendiren bir Node.js iletici.

ChirpStack MQTT'yi Nasıl Kullanır?

ChirpStack açık kaynaklı bir LoRaWAN ağ sunucusudur. Tipik bir kurulumda (örneğin resmi Docker Compose kurulumu) MQTT iki kez karşınıza çıkar:

1. Ağ geçidi arka ucu. Ağ geçidi köprüleri ham radyo çerçevelerini yerel bir Mosquitto broker'a yayınlar, ChirpStack de bunlara abone olur.
2. MQTT entegrasyonu. Tekilleştirme, şifre çözme ve çözümlemeden sonra ChirpStack uygulama olaylarını (uplink'ler, join'ler, onaylar, hatalar) aynı yerel broker'daki MQTT topic'lerine yayınlar.

İstediğiniz şey entegrasyon olaylarıdır. Bunlar LoRaWAN sunucusunun ağı içindeki bir broker'da bulunur ve bu broker genellikle panolardan, telefonlardan veya diğer sahalardan erişilebilir değildir. Bunları bir bulut broker'a iletmek, ağ sunucusunun kendisini dışarıya açmadan bu sorunu çözer.

 Sensors ~~LoRa~~> Gateway --> local Mosquitto <--> ChirpStack
                                    |
                     application/.../event/up
                                    |
                  Mosquitto bridge or Node.js forwarder
                                    |   (TLS)
                                    v
                           Cloud MQTT broker --> Node-RED, dashboards, alerts

Adım 1: ChirpStack MQTT Entegrasyonunu Etkinleştirin

Standart bir kurulumda chirpstack.toml dosyasındaki entegrasyon bölümü şöyle görünür:

[integration]
  enabled = ["mqtt"]

  [integration.mqtt]
    server = "tcp://mosquitto:1883/"
    json = true

json = true ile olaylar Protobuf yerine JSON olarak gelir; bununla çalışmak çok daha kolaydır. Varsayılan olay topic'i şudur:

application/<application_id>/device/<dev_eui>/event/<event>

Burada <event>; up, join, ack, txack, log, status veya location değerlerinden biridir. Dosyayı değiştirdikten sonra ChirpStack'i yeniden başlatın, ardından sunucudaki yerel broker'ı izleyin:

mosquitto_sub -h localhost -p 1883 -t 'application/+/device/+/event/up' -v

Adım 2: Payload'ları Bir Codec ile Çözümleyin

Ham LoRaWAN payload'ları bayttır ve data alanında base64 kodlanmış olarak iletilir. ChirpStack'in her uplink'e çözümlenmiş bir object alanı eklemesi için cihaz profiline bir JavaScript codec'i ekleyin (Device profiles > profiliniz > Codec, tür JavaScript):

function decodeUplink(input) {
  var b = input.bytes;
  if (input.fPort !== 1 || b.length < 6) {
    return { errors: ["unexpected fPort or length"] };
  }
  var temp = (b[2] << 8) | b[3];
  if (temp & 0x8000) temp -= 0x10000;
  return {
    data: {
      moisture_pct: ((b[0] << 8) | b[1]) / 10,
      soil_temp_c: temp / 10,
      battery_v: ((b[4] << 8) | b[5]) / 1000
    }
  };
}

Bundan sonra bir uplink olayı, diğer alanların yanı sıra deviceInfo.deviceName, deviceInfo.devEui, fCnt, fPort, time, object (çözümlenmiş değerleriniz) ve rxInfo (her ağ geçidi için rssi ve snr içeren bir girdi) alanlarını içerir.

Seçenek A: Mosquitto Köprüsü ile İletme

ChirpStack zaten Mosquitto ile çalışıyorsa köprü en hızlı yoldur: birkaç satırlık yapılandırmayla Mosquitto eşleşen topic'leri bulut broker'a iletir ve otomatik olarak yeniden bağlanır. /etc/mosquitto/conf.d/cloud-bridge.conf dosyasını (veya Docker biriminizdeki karşılığını) oluşturun:

connection connectmq
address broker.connectmq.com:1883
remote_clientid cs-bridge-c3h7k5
cleansession true
try_private false
bridge_protocol_version mqttv311
notifications true
notification_topic connectmq/demo/c3h7k5/bridge/state

# yerel:  application/<app>/device/<eui>/event/up
# uzak:   connectmq/demo/c3h7k5/<app>/device/<eui>/event/up
topic +/device/+/event/up out 1 application/ connectmq/demo/c3h7k5/

topic satırı bir desen, bir yön, bir QoS ve iki önek alır. Mosquitto yerel önek olan application/ kısmını çıkarır ve uzak öneki ekler; bu da uzak topic'i, herkese açık test broker'ında izin verilen maksimum değer olan sekiz seviyede tutar. c3h7k5 değerini kendi rastgele dizenizle değiştirin; herkese açık alan paylaşımlıdır ve herkes tarafından okunabilir. Uzak broker Mosquitto değilse try_private false önerilir.

Mosquitto'yu yeniden başlatın ve herhangi bir yerden abone olun:

mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-c3h7k5 \
  -t 'connectmq/demo/c3h7k5/#' -v

Üretim için TLS'ye ve özel broker'ınızla birlikte verilen kimlik bilgilerine geçin:

connection connectmq
address broker.connectmq.com:8883
bridge_cafile /etc/ssl/certs/ca-certificates.crt
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
cleansession true
try_private false
notifications true
notification_topic farm1/lorawan/bridge/state
topic +/device/+/event/up out 1 application/ farm1/lorawan/

Köprünün sınırlaması, payload'ların değiştirilmeden iletilmesidir. ChirpStack olayları; base64 veri, iletim bilgisi ve tam ağ geçidi meta verileriyle oldukça ayrıntılıdır ve topic'ler okunabilir adlar yerine uygulama UUID'lerini ve DevEUI'leri kullanır.

Seçenek B: Node.js ile ChirpStack MQTT İletici

Tüketicilerin kompakt ve adlandırılmış veriler görmesi gerektiğinde küçük bir iletici daha iyidir. Bu örnek MQTT.js v5 kullanır, yerel broker'daki uplink'lere abone olur ve her cihaz için temiz bir kayıt yeniden yayınlar. npm install mqtt ile kurun.

// forwarder.mjs
import mqtt from "mqtt";

const LOCAL_URL = process.env.LOCAL_URL ?? "mqtt://localhost:1883";
const OUT_URL = process.env.OUT_URL ?? "mqtt://broker.connectmq.com:1883";
const OUT_PREFIX = process.env.OUT_PREFIX ?? "connectmq/demo/c3h7k5/farm";

const out = mqtt.connect(OUT_URL, {
  clientId: process.env.OUT_CLIENT_ID ?? "cs-forwarder-c3h7k5",
  username: process.env.OUT_USER,
  password: process.env.OUT_PASS,
  protocolVersion: 5,
  will: { topic: `${OUT_PREFIX}/forwarder/status`, payload: "offline", qos: 1, retain: true },
});
out.on("connect", () => {
  console.log("cloud broker connected");
  out.publish(`${OUT_PREFIX}/forwarder/status`, "online", { qos: 1, retain: true });
});
out.on("error", (err) => console.error("cloud:", err.message));

const local = mqtt.connect(LOCAL_URL, { clientId: "cs-forwarder-local-c3h7k5" });
local.on("connect", () => {
  local.subscribe("application/+/device/+/event/up", { qos: 1 });
  console.log("local broker connected");
});

local.on("message", (topic, payload) => {
  let ev;
  try {
    ev = JSON.parse(payload.toString());
  } catch {
    return console.warn("non-JSON event on", topic);
  }
  if (!ev.object) {
    return console.warn(`${ev.deviceInfo?.deviceName}: no decoded object, check the codec`);
  }
  const rx = ev.rxInfo ?? [];
  const best = rx.reduce((a, g) => ((g.rssi ?? -999) > (a.rssi ?? -999) ? g : a), {});
  const name = ev.deviceInfo.deviceName.replace(/[^A-Za-z0-9_-]/g, "_");
  const record = {
    ts: ev.time,
    dev_eui: ev.deviceInfo.devEui,
    ...ev.object,
    f_cnt: ev.fCnt,
    rssi: best.rssi ?? null,
    snr: best.snr ?? null,
    gateways: rx.length,
  };
  out.publish(`${OUT_PREFIX}/${name}/telemetry`, JSON.stringify(record), { qos: 1, retain: true });
  console.log(name, record);
});

ChirpStack'in yanında çalıştırın:

node forwarder.mjs
# üretim
OUT_URL=mqtts://broker.connectmq.com:8883 OUT_USER=YOUR_USERNAME \
OUT_PASS=YOUR_PASSWORD OUT_CLIENT_ID=YOUR_CLIENT_ID OUT_PREFIX=farm1/north \
node forwarder.mjs

+, # ve / gibi karakterler hiyerarşiyi bozacağı için cihaz adları topic'e eklenmeden önce temizlenir. Kayıtlar retained olarak yayınlanır; böylece LoRaWAN cihazları yalnızca 15 dakikada bir veri gönderse bile panolar her sensörün son ölçümünü anında görür.

İkisi Arasında Seçim Yapmak

Pek çok kurulum, veri akışını başlatmak için köprüyle başlar ve tüketiciler çoğaldıkça bir ileticiye geçer. The Things Network MQTT eğitimi aynı iletici fikrini Python ile uygular; çiftliğiniz topluluk ve özel LoRaWAN ağlarını bir arada kullanıyorsa bu faydalıdır.

ChirpStack Üzerinden Downlink Gönderme

Bir downlink'i kuyruğa almak için yerel broker'da cihazın komut topic'ine yayın yapın:

mosquitto_pub -h localhost -p 1883 \
  -t 'application/YOUR_APP_ID/device/0004a30b001c1234/command/down' \
  -m '{"devEui":"0004a30b001c1234","confirmed":false,"fPort":2,"data":"Hg=="}'

data base64 biçimindedir (Hg== tek bir bayt olan 30'dur; örneğin dakika cinsinden bir raporlama aralığı). Class A cihazlar bunu bir sonraki uplink'lerinden sonra alır. Downlink komutlarını buluttan yalnızca bunlara yayın yapabilen her client'a güveniyorsanız iletin ve ileticide doğrulayın.

Sorun Giderme

1. event/up üzerinde hiçbir şey yok. Cihazın ağa katıldığını (event/join arayın), entegrasyonun etkin olduğunu ve JSON bekliyorsanız json = true ayarlandığını kontrol edin.
2. object eksik. Codec yoktur, başarısız olmuştur veya hata döndürmüştür; event/log mesajları codec hatalarını gösterir.
3. Köprü bağlanıp ardından kopuyor. Yinelenen remote_clientid, yanlış kimlik bilgileri veya 8883 portu için eksik CA dosyası. Mosquitto günlüğü nedeni gösterir.
4. Mesajlar herkese açık broker'da reddediliyor. Topic sekiz seviyeyi aşıyordur ya da client saniyede on mesajı aşıyordur; daha kısa önekler kullanın ve log olaylarını oraya iletmeyin.

İletim Yolunu İzleme

Bir LoRaWAN hattında sessizce arızalanabilecek birkaç nokta vardır: bir ağ geçidinin gücü kesilir, bir codec düzenlemesinden sonra ChirpStack çözümlemeyi bırakır veya iletici çöker. Her katmanı ayrı ayrı izleyin. ChirpStack'in web arayüzü ağ geçitlerinin son görülme zamanlarını ve cihaz başına çerçeveleri gösterir. İleticinin son vasiyetle desteklenen retained status topic'i, ileticinin kendisinin çalışıp çalışmadığını gösterir; köprünün bildirim topic'i de Seçenek A için aynı işi görür. Son olarak, her cihazın retained telemetry mesajının yaşı, verilerin uçtan uca akmaya devam edip etmediğini söyler.

Bulut tarafında ConnectMQ canlı topic gezgini, bir codec değişikliğinden sonra kayıtların beklenen biçimde gelip gelmediğini doğrulamanın en hızlı yoludur; battery_v gibi bir alan için tanımlanan eşik uyarı kuralı da bir sensör sessizleşmeden önce erken uyarı verir.

Üretim Notları

Ağ sunucusunu ve ağ geçidi broker'ını özel tutun ve dışarıya giden tek yol olarak ileticiyi veya köprüyü kullanın. Böylece tam yönetilen bir MQTT hizmeti, LoRaWAN verileri, Wi-Fi cihazları ve kontrolcüler için ortak merkez haline gelir; buluttaki MQTT broker makalesi barındırma seçeneklerini karşılaştırır. Verilerle neler yapılabileceğini görmek için akıllı tarım IoT rehberi ve otomatik sulama sistemi projesi pratik kullanımlar gösterir; IoT otomasyon rehberi ise daha geniş resmi ele alır.

ChirpStack Verilerini ConnectMQ'ya İletin

ConnectMQ, LoRaWAN verilerinize canlı topic gezgini, pano ve düşük pil ya da don gibi değerler için eşik uyarı kuralları içeren, TLS ile korunan özel bir MQTT broker sunar. app.connectmq.com adresinde kredi kartı gerektirmeden ücretsiz bir Serverless broker oluşturun ve köprünüzü veya ileticinizi ona yönlendirin.

Sık Sorulan Sorular

ChirpStack v4 uplink'ler için hangi MQTT topic'ini kullanır?

Varsayılan olarak application/<application_id>/device/<dev_eui>/event/up kullanılır; MQTT entegrasyonunda json = true ayarlandığında payload'lar JSON olur.

ChirpStack doğrudan bir bulut broker'a yayın yapabilir mi?

Entegrasyonun server ayarını başka bir broker'a yönlendirebilirsiniz; ancak onu yerel tutup seçilen topic'leri iletmek, ağdan nelerin çıkacağı üzerinde size kontrol sağlar.

ChirpStack payload'ları neden base64?

data alanı, base64 olarak kodlanmış ham LoRaWAN baytlarını taşır. object alanında çözümlenmiş değerler almak için cihaz profiline bir codec ekleyin.

Mosquitto köprüsü internet kesildiğinde mesajları arabelleğe alır mı?

cleansession false ve QoS 1 ile Mosquitto, bağlantı kesikken yapılandırılmış kuyruk sınırları dahilinde köprü için mesajları kuyruğa alabilir. cleansession true ile kesinti sırasında yayınlanan mesajlar iletilmez.