文件格式

项目数据是纯 JSON 和纯文本。没有内容存储在专有数据库中，因此工作区可以被检查、复制和比较差异。

通用 JSON 规则

• .bmprj、.bmecu、.bmdump、.bmdid、DTC 和操作按钮文件都是 JSON。
• did、txid、地址和大小使用十进制数字。
• 编辑并保存项目和 ECU 文件时，未知字段会保留。
• 文件为 UTF-8；DTC JSON 允许带 BOM。

工作区和项目文件

路径	内容
project.bmprj	项目文档
*.bmecu	每个文件一个 ECU 定义
*.bmdump	缓存值，从 ECU List 保存和加载
*.bmdid	Incubator 的 DID 列表
*.bmrcp	镜像旁边的固件刷写方案
notes.md	项目备注，UTF-8，最大 64 KiB
chat_history.json	项目的 AI 聊天历史
config_global.json	%APPDATA%\BlackMagic 中的全局设置
config.json	<workspace>/data 中的本地工作区设置

.bmprj — 项目

project.bmprj 位于项目文件夹中。

字段	类型	用途
title	string	项目名称
file_version	string	格式版本，当前为 "4"
dtcinfo	string	本地 DTC 数据库
authlib	string	项目认证库
own_ip	string	DoIP IP
own_netmask	string	DoIP 子网掩码
dhcp_enabled	bool	DoIP DHCP
cover_img	string	封面图像
features	array	项目功能
mod_params	object	扩展参数

不以点开头的 dtcinfo 会在 <workspace>/data/dtc 中查找；以点开头的路径相对于项目文件夹。

.bmecu — ECU 定义

顶层：unit、caption、subsystem、comment、flags、authlib、transport（can 或 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 }

参数字段：type（通常为 ID）、did、comment、writeable、auth、write_auth、groups（info、temp、measure、ioctl）、views。

视图字段：format（uint、int、ascii、hex、enum、combined）、name、offset、size、可选的 bit_offset / bit_size、unit。对于 uint/int：scale（默认 1.0）和 value_offset（默认 0）。enum 使用 values（{ "val": …, "text": "…" }）；combined 使用 sub_views。对于 type="ID"，载荷从 62 DID_H DID_L 头之后开始，即 data_start=3。

例程：rid、name、comment、auth、could_start、could_stop、could_request_result、options（一个 data_start=4 的 View）。快照 DTC：did、size、view。

.bmdump — 缓存值

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

ECU 键是十六进制的 txid。DTCi 为 (format id << 8) | supported mask；DTC 条目为 (dtcid << 8) | status；DID 键为十进制，值为包含 62 DID_H DID_L 头的完整十六进制缓冲区。

.bmdid — DID 列表

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

idparams[] 使用 name、comment、type、did；Incubator 会扫描此列表。

DTC 数据库

JSON：

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

TXT 每个故障码使用一行 CODE description；以 # 或 ; 开头的行会被忽略。故障码为 P、C、B 或 U 后跟 5 或 7 个十六进制字符。全局数据库为 data/dtc/codes.json 或 .txt；本地数据库在 Project Properties 中选择。

CSV

• ECU List：分隔符为 ;，带列名的表头行，每行末尾有 ;。
• Measurement Values：每行 "Name","DID","Value Unit"，无表头。

CSV 用于交换，不用于恢复项目状态。

日志

.log 是文本文件，每行一个事件：

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

已保存日志的第一行是 [build] ...，包含版本、配置和构建日期。

脚本、固件和服务路径

路径	用途
<workspace>/scripts/*.lua	共享 Lua 脚本
<project>/scripts/*.lua	项目脚本（优先）
<workspace>/firmware, <project>/firmware	固件镜像
.bin	原始镜像；需要基地址
.hex, .ihex, .srec	带地址的镜像
%APPDATA%\BlackMagic\config_global.json	全局设置
%APPDATA%\BlackMagic\imgui.ini	窗口布局
%LOCALAPPDATA%\BlackMagic\chat.json	AI 聊天设置
%LOCALAPPDATA%\BlackMagic\mcp.json	本地 MCP 服务器令牌
<workspace>/data/config.json	本地工作区设置
<workspace>/logs/*.log	会话日志

相关

• 工作区
• 项目设置
• 报告与导出