OCTAVE Wiki

What is OCTAVE?

OCTAVE is an open-source (GPLv3) car head unit / infotainment system you run on your own hardware. It pairs a C++ / Qt 6 backend — the shipped binary on every platform — with a QML frontend. It plays local music, reads live data from the car over OBD-II, mirrors an Android phone over USB or Wi-Fi, shows a live 3D model of the vehicle from an IMU, and recolours its interface to match the album art. It runs on Windows, macOS, Linux, Raspberry Pi / Orange Pi class boards, and Android (iOS is planned but not built yet).

Until October 2026 OCTAVE also had a Python / PySide6 backend. It is frozen on the python-final branch, which carries its own wiki describing that backend as it stood.

The typical installation is a single-board computer behind the dash, a touchscreen, a power source and a 3D-printed mount (the author daily-drives it in a 2003 Jeep TJ on an Orange Pi 5 Plus with a 10.1-inch 1280×800 touchscreen). Development and testing can happen on any desktop OS.

This reference describes the checked-out source and its build workflow. Released packages can differ, and optional hardware or Qt modules affect feature availability. Platform differences are called out in the detailed pages.

Core Features

♫

Local Media Player

MP3, M4A, FLAC, OGG, Opus and WAV playback with album art carousel, shuffle/repeat, playlists, a persistent metadata store, and album-art colour extraction.

OBD-II Diagnostics

Live vehicle data via an ELM327 adapter (USB / Bluetooth serial; BLE on Android), DTC read and clear, freeze frame, a full-screen shift light, and a protocol transcript in the logs.

◔

Gauges & Dashboards

Seven gauge primitives plus G-force and compass widgets, JSON-defined dashboards (five built-in presets plus your own), a chooser with live miniatures, and an in-app drag-and-drop dashboard editor.

☏

Phone Mirror & Android Auto

Mirror an Android phone over USB or Wi-Fi with the built-in scrcpy-protocol client. Android Auto runs on OCTAVE's built-in head unit (beta) or through Google's Desktop Head Unit.

⚙

Hardware Integrations

ESP32 wireless volume knob (ESP-NOW pair, USB dongle, LED ring), BerryIMU v3 attitude and heading readings, and PAJ7620U2 gesture recognition.

⛟

Live 3D Vehicle

A rigged Jeep TJ in Qt Quick 3D with working doors, hood, tailgate, lights, steering and wheels, rolled and pitched in real time by the IMU.

◆

Dynamic Theming

UI colours adapt in real time to album art. Accent, background and text colours are extracted and applied across every view (and to the ESP32 LED ring).

∿

Waveform Visualizer

FFT visualisation with 96 frequency bars for local tracks or live mirrored phone audio, rendered in QML.

✎

Diagnostics & Logs

Rotating log files, crash backtraces, a UI-thread watchdog, and a Diagnostics page that copies or exports the logs straight from the dash.

↻

Network & Updates

WiFi status, GitHub update checks and git-based self-update with in-app restart for checkout installs.

Platform Support

Platform	Status	Shipped artefact	Notes
Linux (Debian/Ubuntu/Arch/Fedora)	Build target	`OCTAVE-<v>-linux-x86_64.AppImage`	Primary development target. I²C hardware needs an accessible bus; Android Auto has capture limitations.
Raspberry Pi / Orange Pi (Linux aarch64)	Build target	`OCTAVE-<v>-linux-aarch64.AppImage`	The in-vehicle target. I²C sensors and the ESP32 knob supported. Google ships no aarch64 adb, so the distro `adb` is used for phone mirroring.
Windows 10+	Build target	`OCTAVE-<v>-windows-x86_64.exe` (Inno Setup)	I²C hardware (BerryIMU, gesture sensor) is unavailable. DHU window discovery is not implemented.
macOS (Intel and Apple Silicon)	Build target	`OCTAVE-<v>-macos.dmg`	I²C hardware is unavailable and DHU window discovery is not implemented. CI builds on macOS 14 against Qt 6.7.3; verify the bundle frontend layout before distribution.
Android (arm64-v8a, Android 11+)	Sideload	`OCTAVE-<v>-android-arm64-v8a.apk`	Local media, OBD over BLE, dashboards, IMU view from the device's own sensors. Phone mirror, Android Auto, ESP32 and I²C sensors are excluded. The workflow uses a persistent release signing key when its secrets are available; builds without those secrets use a temporary key and cannot update a differently signed install.
iOS	Planned, not built	—	No CMake toolchain wiring and no CI job yet (see `BUILD.md`, "iOS build").

