Create a campaign (console)Create a campaign (AWS CLI)

Create an AWS IoT FleetWise campaign

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:
1. Navigate to the AWS IoT FleetWise console.
2. 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.

Topics

Create a campaign (console)

You can use the AWS IoT FleetWise console to create a campaign to select, collect, and transfer vehicle data to the cloud.

To create a campaign

Navigate to the AWS IoT FleetWise console.
On the navigation pane, choose Campaigns.
On the Campaigns page, choose Create campaign, and then complete the steps in the following topics.

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 and Manage AWS IoT FleetWise vehicles.
After a campaign is created, you must approve the campaign. For more information, see Step 5: Deploy a campaign.

Step 1: Configure campaign

In General information, do the following:

Enter a name for the campaign.
(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 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.
2. 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.
3. 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.
  
  Enter the logical expression used to recognize what data to collect.
4. (Optional) You can specify the language version of the conditional expression. The default value is 1.
5. (Optional) You can 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.
6. 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.
7. 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.
8. (Optional) You can edit the scheme’s Advanced scheme options.
  
  To save wireless bandwidth and reduce network traffic by compressing data, choose Snappy.
  (Optional) To define how long, in milliseconds, to continue collecting data after a data collection event, you can specify the Post trigger collection duration.
  (Optional) To indicate the priority level of the campaign, you can specify the campaign Priority. Campaigns with a smaller number for priority are deployed first and are considered to have a higher priority.
  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.
  (Optional) To provide additional information for a signal, add up to five attributes as Extra data dimensions.
To upload a file to define the data collection scheme, select Upload a .json file from your local device. AWS IoT FleetWise automatically defines which options that you can define in the file. You can review and update the selected options.
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 API documentation.
  
  Note
  AWS IoT FleetWise currently supports the .json file format extension.
2. 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.

Specify signals

You can specify the signals to collect data from when the data collection scheme is invoked.

To specify the signals to collect data from

Search for the fully qualified Name of the signal.

Note
The fully qualified name of the signal is the path to the signal plus the signal's name. Use a dot(.) to refer to a child signal.
For example, Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringState is the fully qualified name for the HandsOffSteeringState actuator. Vehicle.Chassis.SteeringWheel.HandsOff. is the path to this actuator.
(Optional) For Max sample count, enter 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) 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.
To add another signal, choose Add more signals. You can add up to 999 signals.
Choose Next.

Step 2: Define storage destination

Note

You can only transfer vehicle data to Amazon S3 if the campaign contains vision system data signals.

Vision system data is in preview release and is subject to change.

Choose the destination where you want to store data collected by the campaign. You can transfer vehicle data to Amazon S3 or Amazon Timestream.

In Destination settings, do the following:

Choose S3 or Timestream from the dropdown list.

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 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.

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.

In S3 destination settings, do the following:

For S3 bucket, choose a bucket that AWS IoT FleetWise has permissions to.
(Optional) Enter a custom prefix that you can use to organize data stored in the S3 bucket.
Choose the output format, which is the format files that are saved as in the S3 bucket.
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.
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.

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? in the Amazon Timestream Developer Guide.

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.

In Timestream table settings, do the following:

For Timestream database name, choose the name of your Timestream database from the dropdown list.
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.

Choose Next.

Step 3: 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:

In the search box, find the attribute or vehicle name and choose it from the list.

Note
Each attribute can be used only once.
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.
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.
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.
Choose Next.

Step 4: 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 5: Deploy a campaign

After you create a campaign, you or your team must deploy the campaign to vehicles.

To deploy a campaign

On the Campaign summary page, choose Deploy.
Review and confirm that you want to start the deployment and begin collecting data from vehicles connected to the campaign.
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 API operation to create a campaign. The following example uses the AWS CLI.

When you create a campaign, data collected from vehicles can be 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 a object storage with industry-leading scalability, data availability, security, and performance.

Important

You can only transfer vehicle data if AWS IoT FleetWise has permissions to write data into S3 or Timestream. For more information about granting access, see Controlling access with AWS IoT FleetWise.

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, Manage AWS IoT FleetWise vehicles, and Manage fleets in AWS IoT FleetWise.
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

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

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"
      }
    }
  ]
}

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 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"
      }
    }
  ]
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Manage data with campaigns

Logical expressions for AWS IoT FleetWise campaigns