Create and manage commands

You can configure reusable remote actions or send one-time, immediate instructions to your devices. When you use this feature, you can specify the instructions that your devices can execute in near real time. A command enables you to configure resuable remote actions for your target vehicle. After you create a command, you can start a command execution that targets a specific vehicle.

This topic shows how you can create and manage a command resource using the AWS IoT Core API or the AWS CLI. It shows you how to perform the following actions on a command resource.

Create a command resource

You can use the CreateCommand AWS IoT Core control plane API operation to create a command resource. The following example uses the AWS CLI.

Considerations when creating a command

When you create a command in AWS IoT FleetWise:

Creating a command example

The following example shows how to create a remote command with a parameter.

aws iot create-command --command-id command-id \ 
    --role-arn role-arn \
    --description description \
    --display-name display-name \     
    --namespace "AWS-IoT-FleetWise" \
    --mandatory-parameters '[
        {
            "name": name, 
            "value": value
        }
   ]'

The CreateCommand API operation returns a response that contains the ID and ARN (Amazon Resource Name) of the command.

{
    "commandId": "HandsOffSteeringMode",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"
}

Retrieve information about a command

You can use the GetCommand AWS IoT Core control plane API operation to retrieve information about a command resource.

To get information about a command resource, run the following command. Replace command-id with the identifier that was used when creating the command.

aws iot get-command --command-id command-id

The GetCommand API operation returns a response that contains the following information.

{
    "commandId": "HandsOffSteeringMode",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/HandsOffSteeringMode"",
    "namespace": "AWS-IoT-FleetWise",
    "mandatoryParameters":[
        {
            "name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode",
            "value": {"B": false }
        }
    ],
    "createdAt": "2024-03-23T11:24:14.919000-07:00",
    "lastUpdatedAt": "2024-03-23T11:24:14.919000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

List commands in your account

You can use the ListCommands AWS IoT Core control plane API operation to list all commands in your account that you created.

To list commands in your account, run the following command. By default, the API returns commands that were created for both namespaces. To filter the list to display only commands that were created for AWS IoT FleetWise, run the following command.

aws iot list-commands --namespace "AWS-IoT-FleetWise"

The ListCommands API operation returns a response that contains the following information.

Update or deprecate a command resource

You can use the UpdateCommand AWS IoT Core control plane API operation to update a command resource. You can use the API to either update the display name and description of a command, or to deprecate a command.

Update a command

To update a command resource, run the following command. Replace command-id with the identifier of the command that you want to update, and provide the updated display-name and description.

aws iot update-command \ 
    --command-id command-id \ 
    --display-name display-name \ 
    --description description

The UpdateCommand API operation returns the following response.

{
    "commandId": "HandsOffSteeringMode",
    "deprecated": false,
    "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}

Deprecate a command

You deprecate a command when you intend to no longer continue using it for your device or when it's outdated. The following example shows how to deprecate a command.

aws iot update-command \ 
    --command-id command-id \ 
    --deprecated

The UpdateCommand API operation returns a response that contains the ID and ARN (Amazon Resource Name) of the command.

{
    "commandId": "HandsOffSteeringMode",
    "deprecated": true,
    "lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}

Once a command has been deprecated, existing command executions will continue running on the vehicle until they become terminal. To run any new command executions, you must use the UpdateCommand API to restore the command so that it becomes available. For additional information about deprecating and restoring a command and considerations for it, see Deprecate a command resource in the AWS IoT Core Developer Guide.

Delete a command resource

You can use the DeleteCommand AWS IoT Core control plane API operation to delete a command resource.

To delete a command resource, run the following command. Replace command-id with the identifier of the command that you want to delete. The following example shows how to delete a command resource.

aws iot delete-command --command-id command-id

If the deletion request is successful: