Conventies voor IoT Plug en Play

Artikel
02/07/2024

IoT Plug en Play-apparaten moeten een reeks conventies volgen wanneer ze berichten uitwisselen met een IoT-hub. IoT Plug en Play-apparaten gebruiken het MQTT-protocol om te communiceren met IoT Hub. IoT Hub ondersteunt ook het AMQP-protocol dat beschikbaar is in sommige SDK's voor IoT-apparaten.

Een apparaat kan modules bevatten of worden geïmplementeerd in een IoT Edge-module die wordt gehost door de IoT Edge-runtime.

U beschrijft de telemetrie, eigenschappen en opdrachten die een IoT-Plug en Play-apparaat implementeert met een DTDL-model (Digital Twins Definition Language). In dit artikel worden twee typen modellen genoemd:

Geen onderdeel : een model zonder onderdelen. Het model declareert telemetrie, eigenschappen en opdrachten als elementen op het hoogste niveau in de inhoudssectie van de hoofdinterface. In het hulpprogramma Azure IoT Explorer wordt dit model weergegeven als één standaardonderdeel.
Meerdere onderdelen : een model dat bestaat uit twee of meer interfaces. Een hoofdinterface, die wordt weergegeven als het standaardonderdeel, met telemetrie, eigenschappen en opdrachten. Een of meer interfaces die zijn gedeclareerd als onderdelen met meer telemetrie, eigenschappen en opdrachten.

Zie de Handleiding voor IoT-Plug en Play modellering voor meer informatie.

Het model identificeren

Als u het model wilt aankondigen dat het wordt geïmplementeerd, bevat een IoT-Plug en Play apparaat of module de model-id in het MQTT-verbindingspakket door deze toe te voegen model-id aan het USERNAME veld.

Om het model te identificeren dat door een apparaat of module wordt geïmplementeerd, kan een service de model-id ophalen uit:

Het veld apparaatdubbel modelId .
Het digitale dubbelveld $metadata.$model .
Een melding over een wijziging van digitale dubbels.

Telemetrie

Telemetrie die vanaf een apparaat zonder onderdeel wordt verzonden, vereist geen extra metagegevens. Het systeem voegt de dt-dataschema eigenschap toe.
Telemetrie die vanaf een apparaat wordt verzonden met behulp van onderdelen, moet de onderdeelnaam toevoegen aan het telemetriebericht.
Wanneer u MQTT gebruikt, voegt u de $.sub eigenschap met de naam van het onderdeel toe aan het telemetrieonderwerp, voegt het systeem de dt-subject eigenschap toe.
Wanneer u AMQP gebruikt, voegt u de dt-subject eigenschap toe met de naam van het onderdeel als berichtaantekening.

Notitie

Voor telemetrie van onderdelen is één bericht per onderdeel vereist.

Zie Telemetrie van nettoladingen > voor meer voorbeelden van telemetrie

Alleen-lezen eigenschappen

Een apparaat stelt een alleen-lezen eigenschap in die vervolgens wordt gerapporteerd aan de back-endtoepassing.

Voorbeeld van een eigenschap zonder kenmerk Alleen-lezen

Een apparaat of module kan elke geldige JSON verzenden die volgt op de DTDL-regels.

DTDL waarmee een eigenschap op een interface wordt gedefinieerd:

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

Voorbeeld van gerapporteerde nettolading van eigenschap:

"reported" :
{
  "temperature" : 21.3
}

Voorbeeld van de eigenschap Alleen-lezen van meerdere onderdelen

Het apparaat of de module moet de {"__t": "c"} markering toevoegen om aan te geven dat het element verwijst naar een onderdeel.

DTDL die verwijst naar een onderdeel:

{
  "@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"
    }
  ]
}

DTDL waarmee het onderdeel wordt gedefinieerd:

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

Voorbeeld van gerapporteerde nettolading van eigenschap:

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

Zie Eigenschappen van nettoladingen >voor meer voorbeelden van alleen-lezen eigenschappen.

Schrijfbare eigenschappen

Een back-endtoepassing stelt een beschrijfbare eigenschap in die ioT Hub vervolgens naar het apparaat verzendt.

Het apparaat of de module moet bevestigen dat deze de eigenschap heeft ontvangen door een gerapporteerde eigenschap te verzenden. De gerapporteerde eigenschap moet het volgende omvatten:

value - de werkelijke waarde van de eigenschap (meestal de ontvangen waarde, maar het apparaat kan besluiten om een andere waarde te rapporteren).
ac - een bevestigingscode die gebruikmaakt van een HTTP-statuscode.
av - een bevestigingsversie die verwijst naar de $version gewenste eigenschap. U vindt deze waarde in de JSON-nettolading van de gewenste eigenschap.
ad - een optionele bevestigingsbeschrijving.

Bevestigingsreacties

Bij het rapporteren van schrijfbare eigenschappen moet het apparaat het bevestigingsbericht opstellen, met behulp van de vier velden in de vorige lijst, om de werkelijke apparaatstatus aan te geven, zoals beschreven in de volgende tabel:

Status (ac)	Version(av)	Waarde(waarde)	Beschrijving (av)
200	Gewenste versie	Gewenste waarde	Gewenste eigenschapswaarde geaccepteerd
202	Gewenste versie	Waarde geaccepteerd door het apparaat	Gewenste eigenschapswaarde geaccepteerd, wordt bijgewerkt (moet eindigen met 200)
203	0	Waarde die is ingesteld door het apparaat	Eigenschap die is ingesteld vanaf het apparaat, wordt niet weergegeven als gewenst
400	Gewenste versie	Werkelijke waarde die door het apparaat wordt gebruikt	Gewenste eigenschapswaarde niet geaccepteerd
500	Gewenste versie	Werkelijke waarde die door het apparaat wordt gebruikt	Uitzondering bij het toepassen van de eigenschap

