# eclipse-kuksa/kuksa-can-provider architecture

> Architecture diagram of the GitHub repository eclipse-kuksa/kuksa-can-provider, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eclipse-kuksa/kuksa-can-provider
- Repository: https://github.com/eclipse-kuksa/kuksa-can-provider

## Overview

##### Project Type and Purpose
- This is a standalone Python “provider” service that sits between a CAN bus (or a replayed CAN dump) and the KUKSA ecosystem (Server and/or Databroker).
- It supports two modes:
- dbc2val – reads raw CAN frames, parses via a DBC file, maps to VSS signals, and pushes into KUKSA Server/Databroker.
- val2dbc – subscribes to VSS signals on the Databroker, maps back to DBC signals, and sends CAN frames onto the bus.

##### Top-Level Architectural Components
File tree and README to see these key parts:
- Entrypoint script: dbcfeeder.py
- Core library package: dbcfeederlib/
- Config and mapping:
- config/ (INIs, default JSONs)
- mapping/vss_*/ (per-version mapping JSONs + overlay specs)
- External interfaces:
- SocketCAN (or virtual CAN via createvcan.sh)
- CAN dump files (candump.log, candump-*.xz)
- ELM/OBDLink and J1939 support modules
- External services:
- KUKSA Server
- KUKSA Databroker
- Dockerfile and CI workflows (for containerization and testing).

##### Main System Components (to represent
a. CAN Input Layer
- SocketCAN interface or replay engine (CAN player).
- Optionally ELM/OBDLink and SAE-J1939 readers.
b. CAN Provider Core
- CLI/Controller (dbcfeeder.py)
- CAN Reader/Player (canreader, canplayer)
- DBC Reader & Parser (dbcreader, dbcparser, dbc2vssmapper)
- Mapping Engine (uses vss_dbc.json and default values JSON)
- Message Builder (canmessage)
c. Client Wrappers
- KUKSA Databroker client wrapper
- KUKSA Server client wrapper
- Databroker subscription loop (for val2dbc mode)
d. External Services
- KUKSA Server
- KUKSA Databroker
e. Configuration & Mapping Artifacts
- config/*.ini, dbc_default_values.json
- mapping/vss_*.json & overlay.vspec files

##### Interactions and Data Flows
- **dbc2val mode** (CAN → KUKSA):
1. CAN frames arrive via SocketCAN or replay stream
2. Frames passed to CAN Reader → parsed by DBC Parser
3. Parsed signals fed into Mapper → VSS datapoints
4. Client Wrapper sends datapoints to KUKSA Server or Databroker
- **val2dbc mode** (KUKSA → CAN):
1. Databroker client subscribes to VSS signals
2. Incoming values go into Mapper, merged with default values
3. CAN message builder assembles frames
4. CAN Client sends frames onto SocketCAN

##### Architectural Patterns & Principles
- Modular layering: input readers, processing/parsing layer, mapping layer, output clients
- Configuration-driven: mapping and defaults are external JSON/INI, not hard-coded
- Test harness in test/ covering all modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External CAN Source
    Source["SocketCAN / Replay File"]:::external

    subgraph "CAN Input Layer"
        direction TB
        CR["CAN Reader"]:::can
        CP["CAN Player"]:::can
        ELM["ELM/OBDLink Bridge"]:::can
        J193["SAE-J1939 Reader"]:::can
    end

    subgraph "Core Processor"
        direction TB
        CLI["CLI/Controller\n(dbcfeeder.py)"]:::core
        DBCR["DBC Reader"]:::core
        DBCP["DBC Parser"]:::core
        MAP["DBC→VSS Mapper"]:::core
        MB["Message Builder"]:::core
    end

    subgraph "KUKSA Clients"
        direction TB
        DCW["Databroker Client Wrapper"]:::client
        SCW["Server Client Wrapper"]:::client
    end

    subgraph "Config & Mapping"
        direction TB
        CFG["INI Config\n(dbc_feeder.ini)"]:::config
        DEF["Default Values\n(dbc_default_values.json)"]:::config
        subgraph "Mapping Artifacts"
            direction TB
            M30["vss_3.0"]:::config
            M311["vss_3.1.1"]:::config
            M40["vss_4.0"]:::config
            M41["vss_4.1"]:::config
            M42["vss_4.2"]:::config
        end
    end

    %% External Services
    KServer["KUKSA Server"]:::external
    KDB["KUKSA Databroker"]:::external

    %% Data Flows: dbc2val
    Source -->|raw CAN frames| CR
    Source -->|replay frames| CP
    CR --> DBCR
    CP --> DBCR
    DBCR --> DBCP
    DBCP --> MAP
    MAP -->|VSS datapoints| DCW
    MAP -->|VSS datapoints| SCW
    DCW --> KDB
    SCW --> KServer

    %% Data Flows: val2dbc
    KDB -->|VSS subscription| DCW
    DCW --> MAP
    MAP --> MB
    MB -->|CAN frames| CP
    CP --> Source

    %% Configuration Injection
    CFG -.-> CLI
    DEF -.-> MAP
    M30 -.-> MAP
    M311 -.-> MAP
    M40 -.-> MAP
    M41 -.-> MAP
    M42 -.-> MAP

    %% Click Events
    click CLI "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeeder.py"
    click CR "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/canreader.py"
    click CP "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/canplayer.py"
    click ELM "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/elm2canbridge.py"
    click J193 "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/j1939reader.py"
    click DBCR "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/dbcreader.py"
    click DBCP "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/dbcparser.py"
    click MAP "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/dbc2vssmapper.py"
    click MB "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/canmessage.py"
    click DCW "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/databrokerclientwrapper.py"
    click SCW "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbcfeederlib/serverclientwrapper.py"
    click CFG "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/config/dbc_feeder.ini"
    click DEF "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/dbc_default_values.json"
    click M30 "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/mapping/vss_3.0"
    click M311 "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/mapping/vss_3.1.1"
    click M40 "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/mapping/vss_4.0"
    click M41 "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/mapping/vss_4.1"
    click M42 "https://github.com/eclipse-kuksa/kuksa-can-provider/blob/main/mapping/vss_4.2"

    %% Styles
    classDef can fill:#E0F7FA,stroke:#006064,color:#006064
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef client fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef config fill:#F5F5F5,stroke:#616161,color:#424242
    classDef external fill:#ECEFF1,stroke:#37474F,color:#37474F
```
