Index
Every page in this wiki, in one list. Start with the project overview if you are new, or jump from the task table below if you already know what you are looking for.
How this wiki is organised
Each topic is written in up to three layers, so you can stop reading when you have what you need:
| Layer | Where it is | Written for |
|---|---|---|
| What it is and why | the section's index page |
someone who has never done this before — plain words, no jargon, a scenario |
| How to actually run it | cli.md |
real commands, real output, every flag, what to do when it fails |
| Exact technical detail | api.md |
field names, schemas, protocols, method signatures |
Two conventions worth knowing:
- Every term is defined where it first appears, and all of them together in the glossary.
- A page that is not fully current says so — an amber banner at the top of
the page, from its frontmatter
status.stablemeans "checked against the current release";outdated,stubandneeds-expansionmean exactly what they say.
Start from what you want to do
| I want to… | Go to |
|---|---|
| understand what this tool is | Project overview |
| look up a word I saw | Glossary |
| install it and run something | Install |
| know what a file from my car is | identify |
| know whether a file is sane | health · analyze |
| see the tuning tables inside a file | scan-maps |
| know what a tuner changed | diff-maps |
| save a change as a reusable file | cook |
| apply a saved change to another file | tune (being replaced by the apply ladder — see glossary) |
| check whether three files belong together | audit |
| add support for an unrecognised ECU | contribute |
| drive it from my own code | API |
| know if my ECU family is supported | read the legal and safety position |
Overview
| Page | What it covers |
|---|---|
| Project overview | What OpenRemap is — and why an ECU file no longer has to be a black box |
| Glossary | Every term, defined once, plus the four apply rungs and the rule ids you see in a refusal |
| Index | This page |
| License | MIT — what you may do with OpenRemap, and what it does not promise |
| Disclaimer | Intended use, right to repair, no warranty, and why a professional must review anything that is flashed |
Install
| Page | What it covers |
|---|---|
| Install | The two shapes OpenRemap comes in, what you need, and which install to pick |
| CLI | The terminal app — the three commands one install gives you, requirements, troubleshooting |
| Package | Install from PyPI with uv tool install openremap or pip install openremap, then update or remove it |
| Repo clone | Install from source — git, uv and a Rust toolchain, the test suite, where things live |
| Harness | The complete graphical app — 2D/3D maps, hex view, map dragging, workflows — coming with 1.0.0 |
Recipe
| Page | What it covers |
|---|---|
| The recipe | What a .remap file is, and why a written change list beats a patched file |
| Inside a recipe | Every part, field by field, in plain words |
| Why it matters | Readable, provable, portable, honest, no lock-in — and the limits |
| Sharing and copyright | What a recipe is not, what you can hand over, where the limits are |
| Format reference | The exact 5.0 schema, reader rules and compatibility policy |
Architecture
| Page | What it covers |
|---|---|
| Architecture | The five layers, what each may import, how a request travels, and the invariants |
| Repository map | Every directory, what belongs in it, and where new code goes |
| Extractors | Registry, base class, evidence tags, match keys, confidence scoring |
| Decoders | Which CPU is decoded by Rust, which by capstone, the cascade, the limits |
| Rust engine | The crate, its modules, the GIL release, how to rebuild it |
| API gate | Method registry, the three kinds, JSON-RPC, workflows |
| Services | The engine's service modules, recipe by recipe |
| The stack | Languages, build system, every library and why |
| Testing & CI | The suites, the corpora, parity goldens, what CI runs |
| Coverage | All 6 manufacturers and 38 extractors, with a page per family |
TUI
| Page | What it covers |
|---|---|
| TUI | The app, its eleven screens, how to move around, and the workspace it writes into |
| BOOT | The five startup checks, their real timings, and the repair panel when one fails |
| HOME | The eight task cards, the recent-files list, and the status line |
| IDENTIFY | What a file is — family, variant, software, confidence |
| INSPECT | Health, layout, checksum verdicts and coherence, failing check named |
| MAPS | Choosing a calibration table, and the SVG picture of the one you picked |
| COOK | Two files in, one 5.0 recipe out — strict first, forced only on refusal |
| DIFF | What changed, table by table, plus the regions no table explains |
| APPLY | The ladder from the screen: strict first, looser rung offered by rule |
| BATCH | Classifying a folder, with real pace, then organising as a second step |
| CONTRIBUTE | Measuring your own dumps and rendering a contribution |
| HELP | Capabilities generated from the engine's registry, plus the family reference |
| PICKER | The in-app file picker: keys, starting folder, Windows drives |
CLI
| Page | What it covers |
|---|---|
| CLI | The command line, how output reads, exit codes, and every command by task |
| Getting oriented | commands, workflow, families — the tool describing itself |
| Look at a file | identify, analyze, health, checksum, layout, scan-vins |
| Convert and read code | convert (HEX → binary) and routine (read code at an address) |
| Maps | scan-maps, diff-maps, map-image |
| Cook | cook-strict, cook-forced, recipe-info, merge |
| Apply | The ladder: tune-strict, -shift, -unique, -any, and how to read a refusal |
| Verify | validate before / check / after, and audit |
| Folders and test files | scan a folder, synth a practice file |
| Contribute | contribute extractor / check |
Getting started
| Page | What it covers |
|---|---|
| Getting started | Who this is for, the five-minute path, and the command map |
| About OpenRemap | The gap the project fills, why it is open source, the project aims, and an FAQ |
| Installation | Pick your platform — then Windows, macOS/Linux, or a developer setup from source |
| Installing on Windows | Step by step, written for people who rarely use a terminal |
| Installing on macOS / Linux | Step by step, per platform |
| Developer setup | Running from source, running the tests, building the Rust engine |
| Setup | Install, verify, update, develop, troubleshoot — the essential commands for every case |
| Quick start | Install → identify → health-check → cook → apply, in about five minutes |
| CLI reference | Every command with a one-line description and a worked session |
openremap workflow |
The built-in plain-English walkthrough, and what each step of it means |
| CLI, API & RPC | The three surfaces side by side, and when to use which |
| families | The supported-family reference: era, file sizes, notes, and full detail for one family |
Concepts
| Page | What it covers |
|---|---|
| Concepts hub | Where to start reading about how the tool thinks |
| How it works | The whole pipeline end to end — identify → health → checksum → cook → apply → audit |
| Confidence scoring | How the confidence tiers are built from signals, and what each tier promises |
| Evidence | Detection tags, signals, probabilistic labels, provenance — how a result explains itself |
| Recipe format | The .remap file specification — fields, structure, maps, and what a recipe deliberately does not store |
| Decoders | The CPU decoders, the code-reference signal, and the detection cascade |
| Architecture | How the pieces connect — engine, API gate, CLI, TUI, and the native core |
| Tune format (.orst) | The deprecated saved-tune format, kept for reference |
Commands — look at a file
| Page | What it covers |
|---|---|
| identify | What is this file? Manufacturer, family, software version, confidence |
| analyze | One pass that describes everything: identity, VIN, layout, maps, checksums, health |
| health | Six safety checks in one command, with a healthy / issues verdict |
| checksum | Which checksum schemes a file satisfies — detection only, never correction |
| layout | How the file is organised: code, calibration, erased pages, identity blocks |
| scan-vins | Find VIN candidates and score how believable each one is |
| convert | Turn Intel HEX / S-Record text into flat bytes |
| routine | Read the code around an offset as one-line pseudo-code |
Commands — tables and maps
| Page | What it covers |
|---|---|
| scan-maps | Find the calibration tables in a file without knowing the family |
| diff-maps | Compare two files table by table: which maps moved, and by how much |
Commands — tune and apply
| Page | What it covers |
|---|---|
| cook | (documents the retired 4.x cook; the current producers are cook-strict / cook-forced) — turn a stock and a tuned file into a recipe |
| cook-volatile | (retired command) — the 4.x car-portable recipe producer, kept for history |
| merge | Combine two recipes into one, validated against a common stock file |
| tune | (documents the retired 4.x tune; the current apply is the four-rung ladder) — apply a recipe safely |
| validate | The individual before / check / after steps, run by hand |
| audit | The receipt check: do stock, tuned and recipe belong together? |
Commands — libraries and contribution
| Page | What it covers |
|---|---|
| scan | Classify a whole folder of dumps, then optionally file them |
| synth | Generate an ECU-like file from scratch — no ECU, no dump |
| contribute | Measure your own dumps and hand over a new ECU family |
API
| Page | What it covers |
|---|---|
| API | What the programmatic surface is, and the three ways to call a method |
| API concepts | The method registry, input schemas, the three kinds, error codes |
| Workflows | Declarative .toml pipelines that chain methods |
| Transport (JSON-RPC) | The stdio wire protocol — drive the API from any language |
| Reference | The complete method catalogue |
Manufacturers
Each OEM has an index page and one page per supported family (era, file size, what the extractor reads, and notes). Two OEMs also have an internals page for people writing extractors.
| Page | What it covers |
|---|---|
| Bosch | 19 extractors, EDC1 through MD1 — plus Bosch internals |
| Siemens | Simtec 56, SIMOS, PPD, SID801/803, EMS2000, MS43, GS20 — plus Siemens internals |
| Delphi | Multec, Multec S |
| Magneti Marelli | IAW 1AV / 1AP / 4LV, MJD 6JF |
| Denso | 68HC16Y5, SH7055, SH7058, EE20 diesel |
| Hitachi | SH72546 |
Project
| Page | What it covers |
|---|---|
| Release notes | What changed in recent versions, in user terms |
| Contributing | The rules that apply to everything, and how to add an ECU family without sharing your dump |
| Third-party credits | The community work the checksum and detection knowledge stands on |
Note
This index mirrors the folder tree, which is also what generates the sidebar — so a page that exists is a page that is listed, and a page that is deleted leaves this list. When a section is reorganised, this page is rewritten with it.