Wanneer een apparaat wordt opgestart, moet het de apparaatdubbel aanvragen en controleren op beschrijfbare eigenschapsupdates. Als de versie van een beschrijfbare eigenschap is toegenomen terwijl het apparaat offline was, moet het apparaat een gerapporteerd eigenschapsantwoord verzenden om te bevestigen dat deze de update heeft ontvangen.

Wanneer een apparaat voor het eerst wordt opgestart, kan het een initiële waarde verzenden voor een gerapporteerde eigenschap als het geen oorspronkelijke gewenste eigenschap van de IoT-hub ontvangt. In dit geval kan het apparaat de standaardwaarde av0 met en ac naar 203verzenden. Voorbeeld:

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

Een apparaat kan de gerapporteerde eigenschap gebruiken om andere informatie aan de hub te verstrekken. Het apparaat kan bijvoorbeeld reageren met een reeks berichten die worden uitgevoerd, zoals:

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

Wanneer het apparaat de doeltemperatuur bereikt, wordt het volgende bericht verzonden:

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

Een apparaat kan een fout melden, zoals:

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

Object type

Als een beschrijfbare eigenschap is gedefinieerd als een object, moet de service een volledig object naar het apparaat verzenden. Het apparaat moet de update bevestigen door voldoende informatie terug te sturen naar de service voor de service om te begrijpen hoe het apparaat heeft gereageerd op de update. Dit antwoord kan het volgende omvatten:

Het hele object.
Alleen de velden die het apparaat heeft bijgewerkt.
Een subset van de velden.

Voor grote objecten kunt u overwegen de grootte te minimaliseren van het object dat u in de bevestiging opneemt.

In het volgende voorbeeld ziet u een beschrijfbare eigenschap die is gedefinieerd als een Object met vier velden:

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
}

Als u deze beschrijfbare eigenschap wilt bijwerken, verzendt u een volledig object van de service die er als volgt uitziet:

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

Het apparaat reageert met een bevestiging die eruitziet als in het volgende voorbeeld:

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

Voorbeeld van geen beschrijfbare eigenschap voor onderdelen

Wanneer een apparaat meerdere gewenste eigenschappen in één nettolading ontvangt, kan het de gerapporteerde eigenschappenantwoorden verzenden over meerdere nettoladingen of de antwoorden combineren tot één nettolading.

Een apparaat of module kan elke geldige JSON verzenden die volgt op de DTDL-regels.

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

Voorbeeld van nettolading van gewenste eigenschap:

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

Voorbeeld van gerapporteerde eigenschap eerste nettolading:

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

Voorbeeld van gerapporteerde eigenschap tweede nettolading:

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

Notitie

U kunt ervoor kiezen om deze twee gerapporteerde eigenschapspayloads te combineren tot één nettolading.

Voorbeeld van meerdere onderdelen beschrijfbare eigenschap

Het apparaat of de module moet de {"__t": "c"} markering toevoegen om aan te geven dat het element verwijst naar een onderdeel.

De markering wordt alleen verzonden voor updates naar eigenschappen die zijn gedefinieerd in een onderdeel. Updates voor eigenschappen die zijn gedefinieerd in het standaardonderdeel bevatten de markering niet. Zie Voorbeeld van geen beschrijfbare eigenschap voor onderdelen.

Wanneer een apparaat meerdere gerapporteerde eigenschappen in één nettolading ontvangt, kan het de gerapporteerde eigenschappenantwoorden verzenden over meerdere nettoladingen of de antwoorden combineren tot één nettolading.

Het apparaat of de module moet bevestigen dat het de eigenschappen heeft ontvangen door gerapporteerde eigenschappen te verzenden:

DTDL die verwijst naar een onderdeel:

{
  "@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"
    }
  ]
}

DTDL waarmee het onderdeel wordt gedefinieerd:

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

Voorbeeld van nettolading van gewenste eigenschap:

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

Voorbeeld van gerapporteerde eigenschap eerste nettolading:

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

Voorbeeld van gerapporteerde eigenschap tweede nettolading:

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

Notitie

U kunt ervoor kiezen om deze twee gerapporteerde eigenschapspayloads te combineren tot één nettolading.

Zie Eigenschappen van nettoladingen >voor meer schrijfbare eigenschappen.

Opdrachten

Geen onderdeelinterfaces gebruiken de opdrachtnaam zonder voorvoegsel.

Op een apparaat of module gebruiken meerdere onderdeelinterfaces opdrachtnamen met de volgende indeling: componentName*commandName

Zie Payloads Commands voor meer opdrachtvoorbeelden>.

Tip

IoT Central heeft zijn eigen conventies voor het implementeren van langlopende opdrachten en offlineopdrachten.

Volgende stappen

Nu u meer hebt geleerd over IoT-Plug en Play conventies, vindt u hier enkele andere resources:

Conventies voor IoT Plug en Play

Het model identificeren

Telemetrie

Alleen-lezen eigenschappen

Voorbeeld van een eigenschap zonder kenmerk Alleen-lezen

Voorbeeld van de eigenschap Alleen-lezen van meerdere onderdelen

Schrijfbare eigenschappen

Bevestigingsreacties

Object type

Voorbeeld van geen beschrijfbare eigenschap voor onderdelen

Voorbeeld van meerdere onderdelen beschrijfbare eigenschap

Opdrachten

Volgende stappen

Aanvullende resources