Wat zijn apparaatsjablonen?

Een apparaatsjabloon in Azure IoT Central is een blauwdruk die de kenmerken en het gedrag definieert van een type apparaat dat verbinding maakt met uw toepassing. De apparaatsjabloon definieert bijvoorbeeld de telemetrie die een apparaat verzendt, zodat IoT Central visualisaties kan maken die gebruikmaken van de juiste eenheden en gegevenstypen.

Een ontwikkelaar van oplossingen voegt apparaatsjablonen toe aan een IoT Central-toepassing. Een apparaatontwikkelaar schrijft de apparaatcode die het gedrag implementeert dat is gedefinieerd in de apparaatsjabloon. Zie Nettoladingen telemetrie, eigenschap en opdracht voor meer informatie over de gegevens die een apparaat uitwisselt met IoT Central.

Een apparaatsjabloon bevat de volgende secties:

• Een apparaatmodel. In dit deel van de apparaatsjabloon wordt gedefinieerd hoe het apparaat communiceert met uw toepassing. Elk apparaatmodel heeft een unieke id. Een apparaatontwikkelaar implementeert het gedrag dat in het model is gedefinieerd.
  • Hoofdonderdeel. Elk apparaatmodel heeft een hoofdonderdeel. De interface van het hoofdonderdeel beschrijft mogelijkheden die specifiek zijn voor het apparaatmodel.
  • Onderdelen. Een apparaatmodel kan onderdelen bevatten naast het hoofdonderdeel om apparaatmogelijkheden te beschrijven. Elk onderdeel heeft een interface die de mogelijkheden van het onderdeel beschrijft. Onderdeelinterfaces kunnen opnieuw worden gebruikt in andere apparaatmodellen. Verschillende telefoonapparaatmodellen kunnen bijvoorbeeld dezelfde camera-interface gebruiken.
  • Overgenomen interfaces. Een apparaatmodel bevat een of meer interfaces waarmee de mogelijkheden van het hoofdonderdeel worden uitgebreid.
• Weergaven. Met dit deel van de apparaatsjabloon kan de ontwikkelaar van de oplossing visualisaties definiëren om gegevens van het apparaat weer te geven en formulieren om een apparaat te beheren en te beheren. Weergaven hebben geen invloed op de code die een apparaatontwikkelaar schrijft om het apparaatmodel te implementeren.

Een apparaat toewijzen aan een apparaatsjabloon

Een apparaat moet worden toegewezen aan een apparaatsjabloon om te kunnen communiceren met IoT Central. Deze opdracht wordt op vier manieren uitgevoerd:

• Wanneer u een apparaat registreert op de pagina Apparaten , kunt u de sjabloon identificeren die het apparaat moet gebruiken.
• Wanneer u een lijst met apparaten bulksgewijs importeert, kunt u de apparaatsjabloon kiezen die alle apparaten in de lijst moeten gebruiken.
• U kunt een niet-toegewezen apparaat handmatig toewijzen aan een apparaatsjabloon nadat deze verbinding heeft gemaakt.
• U kunt automatisch een apparaat toewijzen aan een apparaatsjabloon door een model-id te verzenden wanneer het apparaat voor het eerst verbinding maakt met uw toepassing.

Automatische toewijzing

IoT Central kan automatisch een apparaat toewijzen aan een apparaatsjabloon wanneer het apparaat verbinding maakt. Een apparaat moet een model-id verzenden wanneer het verbinding maakt. IoT Central gebruikt de model-id om de apparaatsjabloon voor dat specifieke apparaatmodel te identificeren. Het detectieproces werkt als volgt:

1. Als de apparaatsjabloon al is gepubliceerd in de IoT Central-toepassing, wordt het apparaat toegewezen aan de apparaatsjabloon.

2. Als de apparaatsjabloon nog niet is gepubliceerd in de IoT Central-toepassing, zoekt IoT Central naar het apparaatmodel in de opslagplaats van het openbare apparaatmodel. Als IoT Central het model vindt, wordt het gebruikt om een eenvoudige apparaatsjabloon te genereren.

3. Als Het model niet wordt gevonden in de openbare modelopslagplaats, wordt het apparaat gemarkeerd als Niet-toegewezen. Een operator kan:

   • Maak een apparaatsjabloon voor het apparaat en migreer vervolgens het niet-toegewezen apparaat naar de nieuwe apparaatsjabloon.
   • Automatisch een apparaatsjabloon genereren op basis van de gegevens die het apparaat verzendt.

In de volgende schermopname ziet u hoe u de model-id van een apparaatsjabloon in IoT Central kunt weergeven. Selecteer een onderdeel in een apparaatsjabloon en selecteer vervolgens Identiteit bewerken:

U kunt het thermostaatmodel bekijken in de openbare modelopslagplaats. De definitie van de model-id ziet er als volgt uit:

"@id": "dtmi:com:example:Thermostat;1"

Gebruik de volgende DPS-nettolading om het apparaat toe te wijzen aan een apparaatsjabloon:

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

Zie de voorbeeldcode die wordt gebruikt in de zelfstudie: Een clienttoepassing maken en verbinden met uw Azure IoT Central-toepassing voor meer informatie over de DPS-nettolading.

Apparaatmodellen

Een apparaatmodel definieert hoe een apparaat communiceert met uw IoT Central-toepassing. De apparaatontwikkelaar moet ervoor zorgen dat het apparaat het gedrag implementeert dat is gedefinieerd in het apparaatmodel, zodat IoT Central het apparaat kan bewaken en beheren. Een apparaatmodel bestaat uit een of meer interfaces en elke interface kan een verzameling telemetrietypen , apparaateigenschappen en opdrachten definiëren. Een oplossingsontwikkelaar kan:

• Importeer een JSON-bestand dat een volledig apparaatmodel of een afzonderlijke interface definieert in een apparaatsjabloon.
• Gebruik de webgebruikersinterface in IoT Central om een apparaatmodel te maken of te bewerken.

Notitie

IoT Central accepteert elke geldige JSON-nettolading van een apparaat, maar kan alleen de gegevens voor visualisaties gebruiken als deze overeenkomt met een definitie in het apparaatmodel. U kunt gegevens exporteren die niet overeenkomen met een definitie. Zie IoT-gegevens exporteren naar cloudbestemmingen met behulp van Blob Storage.

Zie Een bestaande apparaatsjabloon bewerken voor meer informatie over het bewerken van een apparaatmodel

Een oplossingsontwikkelaar kan ook een JSON-bestand exporteren vanuit de apparaatsjabloon die een volledig apparaatmodel of een afzonderlijke interface bevat. Een apparaatontwikkelaar kan dit JSON-document gebruiken om te begrijpen hoe het apparaat moet communiceren met de IoT Central-toepassing.

Het JSON-bestand dat het apparaatmodel definieert, maakt gebruik van de Digital Twin Definition Language (DTDL) V2. IoT Central verwacht dat het JSON-bestand het apparaatmodel bevat met de inline gedefinieerde interfaces in plaats van in afzonderlijke bestanden. Voor modellen die in IoT Central zijn gemaakt, is de context dtmi:iotcentral:context;2 gedefinieerd om aan te geven dat het model is gemaakt in IoT Central:

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

Zie de IoT Plug en Play modelleringshandleiding voor meer informatie over DTDL-modellen.

Notitie

IoT Central definieert enkele extensies voor de DTDL v2-taal. Zie de IoT Central-extensie voor meer informatie.

Eigenschappen

Eigenschappen zijn standaard alleen-lezen. Alleen-lezeneigenschappen betekenen dat de eigenschapswaarde van het apparaat wordt bijgewerkt naar uw IoT Central-toepassing. Uw IoT Central-toepassing kan de waarde van een alleen-lezen eigenschap niet instellen.

U kunt een eigenschap ook markeren als beschrijfbaar op een interface. Een apparaat kan een update ontvangen van een beschrijfbare eigenschap van uw IoT Central-toepassing en updates van de eigenschapswaarde rapporteren voor uw toepassing.

Apparaten hoeven niet verbonden te zijn om eigenschapswaarden in te stellen. De bijgewerkte waarden worden overgedragen wanneer het apparaat vervolgens verbinding maakt met de toepassing. Dit gedrag is van toepassing op zowel alleen-lezen- als schrijfbare eigenschappen.

Gebruik geen eigenschappen om telemetrie van uw apparaat te verzenden. Een leeseigenschap zoals temperatureSetting=80 moet bijvoorbeeld betekenen dat de temperatuur van het apparaat is ingesteld op 80 en dat het apparaat deze temperatuur probeert te bereiken, of op deze temperatuur blijft.

Voor schrijfbare eigenschappen retourneert de apparaattoepassing een gewenste statusstatuscode, versie en beschrijving om aan te geven of deze de eigenschapswaarde heeft ontvangen en toegepast.

Cloudeigenschappen

