Uso de comandos en una solución de Azure IoT Central

En esta guía paso a paso se muestra cómo usar comandos definidos en una plantilla de dispositivo.

Un operador puede usar la interfaz de usuario de IoT Central para llamar a un comando en un dispositivo. Los comandos controlan el comportamiento de un dispositivo. Por ejemplo, un operador podría llamar a un comando para reiniciar un dispositivo o recopilar datos de diagnóstico.

Un dispositivo puede:

• Responda a un comando inmediatamente.
• Responda a IoT Central cuando reciba el comando y, después, notifique a IoT Central cuando se complete el comando de ejecución prolongada .

De forma predeterminada, los comandos esperan que un dispositivo se conecte y produzca un error si no se puede acceder al dispositivo. Si selecciona la opción Queue if offline (poner en cola si no hay conexión) en la interfaz de usuario de la plantilla de dispositivo, se puede poner en cola un comando hasta que un dispositivo se conecte. Estos comandos sin conexión se describen en una sección independiente más adelante en este artículo.

Para obtener información sobre las convenciones de comandos de IoT Pug y Play, consulte Convenciones de IoT Plug and Play.

Para más información sobre los datos de comandos que intercambia un dispositivo con IoT Central, consulte Telemetría, propiedad y cargas de comandos.

Para obtener información sobre cómo administrar comandos mediante la API REST de IoT Central, consulte Uso de la API REST de IoT Central para controlar los dispositivos.

Para obtener información sobre cómo implementar comandos en un dispositivo sin usar los SDK de dispositivo, consulte Comunicación con un centro de IoT mediante el protocolo MQTT.

Definición de los comandos

Los comandos estándar se envían a un dispositivo para indicar al dispositivo que haga algo. Un comando puede incluir parámetros con información adicional. Por ejemplo, un comando para abrir una válvula en un dispositivo podría tener un parámetro que especifique cuánto abrir la válvula. Los comandos también pueden recibir un valor devuelto cuando el dispositivo completa el comando. Por ejemplo, un comando que pide a un dispositivo que ejecute algunos diagnósticos podría recibir un informe de diagnóstico como un valor devuelto.

Los comandos se definen como parte de una plantilla de dispositivo. En la captura de pantalla siguiente se muestra la definición de comando Obtener Max-Min informe en la plantilla de dispositivo Thermostat . Este comando tiene parámetros de solicitud y respuesta:

En la tabla siguiente se muestran los valores de configuración de una funcionalidad de comando:

Campo	Description
Display Name (Nombre para mostrar)	Valor de comando usado en iconos de panel y formularios de dispositivo.
Nombre	El nombre del comando. IoT Central genera un valor para este campo a partir del nombre para mostrar, pero puedes elegir tu propio valor si es necesario. Este campo debe ser alfanumérico. El código del dispositivo usa este valor name .
Tipo de funcionalidad	Comando.
Queue if offline (poner en cola si no hay conexión)	Indica si se va a convertir este comando en un comando sin conexión .
Description	Descripción de la funcionalidad del comando.
Comentario	Cualquier comentario sobre la funcionalidad del comando.
Solicitud	Carga útil del comando de dispositivo.
Respuesta	Carga útil de la respuesta del comando de dispositivo.

Para obtener información sobre el Digital Twin Definition Language (DTDL) que usa Azure IoT Central para definir comandos en una plantilla de dispositivo, consulte Convenciones de IoT Plug and Play > Comandos.

Los campos opcionales, como el nombre para mostrar y la descripción, le permiten agregar más detalles a la interfaz y las funcionalidades.

Comandos estándar

Para controlar un comando estándar, un dispositivo envía un valor de respuesta en cuanto recibe el comando de IoT Central. Puede usar el SDK de dispositivo IoT de Azure para controlar los comandos estándar invocados por la aplicación de IoT Central.

