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. # Collect AWS IoT FleetWise data with campaigns **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). A campaign is an orchestration of data collection rules. Campaigns give the Edge Agent for AWS IoT FleetWise software instructions on how to select, collect, and transfer data to the cloud. You create campaigns in the cloud. After you or your team has approved a campaign, AWS IoT FleetWise sets the campaign as ready to deploy, and it will be deployed on the next vehicle check-in. You can choose to deploy a campaign to a vehicle or a fleet of vehicles. The Edge Agent software doesn't start collecting data until a running campaign is deployed to the vehicle. **Important** Campaigns won't work until you have the following. The Edge Agent software is running in your vehicle. For more information about how to develop, install, and work with the Edge Agent software, do the following. Open the [AWS IoT FleetWise console](https://console.aws.amazon.com/iotfleetwise). On the service home page, in the **Get started with AWS IoT FleetWise** section, choose **Explore Edge Agent**. You've set up AWS IoT Core to provision your vehicle. For more information, see [Provision AWS IoT FleetWise vehicles](provision-vehicles.md). **Note** You can also [Monitor the last known state of your vehicles](last-known-state.md) (not fleets) in near real time using state templates that allow you to stream telemetry data with either an "On Change" or "Periodic" update strategy. The capability also provides "On Demand" features to activate or deactivate previously deployed templates or request the current vehicle state one-time (fetch). Access to last known state is currently gated. For more information, see [AWS Region and feature availability in AWS IoT FleetWise](fleetwise-regions.md). Each campaign contains the following information. `signalCatalogArn` The Amazon Resource Name (ARN) of the signal catalog associated with the campaign. (Optional) `tags` Tags are metadata that can be used to manage the campaign. You can assign the same tag to resources from different services to indicate that the resources are related. `TargetArn` The ARN of a vehicle or fleet to which the campaign is deployed. `name` A unique name that helps identify the campaign. `collectionScheme` The data collection schemes give Edge Agent software instructions on what data to collect or when to collect it. AWS IoT FleetWise currently supports the condition-based collection scheme and the time-based collection scheme. + `conditionBasedCollectionScheme` – the condition-based collection scheme uses a logical expression to recognize what data to collect. The Edge Agent software collects data when the condition is met. + `expression` – the logical expression used to recognize what data to collect. For example, if the `$variable.`myVehicle.InVehicleTemperature` > 50.0` expression is specified, the Edge Agent software collects temperature values that are greater than 50.0. For instructions on how to write expressions, see [Logical expressions for AWS IoT FleetWise campaigns](logical-expression.md). + (Optional) `conditionLanguageVersion` – the version of the conditional expression language. + (Optional) `minimumTriggerIntervalMs` – the minimum duration of time between two data collection events, in milliseconds. If a signal changes often, you might collect data at a slower rate. + (Optional) `triggerMode` – can be one of the following values: + `RISING_EDGE` – the Edge Agent software collects data only when the condition is met for the first time. For example, `$variable.`myVehicle.AirBagDeployed` == true`. + `ALWAYS` – Edge Agent software collects data whenever the condition is met. + `timeBasedCollectionScheme` – when you define a time-based collection scheme, specify a time period in milliseconds. The Edge Agent software uses the time period to decide how often to collect data. For example, if the time period is 120,000 milliseconds, the Edge Agent software collects data once every two minutes. + `periodMs` – the time period (in milliseconds) to decide how often to collect data. (Optional) `compression` To save wireless bandwidth and reduce network traffic, you can specify [SNAPPY](https://opensource.google/projects/snappy) to compress data in vehicles. By default (`OFF`), the Edge Agent software doesn't compress data. `dataDestinationConfigs` Choose the single destination where the campaign will transfer vehicle data. You can send the data to an [MQTT topic](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html), or store it in Amazon S3 or Amazon Timestream. MQTT (Message Queuing Telemetry Transport) is a lightweight and widely adopted messaging protocol. You can publish data to an MQTT topic to stand up your own event-driven architectures using AWS IoT rules. AWS IoT support for MQTT is based on the [ MQTT v3.1.1 specification](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and the [MQTT v5.0 specification](http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), with some differences. For more information, see [MQTT differences](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html#mqtt-differences.html). S3 can be a cost-effective data storage mechanism that offers durable data management capabilities and downstream data services. You can use S3 for data related to driving behaviors or analyzing long-term maintenance. Timestream is a data persistence mechanism that can help you identify trends and patterns in near real time. You can use Timestream for time-series data, such as to analyze historical trends in vehicle speed or braking. Amazon Timestream is not available in the Asia Pacific (Mumbai) Region. (Optional) `dataExtraDimensions` You can add one or more attributes to provide additional information for a signal. (Optional) `dataPartitions` Create a data partition to temporarily store signal data on a vehicle. You configure when and how to forward the data to the cloud. + Specify how AWS IoT FleetWise stores the data on a vehicle or fleet by defining the maximum storage size, minimum time to live, and storage location. + The campaign `spoolingMode` must be `TO_DISK`. + Uploading configurations include defining the version of the condition language and the logical expression. (Optional) `description` Add a description to help identify the campaign's purpose. (Optional) `diagnosticsMode` When the diagnostics mode is configured to `SEND_ACTIVE_DTCS`, the campaign sends stored, standard diagnostic trouble codes (DTCs) that help identify what is wrong with your vehicle. For example, P0097 indicates the engine control module (ECM) has determined that the intake air temperature sensor 2 (IAT2) input is lower than the normal sensor range. By default (`OFF`), the Edge Agent software doesn't send diagnostic codes. (Optional) `expiryTime` Define the expiration date for your campaign. When the campaign expires, the Edge Agent software stops collecting data as specified in this campaign. If multiple campaigns are deployed to the vehicle, the Edge Agent software uses other campaigns to collect data. Default value: `253402243200` (December 31, 9999, 00:00:00 UTC) (Optional) `postTriggerCollectionDuration` You can define a post-trigger collection duration, so that the Edge Agent software continues collecting data for a specified period after a scheme is invoked. For example, if a condition-based collection scheme with the following expression is invoked: `$variable.`myVehicle.Engine.RPM` > 7000.0`, the Edge Agent software continues to collect revolutions per minute (RPM) values for the engine. Even if the RPM only goes higher than 7000 once, it might indicate that there's a mechanical issue. In this case, you might want the Edge Agent software to continue collecting data to help monitor the condition. Default value: `0` (Optional) `priority` Specify an integer to indicate the priority level of the campaign. Campaigns with a smaller number are higher priorities. If you deploy multiple campaigns to a vehicle, the campaigns that are higher priorities are initiated first. Default value: `0` (Optional) `signalsToCollect` A list of signals from which data is collected when the data collection scheme is invoked. + `name` – the name of the signal from which data is collected when the data collection scheme is invoked. + `dataPartitionId` – the ID of the data partition to use in the signal. The ID must match one of the IDs provided in `dataPartitions`. If you upload a signal as a condition in your data partition, then those same signals must be included in `signalsToCollect`. + (Optional) `maxSampleCount` – the maximum number of data samples that the Edge Agent software collects and transfers to the cloud when the data collection scheme is invoked. + (Optional) `minimumSamplingIntervalMs` – the minimum duration of time between two data sample collection events, in milliseconds. If a signal changes often, you can use this parameter to collect data at a slower rate. Valid range: 0‐4294967295 (Optional) `spoolingMode` If `spoolingMode` is configured to `TO_DISK`, the Edge Agent software temporarily stores data locally when a vehicle isn't connected to the cloud. After the connection is reestablished, the data stored locally is automatically transferred to the cloud. Default value: `OFF` (Optional) `startTime` An approved campaign is activated at the start time. Default value: `0` The status of a campaign can be one of the following values. + `CREATING` – AWS IoT FleetWise is processing your request to create the campaign. + `WAITING_FOR_APPROVAL` – After a campaign is created, it enters the `WAITING_FOR_APPROVAL` state. To approve the campaign, use the `UpdateCampaign` API operation. After the campaign is approved, AWS IoT FleetWise automatically deploys the campaign to the target vehicle or fleet. For more information, see [Update an AWS IoT FleetWise campaign](update-campaign-cli.md). + `RUNNING ` – The campaign is active. + `SUSPENDED` – The campaign is suspended. To resume the campaign, use the `UpdateCampaign` API operation. AWS IoT FleetWise provides the following API operations that you can use to create and manage campaigns. + [CreateCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateCampaign.html) – Creates a new campaign. + [UpdateCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_UpdateCampaign.html) – Updates an existing campaign. After a campaign is created, you must use this API operation to approve the campaign. + [DeleteCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_DeleteCampaign.html) – Deletes an existing campaign. + [ListCampaigns](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_ListCampaigns.html) – Retrieves a paginated list of summaries for all campaigns. + [GetCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_GetCampaign.html) – Retrieves information about a campaign. **Topics** + [Create an AWS IoT FleetWise campaign](create-campaign.md) + [Update an AWS IoT FleetWise campaign](update-campaign-cli.md) + [Delete an AWS IoT FleetWise campaign](delete-campaign.md) + [Get AWS IoT FleetWise campaign information](get-campaign-information-cli.md) + [Store and forward campaign data](store-and-forward.md) + [Collect diagnostic trouble code data using AWS IoT FleetWise](diagnostic-trouble-codes.md) + [Visualize AWS IoT FleetWise vehicle data](process-visualize-data.md) # Create an AWS IoT FleetWise campaign **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 use the AWS IoT FleetWise console or API to create campaigns to collect vehicle data. **Important** For your campaign to work, you must have the following: The Edge Agent software is running in your vehicle. For more information about how to develop, install, and work with the Edge Agent software, do the following: Open the [AWS IoT FleetWise console](https://console.aws.amazon.com/iotfleetwise). On the service home page, in the **Get started with AWS IoT FleetWise** section, choose **Explore Edge Agent**. You've set up AWS IoT Core to provision your vehicle. For more information, see [Provision AWS IoT FleetWise vehicles](provision-vehicles.md). **Topics** + [Create a campaign (console)](#create-campaign-console) + [Create a campaign (AWS CLI)](#create-campaign-cli) + [Logical expressions for AWS IoT FleetWise campaigns](logical-expression.md) ## Create a campaign (console) Use the AWS IoT FleetWise console to create a campaign to select, collect, and transfer vehicle data to the cloud. **To create a campaign** 1. Open the [AWS IoT FleetWise console](https://console.aws.amazon.com/iotfleetwise). 1. On the navigation pane, choose **Campaigns**. 1. On the **Campaigns** page, choose **Create campaign**, and then complete the steps in the following topics. **Topics** + [Step 1: Configure campaign](#configure-campaign-console) + [Step 2: Specify storage and upload conditions](#specify-storage-upload-conditions) + [Step 3: Configure data destination](#configure-data-collection-scheme-console) + [Step 4: Add vehicles](#add-attributes-console) + [Step 5: Review and create](#review-and-create-campaign-console) + [Step 6: Deploy a campaign](#update-campaign-console) **Important** You must have a signal catalog and a vehicle before you create a campaign. For more information, see [Manage AWS IoT FleetWise signal catalogs](signal-catalogs.md) and [Manage AWS IoT FleetWise vehicles](vehicles.md). After a campaign is created, you must approve the campaign. For more information, see [Update an AWS IoT FleetWise campaign](update-campaign-cli.md). ### Step 1: Configure campaign In **General information**, do the following: 1. Enter a name for the campaign. 1. (Optional) Enter a description. Configure the campaign's data collection scheme. A data collection scheme gives the Edge Agent software instructions on what data to collect or when to collect it. In the AWS IoT FleetWise console, you can configure a data collection scheme in the following ways: + Manually define the data collection scheme. + Upload a file to automatically define the data collection scheme. In **Configuration option**, choose one of the following: + To manually specify the type of data collection scheme and define options to customize the scheme, choose **Define data collection scheme**. #### Manually define the data collection scheme Manually specify the type of data collection scheme and define options to customize the scheme. 1. In the **Data collection scheme details** section, choose the type of data collection scheme you want this campaign to use. To use a logical expression to recognize what vehicle data to collect, choose **Condition-based**. To use a specific time period to decide how often to collect vehicle data, choose **Time-based**. 1. Define the duration of time the campaign collects data. **Note** By default, an approved campaign is activated immediately and doesn't have a set end time. To avoid extra charges, you must specify a time range. 1. If you specified a condition-based data collection scheme, you must define a logical expression to recognize what data to collect. AWS IoT FleetWise uses a logical expression to recognize what data to collect for a condition-based scheme. The expression must specify a signal's fully qualified name as a variable, a comparison operator, and a comparison value. For example, if you specify the `$variable.`myVehicle.InVehicleTemperature` > 50.0` expression, AWS IoT FleetWise collects temperature values that are greater than 50.0. For instructions about how to write expressions, see [Logical expressions for AWS IoT FleetWise campaigns](logical-expression.md). Enter the logical expression used to recognize what data to collect. 1. (Optional) Specify the language version of the conditional expression. The default value is 1. 1. (Optional) Specify the minimum trigger interval, which is the smallest duration of time between two data collection events. For example, if a signal changes often, you might want to collect data at a slower rate. 1. Specify the **Trigger mode** condition for the Edge Agent software to collect data. By default, the Edge Agent for AWS IoT FleetWise software **Always** collects data whenever the condition is met. Or, it can collect data only when the condition is met for the first time, **On first trigger**. 1. If you specified a time-based data collection scheme, you must specify a time **Period**, in milliseconds, from 10,000 ‐ 60,000 milliseconds. The Edge Agent software uses the time period to decide how often to collect data. 1. (Optional) Edit the scheme’s **Advanced scheme options**. 1. To save wireless bandwidth and reduce network traffic by compressing data, choose **Snappy**. 1. (Optional) To define how long, in milliseconds, to continue collecting data after a data collection event, you can specify the **Post trigger collection duration**. 1. (Optional) To indicate the priority level of the campaign, specify the campaign **Priority**. Campaigns with a smaller number for priority are deployed first and are considered to have a higher priority. 1. The Edge Agent software can temporarily store data locally when a vehicle isn't connected to the cloud. After the connection is reestablished, the data stored locally is automatically transferred to the cloud. Specify if you want the Edge Agent to **Store data locally** during a lost connection. 1. (Optional) To provide additional information for a signal, add up to five attributes as **Extra data dimensions**. #### Import a file to define the data collection scheme Upload a .json file with details about the data collection scheme. 1. To import information about the data collection scheme, choose **Choose files**. For more information about the required file format, see the [CreateCampaign](https://docs.aws.amazon.com//iot-fleetwise/latest/APIReference/API_CreateCampaign.html#API_CreateCampaign) API documentation. **Note** AWS IoT FleetWise currently supports the .json file format extension. 1. AWS IoT FleetWise automatically defines the data collection scheme based on the information in your file. Review the options that AWS IoT FleetWise selected for you. You can update the options, if needed. ### Step 2: Specify storage and upload conditions To choose if the Edge Agent software will temporarily store data locally when a vehicle isn't connected to the cloud, specify the spooling mode. + In **Data spooling mode**, choose one of the following: + **Not stored** – The Edge Agent software collects but doesn't temporarily store data locally when a vehicle is offline. The Edge Agent software transfers data to the cloud when the vehicle reconnects. + **Stored to disk** – The Edge Agent software collects and temporarily stores data locally when a vehicle is offline. Collected data is temporarily stored at a location defined by the Edge Agent config file “persistency” section. The Edge Agent transfers data to the cloud when the vehicle reconnects. + **Stored to disk with partitions** – The vehicle always temporarily stores data on the Edge in your specified data partition. You can choose when you want to forward your stored data to the cloud. 1. (Optional) Enter a partition ID to designate a particular set of data. 1. Enter a folder name as the location where data will be stored. The absolute path of the storage location is `{persistency_path} / {vehicle_name} / {campaign_name} / {storage_location}`. 1. Enter the maximum storage size of the data stored in the partition. Newer data overwrites older data when the partition reaches the maximum size. 1. Enter the minimum amount of time that data in this partition will be kept on the disk. 1. (Optional) Enter upload conditions for the partition. #### Specify signals You can specify the signals to collect data from during the campaign. **To specify the signals to collect data from** 1. Select the **Signal name**. 1. (Optional) For **Max sample count**, enter the maximum number of data samples that the Edge Agent software collects and transfers to the cloud during the campaign. 1. (Optional) For **Min sampling interval**, enter the minimum duration of time between two data sample collection events, in milliseconds. If a signal changes often, you can use this parameter to collect data at a slower rate. 1. To add another signal, choose **Add more signals**. You can add up to 999 signals. 1. Choose **Next**. ### Step 3: Configure data destination **Note** If the campaign contains vision system data signals, you can only store the vehicle data in Amazon S3. You can't store it in Timestream or send it to an MQTT topic. Vision system data is in preview release and is subject to change. Amazon Timestream is not available in the Asia Pacific (Mumbai) Region. Choose the destination where you want to send or store data collected by the campaign. You can send vehicle data to an MQTT topic, or store it in Amazon S3 or Amazon Timestream. In **Destination settings**, do the following: + Choose Amazon S3, Amazon Timestream, or MQTT topic from the dropdown list. #### Amazon S3 **Important** You can only transfer data to S3 if AWS IoT FleetWise has permissions to write into the S3 bucket. For more information about granting access, see [Controlling access with AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html). To store vehicle data in an S3 bucket, choose **Amazon S3**. S3 is an object storage service that stores data as objects within buckets. For more information, see [ Creating, configuring, and working with Amazon S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html) in the *Amazon Simple Storage Service User Guide*. S3 optimizes the cost of data storage and provides additional mechanisms to use vehicle data, such as data lakes, centralized data storage, data processing pipelines, and analytics. You can use S3 to store data for batch processing and analysis. For example, you can create reports of hard-braking events for your machine learning (ML) model. Incoming vehicle data is buffered for 10 minutes before delivery. In **S3 destination settings**, do the following: 1. For **S3 bucket**, choose a bucket that AWS IoT FleetWise has permissions to. 1. (Optional) Enter a custom prefix that you can use to organize data stored in the S3 bucket. 1. Choose the output format, which is the format files that are saved as in the S3 bucket. 1. Choose if you want to compress data stored in the S3 bucket as a .gzip file. We recommend compressing data because it minimizes storage costs. 1. The options you select in **S3 destination settings** change the **Example S3 object URI**. This is an example of what files are saved as in S3. #### Amazon Timestream **Important** You can only transfer data to a table if AWS IoT FleetWise has permissions to write data into Timestream. For more information about granting access, see [Controlling access with AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html). Amazon Timestream is not available in the Asia Pacific (Mumbai) Region. To store vehicle data in a Timestream table, choose **Amazon Timestream**. You can use Timestream to query vehicle data so that you can identify trends and patterns. For example, you can use Timestream to create an alarm for vehicle fuel level. Incoming vehicle data is transferred to Timestream in near real time. For more information, see [ What is Amazon Timestream?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html) in the *Amazon Timestream Developer Guide*. In **Timestream table settings**, do the following: 1. For **Timestream database name**, choose the name of your Timestream database from the dropdown list. 1. For **Timestream table name**, choose the name of your Timestream table from the dropdown list. In **Service access for Timestream**, do the following: + Choose an IAM role from the dropdown list. #### MQTT topic **Important** You can only route data to an MQTT topic if AWS IoT FleetWise has permissions to AWS IoT topics. For more information about granting access, see [Controlling access with AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html). To send vehicle data to an MQTT topic, choose **MQTT topic**. Vehicle data sent by MQTT messaging is delivered in near real-time and allows you to use rules to take action, or route data to other destinations. For more information about using MQTT, see [Device communication protocols](https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html) and [Rules for AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) in the *AWS IoT Core Developer Guide*. 1. Under **MQTT topic**, enter the **Topic name**. 1. Under **Service access for MQTT topic**, choose whether you want to let AWS IoT FleetWise **Create and use a new service role** for you. If you want to **Use an existing service role**, select the role in the dropdown list under **Select role**. + Choose **Next**. ### Step 4: Add vehicles To choose which vehicles to deploy your campaign to, select them in the vehicles list. Filter vehicles by searching for the attributes and their values that you added when creating the vehicles, or by vehicle name. In **Filter vehicles**, do the following: 1. In the search box, find the attribute or vehicle name and choose it from the list. **Note** Each attribute can be used only once. 1. Enter the value of the attribute or the vehicle name that you want to deploy the campaign to. For example, if the fully qualified name of the attribute is `fuelType`, enter `gasoline` as its value. 1. To search for another vehicle attribute, repeat the preceding steps. You can search for up to five vehicle attributes and an unlimited number of vehicle names. 1. Vehicles that match your search are listed under **Vehicle name**. Choose the vehicles that you want the campaign to deploy to. **Note** Up to 100 vehicles are displayed in search results. Choose **Select all** to add all vehicles to the campaign. 1. Choose **Next**. ### Step 5: Review and create Verify the configurations for the campaign, and then choose **Create campaign**. **Note** After a campaign is created, you or your team must deploy the campaign to vehicles. ### Step 6: Deploy a campaign After you create a campaign, you or your team must deploy the campaign to vehicles. **To deploy a campaign** 1. On the **Campaign summary** page, choose **Deploy**. 1. Review and confirm that you want to start the deployment and begin collecting data from vehicles connected to the campaign. 1. Choose **Deploy**. If you want to pause collecting data from vehicles connected to the campaign, on the **Campaign summary** page, choose **Suspend**. To resume collecting data from vehicles connected to the campaign, choose **Resume**. ## Create a campaign (AWS CLI) You can use the [CreateCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_CreateCampaign.html) API operation to create a campaign. The following example uses the AWS CLI. When you create a campaign, data collected from vehicles can be sent to an MQTT topic or stored in either Amazon S3 (S3) or Amazon Timestream. Choose Timestream for a fast, scalable, and server-less time series database, such as to store data that requires near real time processing. Choose S3 for object storage with industry-leading scalability, data availability, security, and performance. Choose MQTT to deliver data in near real-time and to use [Rules for AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) to perform actions you define or route the data to other destinations. **Important** You can only transfer vehicle data to an MQTT topic, Amazon S3, or Amazon Timestream if AWS IoT FleetWise has permissions to send MQTT messages on your behalf, or to write data into S3 or Timestream. For more information about granting access, see [ Controlling access with AWS IoT FleetWise](https://docs.aws.amazon.com/iot-fleetwise/latest/developerguide/controlling-access.html). Amazon Timestream is not available in the Asia Pacific (Mumbai) Region. ### Create campaign **Important** You must have a signal catalog and a vehicle or fleet before you create a campaign. For more information, see [Manage AWS IoT FleetWise signal catalogs](signal-catalogs.md), [Manage AWS IoT FleetWise vehicles](vehicles.md), and [Manage fleets in AWS IoT FleetWise](fleets.md). After a campaign is created, you must use the `UpdateCampaign` API operation to approve the campaign. For more information, see [Update an AWS IoT FleetWise campaign](update-campaign-cli.md) To create a campaign, run the following command. Replace *file-name* with the name of the .json file that contains the campaign configuration. ``` aws iotfleetwise create-campaign --cli-input-json file://file-name.json ``` #### Example configuration file for S3 + Replace *campaign-name* with the name of the campaign that you're creating. + Replace *signal-catalog-arn* with the Amazon Resource Name (ARN) of the signal catalog. + Replace *target-arn* with the ARN of a fleet or vehicle that you created. + Replace *bucket-arn* with the ARN of the S3 bucket. ``` { "name": "campaign-name", "targetArn": "target-arn", "signalCatalogArn": "signal-catalog-arn", "collectionScheme": { "conditionBasedCollectionScheme": { "conditionLanguageVersion": 1, "expression": "$variable.`Vehicle.DemoBrakePedalPressure` > 7000", "minimumTriggerIntervalMs": 1000, "triggerMode": "ALWAYS" } }, "compression": "SNAPPY", "diagnosticsMode": "OFF", "postTriggerCollectionDuration": 1000, "priority": 0, "signalsToCollect": [ { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "name": "Vehicle.DemoEngineTorque" }, { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "name": "Vehicle.DemoBrakePedalPressure" } ], "spoolingMode": "TO_DISK", "dataDestinationConfigs": [ { "s3Config": { "bucketArn": "bucket-arn", "dataFormat": "PARQUET", "prefix": "campaign-name", "storageCompressionFormat": "GZIP" } } ], "dataPartitions": [ { ... } ] } ``` #### Example configuration file for Timestream **Note** Amazon Timestream is not available in the Asia Pacific (Mumbai) Region. + Replace *campaign-name* with the name of the campaign that you're creating. + Replace *signal-catalog-arn* with the ARN of the signal catalog. + Replace *target-arn* with the ARN of a fleet or vehicle that you created. + Replace *role-arn* with the ARN of the task execution role that grants AWS IoT FleetWise permission to deliver data to the Timestream table. + Replace *table-arn* with the ARN of the Timestream table. ``` { "name": "campaign-name", "targetArn": "target-arn", "signalCatalogArn": "signal-catalog-arn", "collectionScheme": { "conditionBasedCollectionScheme": { "conditionLanguageVersion": 1, "expression": "$variable.`Vehicle.DemoBrakePedalPressure` > 7000", "minimumTriggerIntervalMs": 1000, "triggerMode": "ALWAYS" } }, "compression": "SNAPPY", "diagnosticsMode": "OFF", "postTriggerCollectionDuration": 1000, "priority": 0, "signalsToCollect": [ { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "name": "Vehicle.DemoEngineTorque" }, { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "name": "Vehicle.DemoBrakePedalPressure" } ], "spoolingMode": "TO_DISK", "dataDestinationConfigs": [ { "timestreamConfig": { "executionRoleArn": "role-arn", "timestreamTableArn": "table-arn" } } ], "dataPartitions": [ { ... } ] } ``` #### Example configuration file for an MQTT topic + Replace *campaign-name* with the name of the campaign that you're creating. + Replace *signal-catalog-arn* with the Amazon Resource Name (ARN) of the signal catalog. + Replace *target-arn* with the ARN of a fleet or vehicle that you created. + Replace *topic-arn* with the ARN of the [MQTT topic](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) that you specified as the destination for messages containing vehicle data. + Replace *role-arn* with the ARN of the task execution role that grants AWS IoT FleetWise permission to send, receive, and take action on messages for the MQTT topic you specified. ``` { "name": "campaign-name", "targetArn": "target-arn", "signalCatalogArn": "signal-catalog-arn", "collectionScheme": { "conditionBasedCollectionScheme": { "conditionLanguageVersion": 1, "expression": "$variable.`Vehicle.DemoBrakePedalPressure` > 7000", "minimumTriggerIntervalMs": 1000, "triggerMode": "ALWAYS" } }, "compression": "SNAPPY", "diagnosticsMode": "OFF", "postTriggerCollectionDuration": 1000, "priority": 0, "signalsToCollect": [ { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "name": "Vehicle.DemoEngineTorque" }, { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "name": "Vehicle.DemoBrakePedalPressure" } ], "spoolingMode": "TO_DISK", "dataDestinationConfigs": [ { "mqttTopicConfig": { "mqttTopicArn": "topic-arn", "executionRoleArn": "role-arn" } } ] } ``` If you [enabled encryption](key-management.md) using a customer managed AWS KMS key, include the following policy statement so that your role can invoke the `CreateCampaign` API operation. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:GenerateDataKey*", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/KMS_KEY_ID" ] } ] } ``` ------ # Logical expressions for AWS IoT FleetWise campaigns AWS IoT FleetWise uses a logical expression to recognize what data to collect as part of a campaign. For more information about expressions, see [Expressions](https://docs.aws.amazon.com/iotevents/latest/developerguide/iotevents-expressions.html) in the *AWS IoT Events Developer Guide*. The expression variable should be constructed to comply with the rules for the type of data being collected. For telemetry system data, the expression variable should be the signal's fully qualified name. For vision system data, the expression combines the signal's fully qualified name with the path leading from the signal's data type to one of its properties. For example, if the signal catalog contains the following nodes: ``` { myVehicle.ADAS.Camera: type: sensor datatype: Vehicle.ADAS.CameraStruct description: "A camera sensor" myVehicle.ADAS.CameraStruct: type: struct description: "An obstacle detection camera output struct" } ``` If the nodes follow the ROS 2 definition: ``` { Vehicle.ADAS.CameraStruct.msg: boolean obstaclesExists uint8[] image Obstacle[30] obstacles } { Vehicle.ADAS.Obstacle.msg: float32: probability uint8 o_type float32: distance } ``` The following are all possible event expression variables: ``` { ... $variable.`myVehicle.ADAS.Camera.obstaclesExists` $variable.`myVehicle.ADAS.Camera.Obstacle[0].probability` $variable.`myVehicle.ADAS.Camera.Obstacle[1].probability` ... $variable.`myVehicle.ADAS.Camera.Obstacle[29].probability` $variable.`myVehicle.ADAS.Camera.Obstacle[0].o_type` $variable.`myVehicle.ADAS.Camera.Obstacle[1].o_type` ... $variable.`myVehicle.ADAS.Camera.Obstacle[29].o_type` $variable.`myVehicle.ADAS.Camera.Obstacle[0].distance` $variable.`myVehicle.ADAS.Camera.Obstacle[1].distance` ... $variable.`myVehicle.ADAS.Camera.Obstacle[29].distance` } ``` # Update an AWS IoT FleetWise campaign You can use the [UpdateCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_UpdateCampaign.html) API operation to update an existing campaign. The following command uses AWS CLI. + Replace *campaign-name* with the name of the campaign that you're updating. + Replace *action* with one of the following: + `APPROVE` – Approves the campaign to allow AWS IoT FleetWise to deploy it to a vehicle or fleet. + `SUSPEND` – Suspends the campaign. The campaign is deleted from vehicles and all vehicles in the suspended campaign will stop sending data. + `RESUME` – Reactivates the `SUSPEND` campaign. The campaign is set to be redeployed to all vehicles on next check-in and the vehicles will resume sending data. + `UPDATE` – Updates the campaign by defining attributes and associating them with the campaign. + Replace *description* with a new description. The description can have up to 2,048 characters. + Replace *data-extra-dimensions* with specified vehicle attributes to enrich data collected during the campaign. For example, you can add vehicle make and model to the campaign, and AWS IoT FleetWise will associate the data with those attributes as dimensions in Amazon Timestream. You can then query the data against vehicle make and model. ``` aws iotfleetwise update-campaign \ --name campaign-name \ --action action \ --description description \ --data-extra-dimensions data-extra-dimensions ``` If you [enabled encryption](key-management.md) using a customer managed AWS KMS key, include the following policy statement so that your role can invoke the `UpdateCampaign` API operation. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:GenerateDataKey*", "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/KMS_KEY_ID" ] } ] } ``` ------ # Delete an AWS IoT FleetWise campaign You can use the AWS IoT FleetWise console or API to delete campaigns. ## Delete a campaign (console) To delete a campaign, use the AWS IoT FleetWise console. **To delete a campaign** 1. Open the [AWS IoT FleetWise console](https://console.aws.amazon.com/iotfleetwise). 1. On the navigation pane, choose **Campaigns**. 1. On the **Campaigns** page, choose the target campaign. 1. Choose **Delete**. 1. In **Delete **campaign-name**?**, enter the name of the campaign to delete, and then choose **Confirm**. ## Delete a campaign (AWS CLI) You can use the [DeleteCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_DeleteCampaign.html) API operation to delete a campaign. The following example uses AWS CLI. To delete a campaign, run the following command. Replace *campaign-name* with the name of the vehicle that you're deleting. ``` aws iotfleetwise delete-campaign --name campaign-name ``` **Deleted data partitions are not recoverable** Deleting a campaign removes all data from devices and the data in a partition won't upload to the cloud. ## Verify campaign deletion You can use the [ListCampaigns](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_ListCampaigns.html) API operation to verify if a campaign has been deleted. The following example uses the AWS CLI. To retrieve a paginated list of summaries for all campaigns, run the following command. ``` aws iotfleetwise list-campaigns ``` # Get AWS IoT FleetWise campaign information You can use the [GetCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_GetCampaign.html) API operation to retrieve vehicle information. The following example uses the AWS CLI. To retrieve the metadata of a campaign, run the following command. Replace *campaign-name* with the name of the campaign to you want to retrieve. ``` aws iotfleetwise get-campaign --name campaign-name ``` **Note** This operation is [eventually consistent](https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf). In other words, changes to the campaign might not be reflected immediately. If you [enabled encryption](key-management.md) using a customer managed AWS KMS key, include the following policy statement so that your role can invoke the `GetCampaign` API operation. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": [ "arn:aws:kms:us-east-1:111122223333:key/KMS_KEY_ID" ] } ] } ``` ------ # Store and forward campaign data **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). Use data partitions within campaigns to temporarily store signal data on the Edge for vehicles and fleets. By configuring upload and storage options for data partitions, you can optimize your ideal conditions for data forwarding to your designated data destinations (like an Amazon S3 bucket). For example, you can configure the data partition to store data on a vehicle until it connects to Wi-Fi. Then, once the vehicle connects, the campaign triggers the data in that particular partition to be sent to the cloud. Alternatively, you can collect data using AWS IoT Jobs. **Topics** + [Create data partitions](create-campaign-data-partitions.md) + [Upload campaign data](update-campaign-cli-data-partitions.md) + [Upload data using AWS IoT Jobs](update-campaign-cli-data-partitions-jobs.md) # Create data partitions **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). A data partition in a campaign temporarily stores signal data. You configure when and how to forward the data to the cloud. A data partition works by first designating a particular set of data using the `dataPartitionId` for a campaign. Then, you can further define partition storage options such as maximum size, minimum time to keep the data partition live (on disk), and where to store the data on the Edge. You can determine the storage location on the vehicle using `storageLocation`. The storage location determines the folder name for the data partition under the campaign storage folder. The campaign storage folder is under a folder named after the vehicle name under a persistency path defined in the Edge config file. This is the absolute path of the storage location: `{persistency_path} / {vehicle_name} / {campaign_name} / {storage_location}`. The spooling mode set to `TO_DISK` specifies that the partitioned data should be saved to a disk on the vehicle. Data storage for data partitions operates on a FIFO (first in, first out) basis. If you delete a campaign, you also delete the data in the associated data partition. If you don't specify a data partition for connectivity on/off use cases, AWS IoT FleetWise still stores data in a ring buffer on the vehicle when there is no connectivity. When connectivity resumes, AWS IoT FleetWise uploads the data to the cloud. This behavior is configurable in the Edge Agent for AWS IoT FleetWise software. **Important** If your data partition exceeds your set maximum storage limit, newer data overwrites older data when the partition reaches the maximum size. Lost data on the Edge isn't recoverable. Storage size is determined by your Edge storage limit. When data is uploaded to the cloud, it can be removed after the minimum time to live passes. Set the minimum time to live appropriately to avoid unintended deletion. Upload options determine variable expressions and condition language. If upload options are specified, you must also specify storage options. You can also request that signals in data partitions are uploaded into the cloud. For more information, see [Upload campaign data](update-campaign-cli-data-partitions.md). After data partition conditions are defined, `signalsToCollect` helps specify which signals to account for in the data partition. You can either specify IDs for data partitions, or set the `dataPartitionId` to `default` to use an established default data partition. A signal without a specified `dataPartitionId` will be associated with the default `dataPartition`. **To create a data partition** Using the following example, create a campaign with a data partition storage condition. This example campaign is configured to store vehicle data in Amazon Timestream. 1. Replace *campaign-name* with the name of the campaign that you're creating. 1. (Optional) Provide a description. 1. Replace *role-arn* with the Amazon Resource Name (ARN) of the task execution role that grants AWS IoT FleetWise permission to deliver data to the Timestream table. 1. Replace *table-arn* with the ARN of the Timestream table. 1. Replace *signal-catalog-arn* with the ARN of the signal catalog. 1. Replace *data-partition-id* both for the `dataPartitions` ID and as the ID to associate with `signalsToCollect`. First, replace the ID of the data partition to use in the signal. For `signalsToCollect`, the ID must match one of the IDs provided in `dataPartitions`. **Note** Establish a default data partition for a campaign by using `default` as the ID. 1. Replace *target-arn* with the ARN of a fleet or vehicle that you created. ``` { "name": "campaign-name", "description": "Measurement of SOC, SOH, thermal, and power optimization for Fleet 2704", "targetArn": "target-arn", "collectionScheme": { "conditionBasedCollectionScheme": { "conditionLanguageVersion": 1, "expression": "$variable.`Vehicle.BMS` > 50", "minimumTriggerIntervalMs": 1000, "triggerMode": "ALWAYS" } }, "compression": "SNAPPY", "dataDestinationConfigs": [{ "timestreamConfig": { "executionRoleArn": "role-arn", "timestreamTableArn": "table-arn" } }], "dataPartitions": [{ "id": "data-partition-id", "storageOptions": { "maximumSize": { "unit": "GB", "value": 1024 }, "minimumTimeToLive": { "unit": "WEEKS", "value": 6 }, "storageLocation": "string" }, "uploadOptions": { "conditionLanguageVersion": 1, "expression": "$variable.`Vehicle.BMS.PowerOptimization` > 90" } }], "signalCatalogArn": "signal-catalog-arn", "signalsToCollect": [{ "dataPartitionId": "data-partition-id", "maxSampleCount": 50000, "minimumSamplingIntervalMs": 100, "name": "Below-90-percent" }], "spoolingMode": "TO_DISK", "tags": [{ "Key": "BMS", "Value": "Under-90" }] } ``` After meeting all specified conditions, the partitioned data forwards to the cloud, enabling the collection and storage of new partitioned signals. Next, you'll call the `UpdateCampaign` API to deploy it to the Edge Agent for AWS IoT FleetWise software. For more information, see [Upload campaign data](update-campaign-cli-data-partitions.md). # Upload campaign data **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). There are two ways to upload campaign data on the Edge: + Campaigns that meet your upload conditions will automatically upload data to the cloud after they are approved. To approve a campaign, use the `updateCampaign` API operation. + Through AWS IoT Jobs, you can force data to upload even when specified conditions are not met. For more information, see [Upload data using AWS IoT Jobs](update-campaign-cli-data-partitions-jobs.md). **To upload campaign data using the `UpdateCampaign` API operation** After you create the campaign, the campaign status displays as `WAITING_FOR_APPROVAL` until you change the `action` to `APPROVED`. + Use the following sample to update the campaign `action` by calling on the [UpdateCampaign](https://docs.aws.amazon.com/iot-fleetwise/latest/APIReference/API_UpdateCampaign.html) API operation. ``` { "action": "APPROVED", "dataExtraDimensions": [ "string" ], "description": "string", "name": "string" } ``` # Upload data using AWS IoT Jobs **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). With AWS IoT Jobs, you can configure campaigns to upload stored vehicle data to the cloud whenever you need it. **To create a job document for your campaign** + Use the following example to create a job document for the campaign. A job document is a .json file that contains information about vehicles or fleets required to perform a job. For more information on creating job document, see [Create and manage jobs by using the AWS CLI](https://docs.aws.amazon.com/iot/latest/developerguide/manage-job-cli.html) in the *AWS IoT Developer Guide*. To request that only one vehicle uploads data, set the job target to the AWS IoT thing that's associated with the vehicle. To request that multiple vehicles (in the same campaign) upload data, create a thing group of all things corresponding with the vehicles, and then set the job target to the thing group. ``` { "version": "1.0", "parameters": { "campaignArn": ${aws:iot:parameter:campaignArn}, "endTime": ${aws:iot:parameter:endTime} } } ``` 1. Replace `CampaignArn` with the Amazon Resource Name (ARN) of a campaign in the same Region and account. The campaign ARN is required. 1. (Optional) Replace `endTime` with the timestamp of data collected on the vehicle in ISO 8601 UTC format (without milliseconds). For example, `2024-03-05T23:00:00Z`. The timestamp is exclusive and determines the last datapoint to be uploaded. If you omit `endTime`, the Edge Agent software continues to upload until all of a campaign's stored data is uploaded. After all data is uploaded, it updates the [job execution status](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-lifecycle.html#iot-job-execution-states) to `SUCCEEDED`. The job's [state](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-lifecycle.html#iot-jobs-states) updates to `COMPLETED`. **To create a job using a managed job template** 1. Choose **IoT-IoTFleetWise-CollectCampaignData** from the list of managed templates. For more information, see [Create a job from AWS managed templates](https://docs.aws.amazon.com/iot/latest/developerguide/job-template-manage-console-create.html) in the *AWS IoT Developer Guide*. 1. The managed template has the `CampaignArn` and `endTime` parameters. 1. Replace `CampaignArn` with the Amazon Resource Name (ARN) of a campaign in the same Region and account. The campaign ARN is required. 1. (Optional) Replace `endTime` with the timestamp of data collected on the vehicle in ISO 8601 UTC format (without milliseconds). For example, `2024-03-05T23:00:00Z`. The timestamp is exclusive and determines the last datapoint to be uploaded. If you omit `endTime`, the Edge Agent software continues to upload until all of a campaign's stored data is uploaded. After all data is uploaded, it updates the [job execution status](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-lifecycle.html#iot-job-execution-states) to `SUCCEEDED`. The job's [state](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-lifecycle.html#iot-jobs-states) updates to `COMPLETED`. For related troubleshooting topics, see [Store and forward issues](troubleshooting-campaign.md). For more information on AWS IoT Jobs, see [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) in the *AWS IoT Developer Guide*. # Collect diagnostic trouble code data using AWS IoT FleetWise **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 a vehicle detects an error, it generates a diagnostic trouble code (DTC) and records a snapshot of the affected sensors or actuators. DTCs help you learn about errors in near real-time, understand what is causing them, and take corrective actions. AWS IoT FleetWise supports the collection of DTCs, including corresponding DTC snapshots and extended data through a data collection campaign. This topic introduces the concepts, workflows, and keywords that facilitate DTC data collection, illustrated with examples. The following shows key concepts for using DTC. **Custom defined functions** A custom defined function is the ability to invoke and execute your own functions predefined on the Edge Agent, extending the [custom decoding](network-agnostic-data-collection.md) concept. These functions are used in coordination with the AWS IoT FleetWise Agent. The Edge Agent for AWS IoT FleetWise software provides built-in functions for calculating signal statistics like minimum, maximum, and average values. A custom-defined function extends this capability by allowing you to create tailored logic for specific use cases. For diagnostic trouble code (DTC) data collection, developers can leverage custom functions to implement advanced data retrieval mechanisms, such as fetching DTC codes, snapshots, and extended data directly from the vehicle's Edge through Unified Diagnostic Services (UDS) or alternative diagnostic interfaces. For more information, see the [custom function guide](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/docs/dev-guide/custom-function-dev-guide.md) and the [DTC data collection reference implementation](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/docs/dev-guide/edge-agent-uds-dtc-dev-guide.md#dtc_query-function-implementation) in the *Edge Agent Developer Guide*. **Signal fetching** In data collection campaigns, signals are typically collected continuously from a device and buffered on the Edge Agent software. Signals are then uploaded or stored periodically in time-based campaigns or triggered by specific conditions in condition-based campaigns. However, due to concerns about device traffic congestion, DTC signals can't be collected from devices and buffered continuously. To address this, AWS IoT FleetWise provides signal fetching, which ensures that the target signal is fetched discontinuously from a device. Signal fetching supports both periodic and condition-driven actions. You can define the fetching driven method, conditions, and exact actions using custom defined functions for each signal that should not be collected from a device continuously. For signals managed by the signal fetching mechanism, the trigger type and conditions for local storage or cloud upload are still governed by the `CollectionScheme`, both `timeBasedCollectionScheme` and `conditionBasedCollectionScheme` are supported, which is the same as regular signals. The following topics show you how you can create and use DTCs. **Topics** + [Diagnostic trouble code keywords](dtc-keywords.md) + [Create a data collection campaign for diagnostic trouble codes](dtc-data-collection.md) + [Diagnostic trouble code use cases](dtc-use-cases.md) # Diagnostic trouble code keywords **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). **`signalsToFetch` parameter for create campaign** Use the signalsToFetch syntax to configure how the signal information can be fetched on the Edge. Standard signal fetching is controlled by modeling as rules explicitly defined in a decoder manifest or custom defined through Edge First Modeling. With signals to fetch, you can define when and how data is fetched during campaigns. Signals to fetch allows the collection of DTC information. For example, you can create a signal of string type named `DTC_Info` that can contain DTC information for every engine control unit (ECU). Or, you can filter for a specific ECU. + `SignalFetchInformation` structure and param definitions. ``` structure SignalFetchInformation { @required fullyQualifiedName: NodePath, @required signalFetchConfig: SignalFetchConfig, // Conditional language version for this config conditionLanguageVersion: languageVersion, @required actions: EventExpressionList, } ``` + `fullyQualifiedName`: the fully qualified name (FQDN) of the signal that you want to use custom fetch for. + `signalFetchConfig`: defines rules on how the above defined signals should be fetched. It supports time-based and condition-based fetch. + `conditionLanguageVersion`: the conditional language version used for parsing the expression in the config. + `actions`: a list of all action expressions evaluated on the Edge. The Edge will get the value of the defined signal. **Important** Actions can only use `custom_function`. ## Campaign expression keywords The following expression takes a signal's fully qualified name supported by the vehicle and returns true if the signal doesn't have any data in the signal buffers on the Edge. Otherside, it returns false. ``` isNull(signalFqdn:String): Boolean ``` **Example usage** ``` isNull($variable.`Vehicle.ECU1.DTC_INFO`) == false We want to make sure DTC_Info signal is being generated on edge. ``` This expression takes the following input: **functionName:String** The name of the custom function that is supported by the Edge **params: varargs*Expression*** Parameters for `functionName`. This can be any list of expressions. Parameters support literal type: String, Int , Boolean, or Double. ``` custom_function(functionName:String, params: varargsExpression): Void ``` **Example usage** ``` { "fullyQualifiedName":"Vehicle.ECU1.DTC_INFO", "signalFetchConfig":{ "timeBased":{ "executionFrequencyMs":2000 } }, "actions":"custom_function(“DTC_QUERY”, -1, 2, -1)" } ``` # Create a data collection campaign for diagnostic trouble codes **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 topic describes how to create a data collection campaign for diagnostic trouble codes (DTC). 1. Define a custom signal on the Edge. You need to define the decoding rules for the DTC signal on the Edge as a custom decoded signal. For more information, see [Tutorial: Configure network agnostic data collection using a custom decoding interface](network-agnostic-data-collection.md). 1. Define custom function on the Edge. You need to define a custom function for collecting DTC signals on the Edge at a compiled time. For more information, see the [custom function guide](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/docs/dev-guide/custom-function-dev-guide.md ) and the [DTC data collection reference implementation](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/docs/dev-guide/edge-agent-uds-dtc-dev-guide.md#dtc_query-function-implementation) in the *Edge Agent Developer Guide*. **Note** An example custom defined function is `DTC_QUERY` as shown in the [demo script](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/docs/dev-guide/edge-agent-uds-dtc-dev-guide.md). 1. Create a signal catalog that models a DTC signal as a string type. ``` [ { "branch": { "fullyQualifiedName": "Vehicle", "description": "Vehicle" } }, { "branch": { "fullyQualifiedName": "Vehicle.ECU1", "description": "Vehicle.ECU1" } }, { "sensor": { "fullyQualifiedName": "Vehicle.ECU1.DTC_INFO", "description": "Vehicle.ECU1.DTC_INFO", "dataType": "STRING" } } ] ``` 1. Create and activate a vehicle model with the DTC signal added. 1. Create and activate a decoder manifest with the DTC signal added. The DTC signal should be a `CUSTOM_DECODING_SIGNAL` signal decoder type with a `CUSTOM_DECODING_INTERFACE` network interface type. **Example signal decoder** ``` [ { "fullyQualifiedName": "Vehicle.ECU1.DTC_INFO", "interfaceId": "UDS_DTC", "type": "CUSTOM_DECODING_SIGNAL", "customDecodingSignal": { "id": "Vehicle.ECU1.DTC_INFO" } } ] ``` **Example network interface** ``` [ { "interfaceId": "UDS_DTC", "type": "CUSTOM_DECODING_INTERFACE", "customDecodingInterface": { "name": "NamedSignalInterface" } } ] ``` **Note** Controller Area Network (CAN) signals don't support the string data type. 1. Provision and create vehicles. The vehicles must utilize a vehicle model (model manifest) and decoder manifest that were activated in the previous steps. 1. Create and approve the campaign. You need to create a campaign by defining DTC signals (optionally with telemetry signals) and deploy it to vehicles. 1. Access the data in the defined destination. DTC data includes the `DTCCode`, `DTCSnapshot`, and `DTCExtendedDatastrings` as a raw string in the data destination defined in the campaign. # Diagnostic trouble code use cases **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 use cases assume the `DTC_QUERY` function was defined in the [demo script](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/docs/dev-guide/edge-agent-uds-dtc-dev-guide.md). ## Periodic fetch Fetch a DTC collection at configured intervals. The following example is a campaign with periodic signal fetching of `Vehicle.DTC_INFO` for all DTCs with a status mask for all ECUs. There is a condition for data collected for `Vehicle.DTC_INFO`. ``` { "compression": "SNAPPY", "spoolingMode": "TO_DISK", "signalsToFetch": [ { "fullyQualifiedName": "Vehicle.ECU1.DTC_INFO", "signalFetchConfig": { "timeBased": { // The FleetWise Edge Agent will query the UDS module for all DTCs every five seconds. "executionFrequencyMs": 5000 } }, "actions": [ // Every five seconds, this action is called and its output is stored in the // signal history buffer of Vehicle.DTC_INFO "custom_function(\"DTC_QUERY\", -1, 2, -1)" ] } ], "signalsToCollect": [ { "name": "Vehicle.ECU1.DTC_INFO" } ], "collectionScheme": { "conditionBasedCollectionScheme": { "conditionLanguageVersion": 1, // Whenever a new DTC is filled into the signal, the data is ingested. "expression": "!isNull($variable.`Vehicle.ECU1.DTC_INFO`)", "minimumTriggerIntervalMs": 1000, // Make sure that data is ingested only when there are new DTCs. "triggerMode": "RISING_EDGE" } }, "dataDestinationConfigs": [ { "s3Config": { "bucketArn": "bucket-arn", "dataFormat": "PARQUET", "prefix": "campaign-name", "storageCompressionFormat": "GZIP" } } ] } ``` ## Condition-driven fetch Fetch a DTC collection when a condition is met. For example, when the CAN signal is `Vehicle.Ignition == 1`, fetch and upload the DTC data. The following example campaign has condition-driven signal fetching of `Vehicle.ECU1.DTC_INFO` to check whether the DTC ("AAA123") is pending with recordNumber 1 for ECU-1. This campaign has time-based data collection and upload. ``` { "compression": "SNAPPY", "spoolingMode": "TO_DISK", "signalsToFetch": [ { "fullyQualifiedName": "Vehicle.ECU1.DTC_INFO", "signalFetchConfig": { "conditionBased": { // The action will only run when the ignition is on. "conditionExpression": "$variable.`Vehicle.Ignition` == 1", "triggerMode": "ALWAYS" } }, // The UDS module is only requested for the specific ECU address and the specific DTC Number/Status. "actions": ["custom_function(\"DTC_QUERY\", 1, 2, 8, \"0xAAA123\")"] } ], "signalsToCollect": [ { "name": "Vehicle.ECU1.DTC_INFO" }, { "name": "Vehicle.Ignition" } ], "collectionScheme": { "timeBasedCollectionScheme": { "periodMs": 10000 } }, "dataDestinationConfigs": [ { "s3Config": { "bucketArn": "bucket-arn", "dataFormat": "PARQUET", "prefix": "campaign-name", "storageCompressionFormat": "GZIP" } } ] } ``` ## On-demand fetch Fetch a specific DTC for a fleet. For an on-demand use case, you can use the same campaign as defined in the periodic fetch. The on-demand effect is achieved by suspending the campaign shortly after the campaign is deployed using the AWS IoT FleetWise console or by running the following CLI command. + Replace *command-name* with the command name. ``` aws iotfleetwise update-campaign \ --name campaign-name \ --action APPROVE ``` Then, suspend the campaign after the DTC data arrives. ``` aws iotfleetwise update-campaign \ --name campaign-name \ --action SUSPEND ``` You can resume the campaign again for DTC data fetching. ``` aws iotfleetwise update-campaign \ --name campaign-name \ --action RESUME ``` # Visualize AWS IoT FleetWise vehicle data **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 Edge Agent for AWS IoT FleetWise software sends selected vehicle data to an MQTT topic, or transfers it to Amazon Timestream or Amazon Simple Storage Service (Amazon S3). After your data arrives in the data destination, you can use other AWS services to process, re-route, visualize, and share it. **Note** Amazon Timestream is not available in the Asia Pacific (Mumbai) Region. ## Processing vehicle data sent to an MQTT topic Vehicle data sent by MQTT messaging is delivered in near real-time and allows you to use Rules to take action, or route data to other destinations. For more information about using MQTT, see [Device communication protocols](https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html) and [Rules for AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) in the *AWS IoT Core Developer Guide*. The default schema of data that is sent in an MQTT message contains the following fields. | Field name | Data type | Description | | --- | --- | --- | | `eventId` | varchar | The ID of the data collection event. | | `vehicleName` | varchar | The ID of the vehicle from which the data was collected. | | `name` | varchar | The name of the campaign that the Edge Agent software uses to collect data. | | `time` | timestamp | The timestamp of the data point. | | `measure_name` | varchar | The name of the signal. | | `measure_value::bigint` | bigint | Signal values of type Integer. | | `measure_value::double` | double | Signal values of type Double. | | `measure_value::boolean` | boolean | Signal values of type Boolean. | | `measure_value::varchar` | varchar | Signal values of type varchar. | ## Process vehicle data in Timestream Timestream is a fully managed time series database that can store and analyze trillions of time series data points per day. Your data is stored in a customer managed Timestream table. You can use Timestream to query vehicle data so that you can gain insights about your vehicles. For more information, see [What is Amazon Timestream?](https://docs.aws.amazon.com/timestream/latest/developerguide/what-is-timestream.html) The default schema of data that is transferred to Timestream contains the following fields. | Field name | Data type | Description | | --- | --- | --- | | `eventId` | varchar | The ID of the data collection event. | | `vehicleName` | varchar | The ID of the vehicle from which the data was collected. | | `name` | varchar | The name of the campaign that the Edge Agent software uses to collect data. | | `time` | timestamp | The timestamp of the data point. | | `measure_name` | varchar | The name of the signal. | | `measure_value::bigint` | bigint | Signal values of type Integer. | | `measure_value::double` | double | Signal values of type Double. | | `measure_value::boolean` | boolean | Signal values of type Boolean. | | `measure_value::varchar` | varchar | Signal values of type varchar. | ## Visualize vehicle data stored in Timestream After your vehicle data is transferred to Timestream, you can use the following AWS services to visualize, monitor, analyze, and share your data. + Visualize and monitor data in dashboards by using [Grafana or Amazon Managed Grafana](https://docs.aws.amazon.com/timestream/latest/developerguide/Grafana.html). You can visualize data from multiple AWS sources (such as Amazon CloudWatch and Timestream) and other data sources with a single Grafana dashboard. + Analyze and visualize data in dashboards by using [Quick](https://docs.aws.amazon.com/timestream/latest/developerguide/Quicksight.html). ## Process vehicle data in Amazon S3 Amazon S3 is an object storage service that stores and protects any amount of data. You can use S3 for a variety of use cases, such as data lakes, backup and restore, archive, enterprise applications, AWS IoT devices, and big data analytics. Your data is stored in S3 as objects in buckets. For more information, see [What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) The default schema of data that is transferred to Amazon S3 contains the following fields. | Field name | Data type | Description | | --- | --- | --- | | `eventId` | varchar | The ID of the data collection event. | | `vehicleName` | varchar | The ID of the vehicle from which the data was collected. | | `name` | varchar | The name of the campaign that the Edge Agent software uses to collect data. | | `time` | timestamp | The timestamp of the data point. | | `measure_name` | varchar | The name of the signal. | | `measure_value_BIGINT` | bigint | Signal values of type Integer. | | `measure_value_DOUBLE` | double | Signal values of type Double. | | `measure_value_BOOLEAN` | boolean | Signal values of type Boolean. | | `measure_value_STRUCT` | struct | Signal values of type Struct. | | `measure_value_VARCHAR` | varchar | Signal values of type varchar. | ## Amazon S3 object format AWS IoT FleetWise transfers vehicle data to S3 where it's saved as an object. You can use the object URI that uniquely identifies the data to find data from the campaign. The S3 object URI format depends on if the collected data is unstructured or processed data. ### Unstructured data Unstructured data is stored in S3 in a not pre-defined manner. It can be in various formats, such as images or videos. Vehicle messages passed to AWS IoT FleetWise with signal data from Amazon Ion files are decoded and transferred to S3 as objects. The S3 objects represent each signal and are binary encoded. The unstructured data S3 object URI uses the following format: ``` s3://bucket-name/prefix/unstructured-data/random-ID-yyyy-MM-dd-HH-mm-ss-SSS-vehicleName-signalName-fieldName ``` ### Processed data Processed data is stored in S3 and undergoes processing steps that validate, enrich, and transform messages. Object lists and velocity are examples of processed data. Data transferred to S3 are stored as objects that represent records that were buffered for a period of about 10 minutes. By default, AWS IoT FleetWise adds a UTC time prefix in the format `year=YYYY/month=MM/date=DD/hour=HH` before writing objects to S3. This prefix creates a logical hierarchy in the bucket where each forward slash (`/`) creates a level in the hierarchy. The processed data also contains the S3 object URI to unstructured data. The processed data S3 object URI uses the following format: ``` s3://bucket-name/prefix/processed-data/year=YYYY/month=MM/day=DD/hour=HH/part-0000-random-ID.gz.parquet ``` ### Raw data Raw data, also known as primary data, are data collected from Amazon Ion files. You can use raw data to troubleshoot any issues or to root cause errors. The raw data S3 object URI uses the following format: ``` s3://bucket-name/prefix/raw-data/vehicle-name/eventID-timestamp.10n ``` ## Analyze vehicle data stored in Amazon S3 After your vehicle data is transferred to S3, you can use the following AWS services to monitor, analyze, and share your data. Extract and analyze data using Amazon SageMaker AI for downstream labeling and machine learning (ML) workflows. For more information, see the following topics in the *Amazon SageMaker AI Developer Guide*: + [Process data](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html) + [Train machine learning models](https://docs.aws.amazon.com/sagemaker/latest/dg/train-model.html) + [Label Images](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-label-images.html) Catalog your data using AWS Glue crawler and analyze it in Amazon Athena. By default, objects written to S3 have Apache Hive style time partitions, with data paths that contain key-value pairs connected by equal signs. For more information, see the following topics in the *Amazon Athena User Guide*: + [Partitioning data in Athena](https://docs.aws.amazon.com/athena/latest/ug/partitions.html) + [Using AWS Glue to connect to data sources in Amazon S3](https://docs.aws.amazon.com/athena/latest/ug/data-sources-glue.html) + [Best practices when using Athena with AWS Glue](https://docs.aws.amazon.com/athena/latest/ug/glue-best-practices.html) Visualize data using Quick by either reading your Athena table or S3 bucket directly. **Tip** If you're reading from S3 directly, confirm that your vehicle data is in JSON format because Quick doesn't support Apache Parquet format. For more information, see the following topics in the *Amazon Quick User Guide*: + [Supported data sources](https://docs.aws.amazon.com/quicksight/latest/user/supported-data-sources.html) + [Creating a data source](https://docs.aws.amazon.com/quicksight/latest/user/create-a-data-source.html)