File formats

Project data is plain JSON and plain text. Nothing is stored in a proprietary database, so a workspace can be inspected, copied and diffed.

General JSON rules

• .bmprj, .bmecu, .bmdump, .bmdid, DTC and action-button files are JSON.
• Use decimal numbers for did, txid, addresses and sizes.
• Unknown fields in project and ECU files are preserved when the file is edited and saved.
• Files are UTF-8; a BOM is allowed in DTC JSON.

Workspace and project files

Path	Contents
project.bmprj	Project document
*.bmecu	One ECU definition per file
*.bmdump	Cached values, saved and loaded from the ECU List
*.bmdid	DID list for the Incubator
*.bmrcp	Firmware recipe next to an image
notes.md	Project notes, UTF-8, up to 64 KiB
chat_history.json	AI chat history of the project
config_global.json	Global settings in %APPDATA%\BlackMagic
config.json	Local workspace settings in <workspace>/data

.bmprj — project

project.bmprj lives in the project folder.

Field	Type	Purpose
title	string	Project name
file_version	string	Format version, currently "4"
dtcinfo	string	Local DTC database
authlib	string	Project auth library
own_ip	string	DoIP IP
own_netmask	string	DoIP netmask
dhcp_enabled	bool	DoIP DHCP
cover_img	string	Cover image
features	array	Project features
mod_params	object	Extension parameters

A dtcinfo without a leading dot is looked up in <workspace>/data/dtc; a path starting with a dot is relative to the project folder.

.bmecu — ECU definition

Top level: unit, caption, subsystem, comment, flags, authlib, transport (can or doip), can, doip, parameters, routines, dtc_snapshot_data, auth.

"can":  { "channel": 1, "txid": 2016, "rxid": 2024, "id29bit": false, "baudrate": 500000 }
"doip": { "ip": "127.0.0.1", "port": 13400, "tls_port": 3496, "ecu_address": 4098, "tst_address": 3712 }

Parameter fields: type (usually ID), did, comment, writeable, auth, write_auth, groups (info, temp, measure, ioctl), views.

View fields: format (uint, int, ascii, hex, enum, combined), name, offset, size, optional bit_offset / bit_size, unit. For uint/int: scale (default 1.0) and value_offset (default 0). enum uses values ({ "val": …, "text": "…" }); combined uses sub_views. For type="ID" the payload starts after the 62 DID_H DID_L header, i.e. data_start=3.

Routine: rid, name, comment, auth, could_start, could_stop, could_request_result, options (a View with data_start=4). Snapshot DTC: did, size, view.

.bmdump — cached values

{
  "prj_title": "MyProject",
  "ecus": {
    "7E0": {
      "DTCi": 1234,
      "DTC": [ 12345678 ],
      "61840": "62F19057424D..."
    }
  }
}

The ECU key is the txid in hex. DTCi is (format id << 8) | supported mask; DTC entries are (dtcid << 8) | status; DID keys are decimal and values are the full hex buffer including the 62 DID_H DID_L header.

.bmdid — DID list

{
  "title": "DID",
  "comment": "Data Identifier list",
  "file_version": 1,
  "idparams": [
    { "name": "VIN", "comment": "Vehicle Identification Number", "type": "ascii", "did": 61840 }
  ]
}

idparams[] uses name, comment, type, did; the Incubator scans this list.

DTC databases

JSON:

{
  "file_version": "1.0",
  "codes": { "P0001": "Fuel Volume Regulator Control Circuit/Open" }
}

TXT uses one CODE description line per code; lines starting with # or ; are ignored. Codes are P, C, B or U followed by 5 or 7 hex characters. The global database is data/dtc/codes.json or .txt; the local one is selected in Project Properties.

CSV

• ECU List: separator ;, header row with column names, and a trailing ; on every row.
• Measurement Values: "Name","DID","Value Unit" per line, no header.

CSV is for exchange, not for restoring project state.

Logs

.log is a text file, one event per line:

[17:24:36.123] UDS: 7A0 >> 22 F1 90
[17:24:36.145] UDS: 7A8 << 62 F1 90 ...

The first line of a saved log is [build] ... with the version, configuration and build date.

Scripts, firmware and service paths

Path	Purpose
<workspace>/scripts/*.lua	Shared Lua scripts
<project>/scripts/*.lua	Project scripts (priority)
<workspace>/firmware, <project>/firmware	Firmware images
.bin	Raw image; a base address is required
.hex, .ihex, .srec	Images with addresses
%APPDATA%\BlackMagic\config_global.json	Global settings
%APPDATA%\BlackMagic\imgui.ini	Window layout
%LOCALAPPDATA%\BlackMagic\chat.json	AI chat settings
%LOCALAPPDATA%\BlackMagic\mcp.json	Local MCP server token
<workspace>/data/config.json	Local workspace settings
<workspace>/logs/*.log	Session logs

Related

• Workspace
• Project setup
• Reports and export