Använda kommandon i en Azure IoT Central-lösning

Den här instruktionsguiden visar hur du använder kommandon som definieras i en enhetsmall.

En operatör kan använda IoT Central-användargränssnittet för att anropa ett kommando på en enhet. Kommandon styr beteendet för en enhet. En operatör kan till exempel anropa ett kommando för att starta om en enhet eller samla in diagnostikdata.

En enhet kan:

• Svara på ett kommando omedelbart.
• Svara på IoT Central när kommandot tas emot och meddela sedan IoT Central när det långvariga kommandot är klart.

Som standard förväntar sig kommandon att en enhet ansluts och misslyckas om enheten inte kan nås. Om du väljer alternativet Köa om offline i enhetsmallens användargränssnitt kan ett kommando placeras i kö tills en enhet är online. Dessa offlinekommandon beskrivs i ett separat avsnitt senare i den här artikeln.

Mer information om IoT Pug- och Play-kommandokonventionerna finns i IoT Plug and Play-konventioner.

Mer information om de kommandodata som en enhet utbyter med IoT Central finns i Nyttolaster för telemetri, egenskap och kommando.

Information om hur du hanterar kommandon med hjälp av REST-API :et för IoT Central finns i Så här använder du REST-API:et för IoT Central för att styra enheter..

Information om hur du implementerar kommandon på en enhet utan att använda enhetens SDK:er finns i Kommunicera med en IoT-hubb med MQTT-protokollet.

Definiera dina kommandon

Standardkommandon skickas till en enhet för att instruera enheten att göra något. Ett kommando kan innehålla parametrar med ytterligare information. Ett kommando för att öppna en ventil på en enhet kan till exempel ha en parameter som anger hur mycket ventilen ska öppnas. Kommandon kan också få ett returvärde när enheten slutför kommandot. Ett kommando som till exempel ber en enhet att köra viss diagnostik kan ta emot en diagnostikrapport som ett returvärde.

Kommandon definieras som en del av en enhetsmall. Följande skärmbild visar kommandodefinitionen Hämta Max-Min-rapport i mallen Termostatenhet . Det här kommandot har parametrar för både begäran och svar:

I följande tabell visas konfigurationsinställningarna för en kommandofunktion:

Fält	Description
Visningsnamn	Kommandovärdet som används på instrumentpaneler och enhetsformulär.
Name	Namnet på kommandot. IoT Central genererar ett värde för det här fältet från visningsnamnet, men du kan välja ditt eget värde om det behövs. Det här fältet måste vara alfanumeriskt. Enhetskoden använder det här namnvärdet .
Typ av kapacitet	Kommando.
Köa om den är offline	Om du vill göra det här kommandot till ett offlinekommando .
beskrivning	En beskrivning av kommandofunktionen.
Kommentar	Eventuella kommentarer om kommandofunktionen.
Förfrågan	Nyttolasten för enhetskommandot.
Response	Nyttolasten för enhetskommandosvaret.

Mer information om DTDL (Digital Twin Definition Language) som Azure IoT Central använder för att definiera kommandon i en enhetsmall finns i Kommandon för IoT Plug and Play-konventioner>.

Med valfria fält, till exempel visningsnamn och beskrivning, kan du lägga till mer information i gränssnittet och funktionerna.

Standardkommandon

För att hantera ett standardkommando skickar en enhet ett svarsvärde så snart den tar emot kommandot från IoT Central. Du kan använda Azure IoT-enhets-SDK för att hantera standardkommandon som anropas av ditt IoT Central-program.

Exempel på implementeringar på flera språk finns i Skapa och ansluta ett klientprogram till ditt Azure IoT Central-program.

Följande skärmbild visar hur det lyckade kommandosvaret visas i IoT Central-användargränssnittet:

Kommentar

För standardkommandon är tidsgränsen 30 sekunder. Om en enhet inte svarar inom 30 sekunder antar IoT Central att kommandot misslyckades. Den här tidsgränsen kan inte konfigureras.

Tidskrävande kommandon

I ett tidskrävande kommando slutför inte en enhet kommandot omedelbart. I stället bekräftar enheten mottagandet av kommandot och bekräftar sedan att kommandot har slutförts. Med den här metoden kan en enhet slutföra en tidskrävande åtgärd utan att hålla anslutningen till IoT Central öppen.

Kommentar

Långvariga kommandon ingår inte i IoT Plug and Play-konventionerna. IoT Central har en egen konvention för att implementera långvariga kommandon.

Det här avsnittet visar hur en enhet kan fördröja sändningen av en bekräftelse på att kommandot har slutförts.

Följande kodfragment visar hur en enhet kan implementera ett tidskrävande kommando:

Kommentar

Den här artikeln använder Node.js för enkelhetens skull.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

Anropet för att onDeviceMethod konfigurera commandHandler metoden. Den här kommandohanteraren:

1. Kontrollerar namnet på kommandot.
2. Anrop sendCommandResponse för att skicka tillbaka svaret till IoT Central. Det här svaret innehåller svarskoden 202 för att ange väntande resultat.
3. Slutför den långvariga åtgärden.
4. Använder en rapporterad egenskap med samma namn som kommandot för att berätta för IoT Central att kommandot har slutförts.

Följande skärmbild visar användargränssnittet för IoT Central när det tar emot egenskapsuppdateringen som anger att kommandot är slutfört:

Offlinekommandon

Det här avsnittet visar hur en enhet hanterar ett offlinekommando. Om en enhet är online kan den hantera offlinekommandot så snart den tas emot. Om en enhet är offline hanterar den offlinekommandot när den ansluter till IoT Central. Enheter kan inte skicka ett returvärde som svar på ett offlinekommando.

Kommentar

Offlinekommandon ingår inte i IoT Plug and Play-konventionerna. IoT Central har en egen konvention för att implementera offlinekommandon.

Kommentar

Den här artikeln använder Node.js för enkelhetens skull.

Följande skärmbild visar ett offlinekommando med namnet GenerateDiagnostics. Parametern request är ett objekt med egenskapen datetime som heter StartTime och en heltalsuppräkningsegenskap med namnet Bank:

Följande kodfragment visar hur en klient kan lyssna efter offlinekommandon och visa meddelandeinnehållet:

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

Utdata från föregående kodfragment visar nyttolasten med värdena StartTime och Bank . Egenskapslistan innehåller kommandonamnet i listobjektet method-name :

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

Kommentar

Standardtiden för offlinekommandon är 24 timmar, varefter meddelandet upphör att gälla.

Kommandon på otilldelade enheter

Du kan anropa kommandon på en enhet som inte är tilldelad till en enhetsmall. Om du vill anropa ett kommando på en otilldelade enhet navigerar du till enheten i avsnittet Enheter , väljer Hantera enhet och sedan Kommando. Ange metodnamn, nyttolast och andra obligatoriska värden. Följande skärmbild visar användargränssnittet som du använder för att anropa ett kommando:

Nästa steg

Nu när du har lärt dig hur du använder kommandon i ditt Azure IoT Central-program kan du läsa Telemetri, egenskap och kommandonyttolaster för att lära dig mer om kommandoparametrar och Skapa och ansluta ett klientprogram till ditt Azure IoT Central-program för att se fullständiga kodexempel på olika språk.