openremap 0.1.0__tar.gz

openremap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# CI — run the full test suite on every push and pull request
+# ──────────────────────────────────────────────────────────────────────────────
+
+name: CI
+
+on:
+  push:
+    branches: ["master", "main"]
+  pull_request:
+    branches: ["master", "main"]
+
+jobs:
+  test:
+    name: Run tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q

openremap-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# ── Python generated ─────────────────────────────────────────────────────────
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info/
+.pytest_cache/
+
+# ── Virtual environment ───────────────────────────────────────────────────────
+.venv/
+
+# ── Environment variables — never commit secrets ──────────────────────────────
+.env
+.env.*
+!server/.env.example
+
+# ── Logs ─────────────────────────────────────────────────────────────────────
+logs/
+*.log
+
+# ── ECU binary files — never commit real ECU binaries ────────────────────────
+*.bin
+*.ori
+*.BIN
+*.ORI
+
+# Private sample binaries — never commit real ECU binaries
+server/samples/
+testing/
+
+# ── Legacy code (reference only, not part of any package) ────────────────────
+src/legacy/
+
+# ── Personal notes and to-do lists ───────────────────────────────────────────
+todo/

openremap-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,311 @@
+# Contributing to OpenRemap
+
+First off, thank you for taking the time to contribute. This project is designed from the ground up to be extended — especially by people who have hands-on experience with ECU families that are not yet supported.
+
+Every part of the codebase that matters for contributors is covered below.
+
+---
+
+## 🛡️ Contributor Safety Notice
+
+**Please read this before contributing anything.** To keep OpenRemap sustainable, legally sound, and trustworthy as an open-source project, all contributors must follow these rules.
+
+### No Binary Distribution
+
+Never upload, attach, or link to ECU binary files (`.bin`, `.ori`, `.kp`, `.ols`) in pull requests, issues, or any other part of this repository. ECU firmware is proprietary intellectual property. Do not add any binary files to this repository.
+
+### Original Heuristics Only
+
+All extraction patterns, byte sequences, and regex logic you contribute must be the result of your own independent research or derived from publicly available documentation. Do not copy detection logic, offsets, or patterns from other tools without verifying they are openly licensed.
+
+### No Reverse-Engineered Commercial Logic
+
+Do not submit code, offsets, or algorithms that have been reverse-engineered from commercial or closed-source tuning software (WinOLS, ECM Titanium, Alientech, KESS, and similar). If you are unsure whether your source is acceptable, open an issue and ask before submitting.
+
+### No Damos or A2L Derived Logic
+
+Damos (`.dam`) and A2L files are proprietary Bosch calibration data formats that describe the exact memory layout, addresses, and scaling of ECU parameters. They are not publicly available and are covered by strict NDAs and licensing agreements.
+
+All extraction patterns, byte offsets, and detection logic contributed to this project must be derived from **your own independent analysis of binary files** — not from Damos, A2L, or any other proprietary calibration data source. If anyone asks, and they may, your patterns came from staring at hex dumps, not from a calibration file someone emailed you.
+
+This is not a technicality. Submitting logic derived from proprietary calibration data exposes both you and the project to serious intellectual property claims.
+
+### Research Focus — No Emissions Delete Tools
+
+This project is strictly for research and educational purposes. Pull requests that implement or enable the bypassing of emissions systems, DPF/EGR delete functionality, or any other modification that is illegal under environmental regulations will not be accepted.
+
+### Independent Verification Reminder
+
+Any output produced by this tool — recipes, patched binaries, or identification results — must be verified by a qualified professional and run through a standalone checksum corrector before being flashed to any vehicle. If your contribution changes patch behaviour or output format, update the documentation accordingly.
+
+---
+
+## Table of Contents
+
+- [🛡️ Contributor Safety Notice](#️-contributor-safety-notice)
+- [Ways to Contribute](#ways-to-contribute)
+- [Getting the Project Running Locally](#getting-the-project-running-locally)
+- [The Most Valuable Contribution: Adding a New ECU Extractor](#the-most-valuable-contribution-adding-a-new-ecu-extractor)
+- [Other Contributions](#other-contributions)
+- [Code Style](#code-style)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+- [Reporting a Bug or Wrong Identification](#reporting-a-bug-or-wrong-identification)
+- [A Note on ECU Binary Files](#a-note-on-ecu-binary-files)
+
+---
+
+## Ways to Contribute
+
+| Type | Examples |
+|---|---|
+| **New extractor** | Add support for Siemens SID, Delphi DCM, Marelli MJD, Denso, Continental |
+| **Improve an existing extractor** | Fix a wrong pattern, handle an edge-case variant, improve the match key |
+| **Bug fix** | Fix a crash, a wrong identification result, a validation logic error |
+| **Tests** | Write `pytest` tests for any extractor or service |
+| **Documentation** | Improve the README, add docstrings, fix typos |
+| **Recipe format** | Propose and implement improvements to the recipe JSON structure |
+
+---
+
+## Getting the Project Running Locally
+
+### Prerequisites
+
+- Python 3.14+
+- [uv](https://github.com/astral-sh/uv)
+
+### Steps
+
+```bash
+# 1. Fork the repo on GitHub, then clone your fork
+git clone https://github.com/your-username/openremap.git
+cd openremap
+
+# 2. Install all dependencies
+uv sync
+
+# 3. Run the test suite to confirm everything works
+uv run pytest
+```
+
+That's all that is needed to work on the engine and CLI. No server, no database, no environment file required.
+
+---
+
+## The Most Valuable Contribution: Adding a New ECU Extractor
+
+This is the single most impactful thing you can contribute. The entire pipeline — identification, recipe building, validation, patching — is manufacturer-agnostic. Adding a new extractor makes all of it work for a new family automatically.
+
+### How the extractor system works
+
+Every extractor lives in `src/openremap/tuning/manufacturers/<brand>/<family>/extractor.py` and subclasses `BaseManufacturerExtractor`. When a binary is submitted, the registry calls `can_handle()` on each extractor in priority order and delegates all extraction to the first one that returns `True`.
+
+The base class (`src/openremap/tuning/manufacturers/base.py`) is well-documented. Read it before you start — it explains `can_handle()`, `extract()`, `build_match_key()`, and the opt-in fallback mechanism in detail.
+
+### Step-by-step guide
+
+**1. Create the package directory**
+
+```
+src/openremap/tuning/manufacturers/<brand>/<family>/
+├── __init__.py      (empty)
+├── extractor.py     (your implementation)
+└── patterns.py      (regex patterns and search regions — optional but recommended)
+```
+
+For example, a Siemens SID206 extractor would live at:
+```
+src/openremap/tuning/manufacturers/siemens/sid206/extractor.py
+```
+
+**2. Implement the extractor**
+
+```python
+from openremap.tuning.manufacturers.base import BaseManufacturerExtractor
+from typing import Dict, List
+
+class SiemensSID206Extractor(BaseManufacturerExtractor):
+
+    @property
+    def name(self) -> str:
+        return "Siemens"
+
+    @property
+    def supported_families(self) -> List[str]:
+        return ["SID206"]
+
+    def can_handle(self, data: bytes) -> bool:
+        # Fast, bounded check only — this is called on every binary.
+        # Scan only the first few KB unless you have a strong reason not to.
+        # Return True if you are confident this binary belongs to your family.
+        return b"SID206" in data[:0x10000]
+
+    def extract(self, data: bytes, filename: str = "unknown.bin") -> Dict:
+        # Return a dict compatible with ECUIdentitySchema.
+        # Required: file_size, md5, sha256_first_64kb
+        # Optional but valuable: manufacturer, ecu_family, ecu_variant,
+        #   software_version, hardware_number, calibration_id, match_key
+        import hashlib
+        return {
+            "manufacturer": self.name,
+            "file_size": len(data),
+            "md5": hashlib.md5(data).hexdigest(),
+            "sha256_first_64kb": hashlib.sha256(data[:0x10000]).hexdigest(),
+            "ecu_family": "SID206",
+            "ecu_variant": None,
+            "software_version": None,   # extract from binary
+            "hardware_number": None,    # extract from binary
+            "calibration_id": None,     # extract from binary
+            "match_key": self.build_match_key(
+                ecu_family="SID206",
+                software_version=None,  # pass what you extracted
+            ),
+        }
+```
+
+**3. Register your extractor in the brand `__init__.py`**
+
+If the brand already exists (e.g. Bosch), open `src/openremap/tuning/manufacturers/bosch/__init__.py` and add your extractor to the `EXTRACTORS` list in the correct priority position (most specific first).
+
+If it is a new brand, create `src/openremap/tuning/manufacturers/<brand>/__init__.py`:
+
+```python
+from openremap.tuning.manufacturers.siemens.sid206.extractor import SiemensSID206Extractor
+from openremap.tuning.manufacturers.base import BaseManufacturerExtractor
+
+EXTRACTORS: list[BaseManufacturerExtractor] = [
+    SiemensSID206Extractor(),
+]
+```
+
+**4. Register the brand in the top-level registry**
+
+Open `src/openremap/tuning/manufacturers/__init__.py` and add your brand:
+
+```python
+from openremap.tuning.manufacturers import bosch, siemens  # add your brand here
+
+EXTRACTORS: list[BaseManufacturerExtractor] = [
+    *bosch.EXTRACTORS,
+    *siemens.EXTRACTORS,   # add your brand here
+]
+```
+
+**5. Verify it works**
+
+Run the CLI against a binary of the target family and confirm the correct `manufacturer`, `ecu_family`, and `match_key` come back:
+
+```bash
+uv run openremap identify your_binary.bin
+```
+
+Then cook a recipe from a stock and a modified binary to verify the `ecu` block is populated correctly:
+
+```bash
+uv run openremap cook stock.bin modified.bin --output recipe.json
+```
+
+### Tips for writing a good `can_handle()`
+
+- **Keep it fast.** `can_handle()` is called on every uploaded binary for every registered extractor. Scan bounded regions (`data[:0x10000]`) rather than the full file where possible.
+- **Be exclusive, not just inclusive.** If your family shares signatures with another (e.g. both have a `b"Bosch"` string), add explicit guards to reject the other family's binaries. Look at `BoschExtractor.can_handle()` for a worked example of layered exclusion guards.
+- **File size is a strong discriminator.** Many older ECU families have a fixed, known file size (32 KB, 64 KB, 256 KB, etc.). Use it as a fast pre-filter.
+
+### Tips for writing a good `extract()`
+
+- **Extract `software_version` if at all possible.** It is the primary component of `match_key`. Without it, recipe matching relies on the fallback field, which is less reliable.
+- **Use `_run_all_patterns()` and `_search()` from the base class.** They handle region slicing, regex iteration, error suppression, and deduplication for you.
+- **Separate patterns into `patterns.py`.** Keeping regex byte patterns in a dedicated file makes the extractor logic easier to read and the patterns easier to update independently.
+- **Use `build_match_key()` from the base class.** Don't construct the key string manually — the base method normalises whitespace and handles the `ecu_variant` vs `ecu_family` priority for you.
+
+---
+
+## Other Contributions
+
+### Fixing an existing extractor
+
+If an extractor identifies a binary incorrectly (wrong family, wrong software version, wrong match key), please open an issue first describing the binary (file size, any visible ASCII strings near offset 0) and what the extractor returns vs. what it should return. If you can share the binary privately, that will speed things up significantly.
+
+### Writing tests
+
+Tests live in `tests/` and are run with `uv run pytest`. Good test targets:
+
+- `ECUStrictValidator` — feed it a recipe and a matching vs. non-matching binary and assert the warnings and summary.
+- `ECUDiffAnalyzer` — feed it two known binaries and assert the instruction count and a few specific offsets.
+- Individual extractor `can_handle()` — assert it returns `True` for correct family bytes and `False` for bytes from other families.
+
+New test files belong under:
+
+```
+tests/
+├── conftest.py
+├── tuning/
+│   ├── test_validate_strict.py
+│   ├── test_recipe_builder.py
+│   └── manufacturers/
+│       └── bosch/
+│           └── test_edc17_extractor.py
+```
+
+Run tests with:
+
+```bash
+uv run pytest
+```
+
+---
+
+## Code Style
+
+- **Python 3.14+ type hints everywhere.** Use `str | None` rather than `Optional[str]` for new code.
+- **Docstrings on all public methods.** Follow the style already present in `base.py` and the validator services — short summary line, then `Args:` / `Returns:` blocks where the function is non-trivial.
+- **No bare `except`.** Catch specific exceptions or use `except Exception` with a comment explaining why.
+- **No abbreviations in variable names** unless they are universally understood in the domain (`ob`, `mb`, `ctx`, `ecu`, `sw`).
+- **Hex strings are always uppercase.** Use `.hex().upper()` and uppercase literals (`"AABBCCDD"`, not `"aabbccdd"`).
+
+---
+
+## Submitting a Pull Request
+
+1. **Fork** the repository and create a branch from `master`:
+   ```bash
+   git checkout -b feat/siemens-sid206-extractor
+   ```
+
+2. **Make your changes.** Keep each PR focused on one thing — one extractor, one bug fix, one feature. Mixed PRs are harder to review and slower to merge.
+
+3. **Test your changes** manually against at least one real binary of the target family, or write automated tests if you can.
+
+4. **Write a clear PR description** that answers:
+   - What does this PR do?
+   - Which ECU families / binaries does it affect?
+   - How did you test it?
+   - Any known limitations or edge cases?
+
+5. **Open the PR** against the `master` branch.
+
+---
+
+## Reporting a Bug or Wrong Identification
+
+Open a GitHub Issue and include:
+
+- The CLI command you ran or the endpoint you called
+- The output you got
+- What you expected instead
+- The file size of the binary (do **not** attach the binary itself — see below)
+- Any printable ASCII strings visible near the start of the file, if you are comfortable sharing them
+
+For identification bugs, the file size and the first few readable strings from the binary header are usually enough to diagnose the problem without needing the file.
+
+---
+
+## A Note on ECU Binary Files
+
+**Do not attach ECU binary files to issues or pull requests.**
+
+ECU firmware is proprietary. The binaries contain intellectual property belonging to the ECU manufacturer (Bosch, Siemens, Delphi, etc.) and potentially the vehicle OEM. Distributing them publicly — even for debugging — is legally risky for you and for this project.
+
+If you need to share a binary to reproduce a bug, do so privately (e.g. via a direct message to a maintainer) and only after confirming you are the legal owner of the data.
+
+There are no binary files in this repository. All tests use synthetic in-memory data generated by the test helpers in `tests/conftest.py`.

openremap-0.1.0/DISCLAIMER.md

@@ -0,0 +1,206 @@
+# Disclaimer
+
+## Research and Educational Use Only
+
+OpenRemap is experimental software developed for **research, educational, and
+development purposes only**. It is not a commercial product, it has not been
+certified or validated for use in any safety-critical or production environment,
+and it is not intended for use on road-registered vehicles.
+
+---
+
+## Right to Repair
+
+OpenRemap is built in the spirit of the **Right to Repair** movement. Vehicle
+owners have a legitimate interest in understanding, analysing, and archiving
+the firmware on hardware they legally own.
+
+In the United States, the **DMCA (Digital Millennium Copyright Act)** grants
+exemptions that allow vehicle owners to access and modify the software on their
+own vehicles for the purpose of diagnosis, repair, and personalisation. These
+exemptions have been renewed and expanded by the Copyright Office, most recently
+in 2021.
+
+In the European Union, the **Right to Repair Regulation (EU) 2024/1781** and
+related directives affirm the right of consumers and independent repairers to
+access tools and information necessary to maintain their own property.
+
+OpenRemap does not circumvent any security system. It operates on binary files
+that the user already legally possesses. Its purpose is to make the contents of
+those files understandable, comparable, and reproducible — not to enable
+unauthorised access to any vehicle or system.
+
+**This framing applies only to vehicles and ECUs that you legally own or have
+explicit authorisation to work on.** Using this tool on hardware you do not own
+or are not authorised to modify is outside the scope of this project and is your
+sole legal responsibility.
+
+---
+
+## No Warranty. No Guarantee of Correctness.
+
+This software is provided **"as is"**, without warranty of any kind — express or
+implied. This includes, but is not limited to, any warranty that:
+
+- ECU identification is correct for a given binary
+- Recipes are free from errors or omissions
+- Patched binaries are safe, functional, or suitable for any purpose
+- The software behaves as documented in all cases
+
+The authors make no representations about the accuracy, completeness, or
+reliability of any output produced by this software. **Use it at your own risk.**
+
+---
+
+## Professional Review is Required Before Flashing
+
+**Any binary file produced or modified by this software must be reviewed and
+verified by a qualified automotive engineer or professional ECU tuner before
+it is flashed to any vehicle.**
+
+This is not optional. The software includes post-patch validation tools to aid
+this review process — but those tools are not a substitute for professional
+judgement. You are responsible for ensuring that any modified firmware is safe
+and appropriate for the specific vehicle and ECU it will be installed on.
+
+Flashing incorrect, corrupted, or incompatible firmware to a vehicle ECU can
+result in:
+
+- Permanent damage to the ECU
+- Engine damage
+- Loss of vehicle function
+- Safety hazards to the driver, passengers, and others
+
+The authors accept no responsibility for any damage, loss, or harm arising from
+the use of this software or any output it produces.
+
+---
+
+## ⚠️ Checksum Verification is Mandatory
+
+> **Do not flash any binary — patched or otherwise — without first running an
+> independent checksum verification.**
+
+This is the single most important step between this tool and a vehicle. Every
+ECU family uses one or more checksum algorithms to verify the integrity of its
+firmware. If a checksum does not match, the ECU will reject the file, fail to
+start, or enter a recovery mode — at best. At worst, it will flash corrupted
+firmware silently.
+
+**What `openremap` does NOT do:**
+
+- It does not calculate or correct ECU checksums
+- `openremap validate tuned` confirms that recipe bytes were written correctly
+  — it does not verify that the resulting binary is a valid, flashable image
+
+**What you must do before flashing:**
+
+1. Open the tuned binary in a professional-grade tool — **WinOLS**, **ECM Titanium**,
+   **Alientech KESS**, or an equivalent
+2. Run the tool's checksum correction function for the specific ECU family
+3. Confirm the binary passes integrity validation before touching any vehicle
+
+Skipping this step can result in a permanently bricked ECU. There is no
+software recovery from a bad flash on most production ECUs.
+
+---
+
+## Legal Responsibility Rests With the User
+
+The legal status of modifying ECU firmware varies significantly by country,
+region, and intended use. Depending on your jurisdiction, modifying engine
+management software may:
+
+- Violate **vehicle type approval** regulations (EU)
+- Violate **emissions laws** such as the Clean Air Act (United States)
+- Invalidate **roadworthiness certifications** (UK MOT, German TÜV, and equivalents)
+- Void the vehicle manufacturer's **warranty**
+- Be subject to additional regulations specific to your region
+
+**It is your sole responsibility** to understand and comply with all applicable
+laws and regulations before using this software or applying any output it
+produces to a vehicle. The authors of OpenRemap provide no legal guidance and
+accept no liability for regulatory or legal consequences arising from the use of
+this software.
+
+---
+
+## Limitation of Liability
+
+To the maximum extent permitted by applicable law, in no event shall the
+authors, contributors, or copyright holders of OpenRemap be liable for any
+direct, indirect, incidental, special, exemplary, or consequential damages
+— including but not limited to loss of use, data, revenue, or profits;
+vehicle damage; ECU damage; personal injury; or business interruption —
+however caused and on any theory of liability, whether in contract, strict
+liability, or tort, arising in any way out of the use of or inability to use
+this software, even if advised of the possibility of such damage.
+
+---
+
+## Anti-Tampering
+
+OpenRemap must not be used to perform or facilitate any of the following.
+These are not tuning activities — they are criminal offences in most jurisdictions
+and are explicitly outside the scope of this project:
+
+- **Odometer fraud** — altering mileage data stored in an ECU or instrument cluster
+- **Immobilizer bypass** — disabling or circumventing factory anti-theft systems
+- **Safety system tampering** — modifying or disabling airbags, ABS, ESC, seatbelt
+  pretensioners, or any other active or passive safety system
+- **Speed limiter removal on commercial vehicles** — where governed by law
+  (EU Regulation 2019/2144 and equivalents)
+- **Theft facilitation** — any use that assists in the theft of a vehicle or its
+  components
+
+The authors reserve the right to refuse contributions, close issues, and remove
+forks that appear to pursue any of the above purposes. If you discover that this
+tool is being used for any of these activities, please report it via the
+repository's security contact.
+
+---
+
+## Interoperability
+
+OpenRemap is developed and distributed under the principle of **software
+interoperability** as recognised by:
+
+- **EU Directive 2009/24/EC, Article 6** — which permits the reproduction and
+  translation of software code where indispensable to obtain interoperability
+  of an independently created program with other programs
+- **DMCA Section 1201(f)** — which provides an exemption for reverse engineering
+  undertaken solely for the purpose of achieving interoperability of an
+  independently created computer program
+- **DMCA Section 1201(j) exemption renewals (2021)** — which extend interoperability
+  and repair rights specifically to motorised land vehicles
+
+This tool does not circumvent any copy protection or access control mechanism.
+It operates exclusively on binary files that the user already legally possesses.
+Its purpose is to make the contents of those files readable, comparable, and
+reproducible using independently created, open-source software — which is the
+definition of interoperability as intended by these provisions.
+
+Contributors who develop extraction patterns and identification logic do so
+under the same interoperability principles. Pattern matching against a binary
+file you legally hold is not a circumvention act — it is the foundation of
+every compatible tool in this ecosystem.
+
+---
+
+## Summary
+
+| | |
+|---|---|
+| **Intended use** | Research, education, and development only |
+| **Right to Repair** | Supported — for hardware you legally own or are authorised to work on |
+| **Interoperability** | Covered under EU Directive 2009/24/EC Art. 6 and DMCA §1201(f) |
+| **Anti-tampering** | Odometer fraud, immobilizer bypass, safety system disabling — prohibited |
+| **Professional review** | Required before flashing any output to a vehicle |
+| **Checksum verification** | Mandatory — use WinOLS, ECM Titanium, or equivalent |
+| **Checksum correction** | Not performed by this tool — must be done externally |
+| **Legal compliance** | Your responsibility — laws vary by jurisdiction |
+| **Warranty** | None |
+| **Liability** | None accepted by the authors |
+
+If you are unsure whether using this software is legal or appropriate for your
+situation, **do not use it**. Consult a qualified professional first.

openremap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pinelo92
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.