# aws/aws-iot-fleetwise-edge architecture

> Architecture diagram of the GitHub repository aws/aws-iot-fleetwise-edge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/aws-iot-fleetwise-edge
- Repository: https://github.com/aws/aws-iot-fleetwise-edge

## Overview

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: [`src/IoTFleetWiseEngine.cpp`](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/IoTFleetWiseEngine.cpp) (Engine), [`src/CANDecoder.cpp`](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CANDecoder.cpp) (Decoders), [`src/DecoderManifestIngestion.cpp`](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/DecoderManifestIngestion.cpp) (Ingestion), [`src/DataSenderManager.cpp`](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/DataSenderManager.cpp) (Data send)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core engine"]
  node_main(("Main<br/>entrypoint<br/>[main.cpp]"))
  node_engine["Engine<br/>runtime orchestrator"]
  node_ingestion["Ingestion<br/>cloud control-plane"]
  node_schemes["Scheme mgr<br/>policy manager"]
  node_decode["Decoders<br/>signal normalization<br/>[CANDecoder.cpp]"]
  node_inspect["Inspection<br/>trigger engine"]
  node_send["Data send<br/>egress pipeline"]
  node_persist[("Persistency<br/>local buffer<br/>[Persistency.cpp]")]
  node_cmd["Commands<br/>actuation path"]
end

subgraph group_vehicle["Vehicle inputs"]
  node_can["CAN<br/>vehicle bus adapter<br/>[CANDataSource.cpp]"]
  node_obd["OBD<br/>vehicle adapter"]
  node_someip["SOME/IP<br/>vehicle adapter"]
  node_ros2["ROS2<br/>vehicle adapter<br/>[ROS2DataSource.cpp]"]
  node_special["Special sources<br/>sensor adapters"]
end

subgraph group_cloud["Cloud link"]
  node_conn["Connectivity<br/>AWS backends"]
end

subgraph group_features["Optional features"]
  node_lks["Last known<br/>feature branch"]
  node_snf["Store-forward<br/>feature branch<br/>[StreamManager.cpp]"]
  node_custom["Custom funcs<br/>feature branch"]
  node_vision["Vision data<br/>feature branch"]
end

subgraph group_interfaces["Schemas"]
  node_schemas["Wire schemas<br/>protobuf/fidl"]
end

node_main -->|"starts"| node_engine
node_engine -->|"loads"| node_ingestion
node_ingestion -->|"updates"| node_schemes
node_ingestion -.->|"parses"| node_schemas
node_engine -->|"normalizes"| node_decode
node_engine -->|"evaluates"| node_inspect
node_inspect -->|"triggers"| node_send
node_send -->|"publishes"| node_conn
node_send -->|"buffers"| node_persist
node_engine -->|"dispatches"| node_cmd
node_cmd -->|"executes"| node_can
node_cmd -->|"executes"| node_someip
node_can -->|"feeds"| node_decode
node_obd -->|"feeds"| node_decode
node_someip -->|"feeds"| node_decode
node_ros2 -->|"feeds"| node_decode
node_special -->|"feeds"| node_decode
node_engine -.->|"extends"| node_lks
node_engine -.->|"extends"| node_snf
node_engine -.->|"extends"| node_custom
node_engine -.->|"extends"| node_vision
node_conn -.->|"implements"| node_schemas
node_someip -.->|"binds"| node_schemas

