Inicie e monitore as execuções de comandos

Depois de criar um recurso de comando, você pode iniciar a execução de um comando no veículo de destino. Depois que o veículo começa a executar o comando, ele pode começar a atualizar o resultado da execução do comando e publicar atualizações de status e informações do resultado nos tópicos reservados do MQTT. Em seguida, você pode recuperar o status da execução do comando e monitorar o status das execuções em sua conta.

Este tópico mostra como você pode enviar um comando para seu veículo usando o console de IoT AWS CLI ou AWS IoT FleetWise . Também mostra como monitorar e atualizar o status da execução do comando.

aws iot describe-endpoint --endpoint-type iot:Jobs

{
    "endpointAddress": "<account-specific-prefix>.jobs.iot.<region>.amazonaws.com"
}

aws iot-jobs-data start-command-execution \ 
    --command-arn command-arn \ 
    --target-arn target-arn \
    --execution-timeout-seconds 30 \
    --endpoint-url endpoint-url \ 
    --parameters '[
        {
            "name": name, 
            "value": value
        }
   ]'

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
 }

timeout_ms: 9000000
issued_timestamp_ms: 1723847831317

Atualizar o resultado da execução do comando

Para atualizar o status da execução do comando, seu dispositivo deve ter estabelecido uma conexão MQTT e inscrito no seguinte tópico de solicitação de comandos.

Neste exemplo, <device-id> substitua pelo identificador exclusivo do dispositivo de destino, que pode ser o nome VehicleId ou a coisa, e <execution-id> pelo identificador para a execução do comando.

// Request topic
$aws/devices/<DeviceID>/command_executions/+/request/protobuf

// Response topics (Optional)
$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/accepted/protobuf
$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/rejected/protobuf

Seu dispositivo pode publicar uma mensagem no tópico de resposta dos comandos. Depois de processar o comando, ele envia uma resposta codificada em protobuf para esse tópico. O <DeviceID> campo deve corresponder ao campo correspondente no tópico da solicitação.

$aws/devices/<DeviceID>/command_executions/<ExecutionId>/response/<PayloadFormat>

Depois que seu dispositivo publicar uma resposta a esse tópico, você poderá recuperar as informações de status atualizadas usando a GetCommandExecution API. O status da execução de um comando pode ser qualquer um dos listados aqui.

Observe que a execução de um comando em qualquer um dos status SUCCEEDEDFAILED, e REJECTED é terminal, e o status é relatado pelo dispositivo. Quando a execução de um comando é terminal, isso significa que nenhuma atualização adicional será feita em seu status ou campos relacionados. Um TIMED_OUT status pode ser relatado pelo dispositivo ou pela nuvem. Se relatado pela nuvem, uma atualização do campo de motivo do status poderá ser feita posteriormente pelo dispositivo.

Por exemplo, o exemplo a seguir mostra um exemplo de mensagem MQTT publicada pelo dispositivo.

{
    "deviceId": "",
    "executionId": "",
    "status": "CREATED",
    "statusReason": {
        "reasonCode": "",
        "reasonDescription": ""
    }
}

Para ver um exemplo que mostra como você pode usar o cliente de teste AWS IoT Core MQTT para assinar os tópicos e ver as mensagens de execução do comando, consulte Visualização de atualizações de comandos usando o cliente de teste MQTT no guia do AWS IoT Core desenvolvedor.

Obtenha a execução do comando

Você pode usar a operação da API do plano de GetCommandExecution AWS IoT controle para recuperar informações sobre a execução de um comando. Você já deve ter executado esse comando usando a operação StartCommandExecution da API.

Para recuperar os metadados de um comando executado, execute o comando a seguir.

aws iot get-command-execution --execution-id execution-id \ 
    --target-arn target-arn

A operação da GetCommandExecution API retorna uma resposta que contém informações sobre o ARN da execução do comando, o status da execução e a hora em que o comando começou a ser executado e quando foi concluído. O código a seguir mostra um exemplo de resposta da solicitação da API.

Para fornecer contexto adicional sobre o status de cada execução de comando, o recurso de comandos fornece um statusReason objeto. O objeto contém dois campos reasonCode reasonDescription e. Usando esses campos, seus dispositivos podem fornecer informações adicionais sobre o status da execução de um comando. Essas informações substituirão qualquer padrão reasonCode e reasonDescription isso será relatado na nuvem.

Para relatar essas informações, seus dispositivos podem publicar as informações de status atualizadas na nuvem. Então, ao recuperar o status de execução do comando usando a GetCommandExecution API, você verá os códigos de status mais recentes.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myFrontDoor",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "65536",
        "reasonDescription": "SUCCESS"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00",
    "Parameters": '{
         "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode":          
         { "B": true }
    }' 
}

Listar as execuções de comandos em sua conta

Use a operação da API HTTP do plano de ListCommandExecutions AWS IoT Core controle para listar todas as execuções de comandos em sua conta. O exemplo usa AWS CLI.

Considerações ao listar as execuções de comandos

Veja a seguir algumas considerações ao usar a ListCommandExecutions API.

Exemplo de execução de comandos de lista

O exemplo a seguir mostra como listar as execuções de comandos em seu Conta da AWS.

Ao executar o comando, você deve especificar se deseja filtrar a lista para exibir somente execuções de comandos que foram criadas para um determinado dispositivo usando o. targetArn ou execuções para um determinado comando especificado usando o. commandArn

Neste exemplo, substitua:

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

A execução desse comando gera uma resposta que contém uma lista das execuções de comando que você criou e a hora em que as execuções começaram a ser executadas e quando foram concluídas. Ele também fornece informações de status e o statusReason objeto que contém informações adicionais sobre o status.

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

Excluir uma execução de comando

Se você não quiser mais usar a execução de um comando, poderá removê-la permanentemente da sua conta.

O exemplo a seguir mostra como excluir a execução de um comando usando o delete-command-execution AWS CLI comando. <execution-id>Substitua pelo identificador da execução do comando que você está excluindo.

aws iot delete-command-execution --execution-id <execution-id>

Se a solicitação da API for bem-sucedida, a execução do comando gerará um código de status de 200. Você pode usar a GetCommandExecution API para verificar se a execução do comando não existe mais na sua conta.