How commaai/opendbc works
Main Components
• CAN Library (opendbc/can)
• This part is responsible for parsing and building CAN messages from DBC files.
• Contains components like the parser (in Python and C/C++ via pyx files) and the packer.
• DBC Repository (opendbc/dbc)
• Holds DBC files and the generator scripts used to produce CAN message definitions.
• Serves as the data dictionary for the CAN layer.
• Car Interface Library (opendbc/car)
• A high-level abstraction for interfacing with different car brands.
• Contains per-brand folders (chrysler, ford, gm, honda, hyundai, etc.).
• Core modules include carcontroller.py, carstate.py, fingerprints.py, interface.py, and brand-specific implementations.
• Safety Module (opendbc/safety)
• Written in C/C++ for real-time safety-critical operations.
• Implements different safety modes (e.g., SAFETY_SILENT, SAFETY_ALLOUTPUT).
• Contains test suites for rigorous validation (using unit tests, MISRA testing, etc.).
• Examples, Docs, & Build/CI:
• The examples directory shows how to use the API (for instance, a joystick program to control a car).
• Documentation (docs/) and pre-commit/CI configuration (.github/workflows, SConstruct/SConscript) support development, testing, and continuous integration.
• The DBC Repository feeds the CAN parser and packer in the CAN Library.
• The CAN Library is central to converting DBC definitions into low-level CAN messages.
• The Car Interface Library leverages the CAN Library to communicate commands and state information between the code and the physical car.
• The Safety Module acts as an overlay on the CAN bus: it both monitors and intervenes to ensure safe message transmission. It may also interact directly with low-level hardware via the panda.
• Example applications illustrate how higher-level control (API calls) translates into CAN communication.
• The CI/build scripts (SConstruct/SConscript, pre-commit configs, and GitHub workflows) ensure that both the Python and safety (C/C++) components compile, pass linting, and meet standard tests.
Architectural Patterns and Technologies
• Layered Architecture:
• Bottom: DBC files providing message definitions.
• Middle: CAN Library for low-level message parsing/packing.
• Upper: Car Interface Library that implements domain-specific logic for each supported car.
• Crossing layers: Safety Module ensuring that communications are within approved operational modes.
• Language & Build Crossovers:
• Mix of Python (for high-level APIs, tests, and examples) and C/C++ (for performance/safety-critical code, e.g., in the safety directory).
• Integration via Cython (see .pyx files) to bridge the two domains.
• Continuous Integration & Testing:
• The GitHub workflows (.github/workflows) cover automated test runs, linting, static analysis (cppcheck, misra), and building.
• Extensibility Pattern:
• The car support “port” structure (organized by brand) facilitates contributions by isolating the vehicle-specific logic within separate modules.
• Off to the side (or integrated), show the “Safety Module” (opendbc/safety) interacting with both the CAN Library and Car Interface.
b. Ancillary blocks:
• “Examples” to show sample usage.
• “Docs & CI/Build” to represent supporting infrastructure (SConscripts, GitHub workflows).
• For instance, from “Car Interface” send control commands through the “CAN Library” and observe a safety check before reaching the hardware.
• Similarly, telemetry or vehicle state flows back up.
d. Connection points:
• Mention that some parts are bridged with Cython (in CAN Library) and that CI tests cross the entire codebase.