Eclipse Ditto MQTT Eğitimi: Yönetilen Bir Broker Üzerinde Açık Kaynak Dijital İkizler

Eclipse Ditto'yu MQTT ile kullanmak, açık kaynak dijital ikizler oluşturmanın en pratik yollarından biridir: cihazlar bir broker'a yayınlar, Ditto her cihazın bir JSON ikizini tutar ve uygulamalar ikiz durumunu bir API üzerinden okur veya değişiklik olaylarını alır. Bu eğitimde Ditto'yu yerel olarak çalıştıracak, bir thing oluşturacak, Ditto'yu bir MQTT broker'a bağlayacak, sade cihaz JSON'unu ikiz özelliklerine (feature) eşleyecek ve ikiz olaylarını MQTT'ye geri yayınlayacaksınız.

Bir ikiz servisinin nereye oturduğuna dair bağlam için dijital ikiz teknolojisi rehberine bakın.

Eclipse Ditto Ne Yapar

Eclipse Ditto, Eclipse Foundation'ın dijital ikizleri yönetmek için geliştirdiği açık kaynak bir çerçevedir. Sensörlerle doğrudan konuşmaz. Bunun yerine her cihaz için thing adı verilen bir ikiz belgesi tutar ve size şunları sunar:

• İkizleri okumak ve değiştirmek için bir REST ve WebSocket API'si.
• Kimin bir ikizin hangi bölümünü okuyabileceğini veya yazabileceğini kontrol eden politikalar.
• MQTT 3.1.1 ve MQTT 5 dahil harici broker'lara bağlanan bir bağlantı servisi (connectivity service).
• Rastgele cihaz mesajlarını ikiz güncellemelerine dönüştüren payload eşleme.
• Değişiklik olayları ve tüm thing'ler üzerinde arama.

Bir thing'in öznitelikleri (attributes) (konum veya seri numarası gibi çoğunlukla statik meta veriler) ve özellikleri (features) vardır (her biri bildirilen değerler için properties ve isteğe bağlı olarak hedef değerler için desiredProperties içeren işlevsel parçalar). Bu, dijital ikiz durum senkronizasyonu yazısında anlatılan bildirilen ve istenen (reported vs desired) kalıbıyla güzel bir şekilde örtüşür.

Bir Eclipse Ditto MQTT Kurulumunun Mimarisi

devices --publish--> MQTT broker <--subscribe/publish-- Ditto connectivity
                         |                                   |
                         |                             Ditto things (twins)
                         |                                   |
dashboards <--subscribe--+                 REST / WebSocket API for apps

Ditto broker'a sıradan bir MQTT istemcisi olarak bağlanır. Bu, broker'ın standartlara uyan herhangi bir broker olabileceği anlamına gelir: yerel bir Mosquitto, denemeler için herkese açık MQTT test broker'ı veya üretimde ConnectMQ gibi yönetilen bir MQTT broker.

Adım 1: Eclipse Ditto'yu Docker ile Çalıştırın

Ditto deposu bir Docker Compose kurulumuyla gelir. Depoyu klonlayın ve yığını başlatın:

git clone https://github.com/eclipse-ditto/ditto.git
cd ditto/deployment/docker
docker compose up -d

Container'lar sağlıklı duruma geldikten sonra API, nginx üzerinden http://localhost:8080 adresinde kullanılabilir. Varsayılan geliştirme kimlik bilgileri API için ditto / ditto, bağlantılar gibi yönetim uç noktaları için devops / foobar şeklindedir. Ditto'yu herhangi bir yere açmadan önce bunları değiştirin. Eclipse Ditto dokümantasyonu dağıtım seçeneklerini ayrıntılı olarak açıklar.

Adım 2: Bir Thing Oluşturun

Bir pompa için ikiz oluşturun. Açık bir politika belirtmeden bir thing oluşturduğunuzda Ditto, kimliği doğrulanmış özneye (nginx kurulumunda nginx:ditto) tam erişim veren varsayılan bir politika oluşturur.

curl -u ditto:ditto -X PUT -H "Content-Type: application/json" \
  http://localhost:8080/api/2/things/acme:pump-01 \
  -d '{
    "attributes": { "site": "plant1", "line": "water", "model": "CP-200" },
    "features": {
      "flow": { "properties": { "value": 0, "unit": "l/min" } },
      "pressure": { "properties": { "value": 0, "unit": "bar" } },
      "motor": { "properties": { "running": false } }
    }
  }'

curl -u ditto:ditto http://localhost:8080/api/2/things/acme:pump-01 ile geri okuyun.

Adım 3: Bir MQTT Bağlantısı Ekleyin

