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 uma interface do usuário do IoT Central para chamar um comando em um dispositivo. As configurações controlam o comportamento do dispositivo. Por exemplo, um operador pode chamar um comando para reinicializar o dispositivo ou coletar dados de diagnóstico.

Um dispositivo pode:

• Responder ao comando imediatamente.
• Responda a IoT Central quando receber um comando e depois notificar IoT Central quando o comando de longa execução for concluído.

Por padrão, os comandos esperam que o dispositivo seja conectado e falhem se o dispositivo não puder ser acessado. 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 a frente neste artigo.

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

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

Para saber como gerenciar comandos usando a API REST do IoT Central, consulte 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 os seus comandos

Os comandos Standard são enviados a 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 o quanto se deve abrir a válvula. Os comandos também podem receber um valor de retorno quando o dispositivo concluir o comando. Por exemplo, um comando que solicita que o dispositivo execute alguns diagnósticos poderia receber um relatório de diagnóstico como um valor de retorno.

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. Este comando tem os parâmetros de solicitação e resposta:

A seguinte tabela mostra as definições de configuração para uma funcionalidade 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 que você adicione 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 seu aplicativo IoT Central.

Para obter exemplos de implementações em vários idiomas, consulte 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 execução longa

Em um comando de longa duração, um dispositivo não conclui o comando imediatamente. Em vez disso, o dispositivo confirma o recebimento do comando e, posteriormente, confirma que o comando foi concluído. Essa abordagem permite que um dispositivo conclua uma operação de longa duraçã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 entrou.

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

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 configurar o método commandHandler. Esse manipulador de comandos:

1. Verifica o nome do comando.
2. Chama sendCommandResponse para enviar a resposta de volta para IoT Central. Essa resposta inclui o código de resposta 202 para indicar êxito.
3. Conclui a operação de execução longa.
4. Usa uma propriedade relatada com o mesmo nome que o comando para informar 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 uma atualização de propriedade que indica que o comando foi concluído:

Comandos offline

Esta seção mostra como um dispositivo lida com um comando offline. Se um dispositivo estiver online, ele poderá manipular um comando offline assim que ele 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 de retorno 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 a propriedade datetime chamada StartTime e uma propriedade de enumeração de inteiro 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 payload e quaisquer outros valores necessários. A captura de tela a seguir mostra a interface do usuário que você usa para chamar um comando:

Próximas etapas

Agora que você aprendeu a usar comandos em seu aplicativo Azure IoT Central, consulte Telemetria, propriedade e payloads de comando para saber mais sobre parâmetros de comando e Criar e conectar um aplicativo cliente ao seu aplicativo Azure IoT Central para ver exemplos completos de código em diferentes idiomas.