# polysync/oscc architecture

> Architecture diagram of the GitHub repository polysync/oscc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polysync/oscc
- Repository: https://github.com/polysync/oscc

## Overview

##### Project Type & Purpose
- OSCC is an embedded‐to‐host control platform enabling computer control of vehicles via CAN.
- It consists of:
- A host‐side C API (api/) that uses SocketCAN to send/receive CAN frames.
- Multiple Arduino‐based firmware modules (firmware/) for throttle, steering, brake (EV & petrol), and a CAN gateway.
- Board definitions and hardware artifacts (hardware/) for sensor interface boards, actuator control boards, etc.
- Utility tools (utils/) for diagnostics and consensus.
- It is an open‐source toolchain bridging PC software and vehicle control ECUs.

##### File Structure Analysis & Architectural Boundaries
- Top level:
- api/ – OSCC C API (include/ & src/).
- firmware/ – Per‐module Arduino firmware (brake, throttle, steering, can_gateway), shared libraries (common/), and CMake toolchain helpers.
- hardware/ – PCB schematics, EDA files, 3D models.
- utils/ – diagnostics_tool and consensus helper scripts.
- .github, Dockerfile, Jenkinsfile, CI & contribution docs.
- Architectural pattern: layered & modular. Each firmware module is a standalone Arduino application published on a common CAN bus. The host API isolates CAN transport and exposes high‐level commands & callbacks.

##### Key Components
- Host Layer:
- Your application using oscc_open/enable/publish_xxx/subscribe_xxx.
- OSCC API library (C code in api/src + vehicle headers in api/include/vehicles).
- Utility tools (diagnostics_tool CLI, consensus scripts).
- Communication Layer:
- SocketCAN on host.
- Physical CAN bus wiring between host’s CAN interface and all firmware modules.
- Embedded Modules (each on its own Arduino board):
- Throttle Module
- Steering Module
- Brake Module (EV firmware & separate petrol firmware + auxiliary brake actuator)
- CAN Gateway Module (passes OBD‐II frames to host)
- Shared common libraries (fault_check, pid, can, serial, ssd1325, etc.).
- Vehicle Layer:
- Vehicle’s OBD‐II CAN network ECU nodes.
- Sensors & actuators: throttle position sensor, steering torque sensor, brake actuator or stock brake pedal.

##### Relationships & Data Flows
- Host App → OSCC API → SocketCAN → CAN bus → Firmware Modules → Vehicle actuators
- Vehicle sensors & ECU reports → Firmware Modules → CAN bus → OSCC API → Host App callbacks
- CAN Gateway Module duplicates arbitrary OBD‐II messages onto the same or second CAN channel for host consumption.
- Diagnostics Tool connects via SocketCAN to monitor live module/vehicle state.
- Build & upload paths: CMake → ArduinoToolchain → firmware modules → serial ports.

##### Architectural Patterns & Principles
- Layered separation: host‐side API vs. embedded firmware vs. vehicle hardware.
- Modularity: each module has its own CMakeLists and tests (Cucumber BDD + Rust property tests).
- Plug‐in vehicle support via api/include/vehicles/*.h and CMake vehicle flags.
- Reuse of common libraries across firmware modules (pid, can, fault_check).

##### Final Advice
- Runtime components and their interactions without cluttering the build/test paths.
- Be explicit about the CAN boundary and per‐module isolation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Layer
    subgraph "Host Layer"
        App["Host Application\noscc_open/enable/publish_xxx/subscribe_xxx"]:::host
        API["OSCC API Library\n(open, enable, publish, subscribe)"]:::host
        VehDefs["Vehicle Definitions\n(api/include/vehicles/*.h)"]:::host
        Diag["Diagnostics Tool CLI"]:::host
        Consensus["Consensus Scripts"]:::host
    end

    %% Communication Layer
    CANIF["SocketCAN Transport"]:::transport
    CANBUS["CAN Bus"]:::can

    %% Embedded Firmware Modules
    subgraph "Embedded Firmware Modules"
        SDK["Firmware SDK\n(common libs: can, pid, fault_check, ...)"]:::fw
        Throttle["Throttle Module\n(Arduino)"]:::fw
        Steering["Steering Module\n(Arduino)"]:::fw
        BrakeEV["Brake Module EV\n(Arduino)"]:::fw
        BrakePet["Brake Module Petrol\n(Arduino)"]:::fw
        CANGW["CAN Gateway Module\n(Arduino)"]:::fw
    end

    %% Vehicle Layer
    subgraph "Vehicle Layer"
        ECU["Vehicle ECUs\n(OBD-II)"]:::veh
        Sensors["Sensors & Actuators"]:::veh
    end

    %% Data Flows
    App -->|"uses API"| API
    API -->|"calls SocketCAN"| CANIF
    CANIF -->|"sends/receives CAN frames"| CANBUS
    CANBUS <--> Throttle
    CANBUS <--> Steering
    CANBUS <--> BrakeEV
    CANBUS <--> BrakePet
    CANBUS <--> CANGW
    ECU -->|"OBD-II messages"| CANBUS
    Sensors -->|"sensor/actuator signals"| CANBUS
    Diag -->|"monitor via SocketCAN"| CANIF
    Consensus -->|"scripted commands via API"| API

    %% SDK to Modules
    SDK --> Throttle
    SDK --> Steering
    SDK --> BrakeEV
    SDK --> BrakePet
    SDK --> CANGW

    %% Click Events
    click API "https://github.com/polysync/oscc/blob/master/api/src/oscc.c"
    click API "https://github.com/polysync/oscc/blob/master/api/include/oscc.h"
    click API "https://github.com/polysync/oscc/tree/master/api/include/can_protocols"
    click VehDefs "https://github.com/polysync/oscc/tree/master/api/include/vehicles"
    click Diag "https://github.com/polysync/oscc/blob/master/utils/diagnostics_tool/src/diagnostics.c"
    click Consensus "https://github.com/polysync/oscc/tree/master/utils/consensus/oscccan/"
    click Throttle "https://github.com/polysync/oscc/blob/master/firmware/throttle/src/main.cpp"
    click Steering "https://github.com/polysync/oscc/blob/master/firmware/steering/src/main.cpp"
    click BrakeEV "https://github.com/polysync/oscc/blob/master/firmware/brake/kia_soul_ev_niro/src/main.cpp"
    click BrakePet "https://github.com/polysync/oscc/blob/master/firmware/brake/kia_soul_petrol/src/main.cpp"
    click CANGW "https://github.com/polysync/oscc/blob/master/firmware/can_gateway/src/main.cpp"
    click SDK "https://github.com/polysync/oscc/tree/master/firmware/common/libs/"

    %% Styles
    classDef host fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef fw fill:#c8e6c9,stroke:#388e3c,color:#1b5e20,stroke-dasharray: 5 5
    classDef can fill:#e0e0e0,stroke:#616161,color:#212121
    classDef transport fill:#f5f5f5,stroke:#9e9e9e,color:#424242,stroke-dasharray: 2 2
    classDef veh fill:#ffe0b2,stroke:#fb8c00,color:#e65100,stroke-width:2px
```
