Estado y conceptos de los comandos - AWS IoT Core
Conceptos clave de los comandosEstados de comandoEstado de la ejecución del comando

Estado y conceptos de los comandos

Use los comandos de AWS IoT para enviar una instrucción desde la nube a un dispositivo conectado a AWS IoT. Cómo utilizar la característica de comandos:

  1. En primer lugar, cree un recurso de comandos con una carga útil que incluya las configuraciones necesarias para ejecutar el comando en el dispositivo.

  2. Especifique el dispositivo de destino que recibirá la carga útil y realice las acciones especificadas.

  3. Ejecute el comando en el dispositivo de destino y recupere la información sobre el estado del dispositivo. Para solucionar cualquier problema, consulte los registros de CloudWatch.

Para obtener más información acerca de este flujo de trabajo, consulte Flujo de trabajo de comandos de alto nivel.

Conceptos clave de los comandos

A continuación, se muestran algunos conceptos clave sobre el uso de la característica de comandos.

Comandos

Los comandos son instrucciones que se envían desde la nube a los dispositivos de IoT. Estas instrucciones (carga útil de comandos) se envían a los dispositivos como mensajes de MQTT. Una vez que los dispositivos reciben la carga útil de comandos, pueden procesar las instrucciones para realizar la acción correspondiente. Algunos ejemplos de estas acciones son: la modificación de los ajustes de configuración del dispositivo, la transmisión de las lecturas de los sensores o la carga de los registros. Los dispositivos pueden ejecutar el comando y devolver el resultado a la nube. Esto le permite supervisar y controlar de forma remota los dispositivos conectados.

Espacio de nombres

Al utilizar la característica de comandos, puede especificar el espacio de nombres del comando. Cuando desee crear un comando en AWS IoT Device Management, debe usar el espacio de nombres predeterminado de AWS-IoT. Cuando desee usar este espacio de nombres, debe proporcionar una carga útil al crear el comando. La carga útil se utilizará cuando ejecute el comando en el dispositivo de destino. Si desea crear un comando para AWS IoT FleetWise, debe usar el espacio de nombres de AWS-IoT-FleetWise. Para obtener más información, consulte Comandos remotos en la Guía para desarrolladores de comandos de AWS IoT FleetWise.

Carga

Al crear el comando, debe proporcionar una carga útil que defina las acciones que debe realizar el dispositivo. La carga útil puede usar cualquier formato de su elección. Para asegurarse de que el dispositivo pueda leer y entender correctamente la información que está enviando, le recomendamos que especifique el tipo de formato de carga útil en el comando. Si los dispositivos utilizan MQTT5, pueden seguir el estándar de MQTT para identificar el formato de carga útil. En el tema de solicitud de comandos habrá un indicador de formato para JSON o CBOR.

Dispositivo de destino

Cuando desee ejecutar el comando, debe especificar el dispositivo de destino que recibirá el comando y llevará a cabo las acciones. Si el dispositivo se ha registrado como objeto con AWS IoT, puede usar el nombre de dicho objeto. Si el dispositivo no se ha registrado, puede usar el ID de cliente de MQTT en su lugar. El ID de cliente es un identificador único para el dispositivo o el cliente definido en el protocolo MQTT. Se puede usar para conectar el dispositivo a AWS IoT.

Ejecución de comandos

La ejecución de comandos es una instancia de un comando que se ejecuta en el dispositivo de destino. Al iniciar la ejecución, el comando (carga útil) se envía al dispositivo de destino. Ahora se genera un ID de ejecución de comando único para el destino. A continuación, el dispositivo puede ejecutar el comando e informar de su progreso a AWS IoT. La lógica del dispositivo determina cómo se ejecutará el comando y cómo se publicará el estado en los temas reservados.

Temas de comandos

