# muki01/vag_kw1281 architecture

> Architecture diagram of the GitHub repository muki01/vag_kw1281, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muki01/vag_kw1281
- Repository: https://github.com/muki01/vag_kw1281
- Video tour (about a minute): https://gitdiagram.com/muki01/vag_kw1281/video

## Overview

VAG KW1281 is Arduino/ESP32 firmware for communicating with Volkswagen Group ECUs over a K-Line interface. The principal workflow is to connect to a control unit, read identification and diagnostic data, decode measuring groups, and display results over serial; the firmware also supports scanning, fault clearing, sniffing, and ECU simulation. The README documents the product modes and protocol behavior; sampled source excerpts are data and command definitions, not the main runtime flow, so implementation-level links are limited.

Main entry points: [`VAG_KW1281`](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281) (Main firmware), [`Basic_Communication_Test/Basic_Communication_Test.ino`](https://github.com/muki01/vag_kw1281/blob/main/Basic_Communication_Test/Basic_Communication_Test.ino) (Communication example), [`Basic_KW1281_Simulator/Basic_KW1281_Simulator.ino`](https://github.com/muki01/vag_kw1281/blob/main/Basic_KW1281_Simulator/Basic_KW1281_Simulator.ino) (Standalone simulator), [`VAG_KW1281/Codes.h`](https://github.com/muki01/vag_kw1281/blob/main/VAG_KW1281/Codes.h) (Command and response codes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operation["Diagnostic operation"]
  node_main["Main firmware"]
  node_tester["Tester mode"]
  node_measure["Group decoding"]
  node_faults["Fault handling"]
  node_scan["Group scan"]
  node_sniffer["Sniffer mode"]
  node_simulator["ECU simulator"]
end

subgraph group_protocol["KW1281 protocol"]
  node_commands["Command and response codes<br/>[Codes.h]"]
end

subgraph group_examples["Example firmware"]
  node_basic["Communication example"]
  node_standalone["Standalone simulator"]
  node_simdata["Recorded ECU responses<br/>[Codes.h]"]
end

subgraph group_hardware["Vehicle interface"]
  node_ecu["VAG control unit"]
  node_kline["K-Line interface"]
  node_board["Arduino or ESP32"]
end

node_operator(("Operator"))
node_monitor(("Serial monitor"))

node_operator -->|"selects mode"| node_main
node_main -->|"runs mode"| node_tester
node_main -->|"runs mode"| node_sniffer
node_main -->|"runs mode"| node_simulator
node_tester -->|"exchanges K-Line data"| node_ecu
node_tester -->|"decodes groups"| node_measure
node_tester -->|"reads or clears"| node_faults
node_tester -->|"scans groups"| node_scan
node_main -.->|"uses protocol codes"| node_commands
node_simulator -->|"emulates ECU"| node_ecu
node_standalone -.->|"uses response data"| node_simdata
node_basic -->|"connects to"| node_ecu
node_board -->|"UART connection"| node_kline
node_kline -->|"level shifts"| node_ecu
node_board -->|"prints diagnostic output"| node_monitor
node_sniffer -->|"prints raw traffic"| node_monitor
node_measure -->|"prints decoded values"| node_monitor

click node_main "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_tester "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_measure "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_faults "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_scan "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_sniffer "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_simulator "https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281"
click node_commands "https://github.com/muki01/vag_kw1281/blob/main/VAG_KW1281/Codes.h"
click node_basic "https://github.com/muki01/vag_kw1281/blob/main/Basic_Communication_Test/Basic_Communication_Test.ino"
click node_standalone "https://github.com/muki01/vag_kw1281/blob/main/Basic_KW1281_Simulator/Basic_KW1281_Simulator.ino"
click node_simdata "https://github.com/muki01/vag_kw1281/blob/main/Basic_KW1281_Simulator/Codes.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_tester,node_measure,node_faults,node_scan,node_sniffer,node_simulator toneBlue
class node_commands toneAmber
class node_basic,node_standalone,node_simdata toneMint
class node_ecu,node_kline,node_board toneRose
class node_operator,node_monitor toneIndigo
```

## Components

### Diagnostic operation

- [Main firmware](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`
- [Tester mode](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`
- [Group decoding](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`
- [Fault handling](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`
- [Group scan](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`
- [Sniffer mode](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`
- [ECU simulator](https://github.com/muki01/vag_kw1281/tree/main/VAG_KW1281): `VAG_KW1281`

### KW1281 protocol

- [Command and response codes](https://github.com/muki01/vag_kw1281/blob/main/VAG_KW1281/Codes.h): `VAG_KW1281/Codes.h`

### Example firmware

- [Communication example](https://github.com/muki01/vag_kw1281/blob/main/Basic_Communication_Test/Basic_Communication_Test.ino): `Basic_Communication_Test/Basic_Communication_Test.ino`
- [Standalone simulator](https://github.com/muki01/vag_kw1281/blob/main/Basic_KW1281_Simulator/Basic_KW1281_Simulator.ino): `Basic_KW1281_Simulator/Basic_KW1281_Simulator.ino`
- [Recorded ECU responses](https://github.com/muki01/vag_kw1281/blob/main/Basic_KW1281_Simulator/Codes.h): `Basic_KW1281_Simulator/Codes.h`

### Vehicle interface

- **VAG control unit**
- **K-Line interface**
- **Arduino or ESP32**

### Other components

- **Operator**
- **Serial monitor**

## Connections

- Operator → Main firmware: selects mode (evidence: `README.md`)
- Main firmware → Tester mode: runs mode (evidence: `README.md`)
- Main firmware → Sniffer mode: runs mode (evidence: `README.md`)
- Main firmware → ECU simulator: runs mode (evidence: `README.md`)
- Tester mode → VAG control unit: exchanges K-Line data (evidence: `README.md`)
- Tester mode → Group decoding: decodes groups (evidence: `README.md`)
- Tester mode → Fault handling: reads or clears (evidence: `README.md`)
- Tester mode → Group scan: scans groups (evidence: `README.md`)
- Main firmware → Command and response codes: uses protocol codes
- ECU simulator → VAG control unit: emulates ECU (evidence: `README.md`)
- Standalone simulator → Recorded ECU responses: uses response data
- Communication example → VAG control unit: connects to (evidence: `README.md`)
- Arduino or ESP32 → K-Line interface: UART connection (evidence: `README.md`)
- K-Line interface → VAG control unit: level shifts (evidence: `README.md`)
- Arduino or ESP32 → Serial monitor: prints diagnostic output (evidence: `README.md`)
- Sniffer mode → Serial monitor: prints raw traffic (evidence: `README.md`)
- Group decoding → Serial monitor: prints decoded values (evidence: `README.md`)