Getting Started

Which Path Do I Want?

System Requirements

Installing a Pre-built Release

The current CI release workflow builds the packages on the GitHub Releases page from the C++ tree. No toolchain needed.

Building from Source

A desktop build needs CMake 3.21+, Qt 6.7.3 (the CI-pinned version) with the Multimedia, SerialPort, Connectivity and Qt5Compat modules, TagLib, and optionally FFmpeg (libavcodec/libavutil, for the built-in phone-mirror decoder), Qt Quick 3D (for the 3D vehicle view) and Qt WebEngine (for the in-app wiki viewer). The per-platform steps follow; BUILD.md is the full guide.

# Get the source
git clone https://github.com/RobDeGeorge/OCTAVE.git
cd OCTAVE

# Configure + build (Debug, current platform)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j

# Run — the binary finds frontend/ one directory up from build/
./build/octave            # Linux
# macOS: stage the frontend, then run
cp -R frontend build/octave.app/Contents/MacOS/
./build/octave.app/Contents/MacOS/octave # macOS
# Windows PowerShell: stage the frontend, then run
Copy-Item -Recurse -Force frontend build/Debug/
./build/Debug/octave.exe  # Windows (MSVC multi-config)

For the Windows multi-config and macOS bundle layouts, stage the runtime frontend before launching. In PowerShell, run Copy-Item -Recurse -Force frontend build/Debug/ for the Debug executable (use build/Release/ for Release). On macOS, run cp -R frontend build/octave.app/Contents/MacOS/. Refresh these copies after QML or asset changes. Linux's build/octave finds the checkout's frontend one level up.

A Debug build also turns on OCTAVE_DEV_TOOLS (the --dev / --profile tooling, see Developer Mode) and OCTAVE_BUILD_TESTS (the QtTest suite, run with ctest --test-dir build; see Testing). A Release build has neither.

CMake reports Built-in phone mirror decoder (libavcodec): ON/OFF and whether QtQuick3D was found at configure time; both are optional and the app degrades gracefully without them (phone mirroring unavailable without FFmpeg, greyed-out "3D View" card without Quick3D). Per-platform package lists, the AppImage / DMG / Inno Setup packaging that CI runs, and the pinned tool versions are in BUILD.md and on the Building & CI/CD page.

Linux

Linux is the primary development and deployment platform. On Debian / Ubuntu, install the toolchain and libraries (this is the package set the cpp-compile-check CI job uses on Ubuntu 22.04, plus the XCB runtime libraries from BUILD.md), then Qt 6.7.3 from the Qt online installer or aqtinstall. Distro Qt is too old on Ubuntu 22.04 (6.2 lacks QtQuick.Effects), so use the pinned version:

sudo apt install -y build-essential cmake ninja-build pkg-config \
  libtag1-dev libavcodec-dev libavutil-dev libgl1-mesa-dev libegl1-mesa-dev \
  libxkbcommon-dev libpulse-dev libssl-dev libfontconfig1 libdbus-1-3 \
  libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \
  libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
  libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xkb1

pipx install aqtinstall
aqt install-qt linux desktop 6.7.3 linux_gcc_64 -O ~/Qt \
    -m qtmultimedia qtserialport qtconnectivity qtsensors qtquick3d qt5compat qtshadertools qtquicktimeline

export PATH="$HOME/Qt/6.7.3/gcc_64/bin:$PATH"
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
./build/octave

Arch Linux / Manjaro / EndeavourOS

Arch's Qt is current enough to build against directly. You need cmake, ninja, taglib and ffmpeg plus the Qt 6 modules listed above (qt6-multimedia, qt6-serialport, qt6-connectivity, qt6-5compat, optionally qt6-quick3d and qt6-webengine). qt6-quick3d additionally needs assimp: without Qt's assimp asset-import plugin the Jeep model silently fails to load with Failed to load asset import plugin with key: "assimp".

Raspberry Pi / Orange Pi

For an aarch64 board the simplest path is the linux-aarch64 AppImage from the releases page; to build on the board, follow the Debian steps with aqt install-qt linux_arm64 desktop 6.7.3 .... Google ships no aarch64 platform-tools, so install the distro's adb (sudo apt install adb) for phone mirroring. The author's Jeep runs an Orange Pi 5 Plus; its boot, system and session configuration is kept as a reference in deployment/orange-pi-5-plus/. See Hardware Setup for I²C sensors and the ESP32 knob.

sudo usermod -a -G dialout $USER

Windows

