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 reiniciar 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, posteriormente, notifique o IoT Central quando o comando de longa execução for concluído.

Por padrão, os comandos esperam que um dispositivo seja conectado e falham se o dispositivo não puder ser alcançado. Se você selecionar a opção Fila se estiver offline na interface do usuário do modelo de dispositivo, um comando poderá ser enfileirado até que um 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 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 cargas úteis 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.

Defina seus comandos

Os 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 de retorno quando o dispositivo conclui o comando. Por exemplo, um comando que pede a um dispositivo para executar alguns diagnósticos pode 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 Get Max-Min report no modelo de dispositivo Termostato . Este comando tem parâmetros de solicitação e resposta:

A tabela a seguir mostra as definições de configuração para um recurso de comando:

Campo	Descrição
Nome a Apresentar	O valor do comando usado em blocos de painel e formulários de dispositivo.
Nome	O nome do comando. O IoT Central gera um valor para esse campo a partir do nome para exibição, mas você pode escolher seu próprio valor, se necessário. Este campo tem de ser alfanumérico. O código do dispositivo usa esse valor Name .
Tipo de Capacidade	Comandos
Fila se estiver offline	Se esse comando deve ser transformado em um comando offline .
Description	Uma descrição da capacidade de comando.
Comentário	Quaisquer comentários sobre a capacidade de comando.
Pedir	A carga útil para o comando device.
Response	A carga útil da resposta do comando do dispositivo.

Para saber mais sobre a DTDL (Digital Twin Definition Language) que o Azure IoT Central usa para definir comandos em um modelo de dispositivo, consulte Comandos de convenções IoT > Plug and Play.

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

Comandos padrão

Para manipular 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 manipular comandos padrão invocados pelo seu aplicativo IoT Central.

Por exemplo, 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:

Nota

Para comandos padrão, há um tempo limite de 30 segundos. Se um dispositivo não responder em 30 segundos, o IoT Central assumirá que o comando falhou. Este período de tempo limite não é configurável.

Comandos de execução prolongada

Em um comando de longa execução, um dispositivo não conclui imediatamente o comando. Em vez disso, o dispositivo confirma o recebimento do comando e, mais tarde, 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.

Nota

Comandos de longa execução não fazem parte das convenções IoT Plug and Play. O IoT Central tem sua própria convenção para implementar comandos de longa execução.

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

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

Nota

Este artigo usa Node.js para simplificar.

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

1. Verifica o nome do comando.
2. Chamadas sendCommandResponse para enviar a resposta de volta para o IoT Central. Esta resposta inclui o código de 202 resposta para indicar resultados pendentes.
3. Conclui a operação de longa duração.
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 ela recebe a 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 o 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.

Nota

Os comandos offline não fazem parte das convenções IoT Plug and Play. O IoT Central tem sua própria convenção para implementar comandos offline.

Nota

Este artigo usa Node.js para simplificar.

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

O trecho de código a seguir mostra como um cliente pode ouvir 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 trecho de código anterior mostra a carga útil com os valores StartTime e 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"}]}

Nota

O tempo de vida padrão para comandos offline é de 24 horas, após o qual a mensagem expira.

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, a carga útil 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óximos passos

Agora que você aprendeu como usar comandos em seu aplicativo do Azure IoT Central, consulte Telemetria, propriedade e cargas úteis 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.