Come usare i comandi in una soluzione Azure IoT Central

Questa guida pratica illustra come usare i comandi definiti in un modello di dispositivo.

Un operatore può usare l'interfaccia utente di IoT Central per chiamare un comando in un dispositivo. I comandi controllano il comportamento di un dispositivo. Ad esempio, un operatore potrebbe chiamare un comando per riavviare un dispositivo o raccogliere dati di diagnostica.

Un dispositivo può:

• Rispondere immediatamente a un comando.
• Rispondere a IoT Central quando riceve il comando e quindi inviare una notifica successiva a IoT Central al completamento del comando a esecuzione prolungata.

Per impostazione predefinita, i comandi prevedono che un dispositivo sia connesso e non riesca se non è possibile raggiungere il dispositivo. Se si seleziona l'opzione Coda se offline nell'interfaccia utente del modello di dispositivo, è possibile accodare un comando fino a quando un dispositivo non viene online. Questi comandi offline sono descritti in una sezione separata più avanti in questo articolo.

Per informazioni sulle convenzioni dei comandi IoT Pug e Play, vedere convenzioni di Plug and Play IoT.

Per altre informazioni sui dati dei comandi che un dispositivo scambia con IoT Central, vedere Payload di telemetria, proprietà e comandi.

Per informazioni su come gestire i comandi usando l'API REST di IoT Central, vedere Come usare l'API REST di IoT Central per controllare i dispositivi.

Definire i comandi

I comandi standard vengono inviati a un dispositivo per indicare al dispositivo di eseguire un'operazione. Un comando può includere parametri con informazioni aggiuntive. Ad esempio, un comando per aprire una valvola in un dispositivo potrebbe avere un parametro che specifica quanto aprire la valvola. I comandi possono anche ricevere un valore restituito quando il dispositivo completa il comando. Ad esempio, un comando che chiede a un dispositivo di eseguire una diagnostica potrebbe ricevere un report di diagnostica come valore restituito.

I comandi vengono definiti come parte di un modello di dispositivo. Lo screenshot seguente mostra la definizione del comando Get Max-Min report nel modello di dispositivo Thermostat . Questo comando ha parametri di richiesta e risposta:

La tabella seguente illustra le impostazioni di configurazione per una funzionalità di comando:

Campo	Descrzione
Nome visualizzato	Valore del comando usato nei riquadri del dashboard e nei moduli del dispositivo.
Nome	Nome del comando. IoT Central genera un valore per questo campo dal nome visualizzato, ma è possibile scegliere un valore personalizzato, se necessario. Questo campo deve essere alfanumerico. Il codice del dispositivo usa questo valore Name .
Tipo di funzionalità	Comando.
Accoda se offline	Indica se impostare questo comando come comando offline .
Descrizione	Descrizione della funzionalità del comando.
Comment	Eventuali commenti sulla funzionalità del comando.
Richiedi	Payload per il comando del dispositivo.
Response	Payload della risposta del comando del dispositivo.

Per informazioni sul linguaggio DTDL (Digital Twin Definition Language) usato da Azure IoT Central per definire i comandi in un modello di dispositivo, vedere Plug and Play IoT convenzioni > Comandi.

Campi facoltativi, ad esempio nome visualizzato e descrizione, consentono di aggiungere altri dettagli all'interfaccia e alle funzionalità.

Comandi standard

Per gestire un comando standard, un dispositivo invia un valore di risposta non appena riceve il comando da IoT Central. È possibile usare Azure IoT SDK per dispositivi per gestire i comandi standard richiamati dall'applicazione IoT Central.

Ad esempio, le implementazioni in più linguaggi, vedere Creare e connettere un'applicazione client all'applicazione Azure IoT Central.

Lo screenshot seguente mostra come viene visualizzata la risposta di comando riuscita nell'interfaccia utente di IoT Central:

Nota

Per i comandi standard, è previsto un timeout di 30 secondi. Se un dispositivo non risponde entro 30 secondi, IoT Central presuppone che il comando non sia riuscito. Questo periodo di timeout non è configurabile.

Comandi a esecuzione prolungata

In un comando a esecuzione prolungata, un dispositivo non completa immediatamente il comando. Il dispositivo conferma invece la ricezione del comando e successivamente conferma che il comando è stato completato. Questo approccio consente a un dispositivo di completare un'operazione a esecuzione prolungata senza mantenere aperta la connessione a IoT Central.

Nota

I comandi a esecuzione prolungata non fanno parte delle convenzioni di Plug and Play IoT. IoT Central ha una propria convenzione per implementare comandi a esecuzione prolungata.

Questa sezione illustra come un dispositivo può ritardare l'invio di una conferma del completamento del comando.

Il frammento di codice seguente illustra come un dispositivo può implementare un comando a esecuzione prolungata:

Nota

Questo articolo usa Node.js per semplicità.

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

Chiamata per configurare onDeviceMethod il commandHandler metodo . Questo gestore di comandi:

1. Controlla il nome del comando.
2. Chiama sendCommandResponse per inviare nuovamente la risposta a IoT Central. Questa risposta include il 202 codice di risposta per indicare i risultati in sospeso.
3. Completa l'operazione a esecuzione prolungata.
4. Usa una proprietà segnalata con lo stesso nome del comando per indicare a IoT Central che il comando è stato completato.

Lo screenshot seguente mostra l'interfaccia utente di IoT Central quando riceve l'aggiornamento della proprietà che indica che il comando è completo:

Comandi offline

Questa sezione illustra come un dispositivo gestisce un comando offline. Se un dispositivo è online, può gestire il comando offline non appena viene ricevuto. Se un dispositivo è offline, gestisce il comando offline quando si connette a IoT Central. I dispositivi non possono inviare un valore restituito in risposta a un comando offline.

Nota

I comandi offline non fanno parte delle convenzioni di Plug and Play IoT. IoT Central ha una propria convenzione per implementare i comandi offline.

Nota

Questo articolo usa Node.js per semplicità.

Lo screenshot seguente mostra un comando offline denominato GenerateDiagnostics. Il parametro request è un oggetto con proprietà datetime denominata StartTime e una proprietà di enumerazione integer denominata Bank:

Il frammento di codice seguente mostra come un client può ascoltare i comandi offline e visualizzare il contenuto del messaggio:

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');
    }
  });
});

L'output del frammento di codice precedente mostra il payload con i valori StartTime e Bank . L'elenco delle proprietà include il nome del comando nell'elemento dell'elenco nome metodo:

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

Nota

Il tempo predefinito per i comandi offline è di 24 ore, dopo il quale il messaggio scade.

Comandi su dispositivi non assegnati

È possibile chiamare i comandi in un dispositivo che non è assegnato a un modello di dispositivo. Per chiamare un comando in un dispositivo non assegnato, passare al dispositivo nella sezione Dispositivi , selezionare Gestisci dispositivo e quindi Comando. Immettere il nome del metodo, il payload e tutti gli altri valori obbligatori. Lo screenshot seguente mostra l'interfaccia utente usata per chiamare un comando:

Passaggi successivi

Dopo aver appreso come usare i comandi nell'applicazione Azure IoT Central, vedere Telemetry, property e command payloads (Payload di telemetria, proprietà e comandi) per altre informazioni sui parametri dei comandi e Creare e connettere un'applicazione client all'applicazione Azure IoT Central per visualizzare esempi di codice completi in linguaggi diversi.