IoT Tak Çalıştır kuralları

  • Makale

IoT Tak Çalıştır cihazlar Bir IoT hub'ı ile ileti alışverişi yaparken bir dizi kuralı izlemelidir. IoT Tak Çalıştır cihazlar IoT Hub ile iletişim kurmak için MQTT protokollerini kullanır. IoT Hub, bazı IoT cihaz SDK'larında kullanılabilen AMQP protokollerini de destekler.

Bir cihaz modülleri içerebilir veya IoT Edge çalışma zamanı tarafından barındırılan bir IoT Edge modülünde uygulanabilir.

bir IoT Tak Çalıştır cihazının Digital Twins Tanım Dili (DTDL) modeliyle uyguladığı telemetriyi, özellikleri ve komutları açıklarsınız. Bu makalede başvuruda bulunılan iki model türü vardır:

  • Bileşen yok - Bileşeni olmayan bir model. Model, ana arabirimin içindekiler bölümünde telemetriyi, özellikleri ve komutları üst düzey öğeler olarak bildirir. Azure IoT gezgini aracında bu model tek bir varsayılan bileşen olarak görünür.
  • Birden çok bileşen - İki veya daha fazla arabirimden oluşan bir model. Telemetri, özellikler ve komutlarla varsayılan bileşen olarak görünen bir ana arabirim. Daha fazla telemetri, özellik ve komut içeren bileşen olarak bildirilen bir veya daha fazla arabirim.

Daha fazla bilgi için bkz. IoT Tak Çalıştır modelleme kılavuzu.

Modeli tanımlama

Uyguladığı modeli duyurmak için bir IoT Tak Çalıştır cihazı veya modülü alana ekleyerek model-id MQTT bağlantı paketinde USERNAME model kimliğini içerir.

Bir cihaz veya modülün uyguladığı modeli tanımlamak için bir hizmet, model kimliğini şu kaynaktan alabilir:

  • Cihaz ikizi modelId alanı.
  • Dijital ikiz $metadata.$model alanı.
  • Dijital ikiz değişiklik bildirimi.

Telemetri

  • Bileşensiz bir cihazdan gönderilen telemetri için ek meta veriler gerekmez. Sistem özelliğini ekler dt-dataschema .
  • Bileşenler kullanılarak bir cihazdan gönderilen telemetri, bileşen adını telemetri iletisine eklemelidir.
  • MQTT kullanırken, bileşen adıyla özelliğini telemetri konusuna ekleyin $.sub , sistem özelliğini ekler dt-subject .
  • AMQP kullanırken, bileşen adıyla özelliğini ileti ek açıklaması olarak ekleyin dt-subject .

Not

Bileşenlerden telemetri için bileşen başına bir ileti gerekir.

Diğer telemetri örnekleri için bkz. Yük Telemetrisi >

Salt okunur özellikler

Cihaz, daha sonra arka uç uygulamasına rapor veren salt okunur bir özellik ayarlar.

Örnek bileşen salt okunur özelliği yok

Bir cihaz veya modül, DTDL kurallarını izleyen geçerli JSON'ları gönderebilir.

Bir arabirimde bir özelliği tanımlayan DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

Örnek bildirilen özellik yükü:

"reported" :
{
  "temperature" : 21.3
}

Örnek birden çok bileşen salt okunur özelliği

Cihazın veya modülün {"__t": "c"} , öğenin bir bileşene başvurduğunu belirtmek için işaretçiyi eklemesi gerekir.

Bir bileşene başvuran DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

Bileşeni tanımlayan DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

Örnek bildirilen özellik yükü:

"reported": {
  "thermostat1": {
    "__t": "c",
    "temperature": 21.3
  }
}

Daha fazla salt okunur özellik örneği için bkz . Payloads > Özellikleri.

Yazılabilir özellikler

Arka uç uygulaması, IoT Hub'ın cihaza gönderdiği yazılabilir bir özellik ayarlar.