Şimdi Ditto'ya broker'a bağlanmasını söyleyin. Aşağıdaki örnek, benzersiz bir topic önekiyle herkese açık broker'a karşı MQTT 5 kullanır. e3b9 değerini kendi rastgele metninizle değiştirin.

{
  "name": "connectmq-demo",
  "connectionType": "mqtt-5",
  "connectionStatus": "open",
  "uri": "tcp://broker.connectmq.com:1883",
  "specificConfig": {
    "clientId": "ditto-e3b9",
    "separatePublisherClient": "false"
  },
  "sources": [
    {
      "addresses": ["connectmq/demo/e3b9/devices/+/telemetry"],
      "authorizationContext": ["nginx:ditto"],
      "qos": 1,
      "payloadMapping": ["telemetry"]
    }
  ],
  "targets": [
    {
      "address": "connectmq/demo/e3b9/twins/{{ thing:name }}/events",
      "topics": ["_/_/things/twin/events"],
      "authorizationContext": ["nginx:ditto"],
      "qos": 0
    }
  ],
  "mappingDefinitions": {
    "telemetry": {
      "mappingEngine": "JavaScript",
      "options": {
        "incomingScript": "function mapToDittoProtocolMsg(headers, textPayload, bytePayload, contentType) { var name = headers['mqtt.topic'].split('/')[4]; var d = JSON.parse(textPayload); var value = { flow: { properties: { value: d.flow, unit: 'l/min' } }, pressure: { properties: { value: d.pressure, unit: 'bar' } }, motor: { properties: { running: d.running } } }; return Ditto.buildDittoProtocolMsg('acme', name, 'things', 'twin', 'commands', 'merge', '/features', headers, value); }"
      }
    }
  }
}

Bunu connection.json olarak kaydedin ve devops kullanıcısıyla bağlantılar API'si üzerinden oluşturun:

curl -u devops:foobar -X POST -H "Content-Type: application/json" \
  http://localhost:8080/api/2/connections -d @connection.json

Bu yapılandırmadaki önemli noktalar:

• separatePublisherClient değerinin false olması, Ditto'nun her iki yön için tek bir MQTT istemcisi kullanmasını sağlar. Varsayılan olarak Ditto türetilmiş bir client ID ile ikinci bir istemci açabilir; bu da ConnectMQ'nun üretim broker'larında yaptığı gibi client ID'leri verilen kimlik bilgilerine bağlayan broker'larda başarısız olur.
• Kaynak (source), tek seviyeli bir wildcard ile her cihazın telemetrisine abone olur.
• JavaScript eşlemesi, cihaz adını topic'ten çıkarır ve sade JSON'u /features üzerinde bir Ditto merge komutuna dönüştürür; böylece cihazların Ditto Protocol'ü bilmesine hiç gerek kalmaz.
• Hedef (target), her ikiz değişiklik olayını thing başına bir olay topic'ine yayınlar.

Üretim için URI'yi ssl://YOUR_BROKER_HOST:8883 olarak değiştirin, clientId değerini YOUR_CLIENT_ID yapın ve ConnectMQ portalından aldığınız kimlik bilgilerini ekleyin; örneğin ssl://YOUR_USERNAME:YOUR_PASSWORD@YOUR_BROKER_HOST:8883.

Adım 4: Cihaz Telemetrisi Yayınlayın

Pompayı mosquitto_pub ile simüle edin. Beşinci topic seviyesi, eşleme betiğinin çıkardığı thing adıdır:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pump-01-e3b9 -q 1 \
  -t "connectmq/demo/e3b9/devices/pump-01/telemetry" \
  -m '{"flow": 418.5, "pressure": 3.7, "running": true}'

İkizi kontrol edin:

curl -u ditto:ditto http://localhost:8080/api/2/things/acme:pump-01/features

Yeni debi, basınç ve çalışma değerlerini görmelisiniz.

Adım 5: İkiz Olaylarını MQTT Üzerinden Tüketin

Artık herhangi bir uygulama Ditto API'sini çağırmadan ikiz değişikliklerini takip edebilir. Olay topic'ine abone olun:

mosquitto_sub -h broker.connectmq.com -p 1883 -i events-viewer-e3b9 \
  -t "connectmq/demo/e3b9/twins/+/events" -v

Başka bir telemetri mesajı yayınlayın; acme/pump-01/things/twin/events/merged topic'ini, yolu ve değişen değeri içeren bir Ditto Protocol olayı görünür. Panolar ve 3D görüntüleyiciler bu olaylara abone olabilir ya da ikiz başına politika uygulanmış erişime ihtiyaç duyuyorlarsa Ditto'nun WebSocket API'sine bağlanabilir.

