How aws/aws-iot-fleetwise-edge works
1. What this repository is
- This is the C++ reference implementation of the AWS IoT FleetWise edge agent.
- The binary is an on-vehicle data collector/command executor that sits between vehicle buses and AWS cloud services.
- The main runtime entrypoint is src/main.cpp, which wires together the edge agent engine and optional feature modules.
2. Top-level architecture
- The core application is centered around IoTFleetWiseEngine with supporting subsystems in src/ and public interfaces in include/aws/iotfleetwise/.
- The design is layered: vehicle data sources at the bottom, decoding/inspection in the middle, and cloud connectivity plus upload/command handling at the top.
- Feature flags and optional dependencies materially change the shape of the runtime: Greengrass V2, SOME/IP, ROS2, store-and-forward, custom functions, CPython/MicroPython, and vision-system data.
3. Cloud control-plane ingestion
- The edge agent receives two main cloud documents: Decoder Manifests and Collection Schemes.
- Those are represented by ingestion and schema classes such as DecoderManifestIngestion, CollectionSchemeIngestion, CollectionSchemeManager, and the protobuf schema files under interfaces/protobuf/schemas/cloudToEdge/.
- This control plane defines what to collect, how to decode it, and when to trigger collection.
4. Vehicle data sources and adapters
- Vehicle data enters through source-specific adapters: CAN, OBD-over-CAN, SOME/IP, ROS2, GPS, Android/Aaos VHAL, remote diagnostics, and custom sources.
- Representative classes include CANDataSource, OBDOverCANModule, SomeipDataSource, ROS2DataSource, AaosVhalSource, ExternalGpsSource, and NamedSignalDataSource.
- These adapters isolate platform- and bus-specific integration from the rest of the engine.
5. Decoding and signal normalization
- Raw bus payloads are converted into normalized signals using decoder logic in CANDecoder, OBDDataDecoder, DecoderDictionaryExtractor, and schema abstractions like IDecoderManifest and IDecoderDictionary.
- Interface definitions in interfaces/protobuf/schemas/cloudToEdge/ and interfaces/someip/fidl/ drive how vehicle signals are described.
- This boundary is important for architecture diagrams because it is where bus-specific data becomes engine-readable signal events.
6. Collection evaluation and trigger execution
- The heart of collection logic is CollectionInspectionEngine, supported by CollectionInspectionWorkerThread, InspectionMatrixExtractor, and CollectionSchemeManager.
- Cloud-defined conditions are evaluated against live signals to decide when to start/stop collection and which signals to sample.
- This is the main decision-making subsystem between data ingestion and data upload.
7. Output and cloud egress
- Collected telemetry is serialized and sent through DataSenderManager and related writers such as DataSenderProtoWriter and DataSenderIonWriter.
- Specific sender paths exist for telemetry, check-ins, last known state, command responses, S3 uploads, and vision-system data.
- Networking backends are abstracted behind modules like AwsIotConnectivityModule, AwsGreengrassV2ConnectivityModule, AwsIotSender, AwsIotReceiver, AwsGreengrassV2Sender, and AwsGreengrassV2Receiver.
8. Command and actuation path
- Remote commands flow from cloud documents into dispatchers such as CanCommandDispatcher, SomeipCommandDispatcher, and ActuatorCommandManager.
- The repository supports CAN actuators, SOME/IP commands, and command response publication back to the cloud.
- This is a separate control path from telemetry upload and should be shown as cloud-to-vehicle, not just vehicle-to-cloud.
9. Store-and-forward and persistence
- The optional store-and-forward feature is implemented under src/snf/ and include/aws/iotfleetwise/snf/.
- It uses local filesystem storage and stream management to buffer data when immediate upload is not possible, then forward it later.
- Persistent/local buffering also appears in CacheAndPersist, Persistency.cpp, and supporting filesystem abstractions.
10. Specialized feature subsystems
- Last Known State: LastKnownStateIngestion, LastKnownStateInspector, LastKnownStateWorkerThread, and LastKnownStateDataSender.
- Custom functions: script/math engines via CustomFunctionScriptEngine, CustomFunctionCPython, CustomFunctionMicroPython, and CustomFunctionMath.
- Vision system data: VisionSystemDataSender with protobuf/Ion-related payload handling.
- Remote profiler / diagnostics: RemoteProfiler, RemoteDiagnosticDataSource, and UDS DTC support.
- These are feature-specific branches off the same ingestion/inspection/send pipeline.
11. Platform and integration boundaries
- The code is intended for embedded Linux on automotive compute platforms such as NXP S32G, Renesas R-Car S4, head units, HPCs, and TCU-style deployments.
- AWS dependencies are important to the architecture: AWS SDK for C++ for MQTT/TLS communication, and optionally AWS IoT Device SDK v2 for Greengrass V2.
- Optional runtime integrations include vsomeip/CommonAPI, ROS2/Cyclone DDS, Amazon Ion, CPython, and MicroPython.
12. Build, packaging, and deployment layout
- The project is CMake-based, with optional feature toggles and dependency setup in CMakeLists.txt and cmake/.
- Deployment helpers live in tools/ for native, cross-compiled, containerized, Yocto, Android, and Greengrass V2 packaging.
- configuration/static-config.json and the interfaces/ directory define runtime configuration and wire formats.
13. Validation and example topology
- test/unit/ covers core subsystems; test/system/ exercises end-to-end scenarios using simulated vehicles, cloud tooling, and external services.
- examples/ contains minimal integration samples for custom functions, MQTT pub/sub, SOME/IP, network-agnostic data collection, S3 upload, and CAN-related flows.
- For an architecture diagram, these examples are useful as concrete instances of the same core engine with different source/sink combinations.
14. Mental model for diagramming
- Draw the system as: vehicle sources → adapters/decoders → collection and inspection engine → senders/persistency → AWS cloud, with a separate cloud command path → dispatchers → vehicle actuators.
- Then overlay optional feature branches for SOME/IP, ROS2, Greengrass V2, store-and-forward, last known state, and custom scripting.
- The clearest subsystem boundaries are “source adapters,” “schema/decoder ingestion,” “inspection/triggering,” “serialization/egress,” and “command execution.”
Main entry points: IoTFleetWiseEngine.cpp Engine · CANDecoder.cpp Decoders · DecoderManifestIngestion.cpp Ingestion · DataSenderManager.cpp Data send
Components 20
Core engine
Main runtime, ingestion, inspection, and egress pipeline.
- Main · Process entrypoint that bootstraps the edge agent and feature modules.
src/main.cpp - Engine · Coordinates sources, control-plane ingestion, inspection, senders, and commands.
src/IoTFleetWiseEngine.cpp - Ingestion · Loads decoder manifests and collection schemes from cloud documents.
src/DecoderManifestIngestion.cpp - Scheme mgr · Manages active collection schemes and their lifecycle.
src/CollectionSchemeManager.cpp - Decoders · Transforms raw bus payloads into normalized signals and dictionaries.
src/CANDecoder.cpp - Inspection · Evaluates cloud-defined conditions and triggers collection windows.
src/CollectionInspectionEngine.cpp - Data send · Serializes and forwards telemetry, check-ins, and specialized payloads.
src/DataSenderManager.cpp - Persistency · Local caching and store-and-forward support for deferred upload.
src/Persistency.cpp - Commands · Dispatches remote commands to vehicle-specific executors.
src/CanCommandDispatcher.cpp
Vehicle inputs
Adapters and sources that bring data from vehicle buses and local sensors.
- CAN · CAN ingestion and decoding path for in-vehicle signals.
src/CANDataSource.cpp - OBD · OBD-over-CAN ECU and module integration.
src/OBDOverCANModule.cpp - SOME/IP · SOME/IP data source, bridge, and command integration.
src/SomeipDataSource.cpp - ROS2 · ROS2 data source for DDS-backed vehicle or sensor topics.
src/ROS2DataSource.cpp - Special sources · Named signals, GPS, AAOS VHAL, remote diagnostics, and external CAN inputs.
src/NamedSignalDataSource.cpp
Cloud link
Connectivity modules and outbound sender/receiver paths.
- Connectivity · AWS IoT and Greengrass V2 connection modules plus MQTT/TLS transport.
src/AwsIotConnectivityModule.cpp
Optional features
Feature-specific branches that extend the main pipeline.
- Last known · Last known state ingestion, inspection, and specialized sender path.
src/LastKnownStateIngestion.cpp - Store-forward · Stream buffering, file system storage, and deferred forwarding.
src/snf/StreamManager.cpp - Custom funcs · Script and math engines for custom function evaluation.
src/CustomFunctionScriptEngine.cpp - Vision data · Vision-system payload serialization and upload path.
src/VisionSystemDataSender.cpp
Schemas
Public interfaces and wire-format definitions.
- Wire schemas · Cloud-to-edge, edge-to-cloud, SOME/IP, persistency, and UDS-DTC schemas.
interfaces/protobuf/schemas/cloudToEdge/decoder_manifest.proto
Connections 23
- Main → Engine: starts · Main wires and launches the runtime engine.
- Engine → Ingestion: loads · Engine ingests decoder manifests and collection schemes from cloud documents.
- Ingestion → Scheme mgr: updates · Ingestion populates the active collection-scheme manager.
- Ingestion → Wire schemas: parses · Control-plane documents are defined by protobuf schema files.
- Engine → Decoders: normalizes · Decoded dictionaries and payloads are converted into engine-readable signals.
- Engine → Inspection: evaluates · Inspection engine applies collection rules to live signals.
- Inspection → Data send: triggers · Triggered collections are serialized for cloud upload.
- Data send → Connectivity: publishes · Sender paths use AWS connectivity backends.
- Data send → Persistency: buffers · Optional buffering and store-and-forward route through local persistence.
- Engine → Commands: dispatches · Remote command requests are routed to actuator dispatchers.
- Commands → CAN: executes · CAN commands are delivered through CAN-specific pathways.
- Commands → SOME/IP: executes · SOME/IP commands are delivered through SOME/IP pathways.
- CAN → Decoders: feeds · CAN payloads are decoded into normalized signals.
- OBD → Decoders: feeds · OBD data is decoded into engine signals.
- SOME/IP → Decoders: feeds · SOME/IP messages are converted into signals.
- ROS2 → Decoders: feeds · ROS2 topics enter the same signal normalization boundary.
- Special sources → Decoders: feeds · Specialized adapters contribute signals to the decoder layer.
- Engine → Last known: extends · Last known state adds a parallel ingestion/inspection/sender branch.
- Engine → Store-forward: extends · Store-and-forward augments outbound data handling.
- Engine → Custom funcs: extends · Custom functions are evaluated as optional signal-processing logic.
- Engine → Vision data: extends · Vision-system payloads are an optional specialized egress path.
- Connectivity → Wire schemas: implements · Cloud connectivity uses the edge-to-cloud and cloud-to-customer wire formats.
- SOME/IP → Wire schemas: binds · SOME/IP integration is described by FIDL and related interface files.