click node_main "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/main.cpp"
click node_engine "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/IoTFleetWiseEngine.cpp"
click node_ingestion "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/DecoderManifestIngestion.cpp"
click node_schemes "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CollectionSchemeManager.cpp"
click node_decode "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CANDecoder.cpp"
click node_inspect "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CollectionInspectionEngine.cpp"
click node_send "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/DataSenderManager.cpp"
click node_persist "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/Persistency.cpp"
click node_cmd "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CanCommandDispatcher.cpp"
click node_can "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CANDataSource.cpp"
click node_obd "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/OBDOverCANModule.cpp"
click node_someip "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/SomeipDataSource.cpp"
click node_ros2 "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/ROS2DataSource.cpp"
click node_special "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/NamedSignalDataSource.cpp"
click node_conn "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/AwsIotConnectivityModule.cpp"
click node_lks "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/LastKnownStateIngestion.cpp"
click node_snf "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/snf/StreamManager.cpp"
click node_custom "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CustomFunctionScriptEngine.cpp"
click node_vision "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/VisionSystemDataSender.cpp"
click node_schemas "https://github.com/aws/aws-iot-fleetwise-edge/blob/main/interfaces/protobuf/schemas/cloudToEdge/decoder_manifest.proto"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_engine,node_ingestion,node_schemes,node_decode,node_inspect,node_send,node_persist,node_cmd toneBlue
class node_can,node_obd,node_someip,node_ros2,node_special toneAmber
class node_conn toneMint
class node_lks,node_snf,node_custom,node_vision toneRose
class node_schemas toneIndigo
```

## Components

### Core engine

Main runtime, ingestion, inspection, and egress pipeline.

- [Main](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/main.cpp): entrypoint · Process entrypoint that bootstraps the edge agent and feature modules. · `src/main.cpp`
- [Engine](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/IoTFleetWiseEngine.cpp): runtime orchestrator · Coordinates sources, control-plane ingestion, inspection, senders, and commands. · `src/IoTFleetWiseEngine.cpp`
- [Ingestion](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/DecoderManifestIngestion.cpp): cloud control-plane · Loads decoder manifests and collection schemes from cloud documents. · `src/DecoderManifestIngestion.cpp`
- [Scheme mgr](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CollectionSchemeManager.cpp): policy manager · Manages active collection schemes and their lifecycle. · `src/CollectionSchemeManager.cpp`
- [Decoders](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CANDecoder.cpp): signal normalization · Transforms raw bus payloads into normalized signals and dictionaries. · `src/CANDecoder.cpp`
- [Inspection](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CollectionInspectionEngine.cpp): trigger engine · Evaluates cloud-defined conditions and triggers collection windows. · `src/CollectionInspectionEngine.cpp`
- [Data send](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/DataSenderManager.cpp): egress pipeline · Serializes and forwards telemetry, check-ins, and specialized payloads. · `src/DataSenderManager.cpp`
- [Persistency](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/Persistency.cpp): local buffer · Local caching and store-and-forward support for deferred upload. · `src/Persistency.cpp`
- [Commands](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CanCommandDispatcher.cpp): actuation path · 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](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CANDataSource.cpp): vehicle bus adapter · CAN ingestion and decoding path for in-vehicle signals. · `src/CANDataSource.cpp`
- [OBD](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/OBDOverCANModule.cpp): vehicle adapter · OBD-over-CAN ECU and module integration. · `src/OBDOverCANModule.cpp`
- [SOME/IP](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/SomeipDataSource.cpp): vehicle adapter · SOME/IP data source, bridge, and command integration. · `src/SomeipDataSource.cpp`
- [ROS2](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/ROS2DataSource.cpp): vehicle adapter · ROS2 data source for DDS-backed vehicle or sensor topics. · `src/ROS2DataSource.cpp`
- [Special sources](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/NamedSignalDataSource.cpp): sensor adapters · Named signals, GPS, AAOS VHAL, remote diagnostics, and external CAN inputs. · `src/NamedSignalDataSource.cpp`

### Cloud link

Connectivity modules and outbound sender/receiver paths.

- [Connectivity](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/AwsIotConnectivityModule.cpp): AWS backends · 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](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/LastKnownStateIngestion.cpp): feature branch · Last known state ingestion, inspection, and specialized sender path. · `src/LastKnownStateIngestion.cpp`
- [Store-forward](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/snf/StreamManager.cpp): feature branch · Stream buffering, file system storage, and deferred forwarding. · `src/snf/StreamManager.cpp`
- [Custom funcs](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/CustomFunctionScriptEngine.cpp): feature branch · Script and math engines for custom function evaluation. · `src/CustomFunctionScriptEngine.cpp`
- [Vision data](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/src/VisionSystemDataSender.cpp): feature branch · Vision-system payload serialization and upload path. · `src/VisionSystemDataSender.cpp`

### Schemas

Public interfaces and wire-format definitions.

- [Wire schemas](https://github.com/aws/aws-iot-fleetwise-edge/blob/main/interfaces/protobuf/schemas/cloudToEdge/decoder_manifest.proto): protobuf/fidl · Cloud-to-edge, edge-to-cloud, SOME/IP, persistency, and UDS-DTC schemas. · `interfaces/protobuf/schemas/cloudToEdge/decoder_manifest.proto`

## Connections

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