IoT Tak Çalıştır kuralları
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 eklerdt-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 av
0
ac
203
varsayı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 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 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: