# fzi-forschungszentrum-informatik/cohda_v2x_driver architecture

> Architecture diagram of the GitHub repository fzi-forschungszentrum-informatik/cohda_v2x_driver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fzi-forschungszentrum-informatik/cohda_v2x_driver
- Repository: https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver

## Overview

##### Project type and its purpose
- This is a Python “driver” library for interacting with COHDA MK6 devices over the BTP (Binary Transport Protocol).
- It provides message-encoding/decoding for ETSI V2X PDUs (CAM, CPM, MAPEM, SPATEM) based on ASN.1 specs.
- Example scripts demonstrate how to send/receive these messages.

##### Main components
a. Examples Layer
– cam_handler_mk6.py, cpm_handler_mk6.py, mapem_handler_mk6.py
– Configuration files under examples/conf (e.g., rsu.conf)
b. Driver Library (package: cohda_driver)
– Entry point: driver.py (initializes BTP connection, loads config)
– btp_request.py (wraps outgoing PDUs into BTP requests)
– btp_indication.py (parses incoming BTP indications)
– common_header.py (shared ASN.1 header logic)
– etsi_message_type.py (enumerates ETSI message types)
– logger.py (colorlog-based logging)
– etsi_messages/*.py (CAM, CPM, MAPEM, SPATEM message classes)
c. ASN.1 Repository
– asn1/… (multiple .asn files for CAM, CPM, MAPEM, SPATEM under their respective folders)
d. ASN.1 Parser
– asn1tools library (runtime dependency)
– dataclasses-struct (for C-struct-like dataclasses)
e. COHDA MK6 Device
– Physical or simulated device reachable over network/serial port
f. External Dependencies
– Python packages (asn1tools, colorlog, dataclasses-struct)
– ETSI ASN.1 specifications

##### Relationships and data flows
1. Examples → Driver Library
- The user runs an example script; it loads a config file and instantiates driver.py
2. Driver Library ↔ COHDA MK6 Device
- driver.py uses BTP connection to send/receive raw bytes
3. Driver Library → ASN.1 Parser
- Outgoing: btp_request.py hands off an ETSI PDU (Python dataclass) to asn1tools for encoding
- Incoming: btp_indication.py receives raw bytes, calls asn1tools to decode into Python objects
4. Driver Library → Application Layer
- Parsed messages are exposed back to the example script via callbacks or return values

##### Architectural patterns and principles
- Layered architecture:
– Presentation (Examples)
– Application (Driver API)
– Integration (ASN.1 parser, BTP transport)
- Facade pattern: driver.py presents a simple interface over low-level BTP + ASN.1 complexity
- Separation of concerns: encoding/decoding logic lives in etsi_messages + asn1tools, transport logic in btp_*.py

##### Must-have elements
- Config files (.conf) feeding into driver initialization

[Examples Layer]
┌────────────────────────┐
│ cam_handler_mk6.py     │
│ cpm_handler_mk6.py     │
│ mapem_handler_mk6.py   │
└───▲────────────────────┘
│ loads config rsu.conf
│ calls API
┌───┴────────────────────┐
│ Driver Library         │
│ ┌───────────────┐      │
│ │ driver.py     │      │
│ ├───────────────┤      │
│ │ btp_request   │      │
│ │ btp_indication│      │
│ │ logger        │      │
│ │ etsi_messages │      │
│ └──▲────────────┘      │
│    │ uses                │
└───┴────────────────────┘
│ calls encode/decode
┌───▼────────────────────┐
│ ASN.1 Parser (asn1tools) │
└───▲────────────────────┘
│ reads .asn files from asn1/ tree
┌───┴────────────────────┐
│ ASN.1 Specs (.asn files)│
└─────────────────────────┘

┌────────────────────────┐
│ COHDA MK6 Device        │
└────────────────────────┘
▲ send/receive BTP bytes
└────────────────────┘

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Examples Layer
    subgraph "Examples Layer"
        direction TB
        CAM["cam_handler_mk6.py"]:::internal
        CPM["cpm_handler_mk6.py"]:::internal
        MAPEM_EX["mapem_handler_mk6.py"]:::internal
        CONF["rsu.conf"]:::config
    end

    %% Driver Library
    subgraph "Driver Library" 
        direction TB
        DRIVER["driver.py"]:::internal
        BTP_REQ["btp_request.py"]:::internal
        BTP_IND["btp_indication.py"]:::internal
        HEADER["common_header.py"]:::internal
        MSG_TYPE["etsi_message_type.py"]:::internal
        LOGGER["logger.py"]:::internal
        subgraph "ETSI Messages"
            direction TB
            CAM_MSG["cam.py"]:::internal
            CPM_MSG["cpm.py"]:::internal
            HDR_MSG["its_pdu_header.py"]:::internal
            MAPEM_MSG["mapem.py"]:::internal
            SPATEM_MSG["spatem.py"]:::internal
        end
    end

    %% ASN.1 Parser
    subgraph "ASN.1 Parser" 
        direction TB
        ASN1TOOLS["asn1tools"]:::external
        DATASTRUCT["dataclasses-struct"]:::external
    end

    %% ASN.1 Specs
    subgraph "ASN.1 Specs" 
        direction TB
        CAM_SPEC["asn1/cam/"]:::specs
        CPM_SPEC["asn1/cpm_tr103562/"]:::specs
        MAPEM_SPEC["asn1/mapem/"]:::specs
        SPATEM_SPEC["asn1/spatem/"]:::specs
    end

    %% Device
    DEVICE["COHDA MK6 Device"]:::physical

    %% Connections
    CAM -->|loads config| DRIVER
    CPM -->|loads config| DRIVER
    MAPEM_EX -->|loads config| DRIVER
    CONF -->|provides settings| DRIVER

    DRIVER -->|"BTP request (bytes)"| BTP_REQ
    DRIVER -->|"BTP indication (bytes)"| BTP_IND
    DRIVER -->|"uses header logic"| HEADER
    DRIVER -->|"enumerates messages"| MSG_TYPE
    DRIVER -->|"logs events"| LOGGER
    BTP_REQ -->|hand off PDU| ASN1TOOLS
    BTP_IND -->|decode bytes| ASN1TOOLS
    ASN1TOOLS -->|returns objects| DRIVER
    DATASTRUCT -.->|used for dataclasses| DRIVER

    ASN1TOOLS -->|"reads specs"| CAM_SPEC
    ASN1TOOLS -->|"reads specs"| CPM_SPEC
    ASN1TOOLS -->|"reads specs"| MAPEM_SPEC
    ASN1TOOLS -->|"reads specs"| SPATEM_SPEC

    DRIVER <-->|"send/receive BTP"| DEVICE
    DRIVER -->|"returns PDU dataclass"| CAM
    DRIVER -->|"returns PDU dataclass"| CPM
    DRIVER -->|"returns PDU dataclass"| MAPEM_EX

    %% Click Events
    click CAM "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/examples/cam_handler_mk6.py"
    click CPM "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/examples/cpm_handler_mk6.py"
    click MAPEM_EX "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/examples/mapem_handler_mk6.py"
    click CONF "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/examples/conf/rsu.conf"
    click DRIVER "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/driver.py"
    click BTP_REQ "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/btp_request.py"
    click BTP_IND "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/btp_indication.py"
    click HEADER "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/common_header.py"
    click MSG_TYPE "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/etsi_message_type.py"
    click LOGGER "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/logger.py"
    click CAM_MSG "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/etsi_messages/cam.py"
    click CPM_MSG "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/etsi_messages/cpm.py"
    click HDR_MSG "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/etsi_messages/its_pdu_header.py"
    click MAPEM_MSG "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/etsi_messages/mapem.py"
    click SPATEM_MSG "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/blob/master/src/cohda_driver/etsi_messages/spatem.py"
    click CAM_SPEC "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/tree/master/asn1/cam/"
    click CPM_SPEC "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/tree/master/asn1/cpm_tr103562/"
    click MAPEM_SPEC "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/tree/master/asn1/mapem/"
    click SPATEM_SPEC "https://github.com/fzi-forschungszentrum-informatik/cohda_v2x_driver/tree/master/asn1/spatem/"

    %% Styles
    classDef internal fill:#87CEFA,stroke:#1E90FF,color:#000000
    classDef external fill:#98FB98,stroke:#2E8B57,color:#000000
    classDef physical fill:#FFA500,stroke:#FF8C00,color:#000000
    classDef config fill:#D3D3D3,stroke:#A9A9A9,color:#000000
    classDef specs fill:#D3D3D3,stroke:#A9A9A9,color:#000000
```