Antes de ejecutar el comando, el dispositivo debe estar suscrito al tema de solicitud de comandos. Al enviar la solicitud a la nube para ejecutar el comando, la carga útil se enviará al dispositivo en el tema de solicitud de comandos. Una vez que el dispositivo ejecute el comando, podrá publicar el resultado y el estado de la ejecución en el tema de respuesta al comando. Para obtener más información, consulte Temas de comandos.

Estados de comando

Un comando que cree en la Cuenta de AWS puede estar en el estado Disponible, Obsoleto o Pendiente de eliminación.

disponibles

Una vez que haya creado correctamente un recurso de comandos, estará en un estado Disponible. El comando ahora se puede usar para enviar la ejecución de un comando al dispositivo.

Obsoleto

Si ya no va a utilizar un comando, puede marcarlo como obsoleto. En este estado, no puede enviar ninguna ejecución nueva del comando a los dispositivos. Las ejecuciones pendientes que ya se hayan iniciado seguirán ejecutándose en el dispositivo hasta que se completen. Para iniciar nuevas ejecuciones, debe restaurar el comando para que esté disponible.

Eliminación pendiente

Al marcar un comando para su eliminación, si el comando ha quedado obsoleto durante un periodo superior al tiempo de espera máximo, el comando se eliminará automáticamente. Se trata de una acción permanente y no se puede deshacer. De forma predeterminada, el tiempo de espera máximo es de 12 horas. Si el comando no ha quedado obsoleto o ha dejado de utilizarse durante un periodo inferior al tiempo de espera máximo, el comando pasará al estado Pendiente de eliminación. El comando se eliminará automáticamente de la cuenta una vez transcurrido el tiempo de espera máximo.

Estado de la ejecución del comando

Al iniciar la ejecución del comando en el dispositivo de destino, la ejecución del comando entra en un estado CREATED. A continuación, puede pasar a cualquiera de los demás estados de ejecución de comandos en función del estado indicado por el dispositivo. A continuación, puede recuperar la información de estado y realizar un seguimiento de las ejecuciones de los comandos.

nota

En determinado dispositivo de destino, puede ejecutar varios comandos al mismo tiempo. Puede utilizar la característica de control de simultaneidad para limitar el número máximo de ejecuciones que se envían al mismo dispositivo, lo que evita que el dispositivo se sobrecargue. Para obtener más información sobre el número máximo de ejecuciones simultáneas que se pueden ejecutar en cada dispositivo, consulte Cuotas de comandos de AWS IoT Device Management.

En la siguiente tabla se muestran los diferentes estados de la ejecución de un comando y la forma en que la ejecución del comando pasa de un estado a otro en función del progreso de la ejecución.

Estado y origen de la ejecución de los comandos
Estado de la ejecución del comando ¿Iniciado por un dispositivo o la nube? ¿Ejecución final? Transiciones de estado permitidas
CREATED Cloud No

  • IN_PROGRESS

  • SUCCEEDED

  • ERROR

  • REJECTED

  • TIMED_OUT
IN_PROGRESS Dispositivo No

  • IN_PROGRESS

  • SUCCEEDED

  • ERROR

  • REJECTED

  • TIMED_OUT
TIMED_OUT Dispositivo y nube No

  • SUCCEEDED

  • ERROR

  • REJECTED

  • TIMED_OUT
SUCCEEDED Dispositivo Sí No aplicable
FAILED Dispositivo Sí No aplicable
REJECTED Dispositivo Sí No aplicable

A medida que los dispositivos ejecutan el comando, pueden publicar actualizaciones del estado y el resultado en cualquier momento en la nube mediante los temas de MQTT reservados a los comandos. Para proporcionar un contexto adicional sobre el estado de cada ejecución de comandos en la nube, puede utilizar las opciones reasonCode y reasonDescription que se incluyen en el objeto statusReason.

En el siguiente diagrama se muestran los distintos estados de ejecución de comandos y cómo se produce la transición entre ellos.

Imagen que muestra cómo el estado de ejecución de un comando pasa de un estado a otro
nota

