2021-11-30 — signal catalog, a vehicle model, a decoder manifest, a vehicle, a fleet, and a campaign—all in the cloud. For more information about the quick start demo, ...
AWS IoT FleetWise
Developer Guide
AWS IoT FleetWise Developer Guide
AWS IoT FleetWise: Developer Guide
Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
AWS IoT FleetWise Developer Guide
Table of Contents
What is AWS IoT FleetWise? ................................................................................................................ 1 Benefits .................................................................................................................................... 2 Use cases .................................................................................................................................. 2 Are you new to AWS IoT FleetWise? ............................................................................................. 3 Accessing AWS IoT FleetWise ....................................................................................................... 3 Pricing for AWS IoT FleetWise ..................................................................................................... 3 How AWS IoT FleetWise works ..................................................................................................... 3 Key concepts ..................................................................................................................... 3 Features of AWS IoT FleetWise ............................................................................................ 5 Related services ......................................................................................................................... 6
Setting up AWS IoT FleetWise ............................................................................................................. 7 Sign up for AWS ........................................................................................................................ 7 Create an IAM user ..................................................................................................................... 7 Configure settings ...................................................................................................................... 8 Prerequisites ...................................................................................................................... 8 Configure settings (console) ............................................................................................... 11 Configure settings (AWS CLI) ............................................................................................. 13
Quick start ...................................................................................................................................... 15 Ingesting data to the cloud ............................................................................................................... 16 Modeling vehicles ............................................................................................................................. 18
Signal catalogs ......................................................................................................................... 19 Configure signals .............................................................................................................. 21 Create a signal catalog (AWS CLI) ....................................................................................... 22 Import a signal catalog (AWS CLI) ...................................................................................... 24 Update a signal catalog (AWS CLI) ...................................................................................... 27 Delete a signal catalog (AWS CLI) ....................................................................................... 29 Get signal catalog information (AWS CLI) ............................................................................ 29
Vehicle models ......................................................................................................................... 30 Create a vehicle model ..................................................................................................... 30 Update a vehicle model (AWS CLI) ...................................................................................... 36 Delete a vehicle model ..................................................................................................... 37 Get vehicle model information (AWS CLI) ............................................................................ 38
Decoder manifests .................................................................................................................... 38 Configure network interfaces and decoder signals ................................................................ 40 Create a decoder manifest ................................................................................................. 41 Update a decoder manifest (AWS CLI) ................................................................................. 44 Delete a decoder manifest ................................................................................................. 45 Get decoder manifest information (AWS CLI) ....................................................................... 46
Vehicles ........................................................................................................................................... 47 Provision vehicles ..................................................................................................................... 48 Authenticate vehicles ........................................................................................................ 49 Authorize vehicles ............................................................................................................ 50 Create a vehicle (AWS CLI) ......................................................................................................... 51 Create multiple vehicles (AWS CLI) ............................................................................................. 52 Update a vehicle (AWS CLI) ....................................................................................................... 53 Update multiple vehicles (AWS CLI) ............................................................................................ 54 Delete a vehicle (AWS CLI) ......................................................................................................... 55 Get vehicle information (AWS CLI) .............................................................................................. 56
Fleets .............................................................................................................................................. 57 Create a fleet (AWS CLI) ............................................................................................................ 58 Associate a vehicle with a fleet (AWS CLI) .................................................................................... 58 Disassociate a vehicle from a fleet (AWS CLI) ............................................................................... 59 Update a fleet (AWS CLI) ........................................................................................................... 59 Delete a fleet (AWS CLI) ............................................................................................................ 60
iii
AWS IoT FleetWise Developer Guide
Get fleet information (AWS CLI) ................................................................................................. 60 Campaigns ....................................................................................................................................... 62
Create a campaign (AWS CLI) ..................................................................................................... 65 Update a campaign (AWS CLI) ................................................................................................... 66 Delete a campaign ................................................................................................................... 66 Get campaign information (AWS CLI) .......................................................................................... 67 Processing and visualizing vehicle data ............................................................................................... 68 Processing vehicle data ............................................................................................................. 68 Visualizing vehicle data ............................................................................................................. 69 Preview AWS CLI and AWS SDKs ........................................................................................................ 70 Configuring the AWS CLI ........................................................................................................... 71 Troubleshooting ............................................................................................................................... 72 AWS IoT FleetWise Edge Agent software issues ............................................................................ 72
Issue: The Edge Agent software doesn't start. ...................................................................... 72 Issue: [ERROR] [IoTFleetWiseEngine::connect]: [ Failed to init persistency library ] ..................... 73 Issue: The Edge Agent software doesn't collect on-board diagnostics (OBD) II PIDs and diagnostic trouble codes (DTCs). ......................................................................................... 73 Issue: The AWS IoT FleetWise Edge Agent software doesn't collect data from the network or isn't able to apply data inspection rules. ............................................................................. 74 Issue: [ERROR] [AwsIotConnectivityModule::connect]: [Connection failed with error] or [WARN] [AwsIotChannel::send]: [No alive MQTT Connection.] ............................................................ 74 Security ........................................................................................................................................... 75 Data protection ........................................................................................................................ 75 Encryption at rest ............................................................................................................. 76 Encryption in transit ......................................................................................................... 76 Identity and Access Management ............................................................................................... 77 Audience ......................................................................................................................... 77 Authenticating with identities ............................................................................................ 78 Managing access using policies .......................................................................................... 79 How AWS IoT FleetWise works with IAM ............................................................................. 81 Identity-based policy examples .......................................................................................... 86 Troubleshooting ............................................................................................................... 88 Monitoring ............................................................................................................................... 90 CloudTrail logs ................................................................................................................. 91 Compliance Validation .............................................................................................................. 92 Resilience ................................................................................................................................ 93 Infrastructure security ............................................................................................................... 94 Configuration and vulnerability analysis ...................................................................................... 94 Security best practices .............................................................................................................. 95 Grant minimum possible permissions .................................................................................. 95 Don't log sensitive information .......................................................................................... 95 Use AWS CloudTrail to view API call history ......................................................................... 95 Keep your device clock in sync ........................................................................................... 95 Document history ............................................................................................................................. 96
iv
AWS IoT FleetWise Developer Guide
What is AWS IoT FleetWise?
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 (p. 70). AWS IoT FleetWise is a managed service that you can use to collect, transform, and transfer vehicle data to the cloud in near-real time. With AWS IoT FleetWise, you can easily collect and organize data from vehicles that use different protocols and data formats. AWS IoT FleetWise helps to transform low-level messages into human-readable values and standardize the data format in the cloud for data analyses. You can also define data collection schemes to control what data to collect in vehicles and when to transfer it to the cloud. After your vehicle data arrives in the cloud, you can use it for use cases like remotely diagnosing issues in individual vehicles, analyzing vehicle fleet health to help prevent potential recalls or safety issues, and using analytics and machine learning to improve advanced technologies like autonomous driving and advanced driver assistance systems. The following diagram shows the basic architecture of AWS IoT FleetWise.
Topics · Benefits (p. 2) · Use cases (p. 2) · Are you new to AWS IoT FleetWise? (p. 3) 1
AWS IoT FleetWise Developer Guide Benefits
· Accessing AWS IoT FleetWise (p. 3) · Pricing for AWS IoT FleetWise (p. 3) · How AWS IoT FleetWise works (p. 3) · Related services (p. 6)
Benefits
The key benefits of AWS IoT FleetWise are:
Easily access standardized, fleet-wide data
Access the unique data format of any vehicle, structure it, and make it understandable without having to develop a custom system. With an aggregated data structure, you can easily access fleetwide insights and identify trends while using your cloud-based applications and services. Reduce costs by transferring vehicle data to the cloud more efficiently
Define data collection schemes to transfer only high-value data signals to the cloud. This helps keep costs low and gives access to more useful data. With AWS IoT FleetWise, you can reduce the amount of data transferred to the cloud from vehicles. Detect and mitigate issues faster by surfacing vehicle health data in near-real time
Surface selected data about widespread vehicle quality issues and take corrective action quickly, such as notifying the manufacturing group to help mitigate further spread. To detect problems early on, you can reduce service and warranty costs, help avoid large recalls, and maintain customer trust. Improve customer experience by remotely diagnosing problems in near-real time
Provide customers remote assistance if something is wrong with their vehicle. Use data from AWS IoT FleetWise to diagnose issues in near-real time. Then, help the customer with a simple fix at home, or work with a dealer to order parts and schedule a service appointment. You can use the collected information to continually improve the experience.
Use cases
The use cases of AWS IoT FleetWise are:
Train computer vision models
Train autonomous vehicles (AVs) and advanced driver assistance systems (ADAS) by using AWS IoT FleetWise to collect camera data from a fleet of vehicles. Protect against warranty claims and recalls
Use near-real time data to proactively detect fleet-wide quality issues and take action. Improve EV range estimates
Collect crowd-sourced environmental data, such as weather and driving conditions, from other nearby vehicles and use it to improve electric vehicle (EV) battery range estimates for drivers in nearreal time. Near-real time hazard detection
Help drivers avoid hazardous road conditions, such as ice or stranded vehicles, by using crowdsourced data from nearby vehicles to detect road conditions in near-real time.
2
AWS IoT FleetWise Developer Guide Are you new to AWS IoT FleetWise?
Are you new to AWS IoT FleetWise?
If you're a first-time user of AWS IoT FleetWise, we recommend that you begin by reading the following sections: · How AWS IoT FleetWise works (p. 3) · Setting up AWS IoT FleetWise (p. 7) · Quick start with AWS IoT FleetWise (p. 15) · Ingesting data to the cloud (p. 16)
Accessing AWS IoT FleetWise
You can use the AWS IoT FleetWise console or API to access AWS IoT FleetWise. Note The AWS IoT FleetWise console currently supports creating vehicle models and decoder manifests only.
Pricing for AWS IoT FleetWise
You pay for vehicles that you created in AWS IoT FleetWise at the end of each month. You also pay for messages that you collect from vehicles. For current information about pricing, see the AWS IoT FleetWise Pricing page.
How AWS IoT FleetWise works
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 (p. 70).
The following sections provide an overview of AWS IoT FleetWise service components and how they interact. After you read this introduction, see the Setting up AWS IoT FleetWise (p. 7) section to learn how to set up AWS IoT FleetWise. Topics
· Key concepts (p. 3) · Features of AWS IoT FleetWise (p. 5)
Key concepts
AWS IoT FleetWise provides a vehicle modeling framework that you can use to model your vehicle and its sensors and actuators in the cloud. To enable the secure communication between your vehicle and the
3
AWS IoT FleetWise Developer Guide Key concepts
cloud, AWS IoT FleetWise also provides the Edge Agent software that you can download and install in your vehicle. You define data collection schemes in the cloud and deploy them to your vehicle. The Edge Agent software running in your vehicle uses data collection schemes to control what data to collect and when to transfer it to the cloud.
The following are the core concepts of AWS IoT FleetWise.
Signal
Signals are fundamental structures that you define to contain vehicle data and its metadata. A signal can be an attribute, a branch, a sensor, or an actuator. For example, you can create a sensor to receive in-vehicle temperature values, and to store its metadata, including a sensor name, a data type, and a unit. For more information, see Create and manage signal catalogs (p. 19). Attribute
Attributes represent static information that generally doesn't change, such as manufacturer and manufacturing date. Branch
Branches represent signals in a nested structure. Branches demonstrate signal hierarchies. For example, the Vehicle branch has a child branch, Powertrain. The Powertrain branch has a child branch, combustionEngine. To locate the combustionEngine branch, use the Vehicle.Powertrain.combustionEngine expression. Sensor
Sensor data reports the current state of the vehicle and change over time, as the state of the vehicle changes, such as fluid levels, temperatures, vibrations, or voltage. Actuator
Actuator data reports the state of a vehicle device, such as motors, heaters, and door locks. Changing the state of a vehicle device can update actuator data. For example, you can define an actuator to represent the heater. The actuator receives new data when you turn on or off the heater. Signal catalog
A signal catalog contains a collection of signals. Signals in a signal catalog can be used to model vehicles that use different protocols and data formats. For example, there are two cars made by different automakers: one uses the Control Area Network (CAN bus) protocol; the other one uses the On-board Diagnostics (OBD) protocol. You can define a sensor in the signal catalog to receive invehicle temperature values. This sensor can be used to represent the thermocouples in both cars. For more information, see Create and manage signal catalogs (p. 19). Vehicle model (model manifest)
Vehicle models are declarative structures that you can use to standardize the format of your vehicles and to define relationships between signals in the vehicles. Vehicle models enforce consistent information across multiple vehicles of the same type. You add signals to create vehicle models. For more information, see Create and manage vehicle models (p. 30). Decoder manifest
Decoder manifests contain decoding information for each signal in vehicle models. Sensors and actuators in vehicles transmit low-level messages (binary data). With decoder manifests, AWS IoT FleetWise is able to transform binary data into human-readable values. Every decoder manifest is associated with a vehicle model. For more information, see Create and manage decoder manifests (p. 38). Network interface
Contains information about the protocol that the in-vehicle network uses. AWS IoT FleetWise supports the following protocols.
4
AWS IoT FleetWise Developer Guide Features of AWS IoT FleetWise
Controller Area Network (CAN bus)
A protocol that defines how data is communicated between electronic control units (ECUs). ECUs can be the engine control unit, airbags, or the audio system. On-board diagnostic (OBD) II
A further developed protocol that defines how self-diagnostic data is communicated between ECUs. It provides a number of standard diagnostic trouble codes (DTCs) that help identify what is wrong with your vehicle. Decoder signal
Provides detailed decoding information for a specific signal. Every signal specified in the vehicle model must be paired with a decoder signal. If the decoder manifest contains CAN network interfaces, it must contain CAN decoder signals. If the decoder manifest contains OBD network interfaces, it must contain OBD decoder signals. Vehicle
A virtual representation of your physical vehicle, such a car or a truck. Vehicles are instances of vehicle models. Vehicles created from the same vehicle model inherit the same group of signals. Each vehicle corresponds to an AWS IoT thing. Fleet
A fleet represents a group of vehicles. Before you can easily manage a fleet of vehicles, you must associate individual vehicles to a fleet. Campaign
Contains data collection schemes. You define a campaign in the cloud and deploy it to a vehicle or fleet. Campaigns give the Edge Agent software instructions on how to select, collect, and transfer data to the cloud. Data collection scheme
Data collection schemes give the Edge Agent software instructions on how to collect data. Currently, AWS IoT FleetWise supports the condition-based collection scheme and the time-based collection scheme. Condition-based collection scheme
Use a logical expression to recognize what data to collect. The Edge Agent software collects data when the condition is met. For example, if the expression is $variable.myVehicle.InVehicleTemperature >35.0, the Edge Agent software collects temperature values that are greater than 35.0. Time-based collection scheme
Specify a time period in milliseconds to define how often to collect data. For example, if the time period is 10,000 milliseconds, the Edge Agent software collects data once every 10 seconds.
Features of AWS IoT FleetWise
The following are the key features of AWS IoT FleetWise.
Vehicle modeling
Build virtual representations of your vehicles and apply a common format to organize vehicle signals. AWS IoT FleetWise supports Vehicle Signal Specification (VSS) that you can use to standardize vehicle signals.
5
AWS IoT FleetWise Developer Guide Related services
Scheme-based data collection Define schemes to transfer only high-value vehicle data to the cloud. You can define conditionbased schemes to control what data to collect, such as data in-vehicle temperature values that are greater than 40 degrees. You can also define time-based schemes to control how often to collect data.
AWS IoT FleetWise Edge Agent software The Edge Agent software running in vehicles facilitates communication between vehicles and the cloud. While vehicles are connected to the cloud, the Edge Agent software continually receives data collection schemes and collects data accordingly.
Related services
AWS IoT FleetWise integrates with the following AWS services to improve the availability and scalability of your cloud solutions. · AWS IoT Core Register and control AWS IoT devices that upload vehicle data to AWS IoT FleetWise.
For more information, see What is AWS IoT in the AWS IoT Developer Guide. · Amazon Timestream Use a time series database to store and analyze your vehicle data. For more
information. see What is Amazon Timestream in the Amazon Timestream Developer Guides.
6
AWS IoT FleetWise Developer Guide Sign up for AWS
Setting up AWS IoT FleetWise
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 (p. 70).
When you sign up for AWS, your AWS account is automatically signed up for all services in AWS, including AWS IoT FleetWise. To set up AWS IoT FleetWise, use the steps in the following sections.
Topics · Sign up for AWS (p. 7) · Create an IAM user (p. 7) · Configure settings (p. 8)
Sign up for AWS
If you do not have an AWS account, complete the following steps to create one.
To sign up for an AWS account
1. Open https://portal.aws.amazon.com/billing/signup. 2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.
Create an IAM user
To create an administrator user for yourself and add the user to an administrators group (console)
1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password. Note We strongly recommend that you adhere to the best practice of using the Administrator IAM user that follows and securely lock away the root user credentials. Sign in as the root user only to perform a few account and service management tasks.
2. In the navigation pane, choose Users and then choose Add user. 3. For User name, enter Administrator. 4. Select the check box next to AWS Management Console access. Then select Custom password, and
then enter your new password in the text box. 5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You
can clear the check box next to User must create a new password at next sign-in to allow the new user to reset their password after they sign in.
7
AWS IoT FleetWise Developer Guide Configure settings
6. Choose Next: Permissions. 7. Under Set permissions, choose Add user to group. 8. Choose Create group. 9. In the Create group dialog box, for Group name enter Administrators. 10. Choose Filter policies, and then select AWS managed - job function to filter the table contents. 11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
Note You must activate IAM user and role access to Billing before you can use the AdministratorAccess permissions to access the AWS Billing and Cost Management console. To do this, follow the instructions in step 1 of the tutorial about delegating access to the billing console. 12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to see the group in the list. 13. Choose Next: Tags. 14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM entities in the IAM User Guide. 15. Choose Next: Review to see the list of group memberships to be added to the new user. When you are ready to proceed, choose Create user.
You can use this same process to create more groups and users and to give your users access to your AWS account resources. To learn about using policies that restrict user permissions to specific AWS resources, see Access management and Example policies.
Configure settings
Before exploring AWS IoT FleetWise, you must configure the service settings. The AWS IoT FleetWise edge agent software transfers your vehicle data to Amazon Timestream. To enable Amazon Timestream to receive your vehicle data, configure the settings. After the settings are configured, AWS IoT FleetWise automatically registers your AWS account, IAM, and Amazon Timestream resources for the preview access.
You can use the AWS IoT FleetWise console or API to configure the settings.
Prerequisites
To configure the settings, you need the following AWS resources. Important
· You must use the same AWS Region when you create Timestream resources for AWS IoT FleetWise. If you switch AWS Regions, you might have issues accessing the Timestream resources.
· AWS IoT FleetWise is available in US East (N. Virginia) and Europe (Frankfurt). · For the list of supported Regions, see Timestream endpoints and quotas in the AWS General
Reference.
· An Amazon Timestream database. For a tutorial, see Create a database in the Amazon Timestream Developer Guide.
· A table created in the specified Amazon Timestream database. For a tutorial, see Create a table in the Amazon Timestream Developer Guide.
8
AWS IoT FleetWise Developer Guide Prerequisites
· An IAM role that allows AWS IoT FleetWise to send data to Amazon Timestream. Make sure that your role has the permissions shown in the following AWS CLI example.
To create an IAM role with required policies
1. To create an IAM role, run the following command. · Replace AWSIoTFleetwisePreviewServiceRole with the name of the role you're creating. · Replace trust-policy with the JSON file that contains the trust policy.
aws iam create-role --role-name AWSIoTFleetwisePreviewServiceRole --assume-rolepolicy-document file://trust-policy.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iotfleetwise.amazonaws.com" }, "Action": "sts:AssumeRole" } ]
}
Example output
{ "Role": { "Path": "/", "RoleName": "AWSIoTFleetwisePreviewServiceRole", "RoleId": "AROA5NYUCQRRSDBVAOP73", "Arn": "arn:aws:iam::12345678912:role/AWSIoTFleetwisePreviewServiceRole", "CreateDate": "2021-11-22T00:54:33+00:00", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iotfleetwise.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } }
}
2. To create an IAM user policy, run the following command. · Replace AWSIoTFleetwisePreviewIAMUserPolicy with the name of the policy you're creating. · Replace iam-user-policy with the name of the JSON file that contains the IAM user policy.
aws iam create-policy --policy-name AWSIoTFleetwisePreviewIAMUserPolicy --policydocument file://iam-user-policy.json
9
AWS IoT FleetWise Developer Guide Prerequisites
{ "Version": "2012-10-17", "Statement": [ { "Sid": "timestreamIngestion", "Effect": "Allow", "Action": [ "timestream:WriteRecords", "timestream:Select" ], "Resource": "*" }, { "Sid": "timestreamDescribeEndpoint", "Effect": "Allow", "Action": [ "timestream:DescribeEndpoints" ], "Resource": "*" } ]
}
Example output
{ "Policy": { "PolicyName": "AWSIoTFleetwisePreviewIAMUserPolicy", "PolicyId": "ANPA5NYUCQRRWIIGN2ZPH", "Arn": "arn:aws:iam::922923205731:policy/
AWSIoTFleetwisePreviewIAMUserPolicy", "Path": "/", "DefaultVersionId": "v1", "AttachmentCount": 0, "PermissionsBoundaryUsageCount": 0, "IsAttachable": true, "CreateDate": "2021-11-22T01:01:41+00:00", "UpdateDate": "2021-11-22T01:01:41+00:00"
} }
3. From the output, copy the Amazon Resource Name (ARN) of the IAM user policy.
4. To attach the IAM user policy to your IAM role, run the following command.
· Replace iam-user-policy-arn with the ARN that you copied in the previous step. · Replace AWSIoTFleetwisePreviewServiceRole with the name of the IAM role that you
created.
aws iam attach-role-policy --policy-arn iam-user-policy-arn --rolename AWSIoTFleetwisePreviewServiceRole
5. To create a permissions policy, run the following command.
· Replace AWSIoTFleetwiseAccessTimestreamPermissionsPolicy with the name of the policy you're creating.
· Replace permissions-policy with the name of the JSON file that contains the permissions policy.
aws iam create-policy --policy-name AWSIoTFleetwiseAccessTimestreamPermissionsPolicy --policy-document file://permissions-policy.json
10
AWS IoT FleetWise Developer Guide Configure settings (console)
{ "Version": "2012-10-17", "Statement": [ { "Sid": "timestreamIngestion", "Effect": "Allow", "Action": [ "timestream:WriteRecords", "timestream:Select" ], "Resource": "*" }, { "Sid": "timestreamDescribeEndpoint", "Effect": "Allow", "Action": [ "timestream:DescribeEndpoints" ], "Resource": "*" } ]
}
Example output
{ "Policy": { "PolicyName": "AWSIoTFleetwiseAccessTimestreamPermissionsPolicy", "PolicyId": "ANPA5NYUCQRRUJFQEZCOI", "Arn": "arn:aws:iam::012345678912:policy/
AWSIoTFleetwiseAccessTimestreamPermissionsPolicy", "Path": "/", "DefaultVersionId": "v1", "AttachmentCount": 0, "PermissionsBoundaryUsageCount": 0, "IsAttachable": true, "CreateDate": "2021-11-22T01:12:55+00:00", "UpdateDate": "2021-11-22T01:12:55+00:00"
} }
6. From the output, copy the ARN of the permissions policy. 7. To attach the IAM permissions policy to your IAM role, run the following command.
· Replace permissions-policy-arn with the ARN that you copied in the previous step. · Replace AWSIoTFleetwisePreviewServiceRole with the name of the IAM role that you
created.
aws iam attach-role-policy --policy-arn permissions-policy-arn --rolename AWSIoTFleetwisePreviewServiceRole
For more information, see Access management for AWS resources in the IAM User Guide.
Configure settings (console)
In the AWS CLI console, configure settings to transfer data to Amazon Timestream.
11
AWS IoT FleetWise Developer Guide Configure settings (console)
1. Navigate to the AWS IoT FleetWise console. 2. In the navigation pane, choose Settings. 3. On the Onboarding page, do the following:
· For Timestream database name, enter the name of your Timestream database. · For Timestream table name, enter the name of your Timestream table. · For Timestream access role, enter the ARN of the IAM role that you created. 4. Choose Submit.
After you update the settings, AWS automatically registers your AWS account, IAM role, and Timestream resources for the preview access. The registration status can be one of the following: · REGISTRATION_SUCCESS The AWS resource is successfully registered. · REGISTRATION_PENDING AWS IoT FleetWise is processing the registration request. This process
takes approximately five minutes to complete. · REGISTRATION_FAILURE AWS IoT FleetWise can't register the AWS resource. Try again later.
12
AWS IoT FleetWise Developer Guide Configure settings (AWS CLI)
Configure settings (AWS CLI)
In the AWS CLI, configure settings to transfer data to Amazon Timestream. 1. To configure the settings, run the following command.
aws iotfleetwise register-account --cli-input-json file://file-name.json
Example AWS IoT FleetWise registration configuration · Replace role-arn with the IAM role that you created. · Replace database-name with the name of your Timestream database. · Replace table-name with the name of your Timestream table.
{ "iamResources": { "roleArn": "role-arn" }, "timestreamResources": { "timestreamDatabaseName": "database-name", "timestreamTableName": "table-name" }
}
2. To verify that your AWS account, IAM, and Amazon Timestream resources are registered, run the following command to retrieve the registration status.
aws iotfleetwise get-register-account-status
Example response
{ "accountStatus": "REGISTRATION_SUCCESS", "creationDate": 1637546612753, "customerAccountId": "012345678912", "iamRegistrationResponse": { "errorMessage": "", "registrationStatus": "REGISTRATION_SUCCESS", "roleArn": "arn:aws:iam::012345678912:role/AWSIoTFleetwisePreviewServiceRole" },
13
AWS IoT FleetWise Developer Guide Configure settings (AWS CLI)
"lastModificationDate": 1637546614035, "timestreamRegistrationResponse": {
"errorMessage": "", "registrationStatus": "REGISTRATION_SUCCESS", "timestreamDatabaseArn": "arn:aws:timestream:us-east-1:012345678912:database/ myDatabase", "timestreamDatabaseName": "myDatabase", "timestreamTableArn": "arn:aws:timestream:us-east-1:922923205731:database/ myDatabase/table/myTable", "timestreamTableName": "myTable" } }
After you update the settings, AWS automatically registers your AWS account, IAM role, and Timestream resources for the preview access. The registration status can be one of the following: · REGISTRATION_SUCCESS The AWS resource is successfully registered. · REGISTRATION_PENDING AWS IoT FleetWise is processing the registration request. This process
takes approximately five minutes to complete. · REGISTRATION_FAILURE AWS IoT FleetWise can't register the AWS resource. Try again later.
14
AWS IoT FleetWise Developer Guide
Quick start with AWS IoT FleetWise
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 (p. 70). AWS IoT FleetWise provides a quick start demo that you can use to explore AWS IoT FleetWise and the AWS IoT FleetWise Edge Agent software. AWS IoT FleetWise provides the demo as an AWS CloudFormation template. You can deploy it to install the Edge Agent software on an Amazon EC2 Graviton and generate sample vehicle data. The demo also provides a script that you can use to create a signal catalog, a vehicle model, a decoder manifest, a vehicle, a fleet, and a campaign--all in the cloud. For more information about the quick start demo, do the following to download the AWS IoT FleetWise Edge Agent software Developer Guide. 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.
15
AWS IoT FleetWise Developer Guide
Ingesting data to the cloud
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 (p. 70).
The AWS IoT FleetWise Edge Agent software, when installed and running in vehicles, facilitates secure communication between your vehicles and the cloud.
Note
· AWS IoT FleetWise is not intended for use in, or in association with, the operation of any hazardous environments or critical systems that may lead to serious bodily injury or death or cause environmental or property damage. Vehicle data collected through your use of AWS IoT FleetWise is for informational purposes only, and you may not use AWS IoT FleetWise to control or operate vehicle functions.
· Vehicle data collected through your use of AWS IoT FleetWise should be evaluated for accuracy as appropriate for your use case, including for purposes of meeting any compliance obligations you may have under applicable vehicle safety regulations (such as safety monitoring and reporting obligations). Such evaluation should include collecting and reviewing information through other industry standard means and sources (such as reports from drivers of vehicles).
To ingest data to the cloud, do the following:
1. Install the AWS IoT FleetWise Edge Agent software in your vehicle. For more information about how to work with the Edge Agent software, do the following to download the AWS IoT FleetWise Edge Agent software Developer Guide.
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. 2. Create or import a signal catalog containing signals that you'll use to create a vehicle model. For
more information, see Create a signal catalog (AWS CLI) (p. 22) and Import a signal catalog (AWS CLI) (p. 24).
Note · If you use the AWS IoT FleetWise console to create the first vehicle model, you don't need
to manually create a signal catalog. When you create your first vehicle model, AWS IoT FleetWise automatically creates a signal catalog for you. For more information, see Create a vehicle model (console) (p. 31). · AWS IoT FleetWise currently supports a signal catalog for each AWS account per Region. 3. Use signals in the signal catalog to create a vehicle model. For more information, see Create a vehicle model (p. 30). Note · If you use the AWS IoT FleetWise console to create a vehicle model, you can upload .dbc files to import signals. .dbc is a file format that Controller Area Network (CAN bus)
16
AWS IoT FleetWise Developer Guide
databases support. After the vehicle model is created, new signals are automatically added to the signal catalog. For more information, see Create a vehicle model (console) (p. 31). · If you use the CreateModelManifest API operation to create a vehicle model, you must use the UpdateModelManifest API operation to activate the vehicle model. For more information, see Update a vehicle model (AWS CLI) (p. 36). · If you use the AWS IoT FleetWise console to create a vehicle model, AWS IoT FleetWise automatically activates the vehicle model for you. 4. Create a decoder manifest. The decoder manifest contains decoding information for every signal specified in the vehicle model that you created in the previous step. The decoder manifest is associated with the vehicle model that you created. For more information, see Create and manage decoder manifests (p. 38). Note · If you use the CreateDecoderManifest API operation to create a decoder manifest, you must use the UpdateDecoderManifest API operation to activate the decoder manifest. For more information, see Update a decoder manifest (AWS CLI) (p. 44). · If you use the AWS IoT FleetWise console to create a decoder manifest, AWS IoT FleetWise automatically activates the decoder manifest for you. 5. Create vehicles from the vehicle model. Vehicles created from the same vehicle model inherit the same group of signals. You must use AWS IoT Core to provision your vehicle before you can ingest data to the cloud. For more information, see Create, provision, and manage vehicles (p. 47). 6. (Optional) Create a fleet to represent a group of vehicles, and then associate individual vehicles with the fleet. This helps you manage multiple vehicles at the same time. For more information, see Create and manage fleets (p. 57). 7. Create campaigns. Campaigns are deployed to a vehicle or a fleet of vehicles. Campaigns give the Edge Agent software instructions on how to select, collect, and transfer data to the cloud. For more information, see Collect and transfer data with campaigns (p. 62). Note You must use the UpdateCampaign API operation to approve the campaign, before AWS IoT FleetWise can deploy it to the vehicle or fleet. For more information, see Update a campaign (AWS CLI) (p. 66).
The Edge Agent software transfers vehicle data to a Timestream table. You can use Timestream to query your data, and use Amazon QuickSight or Grafana to visualize your data. For more information, see Processing and visualizing vehicle data (p. 68).
17
AWS IoT FleetWise Developer Guide
Modeling vehicles
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 (p. 70).
AWS IoT FleetWise provides a vehicle modeling framework that you can use to build virtual representations of your vehicles in the cloud. Signals, signal catalogs, vehicle models, and decoder manifests are the core components that you work with to model your vehicles.
Signal
Signals are fundamental structures that you define to contain vehicle data and its metadata. A signal can be an attribute, a branch, a sensor, or an actuator. For example, you can create a sensor to receive in-vehicle temperature values, and to store its metadata, including a sensor name, a data type, and a unit. For more information, see Create and manage signal catalogs (p. 19). Signal catalog
A signal catalog contains a collection of signals. Signals in a signal catalog can be used to model vehicles that use different protocols and data formats. For example, there are two cars made by different automakers: one uses the Control Area Network (CAN bus) protocol; the other one uses the On-board Diagnostics (OBD) protocol. You can define a sensor in the signal catalog to receive invehicle temperature values. This sensor can be used to represent the thermocouples in both cars. For more information, see Create and manage signal catalogs (p. 19). Vehicle model (model manifest)
Vehicle models are declarative structures that you can use to standardize the format of your vehicles and to define relationships between signals in the vehicles. Vehicle models enforce consistent information across multiple vehicles of the same type. You add signals to create vehicle models. For more information, see Create and manage vehicle models (p. 30). Decoder manifest
Decoder manifests contain decoding information for each signal in vehicle models. Sensors and actuators in vehicles transmit low-level messages (binary data). With decoder manifests, AWS IoT FleetWise is able to transform binary data into human-readable values. Every decoder manifest is associated with a vehicle model. For more information, see Create and manage decoder manifests (p. 38).
You can use the AWS IoT FleetWise console or API to model vehicles in the following way.
1. Create or import a signal catalog containing signals that you'll use to create a vehicle model. For more information, see Create a signal catalog (AWS CLI) (p. 22) and Import a signal catalog (AWS CLI) (p. 24). Note · If you use the AWS IoT FleetWise console to create the first vehicle model, you don't need to manually create a signal catalog. When you create your first vehicle model, AWS IoT FleetWise automatically creates a signal catalog for you. For more information, see Create a vehicle model (console) (p. 31). · AWS IoT FleetWise currently supports a signal catalog for each AWS account per Region.
18
AWS IoT FleetWise Developer Guide Signal catalogs
2. Use signals in the signal catalog to create a vehicle model. For more information, see Create a vehicle model (p. 30). Note · If you use the AWS IoT FleetWise console to create a vehicle model, you can upload .dbc files to import signals. .dbc is a file format that Controller Area Network (CAN bus) databases support. After the vehicle model is created, new signals are automatically added to the signal catalog. For more information, see Create a vehicle model (console) (p. 31). · If you use the CreateModelManifest API operation to create a vehicle model, you must use the UpdateModelManifest API operation to activate the vehicle model. For more information, see Update a vehicle model (AWS CLI) (p. 36). · If you use the AWS IoT FleetWise console to create a vehicle model, AWS IoT FleetWise automatically activates the vehicle model for you.
3. Create a decoder manifest. The decoder manifest contains decoding information for every signal specified in the vehicle model that you created in the previous step. The decoder manifest is associated with the vehicle model that you created. For more information, see Create and manage decoder manifests (p. 38). Note · If you use the CreateDecoderManifest API operation to create a decoder manifest, you must use the UpdateDecoderManifest API operation to activate the decoder manifest. For more information, see Update a decoder manifest (AWS CLI) (p. 44). · If you use the AWS IoT FleetWise console to create a decoder manifest, AWS IoT FleetWise automatically activates the decoder manifest for you.
CAN bus databases support the .dbc file format. You might upload .dbc files to import signals and decoder signals. To get an example .dbc file, do the following.
To get a .dbc file
1. Download the EngineSignals.zip. 2. Navigate to the directory where you downloaded the EngineSignals.zip file. 3. Unzip the file and save it locally as EngineSignals.dbc.
Topics · Create and manage signal catalogs (p. 19) · Create and manage vehicle models (p. 30) · Create and manage decoder manifests (p. 38)
Create and manage signal catalogs
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 (p. 70).
A signal catalog is a collection of standardized signals that can be reused to create vehicle models. AWS IoT FleetWise supports Vehicle Signal Specification (VSS) that you can follow to define signals. A signal can be any of the following type.
19
AWS IoT FleetWise Developer Guide Signal catalogs
Attribute
Attributes represent static information that generally doesn't change, such as manufacturer and manufacturing date. Branch
Branches represent signals in a nested structure. Branches demonstrate signal hierarchies. For example, the Vehicle branch has a child branch, Powertrain. The Powertrain branch has a child branch, combustionEngine. To locate the combustionEngine branch, use the Vehicle.Powertrain.combustionEngine expression. Sensor
Sensor data reports the current state of the vehicle and change over time, as the state of the vehicle changes, such as fluid levels, temperatures, vibrations, or voltage. Actuator
Actuator data reports the state of a vehicle device, such as motors, heaters, and door locks. Changing the state of a vehicle device can update actuator data. For example, you can define an actuator to represent the heater. The actuator receives new data when you turn on or off the heater.
Note
· If you use the AWS IoT FleetWise console to create the first vehicle model, you don't need to manually create a signal catalog. When you create your first vehicle model, AWS IoT FleetWise automatically creates a signal catalog for you. For more information, see Create a vehicle model (console) (p. 31).
· If you use the AWS IoT FleetWise console to create a vehicle model, you can upload .dbc files to import signals. .dbc is a file format that Controller Area Network (CAN bus) databases support. After the vehicle model is created, new signals are automatically added to the signal catalog. For more information, see Create a vehicle model (console) (p. 31).
· AWS IoT FleetWise currently supports a signal catalog for each AWS account per Region.
AWS IoT FleetWise provides the following API operations that you can use to create and manage signal catalogs.
· CreateSignalCatalog Creates a new signal catalog. · ImportSignalCatalog Imports signals to create a signal catalog by uploading a JSON file. Signals
must be defined by following VSS and saved in the JSON format. · UpdateSignalCatalog Updates an existing signal catalog by updating, removing, or adding signals. · DeleteSignalCatalog Deletes an existing signal catalog. · ListSignalCatalogs Retrieves a paginated list of summaries of all signal catalogs. · ListSignalCatalogNodes Retrieves a paginated list of summaries of all signals (nodes) in a given signal
catalog. · GetSignalCatalog Retrieves information about a signal catalog.
Tutorials · Configure signals (p. 21) · Create a signal catalog (AWS CLI) (p. 22) · Import a signal catalog (AWS CLI) (p. 24) · Update a signal catalog (AWS CLI) (p. 27) · Delete a signal catalog (AWS CLI) (p. 29)
20
AWS IoT FleetWise Developer Guide Configure signals
· Get signal catalog information (AWS CLI) (p. 29)
Configure signals
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 (p. 70).
This section shows you how to configure branches, attributes, sensors, and actuators.
Topics · Configure branches (p. 21) · Configure attributes (p. 21) · Configure sensors or actuators (p. 22)
Configure branches
To configure a branch, specify the following information.
· name The branch's name. The branch name must be unique. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore).
· fullyQualifiedName The fully qualified name of the branch is the path to the branch plus the branch's name. Use a dot(.) to refer to a child branch. For example, Vehicle.Chassis.SteeringWheel is the fully qualified name for the SteeringWheel branch. Vehicle.Chassis. is the path to this branch. The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore)
· (Optional) Description The description for the branch. The description can have up to 2048 characters. Valid characters: a-z, A-Z, 0-9, : (colon), _ (underscore), and - (hyphen)
Configure attributes
To configure an attribute, specify the following information.
· name The attribute's name. The attribute name must be unique. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore).
· dataType The attribute's data type must be one of the following: INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, BOOLEAN, FLOAT, DOUBLE, STRING, UNIX_TIMESTAMP, INT8_ARRAY, UINT8_ARRAY, INT16_ARRAY, UINT16_ARRAY, INT32_ARRAY, UINT32_ARRAY, INT64_ARRAY, UINT64_ARRAY, BOOLEAN_ARRAY, FLOAT_ARRAY, DOUBLE_ARRAY, STRING_ARRAY, UNIX_TIMESTAMP_ARRAY, or UNKNOWN.
· fullyQualifiedName The fully qualified name of the attribute is the path to the attribute plus the attribute's name. Use a dot(.) to refer to a child signal. For example,
21
AWS IoT FleetWise Developer Guide Create a signal catalog (AWS CLI)
Vehicle.Chassis.SteeringWheel.Diameter is the fully qualified name for the Diameter attribute. Vehicle.Chassis.SteeringWheel. is the path to this attribute.
The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore) · (Optional) Description The description for the attribute.
The description can have up to 2048 characters. Valid characters: a-z, A-Z, 0-9, : (colon), _ (underscore), and - (hyphen) · (Optional) unit The scientific unit for the attribute, such as km or Celsius. · (Optional) min The minimum value of the attribute. · (Optional) max The maximum value of the attribute. · (Optional) defaultValue The default value of the attribute. · (Optional) assignedValue The value assigned to the attribute. · (Optional) allowedValues A list of values that the attribute accepts.
Configure sensors or actuators
To configure a sensor or actuator, specify the following information.
· name The signal's name.
The signal name must be unique. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). · dataType The signal's data type must be one of the following: INT8, UINT8, INT16, UINT16,
INT32, UINT32, INT64, UINT64, BOOLEAN, FLOAT, DOUBLE, STRING, UNIX_TIMESTAMP, INT8_ARRAY, UINT8_ARRAY, INT16_ARRAY, UINT16_ARRAY, INT32_ARRAY, UINT32_ARRAY, INT64_ARRAY, UINT64_ARRAY, BOOLEAN_ARRAY, FLOAT_ARRAY, DOUBLE_ARRAY, STRING_ARRAY, UNIX_TIMESTAMP_ARRAY, or UNKNOWN. · fullyQualifiedName 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.
The fully qualified name can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore) · (Optional) Description The description for the signal.
The description can have up to 2048 characters. Valid characters: a-z, A-Z, 0-9, : (colon), _ (underscore), and - (hyphen) · (Optional) unit The scientific unit for the signal, such as km or celsius. · (Optional) min The minimum value of the signal. · (Optional) max The maximum value of the signal. · (Optional) assignedValue The value assigned to the signal. · (Optional) allowedValues A list of values that the signal accepts.
Create a signal catalog (AWS CLI)
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.
22
AWS IoT FleetWise Developer Guide Create a signal catalog (AWS CLI)
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 (p. 70).
You can use the CreateSignalCatalog API operation to create a signal catalog. The following example uses AWS CLI.
To create a signal catalog, run the following command.
Replace signal-catalog-configuration with the name of the JSON file that contains the configuration.
aws iotfleetwise create-signal-catalog --cli-input-json file://signal-catalogconfiguration.json
· Replace signal-catalog-name with the name of the signal catalog that you're creating. · (Optional) Replace description with a description to help you identify the signal catalog.
For more information about how to configure branches, attributes, sensors, and actuators, see Configure signals (p. 21).
{ "description": "description", "name": "signal-catalog-name", "nodes": [ ... { "branch": { "fullyQualifiedName": "Vehicle", "name": "Vehicle" }, "type": "branch" }, { "branch": { "description": "Powertrain data for battery management.", "fullyQualifiedName": "Vehicle.Powertrain", "name": "Powertrain" }, "type": "branch" }, { "branch": { "description": "Transmission-specific data, stopping at the drive shafts.", "fullyQualifiedName": "Vehicle.Powertrain.Transmission", "name": "Transmission" }, "type": "branch" }, { "sensor": { "dataType": "float", "description": "Vehicle_Odometer", "fullyQualifiedName": "Vehicle.Powertrain.Transmission.VehicleOdometer", "max": 67108863.984375, "min": 0, "name": "VehicleOdometer", "unit": "km" }, "type": "sensor"
23
AWS IoT FleetWise Developer Guide Import a signal catalog (AWS CLI)
}, {
"branch": { "description": "All data concerning steering, suspension, wheels, and
brakes.", "fullyQualifiedName": "Vehicle.Chassis", "name": "Chassis"
}, "type": "branch" }, { "branch": {
"description": "Steering wheel signals.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel", "name": "SteeringWheel" }, "type": "branch" }, { "attribute": { "dataType": "float", "description": "The diameter of the steering wheel.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel.Diameter", "max": 50, "min": 1, "name": "string", "unit": "cm" }, "type": "attribute" }, { "actuator": { "dataType": "boolean", "description": "Hands Off Steering State.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringState", "name": "HandsOffSteeringState" }, "type": "sensor" } ] }
Import a signal catalog (AWS CLI)
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 (p. 70).
You can use the ImportSignalCatalog API operation to upload a JSON file that helps create a signal catalog. You must follow the Vehicle Signal Specification (VSS) to save signals in the JSON file. The following example uses AWS CLI.
To import a signal catalog, run the following command.
· Replace signal-catalog-name with the name of the signal catalog that you're creating. · (Optional) Replace description with a description to help you identify the signal catalog.
24
AWS IoT FleetWise Developer Guide Import a signal catalog (AWS CLI)
· Replace signal-catalog-configuration-vss with the name of the JSON file that contains signals defined in VSS.
For more information about how to configure branches, attributes, sensors, and actuators, see Configure signals (p. 21).
aws iotfleetwise import-signal-catalog / --name signal-catalog-name / --description description / --vss-json file://signal-catalog-configuration-vss.json
{ "Vehicle": { "type": "branch", "children": { "Chassis": { "type": "branch", "description": "All data concerning steering, suspension, wheels, and
brakes.", "children": { "SteeringWheel": { "type": "branch", "description": "Steering wheel signals", "children": { "Diameter": { "type": "attribute", "description": "The diameter of the steering wheel", "datatype": "float", "unit": "cm", "min": 1, "max": 50 }, "HandsOff": { "type": "branch", "children": { "HandsOffSteeringState": { "type": "actuator", "description": "HndsOffStrWhlDtSt. Hands Off
Steering State", "datatype": "boolean"
}, "HandsOffSteeringMode": {
"type": "actuator", "description": "HndsOffStrWhlDtMd. Hands Off Steering Mode", "datatype": "int8", "min": 0, "max": 2 } } } } }, "Accelerator": { "type": "branch", "description": "", "children": { "AcceleratorPedalPosition": { "type": "sensor", "description": "Throttle__Position. Accelerator pedal position as percent. 0 = Not depressed. 100 = Fully depressed.", "datatype": "uint8",
25
AWS IoT FleetWise Developer Guide Import a signal catalog (AWS CLI)
"unit": "%", "min": 0, "max": 100.000035 } } } } }, "Powertrain": { "type": "branch", "description": "Powertrain data for battery management, etc.", "children": { "Transmission": { "type": "branch", "description": "Transmission-specific data, stopping at the drive shafts.", "children": { "VehicleOdometer": { "type": "sensor", "description": "Vehicle_Odometer", "datatype": "float", "unit": "km", "min": 0, "max": 67108863.984375 } } }, "CombustionEngine": { "type": "branch", "description": "Engine-specific data, stopping at the bell housing.", "children": { "Engine": { "type": "branch", "description": "Engine description", "children": {
"timing": { "type": "branch", "description": "timing description", "children": { "run_time": { "type": "sensor", "description": "Engine run time", "datatype": "int16", "unit": "ms", "min": 0, "max": 10000 }, "idle_time": { "type": "sensor", "description": "Engine idle time", "datatype": "int16", "min": 0, "unit": "ms", "max": 10000 } }
} } } } } } }, "Axle": { "type": "branch",
26
AWS IoT FleetWise Developer Guide Update a signal catalog (AWS CLI)
"description": "Axle signals", "children": {
"TireRRPrs": { "type": "sensor", "description": "TireRRPrs. Right rear Tire pressure in kilo-
Pascal", "datatype": "float", "unit": "kPaG", "min": 0, "max": 1020
} } } } } }
Update a signal catalog (AWS CLI)
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 (p. 70).
You can use the UpdateSignalCatalog API operation to update an existing signal catalog. The following example uses AWS CLI.
To update an existing signal catalog, run the following command.
Replace signal-catalog-configuration with the name of the JSON file that contains the configuration.
aws iotfleetwise update-signal-catalog --cli-input-json file://signal-catalogconfiguration.json
· Replace signal-catalog-name with the name of the signal catalog that you're updating. · (Optional) Replace description with a description to help you identify the signal catalog.
For more information about how to configure branches, attributes, sensors, and actuators, see Configure signals (p. 21).
{ "name": "signal-catalog-name", "description": "description", "nodesToAdd": [ { "branch": { "fullyQualifiedName": "Vehicle", "name": "Vehicle" }, "type": "branch" }, { "branch": {
27
AWS IoT FleetWise Developer Guide Update a signal catalog (AWS CLI)
"description": "Powertrain data for battery management.", "fullyQualifiedName": "Vehicle.Powertrain", "name": "Powertrain" }, "type": "branch" } ], "nodesToRemove": [ { "branch": { "description": "Transmission-specific data, stopping at the drive shafts.", "fullyQualifiedName": "Vehicle.Powertrain.Transmission", "name": "Transmission" }, "type": "branch" } ], "nodesToUpdate": [ { "sensor": { "dataType": "float", "description": "Vehicle_Odometer", "fullyQualifiedName": "Vehicle.Powertrain.Transmission.VehicleOdometer", "max": 67108863.984375, "min": 0, "name": "VehicleOdometer", "unit": "km" }, "type": "sensor" }, { "branch": { "description": "All data concerning steering, suspension, wheels, and brakes.", "fullyQualifiedName": "Vehicle.Chassis", "name": "Chassis" }, "type": "branch" }, { "branch": { "description": "Steering wheel signals.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel", "name": "SteeringWheel" }, "type": "branch" }, { "attribute": { "dataType": "float", "description": "The diameter of the steering wheel.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel.Diameter", "max": 50, "min": 1, "name": "string", "unit": "cm" }, "type": "attribute" }, { "actuator": { "dataType": "boolean", "description": "Hands Off Steering State.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringState", "name": "HandsOffSteeringState"
28
AWS IoT FleetWise Developer Guide Delete a signal catalog (AWS CLI)
}, "type": "sensor" } ] }
Delete a signal catalog (AWS CLI)
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 (p. 70).
You can use the DeleteSignalCatalog API operation to delete a signal catalog. The following example uses AWS CLI. To delete an exiting signal catalog, run the following command. Replace signal-catalog-name with the name of the signal catalog that you're deleting.
aws iotfleetwise delete-signal-catalog --name signal-catalog-name
Get signal catalog information (AWS CLI)
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 (p. 70).
You can use the ListSignalCatalogs API operation to verify if a signal catalog has been deleted. The following example uses AWS CLI. To retrieve a paginated list of summaries of all signal catalogs, run the following command.
aws iotfleetwise list-signal-catalogs
You can use the ListSignalCatalogNodes API operation to verify if a signal catalog has been updated. The following example uses AWS CLI. To retrieve a paginated list of summaries of all signals (nodes) in a given signal catalog, run the following command. Replace signal-catalog-name with the name of the signal catalog that you're checking.
aws iotfleetwise list-signal-catalog-nodes --name signal-catalog-name
You can use the GetSignalCatalog API operation to retrieve signal catalog information. The following example uses AWS CLI. To retrieve information about a signal catalog, run the following command.
29
AWS IoT FleetWise Developer Guide Vehicle models
Replace signal-catalog-name with the name of the signal catalog that you want to retrieve.
aws iotfleetwise get-signal-catalog --name signal-catalog-name
Create and manage vehicle models
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 (p. 70).
You use signals to create vehicle models that help standardize the format of your vehicles. Vehicle models enforce consistent information across multiple vehicles of the same type, so that you can process data from fleets of vehicles. Vehicles created from the same vehicle model inherit the same group of signals. For more information, see Create, provision, and manage vehicles (p. 47). Each vehicle model has a status field that contains the state of the vehicle model. The state can be one of the following values: · ACTIVE The vehicle model is active. · DRAFT The configuration of the vehicle model is saved.
Important · If you want to use the CreateModelManifest API operation to create the first vehicle
model, you must create a signal catalog first. For more information, see Create a signal catalog (AWS CLI) (p. 22). · If you use the AWS IoT FleetWise console to create a vehicle model, AWS IoT FleetWise automatically activates the vehicle model for you. · If you use the CreateModelManifest API operation to create a vehicle model, the vehicle model stays in the DRAFT state. · You can't create vehicles from vehicle models that are in the DRAFT state. Use the UpdateModelManifest API operation to change vehicle models to the ACTIVE state. · You can't edit vehicle models that are in the ACTIVE state.
Topics · Create a vehicle model (p. 30) · Update a vehicle model (AWS CLI) (p. 36) · Delete a vehicle model (p. 37) · Get vehicle model information (AWS CLI) (p. 38)
Create a vehicle model
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.
30
AWS IoT FleetWise Developer Guide Create a vehicle model
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 (p. 70).
You can use the AWS IoT FleetWise console or API to create vehicle models. Important You must have a signal catalog before you can create a vehicle model by using the CreateModelManifest API operation.
Topics · Create a vehicle model (console) (p. 31) · Create vehicle models (AWS CLI) (p. 34)
Create a vehicle model (console)
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 (p. 70).
In the AWS IoT FleetWise console, you can create a vehicle model in the following ways: · Use a template provided by AWS (p. 31) · Manually create a vehicle model (p. 31) · Duplicate a vehicle model (p. 34)
Use a template provided by AWS
AWS IoT FleetWise provides an On-board Diagnostics (OBD) II, J1979 template that automatically creates a signal catalog, a vehicle model, and a decoder manifest for you. The template also adds OBD network interfaces to the decoder manifest. For more information, see Create and manage decoder manifests (p. 38).
To create a vehicle model by using a template 1. Navigate to the AWS IoT FleetWise console. 2. On the navigation pane, choose Vehicle models. 3. On the Vehicle models page, choose Add provided template. 4. Choose On-board diagnostics (OBD) II. 5. Enter a name for the OBD network interface that AWS IoT FleetWise is creating. 6. Choose Add.
Manually create a vehicle model
You can add signals from the signal catalog or import signals by uploading one or more .dbc files. .dbc is a file format that Controller Area Network (CAN bus) databases support.
31
AWS IoT FleetWise Developer Guide Create a vehicle model
To manually create a vehicle model 1. Navigate to the AWS IoT FleetWise console. 2. On the navigation pane, choose Vehicle models. 3. On the Vehicle models page, choose Create vehicle model, and then do the following.
Topics · Step 1: Configure vehicle model (p. 32) · Step 2: Add signals (p. 32) · Step 3: Import signals (p. 32) · (Optional) Step 4: Add attributes (p. 33) · Step 5: Review and create (p. 34)
Step 1: Configure vehicle model
In General information, do the following. 1. Enter a name for the vehicle model. 2. (Optional) Enter a description. 3. Choose Next.
Step 2: Add signals Note · If this is the first time you've used AWS IoT FleetWise, this step isn't available until you have a signal catalog. When the first vehicle model is created, AWS IoT FleetWise automatically creates a signal catalog with signals added to the first vehicle model. · If you're experienced with AWS IoT FleetWise, you can add signals to your vehicle model by selecting signals from the signal catalog or uploading .dbc files to import signals. · You must have at least one signal to create a vehicle model.
To add signals 1. Choose one or more signals from the signal catalog that you're adding to the vehicle model. You can
review selected signals in the right pane. Note Only selected signals will be added to the vehicle model.
2. Choose Next.
Step 3: Import signals Note · If this is the first time you've used AWS IoT FleetWise, you must upload at least one .dbc file to import signals. · If you're experienced with AWS IoT FleetWise, you can add signals to your vehicle model by selecting signals from the signal catalog or uploading .dbc files to import signals. · You must have at least one signal to create a vehicle model.
32
AWS IoT FleetWise Developer Guide Create a vehicle model
To import signals
1. Choose Choose files. 2. In the dialog box, choose the .dbc file that contains signals. You can upload multiple .dbc files. 3. AWS IoT FleetWise parses your .dbc files to retrieve signals.
In the Signals section, specify the following metadata for each signal.
· Name The signal's name.
The signal name must be unique. The signal name plus the path can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). · Data type The signal's data type must be one of the following: INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, BOOLEAN, FLOAT, DOUBLE, STRING, UNIX_TIMESTAMP, INT8_ARRAY, UINT8_ARRAY, INT16_ARRAY, UINT16_ARRAY, INT32_ARRAY, UINT32_ARRAY, INT64_ARRAY, UINT64_ARRAY, BOOLEAN_ARRAY, FLOAT_ARRAY, DOUBLE_ARRAY, STRING_ARRAY, UNIX_TIMESTAMP_ARRAY, or UNKNOWN. · Signal type The type of the signal, which can be Sensor or Actuator. · (Optional) Unit The scientific unit for the signal, such as km or Celsius. · (Optional) Path The path to the signal. Similar to JSONPath, use a dot(.) to refer to a child signal. For example, Vehicle.Engine.Light.
The signal name plus the path can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore). · (Optional) Min The minimum value of the signal. · (Optional) Max The maximum value of the signal. · (Optional) Description The description for the signal.
The description can have up to 2048 characters. Valid characters: a-z, A-Z, 0-9, : (colon), _ (underscore), and - (hyphen) 4. Choose Next.
(Optional) Step 4: Add attributes
You can add up to 100 attributes, including the existing attributes in the signal catalog.
To add attributes
1. In Add attributes, specify the following metadata for each attribute.
· Name The attribute's name.
The signal name must be unique. The signal name and path can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore) · Data type The attribute's data type must be one of the following: INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, BOOLEAN, FLOAT, DOUBLE, STRING, UNIX_TIMESTAMP, INT8_ARRAY, UINT8_ARRAY, INT16_ARRAY, UINT16_ARRAY, INT32_ARRAY, UINT32_ARRAY, INT64_ARRAY, UINT64_ARRAY, BOOLEAN_ARRAY, FLOAT_ARRAY, DOUBLE_ARRAY, STRING_ARRAY, UNIX_TIMESTAMP_ARRAY, or UNKNOWN · (Optional) Unit The scientific unit for the attribute, such as km or Celsius. · (Optional) Path The path to the signal. Similar to JSONPath, use a dot(.) to refer to a child signal. For example, Vehicle.Engine.Light.
The signal name plus the path can have up to 150 characters. Valid characters: a-z, A-Z, 0-9, : (colon), and _ (underscore)
33
AWS IoT FleetWise Developer Guide Create a vehicle model
· (Optional) Min The minimum value of the attribute. · (Optional) Max The maximum value of the attribute. · (Optional) Description The description for the attribute.
The description can have up to 2048 characters. Valid characters: a-z, A-Z, 0-9, : (colon), _ (underscore), and - (hyphen) 2. Choose Next.
Step 5: Review and create Verify the configurations for the vehicle model, and then choose Create.
Duplicate a vehicle model
AWS IoT FleetWise can copy the configurations of an existing vehicle model to create a new model. Signals specified in the selected vehicle model are copied to the new vehicle model.
To duplicate a vehicle model 1. Navigate to the AWS IoT FleetWise console. 2. On the navigation pane, choose Vehicle models. 3. Choose a model from the vehicle model list, and then choose Duplicate model.
To configure the vehicle model, follow the Manually create a vehicle model (p. 31) tutorial. It can take a few minutes for AWS IoT FleetWise to process your request to create the vehicle model. After the vehicle model is successfully created, on the Vehicle models page, the Status column shows ACTIVE. When the vehicle model becomes active, you can't edit it.
Create vehicle models (AWS CLI)
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 (p. 70).
You can use the CreateModelManifest API operation to create vehicle models (model manifests). The following example uses the AWS CLI.
Important If you want to use the AWS IoT FleetWise API to create the first vehicle model, you must create a signal catalog first. For more information about how to create a signal catalog, see Create a signal catalog (AWS CLI) (p. 22). To create a vehicle model, run the following command. Replace vehicle-model-configuration with the name of the JSON file that contains the configuration.
aws iotfleetwise create-model-manifest --cli-input-json file://vehicle-modelconfiguration.json
34
AWS IoT FleetWise Developer Guide Create a vehicle model
· Replace vehicle-model-name with the name of the vehicle model that you're creating.
· Replace signal-catalog-ARN with the Amazon Resource Name (ARN) of the signal catalog.
· (Optional) Replace description with a description to help you identify the vehicle model.
For more information about how to configure branches, attributes, sensors, and actuators, see Configure signals (p. 21).
{ "name": "vehicle-model-name", "signalCatalogArn": "signal-catalog-ARN", "description": "description", "nodes": [ ... { "branch": { "fullyQualifiedName": "Vehicle", "name": "Vehicle" }, "type": "branch" }, { "branch": { "description": "Powertrain data for battery management.", "fullyQualifiedName": "Vehicle.Powertrain", "name": "Powertrain" }, "type": "branch" }, { "branch": { "description": "Transmission-specific data, stopping at the drive shafts.", "fullyQualifiedName": "Vehicle.Powertrain.Transmission", "name": "Transmission" }, "type": "branch" }, { "sensor": { "dataType": "float", "description": "Vehicle_Odometer", "fullyQualifiedName": "Vehicle.Powertrain.Transmission.VehicleOdometer", "max": 67108863.984375, "min": 0, "name": "VehicleOdometer", "unit": "km" }, "type": "sensor" }, { "branch": { "description": "All data concerning steering, suspension, wheels, and
brakes.", "fullyQualifiedName": "Vehicle.Chassis", "name": "Chassis"
}, "type": "branch" }, { "branch": {
"description": "Steering wheel signals.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel", "name": "SteeringWheel" },
35
AWS IoT FleetWise Developer Guide Update a vehicle model (AWS CLI)
"type": "branch" }, {
"attribute": { "dataType": "float", "description": "The diameter of the steering wheel.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel.Diameter", "max": 50, "min": 1, "name": "string", "unit": "cm"
}, "type": "attribute" }, { "actuator": {
"dataType": "boolean", "description": "Hands Off Steering State.", "fullyQualifiedName": "Vehicle.Chassis.SteeringWheel.HandsOff.HandsOffSteeringState", "name": "HandsOffSteeringState" }, "type": "sensor" } ] }
Update a vehicle model (AWS CLI)
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 (p. 70).
You can use the UpdateModelManifest API operation to update an existing vehicle model (model manifests). The following example uses the AWS CLI.
To update an existing vehicle model, run the following command.
Replace vehicel-model-configuration with the name of the JSON file that contains the configuration.
aws iotfleetwise update-model-manifest --cli-input-json file://vehicle-modelconfiguration.json
· Replace vehicle-model-status with the name of the vehicle model that you're updating. · (Optional) To activate the vehicle model, replace vehicle-model-status with ACTIVE.
Important After the vehicle model is activated, you can't change the vehicle model. · (Optional) Replace description with a description to help you identify the signal catalog.
For more information about how to configure branches, attributes, sensors, and actuators, see Configure signals (p. 21).
36
AWS IoT FleetWise Developer Guide Delete a vehicle model
{ "name": "vehicle-model-name", "status": "vehicle-model-status" "description": "description", "nodesToAdd": [ { "branch": { "fullyQualifiedName": "Vehicle", "name": "Vehicle" }, "type": "branch" }, { "branch": { "description": "Powertrain data for battery management.", "fullyQualifiedName": "Vehicle.Powertrain", "name": "Powertrain" }, "type": "branch" } ], "nodesToRemove": [ { "branch": { "description": "Transmission-specific data, stopping at the drive shafts.", "fullyQualifiedName": "Vehicle.Powertrain.Transmission", "name": "Transmission" }, "type": "branch" } ]
}
Delete a vehicle model
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 (p. 70).
You can use the AWS IoT FleetWise console or API to delete vehicle models. Important Vehicles and decoder manifests associated with the vehicle model must be deleted first. For more information, see Delete a vehicle (AWS CLI) (p. 55) and Delete a decoder manifest (p. 45).
Delete a vehicle model (console)
To delete a vehicle model, use the AWS IoT FleetWise console.
To delete a vehicle model
1. Navigate to the AWS IoT FleetWise console. 2. On the navigation pane, choose Vehicle models. 3. On the Vehicle models page, choose the target vehicle model.
37
AWS IoT FleetWise Developer Guide Get vehicle model information (AWS CLI)
4. Choose Delete. 5. In Delete vehicle-model-name?, enter the name of the vehicle model to delete, and then choose
Confirm.
Delete a vehicle model (AWS CLI)
You can use the DeleteModelManifest API operation to delete an existing vehicle model (model manifests). The following example uses the AWS CLI. To delete a vehicle model, run the following command. Replace model-manifest-name with the name of the vehicle model that you're deleting.
aws iotfleetwise delete-model-manifest --name model-manifest-name
Get vehicle model information (AWS CLI)
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 (p. 70).
You can use the ListModelManifests API operation to verify if a vehicle model has been deleted. The following example uses AWS CLI. To retrieve a paginated list of summaries of all vehicle models, run the following command.
aws iotfleetwise list-model-manifests
You can use the ListModelManifestNodes API operation to verify if a vehicle model has been updated. The following example uses AWS CLI. To retrieve a paginated list of summaries of all signals (nodes) in a given vehicle model, run the following command. Replace vehicle-model-name with the name of the vehicle model that you're checking.
aws iotfleetwise list-model-manifest-nodes / --name vehicle-model-name
To retrieve information about a vehicle model, run the following command. Replace vehicle-model with the name of the vehicle model that you want to retrieve.
aws iotfleetwise get-model-manifest --name vehicle-model
Create and manage decoder manifests
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.
38
AWS IoT FleetWise Developer Guide Decoder manifests
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 (p. 70).
Decoder manifests contain decoding information that AWS IoT FleetWise uses to transform vehicle data (binary data) into human-readable values and to prepare your data for data analyses. Network interface and decoder signals are the core components that you work with to configure decoder manifests.
Network interface
Contains information about the protocol that the in-vehicle network uses. AWS IoT FleetWise supports the following protocols. Controller Area Network (CAN bus)
A protocol that defines how data is communicated between electronic control units (ECUs). ECUs can be the engine control unit, airbags, or the audio system. On-board diagnostic (OBD) II
A further developed protocol that defines how self-diagnostic data is communicated between ECUs. It provides a number of standard diagnostic trouble codes (DTCs) that help identify what is wrong with your vehicle. Decoder signal
Provides detailed decoding information for a specific signal. Every signal specified in the vehicle model must be paired with a decoder signal. If the decoder manifest contains CAN network interfaces, it must contain CAN decoder signals. If the decoder manifest contains OBD network interfaces, it must contain OBD decoder signals.
Each decoder manifest must be associated with a vehicle model. AWS IoT FleetWise uses the associated decoder manifest to decode data from vehicles created based on the vehicle model.
Each decoder manifest has a status field that contains the state of the decoder manifest. The state can be one of the following values:
· ACTIVE The decoder manifest is active. · DRAFT The configuration of the decoder manifest is saved.
Important
· If you use the AWS IoT FleetWise console to create a decoder manifest, AWS IoT FleetWise automatically activates the decoder manifest for you.
· If you use the CreateDecoderManifest API operation to create a decoder manifest, the decoder manifest stays in the DRAFT state.
· You can't create vehicles from vehicle models that are associated with a DRAFT decoder manifest. Use the UpdateDecoderManifest API operation to change the decoder manifest to the ACTIVE state.
· You can't edit decoder manifests that are in the ACTIVE state.
Topics · Configure network interfaces and decoder signals (p. 40) · Create a decoder manifest (p. 41) · Update a decoder manifest (AWS CLI) (p. 44)
39
AWS IoT FleetWise Developer Guide Configure network interfaces and decoder signals
· Delete a decoder manifest (p. 45) · Get decoder manifest information (AWS CLI) (p. 46)
Configure network interfaces and decoder signals
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 (p. 70).
Every decoder manifest has at least a network interface and decoder signals paired with signals specified in the associated vehicle model.
If the decoder manifest contains CAN network interfaces, it must contain CAN decoder signals. If the decoder manifest contains OBD network interfaces, it must contain OBD decoder signals. Topics
· Configure network interfaces (p. 40) · Configure decoder signals (p. 41)
Configure network interfaces
To configure a CAN network interface, specify the following information. · canInterfaceName The CAN interface's name.
The interface name must be unique and can have 1-100 characters. · (Optional) protocolName The protocol's name.
Valid values: CAN · (Optional) protocolVersion AWS IoT FleetWise currently supports CAN 2.0b.
Valid values: 2.0b
To configure an OBD network interface, specify the following information. · obdInterfaceName The OBD interface's name.
The interface name must be unique and can have 1-100 characters. · requestMessageId The ID of the message that is requesting data. · (Optional) dtcRequestIntervalSeconds How often to request diagnostic trouble codes (DTCs)
from the vehicle in seconds. For example, if the specified value is 120, the Edge Agent software collects stored DTCs once every 2 minutes. · (Optional) hasTransmissionEcu Whether the vehicle has a transmission control module (TCM). Valid values: true and false · (Optional) obdStandard The OBD standard that AWS IoT FleetWise supports. AWS IoT FleetWise currently supports the World Wide Harmonization On-Board Diagnostics (WWH-OBD) ISO15765-4 standard.
40
AWS IoT FleetWise Developer Guide Create a decoder manifest
· (Optional) pidRequestIntervalSeconds How often to request OBD II PIDs from the vehicle. For example, if the specified value is 120, the Edge Agent software collects OBD II PIDs once every 2 minutes.
· (Optional) useExtendedIds Whether to use extended IDs in the message.
Valid values: true and false
Configure decoder signals
To configure a CAN decoder signal, specify the following information.
· factor The multiplier used to decode the message. · isBigEndian Whether the byte ordering of the message is big-endian. If it's big-endian, the most
significant value in the sequence is stored first, at the lowest storage address. · isSigned Whether the message is signed. If it's signed, the message can represent both positive and
negative numbers. · length The length of the message in bytes. · messageId The ID of the message. · offset Indicates the location of the message. · startBit Indicates the location of the first bit of the message. · (Optional) canSignalName The name of the signal.
To configure an OBD decoder signal, specify the following information.
· byteLength The length of the message in bytes. · offset Indicates the location of the message. · pid The diagnostic code used to request a message from a vehicle for this signal. · pidResponseLength The length of the requested message. · scaling The multiplier used to decode the message. · serviceMode The mode of operation (diagnostic service) in a message. · startByte Indicates the beginning of the message. · (Optional) bitMaskLength The number of bits that are masked in a message. · (Optional) bitRightShift The number of positions shifted to the right.
Create a decoder manifest
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 (p. 70).
You can use the AWS IoT FleetWise console or API to create a decoder manifest for your vehicle model. Important You must have a vehicle model before you can create a decoder manifest. Every decoder manifest must be associated with a vehicle model. For more information, see Create and manage vehicle models (p. 30).
41
AWS IoT FleetWise Developer Guide Create a decoder manifest
Topics · Create a decoder manifest (console) (p. 42) · Create a decoder manifest (AWS CLI) (p. 43)
Create a decoder manifest (console)
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 (p. 70).
You can use the AWS IoT FleetWise console to create a decoder manifest associated with your vehicle model. To create a decoder manifest 1. Navigate to the AWS IoT FleetWise console. 2. On the navigation pane, choose Vehicle models. 3. Choose the target vehicle model. 4. On the vehicle model summary page, choose Create decoder manifest, and then do the following.
Topics · Step 1: Configure decoder manifest (p. 42) · Step 2: Add network interfaces (p. 42) · Step 4: Review and create (p. 43)
Step 1: Configure decoder manifest
In General information, do the following. 1. Enter a unique name for the decoder manifest. 2. (Optional) Enter a description. 3. Choose Next.
Step 2: Add network interfaces
Each decoder manifest must have at least one network interface. You can add multiple network interfaces to a decoder manifest. To add a network interface · In Network interface, do the following.
a. For Network interface type, choose the CAN_INTERFACE or OBD_INTERFACE. b. Enter a unique name for your network interface. c. Enter a unique network interface ID. You can use the ID generated by AWS IoT FleetWise. d. Select one or more signals specified in your vehicle model to pair with decoder signals.
42
AWS IoT FleetWise Developer Guide Create a decoder manifest
e. To provide decording information, upload a .dbc file. AWS IoT FleetWise parses the .dbc file to retrieve decoder signals.
f. In the Paired signals section, make sure that every signal is paired with a decoder signal. g. Choose Next.
Note
· You can upload only one .dbc file for each network interface. · Make sure that every signal specified in your vehicle model is paired with a decoder signal. · After you choose to add another network interface, you can't edit the one that you're editing.
You can delete any existing network interfaces.
Step 4: Review and create
Verify the configurations for the decoder manifest, and then choose Create.
Create a decoder manifest (AWS CLI)
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 (p. 70).
You can use the CreateDecoderManifest API operation to create decoder manifests. The following example uses the AWS CLI.
Important Before you create a decoder manifest, create a vehicle model first. For more information, see Create a vehicle model (p. 30). To create a decoder manifest, run the following command. Replace decoder-manifest-configuration with the name of the JSON file that contains the configuration.
aws iotfleetwise create-decoder-manifest --cli-input-json file://decoder-manifestconfiguration.json
· Replace decoder-manifest-name with the name of the decoder manifest that you're creating. · Replace vehicle-model-ARN with the Amazon Resource Name (ARN) of the vehicle-model. · (Optional) Replace description with a description to help you identify the decoder manifest.
For more information about how to configure branches, attributes, sensors, and actuators, see Configure network interfaces and decoder signals (p. 40).
{ "name": "decoder-manifest-name", "modelManifestArn": "vehicle-model-arn", "description": "description", "networkInterfaces": [
43
AWS IoT FleetWise Developer Guide Update a decoder manifest (AWS CLI)
{ "canInterface": { "canInterfaceName": "myNetworkInterface", "protocolName": "CAN", "protocolVersion": "2.0b" }, "interfaceId": "Qq1acaenByOB3sSM39SYm", "type": "CAN_INTERFACE"
} ], "signalDecoders": [
{ "canSignal": { "canSignalName": "Engine_Idle_Time", "factor": 1, "isBigEndian": true, "isSigned": false, "length": 24, "messageId": 271343712, "offset": 0, "startBit": 16 }, "fullyQualifiedName": "Engine_Idle_Time", "interfaceId": "Qq1acaenByOB3sSM39SYm", "type": "CAN_SIGNAL"
}, {
"canSignal": { "canSignalName": "Engine_Run_Time", "factor": 1, "isBigEndian": true, "isSigned": false, "length": 24, "messageId": 271343712, "offset": 0, "startBit": 40
}, "fullyQualifiedName": "Engine_Run_Time", "interfaceId": "Qq1acaenByOB3sSM39SYm", "type": "CAN_SIGNAL" } ] }
Update a decoder manifest (AWS CLI)
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 (p. 70).
You can use the UpdateDecoderManifest API operation to update a decoder manifest. You can add, remove, and update network interfaces and signal decoders. You can also change the status of the decoder manifest. The following example uses the AWS CLI.
To update a decoder manifest, run the following command.
Replace decoder-manifest-name with the name of the decoder manifest that you're updating.
44
AWS IoT FleetWise Developer Guide Delete a decoder manifest
aws iotfleetwise update-decoder-manifest / --name decoder-manifest-name / --status ACTIVTE
Important After you activate the decoder manifest, you can't edit it.
Delete a decoder manifest
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 (p. 70).
You can use the AWS IoT FleetWise console or API to delete a decoder manifest. Important Vehicles associated with the decoder manifest must be deleted first. For more information, see Delete a vehicle (AWS CLI) (p. 55).
Topics · Delete a decoder manifest (console) (p. 45) · Delete a decoder manifest (AWS CLI) (p. 45)
Delete a decoder manifest (console)
You can use the AWS IoT FleetWise console to delete a decoder manifest.
To delete a decoder manifest
1. Navigate to the AWS IoT FleetWise console. 2. On the navigation pane, choose Vehicle models. 3. Choose the target vehicle model. 4. On the vehicle model summary page, choose the Decoder manifests tab. 5. Choose the target decoder manifest, and then choose Delete. 6. In Delete decoder-manifest-name?, enter the name of the decoder manifest to delete, and then
choose Confirm.
Delete a decoder manifest (AWS CLI)
You can use the DeleteDecoderManifest API operation to delete a decoder manifest. The following example uses AWS CLI.
Important Before you delete the decoder manifest, delete the associated vehicles first. For more information, see Delete a vehicle (AWS CLI) (p. 55).
To delete a decoder manifest, run the following command.
Replace decoder-manifest-name with the name of the decoder manifest that you're deleting.
45
AWS IoT FleetWise Developer Guide Get decoder manifest information (AWS CLI)
aws iotfleetwise delete-decoder-manifest --name decoder-manifest-name
Get decoder manifest information (AWS CLI)
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 (p. 70).
You can use the ListDecoderManifests API operation to verify if a decoder manifest has been deleted. The following example uses AWS CLI. To retrieve a paginated list of summaries of all decoder manifests, run the following command.
aws iotfleetwise list-decoder-manifests
You can use the ListDecoderManifestSignals API operation to verify if decoder signals in the decoder manifest have been updated. The following example uses AWS CLI. To retrieve a paginated list of summaries of all decoder signals (nodes) in a given decoder manifest, run the following command. Replace decoder-manifest-name with the name of the decoder manifest that you're checking.
aws iotfleetwise list-decoder-manifest-signals / --name decoder-manifest-name
You can use the ListDecoderManifestNetworkInterfaces API operation to verify if network interfaces in the decoder manifest have been updated. The following example uses AWS CLI. To retrieve a paginated list of summaries of all network interfaces in a given decoder manifest, run the following command. Replace decoder-manifest-name with the name of the decoder manifest that you're checking.
aws iotfleetwise list-decoder-manifest-network-interfaces / --name decoder-manifest-name
You can use the GetDecoderManifest API operation to verify if network interfaces and decoder signals in the decoder manifest have been updated. The following example uses AWS CLI. To retrieve information about a decoder manifest, run the following command. Replace decoder-manifest with the name of the decoder manifest that you want to retrieve.
aws iotfleetwise get-decoder-manifest --name decoder-manifest
46
AWS IoT FleetWise Developer Guide
Create, provision, and manage vehicles
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 (p. 70).
Vehicles are instances of vehicle models. Vehicles must be created from a vehicle model and associated with a decoder manifest. Vehicles uploads one or more data streams to the cloud. For example, a vehicle can send mileage, engine temperature, and state of heater data to the cloud. Every vehicle contains the following information:
vehicleId An ID that identifies the vehicle.
modelManifestARN The Amazon Resource Name (ARN) of a vehicle model (model manifest). Every vehicle is created from a vehicle model. Vehicles created from the same vehicle model consist of the same group of signals inherited from the vehicle model. These signals are defined and standardized in the signal catalog.
decoderManifestArn The ARN of the decoder manifest. A decoder manifest provides decoding information that AWS IoT FleetWise can use to transform raw signal data (binary data) into human-readable values. A decoder manifest must be associated with a vehicle model. AWS IoT FleetWise uses the same decoder manifest to decode raw data from vehicles created based on the same vehicle model.
attributes Attributes are key-value pairs that contain static information. Vehicles can contain attributes inherited from the vehicle model. You can add additional attributes to distinguish an individual vehicle from other vehicles created from the same vehicle model. For example, if you have a black car, you can specify the following value for an attribute: {"color": "black"}. Important Attributes must be defined in the associated vehicle model before you can add them to individual vehicles.
For more information about vehicle models, decoder manifests, and attributes, see Modeling vehicles (p. 18).
AWS IoT FleetWise provides the following API operations that you can use to create and manage vehicles.
· CreateVehicle Creates a new vehicle.
47
AWS IoT FleetWise Developer Guide Provision vehicles
· BatchCreateVehicle Creates one or more new vehicles. · UpdateVehicle Updates an existing vehicle. · BatchUpdateVehicle Updates one or more existing vehicles. · DeleteVehicle Deletes an existing vehicle. · ListVehicles Retrieves a paginated list of summaries of all vehicles. · GetVehicle Retrieves information about a vehicle.
Tutorials · Provision vehicles (p. 48) · Create a vehicle (AWS CLI) (p. 51) · Create multiple vehicles (AWS CLI) (p. 52) · Update a vehicle (AWS CLI) (p. 53) · Update multiple vehicles (AWS CLI) (p. 54) · Delete a vehicle (AWS CLI) (p. 55) · Get vehicle information (AWS CLI) (p. 56)
Provision vehicles
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 (p. 70).
The AWS IoT FleetWise Edge Agent software running in your vehicle collects and transfers data to the cloud. AWS IoT FleetWise integrates with AWS IoT Core to support secure communication between the Edge Agent software and the cloud through MQTT. Each vehicle corresponds to an AWS IoT thing. You can use an existing AWS IoT thing to create a vehicle or set AWS IoT FleetWise to automatically create an AWS IoT thing for your vehicle. For more information, see Create a vehicle (AWS CLI) (p. 51).
The following topics are reserved for use by AWS IoT FleetWise. You can subscribe and publish to reserved topics as they allow. However, you can't create new topics that begin with a dollar sign ($). Unsupported publish or subscribe operations to reserved topics can result in a terminated connection.
Topic
Client operation allowed
$aws/iotfleetwise/ Publish vehicles/ vehicleId/checkins
$aws/iotfleetwise/ Publish vehicles/ vehicleId/signals
Description
The AWS IoT FleetWise Edge Agent software publishes vehicle status information to this topic.
The AWS IoT FleetWise Edge Agent software publishes signals to this topic.
48
AWS IoT FleetWise Developer Guide Authenticate vehicles
Topic
Client operation allowed
$aws/iotfleetwise/ vehicles/ vehicleId/ collection_schemes
Subscribe
$aws/iotfleetwise/ vehicles/ vehicleId/ decoder_manifests
Subscribe
Description
AWS IoT FleetWise publishes data collection schemes to this topic. Vehicles consume these data collection schemes.
AWS IoT FleetWise publishes decoder manifests to this topic. Vehicles consume these decoder manifests.
AWS IoT Core supports authentication and authorization that help securely control access to AWS IoT FleetWise resources. Vehicles can use X.509 certificates to get authenticated (signed in) to use AWS IoT FleetWise and AWS IoT Core polices to get authorized (have permissions) to perform specified actions.
Authenticate vehicles
You can create AWS IoT Core policies to authenticate your vehicles.
To authenticate your vehicle
· To create an AWS IoT Core policy, run the following command.
· Replace policy-name with the name of the policy you want to create. · Replace file-name with the name of the JSON file that contains the AWS IoT Core policy.
aws iot create-policy --policy-name policy-name --policy-document file://filename.json
Before you use the example policy, do the following: · Replace region with the AWS Region where you created AWS IoT FleetWise resources. · Replace awsAccount with your AWS account ID.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": [ "arn:aws:iot:region:awsAccount:client/
${iot:Connection.Thing.ThingName}" ]
}, {
"Effect": "Allow", "Action": [
49
AWS IoT FleetWise Developer Guide Authorize vehicles
"iot:Publish" ], "Resource": [
"arn:aws:iot:region:awsAccount:topic/$aws/iotfleetwise/vehicles/ ${iot:Connection.Thing.ThingName}/checkins",
"arn:aws:iot:region:awsAccount:topic/$aws/iotfleetwise/vehicles/ ${iot:Connection.Thing.ThingName}/signals"
] }, {
"Effect": "Allow", "Action": [
"iot:Subscribe" ], "Resource": [
"arn:aws:iot:region:awsAccount:topicfilter/$aws/iotfleetwise/vehicles/ ${iot:Connection.Thing.ThingName}/collection_schemes",
"arn:aws:iot:region:awsAccount:topicfilter/$aws/iotfleetwise/vehicles/ ${iot:Connection.Thing.ThingName}/decoder_manifests"
] }, {
"Effect": "Allow", "Action": [
"iot:Receive" ], "Resource": [
"arn:aws:iot:region:awsAccount:topic/$aws/iotfleetwise/vehicles/ ${iot:Connection.Thing.ThingName}/collection_schemes",
"arn:aws:iot:region:awsAccount:topic/$aws/iotfleetwise/vehicles/ ${iot:Connection.Thing.ThingName}/decoder_manifests"
] } ] }
Authorize vehicles
You can create X.509 certificates to authorize your vehicles.
To authorize your vehicle
Important We recommend that you create a new certificate for each vehicle.
1. To create an RSA key pair and issue an X.509 certificate, run the following command.
· Replace cert with the name of the file that saves the command output contents of certificatePem.
· Replace public-key with the name of the file that saves the command output contents of keyPair.PublicKey.
· Replace private-key with the name of the file that saves the command output contents of keyPair.PrivateKey.
aws iot create-keys-and-certificate \ --set-as-active \ --certificate-pem-outfile cert.pem \ --public-key-outfile public-key.key" \ --private-key-outfile private-key.key"
50
AWS IoT FleetWise Developer Guide Create a vehicle (AWS CLI)
2. Copy the Amazon Resource Name (ARN) of the certificate from the output. 3. To attach the policy to the certificate, run the following command.
· Replace policy-name with the name of the AWS IoT Core policy that you created. · Replace certificate-arn with the ARN of the certificate that you copied.
aws iot attach-policy \ --policy-name policy-name\ --target "certificate-arn"
4. To attach the certificate to the thing, run the following command. · Replace thing-name with the name of your AWS IoT thing or the ID of your vehicle. · Replace certificate-arn with the ARN of the certificate that you copied.
aws iot attach-thing-principal \ --thing-name thing-name \ --principal "certificate-arn"
Create a vehicle (AWS CLI)
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 (p. 70).
When you create a vehicle, you must use a vehicle model that is associated with a decoder manifest. You can use the CreateVehicle API operation to create a vehicle. The following example uses the AWS CLI.
Important Before you start, check the following: · You must have a vehicle model and the status of the vehicle model must be ACTIVE. For more
information, see Create and manage vehicle models (p. 30). · Your vehicle model must be associated with a decoder manifest, and the status of the
decoder manifest must be ACTIVE. For more information, see Create and manage decoder manifests (p. 38).
To create a vehicle, run the following command. Replace file-name with the name of the JSON file that contains the vehicle configuration.
aws iotfleetwise create-vehicle --cli-input-json file://file-name.json
Example vehicle configuration · (Optional) The associationBehavior value can be one of the following:
· CreateIotThing When your vehicle is created, AWS IoT FleetWise automatically creates an AWS IoT thing with the name of your vehicle ID for your vehicle.
51
AWS IoT FleetWise Developer Guide Create multiple vehicles (AWS CLI)
· ValidateIotThingExists Use an existing AWS IoT thing to create a vehicle.
To create an AWS IoT thing, run the following command. Replace thing-name with the name of the thing you want to create.
aws iot create-thing --thing-name thing-name
If it's not specified, AWS IoT FleetWise automatically creates an AWS IoT thing for your vehicle. Important Make sure that the AWS IoT thing is provisioned after the vehicle is created. For more information, see Provision vehicles (p. 48).
· Replace vehicle-ID with one of the following. · The name of your AWS IoT thing if associationBehavior is configured to ValidateIotThingExists. · The ID of the vehicle to create if associationBehavior is configured to CreateIotThing.
The vehicle ID can have 1100 characters. Valid characters: az, AZ, 09, dash (-), underscore(_), and colon (:). · Replace model-manifest-ARN with the ARN of your vehicle model (model manifest). · Replace decoder-manifest-ARN with the ARN of the decoder manifest associated with the specified vehicle model. · (Optional) You can add additional attributes to distinguish this vehicle from other vehicles created from the same vehicle model. For example, if you have an electric car, you can specify the following value for an attribute: {"fuelType": "electric"}.
Important Attributes must be defined in the associated vehicle model before you can add them to individual vehicles.
{ "associationBehavior": "associationBehavior", "vehicleId": "vehicle-ID", "modelManifestArn": "model-manifest-ARN", "decoderManifestArn": "decoder-manifest-ARN", "attributes": { ... "key": "value" }
}
Create multiple vehicles (AWS CLI)
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 (p. 70).
You can use the BatchCreateVehicle API operation to create multiple vehicles at one time. The following example uses the AWS CLI.
52
AWS IoT FleetWise Developer Guide Update a vehicle (AWS CLI)
To create multiple vehicles, run the following command.
Replace file-name with the name of the JSON file that contains the configurations of multiple vehicles.
aws iotfleetwise batch-create-vehicle --cli-input-json file://file-name.json
Example vehicle configurations
{ "vehicles": [ ... { "associationBehavior": "associationBehavior", "vehicleId": "vehicle-ID", "modelManifestArn": "model-manifest-ARN", "decoderManifestArn": "decoder-manifest-ARN", "attributes": { ... "key": "value" } }, { "associationBehavior": "associationBehavior", "vehicleId": "vehicle-ID", "modelManifestArn": "model-manifest-ARN", "decoderManifestArn": "decoder-manifest-ARN", "attributes": { ... "key": "value" } } ]
}
You can create up to 10 vehicles for each batch operation. For more information about the vehicle configuration, see Create a vehicle (AWS CLI) (p. 51).
Update a vehicle (AWS CLI)
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 (p. 70).
You can use the UpdateVehicle API operation to update an existing vehicle. The following example uses the AWS CLI.
To update a vehicle, run the following command.
Replace file-name with the name of the JSON file that contains the configuration of your vehicle.
aws iotfleetwise update-vehicle --cli-input-json file://file-name.json
53
AWS IoT FleetWise Developer Guide Update multiple vehicles (AWS CLI)
Example vehicle configuration
· Replace vehicle-ID with the ID of the vehicle you want to update. · (Optional) Replace model-manifest-ARN with the ARN of the vehicle model (model manifest) that
you use to replace the vehicle model in use. · (Optional) Replace decoder-manifest-ARN with the ARN of your decoder manifest associated with
the new vehicle model that you specified. · (Optional) The mergeAttributes value can be one of the following.
· true Merge new attributes into existing attributes by updating existing attributes with new values and adding new attributes if they don't exist.
For example, if a vehicle has the following attributes: {"color": "black", "fuelType": "electric"}, and you update the vehicle with the following attributes: {"color": "", "fuelType": "gasoline", "model": "x"}, the updated vehicle has the following attributes: {"fuelType": "gasoline", "model": "x"}. · false Replace existing attributes with new attributes.
For example, if a vehicle has the following attributes: {"color": "black", "fuelType": "electric"}, and you update the vehicle with the {"model": "x"} attribute, the updated vehicle has the {"model": "x"} attribute.
If it's not specified, the default value is false. · (Optional) Configure attributes to add new attributes or update existing ones with new values.
For example, if you have an electric car, you can specify the following value for an attribute: {"fuelType": "electric"}.
To delete attributes, configure mergeAttributes to true and define attributes with empty strings. For example, {"color": "", "fuelType": ""}.
Important Attributes must be defined in the associated vehicle model before you can add them to individual vehicles.
{ "vehicleId": "vehicle-id", "modelManifestArn": "model-manifest-arn", "decoderManifestArn": "decoder-manifest-arn", "mergeAttributes": true, "attributes": { ... "key": "value" }
}
Update multiple vehicles (AWS CLI)
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 (p. 70).
54
AWS IoT FleetWise Developer Guide Delete a vehicle (AWS CLI)
You can use the BatchUpdateVehicle API operation to update multiple existing vehicles at one time. The following example uses the AWS CLI.
To update multiple vehicles, run the following command.
Replace file-name with the name of the JSON file that contains the configurations of multiple vehicles.
aws iotfleetwise batch-update-vehicle --cli-input-json file://file-name.json
Example vehicle configurations
{ "vehicles": [ ... { "vehicleId": "vehicle-id", "modelManifestArn": "model-manifest-arn", "decoderManifestArn": "decoder-manifest-arn", "mergeAttributes": true, "attributes": { ... "key": "value" } }, { "vehicleId": "vehicle-id", "modelManifestArn": "model-manifest-arn", "decoderManifestArn": "decoder-manifest-arn", "mergeAttributes": true, "attributes": { ... "key": "value" } } ]
}
You can update up to 10 vehicles for each batch operation. For more information about the configuration of each vehicle, see Update a vehicle (AWS CLI) (p. 53).
Delete a vehicle (AWS CLI)
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 (p. 70).
You can use the DeleteVehicle API operation to delete a vehicle. The following example uses AWS CLI. Important After a vehicle is deleted. AWS IoT FleetWise automatically remove the vehicle from the associated fleets and campaigns. For more information, see Create and manage fleets (p. 57) and Collect and transfer data with campaigns (p. 62).
To delete a vehicle, run the following command.
55
AWS IoT FleetWise Developer Guide Get vehicle information (AWS CLI) Replace vehicle-ID with the ID of the vehicle you want to delete. aws iotfleetwise delete-vehicle --vehicle-id vehicle-ID
Get vehicle information (AWS CLI)
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 (p. 70). You can use the ListVehicles API operation to verify if a vehicle has been deleted. The follow example uses the AWS CLI. To retrieve a paginated list of summaries of all vehicles, run the following command.
aws iotfleetwise list-vehicles
You can use the GetVehicle API operation to retrieve vehicle information. The follow example uses the AWS CLI. To retrieve the metadata of a vehicle, run the following command. Replace vehicle-ID with the ID of the vehicle you want to retrieve.
aws iotfleetwise get-vehicle --vehicle-Id vehicle-ID
56
AWS IoT FleetWise Developer Guide
Create and manage fleets
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 (p. 70).
A fleet represents a group of vehicles. A fleet without associated vehicles is an empty entity. Before you can use the fleet to manage multiple vehicles at the same time, you must associate vehicles with the fleet. A vehicle can belong to multiple fleets. You can control what data to collect from a fleet of vehicles and when to collect data by deploying a campaign. For more information, see Collect and transfer data with campaigns (p. 62). A fleet contains the following information. fleetId
The ID of the fleet. (Optional) description
A description that helps you find the fleet. signalCatalogArn
The Amazon Resource Name (ARN) of the signal catalog.
AWS IoT FleetWise provides the following API operations that you can use to create and manage fleets. · CreateFleet Creates a group of vehicles that contain the same group of signals. · AssociateVehicle Associates a vehicle to a fleet. · DisassociateVehicle Disassociates a vehicle from a fleet. · UpdateFleet Updates the description for an existing fleet. · DeleteFleet Deletes an existing fleet. · ListFleets Retrieves a paginated list of summaries of all fleets. · ListFleetsForVehicle Retrieves a paginated list of IDs of all fleets that the vehicle belongs to. · ListVehiclesInFleet Retrieves a paginated list of summaries of all vehicles in a fleet. · GetFleet Retrieves information about a fleet.
Topics · Create a fleet (AWS CLI) (p. 58) · Associate a vehicle with a fleet (AWS CLI) (p. 58) · Disassociate a vehicle from a fleet (AWS CLI) (p. 59) · Update a fleet (AWS CLI) (p. 59) · Delete a fleet (AWS CLI) (p. 60)
57
AWS IoT FleetWise Developer Guide Create a fleet (AWS CLI)
· Get fleet information (AWS CLI) (p. 60)
Create a fleet (AWS CLI)
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 (p. 70).
You can use the CreateFleet API operation to create a vehicle fleet. The following example uses AWS CLI. Important You must have a signal catalog before you can create a fleet. For more information, see Create a signal catalog (AWS CLI) (p. 22).
To create a fleet, run the following command. · Replace fleet-id with the ID of the fleet that you're creating.
The fleet ID must be unique and have 1-100 characters. Valid characters: letters (A-Z and a-z), numbers (0-9), colons (:), dashes (-), and underscores (_). · (Optional) Replace description with a description. The description can have 1-2048 characters. · Replace signal-catalog-ARN with the ARN of the signal catalog.
aws iotfleetwise create-fleet / --fleet-Id fleet-ID / --description description / --signalCatalogArn signal-catalog-ARN
Associate a vehicle with a fleet (AWS CLI)
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 (p. 70).
You can use the AssociateVehicle API operation to associate a vehicle with a fleet. The following example uses AWS CLI.
Important · You must have a vehicle and a fleet before you can associate a vehicle with a fleet. For more
information, see Create, provision, and manage vehicles (p. 47).
58
AWS IoT FleetWise Developer Guide Disassociate a vehicle from a fleet (AWS CLI)
· If you associate a vehicle with a fleet that is targeted by a campaign, AWS IoT FleetWise automatically deploys the campaign to the vehicle.
To associate a vehicle with a fleet, run the following command. · Replace fleet-id with the ID of the fleet. · Replace vehicle-id with the ID of the vehicle.
aws iotfleetwise associate-vehicle --fleet-id fleet-id --vehicle-id vehicle-id
Disassociate a vehicle from a fleet (AWS CLI)
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 (p. 70).
You can use the DisassociateVehicle API operation to disassociate a vehicle from a fleet. The following example uses AWS CLI. To disassociate a vehicle with a fleet, run the following command. · Replace fleet-id with the ID of the fleet. · Replace vehicle-id with the ID of the vehicle.
aws iotfleetwise disassociate-vehicle --fleet-id fleet-id --vehicle-id vehicle-id
Update a fleet (AWS CLI)
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 (p. 70).
You can use the UpdateFleet API operation to update the description for a fleet. The following example uses AWS CLI. To update a fleet, run the following command. · Replace fleet-id with the ID of the fleet that you're updating. · Replace description with a new description.
59
AWS IoT FleetWise Developer Guide Delete a fleet (AWS CLI)
The description can have 1-2048 characters.
aws iotfleetwise update-fleet --fleet-id fleet-id --description description
Delete a fleet (AWS CLI)
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 (p. 70).
You can use the DeleteFleet API operation to delete a fleet. The following example uses AWS CLI. Important Before you delete a fleet, make sure it has no associated vehicles. For instructions on how to disassociate a vehicle from a fleet, see Disassociate a vehicle.
To delete a fleet, run the following command. Replace fleet-id with the ID of the fleet that you're deleting.
aws iotfleetwise delete-fleet --fleet-id fleet-id
Get fleet information (AWS CLI)
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 (p. 70).
You can use the ListFleets API operation to verify if a fleet has been deleted. The following example uses the AWS CLI. To retrieve a paginated list of summaries of all fleets, run the following command.
aws iotfleetwise list-fleets
You can use the ListFleetsForVehicle API operation to retrieve a paginated list of IDs of all fleets that the vehicle belongs to. The following example uses the AWS CLI. To retrieve a paginated list of IDs of all fleets that the vehicle belongs to, run the following command. Replace vehicle-id with the ID of the vehicle.
60
AWS IoT FleetWise Developer Guide Get fleet information (AWS CLI)
aws iotfleetwise list-fleets-for-vehicle \ --vehicle-id vehicle-id
You can use the ListVehiclesInFleet API operation to retrieve a paginated list of summaries of all vehicles in a fleet. The following example uses the AWS CLI. To retrieve a paginated list of summaries of all vehicles in a fleet, run the following command. Replace fleet-id with the ID of the fleet.
aws iotfleetwise list-vehicles-in-fleet \ --fleet-id fleet-id
You can use the GetFleet API operation to retrieve fleet information. The following example uses the AWS CLI. To retrieve the metadata of a fleet, run the following command. Replace fleet-id with the ID of the fleet.
aws iotfleetwise get-fleet \ --fleet-id fleet-id
61
AWS IoT FleetWise Developer Guide
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 (p. 70).
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 (p. 48).
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.
62
AWS IoT FleetWise Developer Guide
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
63
AWS IoT FleetWise Developer Guide
(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) (p. 66). · 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.
64
AWS IoT FleetWise Developer Guide Create a campaign (AWS CLI)
· DeleteCampaign Deletes an existing campaign. · ListCampaigns Retrieves a paginated list of summaries for all campaigns. · GetCampaign Retrieves information about a campaign.
Tutorials · Create a campaign (AWS CLI) (p. 65) · Update a campaign (AWS CLI) (p. 66) · Delete a campaign (p. 66) · Get campaign information (AWS CLI) (p. 67)
Create a campaign (AWS CLI)
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 (p. 70).
You can use the CreateCampaign API operation to create a campaign. The following example uses the AWS CLI.
Important · You must have a signal catalog and a vehicle or fleet before you create a campaign. For
more information, see Create and manage signal catalogs (p. 19), ??? (p. 47), and Create and manage fleets (p. 57). · After a campaign is created, you must use the UpdateCampaign API operation to approve the campaign. For more information, see Update a campaign (AWS CLI) (p. 66)
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.
{ "campaignName": "campaign-name", "targetArn": "target-arn", "signalCatalogArn": "signal-catalog-arn", "collectionScheme": { "conditionBasedCollectionScheme": { "conditionLanguageVersion": 1, "expression": "$variable.`Vehicle.DemoBrakePedalPressure` > 7000",
65
AWS IoT FleetWise Developer Guide Update a campaign (AWS CLI)
"minimumTriggerIntervalMs": 1000, "triggerMode": "ALWAYS" } }, "compression": "SNAPPY", "diagnosticsMode": "OFF", "postTriggerCollectionDuration": 1000, "priority": 0, "signalsToCollect": [ { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "signalName": "Vehicle.DemoEngineTorque" }, { "maxSampleCount": 100, "minimumSamplingIntervalMs": 0, "signalName": "Vehicle.DemoBrakePedalPressure" } ], "spoolingMode": "TO_DISK" }
Update a campaign (AWS CLI)
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 (p. 70).
You can use the UpdateCampaign 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 SiteWise to deploy it to a vehicle or fleet. · SUSPEND Suspends the campaign. · RESUME Reactivates the SUSPEND campaign. · UPDATE Updates the campaign by defining attributes and associating them with a signal.
aws iotfleetwise update-campaign \ --campaign-name campaign-name \ --action action
Delete a campaign
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.
66
AWS IoT FleetWise Developer Guide Get campaign information (AWS CLI)
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 (p. 70).
You can use the DeleteCampaign 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 --campaign-name campaign-name
Get campaign information (AWS CLI)
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 (p. 70).
You can use the ListCampaigns 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
You can use the GetCampaign 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 --campaign-name campaign-name
67
AWS IoT FleetWise Developer Guide Processing vehicle data
Processing and visualizing vehicle data
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 (p. 70).
The AWS IoT FleetWise Edge Agent software transfers selected vehicle data to Amazon Timestream. After your data arrives in Timestream, you can use Timestream to query your data and use other AWS services to visualize and share it.
Processing vehicle data
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?.
The default schema of data that is transferred to Timestream contains the following fields.
Field name eventId vehicleId
campaignName
Data type varchar varchar
varchar
time
timestamp
measure_name
varchar
measure_value::biginbtigint
measure_value::doubldeouble
Description
The ID of the data collection event.
The ID of the vehicle from which the data was collected.
The name of the campaign that the Edge Agent software uses to collect data.
The timestamp of the data point.
The name of the signal.
Signal values of type Integer.
Signal values of type Double.
68
AWS IoT FleetWise Developer Guide Visualizing vehicle data
Field name
Data type
measure_value::boolebaonolean
Description
Signal values of type Boolean.
Visualizing vehicle data
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. 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 Amazon QuickSight.
69
AWS IoT FleetWise Developer Guide
Preview AWS CLI and AWS SDKs
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 (p. 70).
Because AWS IoT FleetWise is in preview, you must download the AWS CLI and SDK resources from the following links to use the feature in your scripts and applications.
· To install AWS SDK for Java 2.x
1. From a command prompt, run java --version to determine if Java 8 or later is installed. If you don't have it installed, follow the instructions to install Java 8.
2. Download the AwsJavaSdk-Iotfleetwise-2.0.zip file. 3. Unzip the AwsJavaSdk-Iotfleetwise-2.0.zip file to get the AwsJavaSdk-
Iotfleetwise-2.0.jar file. 4. Use the following information to add a dependency to the AwsJavaSdk-
Iotfleetwise-2.0.jar file that you downloaded.
groupId: software.amazon.awssdk artifactId: iotfleetwise version: 2.0
For Apache Maven projects, follow the instructions on the Guide to installing 3rd party JARs or Frequently Asked Technical Questions page on the Apache Maven Project website. 5. Verify that iotfleetwise has been added in your dependency file. For Apache Maven, check the pom.xml file. 6. Add the following dependencies for Apache Maven projects.
<dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>aws-core</artifactId>
</dependency> <dependency>
<groupId>software.amazon.awssdk</groupId> <artifactId>aws-json-protocol</artifactId> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>apache-client</artifactId> </dependency>
For more information about how to set up AWS SDK for Java 2.x with other build systems, see Setting up in the AWS SDK for Java 2.x Developer Guide.
To import the client, add the following.
import software.amazon.awssdk.services.iotfleetwise.IotfleetwiseClient;
70
AWS IoT FleetWise Developer Guide Configuring the AWS CLI
To instantiate the the client, add the following. Replace US_EAST_1 with EU_CENTRAL_1 if you want to work with AWS IoT FleetWise in Europe (Frankfurt).
final IotfleetwiseClient client = IotfleetwiseClient.builder() .region(Region.US_EAST_1) .build();
· To install AWS SDK for Python (Boto3) 1. From a command prompt, run python3 -V to determine if Python 3.6 or later is installed. If you don't have it installed, follow the instructions to install Python 3. 2. Download the AwsSdkPythonCli-Iotfleetwise.zip file. 3. Unzip the AwsSdkPythonCli-Iotfleetwise.zip file to get the AwsSdkPythonCliIotfleetwise folder. 4. Navigate to the AwsSdkPythonCli-Iotfleetwise directory where you see the boto3-1.20.13-py3-none-any.whl file. 5. To install AWS SDK for Python (Boto3), run the following command.
python3 -m pip install boto3-1.20.13-py3-none-any.whl
For more information about how to use AWS SDK for Python (Boto), see the AWS SDK for Python (Boto) Documentation.
Configuring the AWS CLI
To enable AWS IoT FleetWise commands in the AWS CLI, complete these steps. From a command prompt, run aws --version to determine if the AWS CLI is installed. If you don't have it installed, follow the instructions to install the AWS CLI. To enable the AWS IoT FleetWise API in the AWS CLI 1. Download the iotfleetwise-preview.zip file. 2. Navigate to the directory where you downloaded the iotfleetwise-preview.zip file. 3. Unzip the file to get the iotfleetwise-preview.json file. 4. From a command prompt, run the following command.
aws configure add-model --service-name iotfleetwise --service-model file:// iotfleetwise-preview.json
The aws iotfleetwise AWS CLI commands are now available.
71
AWS IoT FleetWise Developer Guide AWS IoT FleetWise Edge Agent software issues
Troubleshooting AWS IoT FleetWise
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 (p. 70).
Use the troubleshooting information and solutions in this section to help resolve issues with AWS IoT FleetWise.
AWS IoT FleetWise Edge Agent software issues
Troubleshoot Edge Agent software issues. Issues
· Issue: The Edge Agent software doesn't start. (p. 72) · Issue: [ERROR] [IoTFleetWiseEngine::connect]: [ Failed to init persistency library ] (p. 73) · Issue: The Edge Agent software doesn't collect on-board diagnostics (OBD) II PIDs and diagnostic
trouble codes (DTCs). (p. 73) · Issue: The AWS IoT FleetWise Edge Agent software doesn't collect data from the network or isn't able
to apply data inspection rules. (p. 74) · Issue: [ERROR] [AwsIotConnectivityModule::connect]: [Connection failed with error] or [WARN]
[AwsIotChannel::send]: [No alive MQTT Connection.] (p. 74)
Issue: The Edge Agent software doesn't start.
You might see the following errors when the Edge Agent software doesn't start. ·
Error from reader: * Line 1, Column 1 Syntax error: value, object or array expected.
Solution: Make sure the AWS IoT FleetWise Edge Agent software configuration file is using valid JSON format. For example, make sure that commas are used correctly. For more information about the configuration file, do the following to download the AWS IoT FleetWise Edge Agent software Developer Guide. 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. ·
[ERROR] [SocketCANBusChannel::connect]: [ SocketCan with name xxx is not accessible]
72
AWS IoT FleetWise Developer Guide Issue: [ERROR] [IoTFleetWiseEngine::connect]:
[ Failed to init persistency library ]
[ERROR] [IoTFleetWiseEngine::connect]: [ Failed to Bind Consumers to Producers ]
Solution: You might see this error when the Edge Agent software fails to establish socket communication with the network interfaces defined in the configuration file.
To check that every network interface defined in the configuration is available, run the following command.
ip link show
To bring a network interface online, run the following command. Replace network-interface-id with the ID of the network interface.
sudo ip link set network-interface-id up
·
[ERROR] [AwsIotConnectivityModule::connect]: [Connection failed with error] [WARN] [AwsIotChannel::send]: [No alive MQTT Connection.] # or [WARN] [AwsIotChannel::send]: [aws-c-common: AWS_ERROR_FILE_INVALID_PATH]
Solution: You might see this error when the Edge Agent software fails to establish an MQTT connection to AWS IoT Core. Check that the following are configured correctly and restart the Edge Agent software. · mqttConnection::endpointUrl AWS account's IoT device endpoint. · mqttConnection::clientID The ID of the vehicle in which the Edge Agent software is running. · mqttConnection::certificateFilename The path to the vehicle certificate file. · mqttConnection::privateKeyFilename The path to the vehicle private key file. · You have used AWS IoT Core to provision the vehicle. For more information, see Provision
vehicles (p. 48).
For more troubleshooting information, see AWS IoT Device SDK for C++ Frequently Asked Questions.
Issue: [ERROR] [IoTFleetWiseEngine::connect]: [ Failed to init persistency library ]
Solution: You might see this error when the Edge Agent software fails to locate the persistence storage. Check that the following is configured correctly and restart the Edge Agent software.
persistency:persistencyPath A local path used to persist collection schemes, decoder manifests, and data snapshots.
Issue: The Edge Agent software doesn't collect on-board diagnostics (OBD) II PIDs and diagnostic trouble codes (DTCs).
Solution: You might see this error if obdInterface:pidRequestIntervalSeconds or obdInterface:dtcRequestIntervalSeconds is configured to 0.
If the Edge Agent software is running in an automatic transmission vehicle, make sure obdInterface:hasTransmissionEcu is configured to true.
73
AWS IoT FleetWise Developer Guide Issue: The AWS IoT FleetWise Edge Agent software doesn't collect data from the network or isn't able to apply data inspection rules. If your vehicle supports extended Controller Area Network (CAN bus) arbitration IDs, make sure obdInterface:useExtendedIds is configured to true.
Issue: The AWS IoT FleetWise Edge Agent software doesn't collect data from the network or isn't able to apply data inspection rules.
Solution: You might see this error when the default quotas are breached.
Resource Value of the signal ID
Quota
The signal ID must be less than or equal to 50,000
Adjustable Yes
Number of active data 256
Yes
collection schemes per
vehicle
Size of the signal
20 MB
Yes
history buffer
Note
The Edge Agent software won't collect data from signals that have an ID greater than 50,000. We recommend that you check how many signals the signal catalog contains before you change this quota.
We recommend that you check how many campaigns that you've created in the cloud and how many schemes each campaign contains before you change this quota.
If the quota is breached, the Edge Agent software stops collecting new data.
Issue: [ERROR] [AwsIotConnectivityModule::connect]: [Connection failed with error] or [WARN] [AwsIotChannel::send]: [No alive MQTT Connection.]
Solution: You might see this error when the Edge Agent software isn't connected to the cloud. By default, the Edge Agent software sends a ping request to AWS IoT Core every minute and waits for three minutes. If there's no response, the Edge Agent software automatically reestablishes the connection to the cloud.
74
AWS IoT FleetWise Developer Guide Data protection
Security in AWS IoT FleetWise
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 (p. 70).
Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.
Security is a shared responsibility between AWS and you. The shared responsibility model describes this as security of the cloud and security in the cloud: · Security of the cloud AWS is responsible for protecting the infrastructure that runs AWS services in
the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the AWS Compliance Programs. To learn about the compliance programs that apply to AWS IoT FleetWise, see AWS Services in Scope by Compliance Program. · Security in the cloud Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company's requirements, and applicable laws and regulations
This documentation helps you understand how to apply the shared responsibility model when using AWS IoT FleetWise. It shows you how to configure AWS IoT FleetWise to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your AWS IoT FleetWise resources. Contents
· Data protection in AWS IoT FleetWise (p. 75) · Identity and Access Management for AWS IoT FleetWise (p. 77) · Monitoring AWS IoT FleetWise (p. 90) · Compliance Validation for AWS IoT FleetWise (p. 92) · Resilience in AWS IoT FleetWise (p. 93) · Infrastructure security in AWS IoT FleetWise (p. 94) · Configuration and vulnerability analysis in AWS IoT FleetWise (p. 94) · Security best practices for AWS IoT FleetWise (p. 95)
Data protection in AWS IoT FleetWise
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.
75
AWS IoT FleetWise Developer Guide Encryption at rest
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 (p. 70).
The AWS shared responsibility model applies to data protection in AWS IoT FleetWise. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. This content includes the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the Data Privacy FAQ. For information about data protection in Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.
For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management (IAM). That way each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:
· Use multi-factor authentication (MFA) with each account. · Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later. · Set up API and user activity logging with AWS CloudTrail. · Use AWS encryption solutions, along with all default security controls within AWS services. · Use advanced managed security services such as Amazon Macie, which assists in discovering and
securing personal data that is stored in Amazon S3. · If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command
line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see Federal Information Processing Standard (FIPS) 140-2.
We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form fields such as a Name field. This includes when you work with AWS IoT FleetWise or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.
Encryption at rest
The data collected from a vehicle is transmitted to the cloud through an AWS IoT Core message with the MQTT message protocol. AWS IoT FleetWise delivers the data to your Amazon Timestream database. In Timestream, your data is encrypted. All AWS services encrypt data at rest by default.
Encryption at rest integrates with AWS Key Management Service (AWS KMS) for managing the encryption key that is used to encrypt your data. You can choose to use a customer managed key to encrypt data collected by AWS IoT FleetWise. You can create, manage, and view your encryption key through AWS KMS. For more information, see What is AWS Key Management Service? in the AWS Key Management Service Developer Guide.
Encryption in transit
All data exchanged with AWS IoT services is encrypted in transit by using Transport Layer Security (TLS). For more information, see Transport security in the AWS IoT Developer Guide.
Also, AWS IoT Core supports authentication and authorization to help securely control access to AWS IoT FleetWise resources. Vehicles can use X.509 certificates to get authenticated (signed in) to use AWS
76
AWS IoT FleetWise Developer Guide Identity and Access Management
IoT FleetWise and use AWS IoT Core policies to get authorized (have permissions) to perform specified actions. For more information, see the section called "Provision vehicles" (p. 48).
Identity and Access Management for AWS IoT FleetWise
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 (p. 70).
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be authenticated (signed in) and authorized (have permissions) to use AWS IoT FleetWise resources. IAM is an AWS service that you can use with no additional charge.
Topics · Audience (p. 77) · Authenticating with identities (p. 78) · Managing access using policies (p. 79) · How AWS IoT FleetWise works with IAM (p. 81) · Identity-based policy examples for AWS IoT FleetWise (p. 86) · Troubleshooting AWS IoT FleetWise identity and access (p. 88)
Audience
How you use AWS Identity and Access Management (IAM) differs, depending on the work that you do in AWS IoT FleetWise.
Service user If you use the AWS IoT FleetWise service to do your job, then your administrator provides you with the credentials and permissions that you need. As you use more AWS IoT FleetWise features to do your work, you might need additional permissions. Understanding how access is managed can help you request the right permissions from your administrator. If you cannot access a feature in AWS IoT FleetWise, see Troubleshooting AWS IoT FleetWise identity and access (p. 88).
Service administrator If you're in charge of AWS IoT FleetWise resources at your company, you probably have full access to AWS IoT FleetWise. It's your job to determine which AWS IoT FleetWise features and resources your employees should access. You must then submit requests to your IAM administrator to change the permissions of your service users. Review the information on this page to understand the basic concepts of IAM. To learn more about how your company can use IAM with AWS IoT FleetWise, see How AWS IoT FleetWise works with IAM (p. 81).
IAM administrator If you're an IAM administrator, you might want to learn details about how you can write policies to manage access to AWS IoT FleetWise. To view example AWS IoT FleetWise identity-based policies that you can use in IAM, see Identity-based policy examples for AWS IoT FleetWise (p. 86).
77
AWS IoT FleetWise Developer Guide Authenticating with identities
Authenticating with identities
Authentication is how you sign in to AWS using your identity credentials. For more information about signing in using the AWS Management Console, see Signing in to the AWS Management Console as an IAM user or root user in the IAM User Guide.
You must be authenticated (signed in to AWS) as the AWS account root user, an IAM user, or by assuming an IAM role. You can also use your company's single sign-on authentication or even sign in using Google or Facebook. In these cases, your administrator previously set up identity federation using IAM roles. When you access AWS using credentials from another company, you are assuming a role indirectly.
To sign in directly to the AWS Management Console, use your password with your root user email address or your IAM user name. You can access AWS programmatically using your root user or IAM users access keys. AWS provides SDK and command line tools to cryptographically sign your request using your credentials. If you don't use AWS tools, you must sign the request yourself. Do this using Signature Version 4, a protocol for authenticating inbound API requests. For more information about authenticating requests, see Signature Version 4 signing process in the AWS General Reference.
Regardless of the authentication method that you use, you might also be required to provide additional security information. For example, AWS recommends that you use multi-factor authentication (MFA) to increase the security of your account. To learn more, see Using multi-factor authentication (MFA) in AWS in the IAM User Guide.
AWS account root user
When you first create an AWS account, you begin with a single sign-in identity that has complete access to all AWS services and resources in the account. This identity is called the AWS account root user and is accessed by signing in with the email address and password that you used to create the account. We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the root user only to create your first IAM user. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks.
IAM users and groups
An IAM user is an identity within your AWS account that has specific permissions for a single person or application. An IAM user can have long-term credentials such as a user name and password or a set of access keys. To learn how to generate access keys, see Managing access keys for IAM users in the IAM User Guide. When you generate access keys for an IAM user, make sure you view and securely save the key pair. You cannot recover the secret access key in the future. Instead, you must generate a new access key pair.
An IAM group is an identity that specifies a collection of IAM users. You can't sign in as a group. You can use groups to specify permissions for multiple users at a time. Groups make permissions easier to manage for large sets of users. For example, you could have a group named IAMAdmins and give that group permissions to administer IAM resources.
Users are different from roles. A user is uniquely associated with one person or application, but a role is intended to be assumable by anyone who needs it. Users have permanent long-term credentials, but roles provide temporary credentials. To learn more, see When to create an IAM user (instead of a role) in the IAM User Guide.
IAM roles
An IAM role is an identity within your AWS account that has specific permissions. It is similar to an IAM user, but is not associated with a specific person. You can temporarily assume an IAM role in the AWS
78
AWS IoT FleetWise Developer Guide Managing access using policies
Management Console by switching roles. You can assume a role by calling an AWS CLI or AWS API operation or by using a custom URL. For more information about methods for using roles, see Using IAM roles in the IAM User Guide.
IAM roles with temporary credentials are useful in the following situations:
· Temporary IAM user permissions An IAM user can assume an IAM role to temporarily take on different permissions for a specific task.
· Federated user access Instead of creating an IAM user, you can use existing identities from AWS Directory Service, your enterprise user directory, or a web identity provider. These are known as federated users. AWS assigns a role to a federated user when access is requested through an identity provider. For more information about federated users, see Federated users and roles in the IAM User Guide.
· Cross-account access You can use an IAM role to allow someone (a trusted principal) in a different account to access resources in your account. Roles are the primary way to grant cross-account access. However, with some AWS services, you can attach a policy directly to a resource (instead of using a role as a proxy). To learn the difference between roles and resource-based policies for cross-account access, see How IAM roles differ from resource-based policies in the IAM User Guide.
· Cross-service access Some AWS services use features in other AWS services. For example, when you make a call in a service, it's common for that service to run applications in Amazon EC2 or store objects in Amazon S3. A service might do this using the calling principal's permissions, using a service role, or using a service-linked role.
· Principal permissions When you use an IAM user or role to perform actions in AWS, you are considered a principal. Policies grant permissions to a principal. When you use some services, you might perform an action that then triggers another action in a different service. In this case, you must have permissions to perform both actions. To see whether an action requires additional dependent actions in a policy, see https://docs.aws.amazon.com/service-authorization/latest/ reference/reference_policies_actions-resources-contextkeys.html in the Service Authorization Reference.
· Service role A service role is an IAM role that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.
· Service-linked role A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your IAM account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles.
· Applications running on Amazon EC2 You can use an IAM role to manage temporary credentials for applications that are running on an EC2 instance and making AWS CLI or AWS API requests. This is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2 instance and make it available to all of its applications, you create an instance profile that is attached to the instance. An instance profile contains the role and enables programs that are running on the EC2 instance to get temporary credentials. For more information, see Using an IAM role to grant permissions to applications running on Amazon EC2 instances in the IAM User Guide.
To learn whether to use IAM roles or IAM users, see When to create an IAM role (instead of a user) in the IAM User Guide.
Managing access using policies
You control access in AWS by creating policies and attaching them to IAM identities or AWS resources. A policy is an object in AWS that, when associated with an identity or resource, defines their permissions. You can sign in as the root user or an IAM user, or you can assume an IAM role. When you then make a request, AWS evaluates the related identity-based or resource-based policies. Permissions in the policies determine whether the request is allowed or denied. Most policies are stored in AWS as JSON
79
AWS IoT FleetWise Developer Guide Managing access using policies
documents. For more information about the structure and contents of JSON policy documents, see Overview of JSON policies in the IAM User Guide.
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.
Every IAM entity (user or role) starts with no permissions. In other words, by default, users can do nothing, not even change their own password. To give a user permission to do something, an administrator must attach a permissions policy to a user. Or the administrator can add the user to a group that has the intended permissions. When an administrator gives permissions to a group, all users in that group are granted those permissions.
IAM policies define permissions for an action regardless of the method that you use to perform the operation. For example, suppose that you have a policy that allows the iam:GetRole action. A user with that policy can get role information from the AWS Management Console, the AWS CLI, or the AWS API.
Identity-based policies
Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see Creating IAM policies in the IAM User Guide.
Identity-based policies can be further categorized as inline policies or managed policies. Inline policies are embedded directly into a single user, group, or role. Managed policies are standalone policies that you can attach to multiple users, groups, and roles in your AWS account. Managed policies include AWS managed policies and customer managed policies. To learn how to choose between a managed policy or an inline policy, see Choosing between managed policies and inline policies in the IAM User Guide.
Resource-based policies
Resource-based policies are JSON policy documents that you attach to a resource. Examples of resourcebased policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resourcebased policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must specify a principal in a resource-based policy. Principals can include accounts, users, roles, federated users, or AWS services.
Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy.
Access control lists (ACLs)
Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.
Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about ACLs, see Access control list (ACL) overview in the Amazon Simple Storage Service Developer Guide.
Other policy types
AWS supports additional, less-common policy types. These policy types can set the maximum permissions granted to you by the more common policy types.
· Permissions boundaries A permissions boundary is an advanced feature in which you set the maximum permissions that an identity-based policy can grant to an IAM entity (IAM user or role).
80
AWS IoT FleetWise Developer Guide How AWS IoT FleetWise works with IAM
You can set a permissions boundary for an entity. The resulting permissions are the intersection of entity's identity-based policies and its permissions boundaries. Resource-based policies that specify the user or role in the Principal field are not limited by the permissions boundary. An explicit deny in any of these policies overrides the allow. For more information about permissions boundaries, see Permissions boundaries for IAM entities in the IAM User Guide. · Service control policies (SCPs) SCPs are JSON policies that specify the maximum permissions for an organization or organizational unit (OU) in AWS Organizations. AWS Organizations is a service for grouping and centrally managing multiple AWS accounts that your business owns. If you enable all features in an organization, then you can apply service control policies (SCPs) to any or all of your accounts. The SCP limits permissions for entities in member accounts, including each AWS account root user. For more information about Organizations and SCPs, see How SCPs work in the AWS Organizations User Guide. · Session policies Session policies are advanced policies that you pass as a parameter when you programmatically create a temporary session for a role or federated user. The resulting session's permissions are the intersection of the user or role's identity-based policies and the session policies. Permissions can also come from a resource-based policy. An explicit deny in any of these policies overrides the allow. For more information, see Session policies in the IAM User Guide.
Multiple policy types
When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see Policy evaluation logic in the IAM User Guide.
How AWS IoT FleetWise works with IAM
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 (p. 70).
Before you use IAM to manage access to AWS IoT FleetWise, learn what IAM features are available to use with AWS IoT FleetWise.
IAM features you can use with AWS IoT FleetWise
IAM feature Identity-based policies (p. 82)
AWS IoT FleetWise support Yes
Resource-based policies (p. 82)
No
Policy actions (p. 83)
Yes
Policy resources (p. 83)
Yes
Policy condition keys (p. 84)
Yes
ACLs (p. 84)
No
ABAC (tags in policies) (p. 85)
Partial
81
AWS IoT FleetWise Developer Guide How AWS IoT FleetWise works with IAM
IAM feature Temporary credentials (p. 85) Principal permissions (p. 85) Service roles (p. 86) Service-linked roles (p. 86)
AWS IoT FleetWise support Yes Yes No No
To get a high-level view of how AWS IoT FleetWise and other AWS services work with most IAM features, see AWS services that work with IAM in the IAM User Guide.
Identity-based policies for AWS IoT FleetWise
Supports identity-based policies
Yes
Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see Creating IAM policies in the IAM User Guide.
With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. You can't specify the principal in an identity-based policy because it applies to the user or role to which it is attached. To learn about all of the elements that you can use in a JSON policy, see IAM JSON policy elements reference in the IAM User Guide.
Identity-based policy examples for AWS IoT FleetWise
To view examples of AWS IoT FleetWise identity-based policies, see Identity-based policy examples for AWS IoT FleetWise (p. 86).
Resource-based policies within AWS IoT FleetWise
Supports resource-based policies
No
Resource-based policies are JSON policy documents that you attach to a resource. Examples of resourcebased policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resourcebased policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must specify a principal in a resource-based policy. Principals can include accounts, users, roles, federated users, or AWS services.
To enable cross-account access, you can specify an entire account or IAM entities in another account as the principal in a resource-based policy. Adding a cross-account principal to a resource-based policy is only half of establishing the trust relationship. When the principal and the resource are in different AWS accounts, an IAM administrator in the trusted account must also grant the principal entity (user or role) permission to access the resource. They grant permission by attaching an identity-based policy to the entity. However, if a resource-based policy grants access to a principal in the same account, no additional identity-based policy is required. For more information, see How IAM roles differ from resource-based policies in the IAM User Guide.
82
AWS IoT FleetWise Developer Guide How AWS IoT FleetWise works with IAM
Policy actions for AWS IoT FleetWise
Supports policy actions
Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.
The Action element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Policy actions usually have the same name as the associated AWS API operation. There are some exceptions, such as permission-only actions that don't have a matching API operation. There are also some operations that require multiple actions in a policy. These additional actions are called dependent actions.
Include actions in a policy to grant permissions to perform the associated operation.
To see a list of AWS IoT FleetWise actions, see Actions Defined by AWS IoT FleetWise in the Service Authorization Reference.
Policy actions in AWS IoT FleetWise use the following prefix before the action:
iotfleetwise
To specify multiple actions in a single statement, separate them with commas.
"Action": [ "iotfleetwise:action1", "iotfleetwise:action2"
]
You can specify multiple actions using wildcards (*). For example, to specify all actions that begin with the word List, include the following action:
"Action": "iotfleetwise:List*"
To view examples of AWS IoT FleetWise identity-based policies, see Identity-based policy examples for AWS IoT FleetWise (p. 86).
Policy resources for AWS IoT FleetWise
Supports policy resources
Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.
The Resource JSON policy element specifies the object or objects to which the action applies. Statements must include either a Resource or a NotResource element. As a best practice, specify a resource using its Amazon Resource Name (ARN). You can do this for actions that support a specific resource type, known as resource-level permissions.
83
AWS IoT FleetWise Developer Guide How AWS IoT FleetWise works with IAM
For actions that don't support resource-level permissions, such as listing operations, use a wildcard (*) to indicate that the statement applies to all resources.
"Resource": "*"
To see a list of AWS IoT FleetWise resource types and their ARNs, see Resources Defined by AWS IoT FleetWise in the Service Authorization Reference. To learn with which actions you can specify the ARN of each resource, see Actions Defined by AWS IoT FleetWise .
To view examples of AWS IoT FleetWise identity-based policies, see Identity-based policy examples for AWS IoT FleetWise (p. 86).
Policy condition keys for AWS IoT FleetWise
Supports policy condition keys
Yes
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.
The Condition element (or Condition block) lets you specify conditions in which a statement is in effect. The Condition element is optional. You can create conditional expressions that use condition operators, such as equals or less than, to match the condition in the policy with values in the request.
If you specify multiple Condition elements in a statement, or multiple keys in a single Condition element, AWS evaluates them using a logical AND operation. If you specify multiple values for a single condition key, AWS evaluates the condition using a logical OR operation. All of the conditions must be met before the statement's permissions are granted.
You can also use placeholder variables when you specify conditions. For example, you can grant an IAM user permission to access a resource only if it is tagged with their IAM user name. For more information, see IAM policy elements: variables and tags in the IAM User Guide.
AWS supports global condition keys and service-specific condition keys. To see all AWS global condition keys, see AWS global condition context keys in the IAM User Guide.
To see a list of AWS IoT FleetWise condition keys, see Condition Keys for AWS IoT FleetWise in the Service Authorization Reference. To learn with which actions and resources you can use a condition key, see Actions Defined by AWS IoT FleetWise .
To view examples of AWS IoT FleetWise identity-based policies, see Identity-based policy examples for AWS IoT FleetWise (p. 86).
Access control lists (ACLs) in AWS IoT FleetWise
Supports ACLs
No
Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.
84
AWS IoT FleetWise Developer Guide How AWS IoT FleetWise works with IAM
Attribute-based access control (ABAC) with AWS IoT FleetWise
Supports ABAC (tags in policies)
Partial
Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes. In AWS, these attributes are called tags. You can attach tags to IAM entities (users or roles) and to many AWS resources. Tagging entities and resources is the first step of ABAC. Then you design ABAC policies to allow operations when the principal's tag matches the tag on the resource that they are trying to access.
ABAC is helpful in environments that are growing rapidly and helps with situations where policy management becomes cumbersome.
To control access based on tags, you provide tag information in the condition element of a policy using the aws:ResourceTag/key-name, aws:RequestTag/key-name, or aws:TagKeys condition keys.
For more information about ABAC, see What is ABAC? in the IAM User Guide. To view a tutorial with steps for setting up ABAC, see Use attribute-based access control (ABAC) in the IAM User Guide.
Note AWS IoT FleetWise only supports iam:PassRole, which is required for the RegisterAccount API operation.
Using Temporary credentials with AWS IoT FleetWise
Supports temporary credentials
Yes
Some AWS services don't work when you sign in using temporary credentials. For additional information, including which AWS services work with temporary credentials, see AWS services that work with IAM in the IAM User Guide.
You are using temporary credentials if you sign in to the AWS Management Console using any method except a user name and password. For example, when you access AWS using your company's single sign-on (SSO) link, that process automatically creates temporary credentials. You also automatically create temporary credentials when you sign in to the console as a user and then switch roles. For more information about switching roles, see Switching to a role (console) in the IAM User Guide.
You can manually create temporary credentials using the AWS CLI or AWS API. You can then use those temporary credentials to access AWS. AWS recommends that you dynamically generate temporary credentials instead of using long-term access keys. For more information, see Temporary security credentials in IAM.
Cross-service principal permissions for AWS IoT FleetWise
Supports principal permissions
Yes
When you use an IAM user or role to perform actions in AWS, you are considered a principal. Policies grant permissions to a principal. When you use some services, you might perform an action that then triggers another action in a different service. In this case, you must have permissions to perform both actions. To see whether an action requires additional dependent actions in a policy, see https:// docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resourcescontextkeys.html in the Service Authorization Reference.
85
AWS IoT FleetWise Developer Guide Identity-based policy examples
Service roles for AWS IoT FleetWise
Supports service roles
No
A service role is an IAM role that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.
Warning Changing the permissions for a service role might break AWS IoT FleetWise functionality. Edit service roles only when AWS IoT FleetWise provides guidance to do so.
Service-linked roles for AWS IoT FleetWise
Supports service-linked roles
No
A service-linked role is a type of service role that is linked to an AWS service. The service can assume the role to perform an action on your behalf. Service-linked roles appear in your IAM account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles.
For details about creating or managing service-linked roles, see AWS services that work with IAM. Find a service in the table that includes a Yes in the Service-linked role column. Choose the Yes link to view the service-linked role documentation for that service.
Identity-based policy examples for AWS IoT FleetWise
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 (p. 70).
By default, IAM users and roles don't have permission to create or modify AWS IoT FleetWise resources. They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API. An IAM administrator must create IAM policies that grant users and roles permission to perform actions on the resources that they need. The administrator must then attach those policies to the IAM users or groups that require those permissions.
To learn how to create an IAM identity-based policy using these example JSON policy documents, see Creating IAM policies in the IAM User Guide.
Topics · Policy best practices (p. 87) · Using the AWS IoT FleetWise console (p. 87) · Allow users to view their own permissions (p. 87) · Access resources in Amazon Timestream (p. 88)
86
AWS IoT FleetWise Developer Guide Identity-based policy examples
Policy best practices
Identity-based policies are very powerful. They determine whether someone can create, access, or delete AWS IoT FleetWise resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations:
· Get started using AWS managed policies To start using AWS IoT FleetWise quickly, use AWS managed policies to give your employees the permissions they need. These policies are already available in your account and are maintained and updated by AWS. For more information, see Get started using permissions with AWS managed policies in the IAM User Guide.
· Grant least privilege When you create custom policies, grant only the permissions required to perform a task. Start with a minimum set of permissions and grant additional permissions as necessary. Doing so is more secure than starting with permissions that are too lenient and then trying to tighten them later. For more information, see Grant least privilege in the IAM User Guide.
· Enable MFA for sensitive operations For extra security, require IAM users to use multi-factor authentication (MFA) to access sensitive resources or API operations. For more information, see Using multi-factor authentication (MFA) in AWS in the IAM User Guide.
· Use policy conditions for extra security To the extent that it's practical, define the conditions under which your identity-based policies allow access to a resource. For example, you can write conditions to specify a range of allowable IP addresses that a request must come from. You can also write conditions to allow requests only within a specified date or time range, or to require the use of SSL or MFA. For more information, see IAM JSON policy elements: Condition in the IAM User Guide.
Using the AWS IoT FleetWise console
To access the AWS IoT FleetWise console, you must have a minimum set of permissions. These permissions must allow you to list and view details about the AWS IoT FleetWise resources in your AWS account. If you create an identity-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities (IAM users or roles) with that policy.
You don't need to allow minimum console permissions for users that are making calls only to the AWS CLI or the AWS API. Instead, allow access to only the actions that match the API operation that you're trying to perform.
To ensure that users and roles can still use the AWS IoT FleetWise console, also attach the AWS IoT FleetWise ConsoleAccess or ReadOnly AWS managed policy to the entities. For more information, see Adding permissions to a user in the IAM User Guide.
Allow users to view their own permissions
This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ViewOwnUserInfo", "Effect": "Allow", "Action": [ "iam:GetUserPolicy", "iam:ListGroupsForUser", "iam:ListAttachedUserPolicies", "iam:ListUserPolicies", "iam:GetUser"
87
AWS IoT FleetWise Developer Guide Troubleshooting
], "Resource": ["arn:aws:iam::*:user/${aws:username}"] }, { "Sid": "NavigateInConsole", "Effect": "Allow", "Action": [
"iam:GetGroupPolicy", "iam:GetPolicyVersion", "iam:GetPolicy", "iam:ListAttachedGroupPolicies", "iam:ListGroupPolicies", "iam:ListPolicyVersions", "iam:ListPolicies", "iam:ListUsers" ], "Resource": "*" } ] }
Access resources in Amazon Timestream
Before using AWS IoT FleetWise, you must register your AWS account, IAM, and Amazon Timestream resources to grant AWS IoT FleetWise permission to send vehicle data to AWS Cloud on your behalf. To register, you need:
· An Amazon Timestream database. · A table created in the specified Amazon Timestream database. · An IAM role that allows AWS IoT FleetWise to send data to Amazon Timestream.
For more information, including procedures and example policies, see Configure Settings.
Troubleshooting AWS IoT FleetWise identity and access
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 (p. 70).
Use the following information to help you diagnose and fix common issues that you might encounter when working with AWS IoT FleetWise and IAM.
Topics · I am not authorized to perform an action in AWS IoT FleetWise (p. 89) · I am not authorized to perform iam:PassRole (p. 89) · I want to view my access keys (p. 89) · I'm an administrator and want to allow others to access AWS IoT FleetWise (p. 90)
88
AWS IoT FleetWise Developer Guide Troubleshooting
· I want to allow people outside of my AWS account to access my AWS IoT FleetWise resources (p. 90)
I am not authorized to perform an action in AWS IoT FleetWise
If the AWS Management Console tells you that you're not authorized to perform an action, then you must contact your administrator for assistance. Your administrator is the person that provided you with your user name and password.
The following example error occurs when the mateojackson IAM user tries to use the console to view details about a fictional myVehicle resource but does not have the iotfleetwise:GetVehicleStatus permissions.
User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: iotfleetwise:GetVehicleStatus on resource: myVehicle
In this case, Mateo asks his administrator to update his policies to allow him to access the myVehicle resource using the iotfleetwise:GetVehicleStatus action.
I am not authorized to perform iam:PassRole
If you receive an error that you're not authorized to perform the iam:PassRole action, then you must contact your administrator for assistance. Your administrator is the person that provided you with your user name and password. Ask that person to update your policies to allow you to pass a role to AWS IoT FleetWise.
Some AWS services allow you to pass an existing role to that service, instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service.
The following example error occurs when an IAM user named marymajor tries to use the console to perform an action in AWS IoT FleetWise. However, the action requires the service to have permissions granted by a service role. Mary does not have permissions to pass the role to the service.
User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole
In this case, Mary asks her administrator to update her policies to allow her to perform the iam:PassRole action.
I want to view my access keys
After you create your IAM user access keys, you can view your access key ID at any time. However, you can't view your secret access key again. If you lose your secret key, you must create a new access key pair.
Access keys consist of two parts: an access key ID (for example, AKIAIOSFODNN7EXAMPLE) and a secret access key (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). Like a user name and password, you must use both the access key ID and secret access key together to authenticate your requests. Manage your access keys as securely as you do your user name and password.
Important Do not provide your access keys to a third party, even to help find your canonical user ID. By doing this, you might give someone permanent access to your account.
When you create an access key pair, you are prompted to save the access key ID and secret access key in a secure location. The secret access key is available only at the time you create it. If you lose your secret access key, you must add new access keys to your IAM user. You can have a maximum of two access keys.
89
AWS IoT FleetWise Developer Guide Monitoring
If you already have two, you must delete one key pair before creating a new one. To view instructions, see Managing access keys in the IAM User Guide.
I'm an administrator and want to allow others to access AWS IoT FleetWise
To allow others to access AWS IoT FleetWise, you must create an IAM entity (user or role) for the person or application that needs access. They will use the credentials for that entity to access AWS. You must then attach a policy to the entity that grants them the correct permissions in AWS IoT FleetWise.
To get started right away, see Creating your first IAM delegated user and group in the IAM User Guide.
I want to allow people outside of my AWS account to access my AWS IoT FleetWise resources
You can create a role that users in other accounts or people outside of your organization can use to access your resources. You can specify who is trusted to assume the role. For services that support resource-based policies or access control lists (ACLs), you can use those policies to grant people access to your resources.
To learn more, consult the following:
· To learn whether AWS IoT FleetWise supports these features, see How AWS IoT FleetWise works with IAM (p. 81).
· To learn how to provide access to your resources across AWS accounts that you own, see Providing access to an IAM user in another AWS account that you own in the IAM User Guide.
· To learn how to provide access to your resources to third-party AWS accounts, see Providing access to AWS accounts owned by third parties in the IAM User Guide.
· To learn how to provide access through identity federation, see Providing access to externally authenticated users (identity federation) in the IAM User Guide.
· To learn the difference between using roles and resource-based policies for cross-account access, see How IAM roles differ from resource-based policies in the IAM User Guide.
Monitoring AWS IoT FleetWise
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 (p. 70).
Monitoring is an important part of maintaining the reliability, availability, and performance of AWS IoT FleetWise and your other AWS solutions. AWS provides the following monitoring tools to watch AWS IoT FleetWise, report when something is wrong, and take automatic actions when appropriate:
· AWS CloudTrail captures API calls and related events made by or on behalf of your AWS account and delivers the log files to an Amazon S3 bucket that you specify. You can identify which users and accounts called AWS, the source IP address from which the calls were made, and when the calls occurred. For more information, see the AWS CloudTrail User Guide.
90
AWS IoT FleetWise Developer Guide CloudTrail logs
Logging AWS IoT FleetWise API calls using AWS CloudTrail
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 (p. 70).
AWS IoT FleetWise is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in AWS IoT FleetWise. CloudTrail captures all API calls for AWS IoT FleetWise as events. The calls captured include calls from the AWS IoT FleetWise console and code calls to the AWS IoT FleetWise API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for AWS IoT FleetWise. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request that was made to AWS IoT FleetWise, the IP address from which the request was made, who made the request, when it was made, and additional details.
To learn more about CloudTrail, see the AWS CloudTrail User Guide.
AWS IoT FleetWise information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS IoT FleetWise, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing Events with CloudTrail Event History.
For an ongoing record of events in your AWS account, including events for AWS IoT FleetWise, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following:
· Overview for creating a trail · CloudTrail supported services and integrations · Configuring Amazon SNS notifications for CloudTrail · Receiving CloudTrail log files from multiple Regions · Receiving CloudTrail log files from multiple accounts
All AWS IoT FleetWise actions are logged by CloudTrail and are documented in the AWS IoT FleetWise API Reference. For example, calls to the CreateCampaign, AssociateVehicle and GetModelManifest actions generate entries in the CloudTrail log files.
Every event or log entry contains information about who generated the request. The identity information helps you determine the following:
· Whether the request was made with root or AWS Identity and Access Management (IAM) user credentials.
· Whether the request was made with temporary security credentials for a role or federated user. · Whether the request was made by another AWS service.
91
AWS IoT FleetWise Developer Guide Compliance Validation
For more information, see the CloudTrail userIdentity element.
Understanding AWS IoT FleetWise log file entries
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 (p. 70).
A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order.
The following example shows a CloudTrail log entry that demonstrates the AssociateVehicle action.
{ "eventVersion": "1.05", "userIdentity": { "type": "AssumedRole", "principalId": "AIDACKCEVSQ6C2EXAMPLE", "arn": "arn:aws:iam::111122223333:assumed-role/NikkiWolf", "accountId": "111122223333", "accessKeyId": "access-key-id", "userName": "NikkiWolf" }, "eventTime": "2021-11-30T09:56:35Z", "eventSource": "iotfleetwise.amazonaws.com", "eventName": "AssociateVehicle", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.21", "userAgent": "aws-cli/2.3.2 Python/3.8.8 Darwin/18.7.0 botocore/2.0.0", "requestParameters": { "fleetId": "f1234567890", "vehicleId": "v0213456789" }, "responseElements": { }, "requestID": "9f861429-11e3-11e8-9eea-0781b5c0ac21", "eventID": "17385819-4927-41ee-a6a5-29ml0br812v4", "eventType": "AwsApiCall", "recipientAccountId": "111122223333"
}
Compliance Validation for AWS IoT FleetWise
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 (p. 70).
92
AWS IoT FleetWise Developer Guide Resilience
Note AWS IoT FleetWise isn't in scope of any AWS compliance programs.
Third-party auditors assess the security and compliance of AWS services as part of multiple AWS compliance programs, such as SOC, PCI, FedRAMP, and HIPAA.
To learn whether AWS IoT FleetWise or other AWS services are in scope of specific compliance programs, see AWS Services in Scope by Compliance Program. For general information, see AWS Compliance Programs.
You can download third-party audit reports using AWS Artifact. For more information, see Downloading Reports in AWS Artifact.
Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. AWS provides the following resources to help with compliance:
· Security and Compliance Quick Start Guides These deployment guides discuss architectural considerations and provide steps for deploying baseline environments on AWS that are security and compliance focused.
· Architecting for HIPAA Security and Compliance Whitepaper This whitepaper describes how companies can use AWS to create HIPAA-compliant applications. Note Not all services are compliant with HIPAA.
· AWS Compliance Resources This collection of workbooks and guides might apply to your industry and location.
· Evaluating Resources with Rules in the AWS Config Developer Guide The AWS Config service assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations.
· AWS Security Hub This AWS service provides a comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices.
· AWS Audit Manager This AWS service helps you continuously audit your AWS usage to simplify how you manage risk and compliance with regulations and industry standards.
Resilience in AWS IoT FleetWise
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 (p. 70).
The AWS global infrastructure is built around AWS Regions and Availability Zones. Regions provide multiple physically separated and isolated Availability Zones, which are connected through low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can design and operate applications and databases that automatically fail over between zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures.
For more information about AWS Regions and Availability Zones, see AWS Global Infrastructure.
93
AWS IoT FleetWise Developer Guide Infrastructure security
Note Data processed by AWS IoT FleetWise is stored in an Amazon Timestream database. Timestream doesn't support backups to other AWS Availability Zones or Regions. However, you can write your own application using the Timestream SDK to query data and save it to the destination of your choice. For more information about Amazon Timestream, see the in the Amazon Timestream Developer Guide.
Infrastructure security in AWS IoT FleetWise
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 (p. 70).
As a managed service, AWS IoT FleetWise is protected by the AWS global network security procedures that are described in the Amazon Web Services: Overview of Security Processes whitepaper.
You use AWS published API calls to access AWS IoT FleetWise through the network. Clients must support Transport Layer Security (TLS) 1.0 or later. We recommend TLS 1.2 or later. Clients must also support cipher suites with perfect forward secrecy (PFS) such as Ephemeral Diffie-Hellman (DHE) or Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7 and later support these modes.
Additionally, requests must be signed using an access key ID and a secret access key that is associated with an IAM principal. Or you can use the AWS Security Token Service (AWS STS) to generate temporary security credentials to sign requests.
Configuration and vulnerability analysis in AWS IoT FleetWise
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 (p. 70).
IoT environments can consist of large numbers of devices that have diverse capabilities, are long-lived, and are geographically distributed. These characteristics make device setup complex and error-prone. Also, because devices are often constrained in computational power, memory, and storage capabilities, the use of encryption and other forms of security on the devices is limited. Devices often use software with known vulnerabilities. These factors make IoT devices, including vehicles collecting data for AWS IoT FleetWise, an attractive target for hackers and make it difficult to secure them on an ongoing basis.
Configuration and IT controls are a shared responsibility between AWS and you, our customer. For more information, see the AWS shared responsibility model.
94
AWS IoT FleetWise Developer Guide Security best practices
Security best practices for AWS IoT FleetWise
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 (p. 70).
AWS IoT FleetWise provides a number of security features to consider as you develop and implement your own security policies. The following best practices are general guidelines and don't represent a complete security solution. Because these best practices might not be appropriate or sufficient for your environment, treat them as helpful considerations rather than prescriptions.
To learn about security in AWS IoT see Security best practices in AWS IoT Core in the AWS IoT Developer Guide
Grant minimum possible permissions
Follow the principle of least privilege by using the minimum set of permissions in IAM roles. Limit the use of the * wildcard for the Action and Resource properties in your IAM policies. Instead, declare a finite set of actions and resources when possible. For more information about least privilege and other policy best practices, see the section called "Policy best practices" (p. 87).
Don't log sensitive information
You should prevent the logging of credentials and other personally identifiable information (PII). We recommend that you implement the following safeguards:
· Don't use sensitive information in device names. · Don't use sensitive information in the names and IDs of AWS IoT FleetWise resources, for example in
the names of campaigns, decoder manifests, vehicle models, and signal catalogs, or the IDs of vehicles and fleets.
Use AWS CloudTrail to view API call history
You can view a history of AWS IoT FleetWise API calls made on your account for security analysis and operational troubleshooting purposes. To receive a history of AWS IoT FleetWise API calls made on your account, simply turn on CloudTrail in the AWS Management Console. For more information, see the section called "CloudTrail logs" (p. 91).
Keep your device clock in sync
It's important to have an accurate time on your device. X.509 certificates have an expiry date and time. The clock on your device is used to verify that a server certificate is still valid. Device clocks can drift over time or batteries can get discharged.
For more information, see the Keep your device's clock in sync best practice in the AWS IoT Core Developer Guide.
95
AWS IoT FleetWise Developer Guide
Document history for the AWS IoT FleetWise Developer Guide
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 (p. 70).
The following table describes the documentation releases for AWS IoT FleetWise.
update-history-change Initial release (p. 96)
update-history-description
Preview release of the AWS IoT FleetWise Developer Guide
update-history-date November 30, 2021
96
Apache FOP Version 2.1