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

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

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

Un dispositivo puede:

• Responder inmediatamente a un comando.
• Responder a IoT Central cuando reciba el comando y después notificar a IoT Central cuando se complete el comandos de larga duración.

De manera predeterminada, los comandos esperan que un dispositivo se conecte y generan un error si no pueden comunicarse con el 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 información sobre las convenciones de comandos 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 Cargas de telemetría, propiedades y comandos.

Para saber cómo administrar comandos mediante la API de REST de IoT Central, consulte Uso de la API de REST de IoT Central para controlar dispositivos.

Para 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 mismo 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 incluir un parámetro que especifique cuánto se debe abrir la válvula. Los comandos también pueden recibir un valor devuelto cuando el dispositivo completa el comando. Por ejemplo, un comando que solicita a un dispositivo que ejecute algunos diagnósticos podría recibir un informe de diagnóstico como valor devuelto.

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

En la tabla siguiente se muestran las opciones de configuración de una funcionalidad de comando:

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

Para información sobre el lenguaje de definición de gemelos digitales (DTDL) que Azure IoT Central usa para definir propiedades 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, 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 Creación y conexión de una aplicación cliente a la aplicación de Azure IoT Central.

En la siguiente captura de pantalla se muestra el aspecto de la respuesta de correcto 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 al cabo de 30 segundos, IoT Central asume que el comando no se ejecutó correctamente. Este período de tiempo de espera no se puede configurar.

Comandos de larga duración

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 ha completado.

En el siguiente fragmento de código se muestra cómo un dispositivo puede implementar un comando de larga duración:

Nota:

En este artículo se usa Node.js por motivos de simplicidad.

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 a sendCommandResponse para devolver la respuesta a IoT Central. Esta respuesta incluye el código de respuesta 202 para indicar que hay resultados 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 propiedad que indica que el comando se completó:

Comandos sin conexión

En esta sección se muestra cómo un dispositivo administra un comando sin conexión. Si un dispositivo está en línea, puede controlar el comando sin conexión en cuanto lo recibe. Si un dispositivo está sin conexión, se encarga del comando sin conexión cuando vuelve a conectarse a IoT Central. 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 por motivos de simplicidad.

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

En el siguiente fragmento de código se 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 útil con los valores StartTime y Bank. La lista de propiedades incluye el nombre del comando en el elemento method-name de la lista:

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 llamar a comandos en un dispositivo que no esté asignado a una plantilla de dispositivo. 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 útil 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 ha aprendido a usar comandos en su aplicación de Azure IoT Central, consulte Cargas de telemetría, propiedades y comandos para saber más sobre los parámetros de comandos y Creación de una aplicación cliente y conexión a la aplicación de Azure IoT Central para ver ejemplos de código completos en distintos lenguajes.