# bri3d/vw_flash architecture

> Architecture diagram of the GitHub repository bri3d/vw_flash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bri3d/vw_flash
- Repository: https://github.com/bri3d/vw_flash

## Overview

##### Project Type and Purpose
- This is an open-source Python-based ECU flashing toolkit for Volkswagen MQB vehicles (“VW_Flash”).
- It provides two frontends: a CLI tool (VW_Flash.py) and a WXPython GUI (VW_Flash_GUI.py).
- Underlying both is a shared core library that handles flash container extraction, cryptography, checksum fixes, and UDS communication over various hardware interfaces.

##### File Structure Analysis
- Top-level scripts:
- VW_Flash.py – command-line interface
- VW_Flash_GUI.py – WXPython GUI (with PyInstaller spec VW_Flash_GUI.spec)
- Core library (`lib/`):
- `connections/` – hardware abstraction (J2534, SocketCAN, fake driver)
- `crypto/` – encryption/decryption modules (AES, XOR, DSG, Simos)
- flash utilities (`*_flash_utils.py`, `checksum.py`, `extract_flash.py`)
- `modules/` – per-ECU handlers (Simos variants, DQ modules, Haldex)
- helpers (resource, DTC, FRF extraction)
- Support directories:
- `data/` – static CSVs and key files
- `frf/` – FRF flash container extractor
- `docs/` – design and usage documentation
- `tests/` – unit tests for file preparation
- Configuration & CI:
- requirements.txt, setup.py
- .github/workflows/python-app.yml for CI
- logging.conf, log_config.yaml

##### Key Insights from README
- Purpose: full custom reflashing + RSA bypass for specific ECUs
- Hardware support: Macchina A0 (J2534), Tactrix OpenPort, SocketCAN
- Architecture notes present in docs/*.md
- Extensibility: new modules under `lib/modules/`

- User Interfaces:
- CLI Frontend (VW_Flash.py)
- GUI Frontend (WXPython)
- Core Library (`lib/`):
- API Facade – entry point for both frontends
- Connection Layer – implements J2534, USB-ISOTP, SocketCAN
- Crypto Layer – AES, XOR, DSG, LZSS decompression
- Flash Engine – checksum, patch application, container extraction
- ECU Modules – per-device logic (Simos18, DQ250, etc.)
- Data Assets: `data/` + `frf/` container extractor
- External Systems:
- ECU Hardware (UDS over ISO-TP)
- Flash hardware (e.g., OpenPort, Macchina A0)
- Testing & CI: tests/ and GitHub Actions

- User → CLI / GUI: issues commands
- CLI / GUI → Core Library API: invokes operations
- Core Library → Connection Layer → Hardware Interfaces → ECU
- Core Library → Crypto Layer & Flash Engine → container & patch processing
- Flash Engine ↔ Data Assets (loads box_codes.csv, dtcs.csv, keys)
- Core Library → Logging subsystem (logging.conf, log_config.yaml)
- Tests → Core Library (unit tests of extraction and patching)
- CI Pipeline → runs Tests and lints code

c. Architectural Patterns & Design Principles
- Layered architecture: UI → API → domain services → hardware drivers
- Modular plugin pattern for ECU-specific logic under `lib/modules/`
- Hardware abstraction layer isolates transport implementations
- Separation of concerns: crypto, flash logic, and connection code kept separate
- Extensible open-source structure—new modules or connection drivers can be added

d. Relevant Technologies & Frameworks
- Python 3.x, `unittest` for tests, `black` for formatting
- WXPython for GUI
- PyInstaller (VW_Flash_GUI.spec) for Windows builds
- J2534 interface, SocketCAN drivers
- AES, LZSS compression/decompression

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Frontend\nVW_Flash.py"]:::ui
        GUI["GUI Frontend\nVW_Flash_GUI.py"]:::ui
        Spec["PyInstaller Spec\nVW_Flash_GUI.spec"]:::ui
    end

    %% Core Library
    subgraph "Core Library"
        API["API Facade"]:::core
        subgraph "Connection Layer"
            ConnDir["lib/connections/"]:::drivers
            ConnSetup["Connection Setup\nconnection_setup.py"]:::drivers
            J2534Drv1["J2534 Driver\nj2534.py"]:::drivers
            J2534Drv2["J2534 Connection\nj2534_connection.py"]:::drivers
            USBISO["USB-ISO-TP Driver\nusb_isotp_connection.py"]:::drivers
            FakeDrv["Fake Driver\nfake_connection.py"]:::drivers
        end
        subgraph "Crypto Layer"
            CryptoDir["lib/crypto/"]:::drivers
            AES["AES\naes.py"]:::drivers
            CryptoIfc["Crypto Interface\ncrypto_interface.py"]:::drivers
            DSG["DSG\ndsg.py"]:::drivers
            XOR["Simos XOR\nsimos_xor.py"]:::drivers
        end
        subgraph "Flash Engine"
            ExtractFlash["Container Extraction\nextract_flash.py"]:::core
            FlashUDS["UDS Flash Comm\nflash_uds.py"]:::core
            Checksum1["Checksum Utils\nchecksum.py"]:::core
            Checksum2["Fast CRC\nfastcrc.py"]:::core
            FlashUtils["ECU Flash Utils\n*_flash_utils.py"]:::core
        end
        subgraph "ECU Modules"
            ModulesDir["lib/modules/"]:::core
            DQ250["DQ250 Handler\ndq250mqb.py"]:::core
            DQ381["DQ381 Handler\ndq381.py"]:::core
            Haldex["Haldex Handler\nhaldex4motion.py"]:::core
            Simos["Simos Family Handlers\n(simos*.py)"]:::core
        end
    end

    %% Data & FRF
    subgraph "Data Assets"
        DataDir["data/"]:::data
        BoxCodes["Box Codes\nbox_codes.csv"]:::data
        DTCs["DTC Definitions\ndtcs.csv"]:::data
        FRFKeys1["FRF Key\nfrf.key"]:::data
        FRFKeys2["MQB DSG Key\nmqb_dsg_key.bin"]:::data
    end
    FRFExtractor["FRF Extractor\ndecryptfrf.py"]:::data

    %% Documentation
    Docs["Documentation\ndocs/"]:::data

    %% CI & Tests
    subgraph "CI & Testing"
        CI["CI Workflow\n.github/workflows/python-app.yml"]:::test
        Tests["Unit Tests\ntests/test_prepare.py"]:::test
    end
    Config1["Logging Config\nlogging.conf"]:::data
    Config2["Log Settings\nlogs/log_config.yaml"]:::data
    Packaging["Packaging & Requirements\nsetup.py\nrequirements.txt"]:::data

    %% External Hardware
    subgraph "External Systems"
        FlashHW["Flash Hardware\n(OpenPort/Macchina A0)"]:::external
        ECUHW["ECU Hardware\nUDS over ISO-TP"]:::external
    end

    %% Relationships
    CLI -->|"invokes"| API
    GUI -->|"invokes"| API
    Spec -->|"builds GUI"| GUI

    API -->|"uses"| ConnDir
    API -->|"uses"| CryptoDir
    API -->|"uses"| ExtractFlash

    ConnDir --> ConnSetup
    ConnDir --> J2534Drv1
    ConnDir --> J2534Drv2
    ConnDir --> USBISO
    ConnDir --> FakeDrv

    CryptoDir --> AES
    CryptoDir --> CryptoIfc
    CryptoDir --> DSG
    CryptoDir --> XOR

    ExtractFlash --> BoxCodes
    ExtractFlash --> DTCs
    ExtractFlash --> FRFKeys1
    ExtractFlash --> FRFKeys2

    API -->|"calls"| FlashUDS
    API -->|"calls"| Checksum1
    API -->|"calls"| Checksum2
    API -->|"calls"| FlashUtils

    API -->|"loads modules"| ModulesDir
    ModulesDir --> DQ250
    ModulesDir --> DQ381
    ModulesDir --> Haldex
    ModulesDir --> Simos

    API -->|"writes logs to"| Config1
    API -->|"reads settings from"| Config2

    API -->|"publishes docs"| Docs

    API -->|"run by"| Tests
    CI --> Tests
    CI -->|"lints & builds"| Spec

    ConnDir -->|"connects to"| FlashHW
    FlashHW -->|"UDS"| ECUHW

    FRFExtractor --> FRFKeys1
    FRFExtractor --> FRFKeys2

    %% Click Events
    click CLI "https://github.com/bri3d/vw_flash/blob/master/VW_Flash.py"
    click GUI "https://github.com/bri3d/vw_flash/blob/master/VW_Flash_GUI.py"
    click Spec "https://github.com/bri3d/vw_flash/blob/master/VW_Flash_GUI.spec"
    click API "https://github.com/bri3d/vw_flash/blob/master/lib/__init.py__"
    click ConnDir "https://github.com/bri3d/vw_flash/tree/master/lib/connections/"
    click ConnSetup "https://github.com/bri3d/vw_flash/blob/master/lib/connections/connection_setup.py"
    click J2534Drv1 "https://github.com/bri3d/vw_flash/blob/master/lib/connections/j2534.py"
    click J2534Drv2 "https://github.com/bri3d/vw_flash/blob/master/lib/connections/j2534_connection.py"
    click USBISO "https://github.com/bri3d/vw_flash/blob/master/lib/connections/usb_isotp_connection.py"
    click FakeDrv "https://github.com/bri3d/vw_flash/blob/master/lib/connections/fake_connection.py"
    click CryptoDir "https://github.com/bri3d/vw_flash/tree/master/lib/crypto/"
    click AES "https://github.com/bri3d/vw_flash/blob/master/lib/crypto/aes.py"
    click CryptoIfc "https://github.com/bri3d/vw_flash/blob/master/lib/crypto/crypto_interface.py"
    click DSG "https://github.com/bri3d/vw_flash/blob/master/lib/crypto/dsg.py"
    click XOR "https://github.com/bri3d/vw_flash/blob/master/lib/crypto/simos_xor.py"
    click ExtractFlash "https://github.com/bri3d/vw_flash/blob/master/lib/extract_flash.py"
    click FlashUDS "https://github.com/bri3d/vw_flash/blob/master/lib/flash_uds.py"
    click Checksum1 "https://github.com/bri3d/vw_flash/blob/master/lib/checksum.py"
    click Checksum2 "https://github.com/bri3d/vw_flash/blob/master/lib/fastcrc.py"
    click ModulesDir "https://github.com/bri3d/vw_flash/tree/master/lib/modules/"
    click DQ250 "https://github.com/bri3d/vw_flash/blob/master/lib/modules/dq250mqb.py"
    click DQ381 "https://github.com/bri3d/vw_flash/blob/master/lib/modules/dq381.py"
    click Haldex "https://github.com/bri3d/vw_flash/blob/master/lib/modules/haldex4motion.py"
    click FRFExtractor "https://github.com/bri3d/vw_flash/blob/master/frf/decryptfrf.py"
    click DataDir "https://github.com/bri3d/vw_flash/tree/master/data/"
    click BoxCodes "https://github.com/bri3d/vw_flash/blob/master/data/box_codes.csv"
    click DTCs "https://github.com/bri3d/vw_flash/blob/master/data/dtcs.csv"
    click FRFKeys1 "https://github.com/bri3d/vw_flash/blob/master/data/frf.key"
    click FRFKeys2 "https://github.com/bri3d/vw_flash/blob/master/data/mqb_dsg_key.bin"
    click Docs "https://github.com/bri3d/vw_flash/tree/master/docs/"
    click Tests "https://github.com/bri3d/vw_flash/blob/master/tests/test_prepare.py"
    click CI "https://github.com/bri3d/vw_flash/blob/master/.github/workflows/python-app.yml"
    click Config1 "https://github.com/bri3d/vw_flash/blob/master/logging.conf"
    click Config2 "https://github.com/bri3d/vw_flash/blob/master/logs/log_config.yaml"
    click Packaging "https://github.com/bri3d/vw_flash/blob/master/setup.py"
    
    %% Styles
    classDef ui fill:#a2d5a2,stroke:#2f5d62,color:#000
    classDef core fill:#8ecae6,stroke:#05668d,color:#000
    classDef drivers fill:#ffb703,stroke:#d95d39,color:#000
    classDef data fill:#adb5bd,stroke:#495057,color:#000
    classDef test fill:#d291bc,stroke:#531d76,color:#000
    classDef external fill:#dff9fb,stroke:#1282a2,color:#000
```