Cihaz veya modül, bildirilen bir özellik göndererek özelliği aldığını onaylamalıdır. Bildirilen özellik şunları içermelidir:

  • value - özelliğin gerçek değeri (genellikle alınan değerdir, ancak cihaz farklı bir değer bildirmeye karar verebilir).
  • ac - HTTP durum kodu kullanan bir bildirim kodu.
  • av - istenen özelliğin başvuruda $version bulunan bir bildirim sürümü. Bu değeri istenen JSON yükü özelliğinde bulabilirsiniz.
  • ad - isteğe bağlı bir bildirim açıklaması.

Bildirim yanıtları

Yazılabilir özellikler bildirildiğinde cihaz, aşağıdaki tabloda açıklandığı gibi gerçek cihaz durumunu belirtmek için önceki listedeki dört alanı kullanarak bildirim iletisini oluşturmalıdır:

Durum(ac) Sürüm(av) Değer(değer) Açıklama(av)
200 İstenen sürüm İstenen değer İstenen özellik değeri kabul edildi
202 İstenen sürüm Cihaz tarafından kabul edilen değer İstenen özellik değeri kabul edildi, güncelleştirme sürüyor (200 ile bitmelidir)
203 0 Cihaz tarafından ayarlanan değer Cihazdan ayarlanan özellik, herhangi bir isteneni yansıtmaz
400 İstenen sürüm Cihaz tarafından kullanılan gerçek değer İstenen özellik değeri kabul edilmedi
500 İstenen sürüm Cihaz tarafından kullanılan gerçek değer özelliği uygulanırken özel durum

Cihaz başlatıldığında cihaz ikizini istemeli ve yazılabilir özellik güncelleştirmelerini denetlemelidir. Yazılabilir özelliğin sürümü cihaz çevrimdışıyken artırıldıysa, cihazın güncelleştirmeyi aldığını onaylamak için bildirilen bir özellik yanıtı göndermesi gerekir.

Bir cihaz ilk kez başlatıldığında, IoT hub'ından istenen ilk özelliği almazsa bildirilen bir özellik için başlangıç değeri gönderebilir. Bu durumda, cihaz ile av0ac203varsayılan değeri ve adresine gönderebilir. Örneğin:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 203,
    "av": 0,
    "ad": "initialize"
  }
}

Bir cihaz, hub'a başka bilgiler sağlamak için bildirilen özelliği kullanabilir. Örneğin, cihaz aşağıdakiler gibi bir dizi devam eden iletiyle yanıt verebilir:

"reported": {
  "targetTemperature": {
    "value": 35.0,
    "ac": 202,
    "av": 3,
    "ad": "In-progress - reporting current temperature"
  }
}

Cihaz hedef sıcaklığa ulaştığında aşağıdaki iletiyi gönderir:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 200,
    "av": 4,
    "ad": "Reached target temperature"
  }
}

Bir cihaz şu gibi bir hata bildirebilir:

"reported": {
  "targetTemperature": {
    "value": 120.0,
    "ac": 500,
    "av": 3,
    "ad": "Target temperature out of range. Valid range is 10 to 99."
  }
}

Object type

Yazılabilir bir özellik nesne olarak tanımlanırsa, hizmetin cihaza tam bir nesne göndermesi gerekir. Cihazın güncelleştirmede nasıl davrandığını anlamak için hizmetin hizmetine yeterli bilgi göndererek güncelleştirmeyi kabul etmesi gerekir. Bu yanıt şunları içerebilir:

  • Nesnenin tamamı.
  • Yalnızca cihazın güncelleştirmiş olduğu alanlar.
  • Alanların alt kümesi.

Büyük nesneler için bildirime eklediğiniz nesnenin boyutunu en aza indirmeyi göz önünde bulundurun.

Aşağıdaki örnekte, dört alanla birlikte olarak tanımlanan yazılabilir bir Object özellik gösterilmektedir:

DTDL:

{
  "@type": "Property",
  "name": "samplingRange",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "startTime",
        "schema": "dateTime"
      },
      {
        "name": "lastTime",
        "schema": "dateTime"
      },
      {
        "name": "count",
        "schema": "integer"
      },
      {
        "name": "errorCount",
        "schema": "integer"
      }
    ]
  },
  "displayName": "Sampling range"
  "writable": true
}

