DBC Compare Tool

Compare two Automotive CAN DBC baselines and see what actually changed.

A Windows desktop + CLI tool that compares DBC baseline folders and writes an engineering-grade Excel change report.

---

What it does

A text diff shows you which characters moved. This shows you which messages and signals changed.

flowchart LR
    OLD[Old baseline folder] --> T[DBC Compare Tool]
    NEW[New baseline folder] --> T
    T --> XLSX[("report.xlsx")]

Loading

It discovers every .dbc file recursively, pairs the corresponding databases — even renamed ones — compares messages and signals, detects likely renames, and writes one multi-sheet workbook.

What it detects

	DBC file	Message	Signal
Added / Removed	✅	✅	✅
Modified		✅	✅
Renamed	✅	✅	✅
Value tables (VAL_)			✅
Comments (CM_)		✅	✅
Parse error	✅

---

Features

• Folder-level comparison — recursively discovers all .dbc files in both baselines and reports every message and signal change between them.
• DBC file pairing — matches relative paths first, then chooses a global one-to-one pairing using shared filename/folder keywords and message content. Release/version decorations are ignored; shared keywords can pair DBCs even when their contents differ completely.
• Manual pairing — Manual Pairing… chooses DBC counterparts only. Run Compare exports directly; message and signal matching stays automatic.
• Message rename detection — scored over CAN ID, DLC, transmitter, cycle time, signal count and signal layout, so a message whose CAN ID changed can still be matched.
• Signal rename detection — scored over start bit, length, byte order, signedness, factor/offset, unit and receivers, with name similarity as supporting evidence. Event Matrix-style messages, where those properties repeat across dozens of signals, switch to a name-driven mode that can never report High confidence.
• Value tables and comments — VAL_ value tables are compared for signals, CM_ comments for both messages and signals.
• Change-type filter — include only Added / Removed / Modified / Renamed in the report.
• Include Unchanged — optionally export all messages and signals, including Unchanged, with filterable OLD/NEW ECU Tx/Rx and technical properties.
• Robust parsing — an unparsable DBC is flagged Parse Error and the rest of the comparison continues; UTF-8, UTF-8 with BOM and the CANdb++ default encoding are all handled.
• CLI mode — same comparison engine, scriptable for CI or batch runs.

---

Quick start

Ready-to-run Windows builds are attached to each release — download the one-file .exe and nothing needs to be installed.

Sample baselines for a first run live in examples/old and examples/new:

dbc-compare-tool --old examples\old --new examples\new --out comparison.xlsx

---

The report

One workbook, five sheets:

Sheet	Contents
Summary	Change counts by category, report title, generation time
DBC Overview	One row per file pair: status (Matched / DBC Added / DBC Removed / DBC Renamed / Manually Paired / Parse Error), pairing confidence/reasons, message/signal counts
Message Details	Every added, removed, modified or renamed message
Signal Details	Every added, removed, modified or renamed signal, with rename confidence
Property Diff	One row per changed property, before and after

Rows are colour-coded by change type — 🟩 Added, 🟥 Removed, 🟨 Modified, 🟦 Renamed — and CAN IDs are written in hexadecimal (0x1A3).

Message Details, Signal Details and Property Diff include separate ECU Node Tx (Old/New) and ECU Node Rx (Old/New) columns. Message Rx is the union of its signals' receivers; signal Tx comes from its parent message. Multi-node cells contain comma-separated names (use Excel's Text Filters → Contains for one ECU).

Detail sheets also show OLD/NEW CAN IDs, frame type, DLC, cycle time, signal counts and descriptions. Signal rows include both parent names and full signal properties: layout, scaling, range, unit, value type, multiplexing, value tables and comments.

With Include Unchanged, unchanged entries appear in gray and are counted separately from Total Changes. Unchanged describes the entity's own compared properties: a message can contain modified signals, and a signal can belong to a renamed/modified message. Review both detail sheets and the OLD/NEW context. Property Diff continues to list changed properties only. The Summary records the report mode and skipped parse-error count; check DBC Overview for incomplete coverage.

Summary — the headline numbers:

