Reference Implementation for AWS IoT FleetWise

AWS IoT FleetWise now supports:

• :mechanical_arm: Remote commands for actuators, see the CAN actuators guide and the SOME/IP guide.
• :electric_plug: Network agnostic data collection and actuator commands.
• :red_car: SOME/IP support, see:
  • the SOME/IP guide for data collection and commands,
  • the Device shadow proxy for SOME/IP guide,
  • and the CAN over SOME/IP guide.
• :abc: String datatype support for both sensor data collection and actuator commands.
• :feather: Last Known State (LKS), a lighter method of data collection.
• :cloud: IoT topics as a data destination.
• :jigsaw: Custom functions in expressions.
  • :snake: including Python support.
• :fast_forward: Store and forward, for conditional upload of collected data.
• :wrench: UDS DTC data collection.
• :books: Usage as an external library, see the examples.

[!NOTE] To quickly get started, jump to the Edge Agent Developer Guide, the ROS2 developer guide, the Android Guide, or the Raspberry Pi Tutorial.

AWS IoT FleetWise is a service that makes it easy for Automotive OEMs, Fleet operators, Independent Software vendors (ISVs) to collect, store, organize, and monitor data from vehicles at scale. The Reference Implementation for AWS IoT FleetWise (“FWE”) provides C++ libraries that can be run with simulated vehicle data on certain supported vehicle hardware or that can help you develop an Edge Agent to run an application on your vehicle that integrates with AWS IoT FleetWise. You can then use AWS IoT FleetWise’s to process the collected data, gain insights about the vehicle’s health and use the service’s visual interface to help diagnose and troubleshoot potential issues with your vehicles. Furthermore, AWS IoT FleetWise’s capability to collect ECU data and store them on cloud databases enables you to utilize different AWS services (Analytics Services, ML, etc.) to develop novel use-cases that augment your existing vehicle functionality. In particular, AWS IoT FleetWise can leverage fleet data (Big Data) and enable you to develop use cases that create business value, for example: improve electric vehicle range estimation, optimized battery life charging, optimized vehicle routing, etc. AWS IoT FleetWise can be extended to utilize cloud computing capabilities for use-cases such as helping to improve pet/child detection, Driver Monitoring System applications, Predictive Diagnostics, electric vehicle’s battery cells outlier detection, etc. You can use the included sample C++ application to learn more about the FWE, develop an Edge Agent for your use case and test interactions before integration.

[!IMPORTANT] As provided in the AWS IoT FleetWise Service Terms, you are solely responsible for your Edge Agent, including ensuring that your Edge Agent and any updates and modifications to it are deployed and maintained safely and securely in any vehicles.

AWS IoT FleetWise Architecture

AWS IoT FleetWise is an AWS service that enables automakers and fleet operators to collect, store, organize, and monitor data from vehicles. Automakers need the ability to connect remotely to their fleet of vehicles and collect vehicle ECU/sensor data. AWS IoT FleetWise can be used by OEM engineers and data scientists to build vehicle models that can be used to build custom data collection schemes. These data collection schemes enables the OEM to optimize the data collection process by defining what signals to collect, how often to collect them, and most importantly the trigger conditions (“events”) that enable the collection process.

Customers can define the data collection schemes to trigger based on a schedule or on specific conditions such as, but not limited to: 1. Ambient temperature dropping to below 0 degree or 2. Vehicle crosses state lines or 3. Active diagnostic trouble codes. These conditions are sent to the vehicle through a set of documents called data collection schemes. In summary, your Edge Agent collects the data of interest according to the data collection schemes and decoding rules as specified by the OEM on the AWS IoT FleetWise Console.

The following diagram illustrates a high-level architecture of the system.

FWE receives two documents:

1. Decoder Manifest - this document describes how signals are collected from the vehicle, and will include details such as, but not limited to: Bus ID, network name, decoding information, etc.

2. Data Collection Schemes - this document describes what signals to collect. It also describes the condition logic that defines the enablement of the trigger logic that allows these signals to be collected, for example, when Vehicle Speed > 100 km/Hr and Driver Seatbelt is Off and Ambient Temperature < 0 degree C.

FWE Deployment & Supported Platforms

The functional flexibility of FWE and its use of dynamic memory allocation means that it cannot reside in the real-time safety vehicle ECUs. FWE must also be connected to the internet and preferably has access to a “good” portion of vehicle ECU data. OEMs have the flexibility to decide where they can deploy their Edge Agent binary. Possible options include (if present):