Eclipse Ditto ve MQTT İçin Üretim Değerlendirmeleri

Bu yerel kurulumdan üretime geçmek, gözden kaçması kolay birkaç karar gerektirir:

• Kimlik bilgileri ve politikalar. Varsayılan nginx kullanıcılarını kimlik sağlayıcınızla değiştirin ve varsayılan politikaya güvenmek yerine thing başına veya thing grubu başına açık politikalar oluşturun. Bağlantının yetkilendirme bağlamı (authorization context), yalnızca ihtiyaç duyduğu izinlere sahip özel bir özne olmalıdır.
• Topic sözleşmeleri. Eşleme betiğinin beklediği topic düzenini belgeleyin. Cihaz firmware'i topic derinliğini değiştirirse betiğin indekse dayalı çıkarımı sessizce bozulur; bu yüzden girdileri doğrulayın ve reddedilen mesajları kaydedin.
• Veri hacmi. Ditto her ikiz değişikliğini kalıcı olarak saklar. Her yüksek frekanslı örneği ona göndermek israftır; cihazların değişiklik olduğunda veya makul bir hızda yayınlamasına izin verin ve tam frekanslı veriyi ayrı bir zaman serisi abonesine gönderin.
• İstenen durum. Uygulamalar desiredProperties ayarlıyorsa, bu değişiklikleri bir cihaz komut topic'ine yayınlayan bir hedef ekleyin ve cihazların aynı telemetri yolu üzerinden geri bildirim yapmasını sağlayın.
• İzleme. Bağlantı durumunu ve broker'ın topic etkinliğini birlikte izleyin; böylece bayat bir ikizin cihazdan mı, broker'dan mı yoksa eşlemeden mi kaynaklandığını anlayabilirsiniz.

Eclipse Ditto MQTT Bağlantılarında Sorun Giderme

Bağlantı komutları uç noktası üzerinden günlük kaydını etkinleştirdikten sonra bağlantı teşhis bilgilerini GET /api/2/connections/{connectionId}/status ve /logs ile alın.

Ditto mu, Retained Topic'ler mi?

Ditto; API'ler, politikalar, arama ve değişiklik geçmişi içeren bir ikiz servisi ekler. Görüntüleyicilerin yalnızca güncel durumu yüklemesine ihtiyacınız varsa retained MQTT topic'leri yeterli olabilir ve ek altyapı gerektirmez; bkz. retained MQTT ile dijital ikiz. Çok sayıda ikiz üzerinde sorgulara, ikiz başına ayrıntılı erişim kontrolüne, istenen özelliklere veya iş uygulamaları için bir REST API'ye ihtiyacınız olduğunda Ditto'yu seçin. Her birinin eksiksiz bir yığında nereye oturduğu için dijital ikiz mimarisi yazısını okuyun.

Eclipse Ditto'yu ConnectMQ Üzerinde Çalıştırın

İkizleri Ditto yönetir; mesajlaşmayı ConnectMQ üstlenir. MQTT 3.1.1 ve 5.0, 8883'te TLS ve telemetriyi ve Ditto olaylarını yan yana izlemek için canlı bir topic gezgini sunan bir bulut MQTT broker olarak, kendi broker'ınızı işletme yükünü ortadan kaldırır. app.connectmq.com adresinden kaydolun, kredi kartı olmadan ücretsiz Serverless planla bir broker oluşturun ve kimlik bilgilerini Ditto bağlantınıza girin.

Sık Sorulan Sorular

Eclipse Ditto bir MQTT broker içeriyor mu?

Hayır. Ditto, bağlantı servisi aracılığıyla harici bir MQTT broker'a istemci olarak bağlanır; bu yüzden broker'ı ayrıca seçer ve işletirsiniz ya da yönetilen bir broker kullanırsınız.

Ditto MQTT 5 kullanabilir mi?

Evet. MQTT 5 için connectionType değerini mqtt-5, MQTT 3.1.1 için mqtt olarak ayarlayın.

Cihazların Ditto Protocol mesajları göndermesi gerekir mi?

Hayır. Yukarıdaki JavaScript örneği gibi bir payload eşlemesiyle cihazlar sade JSON yayınlayabilir ve Ditto bunu ikiz komutlarına dönüştürür.

İstenen değerleri Ditto'dan cihazlara nasıl gönderirim?

Bir feature üzerindeki desiredProperties değerini güncelleyin ve bu değişiklikleri yayınlayan bir hedef ekleyin ya da cihazın abone olduğu bir cihaz komut topic'ine live mesajlar gönderin.