can-dbc-matrix

name	can-dbc-matrix
description	Converts CAN .dbc files to canmatrix JSON using canconvert --jsonExportAll, then performs all listing, lookup, and decode analysis on that JSON only (never treat raw .dbc as the analysis source). Use when the user attaches or mentions .dbc files, DBC/CANdb/CAN matrix, canconvert, canmatrix, candump or frame decoding, signal names, arbitration IDs, or vehicle bus databases (e.g. Model3CAN).

CAN DBC Matrix

Mandatory workflow (do not skip)

1. Convert the .dbc file to JSON with canconvert and --jsonExportAll (full export: ECUs, attributes, value tables, defines). Before conversion, verify canmatrix is installed; install only if the check fails (see below).
2. Analyze only the resulting JSON (json.load, iterate messages / signals, decode frames). Do not use raw .dbc text as the primary source for structure, scaling, or bit layout.

If the user only has a .dbc path, run conversion first (see below), then open the generated JSON for all subsequent steps.

Install check, then convert

Run checks in order; skip pip install when the package is already present.

python -m pip show canmatrix

• If this prints Name: canmatrix and a version, the package is installed → go straight to canconvert.
• If it errors or shows nothing, install then convert:

python -m pip install canmatrix
canconvert input.dbc output.json --jsonExportAll

Use python -m pip so the same interpreter is used on Windows and Unix.

If canconvert is not on PATH (common after pip install --user or certain Windows setups), call the same CLI via the module that backs the canconvert entry point:

python -m canmatrix.cli.convert input.dbc output.json --jsonExportAll

Do not use python -m canmatrix.cli — that package has no __main__ and will fail.

Other supported inputs (same pipeline: convert to JSON, then analyze JSON): .arxml, .kcd, .dbf, .xls(x), .sym, .ldf.

Quick Reference: JSON Top-Level Keys

Key	Type	Content
messages	array	CAN frames with nested signals
ecus	object	ECU name → comment mapping
attributes	object	Global DB attributes
value_tables	object	Named value enumerations
signal_defines	array	Signal attribute definitions
frame_defines	array	Frame attribute definitions
global_defines	array	Global attribute definitions
baudrate	number	CAN bus baudrate
fd_baudrate	number	CAN FD baudrate

Core workflow (after JSON exists)

1. Load the JSON with json.load()
2. Navigate using json-schema.md
3. Process messages and signals as needed

Common Tasks

List All Messages

import json

with open("can_db.json", encoding="utf-8") as f:
    db = json.load(f)

for msg in db["messages"]:
    print(f"0x{msg['id']:03X} {msg['name']}  DLC={msg['length']}  "
          f"cycle={msg.get('cycle_time', 'N/A')}ms  TX={msg.get('transmitters', [])}")

Find a Signal by Name

def find_signal(db, signal_name):
    for msg in db["messages"]:
        for sig in msg["signals"]:
            if sig["name"] == signal_name:
                return msg, sig
    return None, None

msg, sig = find_signal(db, "VehicleSpeed")

Decode a Raw CAN Frame

def decode_frame(db, arb_id, data_bytes):
    """Decode raw CAN data bytes into physical signal values."""
    msg = next((m for m in db["messages"] if m["id"] == arb_id), None)
    if not msg:
        return None

    results = {}
    for sig in msg["signals"]:
        raw = extract_raw_value(data_bytes, sig)
        physical = raw * float(sig["factor"]) + float(sig["offset"])

        # Value table lookup
        val_str = sig.get("values", {}).get(str(int(raw)))
        results[sig["name"]] = {
            "raw": raw,
            "physical": physical,
            "unit": sig.get("unit", ""),
            "enum": val_str,
        }
    return results


def extract_raw_value(data_bytes, sig):
    """Extract raw integer from CAN data bytes for one signal."""
    start_bit = sig["start_bit"]
    bit_length = sig["bit_length"]
    is_big_endian = sig.get("is_big_endian", False)
    is_signed = sig.get("is_signed", False)

    bits = ''.join(f'{b:08b}' for b in data_bytes)

    if is_big_endian:
        byte_pos = start_bit // 8
        bit_in_byte = start_bit % 8
        collected = []
        pos = byte_pos * 8 + (7 - bit_in_byte)
        for _ in range(bit_length):
            if 0 <= pos < len(bits):
                collected.append(bits[pos])
            curr_byte = pos // 8
            curr_bit = pos % 8
            if curr_bit == 0:
                pos = (curr_byte + 1) * 8 + 7
            else:
                pos -= 1
        raw = int(''.join(collected), 2)
    else:
        raw = 0
        for i in range(bit_length):
            byte_num = (start_bit + i) // 8
            bit_num = (start_bit + i) % 8
            if byte_num < len(data_bytes):
                if data_bytes[byte_num] & (1 << bit_num):
                    raw |= (1 << i)

    if is_signed and raw >= (1 << (bit_length - 1)):
        raw -= (1 << bit_length)
    return raw

Physical Value Formula

physical = raw_value * factor + offset
raw_value = (physical - offset) / factor

Signal range: [min, max] in physical units.

Generate Message/Signal Summary Table

def summarize(db):
    rows = []
    for msg in db["messages"]:
        for sig in msg["signals"]:
            rows.append({
                "Message": f"0x{msg['id']:03X} {msg['name']}",
                "Signal": sig["name"],
                "Start": sig["start_bit"],
                "Len": sig["bit_length"],
                "Factor": sig["factor"],
                "Offset": sig["offset"],
                "Unit": sig.get("unit", ""),
                "Min": sig.get("min", ""),
                "Max": sig.get("max", ""),
                "Endian": "BE" if sig.get("is_big_endian") else "LE",
            })
    return rows

Filter by ECU (Transmitter/Receiver)

def messages_by_tx(db, ecu_name):
    return [m for m in db["messages"] if ecu_name in m.get("transmitters", [])]

def signals_received_by(db, ecu_name):
    results = []
    for msg in db["messages"]:
        for sig in msg["signals"]:
            if ecu_name in sig.get("receivers", []):
                results.append((msg, sig))
    return results

Important Notes

• Message id is a decimal integer. Convert with hex(id) for display.
• is_extended_frame: True = 29-bit CAN ID, False = 11-bit standard ID.
• is_fd: True = CAN FD frame (up to 64 bytes), False = Classic CAN (up to 8 bytes).
• factor/offset may be strings or floats depending on export settings. Always cast to float().
• values dict maps raw integer (as string key) → enum label string.
• Motorola (big-endian) bit numbering: canmatrix exports in "lsb" format by default.
• cycle_time is in milliseconds. 0 or absent means event-triggered.

Additional reference

See json-schema.md for the complete JSON structure (default vs --jsonExportAll).