Collect and transfer data with campaigns - AWS IoT FleetWise

Collect and transfer data with campaigns

AWS IoT FleetWise is in preview release and is subject to change. We recommend that you use the service only with test data, and not in production environments.

While AWS IoT FleetWise is in preview, you must download the preview AWS SDK and AWS CLI to use the API operations for this service. These API operations aren't available in the public AWS SDK or AWS CLI. For more information, see Preview AWS CLI and AWS SDKs.

A campaign is an orchestration of data collection rules. Campaigns give the AWS IoT FleetWise Edge Agent 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 campaigns, AWS IoT FleetWise automatically deploys them to vehicles. 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.

Note

Campaigns won't work until you have the following.

  • The Edge Agent software is running in your vehicle. For more information about how to 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 must set up AWS IoT Core to provision your vehicle. For more information, see Provision vehicles.

Each campaign contains the following information.

signalCatalogArn

The Amazon Resource Name (ARN) of the signal catalog associated with the campaign.

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 Expressions in the AWS IoT Events Developer Guide.

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

(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) conditionLanguageVersion

The version of the conditional expression language.

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.

(Optional) compression

To save wireless bandwidth and reduce network traffic, you can specify SNAPPY to compress data in vehicles.

By default (OFF), the Edge Agent software doesn't compress data.

(Optional) dataExtraDimensions

You can add one or more attributes to provide additional information for a signal.

(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

You can define the expiration date for your campaign. When the campaign expires, the Edge Agent software stops collecting data 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 collect data, which helps monitor the condition.

Default value: 0

(Optional) priority

You can specify an integer to indicate the priority level of the campaign. Campaigns with a smaller number are higher priorities. You can choose to deploy multiple campaigns to a vehicle. 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.

Important

Signals used in the expression for the condition-based collection scheme must be specified in this field.

signalName

The name of the signal from which data is collected when the data collection scheme is invoked.

(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 a campaign (AWS CLI).

  • 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 – Creates a new campaign.

  • UpdateCampaign – Updates an existing campaign. After a campaign is created, you must use this API operation to approve the campaign.

  • DeleteCampaign – Deletes an existing campaign.

  • ListCampaigns – Retrieves a paginated list of summaries for all campaigns.

  • GetCampaign – Retrieves information about a campaign.