1. Vehicle Gateway such as the NXP S32G and Renesas R-Car S4
2. Vehicle Head-Unit
3. Vehicle’s High Performance Computer
4. Telecommunication Control Unit

FWE was built and tested on 64-bit architectures. It has been tested on both ARM and X86 multicore based machines, with a Linux Kernel version of 5.4 and above. The kernel module for ISO-TP (can-isotp) would need to be installed in addition for Kernels below 5.10.

FWE was also tested on an EC2 Instance with the following details:

• Platform: Ubuntu
• Platform Details: Linux/UNIX
• Server: AmazonEC2
• InstanceType: c4.8xlarge
• AvailabilityZone: us-east-1
• Architecture: x86_64
• CpuOptions: {‘CoreCount’: 18, ‘ThreadsPerCore’: 2}
• AMI name: ubuntu-focal-20.04-amd64-server-20230112

AWS IoT FleetWise Client-Server Communication

FWE depends on the AWS SDK for C++ to send and receive data from and to AWS IoT FleetWise Server. All data sent to the AWS IoT FleetWise server is sent over an encrypted TLS connection using MQTT, which is designed to make it secure by default while in transit. FWE uses MQTT quality of service one (QoS = 1).

Security

See SECURITY for more information

License Summary and Build Dependencies

FWE depends on the following open source libraries. Refer to the corresponding links for more information.

• AWS SDK for C++: v1.11.284
  • Curl: v7.58.0
  • OpenSSL: v1.1.1
  • zlib: v1.2.11
• GoogleTest: v1.15.2
• Google Benchmark: v1.6.1
• Protobuf: v3.21.12
• Boost: v1.84.0
• JsonCpp: v1.9.5
• Snappy: v1.1.8

Optional: The following dependencies are only required when the option FWE_FEATURE_GREENGRASSV2 is enabled.

• AWS IoT Device SDK for C++ v2: v1.32.2

Optional: The following dependencies are only required when the option FWE_FEATURE_VISION_SYSTEM_DATA is enabled.

• Amazon Ion: v1.1.2

Optional: The following dependencies are only required when the option FWE_FEATURE_ROS2 is enabled.

• ROS2: Galactic
• Cyclone DDS: 0.8.0
• Fast-CDR: v1.0.21

Optional: The following dependencies are only required when the option FWE_FEATURE_SOMEIP is enabled.

• vsomeip: 3.5.1
• CommonAPI C++ Core Runtime: 3.2.4
• CommonAPI C++ SOME/IP Runtime: 3.2.4

Optional: The following dependencies are only required when the option FWE_FEATURE_STORE_AND_FORWARD is enabled.

• device-storelibrary-cpp: v1.0.0

Optional: The following dependencies are only required when the option FWE_FEATURE_CPYTHON is enabled.

• CPython: v3.8.10

Optional: The following dependencies are only required when the option FWE_FEATURE_MICROPYTHON is enabled.

• MicroPython: v1.23.0

See LICENSE for more information.

Getting Help

Contact AWS Support if you have any technical questions about FWE.

Metrics

See Metrics for details, which Edge specific metrics exist and how they can be accessed.

Resources

The following documents provide more information about FWE.

1. Change Log provides a summary of feature enhancements, updates, and resolved and known issues.
2. Offboarding and Data Deletion provides a summary of the steps needed on the client side to offboard from the service.
3. Edge Agent Developer Guide provides step-by-step instructions for building and running your Edge Agent.

The following documents provide more information about the cloud component of AWS IoT FleetWise.

1. AWS IoT FleetWise API Reference describes all the API operations for FleetWise

Contributing Guidelines

Thank you for your interest in contributing to our project. Whether it’s a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn’t already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

• A reproducible test case or series of steps
• The version of our code being used
• Any modifications you’ve made relevant to the bug
• Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

1. You are working against the latest source on the main branch.
2. You check existing open, and recently merged, pull requests to make sure someone else hasn’t addressed the problem already.
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

1. Fork the repository.
2. Install pre-commit and run pre-commit install. This will ensure all your changes are properly formatted before committing.
3. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
4. Ensure local tests pass.
5. Commit to your fork using clear commit messages.
6. Send us a pull request, answering any default questions in the pull request interface.
7. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional document on forking a repository and creating a pull request.

Finding contributions to work on

Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ‘help wanted’ issues is a great place to start.

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

Licensing

See the LICENSE file for our project’s licensing. We will ask you to confirm the licensing of your contribution.