U kunt ook cloudeigenschappen toevoegen aan het hoofdonderdeel van het model. Met cloudeigenschappen kunt u metagegevens van apparaten opgeven die moeten worden opgeslagen in de IoT Central-toepassing. Cloudeigenschapswaarden worden opgeslagen in de IoT Central-toepassing en worden nooit gesynchroniseerd met een apparaat. Cloudeigenschappen hebben geen invloed op de code die een apparaatontwikkelaar schrijft om het apparaatmodel te implementeren.

Een oplossingsontwikkelaar kan cloudeigenschappen toevoegen aan apparaatweergaven en formulieren naast apparaateigenschappen, zodat een operator de apparaten kan beheren die zijn verbonden met de toepassing. Een oplossingsontwikkelaar kan ook cloudeigenschappen gebruiken als onderdeel van een regeldefinitie om een drempelwaarde te bewerken door een operator.

In het volgende DTDL-fragment ziet u een voorbeeld van een definitie van de cloudeigenschap:

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

Telemetrie

Met IoT Central kunt u telemetrie weergeven in apparaatweergaven en grafieken en regels gebruiken om acties te activeren wanneer drempelwaarden worden bereikt. IoT Central gebruikt de informatie in het apparaatmodel, zoals gegevenstypen, eenheden en weergavenamen, om te bepalen hoe telemetriewaarden moeten worden weergegeven. U kunt ook telemetriewaarden weergeven op toepassings- en persoonlijke dashboards.

U kunt de ioT Central-functie voor gegevensexport gebruiken om telemetrie te streamen naar andere bestemmingen, zoals opslag of Event Hubs.

Opdracht

Een opdracht moet standaard binnen 30 seconden worden uitgevoerd en het apparaat moet zijn verbonden wanneer de opdracht binnenkomt. Als het apparaat op tijd reageert of het apparaat niet is verbonden, mislukt de opdracht.

Opdrachten kunnen aanvraagparameters hebben en een antwoord retourneren.

Offlineopdrachten

U kunt wachtrijopdrachten kiezen als een apparaat momenteel offline is door de wachtrij in te schakelen als offlineoptie voor een opdracht in de apparaatsjabloon.

Offlineopdrachten zijn meldingen in één richting naar het apparaat vanuit uw oplossing. Offlineopdrachten kunnen aanvraagparameters hebben, maar er wordt geen antwoord geretourneerd.

Notitie

Offlineopdrachten worden gemarkeerd alsof durable u het model exporteert als DTDL.

Offlineopdrachten maken gebruik van IoT Hub-cloud-naar-apparaat-berichten om de opdracht en nettolading naar het apparaat te verzenden.

De nettolading van het bericht dat het apparaat ontvangt, is de onbewerkte waarde van de parameter. Een aangepaste eigenschap met de naam method-name slaat de naam van de IoT Central-opdracht op. In de volgende tabel ziet u enkele voorbeelden van nettoladingen:

IoT Central-aanvraagschema	Voorbeeld van nettolading ontvangen per apparaat
Geen aanvraagparameter	@
Dubbel	1.23
String	sample string
Object	{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

In het volgende codefragment van een apparaatmodel ziet u de definitie van een opdracht. De opdracht heeft een objectparameter met een datum/tijd-veld en een opsomming:

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

Als u de wachtrij inschakelt als offlineoptie in de gebruikersinterface van de apparaatsjabloon voor de opdracht in het vorige fragment, bevat het bericht dat het apparaat ontvangt de volgende eigenschappen:

Eigenschapsnaam	Voorbeeldwaarde
custom_properties	{'method-name': 'GenerateDiagnostics'}
data	{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Weergaven

Een oplossingsontwikkelaar maakt weergaven waarmee operators verbonden apparaten kunnen bewaken en beheren. Weergaven maken deel uit van de apparaatsjabloon, dus een weergave is gekoppeld aan een specifiek apparaattype. Een weergave kan het volgende omvatten:

• Grafieken om telemetrie te tekenen.
• Tegels om alleen-lezen apparaateigenschappen weer te geven.
• Tegels waarmee de operator schrijfbare apparaateigenschappen kan bewerken.
• Tegels waarmee de operator cloudeigenschappen kan bewerken.
• Tegels waarmee de operator opdrachten kan aanroepen, inclusief opdrachten die een nettolading verwachten.
• Tegels voor het weergeven van labels, afbeeldingen of markdown-tekst.

Volgende stappen

Nu u meer hebt geleerd over apparaatsjablonen, is een voorgestelde volgende stap het lezen van telemetrie, eigenschap en opdrachtpayloads voor meer informatie over de gegevens die een apparaat uitwisselt met IoT Central.