Install Visual Studio 2022 with the "Desktop development with C++" workload, Qt 6.7.3 for MSVC from the Qt online installer, and vcpkg for TagLib and FFmpeg (vcpkg install taglib:x64-windows "ffmpeg[core,avcodec]:x64-windows", as CI does). Then, in PowerShell:

cmake -S . -B build `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake" `
  -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j
Copy-Item -Recurse -Force frontend build/Release/
./build/Release/octave.exe

Visual Studio is a multi-config generator, so OCTAVE_DEV_TOOLS defaults to off there; pass -DOCTAVE_DEV_TOOLS=ON to get --dev / --profile. CI packages the build with windeployqt and the Inno Setup script build_scripts/installer_windows.iss.

macOS

xcode-select --install
brew install taglib ffmpeg pkg-config

pipx install aqtinstall
aqt install-qt mac desktop 6.7.3 -O ~/Qt \
    -m qtmultimedia qtserialport qtconnectivity qtsensors qtquick3d qt5compat qtshadertools qtquicktimeline

export PATH="$HOME/Qt/6.7.3/macos/bin:$PATH"
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
cp -R frontend build/octave.app/Contents/MacOS/
./build/octave.app/Contents/MacOS/octave

The output is build/octave.app; CI turns it into the .dmg with macdeployqt. Apple Silicon and Intel are both supported.

Android Build

The Android app is built from the C++ / Qt 6 tree in src/ as a native .apk for arm64-v8a (Android 11+, minSdk 30, package org.octave.app) — the same code as the desktop build, with mobile-specific parts behind Q_OS_ANDROID.

Prerequisites

• Linux host with roughly 40–60 GB free on the $HOME disk
• Qt for Android 6.7.3 (android_arm64_v8a) plus the matching host Qt (gcc_64) for androiddeployqt
• OpenJDK 17 — the version used by OCTAVE's APK CI job; this checkout pins Android Gradle Plugin 7.4.1
• Android SDK (platform android-33, Build-Tools 33.0.2) and NDK 26.1.10909125

Build the APK

With the toolchain environment variables set (see BUILD.md), configure with Qt's qt-cmake cross-compile wrapper and build the apk target. OpenSSL for Android is bundled from android/openssl/<abi>/ through QT_ANDROID_EXTRA_LIBS:

qt-cmake -S . -B build-android \
    -DCMAKE_BUILD_TYPE=Debug \
    -DANDROID_ABI=arm64-v8a \
    -DANDROID_PLATFORM=android-30 \
    -DQT_ANDROID_SIGN_APK=OFF

cmake --build build-android --target apk -j
adb install build-android/android-build/build/outputs/apk/debug/android-build-debug.apk

CI builds Release. It uses the persistent release key when signing secrets are available, otherwise a temporary key. INSTALL_FAILED_UPDATE_INCOMPATIBLE means the installed app uses a different key. Use a build signed with the same key, or back up settings before uninstalling the old app.

Android Feature Differences

On Android, desktop-only managers are compiled as stub classes behind Q_OS_MOBILE so the QML keeps working, and Android-specific code sits behind #ifdef Q_OS_ANDROID. The desktop ↔ Android split:

Running OCTAVE

Standard Mode

./build/octave

A release install runs the same binary from its installed location (the Start-menu entry, the app bundle, or the AppImage).

Command-Line Flags

./build/octave --debug
./build/octave --smoke; echo $?

Performance Profiling

./build/octave --profile     # real OBD, perf monitor + command server

Starts the PerfMonitor (CSV + log under dev/perf/logs/, exposed to QML as perfMonitor), a command server on 127.0.0.1:9876 for remote control and the MCP tools, and times the hot paths marked with OCTAVE_PERF_SCOPE. The code is src/dev/, compiled in by the OCTAVE_DEV_TOOLS CMake option (on by default only for -DCMAKE_BUILD_TYPE=Debug); other builds ignore --dev / --profile with a warning. See Performance Profiling.

Developer Mode

Developer mode provides a simulated car and keyboard controls for testing without hardware or a vehicle. It is a flag on an OCTAVE_DEV_TOOLS build: the real OBDManager talks to a simulated ELM327 adapter, so the shipped OBD code runs against the simulation. The simulated car on its own is --sim (src/sim/), which every build has, release downloads included. The in-app half (src/dev/) is committed. The client tools that drive it over the command server (screenshot / story recorder, MCP servers, perf scripts, all Python scripts in dev/) are gitignored: they exist on the maintainers' machines but are not part of a fresh clone.

./build/octave --dev
./build/octave --dev --profile     # + command server: what the screenshot / MCP tooling launches

Build Dependencies

Runtime tools that are not build dependencies: adb for phone mirroring (fetched into tools/platform-tools/ by python scripts/fetch_platform_tools.py and bundled in releases). The app itself needs no Python; the Python tools around it (the dev/ clients, the wiki and API doc generators) go into a virtualenv next to the checkout:

python3 -m venv venv && venv/bin/pip install -r requirements.txt

Directory Structure

octave/
├── src/                 # C++ application
│   ├── main.cpp                       # entry point, manager wiring
│   ├── managers/                      # one *manager.{h,cpp} per feature + elm327protocol
│   ├── util/                          # logger.cpp (rotating logs, crash handlers), uiwatchdog.cpp, perfscope.h
│   ├── phone_mirror/scrcpyclient.*    # built-in scrcpy-protocol client
│   ├── items/embeddeddhuitem.*        # QQuickItem for Android Auto frames
│   ├── platform/                      # Android JNI bridges (media, process), Linux BlueZ pairing
│   ├── sim/                           # --sim simulator (every build): simulated car, ELM327, IMU motion, the sim object
│   └── dev/                           # --dev / --profile tooling (OCTAVE_DEV_TOOLS builds only), qml/ dev overlay
├── frontend/            # QML UI
│   ├── Main.qml  MainMenu.qml  MediaRoom.qml  MediaPlayer.qml  OBDMenu.qml  CarMenu.qml ...
│   ├── JeepVehicle.qml  JeepHinge.qml  JeepLamp.qml  JeepLink.qml  JeepSteering.js
│   ├── gauges/          # gauge primitives
│   ├── dashboards/      # DashboardRenderer, WidgetCatalog, presets/*.json, editor/, widgets/
│   ├── settings/        # settings pages and components (DeviceSettingsPage has Service, Frontends and Diagnostics)
│   ├── shaders/         # .qsb shaders (compiled into the binary as resources)
│   └── assets/          # icons, fonts, jeep_tj_2003.glb + jeep_tj/ part GLBs, readme media
├── tests/
│   ├── cpp/             # QtTest suite run by ctest (CI)
│   └── fixtures/        # H.264 clips and QML fixtures used by the tests
├── phone_server/        # OCTAVE's fork of the scrcpy server (Java) + build_without_gradle.sh
├── tools/
│   ├── phone-server/    # prebuilt jar + LICENSE/NOTICE (tracked)
│   ├── platform-tools/  # adb fetched by scripts/fetch_platform_tools.py (gitignored)
│   └── vehicle/         # Blender scripts that build the Jeep model
├── android/             # AndroidManifest, gradle, JNI bridges (OctaveMediaBridge, OctaveOBDBridge)
├── packaging/linux/     # build-appimage.sh
├── build_scripts/       # installer_windows.iss (Inno Setup)
├── scripts/             # fetch_platform_tools.py, desktop / Pi launcher scripts, Android bundle builder
├── deployment/          # orange-pi-5-plus/ reference config of the Jeep head unit
├── docs/                # GAUGE_AUTHORING.md, PHONE_MIRROR_NATIVE_PLAN.md, vehicle/ references
├── wiki/                # this wiki (static HTML)
├── TODO/                # parked plans, one markdown file each
├── hardware/            # 3D-printed mount CAD/STL (2003 Jeep TJ media console)
├── dev/                 # developer client tools (gitignored, not in a clone)
├── CMakeLists.txt       # the build
├── BUILD.md             # full desktop / Android build guide
└── CLAUDE.md            # contributor rules (conventions, wiki upkeep)

First Steps After Install

1. Set your music directory — Open Settings and point the media library at a folder of MP3 / M4A / FLAC / OGG / Opus / WAV files. OCTAVE scans it, extracts album art and caches tags in metadata_cache.json to reduce repeated metadata work on later launches.
2. Connect OBD-II (optional) — Plug in an ELM327 adapter (USB, or pair a Bluetooth one and select its port in Settings > OBD). On Linux make sure you are in the dialout group. Then open the OBD page, pick a dashboard from the chooser, or build your own in the editor.
3. Try the 3D view — Sensors > 3D View shows the Jeep model; with a BerryIMU attached it follows the vehicle's attitude (use ZERO on level ground).
4. Explore Settings — OCTAVE provides settings across display, media, OBD, accessories and device, all persisted to settingsConfigure.json. Settings > Device > Diagnostics shows the app version, the device and the recent log, and lets you export the logs.