How polysync/oscc works
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.