Cuando AWS IoT no detecta ninguna respuesta del dispositivo dentro del periodo de espera, se establece TIMED_OUT como un estado temporal que permite reintentos y cambios de estado. Si el dispositivo indica de forma explícita TIMED_OUT durante la ejecución de un comando, se convierte en un estado final y no es posible realizar más transiciones. Consulte Ejecuciones de comandos no finales.

En la siguiente sección se describen las ejecuciones de comandos finales y no finales, los distintos estados de ejecución y su funcionamiento.

Ejecuciones de comandos no finales

La ejecución del comando no es final si la ejecución puede aceptar actualizaciones de dispositivos o clientes. Una ejecución en un estado no final se considera Activa. Los siguientes estados son no finales.

  • CREATED

    Al iniciar la ejecución de un comando desde la consola de AWS IoT o al utilizar la API StartCommandExecution para enviar el comando al dispositivo mediante el tema de solicitud de comandos. Si la solicitud se realiza correctamente, el estado de ejecución del comando cambia a CREATED. A partir de este estado, la ejecución del comando puede pasar a cualquier otro estado final o no final.

  • IN_PROGRESS

    Tras recibir la carga útil del comando, el dispositivo puede empezar a ejecutar las instrucciones de la carga útil y realizar las acciones especificadas. Mientras se ejecuta el comando, el dispositivo puede publicar una respuesta en el tema de respuesta de comandos y actualizar el estado de ejecución del comando como IN_PROGRESS. A partir del estado IN_PROGRESS, la ejecución del comando puede pasar a cualquiera de los otros estados finales o no finales que no sean CREATED.

    nota

    La API de UpdateCommandExecution se puede invocar varias veces con un estado IN_PROGRESS. Puede especificar detalles adicionales sobre la ejecución mediante el objeto statusReason.

  • TIMED_OUT

    Tanto la nube como el dispositivo pueden desencadenar este estado de ejecución de comandos. Una ejecución en el estado CREATED o IN_PROGRESS puede cambiar al estado TIMED_OUT debido a los siguientes motivos.

    • Una vez que se envía el comando al dispositivo, se iniciará un temporizador. Si el dispositivo no responde dentro de un periodo de tiempo específico, la nube cambia el estado de ejecución de comandos a TIMED_OUT. En este caso, la ejecución del comando no es final.

    • El dispositivo puede cambiar el estado a cualquiera de los demás estados finales o informar de que se ha agotado el tiempo de espera al ejecutar el comando y establecer el estado en TIMED_OUT. En este caso, el estado de ejecución permanece en TIMED_OUT, pero los campos del objeto StatusReason cambian en función de la información proporcionada por los dispositivos. La ejecución del comando pasa ahora a ser final.

    Para obtener más información, consulte Valor de tiempo de espera y estado de ejecución de TIMED_OUT.

Ejecuciones de comandos finales

La ejecución de un comando pasa a ser final si la ejecución ya no acepta actualizaciones adicionales de los dispositivos. Los siguientes estados son finales. Una ejecución puede pasar a los estados finales desde cualquiera de los estados no finales, CREATED, IN_PROGRESS o TIMED_OUT.

  • SUCCEEDED

    Si el dispositivo ha completado correctamente la ejecución del comando, este puede publicar una respuesta en el tema de respuesta de comandos y actualizar el estado de ejecución del comando como SUCCEEDED.

  • ERROR

    Si el dispositivo no ha completado la ejecución del comando, este puede publicar una respuesta en el tema de respuesta de comandos y actualizar el estado de ejecución del comando como FAILED. Puede utilizar los campos reasonCode y reasonDescription del objeto statusReason, o los registros de CloudWatch, para seguir solucionando los errores.

  • REJECTED

    Cuando el dispositivo recibe una solicitud no válida o incompatible, el dispositivo debe invocar la API UpdateCommandExecution con un estado REJECTED. Puede utilizar los campos reasonCode y reasonDescription del objeto statusReason, o los registros de CloudWatch, para seguir solucionando los errores.