Como usar comandos em uma solução do Azure IoT Central

Este guia de instruções mostra como usar comandos definidos em um modelo de dispositivo.

Um operador pode usar a interface do usuário do IoT Central para chamar um comando em um dispositivo. Os comandos controlam o comportamento de um dispositivo. Por exemplo, um operador pode chamar um comando para reinicializar um dispositivo ou coletar dados de diagnóstico.

Um dispositivo pode:

• Responda a um comando imediatamente.
• Responda ao IoT Central quando receber o comando e, em seguida, notifique o IoT Central quando o comando de execução longa for concluído.

Por padrão, os comandos esperam que um dispositivo seja conectado e falhem se o dispositivo não puder ser atingido. Se você selecionar a opção fila se estiver offline na interface do usuário do modelo de dispositivo, um comando poderá ser colocado na fila até que o dispositivo fique online. Esses comandos offline são descritos em uma seção separada mais adiante neste artigo.

Para saber mais sobre as convenções de comando do IoT Pug and Play, consulte as convenções IoT Plug and Play.

Para saber mais sobre os dados de comando que um dispositivo troca com o IoT Central, consulte telemetria, propriedade e cargas de comando.

Para saber como gerenciar comandos usando a API REST do IoT Central, confira Como usar a API REST do IoT Central para controlar dispositivos.

Para saber como implementar comandos em um dispositivo sem usar os SDKs do dispositivo, consulte Comunicar-se com um hub IoT usando o protocolo MQTT.

Definir seus comandos

Comandos padrão são enviados para um dispositivo para instruir o dispositivo a fazer algo. Um comando pode incluir parâmetros com informações adicionais. Por exemplo, um comando para abrir uma válvula em um dispositivo pode ter um parâmetro que especifica quanto abrir a válvula. Os comandos também podem receber um valor retornado quando o dispositivo concluir o comando. Por exemplo, um comando que solicita que um dispositivo execute alguns diagnósticos pode receber um relatório de diagnóstico como um valor retornado.

Os comandos são definidos como parte de um modelo de dispositivo. A captura de tela a seguir mostra a definição de comando obter Max-Min de relatório no modelo de dispositivo termostato. Esse comando tem parâmetros de solicitação e resposta:

A tabela a seguir mostra as configurações de um recurso de comando:

Para saber mais sobre a DTDL (Linguagem de Definição de Gêmeo Digital) que o Azure IoT Central usa para definir comandos em um modelo de dispositivo, consulte Convenções de IoT Plug and Play > Comandos.

Campos opcionais, como nome de exibição e descrição, permitem adicionar mais detalhes à interface e aos recursos.

Comandos padrão

Para lidar com um comando padrão, um dispositivo envia um valor de resposta assim que recebe o comando do IoT Central. Você pode usar o SDK do dispositivo IoT do Azure para lidar com comandos padrão invocados pelo aplicativo IoT Central.

Para obter exemplos de implementações em vários idiomas, consulte Tutorial: Criar e conectar um aplicativo cliente ao seu aplicativo do Azure IoT Central.

A captura de tela a seguir mostra como a resposta de comando bem-sucedida é exibida na interface do usuário do IoT Central:

Comandos de longa duração

Em um comando de execução longa, um dispositivo não conclui imediatamente o comando. Em vez disso, o dispositivo reconhece o recebimento do comando e, em seguida, confirma que o comando foi concluído. Essa abordagem permite que um dispositivo conclua uma operação de longa execução sem manter a conexão com o IoT Central aberta.

Esta seção mostra como um dispositivo pode atrasar o envio de uma confirmação de que o comando foi concluído.

O snippet de código a seguir mostra como um dispositivo pode implementar um comando de execução longa:

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

A chamada para onDeviceMethod configura o método commandHandler. Este manipulador de comandos:

1. Verifica o nome do comando.
2. Chama sendCommandResponse para enviar a resposta de volta para o IoT Central. Essa resposta inclui o 202 código de resposta para indicar resultados pendentes.
3. Conclui a operação de execução longa.
4. Usa uma propriedade relatada com o mesmo nome do comando para informar ao IoT Central que o comando foi concluído.

A captura de tela a seguir mostra a interface do usuário do IoT Central quando recebe a atualização de propriedade que indica que o comando está concluído:

Comandos offline

Esta seção mostra como um dispositivo lida com um comando offline. Se um dispositivo estiver online, ele poderá manipular o comando offline assim que for recebido. Se um dispositivo estiver offline, ele manipulará o comando offline quando se conectar ao IoT Central. Os dispositivos não podem enviar um valor retornado em resposta a um comando offline.

A captura de tela a seguir mostra um comando offline chamado GenerateDiagnostics. O parâmetro de solicitação é um objeto com propriedade datetime chamada StartTime e uma propriedade de enumeração de inteiros chamada Bank:

O snippet de código a seguir mostra como um cliente pode escutar comandos offline e exibir o conteúdo da mensagem:

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

A saída do snippet de código anterior mostra a carga com os valoresStartTime e valores Bank . A lista de propriedades inclui o nome do comando no item de lista method-name:

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

Comandos em dispositivos não atribuídos

Você pode chamar comandos em um dispositivo que não está atribuído a um modelo de dispositivo. Para chamar um comando em um dispositivo não atribuído, navegue até o dispositivo na seção Dispositivos , selecione Gerenciar dispositivo e, em seguida, Comando. Insira o nome do método, o conteúdo e quaisquer outros valores necessários. A captura de tela a seguir mostra a interface do usuário usada para chamar um comando:

Próximas etapas

Agora que você sabe como usar comandos em seu aplicativo do Azure IoT Central, consulte telemetria, propriedade e cargas de comando para saber mais sobre parâmetros de comando e criar e conectar um aplicativo cliente ao seu aplicativo do Azure IoT Central para ver exemplos de código completos em diferentes idiomas.