CliOS 2.0.1 supports Raspberry Pi 5 with Raspberry Pi OS Bookworm or Trixie 64-bit and a 1920×720 display. Raspberry Pi 4 is experimental; macOS, Windows, and x86 are development/mock targets only.
Open-source, modular digital cockpit and telemetry system for vehicles.
Built with Python, PySide6, QML, and SocketCAN for 1920x720 ultrawide displays.
Lire la documentation en Francais • Issues • Discussions
- Real-Time CAN and OBD Telemetry: Decodes live powertrain and chassis frames via SocketCAN and flexible JSON vehicle profiles.
- Dynamic Powertrain Engine: Real-time calculations of horsepower, instantaneous torque, engine load, and longitudinal G-forces.
- Modular Multi-Theme UI (QML):
- Apex: High-contrast, track-inspired digital cluster with live G-meter and sport telemetry.
- Atelier Luxe: Minimalist design focused on cabin comfort, efficiency, and trip overview.
- GT Modern and Legacy: Classic performance and heritage cluster layouts.
- Trip Analytics and Auto-Export: Automatic tracking of fuel consumption, trip cost, aggression index, and plug-and-play USB export.
- Audio DSP and Ambient LEDs: Real-time cabin noise filtering and engine sound design (via
pyoDSP) with BLE ambient light sync. - Fail-Safe Architecture: In-memory state store with strict TTL, domain snapshots, and volatile fallbacks.
- Zero-Hardware Mock Mode: Fully interactive physics and CAN simulation engine to test and develop on macOS, Linux, or Windows without a car.
- Raspberry Pi 5 Kiosk: Auto-launch into a distraction-free Wayland kiosk (
cage). - Safe Releases: SHA-256 verified staging, atomic
/opt/clios/currentactivation, first-boot health checks, and automatic N-1 rollback.
Theme API v1 and the v1 theme, vehicle, CAN, and profile schemas remain stable throughout the 2.x series. A future incompatible contract requires a new major API version. Local themes are trusted, unsandboxed QML and are only loaded in developer mode. Python services remain statically registered and must be reviewed in this repository.
Community guides: create a theme, adapt a vehicle, and develop a service. Validate contributions with python3 tools/validate_data.py --all.
Maintainer workflow: CI, branches, releases and update channels (French). Concrete implementation summaries are kept in docs/implementation_reports.
| Apex (Track and Performance) | Atelier Luxe (Comfort and Touring) |
|---|---|
 |  |
