Development Guide

Design Decisions

Why dev mode wraps production instead of duplicating it

Dev mode is a flag on the production binary: octave --dev builds every manager exactly as a normal start does, then points the real OBDManager at a simulated ELM327 adapter (a QIODevice registered through OBDConnectionWorker::setCustomTransport()) and reparents the dev overlay into the real window. Nothing in the OBD stack is replaced, so the AT init sequence, PID parsing and decoding, demand-driven polling, the vehicle scan and gate, VIN decode and the DTC paths all run the code that ships.

Why a TCP command server and MCP servers for performance work

The head unit runs in a Jeep; the problems that matter are stutter, stalls and regressions that only show up when the app is driven the way a driver drives it. A JSON-over-TCP command server (src/service/commandserver.cpp, only started by --profile) lets a script or an agent navigate pages, toggle every setting, skip tracks, drive the simulator and read the perf counters while the perf monitor measures the event loop, so a test is repeatable and comparable between commits (dev/docs/perf_test_plan.md, dev/perf/run_perf_loop.py). The two MCP servers expose the same channel to a coding agent so it can reproduce a report, bisect a regression or benchmark a setting without a human clicking. The README makes the same point: "The same command channel is exposed as MCP tools, so a coding agent can navigate the app, change settings, read performance counters and record clips."

Where the tooling lives, and why the in-app half is committed

The tooling has two halves. The in-app half (perf monitor, UI driver and actions, dev keyboard, overlay) is src/dev/. It is committed because CMake must list it, but it is only compiled when the OCTAVE_DEV_TOOLS option is on: the default only for CMAKE_BUILD_TYPE=Debug desktop builds, off for every other or missing build type, Android and iOS, so no shipped binary carries the perf monitor or the UI-driving actions. Even when compiled, nothing runs without --dev / --profile. The simulator (src/sim/) and the service socket (src/service/) are in every build, inert unless --sim / --service (or a setting) start them. Production code touches it in three small places: OCTAVE_PERF_SCOPE("label") timing scopes (src/util/perfscope.h, compiled to nothing without the option), OBDManager::setPortOverride() / OBDConnectionWorker::setCustomTransport() (generic hooks; nothing is registered in a normal run) and a friend declaration on BerryIMUManager for the simulator's IMU feed (SimImuAccess).

The client half (dev/: MCP servers, screenshot / story / collage / perf scripts, written in Python) talks to the app only over the command server's TCP socket. It stays in .gitignore and is synced between the developer machines through Dropbox, so a fresh clone has the in-app half but none of the clients.

Why screenshots are grabbed from inside Qt

The first screenshot tool used xdotool + mss (X11 input and capture) and broke under Wayland. The current one asks the running app to capture itself: screenshot and record_start run grabWindow() on the GUI thread, which works identically on Wayland, X11 and Xvfb, and hides the dev HUD automatically. It also gives deterministic window sizes for README assets (dev/docs/SCREENSHOTS.md).

Why errors do not surface in the UI

Errors are reported through logs and page-specific status text. The one exception is ErrorToast: a short top-centre notice when the OBD link drops while you're on another page. The rotating logs, crash handlers, UI watchdog, and Diagnostics card support troubleshooting after a session.

Repository Map for Developers

Dev Mode Setup & Usage

Dev mode is the simulator of --sim (below, in every build) plus keyboard controls, the overlay and the UI tooling, for testing without an OBD-II adapter.

# any build, release included
build/octave --headless --sim            # simulated car, IMU motion, test tracks; the sim object on the service; throwaway config
build/octave --sim                       # the same car in the QML UI (no service unless --service)
build/octave --headless --sim --config /tmp/octave-sim   # keep the config between runs (nothing seeded there)
# needs a build with OCTAVE_DEV_TOOLS=ON, the default for -DCMAKE_BUILD_TYPE=Debug
build/octave --dev                       # --sim on your usual config + overlay + keyboard driving
build/octave --dev --profile             # + perf monitor, command server :9876 and the sim_* actions
build/octave --profile                   # production mode, real OBD, perf monitor + command server
build/octave --dev --profile --command-port 9877
build/octave --service                   # any build: the service protocol only (no UI / perf / sim actions)
build/octave --headless                  # the managers + the service, no QML engine, no window
build/octave --headless --web-root dist  # serve your built web frontend at http://127.0.0.1:9876/
build/octave --headless --dev            # --headless --sim on your usual config, plus the sim_* actions (no UI / perf actions)
python3 tools/stream/service_load.py build/octave 19818 /tmp/load/cfg ~/Music   # service load: CPU, RSS, event latency with 5 clients (TODO/open-backend.md has the baseline)
build/octave --help                      # every flag (and --version); exits before any manager, config or log file
build/octave --dump-api docs/api         # regenerate the published API (then: python wiki/build_api_reference.py)

A build without the option (Release, or no build type) ignores --dev / --profile with a warning; --sim and --service work in every build (service protocol). --sim on its own runs on a throwaway config (logged at start, deleted at exit); --dev keeps your usual one, so use --config DIR (or XDG_CONFIG_HOME=/tmp/octave-dev, as the story and collage tools do with their own profile directory) when a dev run should not touch your settings.

OctaveDev::Runtime

src/main.cpp builds every manager as usual, then hands them to src/dev/devruntime.cpp:

1. Before it, main.cpp starts the simulator (core.sim.start(), for --sim or --dev): CarSim, the simulated adapter registered for port sim://elm327, obdManager.setPortOverride("sim://elm327") (the saved port setting is left alone) and the IMU feed.
2. beforeLoad() — with --dev: registers devKeyboardController (driving the simulator's car), devToolsManager and devMode = true. With --profile: creates PerfMonitor as the perfMonitor context property.
3. engine.load(Main.qml) — the production QML; there is no separate dev entry.
4. afterLoad() — reparents src/dev/qml/DevOverlay.qml into the window (C++ object ownership plus a QObject parent so the JS GC cannot reclaim it); with --profile, starts the perf monitor and adds the core, collage and (in dev mode) sim_* actions to the command server, which main.cpp created (--profile turns the service on in these builds) and starts right after.
5. startHeadless() — instead of the two above under --headless, where there is no engine: with --dev the sim_* actions on the service (the simulator itself, with the IMU feed on from the start, is main.cpp's). No overlay, keyboard, perf monitor or UI actions; --profile is ignored with a warning.
6. shutdown() — first thing in aboutToQuit: writes the perf report, finishes a recording; main.cpp then stops the command server before the managers clean up.

Keyboard controls

Handled by devKeyboardController.handle_key(key, pressed) (DevKeyboardController in src/dev/devkeyboard.h), fed from Keys.onPressed / onReleased in the overlay. The overlay's HUD re-reads obdManager.rpm(), speedMPH(), ... every 100 ms; those getters only change for PIDs that are being polled.

Dev mode architecture

  build/octave --dev --profile
    |
    +-- every manager, every connection   (src/main.cpp, unchanged)
    +-- core.sim.start()         CarSim (60 Hz physics), SimElm327Device for sim://elm327,
    |                            obdManager.setPortOverride, the IMU feed (src/sim/)
    +-- Runtime::beforeLoad      devKeyboardController / devToolsManager / devMode,
    |                            perfMonitor
    +-- engine.load(Main.qml)    production frontend
    +-- Runtime::afterLoad       src/dev/qml/DevOverlay.qml reparented into the window,
                                 command server :9876 (core + collage + sim_* actions)

  OBDManager --worker thread--> OBDConnectionWorker --QIODevice--> SimElm327Device
                                  (real AT init, PID polling,        |  reads CarState
                                   scan, VIN, DTC parsing)           v  (mutex, shared_ptr)
                                                                   CarSim  <-- keyboard, sim_*

Simulated Car and Adapter

Everything here is in src/sim/, built in every configuration (release builds too, so a frontend author can download a release instead of building OCTAVE) and inert until started with --sim, --dev, or by choosing Simulated car in the OBD adapter picker. The picker works in desktop, mobile and WebAssembly builds, including releases, without Bluetooth or launch flags. src/sim/demodrive.cpp drives the shared simulator automatically: idle, accelerate, cruise, coast and brake, with simulated IMU motion. Selecting hardware or closing the OBD connection stops the demo motion and restores the hardware sensor path. The simulated adapter does not replace the saved hardware adapter; the UI labels its data Simulated. Simulator (src/sim/simulator.h) owns the parts and is served as the experimental sim object (docs/api/README.md, "Simulator").

src/sim/carsim.cpp + src/sim/simelm327.cpp

CarSim is a simple physics model (throttle drives RPM and speed, brake slows it, the gear follows speed while the engine runs, load / MAF / MAP / timing / AFR / O2 from throttle and RPM, scenarios that hold temperatures or fuel) stepped by a 60 Hz GUI-thread timer into a mutex-guarded CarState. SimElm327Device is a sequential QIODevice on the OBD worker thread that answers what the worker sends:

• The AT init sequence (ATZ → ELM327 v1.5, ATS0 turns spaces off, ATRV → battery voltage, other AT commands → OK).
• Mode 01: every PID in ELM327Protocol::pidTable() and extendedPidTable(), encoded with the inverse of the shipped decoders. Modelled PIDs follow the simulation; the rest hold plausible fixed values. The supported-PID bitmaps (0100 ... 01E0) report all of them, so no widget is gated out in a simulated run.
• Mode 03 / 07 / 0A DTCs (P0300 + P0420 stored, P0300 pending; CAN count byte), Mode 04 clear (codes stay cleared until restart), Mode 02 freeze-frame DTC, PID 01 MIL + count, and the Mode 09 VIN 1J4FA49S03P123456 (2003 Jeep) as a CAN multi-frame reply.
• Link behaviour: in realistic mode each reply arrives after a Bluetooth-like 35–70 ms (700 ms for ATZ) and 2 % of PID polls answer NO DATA; with sim.setRealistic(false) replies take 8 ms and never drop. A dropout (sim.dropoutNow(), or random ones every 90–180 s with sim.setDropouts(true)) closes the device for 2–4 s, the worker reports the link lost, and the manager's passive scan reconnects.

Because the poller walks the demanded PIDs one by one at adapter speed, a page that asks for ~120 PIDs (Parameter Cards) takes several seconds to fill, as it does in the car.

src/sim/imufeed.cpp is the simulated IMU (sim.setImu, below). Turning it on stops the BerryIMU I²C worker; turning it off restarts it. It is on from the start with --sim and --headless; a GUI --dev run leaves it off, so a Pi's real IMU is not masked.

src/sim/simconfig.cpp prepares the throwaway config of a --sim run without --config (HOME, XDG_*, APPDATA and the config folder pointed at a temporary directory, as --dump-api does): settingsConfigure.json with the ESP32 knob and gesture sensor off and mediaFolder set to a Music/ folder holding three generated 20 s WAV tracks (tones, with title, artist and album in a RIFF INFO chunk). sim.setVideo(true) loops tests/data/stream-test.h264, compiled in as :/sim/stream-test.h264 (not in the browser build), into the phone video stream.

The sim object and the sim_* actions

Every build serves the sim object (active, setThrottle, setBrake, rev, setEngineOn, toggleEngine, setGear, upshift, downshift, setSpeed, setRpm, setRealistic, scenario, setDropouts, dropoutNow, setFailureRate, setLinkUp, setImu, setVideo, pairingCode, status); it is marked experimental, and when the run is not simulated every control returns false and does nothing. In developer builds with --dev the command server also takes the older sim_* actions, which are aliases for those methods and answer {"ok": false} when there is no simulated car. Over the command server the controls are sim_throttle / sim_brake (value), sim_rev (intensity), sim_engine (on), sim_gear, sim_upshift, sim_downshift, sim_speed (mph), sim_rpm, sim_scenario (name: cold | hot | low_fuel | normal), sim_realistic (enabled), sim_imu (on), sim_status, sim_dropouts (on), sim_dropout_now, sim_failure_rate (value, default 0.02) and sim_link (up: false unplugs the simulated adapter until it is plugged back in, for testing the no-vehicle states), sim_video (on) and sim_pairing_code. All but sim_status and sim_pairing_code are queued on the GUI thread and answer {"queued": name}. The scenarios hold while the engine runs: the per-tick update adds noise around the scenario’s coolant and oil temperatures instead of resetting them to normal. sim_imu starts the IMU feed (src/sim/imufeed.cpp), which drives the real berryIMU manager’s signals with a synthetic drive tied to the simulated speed (winding road for heading and lateral G, longitudinal G from acceleration, body roll and pitch, hills for altitude), so the sensors page, G-force and compass widgets and the 3D vehicle move without hardware. It pauses the manager’s I²C start/retry path while on.

DevToolsPanel

src/dev/devtoolsmanager.cpp & src/dev/qml/DevToolsPanel.qml (embedded in src/dev/qml/DevOverlay.qml)

DevToolsManager is exposed to QML as devToolsManager. It captures the window with Qt's grabWindow() (Wayland- and X11-safe), saves PNGs to dev/screenshots/output/, keeps a manifest.json of every capture with its description, and can generate a GALLERY.md.

Command Server (TCP)

src/service/commandserver.cpp, coreactions.cpp, uidriver.cpp

A TCP server on 127.0.0.1:9876 that accepts newline-delimited JSON commands. main.cpp owns it: it starts with --profile (dev-tools builds), --service or the serviceEnabled setting (when and where it listens) and stops on aboutToQuit.

The listener runs on its own thread and every client connection gets a thread, so a slow GUI call on one connection never blocks get_metrics on another. Handlers run on the connection thread and reach Qt objects through CommandServer::onGui(fn, timeoutMs) (blocking, 30 s default; a stuck GUI thread comes back as the error GUI thread did not answer within … ms instead of a hung client) or postGui(fn) (fire and forget: navigation and the sim_* controls). Extra actions are added with registerAction(name, handler); invokeByName() calls slots / invokables / QML functions by name with argument conversion. --command-port N picks another port.

Protocol

// Client sends JSON + newline:
{"action": "next_track"}

// Server responds with JSON + newline:
{"ok": true, "result": null}

// With arguments:
{"action": "navigate", "args": {"page": "media_player"}}

// Error response:
{"ok": false, "error": "Unknown action: foo"}

Actions (the list_actions response)

• App: ping (returns "pong"), list_actions
• Performance: get_metrics, get_detailed_report, get_slot_timings
• Navigation: navigate (page id), go_back, go_home, get_current_page, list_pages, open_settings (section id), list_settings_sections
• Screenshots / recording: screenshot (path), set_dev_chrome (show/hide the HUD), set_window_size, record_start (path, fps), record_stop, record_status
• UI driving: find_item (geometry + effective visibility of any QML item by objectName, popups included), list_items (prefix match), list_interactive (every control a finger could reach right now: not hidden, clipped, under a sheet or popup that takes the tap, or painted over by a page; each with its kind, the text and icon drawn inside it, its on-screen rectangle and its checked / value state; the view the AI usability testers in dev/ux/ get), get_prop / set_prop (the name is "root" for the window, else an item’s objectName, else a manager’s context-property name such as shiftLightManager), call (invoke a no-arg method such as forceActiveFocus), find_text (an item by its visible label, or another string property such as placeholderText, for QML without objectNames), click (x, y), long_press (x, y, ms), type_text (into a field matched by objectName or placeholder, key events sent straight to it), drag (x1, y1, x2, y2, steps) and wheel (x, y, notches) — synthetic mouse events delivered through the window's normal event path, so MouseArea drag thresholds and Flickable behave as they would for a finger. Closed popups leave the item tree, and pages pushed via navigate are not destroyed on go_home, so tests should prefer the visible instance (the server does) and scroll targets into view before clicking.
• Media: next_track, previous_track, toggle_play and toggle_shuffle go through nowPlaying (the phone while it has the controls), pause (local player), toggle_mute, set_volume, get_media_status, get_track_info, skip_tracks
• OBD: obd_status, obd_reconnect
• Settings: get_settings, get_all_settings, toggle_setting, set_bool_setting, set_numeric_setting, set_string_setting, and the list_toggle_settings / list_numeric_settings / list_string_settings discovery calls
• Collage: collage_list_popups, collage_open_popup, collage_close_popups, collage_mount, collage_grab, collage_unmount (python -m dev.collage; src/dev/collagebridge.cpp, registered whenever the command server runs, with or without --dev)
• Simulator: in dev mode the sim_* actions (above)

Navigation bridge and valid pages

The GUI-thread half is UiDriver: navigation is queued, captures and UI driving block so the result can be read back. Mouse input goes through QTest (the build links Qt Test when OCTAVE_DEV_TOOLS is on). Because QML function foo(arg) parameters are untyped and register as QVariant, UiDriver::navigateTo() calls the window's navigateTo(page) through invokeByName() with a QVariant argument instead of Q_ARG(str, ...), which would match nothing and fail silently. Page ids map to QML files:

home, media_room, media_player, obd, obd_home, obd_diagnostics, trip_history, sensor_home,
settings, phone_mirror, android_auto, airplay, sensors, car, clock
# settings sections for open_settings:
displaySettings, mediaSettings, obdSettings, accessoriesSettings, deviceSettings, about

Example consumer: dev/tests/drive_dashboard_editor.py drives the whole dashboard editor (place, bind, drag, resize, options, save, edit, duplicate, delete, draft rescue, hot reload; ~40 assertions, ~3 min) under Xvfb (xvfb | visible | offscreen modes), writes screenshots to dev/screenshots/output/editor/, cleans up its test-dash*.json dashboards, and exits 1 on any failed assertion. dev/tests/drive_dashboard_features.py reuses its helpers for per-widget overrides, colour, enum options, drag-to-resize, share / import, swipe between dashboards and the no-vehicle Parameter Cards state (screenshots in dev/screenshots/output/features/). test_dtc.py / clear_dtc.py in the same folder are stand-alone hardware checks that talk to an adapter on /dev/rfcomm0 directly, without the app.

MCP Servers

dev/mcp_server.py (octave-perf) and dev/mcp_benchmark.py (octave-benchmark) are MCP servers (MCPServer on mcp 2.x, falling back to FastMCP on 1.x) that let a coding agent such as Claude Code drive OCTAVE through the command server. Both need the mcp Python package (pip install mcp) and the app running with --profile; the benchmark script only serves MCP when given --mcp (without it, it runs the suite once as a CLI), so .mcp.json passes that flag; every tool just sends a JSON action to 127.0.0.1:9876.

Setup

pip install mcp                       # for the MCP client scripts
build/octave --dev --profile           # simulator; drop --dev for real OBD
python dev/mcp_server.py              # stdio MCP server; normally launched by the agent from .mcp.json

The local .mcp.json is gitignored. Configure its server commands with the Python interpreter and script paths for your checkout; machine-specific paths copied from another workstation will fail. Pass --mcp to the benchmark server.

  AI agent (Claude Code)
       |  stdio (MCP)
       v
  dev/mcp_server.py  /  dev/mcp_benchmark.py
       |  TCP 127.0.0.1:9876, JSON + newline
       v
  CommandServer (a thread per client)  --onGui / postGui-->  UiDriver / managers (GUI thread)
       |
       v
  PerfMonitor (metrics, slot timings)   CarSim + SimElm327Device (sim_*)   grabWindow() (screenshot / record)

octave-perf tools

dev/docs/perf_test_plan.md is the agent-facing script for a full regression pass (idle baseline, navigation, single / 10 / 20-track skips, settings toggles, slider sweeps) with pass criteria per section; dev/docs/perf_optimize_prompt.md and dev/docs/PERFORMANCE_AUDIT.md record earlier optimisation rounds.

octave-benchmark tools

benchmark_page(page, settle_seconds, samples), benchmark_setting(key) (sweeps a setting across its range), benchmark_transition(transition, skip_count, ...), benchmark_media_ops, get_bottlenecks(min_p95_ms), run_benchmark_suite(include_stress) (five phases: baseline, settings matrix, stress, combined, bottlenecks), save_baseline and compare_to_baseline, which diffs a run against a saved JSON baseline and flags regressions.

Stand-alone perf scripts

dev/perf/run_perf_loop.py talks to the socket directly and loops the full test gamut, comparing iterations; dev/perf/brutalize.py maxes every visual setting and hammers the app until it degrades; dev/perf/profile_performance.py is a system-level sampler for the Orange Pi (--duration, --interval). Perf CSV/log output lands in dev/perf/logs/.

Performance Profiling

src/dev/perfmonitor.cpp

build/octave --profile          # OCTAVE_DEV_TOOLS build

--profile writes dev/perf/logs/perf_<YYYYMMDD_HHMMSS>.csv and .log, registers the monitor as the perfMonitor context property and starts the command server. get_metrics is what the MCP tools and perf scripts read; numbers depend on the machine and build type, so compare a run against a baseline taken on the same machine and build.

Hot paths are timed with OCTAVE_PERF_SCOPE("label") from src/util/perfscope.h: compiled to nothing without OCTAVE_DEV_TOOLS, one relaxed atomic load when built but not profiling, safe from any thread. The current labels: media.next_track, media.previous_track, media._update_position, media._extract_colors, media._kmeans_colors, audio._analyze_audio (FFT), obd._monitor_connection, esp32._read_serial, settings.save_settings. Add a scope at the top of any function worth watching.

What is measured

Outputs

• Terminal: a colour-coded [PERF] line refreshed every second; slow slots every 5 s.
• CSV: columns timestamp, loop_avg_ms, loop_p50_ms, loop_p95_ms, loop_p99_ms, loop_max_ms, gil_avg_ms, gil_p99_ms, cpu_pct, mem_mb, threads.
• Perf log: plain text with OK / WARN / STUTTER tags and slow-slot details.
• QML HUD: perfMonitor.summaryText.
• Command server: get_metrics, get_detailed_report, get_slot_timings.

Manual instrumentation

#include "../util/perfscope.h"
void Foo::bar()
{
    OCTAVE_PERF_SCOPE("foo.bar");
    ...
}

Screenshots & Video Stories

dev/screenshots/ (auto.py, stories.py, optimize.py; core.py / scenarios.py / cli.py are the deprecated xdotool tool kept for reference). Full documentation: dev/docs/SCREENSHOTS.md.

Every launcher (auto.py, stories.py, python -m dev.collage, dev/tests/drive_dashboard_editor.py, dev/shots_gap/) starts the app through dev/app_launch.py, which picks the binary ($OCTAVE_BIN, else build-desktop-<user>/octave, build/octave, then the newest build*/octave) and starts it with --dev --profile (--profile alone for production mode).

Menu sweep

python -m dev.screenshots                # launch dev mode headless (Xvfb if installed), shoot every page, quit
python dev/screenshot_tool.py            # identical wrapper
python -m dev.screenshots --visible      # real window (full GPU; a tiling WM may resize it)
python -m dev.screenshots --no-launch    # sweep an app you started yourself with --profile
python -m dev.screenshots --prod         # production mode (no --dev), real OBD

Options: --size WxH (1280x720), --settle SECS (1.2), --dev-chrome, --keep, --port N (9876), --out DIR, and the mode flags --xvfb / --offscreen. Mode is auto-picked --visible > --offscreen > Xvfb (if xvfb-run exists) > offscreen. Output: dev/screenshots/output/*.png, manifest.json, GALLERY.md for all 11 top-level pages and 6 settings sections. --out must be an absolute path inside the checkout (the manifest stores repo-relative paths). The offscreen platform has no GL, so the ColorOverlay icons and MultiEffect album art render blank there — Xvfb (xorg-server-xvfb, llvmpipe) is the faithful headless path.

Video stories (README / demo clips)

python -m dev.screenshots.stories --list
python -m dev.screenshots.stories                          # all stories
python -m dev.screenshots.stories drive media --visible    # Wayland is fine
python -m dev.screenshots.stories tour --media-folder ~/Music --size 1280x720 --fps 30
python -m dev.screenshots.stories --no-launch drive        # app already up with --profile

Launches the dev app with its own settings profile (dev/screenshots/profile/, so demos never touch your real config), drives it over the command server (navigation, media, sim_*) and records with record_start / record_stop: a GUI-thread QTimer calls root.grabWindow() per frame and pipes raw RGBA into ffmpeg -c:v libx264 -crf 18 (keep fps ≤ 30). Frames are paced by wall clock: when rendering misses ticks (the 3D vehicle under software GL) the last frame is repeated, so clips play at real speed (repeated in the stop line). Grabs are scaled to the logical window size, so a device pixel ratio above 1 (e.g. QT_FONT_DPI=144 under X11) does not crop the video. Each story yields <story>.mp4, an 800 px animated .webp at 15 fps (the README asset), a palettegen .gif and the requested stills under dev/screenshots/output/stories/, plus manifest.json. Stories are step lists in stories.py (("nav", page), ("settings", section), ("wait", s), ("still", name), ("rec", name) / ("stop",), ("media", action), ("sim", action, args), ("click", objectName) (waits up to 3 s for it), ("click_text", label), ("long_press_text", label), ("long_press_current",) (the playing track’s row), ("type", field, text[, enter]) (one character at a time so it reads on video), ("tap", x, y), ("wait_item", name), ("pid", search, id) (editor PID picker), ("py", fn)) registered in STORIES: tour, drive, media, dashboards, settings, jeep, shiftlight, editor (builds, previews and saves a “Trail Rig” dashboard, deleted again afterwards), diagnostics (warning lights, then read / freeze-frame / clear codes), library (song action sheet, sort, playlists, music search; search needs network), sensors (simulated IMU, 3D vehicle, clock still) and mirror (needs a phone, runs only when named). --out may point outside the repo (the manifest then uses absolute paths).

python -m dev.screenshots.optimize <png|mp4> --width N --out frontend/assets/readme rescales (lanczos) and recompresses with ffmpeg, then pngquant if installed. Keep animated assets under ~3 MB. The same operations are the run_story, record_*, sim and optimize_assets MCP tools.

AI Usability Testers

dev/ux/ has AI agents use the app the way a person does, to find where the UI confuses or slows people down. Each tester is a persona (first_timer, driver, enthusiast, non_techie) given a goal in its own words (“mute the sound”, “find out if the car has trouble codes”). It sees only a screenshot with a numbered tag on every control list_interactive reports, and can only tap, long-press, swipe, scroll and type. navigate, set_prop and the settings actions are kept for the orchestrator, which uses them for setup and to check, from the app’s own state, whether the goal was really reached. Every run gets its own instance (--dev --sim --profile --command-port N under Xvfb, with a temp HOME / XDG_* and the throwaway sim config), so runs can go in parallel.

• venv/bin/python dev/ux/run.py [-t tasks] [-p personas] [--parallel N] [--repeat N] [-m model]: runs the testers through a local vision model in Ollama (default qwen2.5vl:7b). Tasks, personas and success checks are in dev/ux/tasks.json. Each run writes per-step screenshots, a steps.jsonl with what the tester saw, thought, did and complained about, the result, and an in-character debrief to dev/ux/runs/<stamp>/.
• venv/bin/python dev/ux/audit.py: a rule-based sweep with no model. It visits every page and every settings card and flags tap targets under 56 px, overlapping tap areas, controls with no text or icon, and screens with more than 35 controls.
• venv/bin/python dev/ux/backlog.py: combines the latest run and audit into evidence.md (the task scoreboard, friction by screen, dead-tap hotspots, debrief issues and audit hits), which triage turns into the ranked backlog.

The cycle is: run, collate, triage, fix one item, then re-run the same tasks to confirm that success went up or the number of taps went down. See dev/ux/README.md.

How to Add New Features

Mobile-only code lives behind #ifdef Q_OS_ANDROID / Q_OS_IOS.

1. Manager: add src/managers/foo.h / foo.cpp (a QObject with Q_PROPERTY, Q_INVOKABLE, signals; log through a QLoggingCategory), list both files in CMakeLists.txt's qt_add_executable, add it as a member of AppCore (src/appcore.h, in construction order), wire it in src/appcore.cpp and expose("fooManager", &fooManager) there: that makes it a QML context property and a service object at once. Write files that change while driving with QSaveFile.
2. Settings: add the key with its default to SettingsManager (defaults table + Q_PROPERTY + save_xxx), and to the settings registry if it should appear in the Quick Panel.
3. QML: build the view in frontend/; settings pages go under frontend/settings/. Gauges and dashboards follow docs/GAUGE_AUTHORING.md.
4. Dev mode / tooling: if the feature depends on hardware, add a simulator in src/dev/ (wired in devruntime.cpp); add command-server actions (registerAction) and MCP tools if an agent should be able to drive it; put an OCTAVE_PERF_SCOPE on any new hot path.
5. Verify: cmake --build build -j and ctest --test-dir build, then run it (./build/octave --dev --profile, screenshots / stories / dashboard drivers for UI work). Add a test under tests/cpp/ for logic that can run headless (below).
6. Wiki: update the manager page and Signals & Slots Reference, the Settings Reference for new keys, and rebuild the search index. Stale docs are treated as worse than missing docs.

Testing & Linting

Test suite (QtTest, ctest)

tests/cpp/ is the test suite. It is built when OCTAVE_BUILD_TESTS is on (the default for -DCMAKE_BUILD_TYPE=Debug desktop builds) and runs headless on the offscreen platform:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build --output-on-failure        # or run one: build/tests/cpp/tst_obdsim

Each test compiles the sources it needs (octave_add_test() in tests/cpp/CMakeLists.txt, with OCTAVE_SOURCE_DIR defined for repo files) and gets its own temp HOME / XDG_CONFIG_HOME when it touches settings or exports, so a run never writes the real config. Phone-mirror tests use tests/cpp/fake-adb.sh as adb (behaviour set through FAKE_ADB_* variables, documented in the script). A few tests reach private members through a friend class Tst… declaration in the manager's header. tst_obdsim and tst_obdadapterfinder link the simulator from src/sim/, in every build; tst_boot skips its --dev --profile and --headless --dev cases without it.

Manual testing workflow

1. Dev mode: ./build/octave --dev for rapid iteration with the simulator and keyboard controls; --profile to script it.
2. Profile mode: ./build/octave --profile and watch loop latency / thread jitter; run dev/docs/perf_test_plan.md through the MCP server before and after a change that touches a hot path.
3. UI-driving scripts: dev/tests/drive_dashboard_editor.py for the editor; write new ones against the find_item / click / drag actions.
4. Logs: --debug for verbose logs (octave-cpp-debug.log).
5. Hardware: the Orange Pi 5 Plus head unit in the Jeep is the reference for OBD, IMU, gesture, ESP32 and phone-mirror changes (the aarch64 AppImage exists for it); the Galaxy Tab S6 / S22 Ultra are the Android targets named in TODO/android-cpp-port.md.
6. Before tagging: cmake --build build -j and ctest --test-dir build; CI then builds every platform on a v* tag.

Continuous Integration

.github/workflows/build.yml has always-on checks and a tag-gated release matrix (full detail on the Building page):

• lint — ruff check . over the Python tools in scripts/ and packaging/, and scripts/gen_gauge_param_docs.py followed by git diff --exit-code docs/GAUGE_AUTHORING.md, so the generated parameter table cannot fall behind the catalog; and tools/api/check_compat.py, which compares docs/api/ with the PR's base (or the commit before a push) and fails when a stable member, a parameter id or its unit is removed or changed without a kProtocolVersion bump and a docs/api/CHANGELOG.md entry naming it (rules: docs/api/README.md, Versioning).
• cpp-compile-check — Debug CMake/Ninja build against Qt 6.7.3, the ctest suite (above), then qmllint over frontend/ failing only on critical entries, so a C++ or QML break cannot sit on main until the next tag.
• phone-server — rebuilds the phone-server jar from source (JDK 21) and checks the committed jar carries the same class and version string; hash mismatch is a warning.
• sdk — npm test for sdk/typescript: its generated types must match docs/api/, the facade type-checks, and the client passes its tests against a fake service.
• cpp-build-windows / cpp-build-macos / cpp-build-linux / cpp-build-linux-arm64 / cpp-build-android — Release builds and installers, only on v* tags or manual dispatch, and only after lint and cpp-compile-check pass.
• release — attaches the five installers to a single GitHub Release on a version tag, published as a pre-release until the published files pass clean-VM testing (see Building).

.github/workflows/wiki-pages.yml publishes the OCTAVE project site to GitHub Pages on every push to main that touches src/, frontend/, CMakeLists.txt, packaging/wasm/ or wiki/ (or by manual dispatch). The project site takes the custom domain of the RobDeGeorge.github.io user site, so the site root is robdegeorge.com/OCTAVE/: the app itself, built for the browser with Qt for WebAssembly by packaging/wasm/build.sh (Qt 6.12 wasm_multithread + emsdk 5.0.5, both cached between runs) and hosted by packaging/wasm/index.html; the build-wasm job uploads it and the deploy job assembles the site. The wiki lives under robdegeorge.com/OCTAVE/wiki/, which is the address linked from the README. The workflow copies wiki/ into _site/wiki/ without the index builder scripts (rsync --exclude '*.py') and generates a redirect stub /OCTAVE/<page>.html for every wiki page, so the old top-level wiki links still resolve. Internal wiki links are relative, so the wiki works under that subpath unchanged; the in-app reader files (embedded.js / embedded.css) are published too but never loaded by the website. The lowercase robdegeorge.com/octave/ and /octave/wiki/ redirect from the website repo. Run python wiki/build_search_index.py before pushing wiki edits so the published search is current.

To test the browser build locally, build it (Building) and serve the staged folder with any static server that sends the COOP/COEP headers threaded WebAssembly needs (a plain python -m http.server does not): packaging/wasm/README.md carries a one-line Python server (the headers are Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp). The published site gets the headers from packaging/wasm/coi-serviceworker.js instead.

Deferred Work: the TODO Folder

TODO/ holds one markdown file per intentionally deferred plan, written so a future session can pick it up cold: a Status line, a Last updated date, why it is parked, file paths and line numbers, prerequisites, a recommended order, and "delete this file when done". These are planning notes, not the source of truth for implemented behavior; verify them against the source before acting. TODO/README.md is the index: every plan with its one-line goal, effort (S / M / L / XL) and the device it needs, ordered from quick wins to new subsystems. It was last audited against the code on 2026-10-18, when finished and obsolete plans were deleted.