Para ver implementaciones de ejemplo en varios lenguajes, consulte Tutorial: Creación y conexión de una aplicación cliente a la aplicación de Azure IoT Central.

En la captura de pantalla siguiente se muestra cómo se muestra la respuesta correcta del comando en la interfaz de usuario de IoT Central:

Nota:

En el caso de los comandos estándar, hay un tiempo de espera de 30 segundos. Si un dispositivo no responde en un plazo de 30 segundos, IoT Central asume que se produjo un error en el comando. Este período de tiempo de espera no se puede configurar.

Comandos de ejecución prolongada

En un comando de ejecución prolongada, un dispositivo no completa inmediatamente el comando. En su lugar, el dispositivo confirma la recepción del comando y, a continuación, confirma que el comando se completó. Este enfoque permite que un dispositivo complete una operación de larga duración sin mantener abierta la conexión a IoT Central.

Nota:

Los comandos de ejecución prolongada no forman parte de las convenciones de IoT Plug and Play. IoT Central tiene su propia convención para implementar comandos de ejecución prolongada.

En esta sección se muestra cómo un dispositivo puede retrasar el envío de una confirmación de que el comando se completó.

El siguiente fragmento de código muestra cómo un dispositivo puede implementar un comando de ejecución prolongada:

Nota:

En este artículo se 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;
  }
};

La llamada a onDeviceMethod configura el método commandHandler. Este controlador de comandos:

1. Comprueba el nombre del comando.
2. Llama sendCommandResponse para enviar la respuesta de vuelta a IoT Central. Esta respuesta incluye el código de respuesta 202 para indicar resultados que están pendientes.
3. Completa la operación de ejecución prolongada.
4. Usa una propiedad notificada con el mismo nombre que el comando para indicar a IoT Central que el comando se completó.

En la captura de pantalla siguiente se muestra la interfaz de usuario de IoT Central cuando recibe la actualización de propiedades que indica que el comando está completo:

Comandos sin conexión

En esta sección se muestra cómo un dispositivo controla un comando sin conexión. Si un dispositivo está en línea, puede controlar el comando sin conexión tan pronto como se reciba. Si un dispositivo está sin conexión, procesa el comando sin conexión cuando se conecta a IoT Central la siguiente vez. Los dispositivos no pueden enviar un valor devuelto en respuesta a un comando sin conexión.

Nota:

Los comandos sin conexión no forman parte de las convenciones de IoT Plug and Play. IoT Central tiene su propia convención para implementar comandos sin conexión.

Nota:

En este artículo se usa Node.js para simplificar.

En la captura de pantalla siguiente se muestra un comando sin conexión denominado GenerateDiagnostics. El parámetro request es un objeto con la propiedad datetime denominada StartTime y una propiedad de enumeración de enteros denominada Bank:

El siguiente fragmento de código muestra cómo un cliente puede escuchar comandos sin conexión y mostrar el contenido del mensaje:

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

La salida del fragmento de código anterior muestra la carga con los valores StartTime y Bank . La lista de propiedades incluye el nombre del comando en el elemento 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:

El período de vida predeterminado para los comandos sin conexión es de 24 horas, después del cual expira el mensaje.

Comandos en dispositivos sin asignar

Puede ejecutar comandos en un dispositivo que no está asignado a una plantilla de dispositivos. Para llamar a un comando en un dispositivo sin asignar, vaya al dispositivo en la sección Dispositivos , seleccione Administrar dispositivo y, a continuación, Comando. Escriba el nombre del método, la carga y cualquier otro valor necesario. En la captura de pantalla siguiente se muestra la interfaz de usuario que se usa para llamar a un comando:

Pasos siguientes

Ahora que sabe cómo usar comandos en la aplicación de Azure IoT Central, consulte Telemetría, propiedades y cargas de comandos para más información sobre los parámetros de comando y Creación y conexión de una aplicación cliente a la aplicación de Azure IoT Central para ver ejemplos de código completos en distintos lenguajes.