IoT Tak ve Kullan konvansiyonları

IoT Tak Çalıştır cihazları, 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.

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

IoT Tak Çalıştır cihazı veya modülü, uyguladığı modeli duyurmak için, MQTT bağlantı paketine model-id ekleyerek USERNAME alanında model ID'yi 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, $.sub özelliğini bileşen adıyla birlikte telemetri konusuna ekleyin, sistem de dt-subject özelliğini ekler.
AMQP kullanırken, dt-subject özelliğini bileşen adıyla birlikte ileti ek açıklaması olarak ekleyin.

Uyarı

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

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

Sadece okunabilir özellikler

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

Örnek bir bileşenin salt okunur özelliği

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
}

Birden fazla bileşenin örnek salt okunur özelliği

Cihaz veya modül, öğenin bir bileşene başvurduğunu belirtmek için {"__t": "c"} işaretini eklemelidir.

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 mülk ş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 $version'ine atıfta bulunan bir kabul sürümü. Bu değeri istenen JSON yükü özelliğinde bulabilirsiniz.
ad - isteğe bağlı bir bildirim açıklaması.

Onay 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:

Status(ac)	Versiyon(av)	Değer(value)	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
beş yüz	İstenen sürüm	Cihaz tarafından kullanılan gerçek değer	özellik uygulanırken istisna

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 varsayılan değeri av ile 0'ye ve ac ile 203'ye 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 etmekte olan mesajla karşılık 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."
  }
}

Nesne türü

Yazılabilir bir özellik nesne olarak tanımlanırsa, hizmetin cihaza tam bir nesne göndermesi gerekir. Cihazın, güncellemenin ardından nasıl davrandığını anlaması için hizmete yeterli bilgi göndererek güncellemeyi onaylaması 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
    }
  }
}

Bileşen yazılabilir özelliği olmayan örnek

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 talep edilen özellik veri yükü:

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

Örnek bildirilen özellik ilk veri paketi:

"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"
  }
}

Uyarı

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

Birden fazla bileşenin yazılabilir özellik örneği

Cihaz veya modül, öğenin bir bileşene başvurduğunu belirtmek için {"__t": "c"} işaretini eklemelidir.

İş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 yapılan güncelleştirmeler işaretçiyi içermez, bkz . Örnek yazılabilir bileşen yok ö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 talep edilen özellik veri yükü:

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

Örnek bildirilen özellik ilk veri paketi:

"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"
    }
  }
}

Uyarı

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.

Commands

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ı.

Tip

IoT Central'ın Uzun süreli komutları ve Çevrimdışı komutları uygulamak için kendi kuralları vardır.

Sonraki Adımlar

IoT Plug and Play standartları hakkında bilgi edindiğinize göre, başka bazı kaynaklar şunlardır:

Last updated on 2025-01-10

Aracılığıyla paylaş

IoT Tak ve Kullan konvansiyonları

Modeli tanımlama

Telemetri

Sadece okunabilir özellikler

Örnek bir bileşenin salt okunur özelliği

Birden fazla bileşenin örnek salt okunur özelliği

Yazılabilir özellikler

Onay yanıtları

Nesne türü

Bileşen yazılabilir özelliği olmayan örnek

Birden fazla bileşenin yazılabilir özellik örneği

Commands

Sonraki Adımlar

Ek kaynaklar