AWS IoT FleetWise will no longer be open to new customers as of April 30, 2026. Existing AWS IoT FleetWise customers can continue using the service. The [Guidance for Connected Mobility on AWS](https://aws.amazon.com/solutions/guidance/connected-mobility-on-aws/) provides guidance on how to develop and deploy modular services for connected mobility solutions that can be used to achieve equivalent capabilities as AWS IoT FleetWise.
# Commands
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
This documentation describes how to use the [commands feature for AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html#commands-iotfw-namespace). For information about using the commands feature in AWS IoT Device Management, see [commands](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html).
You are solely responsible for deploying commands in a manner that is safe and compliant with applicable laws. For more information on your responsibilities, please see the [AWS Service Terms for AWS IoT Services](https://aws.amazon.com/service-terms/).
Use the commands feature to execute commands on a vehicle from the cloud. Commands target one device at a time, and can be used for low-latency, high-throughput applications, such as to retrieve the device-side logs, or to initiate a device state change.
The *command* is a resource that's managed by AWS IoT Device Management. It contains reusable configurations that are applied when sending a command execution to the vehicle. You can pre-define a set of commands for specific use cases, or use them to create reusable configurations for recurrent use cases. For example, you can configure commands that can be used by an App to lock a vehicle's door or to change the temperature remotely.
Using the AWS IoT commands feature, you can:
+ Create a command resource and reuse the configuration to send multiple commands to your target device and then execute them on the device.
+ Control the granularity with which you want each command to be executed on the device. For example, you can provision a vehicle as an AWS IoT thing, and then send a command to lock or unlock the doors of the vehicle.
+ Run multiple commands concurrently on the target device without waiting for the previous one to be completed.
+ Choose to enable notifications for commands events, and retrieve the status and result information from the device as it runs the command and once it's completed.
The following topics show you how to create, send, receive, and manage commands.
**Topics**
+ [Commands concepts](remote-command-concepts-states.md)
+ [Vehicles and commands](remote-command-vehicles.md)
+ [Create and manage commands](create-manage-remote-command-cli.md)
+ [Start and monitor command executions](send-monitor-remote-command-cli.md)
+ [Example: Using commands to control a vehicle steering mode (AWS CLI)](remote-command-tutorial.md)
+ [Command usage scenarios](remote-command-use-cases.md)
# Commands concepts
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
Commands are instructions that are sent from the cloud to your target device. The target device can be a vehicle and it must registered as an *AWS IoT thing* in the thing registry. The command can contain parameters that define an action that the actuators of the vehicle need to perform. The vehicle then parses the command and its parameters, and processes them to take the corresponding action. It then responds to the cloud application with the status of the command execution.
For the detailed workflow, see [Vehicles and commands](remote-command-vehicles.md).
**Topics**
+ [Commands key concepts](#remote-command-concepts)
+ [Command execution status](#remote-command-execution-status-codes)
## Commands key concepts
The following shows some key concepts for using the commands feature and how it works with last known state (LKS) state templates.
**Command**
A Command is an entity that you can use to send instructions to a physical vehicle to have it perform actions such as turning on the engine or changing the position of the windows. You can pre-define a set of commands for specific use cases, or use them to create reusable configurations for recurrent use cases. For example, you can configure commands that can be used by an App to lock a vehicle's door or to change the temperature remotely.
**Namespace**
When you use the commands feature, you must specify the namespace for the command. When you create a command in AWS IoT FleetWise, you must choose `AWS-IoT-FleetWise` as your namespace. When you use this namespace, you must provide the parameters that will be used to run the command on the vehicle. If you want to create a command in AWS IoT Device Management instead, you must use the `AWS-IoT` namespace instead. For more information, see [commands](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html) in the *AWS IoT Device Management developer guide*.
**Command states**
The commands that you create will be in an available state, which means that it can be used to start a command execution on the vehicle. If a command becomes outdated, you can deprecate the command. For a command in the deprecated state, existing command executions will run to completion. You cannot update the command or run any new executions. To send new executions, you must restore the command so that it becomes available.
You can also delete a command if it's no longer required. When you mark a command for deletion, if the command has been deprecated for a duration that's longer than the maximum timeout of 24 hours, the command will be deleted immediately. If the command isn't deprecated, or has been deprecated for a duration shorter than the maximum timeout, the command will be in a pending deletion state. The command will be removed automatically from your account after 24 hours.
**Parameters**
When creating a command, you can optionally specify the parameters that you want the target vehicle to execute when running the command. The command you create is a reusable configuration and it can be used to send multiple command executions to your vehicle and execute them concurrently. Alternatively, you can also specify the parameters only at runtime and choose to perform a one-time operation of creating a command and sending it to your vehicle.
**Target vehicle**
When you want to run the command, you must specify a target vehicle that will receive the command and perform specific actions. The target vehicle must have already been registered as a *thing* with AWS IoT. After you send the command to the vehicle, it will start executing an instance of the command based on the parameters and the values that you specified.
**Actuators**
When you want to run the command, you must specify the actuators on the vehicle that will receive the command and their values that determine the actions to be performed. You can optionally configure default values for the actuators to avoid sending inaccurate commands. For example, you can use a default value of `LockDoor` to a door lock actuator so that the command doesn't accidentally unlock the doors. For general information about actuators, see [Key concepts](how-iotfleetwise-works.md#key-concepts).
**Data type support**
The following data types are supported for the actuators that are used for the commands feature.
Arrays are not supported for telematics data, commands, or last known state (LKS). You can only use the array data type for vision systems data.
+ Floating point types. The following types are supported.
+ Float (32 bits)
+ Double (64 bits)
+ Integer (both signed and unsigned). The following integer types are supported.
+ int8 and uint8
+ int16 and uint16
+ int32 and uint32
+ Long. The following long types are supported.
+ Long (int64)
+ Unsigned long (uint64)
+ String
+ Boolean
**Command execution**
A command execution is an instance of a command running on a target device. The vehicle executes the command using either the parameters that you specified when you created the command or when you started the command execution. The vehicle then performs the operations specified and returns the status of the execution.
For a given vehicle, you can run multiple commands concurrently. For information about the maximum number of concurrent executions that you can run for each vehicle, see [AWS IoT Device Management commands quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#commands-limits).
**Last known state (LKS) state templates**
State templates provide a mechanism for vehicle owners to track the state of their vehicle. To monitor the last known state (LKS) of your vehicles in near-real time, you can create state templates and associate them with your vehicles.
Using the commands feature, you can perform "On Demand" operations that can be used for state data collection and processing. For example, you can request the current vehicle state one-time (fetch), or activate or deactivate previously deployed LKS state templates to start or stop reporting vehicle data. For examples that show how to use commands with state templates, see [Command usage scenarios](remote-command-use-cases.md).
## Command execution status
After you start the command execution, your vehicle can publish the status of the execution, and provide the reasons for the status as additional information about the execution. The following sections describe the various command execution statuses, and the status codes.
**Topics**
+ [Command execution status reason code and description](#remote-command-execution-status-reason-codes)
+ [Command execution status and status codes](#remote-command-execution-status-codes)
+ [Command execution timeout status](#remote-command-execution-status-timeout)
### Command execution status reason code and description
To report updates to the command execution status, your vehicles can use the `UpdateCommandExecution` API to publish the updated status information to the cloud, using the [Commands reserved topics](https://docs.aws.amazon.com/iot/latest/developerguide/reserved-topics.html#reserved-topics-commands) described in the *AWS IoT Core developer guide*. When reporting the status information, your devices can provide additional context about the status of each command execution using the `StatusReason` object, and the fields `reasonCode` and `reasonDescription` that are contained within the object.
### Command execution status and status codes
The following table shows the various command execution status codes and the allowed statuses that a command execution can transition to. It also shows whether a command execution is "terminal" (that is, no further status updates are forthcoming), whether the change is initiated by the vehicle or the cloud, and the different pre-defined status codes and how they map to the statuses that are reported by the cloud.
+ For information about how AWS IoT FleetWise uses the predefined status codes, and the `statusReason` object, see [Command status](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/include/aws/iotfleetwise/ICommandDispatcher.h) in the *Edge Agent for AWS IoT FleetWise software documentation*.
+ For additional information about terminal and non-terminal executions, and the transitions between the statuses, see [Command execution status](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-concepts.html#iot-command-execution-status) in the *AWS IoT Core developer guide*.
**Command execution status and source**
| Command execution status | Description | Initiated by device/cloud? | Terminal execution? | Allowed status transitions | Pre-defined status codes |
| --- | --- | --- | --- | --- | --- |
| CREATED | When the API request to start executing the command (StartCommandExecution API) is successful, the command execution status changes to CREATED. | Cloud | No | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | None |
| IN\$1PROGRESS | When the vehicle starts executing the command, it can publish a message to the response topic to update the status to IN\$1PROGRESS. | Device | No | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1COMMAND\$1IN\$1PROGRESS |
| SUCCEEDED | When the vehicle has successfully processed the command and completed the execution, it can publish a message to the response topic to update the status to SUCCEEDED. | Device | Yes | Not applicable | COMMAND\$1STATUS\$1SUCCEEDED |
| FAILED | When the vehicle failed to execute the command, it can publish a message to the response topic to update the status to FAILED. | Device | Yes | Not applicable | COMMAND\$1STATUS\$1EXECUTION\$1FAILED |
| REJECTED | If the vehicle fails to accept the command, it can publish a message to the response topic to update the status to REJECTED. | Device | Yes | Not applicable | None |
| TIMED\$1OUT | The command execution status can change to `TIMED_OUT` due to any of the following reasons. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) For more information about this status, see [Command execution timeout status](#remote-command-execution-status-timeout). | Device and cloud | No | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-concepts-states.html) | COMMAND\$1STATUS\$1EXECUTION\$1TIMEOUT |
### Command execution timeout status
A command execution timeout can be reported both by the cloud and the device. After the command is sent to the device, a timer starts. If there was no response received from the device within the specified duration, the cloud reports a `TIMED_OUT` status. In this case, the command execution in `TIMED_OUT` status is non-terminal.
The device can override this status to a terminal status, such as `SUCCEEDED`, `FAILED`, or `REJECTED`. It can also report that a timeout occurred when running the command. In this case, the command execution status stays at `TIMED_OUT` but the fields of the `StatusReason` object are updated based on the information reported by the device. The command execution in the `TIMED_OUT` status now becomes terminal.
For additional information, see [Command execution timeout considerations](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-command-execution-timeout) in the *AWS IoT Core developer guide*.
# Vehicles and commands
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
You are solely responsible for deploying commands in a manner that is safe and compliant with applicable laws.
To use the commands feature:
1. First, create a command resource. Optionally, specify the parameters that contain the information required to execute the command.
1. Specify the target vehicle that will receive the command and perform the specified actions.
1. Now, you can run the command on the target device, and check the command execution details to retrieve the status and use CloudWatch logs to further troubleshoot any issues.
The following sections show you the workflow between vehicles and commands.
**Topics**
+ [Workflow overview](#remote-command-vehicles-overview)
+ [Vehicle workflow](#iot-remote-command-devices-workflow)
+ [Commands workflow](#iot-remote-command-commands-workflow)
+ [(Optional) Commands notifications](#remote-command-notifications)
## Workflow overview
The following steps provide an overview of the commands workflow between your vehicles and commands. When you use any of the commands HTTP API operations, the request is signed using Sigv4 credentials.
**Note**
Except for the `StartCommandExecution` API operation, all operations that are performed over HTTP protocol use the control plane endpoint.
1.
**Establish MQTT connection and subscribe to commands topics**
To prepare for the commands workflow, the devices must establish an MQTT connection with the `iot:Data-ATS` endpoint, and subscribe to the commands request topic mentioned above. Optionally, your devices can also subscribe to the commands accepted and rejected response topics.
1.
**Create a vehicle model and command resource**
You can now create a vehicle and a command resource using the `CreateVehicle` and `CreateCommand` control plane API operations. The command resource contains the configurations to be applied when the command is executed on the vehicle.
1.
**Start command execution on the target device**
Start the command execution on the vehicle using the `StartCommandExecution` data plane API with your account-specific `iot:Jobs` endpoint. The API publishes a protobuf-encoded payload message to the commands request topic.
1.
**Update the result of the command execution**
The vehicle processes the command and the payload received, and then publishes the result of the command execution to the response topic using the `UpdateCommandExecution` API. If your vehicle subscribed to the commands accepted and rejected response topics, it will receive a message that indicates whether the response was accepted or rejected by the cloud service.
1.
**(Optional) Retrieve command execution result**
To retrieve the result of the command execution, you can use the `GetCommandExecution` control plane API operation. After your vehicle publishes the command execution result to the response topic, this API will return the updated information.
1.
**(Optional) Subscribe and manage commands events**
To receive notifications for command execution status updates, you can subscribe to the commands events topic. You can then use the `CreateTopicRule` control plane API to route the commands events data to other applications such as AWS Lambda functions or Amazon SQS and build applications on top of it.
## Vehicle workflow
The following steps describe the vehicle workflow in detail when using the commands feature.
**Note**
The operations that are described in this section use the MQTT protocol.
1.
**Establish an MQTT connection**
To prepare your vehicles to use the commands feature, it must first connect to the AWS IoT Core message broker. Your vehicle must be allowed to perform the `iot:Connect` action to connect to AWS IoT Core and establish an MQTT connection with the message broker. To find the data plane endpoint for your AWS account, use the `DescribeEndpoint` API or the `describe-endpoint` CLI command as shown below.
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
Running this command returns the account-specific data plane endpoint as shown below.
```
account-specific-prefix.iot.region.amazonaws.com
```
1.
**Susbcribe to commands request topic**
After a connection has been established, your devices can then subscribe to the AWS IoT commands MQTT request topic. When you create a command and start the command execution on your target device, a protobuf encoded payload message will be published to the request topic by the message broker. Your device can then receive the payload message and process the command. In this example, replace *``* with the unique identifier of your target vehicle. This ID can be the unique identifier of your vehicle or a thing name
**Note**
The payload message that's sent to the device must use the protobuf format.
```
$aws/commands/things//executions/+/request/protobuf
```
1.
**(Optional) Subscribe to commands response topics**
Optionally, you can subscribe to these commands response topics to receive a message that indicates whether the cloud service accepted or rejected the response from the device.
**Note**
It is optional for your vehicles to subscribe to the `/accepted` and `/rejected` response topics. Your vehicles will automatically receive these response messages even if they haven't explicitly subscribed to these topics.
```
$aws/commands/things//executions//response/protobuf/accepted
$aws/commands/things//executions//response/protobuf/rejected
```
1.
**Update the result of a command execution**
The target vehicle then processes the command. It then uses the `UpdateCommandExecution` API to publish the result of the execution to the following MQTT response topic.
**Note**
For a given vehicle and command execution, the ** must match the corresponding field in the request topic that the device subscribed to.
```
$aws/commands/things//executions//response/protobuf
```
The `UpdateCommandExecution` API is a data plane API operation over MQTT that's authenticated with TLS.
+ If the cloud service successfully processed the command execution result, a message is published to the MQTT accepted topic. The accepted topic uses the following format.
```
$aws/commands/things//executions//response/protobuf/accepted
```
+ If the cloud service failed to process the command execution result, a response is published to the MQTT rejected topic. The rejected topic uses the following format.
```
$aws/commands/things//executions//response/protobuf/rejected
```
For more information about this API and an example, see [Update command execution result](send-monitor-remote-command-cli.md#update-remote-command-execution-cli).
## Commands workflow
The following steps describe the commands workflow in detail.
**Note**
The operations that are described in this section use the HTTP protocol.
1.
**Register your vehicle**
Now that you've prepared your vehicle to use the commands feature, you can prepare your application by registering your vehicle and then creating a command that will be sent to the vehicle. To register the vehicle, create an instance of a vehicle model (model manifest) using the [https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateVehicle.html) control plane API operation. For more information and examples, see [Create a vehicle](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/create-vehicle.html).
1.
**Create a command**
Use the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) HTTP control plane API operation to model commands that are applicable to the vehicle that you're targeting. Specify any parameters and default values to be used when executing the command, and make sure that it uses the `AWS-IoT-FleetWise` namespace. For more information and examples for using this API, see [Create a command resource](create-manage-remote-command-cli.md#create-remote-command-cli).
1.
**Start the command execution**
You can now execute the command that you created on the vehicle using the [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_StartCommandExecution.html) data plane API operation. AWS IoT Device Management fetches the command and command parameters, and validates the incoming request. It then invokes AWS IoT FleetWise API with the required parameters to generate the vehicle-specific payload. The payload is then sent to the device by AWS IoT Device Management over MQTT to the command request topic that your device subscribed to. For more information and examples for using this API, see [Send a command (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli).
```
$aws/commands/things//executions/+/request/protobuf
```
**Note**
If the device was offline when the command was sent from the cloud and MQTT persistent sessions is in use, the command waits at the message broker. If the device comes back online before the time out duration, and if it has subscribed to the commands request topic, the device can then process the command and publish the result to the response topic. If the device doesn't come back online before the time out duration, the command execution will time out and the payload message will expire.
1.
**Retrieve the command execution**
After you've executed the command on the device, use the [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) control plane API operation to retrieve and monitor the result of the command execution. You can also use the API to obtain additional information about the execution data, such as when it was last updated, when the execution was completed, and the parameters specified.
**Note**
To retrieve the latest status information, your device must have published the command execution result to the response topic.
For more information and examples for using this API, see [Get command execution](send-monitor-remote-command-cli.md#get-remote-command-execution-cli).
## (Optional) Commands notifications
You can subscribe to commands events to receive notifications when the status of a command execution changes. The following steps show you how to subscribe to commands events, and then process them.
1.
**Create a topic rule**
You can subscribe to the commands events topic and receive notifications when the status of a command execution changes. You can also create a topic rule to route the data processed by the vehicle to other applications such as AWS Lambda functions. You can create a topic rule either using the AWS IoT console, or the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html) AWS IoT Core control plane API operation. For more information, see [Creating and AWS IoT rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-create-rule.html).
In this example, replace `` with the identifier of the command for which you want to receive notifications and `` with the status of the command execution.
```
$aws/events/commandExecution//
```
**Note**
To receive notifications for all commands and command execution statuses, you can use wildcard characters and subscribe to the following topic.
```
$aws/events/commandExecution/+/#
```
1.
**Receive and process commands events**
If you created a topic rule in the previous step to subscribe to commands events, then you can manage the commands push notifications that you receive. You can also optionally build applications on top of it, such as with AWS Lambda, Amazon SQS, Amazon SNS, or AWS Step Functions using the topic rule that you created.
The following code shows a sample payload for the commands events notifications that you'll receive.
```
{
"executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554",
"status":"FAILED",
"statusReason": {
"reasonCode": "4",
"reasonDescription": ""
},
"eventType": "COMMAND_EXECUTION",
"commandArn":"arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086",
"targetArn":"arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd",
"timestamp":1717708862107
}
```
# Create and manage commands
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
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.
**Topics**
+ [Create a command resource](#create-remote-command-cli)
+ [Retrieve information about a command](#get-remote-command-cli)
+ [List commands in your account](#list-remote-command-cli)
+ [Update or deprecate a command resource](#update-remote-command-cli)
+ [Delete a command resource](#delete-remote-command-cli)
## Create a command resource
You can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCommand.html) AWS IoT Core control plane API operation or the AWS IoT FleetWise console to create a command.
### Create a command (console)
You can use the AWS IoT FleetWise console to create a command.
**To create a command**
1. Open the [AWS IoT FleetWise console](https://console.aws.amazon.com/iotfleetwise).
1. On the navigation pane, choose **Commands**.
1. Choose **Create command**.
1. Specify a unique command ID to help you identify the command that you want to run on the vehicle.
1. (Optional) Specify an optional display name and description.
1. (Optional) Select the actuator and default parameter value. Parameters specify the actions the target vehicle can perform upon receiving the command. If you don't add parameters, you will need to provide them when running the command.
1. Choose an IAM role that grants permissions to generate the payload for commands. See [Controlling access](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload).
1. Choose **Create command**.
### Create a command (AWS CLI)
The following example shows how to create a command with a parameter.
#### Considerations when creating a command
When you create a command in AWS IoT FleetWise:
+ You must specify the `roleArn` that grants permission to create and run commands on your vehicle. For more information and about sample policies including when KMS keys are enabled, see [Grant AWS IoT Device Management permission to generate the payload for commands with AWS IoT FleetWise](controlling-access.md#generate-command-payload).
+ You must specify `AWS-IoT-FleetWise` as the namespace.
+ You can skip the `mandatory-parameters` field and specify them at run time instead. Alternatively, you can create a command with parameters, and optionally specify default values for them. If you specified default values, then at run time, you can use these values or override them by specifying your own values. For these additional examples, see [Command usage scenarios](remote-command-use-cases.md).
+ You can specify up to three name-value pairs for the `mandatory-parameters` field. However, when executing the command on the vehicle, only one name-value pair is accepted, and the `name` field must use the fully qualified name with the `$actuatorPath.` prefix.
+ Replace *command-id* with a unique identifier for the command. You can use UUID, alphanumeric characters, "-", and "\$1".
+ Replace *role-arn* with the IAM role that grants you permission to create and run commands, for example, `"arn:aws:iam:accountId:role/FwCommandExecutionRole"`.
+ (Optional) Replace *display-name* with a user-friendly name for the command, and *description* with a meaningful description of the command.
+ Replace *name* and *value* of the `mandatory-parameters` object with the required information for the command being created. The `name` field is the fully qualified name as defined in the signal catalog with `$actuatorPath.` as the prefix. For example, `name` can be *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* and `value` can be a boolean that indicates a steering mode status like *\$1"B": false\$1*.
```
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 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommand.html) 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.
+ The ID and ARN (Amazon Resource Name) of the command.
+ The date and time when the command was created and last updated.
+ The command state which indicates whether it's available to run on the vehicle.
+ Any parameters that you specified when creating the command.
```
{
"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 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommands.html) 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.
**Note**
You can also sort the list in ascending or descending order, or filter the list to display only commands that have a specific command parameter name.
```
aws iot list-commands --namespace "AWS-IoT-FleetWise"
```
The `ListCommands` API operation returns a response that contains the following information.
+ The ID and ARN (Amazon Resource Name) of the commands.
+ The date and time when the command was created and last updated.
+ The command state which indicates whether the commands are available to run on the vehicle.
## Update or deprecate a command resource
You can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCommand.html) AWS IoT Core control plane API operation or AWS IoT FleetWise console to update a command resource. You can update the display name and description of a command. You can also deprecate a command if it's not currently being used.
**Note**
You can't modify the namespace information or the parameters to be used when executing the command.
### Update a command (console)
**Update a command**
To update a command from the console, go to the [Commands](https://console.aws.amazon.com/iotfleetwise/home#/commands) page of the AWS IoT FleetWise console and perform the following steps.
1. Choose the command that you want to update, and then choose **Edit**.
1. Edit the command details, and then choose **Save changes**.
**Deprecate a command**
To deprecate a command from the console, go to the [Commands](https://console.aws.amazon.com/iotfleetwise/home#/commands) page of the AWS IoT FleetWise console and perform the following steps.
1. Choose the command that you want to deprecate, and then choose **Deprecate**.
1. Confirm the deprecation, and then choose **Deprecate**.
### Update a command (AWS CLI)
**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](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-deprecate) in the *AWS IoT Core Developer Guide*.
## Delete a command resource
You can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCommand.html) AWS IoT Core control plane API operation or AWS IoT FleetWise console to delete a command resource.
**Note**
Deletion actions are permanent and can't be undone. The command will be permanently removed from your account.
### Delete a command (console)
To delete a command from the console, go to the [Commands](https://console.aws.amazon.com/iotfleetwise/home#/commands) page of the AWS IoT FleetWise console and perform the following steps.
1. Choose the command that you want to delete, and then choose **Delete**.
1. Confirm that you want to delete the command, and then choose **Delete**.
### Delete a command (AWS CLI)
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:
+ If the command has been deprecated for a duration that's longer than the maximum timeout of 24 hours, the command will be deleted immediately and you'll see a HTTP `statusCode` of 204.
+ If the command isn't deprecated, or has been deprecated for a duration shorter than the maximum timeout, the command will be in a `pending deletion` state and you'll see a HTTP `statusCode` of 202. The command will be removed automatically from your account after the maximum timeout of 24 hours.
# Start and monitor command executions
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
After you've created a command resource, you can start a command execution on the target vehicle. Once the vehicle starts executing the command, it can start updating the result of the command execution and publish status updates and result information to the MQTT reserved topics. You can then retrieve the status of the command execution and monitor the status of the executions in your account.
This topic shows how you can send a command to your vehicle using the AWS CLI or AWS IoT FleetWise console. It also shows you how to monitor and update the status of the command execution.
**Topics**
+ [Update command execution result](#update-remote-command-execution-cli)
+ [Get command execution](#get-remote-command-execution-cli)
+ [List command executions in your account](#list-remote-command-execution-cli)
+ [Delete a command execution](#delete-remote-command-execution-cli)
## Send a command (console)
To send a command from the console, go to the [Vehicles](https://console.aws.amazon.com/iotfleetwise/home#/vehicles) page of the AWS IoT FleetWise console and perform the following steps.
1. Choose the vehicle that you want to send a command to.
1. Choose **Run command**.
1. Select the command ID.
1. Specify the command execution timeout, and then choose **Run command**.
## Send a command (AWS CLI)
You can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot_data_StartCommandExecution.html) AWS IoT data plane API operation to send a command to a vehicle. The vehicle then forwards the command to an automotive middleware service (like SOME/IP (Scalable Service-Oriented Middleware over IP)) or publishes it on a vehicle network (like a controller area network (CAN) device interface). The following example uses the AWS CLI.
**Topics**
+ [Considerations when sending a command](#send-remote-command-considerations)
+ [Obtain account-specific data plane endpoint](#send-remote-command-endpoint)
+ [Send a command example](#send-remote-command-example)
### Considerations when sending a command
When you start a command execution in AWS IoT FleetWise:
+ You must provision an AWS IoT thing for the vehicle. For more information, see [Provision AWS IoT FleetWise vehicles](provision-vehicles.md).
+ You must have already created a command with `AWS-IoT-FleetWise` as the namespace and provided a `role-Arn` that grants you permission to create and run commands in AWS IoT FleetWise. For more information, see [Create a command resource](create-manage-remote-command-cli.md#create-remote-command-cli).
+ You can skip the `parameters` field if you choose to use any default values that were specified for the parameters when creating the command. If the `mandatory-parameters` wasn't specified at creation time, or if you want to override any default values by specifying your own values for the parameters, you must specify the `parameters` field. For these additional examples, see [Command usage scenarios](remote-command-use-cases.md).
+ You can specify up to three name-value pairs for the `mandatory-parameters` field. However, when executing the command on the vehicle, only one name-value pair is accepted, and the `name` field must use the fully qualified name with the `$actuatorPath.` prefix.
### Obtain account-specific data plane endpoint
Before you run the API command, you must obtain the account-specific endpoint URL for the `iot:Jobs` endpoint. For example, if you run this command:
```
aws iot describe-endpoint --endpoint-type iot:Jobs
```
It will return the account-specfic endpoint URL as shown in the sample response below.
```
{
"endpointAddress": ".jobs.iot..amazonaws.com"
}
```
### Send a command example
To send a command to a vehicle, run the following command.
+ Replace *command-arn* with the ARN for the command that you want to execute. You can obtain this information from the response of the `create-command` CLI command.
+ Replace *target-arn* with the ARN for the target device, or AWS IoT thing, for which you want to execute the command.
**Note**
You can specify the target ARN of an AWS IoT thing (AWS IoT FleetWise vehicle). Thing groups and fleets aren't currently supported.
+ Replace *endpoint-url* with the account-specific endpoint that you obtained in [Obtain account-specific data plane endpoint](#send-remote-command-endpoint), prefixed by `https://`, for example, `https://123456789012abcd.jobs.iot.ap-south-1.amazonaws.com`.
+ Replace *name* and *value* with the `mandatory-parameters` field that you specified when you created the command using the `create-command` CLI.
The `name` field is the fully qualified name as defined in the signal catalog with `$actuatorPath.` as the prefix. For example, `name` can be *\$1actuatorPath.Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringMode* and `value` can be a boolean that indicates a steering mode status like *\$1"B": false\$1*.
+ (Optional) You can also specify an additional parameter, `executionTimeoutSeconds`. This optional field specifies the time in seconds within which the device must respond with the execution result. You can configure the timeout to a maximum value of 24 hours.
When the command execution has been created, a timer starts. Before the timer expires, if the command execution status doesn't change to a status that makes it terminal, such as `SUCCEEDED` or `FAILED`, then the status automatically changes to `TIMED_OUT`.
**Note**
The device can also report a `TIMED_OUT` status, or override this status to a status such as `SUCCEEDED`, `FAILED`, or `REJECTED`, and the command execution will become terminal. For more information, see [Command execution timeout status](remote-command-concepts-states.md#remote-command-execution-status-timeout).
```
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
}
]'
```
The `StartCommandExecution` API operation returns a command execution ID. You can use this ID to query the command execution status, details, and command execution history.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
After you run the command, your devices will receive a notification that contains the following information. The `issued_timestamp_ms` field corresponds to the time that the `StartCommandExecution` API was invoked. The `timeout_ms` corresponds to the time out value that's configured using the `executionTimeoutSeconds` parameter when invoking the `StartCommandExecution` API.
```
timeout_ms: 9000000
issued_timestamp_ms: 1723847831317
```
## Update command execution result
To update the status of the command execution, your device must have established an MQTT connection and subscribed to the following commands request topic.
In this example, replace *``* with the unique identifier of your target device, which can be the `VehicleId` or the thing name, and *``* with the identifier for the command execution.
**Note**
The payload must use the protobuf format.
It is optional for your devices to subscribe to the `/accepted` and `/rejected` response topics. Your devices will receive these response messages even if they haven't explicitly subscribed to them.
```
// Request topic
$aws/devices//command_executions/+/request/protobuf
// Response topics (Optional)
$aws/devices//command_executions//response/accepted/protobuf
$aws/devices//command_executions//response/rejected/protobuf
```
Your device can publish a message to the commands response topic. After processing the command, it sends a protobuf-encoded response to this topic. The ** field must match the corresponding field in the request topic.
```
$aws/devices//command_executions//response/
```
After your device publishes a response to this topic, you can retrieve the updated status information using the `GetCommandExecution` API. The status of a command execution can be any of those listed here.
+ `IN_PROGRESS`
+ `SUCCEEDED`
+ `FAILED`
+ `REJECTED`
+ `TIMED_OUT`
Note that a command execution in any of the statuses `SUCCEEDED`, `FAILED`, and `REJECTED` is terminal, and the status is reported by the device. When a command execution is terminal, this means that no further updates will be made to its status or related fields. A `TIMED_OUT` status may be reported by the device or the cloud. If reported by the cloud, an update of the status reason field may later be made by the device.
For example, the following shows a sample MQTT message that's published by the device.
**Note**
For the command execution status, if your devices use the `statusReason` object to publish the status information, you must make sure that:
The `reasonCode` uses the pattern `[A-Z0-9_-]+`, and it does not exceed 64 characters in length.
The `reasonDescription` doesn't exceed 1,024 characters in length. It can use any characters except control characters such as new lines.
```
{
"deviceId": "",
"executionId": "",
"status": "CREATED",
"statusReason": {
"reasonCode": "",
"reasonDescription": ""
}
}
```
For an example that shows how you can use the AWS IoT Core MQTT test client to subscribe to the topics and see the command execution messages, see [Viewing commands updates using the MQTT test client](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command-execution-start-monitor.html#iot-remote-command-execution-update-mqtt) in the *AWS IoT Core developer guide*.
## Get command execution
You can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCommandExecution.html) AWS IoT control plane API operation to retrieve information about a command execution. You must have already executed this command using the `StartCommandExecution` API operation.
To retrieve the metadata of an executed command, run the following command.
+ Replace *execution-id* with the ID of the command. You can obtain this information from the response of the `start-command-execution` CLI command.
+ Replace *target-arn* with the ARN for the target vehicle, or AWS IoT thing, for which you want to execute the command.
```
aws iot get-command-execution --execution-id execution-id \
--target-arn target-arn
```
The `GetCommandExecution` API operation returns a response that contains information about the ARN of the command execution, the execution status, and the time when the command started executing and when it completed. The following code shows a sample response from the API request.
To provide additional context about the status of each command execution, the commands feature provides a `statusReason` object. The object contains two fields, `reasonCode` and `reasonDescription`. Using these fields, your devices can provide additional information about the status of a command execution. This information will override any default `reasonCode` and `reasonDescription` that's reported from the cloud.
To report this information, your devices can publish the updated status information to the cloud. Then, when you retrieve the command execution status using the `GetCommandExecution` API, you'll see the latest status codes.
**Note**
The `completedAt` field in the execution response corresponds to the time when the device reports a terminal status to the cloud. In the case of `TIMED_OUT` status, this field will be set only when the device reports A timeout. When the `TIMED_OUT` status is set by the cloud, the `TIMED_OUT` status is not updated. For more information about the time out behavior, see [Command execution timeout status](remote-command-concepts-states.md#remote-command-execution-status-timeout).
```
{
"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 }
}'
}
```
## List command executions in your account
Use the [https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCommandExecutions.html) AWS IoT Core control plane HTTP API operation to list all command executions in your account. The example uses the AWS CLI.
**Topics**
+ [Considerations when listing command executions](#list-remote-command-considerations)
+ [List command executions example](#list-remote-command-example)
### Considerations when listing command executions
The following are some considerations when using the `ListCommandExecutions` API.
+ You must specify at least the `targetArn` or the `commandArn` depending on whether you want to list executions for a particular command or a target vehicle. The API request cannot be empty and cannot contain both fields in the same request.
+ You must provide only the `startedTimeFilter` or the `completedTimeFilter` information. The API request cannot be empty and cannot contain both fields in the same request. You can use the `before` and `after` fields of the object to list command executions that were either created or completed within a specific timeframe.
+ Both the `before` and `after` fields must not be greater than the current time. By default, if you don't specify any value, the `before` field is the current time and `after` field is current time - 6 months. That is, depending on the filter that you use, the API will list all executions that were either created or completed within the last six months.
+ You can use the `sort-order` parameter to specify whether you want to list the executions in the ascending order. By default, the executions will be listed in the descending order if you don't specify this field.
+ You cannot filter the command executions based on their status when listing command executions for a command ARN.
### List command executions example
The following example shows you how to list command executions in your AWS account.
When running the command, you must specify whether to filter the list to display only command executions that were created for a particular device using the `targetArn`, or executions for a particular command specified using the `commandArn`.
In this example, replace:
+ *``* with the Amazon Resource Number (ARN) of the device for which you're targeting the execution, such as `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``* with the Amazon Resource Number (ARN) of the device for which you're targeting the execution, such as `arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f`.
+ *``* with the time after which you want to list the executions that were created, for example, `2024-11-01T03:00`.
```
aws iot list-command-executions \
--target-arn \
--started-time-filter '{after=}' \
--sort-order "ASCENDING"
```
Running this command generates a response that contains a list of command executions that you created, and the time when the executions started executing, and when it completed. It also provides status information, and the `statusReason` object that contains additional information about the 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"
}
]
}
```
## Delete a command execution
If you no longer want to use a command execution, you can remove it permanently from your account.
**Note**
A command execution can be deleted only if it has entered a terminal status, such as `SUCCEEDED`, `FAILED`, or `REJECTED`.
The following example shows you how to delete a command execution using the `delete-command-execution` AWS CLI command. Replace *``* with the identifier of the command execution that you're deleting.
```
aws iot delete-command-execution --execution-id
```
If the API request is successful, then the command execution generates a status code of 200. You can use the `GetCommandExecution` API to verify that the command execution no longer exists in your account.
# Example: Using commands to control a vehicle steering mode (AWS CLI)
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
The following example shows you how to use the commands feature using the AWS CLI. This example uses an AWS IoT FleetWise vehicle as a target device to show how you can send a command to remotely control the steering mode.
**Topics**
+ [Overview of vehicle steering mode example](#iot-remote-command-tutorial-overview)
+ [Prerequisites](#iot-remote-command-tutorial-prereq)
+ [IAM policy for using remote commands](#remote-command-policy)
+ [Run AWS IoT commands (AWS CLI)](#iot-remote-command-tutorial-run)
+ [Cleaning up](#remote-command-tutorial-clean)
## Overview of vehicle steering mode example
In this example, you'll:
1. Create a command resource for the operation using the `create-command` AWS CLI to change the steering mode of the vehicle.
1. Retrieve information about the command, such as the time when it was created or last updated using the `get-command` AWS CLI.
1. Send the command to the vehicle using the `start-command-execution` AWS CLI with the steering mode as a mandatory parameter, which will then get executed on the device.
1. Get the result of the command execution using the `get-command-execution` AWS CLI. You can check when the execution completes, and retrieve additional details such as the execution result, and the time it took to complete executing the command.
1. Perform clean up activities by removing any commands and command executions that you no longer want to use.
## Prerequisites
Before you run this example:
+ Provision your AWS IoT FleetWise vehicle as an AWS IoT thing in the AWS IoT registry. You must also add a certificate to your thing and activate it, and attach a policy to your thing. Your device can then connect to the cloud and execute the commands. For more information, see [Provision vehicles](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/provision-vehicles.html).
+ Create an IAM user and an IAM policy that grants you permission to perform the API operations for using commands, as shown in [IAM policy for using remote commands](#remote-command-policy).
## IAM policy for using remote commands
The following table shows a sample IAM policy that grants access to all the control plane and data plane API operations for the commands feature. The user of the application will have permissions to perform all remote command API operations, as shown in the table.
**API operation**
| API action | Control/data plane | Protocol | Description | Resource |
| --- | --- | --- | --- | --- |
| CreateCommand | Control plane | HTTP | Creates a command resource | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommand | Control plane | HTTP | Retrieves information about a command | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommand | Control plane | HTTP | Updates information about a command or to deprecate it | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommands | Control plane | HTTP | Lists commands in your account | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommand | Control plane | HTTP | Deletes a command | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| StartCommandExecution | Data plane | HTTP | Starts executing a command | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| UpdateCommandExecution | Data plane | MQTT | Update a command execution | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| GetCommandExecution | Control plane | HTTP | Retrieves information about a command execution | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| ListCommandExecutions | Control plane | HTTP | Lists command executions in your account | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
| DeleteCommandExecution | Control plane | HTTP | Deletes a command execution | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/remote-command-tutorial.html) |
In this example, replace:
+ `us-east-1` with your AWS Region, such as `ap-south-1`.
+ `111122223333` with your AWS account number, such as `57EXAMPLE833`.
+ `command-id`, `command-id1`, and `command-id2` with your unique command identifier, such as `LockDoor` or `TurnOffAC`.
+ `thing-name` with your AWS IoT thing name, such as `my_car`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:CreateCommand",
"iot:GetCommand",
"iot:ListCommands",
"iot:UpdateCommand",
"iot:DeleteCommand"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id1",
"arn:aws:iot:us-east-1:111122223333:command/command-id2"
]
},
{
"Action": [
"iot:GetCommandExecution",
"iot:ListCommandExecutions",
"iot:DeleteCommandExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
},
{
"Action": "iot:StartCommandExecution",
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:111122223333:command/command-id",
"arn:aws:iot:us-east-1:111122223333:thing/thing-name"
]
}
]
}
```
------
## Run AWS IoT commands (AWS CLI)
The following shows how you can use the AWS CLI to perform commands operations and change the vehicle steering mode.
1.
**Create a command resource for the steering mode operation**
Create the command that you want to send to your device using the `create-command` CLI. In this example, specify:
+ `command-id` as *`TurnOffSteeringMode`*
+ `role-arn` as `"arn:aws:iam:accountId:role/FwCommandExecutionRole"` The `role-arn` must be provided, as it is the IAM role that grants permissions to create and run commands on your vehicle. For more information, see [Grant AWS IoT Device Management permission to generate the payload for commands with AWS IoT FleetWise](controlling-access.md#generate-command-payload).
+ `display-name` as "*`Turn off steering mode`*"
+ `namespace` must be `AWS-IoT-FleetWise`
+ `mandatory-parameters` as a name-value pair, with `name` as "*\$1actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode*" and defaultValue as `{ "S": "true" }`
**Note**
You can also create a command without specifying any mandatory parameters. You must then specify the parameters to use when executing the command using the `start-command-execution` CLI. For an example, see [Command usage scenarios](remote-command-use-cases.md).
**Important**
When using the `AWS-IoT-FleetWise` namespace, you must ensure that the `Name` field specified as part of the `mandatory-parameters` use the `$actuatorPath.` prefix, and the `Value` field must use the string data type.
```
aws iot create-command \
--command-id TurnOffSteeringMode \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--display-name "Turn off steering mode" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": { "S": "true" }
}
]'
```
The following output shows a sample response from the CLI, where `ap-south-1` and `123456789012` are examples of the AWS Region and AWS account ID.
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode"
}
```
For additional examples on using this command, see [Create a command resource](create-manage-remote-command-cli.md#create-remote-command-cli).
1.
**Retrieve information about the command**
Run the following command to retrieve information about the command, where `command-id` is the command ID in the output of the `create-command` operation from above.
**Note**
If you create more than one command, you can use the `ListCommands` API to list all commands in your account, and then use the `GetCommand` API to obtain additional information about a specific command. For more information, see [List commands in your account](create-manage-remote-command-cli.md#list-remote-command-cli).
```
aws iot get-command --command-id TurnOffSteeringMode
```
Running this command generates the following response. You'll see the time when the command was created and when it was last updated, any parameters that you specified, and whether the command is available to run on the device.
```
{
"commandId": "TurnOffSteeringMode",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"namespace": "AWS-IoT-FleetWise",
"mandatoryParameters":[
{
"name": "$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode",
"defaultValue": {"S": "true" }
}
],
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
"deprecated": false
}
```
For additional examples on using this command, see [Retrieve information about a command](create-manage-remote-command-cli.md#get-remote-command-cli).
1.
**Start the command execution**
Run the following command to start executing the command, where `command-arn` is the command ARN in the output of the `get-command` operation from above. The `target-arn` is the ARN of the target device for which you're executing the command, for example, *`myVehicle`*.
In this example, since you provided default values for the parameters when creating the command, the `start-command-execution` CLI can use these values when executing the command. You can also choose to override the default value by specifying a different value for the parameters when using the CLI.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode \
--target-arn arn:aws:iot:ap-south-1:123456789012:thing/myVehicle
```
Running this command returns a command execution ID. You can use this ID to query the command execution status, details, and command execution history.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}
```
For additional examples on using the CLI, see [Send a command (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli).
1.
**Retrieve information about the command execution**
Run the following command to retrieve information about the command that you executed on the target device. Specify the `execution-id`, which you obtained as output of the `start-command-execution` operation from above, and the `target-arn`, which is the ARN of the device that you're targeting.
**Note**
To obtain the latest status information, your devices must have published the updated status information to the MQTT reserved response topic for commands using the `UpdateCommandExecution` MQTT API. For more information, see [Update command execution result](send-monitor-remote-command-cli.md#update-remote-command-execution-cli).
If you start more than one command execution, you can use the `ListCommandExecutions` API to list all command executions in your account, and then use the `GetCommandExecution` API to obtain additional information about a specific execution. For more information, see [List command executions in your account](send-monitor-remote-command-cli.md#list-remote-command-execution-cli).
```
aws iot get-command-execution \
--execution-id <"07e4b780-7eca-4ffd-b772-b76358da5542"> \
--target-arn arn:aws:iot:us-east-1::thing/myVehicle
```
Running this command returns information about the command execution, the execution status, the time when it started executing, and the time when it was completed. For example, the following response shows that the command execution succeeded on the target device and the steering mode was turned off.
```
{
"executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
"commandArn": "arn:aws:iot:ap-south-1:123456789012:command/TurnOffSteeringMode",
"targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myVehicle",
"result": "SUCCEEDED",
"statusReason": {
"reasonCode": "65536",
"reasonDescription": "SUCCESS"
},
"result": {
"KeyName": {
"S": "",
"B": true,
"BIN": null
}
},
"createdAt": "2024-03-23T00:50:10.095000-07:00",
"completedAt": "2024-03-23T00:50:10.095000-07:00",
"parameters": '{
"$actuatorPath.Vehicle.Chassis.SteeringWheel.TurnOffSteeringMode":
{ "S": "true" }
}'
}
```
## Cleaning up
Now that you've created a command and executed it on your device, if you no longer intend to use this command, you can delete it. Any pending command executions that are in progress will continue to run without getting impacted by the deletion request.
**Note**
Alternatively, you can also deprecate a command if it's outdated and you might need to use it later to run on the target device.
1.
**(Optional) Deprecate the command resource**
Run the following command to deprecate the command, where `command-id` is the command ID in the output of the `get-command` operation from above.
```
aws iot update-command \
--command-id TurnOffSteeringMode \
--deprecated
```
Running this command returns an output that shows the command has been deprecated. You can also use the CLI to restore the command.
**Note**
You can also use the `update-command` CLI to update the display name and description of a command. For additional information, see [Update or deprecate a command resource](create-manage-remote-command-cli.md#update-remote-command-cli).
```
{
"commandId": "TurnOffSteeringMode",
"deprecated": true,
"lastUpdatedAt": "2024-05-09T23:16:51.370000-07:00"
}
```
1.
**Delete the command**
Run the following command to delete the command, specified by the `command-id`.
**Note**
The deletion action is permanent and can't be undone.
```
aws iot delete-command --command-id TurnOffSteeringMode
```
If the deletion request is successful, you'll see a HTTP `statusCode` of 202 or 204 depending on whether you marked the command for deprecation and when it was deprecated. For more information and an example, see [Delete a command resource](create-manage-remote-command-cli.md#delete-remote-command-cli).
You can use the `get-command` CLI to verify that the command has been removed from your account.
1.
**(Optional) Delete the command executions**
By default, all command executions will be deleted in six months from the date that you create them. You can view this information using the `timeToLive` parameter from the `GetCommandExecution` API.
Alternatively, if your command execution has become terminal, such as when your execution status is one of `SUCCEEDED`, `FAILED`, or `REJECTED`, you can delete the command execution. Run the following command to delete the execution, where `execution-id` is the Execution ID in the output of the `get-command-execution` operation from above.
```
aws iot delete-command-execution \
--execution-id "07e4b780-7eca-4ffd-b772-b76358da5542"
```
You can use the `get-command-execution` CLI to verify that the command execution has been removed from your account.
# Command usage scenarios
**Important**
Access to certain AWS IoT FleetWise features is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md).
When using the commands feature, you can create and run commands in the following scenarios:
+ You can omit the parameters during creation and specify only the command ID. In this case, you need to specify the parameters to be used when running the command on the target device.
+ You can specify one or more parameters, and configure default values for them when creating the command. Providing default values will help protect you from sending inaccurate commands.
+ You can specify one or more parameters, and configure values for them when creating the command. More than one parameter can be provided but only one of them will be executed, and the `Name` field of this parameter must use the `$actuatorPath` prefix.
This section provides some usage scenarios for the `CreateCommand` and the `StartCommandExecution` API and using the parameters. It also shows you some examples of using commands with state templates.
**Topics**
+ [Creating a command with no parameters](#remote-command-use-case1)
+ [Creating a command with default values for parameters](#remote-command-use-case2)
+ [Creating a command with parameter values](#remote-command-use-case3)
+ [Using commands with state templates](#remote-command-use-cases-templates)
## Creating a command with no parameters
The following use case shows how you can use the `CreateCommand` API or the `create-command` CLI to create a command with no parameters. When you create a command, you only need to provide a command ID and a role ARN.
This use case is especially useful in recurrent use cases, such as when you want to send the same command multiple times to a vehicle. In this case, the command is not tied to a specific actuator and gives you the flexibility to execute the command on any actuator. You must specify the parameters at run time instead when executing the command using the `StartCommandExecution` API or the `start-command-execution` CLI, which includes the actuators and physical signal values.
### Creating a command without `mandatory-parameters` input
This use case shows how to create a command without any mandatory parameters input.
```
aws iot create-command \
--command-id "UserJourney1" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--description "UserJourney1 - No mandatory parameters" \
--namespace "AWS-IoT-FleetWise"
```
### Running a command created without `mandatory-parameters` input
In this first example, the command that was created above allows you to execute a command on any actuator without restrictions. To set `actuator1` to a value of 10, run:
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
Similarly, you can run a command that sets `actuator3` to a value of `true`.
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney1 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator3": {"S": "true"}
}'
```
## Creating a command with default values for parameters
This command only allows you to execute a command on the specified actuator. Providing default values will help protect you from sending inaccurate commands. For example, a `LockDoor` command that locks and unlocks doors can be configured with a default value to avoid the command from accidentally unlocking doors.
This use case is especially useful when you want to send the same command multiple times and perform different actions on the same actuator, such as locking and unlocking the doors of a vehicle. If you want to set the actuator to the default value, then you don't need to pass qny `parameters` to the `start-command-execution` CLI. If you do specify a different value for the `parameters` in the `start-command-execution` CLI, it will override the default value.
### Creating a command with default values for `mandatory-parameters`
The following command shows how to provide a default value for actuator1.
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1",
"defaultValue": {"S": "0"}
}
]'
```
### Running a command created with default values for `mandatory-parameters`
The command `UserJourney2` allows you to execute a command without the need to pass an input value during runtime. In this case, the execution at runtime will use the default values specified during creation.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle
```
You can also pass a different value for the same actuator, actuator1, during runtime, which will override the default value.
```
aws iot-jobs-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney3 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "139"}
}'
```
## Creating a command with parameter values
This command only allows you to execute a command on the specified actuator. It also forces you to set a value for the actuator during runtime.
This use case is especially useful when you want the end user to only perform certain specified actions on some of the actuators when running it on the vehicle.
**Note**
You can have more than name-value pairs for the `mandatory-parameters` input, with default values for some or all of them. At runtime, you can then determine the parameter that you want to use when running on the actuator, provided the actuator name uses the fully-qualified name with the `$actuatorPath.` prefix.
### Creating command without default values for `mandatory-parameters`
This command only allows you to execute a command on the specified actuator. It also forces you to set a value for the actuator during runtime.
```
aws iot create-command \
--command-id "UserJourney2" \
--namespace "AWS-IoT-FleetWise" \
--role-arn "arn:aws:iam:accountId:role/FwCommandExecutionRole" \
--mandatory-parameters '[
{
"name": "$actuatorPath.Vehicle.actuator1"
}
]'
```
### Running a command created without default values for `mandatory-parameters`
When running the command, in this case, you must specify a value for actuator1. The command execution shown below will successfully set the value of `actuator1` to `10`.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/UserJourney2 \
--target-arn arn:aws:iot:region:111122223333:thing/target-vehicle \
--parameters '{
"$actuatorPath.Vehicle.actuator1": {"S": "10"}
}'
```
## Using commands with state templates
You can also use the commands API operations for state data collection and processing. For example, you can fetch a one-time state snapshot or to activate or deactivate state templates to start or stop collecting vehicle state data. The following examples show how to use the commands feature with state templates. For more information, see [State template operations for data collection and processing](state-template-api-operations.md)
**Note**
The Name field specified as part of the `mandatory-parameters` input must use the `$stateTemplate` prefix.
### Example 1: Creating commands for state templates with default values
This example shows how to use the `create-command` CLI to activate state templates.
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name"
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
}
]'
```
Similarly, the following command shows an example of how you can use the `start-command-execution` CLI for state templates.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"}
}'
```
### Example 2: Creating commands for state templates without default values
The following command creates multiple state templates without default values for any of the parameters. It forces you to run the command with these parameters and the values for them.
```
aws iot create-command \
--command-id \
--display-name "Activate State Template" \
--namespace AWS-IoT-FleetWise \
--mandatory-parameters '[
{
"name": "$stateTemplate.name",
"defaultValue": {"S": "ST123"}
},
{
"name": "$stateTemplate.operation",
"defaultValue": {"S": "activate"}
},
{
"name": "$stateTemplate.deactivateAfterSeconds",
"defaultValue": {"L": "120"}
}
]'
```
The following command shows how you can use the `start-command-execution` CLI for the example above.
```
aws iot-data start-command-execution \
--command-arn arn:aws:iot:region:111122223333:command/ \
--target-arn arn:aws:iot:region:111122223333:thing/ \
--parameters '{
"$stateTemplate.name": {"S": "ST345"},
"$stateTemplate.operation": {"S": "activate"},
"$stateTemplate.deactivateAfterSeconds" : {"L": "120"}
```