Signal Details — what changed, and how confident the rename match is:

Property Diff — the old and new value of every property that moved:

---

Rename detection

Rename detection is a heuristic, not a proof. Structural properties carry the score and the name is supporting evidence, so a signal keeps its identity through a pure rename:

Property	Old	New
Name	VehicleSpeed	VehSpeed
Start bit	16	16
Length	16	16
Factor	0.01	0.01
Unit	km/h	km/h

→ reported as Renamed, High confidence.

Two limits are worth knowing before you trust a verdict:

• Event Matrix-style messages have dozens of structurally identical signals, so their matches lean on name similarity and can never reach High.
• Review a detected rename whenever the difference between Renamed and Removed + Added matters to you.

Scoring weights and known edge cases are in docs/architecture.md.

---

Requirements

• Windows (the UI and path handling target Windows; the core engine is platform-agnostic)
• Python 3.9 or newer, to run from source
• Runtime dependencies: cantools, openpyxl, PySide6 — pyinstaller is needed only to build the executable

---

Install from source

git clone https://github.com/longvo92/dbc-compare-tool.git
cd dbc-compare-tool
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .

The -e . step is required: the package lives under src/, so python -m dbc_compare_tool only resolves after an editable install. It also puts two commands on the environment's PATH — dbc-compare-tool (CLI) and dbc-compare-tool-gui (desktop app).

---

Usage

GUI:

The Baselines section holds folder selection and manual pairing; Report holds the output path and export options. Run Compare and Open Report stay visible at the bottom when the setup area scrolls. Inputs are locked during a run, and the footer shows comparison/export status.

.\.venv\Scripts\python.exe -m dbc_compare_tool

CLI:

.\.venv\Scripts\python.exe -m dbc_compare_tool.cli --old "path\to\old baseline" --new "path\to\new baseline"

--old and --new are required. Folder paths may contain spaces. --out is optional; when omitted, the report is written beside the new baseline folder as compared_<new-folder-name>.xlsx. An explicit --out path must end in .xlsx. The GUI applies the same automatic output rule when Report Path is left empty.

For a complete inventory for technical impact review:

dbc-compare-tool --old examples\old --new examples\new --include-unchanged --out impact_review.xlsx

In the GUI, tick Include Unchanged before Run Compare. This disables and bypasses the change-type filters, including for manual DBC pairing. The default remains changes only.

Exit codes: 0 success, 1 parse or write failure, 2 bad arguments or missing folder.

run_gui.bat and run_cli.bat at the repository root do the same, using .venv in the repo.

---

Development

Run the test suite:

.\.venv\Scripts\python.exe -m unittest discover -s tests

CI runs the same suite on Linux and Windows against Python 3.9, 3.10 and 3.12, plus a CLI comparison of the bundled example baselines. The comparison engine and the report writers have no UI dependency, so those runs install cantools and openpyxl only — no test imports Qt.

Build distributables (zipapp and one-file .exe):

.\.venv\Scripts\python.exe scripts\build.py        # both
.\.venv\Scripts\python.exe scripts\build.py exe    # exe only

Structure

flowchart TD
    GUI["ui/ — PySide6 desktop app"] --> ENG
    CLI["cli.py — command line"] --> ENG
    ENG["core/ — discovery, parsing, comparison, rename scoring"] --> REP
    REP["report/ — Excel writer"] --> XLSX[("report.xlsx")]

Loading

The desktop app and the CLI share the same engine, and that engine has no UI dependency. Outside the package: scripts/build.py produces the distributables, scripts/release_check.py gates a release, examples/ holds the sample baselines, and tests/ mirrors the layers above.

Documentation

• User Guide — step-by-step usage, also in the app's Help menu
• Changelog — every released version, also in the app's Help menu
• Architecture — layers, data flow, rename scoring weights, validation status

Contributing

Issues and pull requests are welcome. For changes to comparison or rename-detection logic, add or update tests under tests/, and keep the comparison engine free of UI imports so it stays usable from the CLI and CI.

Author

Long Vo Thien

License

MIT © Long Vo Thien