Bu yazılabilir özelliği güncelleştirmek için hizmetten aşağıdaki örneğe benzer tam bir nesne gönderin:

{
  "samplingRange": {
    "startTime": "2021-08-17T12:53:00.000Z",
    "lastTime": "2021-08-17T14:54:00.000Z",
    "count": 100,
    "errorCount": 5
  }
}

Cihaz aşağıdaki örneğe benzer bir bildirimle yanıt verir:

{
  "samplingRange": {
    "ac": 200,
    "av": 5,
    "ad": "Weighing status updated",
    "value": {
      "startTime": "2021-08-17T12:53:00.000Z",
      "lastTime": "2021-08-17T14:54:00.000Z",
      "count": 100,
      "errorCount": 5
    }
  }
}

Örnek yazılabilir bileşen yok özelliği

Bir cihaz tek bir yükte istenen birden çok özelliği aldığında, bildirilen özellik yanıtlarını birden çok yük arasında gönderebilir veya yanıtları tek bir yükte birleştirebilir.

Bir cihaz veya modül, DTDL kurallarını izleyen geçerli JSON'ları gönderebilir.

DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    },
    {
      "@type": "Property",
      "name": "targetHumidity",
      "schema": "double",
      "writable": true
    }
  ]
}

örnek istenen özellik yükü:

"desired" :
{
  "targetTemperature" : 21.3,
  "targetHumidity" : 80,
  "$version" : 3
}

Örnek bildirilen özellik ilk yükü:

"reported": {
  "targetTemperature": {
    "value": 21.3,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

Örnek bildirilen özellik ikinci yükü:

"reported": {
  "targetHumidity": {
    "value": 80,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

Not

Bildirilen bu iki özellik yükünü tek bir yükte birleştirmeyi seçebilirsiniz.

Yazılabilir özellik için birden çok bileşen örneği

Cihazın veya modülün {"__t": "c"} , öğenin bir bileşene başvurduğunu belirtmek için işaretçiyi eklemesi gerekir.

İşaretçi yalnızca bir bileşende tanımlanan özelliklere yönelik güncelleştirmeler için gönderilir. Varsayılan bileşende tanımlanan özelliklere Güncelleştirmeler işaretçiyi içermez, bkz.Örnek hiçbir bileşen yazılabilir özelliği.

Bir cihaz tek bir yükte birden çok bildirilen özellik aldığında, bildirilen özellik yanıtlarını birden çok yük arasında gönderebilir veya yanıtları tek bir yükte birleştirebilir.

Cihaz veya modül, bildirilen özellikleri göndererek özellikleri aldığını onaylamalıdır:

Bir bileşene başvuran DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

Bileşeni tanımlayan DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    }
  ]
}

örnek istenen özellik yükü:

"desired": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": 21.3,
    "targetHumidity": 80,
    "$version" : 3
  }
}

Örnek bildirilen özellik ilk yükü:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": {
      "value": 23,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

Örnek bildirilen özellik ikinci yükü:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetHumidity": {
      "value": 80,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

Not

Bildirilen bu iki özellik yükünü tek bir yükte birleştirmeyi seçebilirsiniz.

Daha fazla yazılabilir özellik örneği için bkz . Payloads > Özellikleri.

Komutlar

Hiçbir bileşen arabirimi ön ek olmadan komut adını kullanmaz.

Bir cihaz veya modülde, birden çok bileşen arabirimi şu biçime sahip komut adlarını kullanır: componentName*commandName.

Diğer komut örnekleri için bkz . Payloads > Komutları.

İpucu

IoT Central'ın Uzun süre çalışan komutları ve Çevrimdışı komutları uygulamaya yönelik kendi kuralları vardır.

Sonraki adımlar

artık IoT Tak Çalıştır kuralları hakkında bilgi edindiğinize göre, diğer bazı kaynaklar şunlardır: