Helltune

An offline Python workbench for ECU binary calibration, built alongside the original VAGEDCSuite sources. Qt desktop GUI and Textual TUI share the same map, project, comparison and checksum engine. Native launchers start directly, with no browser or web server.

• Side-by-side docked panels and custom maps from hex addresses, with live validation and editable axes/scaling.
• Editable map tables, hex view, visual selections, copy/paste, undo/redo and autosaved projects.
• MSA15 two-chip export with custom output folder and filenames, read-back verification and a separate checksum result.
• Dockable Inspector, inline arithmetic tools, single-column axis editing and verified binary export.
• Branded PDF reports with vehicle details, a printable dyno chart and optional maps, changes, samples and checksum pages.
• Whole-binary fuel presets: optional economy demand shaping and measured vegetable-oil adjustments, with previews across calibration banks and one-step undo.
• Multiple independent map windows with linked hover, original/current values and catalogue-wide byte-change reports.
• Manual / automatic / 4×4 calibration variants, detected from bank code IDs and gearbox markers, with shared map, dyno and preset filtering.
• Live 2D heatmaps, row/column curves and rotatable 3D surfaces beneath the GUI editor.
• One dyno plot with cyan torque (Nm) and orange power (hp / PS / kW); colored peak cards, sample inspection and optional comparison curves. The TUI adds enlarged unit labels, dual scales and detailed RPM inspection.
• Ember, Arctic, Midnight and High contrast themes, saved through Options in either interface.
• Dedicated row/column breakpoint editor with exact previews and shared-axis references.
• Brief/detailed explanations for all detected maps. Recognized functions describe increase/decrease effects and related maps; unidentified candidates explicitly retain an unknown function.
• Smart modifiers and coordinated templates, with source-bound map roles, exact before/after previews and one-edit undo.
• An offline Learn workspace with interactive calculators, hardware planning and a printable VP37 handbook.
• Vim navigation, character/row/block visual modes, command/path/map autocompletion and searchable command history in the terminal.

VP SOI correction: AFN/MSA15-family timing now uses signed counts × 0.01°, including the temperature limiter. Earlier builds inherited the wrong factor. Review older timing edits and exports.

Install on Arch Linux

Current version: 0.5.0. See the release notes.

From this checkout:

sudo pacman -S --needed base-devel python-build python-installer python-setuptools pyside6 python-matplotlib python-textual
makepkg -si
helltune
helltune-tui

base-devel provides makepkg; the PKGBUILD builds the current local checkout, including uncommitted Python changes. It installs the Python wheel, native commands, two application-menu shortcuts, icon and documentation. It does not package your firmware files, project database or optional checksum DLL. There is no AUR download or remote source checkout in this recipe. To build without installing, run makepkg -f and inspect the resulting helltune-0.5.0-1-any.pkg.tar.zst with pacman -Qip / pacman -Qlp.

See Arch packaging details, including removal and optional adapters.

Install with Python

Use Python 3.10+ and native wheels compatible with your system:

python3 -m venv .venv
.venv/bin/python -m pip install '.[native]'
.venv/bin/helltune
.venv/bin/helltune-tui

Install .[gui] or .[tui] for just one interface. The plain core CLI has no third-party runtime dependency. Optional spreadsheet adapters: pip install -r requirements-spreadsheet.txt. Optional checksum reference backend: pip install -r requirements-checksum.txt plus the separately supplied, pinned DLL described in the existing checksum documentation.

Repository launchers remain available:

./start-gui.sh /path/to/image.bin
./start-tui.sh /path/to/image.bin
python3 scripts/install-shortcuts.py

The launchers choose .venv when it contains the necessary interface packages, otherwise system Python. EDC15_PYTHON=/absolute/path/to/python overrides that selection. The shortcut installer writes user-local application entries pointing at this checkout and migrates its own older EDC15 entries. --directory ~/Desktop installs desktop files; --remove removes only entries managed by this installer.

First session

1. Open a binary with Ctrl+O. A new project retains the original bytes and autosaves each edit. Resume an existing project through File → Open project / TUI F4, or helltune --project PROJECT_ID.
2. Select a map in the catalogue. Ctrl+F filters the GUI list; F2 focuses the TUI list. Enter * in the TUI filter to include unidentified candidates.
3. Inspect the axes, units and Map description → Brief / Detailed before editing. In the TUI press F12, or enter :describe detailed.
4. Select cells, press Enter, and enter a physical value. Toggle raw display with GUI Ctrl+R / TUI F6. Preview and changed-cell colors update immediately after an edit.
5. Open additional maps with Ctrl/Shift-click in the catalogue, then Ctrl+Shift+M. Ctrl+Shift+T tiles the windows. Hover links use shared bytes first, then compatible physical coordinates; separate maps are not rewritten merely because their engine functions interact.
6. Check the Map impact tab. Ctrl+Z in the GUI / u in the TUI undoes an edit. Use the checksum report and explicit repair when appropriate, then Ctrl+S to export to a new binary file.

Source files are never overwritten. Projects retain history and original data. The existing project store path remains compatible with earlier EDC15 workbench versions; pass --projects-dir to choose another directory. Appearance preferences are separate at $XDG_CONFIG_HOME/helltune/options.json (default ~/.config/helltune/options.json).

Frequently used controls

Action	GUI	TUI
Help and complete keybindings	F1	F1 / ?
Open / export binary	Ctrl+O / Ctrl+S	Ctrl+O / Ctrl+S
Split MSA15 chip files	File → Split MSA15 chip files / Alt+S	Alt+S / :split
Set selected cells	Enter	Enter / i
Undo / redo	Ctrl+Z / Ctrl+Y	u / Ctrl+R
Visual selection	v, Shift+arrows, mouse drag	v contiguous, V rows, Ctrl+V rectangle
Copy / paste	Ctrl+C / Ctrl+V	y / p
2D / 3D preview	Live preview or Ctrl+3 / Ctrl+4	F9 / F10
Dyno	Ctrl+D	F11
Theme options	Options → Appearance, Ctrl+,	:theme, Ctrl+,
Map explanation	Map description tab	F12 / :describe brief
Axis breakpoints	Right-click table/header; Edit menu	Alt+R / Alt+C or :axis rows / :axis columns
Commands / completion	Ctrl+P / :	: then Tab / Shift+Tab

TUI Vim keybindings

h j k l or arrows move; counts repeat movements (12j). 0 / $ move to the first/last column, gg / G to the first/last cell, and Ctrl+F / Ctrl+B move a page. w / b move four cells. Use v, V or Ctrl+V to select; Escape returns to Normal. y yanks, p pastes, u undoes, Ctrl+R redoes. / searches, n / N repeat; ma sets a bookmark and 'a jumps to it. Vim navigation also works in lists, reports and the axis editor; prompts retain normal text entry. See TUI navigation.

After :, Tab completes commands, map addresses, paths, project IDs, theme names and supported arguments. Shift+Tab cycles backward; Up/Down recall commands. Escape first dismisses completion, then closes the prompt. File paths containing spaces are quoted automatically. See the full Vim and command guide.

In the dyno, h/l or ←/→ inspect RPM, n/w jump to peak Nm/power, p changes hp/PS/kW, c toggles comparison, t opens all samples and fuel limits, and j/k / PageUp / PageDown scroll. Escape returns to editing. Terminal colors follow NO_COLOR and terminal capabilities. If your shell sets NO_COLOR, run env -u NO_COLOR ./start-tui.sh to enable colors.

Maps, presets and explanations

The Helltune workflow guide documents themes, live charts, breakpoint editing, every preset formula, compatibility checks, stale previews and mod-calibration requirements. Map explanations list all recognized functions and their relationships.

Hardware recipes require independently verified custom definitions with the relevant physical units. Automatic raw N146/MAP sensor guesses are deliberately ineligible. Preset defaults are examples, not an engine-specific tune. The dyno uses calibration-derived estimates and explicit assumptions; it does not measure engine/wheel output. See analysis evidence.

Existing tools and scope

The native implementations reuse the existing project engine. Additional CLI and optional browser workflows remain documented in README-LINUX.md: binary tools, map pairing, EEPROM layout, descriptors, XDF, spreadsheet exchange, selectors, compressor charts, part numbers, VIN and library management. Run helltune-cli --help or python3 -m edc15 --help for the complete CLI.

Automatic map identification is heuristic and currently characterized on the supplied MSA15 GA images (60 named maps across three banks). It does not establish the ECU's active bank. Unclassified candidates are not proven tuning functions. Real FS validation and complete original-suite parity remain unfinished. This application edits local files; it does not flash an ECU.

Repository layout

The Python application lives in edc15/; original C# sources and manuals are grouped under legacy/VAGEDCSuite/. Firmware, the optional checksum DLL, virtual environments and build output remain local and are ignored by Git. See the repository layout and push instructions.

Development and verification

python3 -m unittest discover -s tests -v
QT_QPA_PLATFORM=offscreen python3 -m unittest -v tests.test_native_gui tests.test_native_tui tests.test_native_previews tests.test_map_windows tests.test_dyno_presentation tests.test_helltune tests.test_helltune_ui

For fixture-based tests, first provide the local images listed in MAPS/fixtures.json. Optional DLL checks also require DEV001.dll. Optional integrations skip when their dependencies are absent. Native tests exercise real Qt widgets and Textual pilots; core tests cover atomic changes, stale previews, source preservation, scales and identification evidence. Tests use supplied images and synthetic layouts and do not modify the original binaries. See verification notes for the recorded checks.

Helltune retains the original VAGEDCSuite code and attribution. README.txt contains the upstream freeware/source statement by Dilemma; no general OSI license was supplied, so packaging records LicenseRef-VAGEDCSuite rather than inventing a license. The generated icon and its full generation prompt are documented in asset provenance.