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. # State template operations for data collection and processing **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 sections describe how to use state templates to activate and deactivate data collection, perform a fetch operation, and process state data from your vehicles. **Topics** + [Activate and deactivate state data collection using state templates](start-stop-data-ingestion.md) + [Fetch a vehicle state snapshot using state templates](on-demand-operations.md) + [Process last known state vehicle data using MQTT messaging](process-last-known-state-vehicle-data.md) # Activate and deactivate state data collection using state templates **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 sections describe how to activate and deactivate data ingestion with state templates using the AWS CLI. **Important** Before you start, make sure that you already created a [state template](state-templates.md), and associated it and its update strategy with a vehicle. You must activate a state template so the Edge Agent can send signal updates to the cloud. To perform these operations with state templates, first create a command resource and then start the command execution on the vehicle. The following section describes how to use this API and how to activate and deactivate data ingestion. **Topics** + [Using the `CreateCommand` API](#start-stop-ingestion-create-command) + [Example: Activate a state template](#start-stop-ingestion-activate-template) + [Example: Deactivate a state template](#start-stop-ingestion-deactivate-template) ## Using the `CreateCommand` API Create a command resource in the "`AWS-IoTFleetwise`" namespace, and use the following parameters when you create or send a command resource for a state template: + `$stateTemplate.name` – The name of the state template on which to perform the operation. The state template must be applied to the vehicle before you can perform an operation. For more information, see [Associate an AWS IoT FleetWise state template with a vehicle](state-templates.md#apply-state-templates). + `$stateTemplate.operation` – The operation to be performed on the state template. Use one of the following values for this parameter: + `activate` – The Edge Agent starts sending signal updates to the cloud based on the `stateTemplateUpdateStrategy` you specified (on-change or periodic) when you applied the state template to the vehicle. For more information, see [Associate an AWS IoT FleetWise state template with a vehicle](state-templates.md#apply-state-templates). Also, you can define an automatic state template deactivation time to stop updates after a specified time period. If an automatic deactivation time is not provided, the state templates will keep sending updates until a deactivate call is issued. As soon as the `activate` command is received, the device should send the signals specified in the state template according to the update strategy. AWS IoT FleetWise recommends that when an activate command is received by the device, the first message it sends should contain a snapshot of all the signals in the state template. Subsequent messages should be sent according to the update strategy. + `deactivate` – The Edge Agent stops sending signal updates to the cloud. + `fetchSnapshot` – The Edge Agent sends a onetime snapshot of the signals defined in the state template regardless of the `stateTemplateUpdateStrategy` you specified when you applied the state template to the vehicle. + (Optional) `$stateTemplate.deactivateAfterSeconds` – The state template is automatically deactivated after the time specified. This parameter can only be used when the value of the `$stateTemplate.operation` parameter is “activate”. If this parameter isn't specified, or if the value of this parameter is 0, the Edge Agent keeps sending signal updates to the cloud until a "deactivate" operation is received for the state template. The state template is never automatically deactivated. Minimum value: 0, maximum value: 4294967295. **Note** The API returns success in response to an activation request for a template already in the active state. The API returns success in response to a deactivation request for a template already in the deactivation state. The most recent request that you make on a state template is the one that takes effect. For example, if you make a request for a state template to deactivate in one hour, then make a second request for that same template to deactivate in four hours, the four hour deactivation takes effect due to it being the most recent request. **Important** A validation exception can occur in any of the following scenarios: A state template is provided which is not `ASSOCIATED` with a vehicle. A request is made to activate a state template but it hasn't been `DEPLOYED` on a vehicle. A request is made to a state template but it's being `DELETED` on a vehicle. ## Example: Activate a state template To activate a state template, first create a command resource. You can then send the following command to the vehicle on which you want to activate the state template. This example shows how you can specify default values for the parameters when creating a command. These parameters and their values are used when starting the command execution to activate the state template. 1. **Create a command resource** Before you can send a command to the vehicle, you must create a command resource. You can specify alternative values for mandatory parameters when you send the command to the vehicle. For more information, see [Create a command resource](create-manage-remote-command-cli.md#create-remote-command-cli). **Important** `$stateTemplate.name` and `$stateTemplate.operation` parameters must be provided as a string data type. If any other data type is provided, or if either of these two parameters is missing, the command execution fails with a validation exception. The `$stateTemplate.deactivateAfterSeconds` parameter must be provided as a `Long` data type. ``` aws iot create-command \ --description "This command activates a state template on a vehicle" --command-id ActivateStateTemplate \ --display-name "Activate State Template" \ --namespace AWS-IoTFleetWise \ --mandatory-parameters '[ { "name": "$stateTemplate.name", "defaultValue": {"S": "ST123"} }, { "name": "$stateTemplate.operation", "defaultValue": {"S": "activate"} }, { "name": "$stateTemplate.deactivateAfterSeconds", "defaultValue": {"L": "120"} } ]' ``` 1. **Start the command execution on the vehicle** After the command is created, send the command to the vehicle. If you didn't specify values for the mandatory parameters when you created the command resource, you must specify them now. For more information, see [Send a command (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli). **Important** Make sure that you use the account-specific AWS IoT jobs data plane API endpoint for the API operation. ``` aws iot-jobs-data start-command-execution \ --endpoint-url \ --command-arn arn:aws:iot:region:111122223333:command/ActivateStateTemplate \ --target-arn arn:aws:iot:region:111122223333:thing/ ``` 1. **Retrieve the status of the state template operation** After you start the command execution, you can use the `GetCommandExecution` API to retrieve the state template. ``` aws iot get-command-execution --execution-id ``` ## Example: Deactivate a state template To deactivate a state template, first create a command resource. You can then send the following command to the vehicle on which you want to deactivate the state template. This example shows how you can specify default values for the parameters when creating a command. These parameters and their values are used when starting the command execution to deactivate the state template. 1. **Create a command resource** Before you can send a command to the vehicle, you must create a command resource. You can specify alternative values for mandatory parameters when you send the command to the vehicle. For more information, see [Create a command resource](create-manage-remote-command-cli.md#create-remote-command-cli). ``` aws iot create-command \ --description "This command deactivates a state template on a vehicle" --command-id DeactivateStateTemplate \ --display-name "Deactivate State Template" \ --namespace AWS-IoTFleetWise \ --mandatory-parameters '[ { "name": "$stateTemplate.name", "defaultValue": {"S": "ST123"} }, { "name": "$stateTemplate.operation", "defaultValue": {"S": "deactivate"} } ]' ``` 1. **Start the command execution on the vehicle** After the command is created, send the command to the vehicle. If you didn't specify values for the mandatory parameters when you created the command resource, you must specify them now. For more information, see [Send a command (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli). ``` aws iot-jobs-data start-command-execution \ --endpoint-url \ --command-arn arn:aws:iot:region:111122223333:command/DeactivateStateTemplate \ --target-arn arn:aws:iot:region:111122223333:thing/ ``` 1. **Retrieve the status of the state template operation** After you start the command execution, you can use the `GetCommandExecution` API to retrieve the state template. ``` aws iot get-command-execution --execution-id ``` # Fetch a vehicle state snapshot using state templates **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 fetch a vehicle's last known state using 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. **Important** A validation exception can occur in any of the following scenarios: A state template is provided which is not `ASSOCIATED` with a vehicle. A request is made to activate a state template but it hasn't been `DEPLOYED` on a vehicle. A request is made to a state template but it's being `DELETED` on a vehicle. ## Fetch a vehicle state snapshot (console) You can use the AWS IoT FleetWise console to fetch a vehicle's last known state. AWS IoT FleetWise will create a command for you to fetch data. **To fetch a vehicle's state** 1. Open the [AWS IoT FleetWise console](https://console.aws.amazon.com/iotfleetwise). 1. On the navigation pane, choose **Vehicles**. 1. Choose a vehicle from the list to open its details page. 1. On the **State templates** tab, choose **Fetch data**. 1. Select the IAM role that grants AWS IoT FleetWise permissions to send a command and fetch data. See [Controlling access](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html#generate-command-payload). 1. Choose **Fetch state**. ## Fetch a vehicle state snapshot (AWS CLI) To fetch a state snapshot, first create a command resource. You can then send the following command to the vehicle for which you want to fetch the state snapshot. For more information about using the `CreateCommand` API and its parameters, see [Using the `CreateCommand` API](start-stop-data-ingestion.md#start-stop-ingestion-create-command). 1. **Create a command resource** The following example shows how to create the command resource to perform the fetch operation. You can specify alternative values for mandatory parameters when you send the command to the vehicle. For more information, see [Create a command resource](create-manage-remote-command-cli.md#create-remote-command-cli). ``` aws iot create-command \ --command-id \ --display-name "FetchSnapshot State Template" \ --namespace AWS-IoTFleetWise \ --mandatory-parameters '[ { "name": "$stateTemplate.name", "defaultValue": {"S": "ST123"} }, { "name": "$stateTemplate.operation", "defaultValue": {"S": "fetchSnapshot"} } ]' ``` Response: ``` { "commandId": "", "commandArn": "arn:aws:iot::111122223333:command/" } ``` 1. **Start command execution to fetch state snapshot** After the command is created, send the command to the vehicle. If you didn't specify values for the mandatory parameters when you created the command resource, you must specify them now. For more information, see [Send a command (AWS CLI)](send-monitor-remote-command-cli.md#send-remote-command-cli). ``` aws iot-jobs-data start-command-execution \ --command-arn arn:aws:iot:region:111122223333:command/ \ --target-arn arn:aws:iot:region:111122223333:thing/ ``` Response: ``` { "executionId": "" } ``` 1. Retrieve the status of the state template operation After you start the command execution, you can use the `GetCommandExecution` API to retrieve the state template. ``` aws iot get-command-execution --execution-id ``` # Process last known state vehicle data using MQTT messaging **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). To receive updates from your vehicle and process its data, subscribe to the following MQTT topic. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-devices.html) in the *AWS IoT Core Developer Guide.* ``` $aws/iotfleetwise/vehicles/$vehicle_name/last_known_state/$state_template_name/data ``` Last known state signal update messages might be received out of order, as MQTT doesn't guarantee ordering. Any clients which use MQTT to receive and process vehicle data must handle this. Last known state signal update messages follow the MQTT 5 messaging protocol. The message header for each MQTT message has the following user properties: + **vehicleName** – A unique identifier of the [vehicles](vehicles.md). + **stateTemplateName** – A unique identifier of the last known state [state template](state-templates.md). In addition, you can specify [vehicle attributes](signal-catalogs.md) to be included in the MQTT message header by specifying the `metadataExtraDimensions` request parameter while updating or creating a state template. (See [ State Templates](state-templates.md).) The user properties in the MQTT message header are useful for routing messages to different destinations without inspecting the payload. The MQTT message payload contains data collected from the vehicles. You can specify vehicle attributes to be included in the MQTT message payload by specifying the `extraDimensions` request parameter while creating or updating a state template (see [Create an AWS IoT FleetWise state template](state-templates.md)). The extra dimensions enrich the data collected from the vehicles by associating extra dimensions to them. The MQTT message payload is protocol buffers (Protobuf) encoded, and the MQTT message header contains a content type indicator defined as application/octet-stream. The Protobuf encoding schema is as follows: ``` // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 syntax = "proto3"; option java_package = "com.amazonaws.iot.autobahn.schemas.lastknownstate"; package Aws.IoTFleetWise.Schemas.CustomerMessage; message LastKnownState { /* * The absolute timestamp in milliseconds since Unix Epoch of when the event was triggered in vehicle. */ uint64 time_ms = 1; /* * This field is deprecated, use signals instead */ repeated Signal signal = 2 [ deprecated = true ]; repeated Signal signals = 3; repeated ExtraDimension extra_dimensions = 4; } message Signal { /* * The Fully Qualified Name of the signal is the path to the signal plus the signal's name. * For example, Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringState * The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). */ string name = 1; /* * The FWE reported signal value can be one of the following data types. */ oneof SignalValue { double double_value = 2; bool boolean_value = 3; sint32 int8_value = 4; uint32 uint8_value = 5; sint32 int16_value = 6; uint32 uint16_value = 7; sint32 int32_value = 8; uint32 uint32_value = 9; sint64 int64_value = 10; uint64 uint64_value = 11; float float_value = 12; /* * An UTF-8 encoded or 7-bit ASCII string */ string string_value = 13; } } message ExtraDimension { /* * The Fully Qualified Name of the attribute is the path to the attribute plus the attribute's name. * For example, Vehicle.Model.Color * The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). */ string name = 1; oneof ExtraDimensionValue { /* * An UTF-8 encoded or 7-bit ASCII string */ string string_value = 2; } } ``` Where: + `time_ms`: The absolute timestamp (in milliseconds since the Unix Epoch) of when the event was triggered in the vehicle. The Edge Agent software uses on the vehicle's clock for this timestamp. + `signal`: An array of `Signal`s that contain the signal information: `name` (string) and `signalValue` which supports the following data types - `double`, `bool`, `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float`, `string`. + `extra_dimensions`: An array of `ExtraDimensions` that contain vehicle attribute information: `name` (string) and `extraDimensionValue` which currently only supports the `string` data type.