| High-G Telemetry & Powertrain Stats | Minimalist Navigation & Trip Stats |
You do not need a vehicle or a Raspberry Pi to run CliOS. Use the built-in mock simulation:
# 1. Clone repository
git clone https://github.com/Tanchouteur/CliOS.git
cd CliOS
# 2. Run universal launcher with mock mode (auto-configures virtualenv)
./clios --mockTip
On laptop or desktop screens with high DPI scaling, run:QT_SCALE_FACTOR=0.65 ./clios --mock to comfortably fit the 1920x720 window.
To deploy CliOS inside a real car, the following hardware is required:
- Single Board Computer:
- Raspberry Pi 5 with Raspberry Pi OS Bookworm/Trixie 64-bit (supported).
- Raspberry Pi 4 (experimental until hardware qualification is complete).
- Display:
- 1920x720 ultrawide display (HDMI or DSI). This is the only guaranteed layout; other formats are experimental.
- CAN Interface Adapter:
- Any SocketCAN-compatible USB or SPI adapter connected to the vehicle's CAN bus (OBD-II port or direct CAN High/Low wiring).
- Supported adapters: InnoMaker USB-CAN, CANable / CandleLight (gs_usb), Waveshare CAN HAT, or SLCAN serial adapters (OBDLink SX, etc.).
CliOS is vehicle-agnostic. To use it on your own car, you provide two JSON definition files:
Defines the mapping between raw CAN IDs and signals (RPM, speed, throttle position, brake status, steering angle, coolant temperature, etc.):
{
"0x181": {
"name": "ENGINE_DATA",
"signals": {
"rpm": { "start_byte": 0, "size": 2, "endian": "big", "factor": 0.125 },
"accel_pos": { "start_byte": 3, "size": 1, "offset": -7, "factor": 0.4201 },
"pedals": {
"start_byte": 5,
"bits": {
"brake": 0,
"clutch": 3
}
}
}
}
}Specifies vehicle dynamics parameters used for real-time power/torque modeling:
- Engine torque/power curves
- Redline and idle RPM
- Gearbox ratios and final drive ratio
- Vehicle curb weight, frontal area, and fuel tank capacity
CliOS includes an interactive installer for Raspberry Pi OS and Debian/Ubuntu:
git clone https://github.com/Tanchouteur/CliOS.git
cd CliOS
./install.shThe installer handles:
- System packages (
apt, audio drivers,can-utils,cageWayland compositor). - Python virtual environment
.venvand DSP audio compilation (pyo). - CAN interface setup (
can-usb,slcan,candlelight,socketcan). - Systemd Kiosk service (
clios.service) for instant auto-boot without a desktop environment. - Optional Fast-Boot kernel and system tuning for Raspberry Pi 5.
- Raspberry Pi 5 Fast-Boot Optimization Guide
- CAN Hardware and System Rules Guide
- Pyo Audio DSP Setup Guide
CliOS is designed around a strict decoupled unidirectional data flow:
[ CAN Bus / OBD-II / Mock ]
│
▼
[ CanService ] ──► (Publishes StatePatch)
│
▼
[ VehicleRuntime ]
│
▼
[ StateStore ] ──► (Strict domains, TTL & quality check)
│
▼
[ Qt Bridge ] ──► (Thread-safe Python-to-QML bridge)
│
▼
[ UiState.qml ] ──► (Semantic properties consumed by Dashboards)
│
┌─────────┴─────────┐
▼ ▼
[ Apex QML ] [ Atelier Luxe QML ]
Read the full specifications in docs/backend_architecture.md.
├── main.py # Application entrypoint and service composition
├── clios # Universal executable runner
├── src/
│ ├── runtime.py # Core event publishing gateway
│ ├── state_store.py # Domain snapshots, TTL and quality handling
│ ├── signal_catalog.py # Strict CAN signal registry
│ ├── qt_bridge.py # Python/QML contract bridge
│ ├── services/ # Business logic (telemetry, stats, audio, storage)
│ └── simulation/ # Physics and mock CAN telemetry generators
├── frontend/
│ ├── state/UiState.qml # Semantic UI state facade
│ └── styles/ # QML themes (Apex, Atelier Luxe, GT Modern)
├── data/
│ ├── can/ # Vehicle CAN DBC and frame definitions (JSON)
│ └── config/ # Engine power curves and vehicle profiles
├── tests/ # Backend, QML, and contract test suites
└── tools/ # Smoke tests and developer utilities
Contributions are welcome. Areas of active interest:
- Vehicle Profiles: DBC and CAN JSON mappings for additional car models (BMW, VAG, Ford, Honda, etc.).
- QML Themes: Custom digital clusters, retro layouts, or specialized track displays.
- Integrations: Media player controls, GPS mapping, or CarPlay/Android Auto companion tools.
- Core Optimizations: Fast boot improvements, DSP audio processing, and BLE peripherals.
Please check CONTRIBUTING.md for architecture guidelines and testing procedures.
Diagnostic bundles can contain logs, profiles, network/platform details, and vehicle information. Review an archive before sharing it; report security-sensitive findings through the private channel described in SECURITY.md.
Distributed under the GNU General Public License v3.0 (GPLv3). See LICENSE for more details.
CliOS is an accessory information display, not a certified replacement for legally required vehicle instruments. It is not affiliated with or endorsed by any vehicle manufacturer or trademark owner. See ASSETS.md for asset provenance and licensing.