Wiki Sections

Getting Started

Installation & First Run — Pre-built binaries, building from source, requirements, directory layout
Architecture Overview — C++ backend and QML frontend, manager pattern, startup order, threading, volume, video paths, logging, design decisions

Backend Deep Dives

Settings Manager — Central settings store, property system, coalesced JSON persistence
Media Manager — Local audio playback, library scanning, album art and colours
OBD Manager — ELM327 protocol, supported parameters, threaded worker, Android BLE, black box trip recorder
Network Manager — WiFi status, update checking, self-update
Hardware Managers — ESP32 knob, BerryIMU, gesture sensor
Phone Mirror & Android Auto — Built-in scrcpy-protocol client, the forked phone server, bundled adb, DHU
Audio Analyzer — FFT waveform visualisation
Utilities — Clock, logging and crash handlers, DiagnosticsManager, UI watchdog, VolumeController, performance monitor, command server

Frontend Deep Dives

Frontend Overview — QML architecture, Main.qml, page routing
Pages & Views — Every page in the application, including the 3D CarMenu
Bottom Bar — Navigation and volume control
Theme System — Dynamic theming, design tokens
Settings UI — Settings framework, layout engines, components
Components — Reusable QML components
Gauges & Dashboards — Gauge primitives, JSON dashboards, the in-app editor

Reference & Guides

Settings Reference — Defaults, persisted keys, and platform differences
Signals & Slots API — Every manager's QML-accessible API
Writing a Frontend — Drive OCTAVE from your own screen, phone, script or web page over the service API
Service API Reference — Generated from the C++: every object a frontend can drive, its types, and the parameter catalog
Hardware Setup — Wiring, firmware, 3D printed mounts
Building & CI/CD — CMake targets, AppImage / DMG / EXE / APK packaging, GitHub Actions
Development — Dev mode, mock data, MCP server, profiling, screenshots
Troubleshooting — Common issues, log locations, debugging

Tech Stack

Component	Implementation
Language / toolchain	C++17, Qt 6.7.3, CMake 3.21+ (Ninja recommended)
Frontend	QML (Qt Quick, Qt Quick Controls "Basic" style, Qt5Compat.GraphicalEffects, QtQuick.Effects, Qt Quick 3D for the vehicle view) loaded from `frontend/` at runtime
Audio playback / tags	QMediaPlayer + TagLib
Waveform FFT	QAudioDecoder + in-house radix-2 FFT on QtConcurrent
OBD-II	QSerialPort + own ELM327 protocol (`elm327protocol.cpp`); Android: native BluetoothGatt via JNI (`OctaveOBDBridge.java`)
I²C sensors	`/dev/i2c-N` + `ioctl`; Android: QtSensors (accelerometer, compass, pressure)
ESP32 serial	QSerialPort
Phone mirror	QTcpSocket + libavcodec (FFmpeg, optional at build) → QVideoSink; QAudioSink
Phone side	`phone_server/` — OCTAVE's fork of the scrcpy server (v3.3.4, Apache-2.0), prebuilt jar in `tools/phone-server/`; bundled Google platform-tools (adb)
Logging	QLoggingCategory + `src/util/logger.cpp` rotating files, signal crash handlers
Tests	QtTest suite in `tests/cpp/`, run by `ctest`
Build & CI	GitHub Actions: compile check, QtTest suite and qmllint on every push; Windows / macOS / Linux x86_64 / Linux aarch64 / Android on tags