移动核心
canshift-core ——CANShift生态系统纯TypeScript合同层.
📖 文档 - 配置合同和电线 协议版本规则.
目的
canshift-core 为:
- 配置类型 —— 说
DashboardConfig, (中文(简体) ),Widget歧视工会,PageConfig, (中文(简体) ),TopBarConfig, (中文(简体) ),ButtonAction, (中文(简体) ),DeviceConfig, (中文(简体) ),SignalConfig, (中文(简体) ),InputBindingsConfig - 验证 对仪表板、信号和设备配置进行运行时间检查
- Schema 迁移 ——将更老的配置带往前的版本链
CURRENT_SCHEMA_VERSION - 设计符号和部件测量标准( W) —— 说
DARK_TOKENS调色板+tokensToCssVars由Tuner公司消费canshift-tuner/生成src/styles/tokens.generated.css),加 (中文(简体) )widget-metrics.ts(由固件渲染器镜像的共用测量表/标签/相向光几何)和theme-presets.ts(8个内置短线主题) - 线格式计划 —— 说
DeviceConfigWireSchema, (中文(简体) ),InputBindingsConfigWireSchema, (中文(简体) ),TrackTelemetrySchema, (中文(简体) ),ScreenSettingsSchema, ECU 配置文件, 硬件配置文件
它纯为TypeScript,有Node.js,浏览器,或React Introduct API. 现在
它被消耗 canshift-tuner 财务报告和审定财务报表 canshift-mobile. 运输形态
居住类型 canshift-tuner/src/transport/ 所以核心可以留下来
浏览器/节点中和 .
没错 没有 包含:
- 固件 C++ 代码( 运行于
canshift-firmware/(中文(简体) ) - UI 组件( 运行于
canshift-tuner/src/(中文(简体) ) - 节点或反应原生特定 API
文件夹结构
canshift-core/
└── src/
├── index.ts # Package root — re-exports every entry plus the config contract
├── entries/ # One file per subpath export, re-exports only
├── schemas/ # Zod schemas — dashboard, widgets, signals, device, wire payloads
├── migrations/ # Shape-change steps from MIGRATION_FLOOR_VERSION to CURRENT_SCHEMA_VERSION
├── validation/ # validateDashboard
├── wire/ # TELE, ALERT and CAN monitor binary frames, device commands, JSON envelope parsing
├── track/ # Lap crossing detection, start/finish line
├── widget-metrics/ # Dash geometry and colours the firmware renderer mirrors
├── design-tokens/ # Tuner CSS tokens
├── controls/ # Button control vocabulary
├── ecu-profiles/ # Built-in ECU signal catalogues, OBD-II PIDs and DTCs
├── can-xml/ # CAN XML import
├── board-profile/ # Board profile blob format
├── constants/ # FIRMWARE_CAPS, STRING_CAPS, dash signals
├── display-tiers.ts # Read by the firmware parity script — do not move
├── layout-grid.ts # Read by the firmware parity script — do not move
├── schema-version.ts # Read by the firmware build — do not move
└── __tests__/
constants/firmware-caps.ts, (中文(简体) ), display-tiers.ts, (中文(简体) ), layout-grid.ts 财务报告和审定财务报表
schema-version.ts 是用一个兄弟的软件来解析的
退出,所以这些路径及其文字布局是合同的一部分.
公共 API
根出出口携带着所有消费进口品. 子路径带一片 一个没有树震的捆绑者只负载模块 切片后面:
| 导入 | 它所持有的 |
|---|---|
@canshift/core | 下方的一切,加上仪表板配置合同,验证,迁移 |
@canshift/core/wire | TELE, ALERT 和 CAN 监视帧, 设备命令, 状态 / USB / 计时器有效载荷解析器 |
@canshift/core/track | 拉普过道探测器、起跑/终点线、轨迹遥测计划 |
@canshift/core/widget-metrics | Dash 几何、重度、传感器范围和危险波段、转向灯段 |
@canshift/core/tokens | Tener 设计符及其 CSS 变量 |
@canshift/core/ecu-profiles | ECU目录, MaxxECU 单元, OBD- II 模式 01 PID 和 DTC 解码 |
@canshift/core/schema-version | CURRENT_SCHEMA_VERSION |
出口没有取消消费进口,以后没有保留. Widget 是一个
工会歧视 type: 缩小 widget.type 缩进 widget.config, (中文(简体) ),
财务报告和审定财务报表 WidgetOfType<'gauge'> 一个成员的名字.
Schema 版本和迁移
每个配置文件都包含 "version" 字段的根 :
{ "version": "1.41.0", ... }
CURRENT_SCHEMA_VERSION (单位:千美元)src/schema-version.ts)是这个代码读取和写入的版本. 其分解如下:
- 大师 ——突破计划变化,需要迁移
- 毛里塔尼亚 ——添加剂变化,后相兼容
- 帕齐 - 只修改文件或评论
在装入配置时,消费者必须:
- 读取
version - 若为
version === CURRENT_SCHEMA_VERSION* 正常装载 - 若为
version < CURRENT_SCHEMA_VERSION运行migrateConfig(config, CURRENT_SCHEMA_VERSION); 比MIGRATION_FLOOR_VERSION(1.24.0) 丢出一个below_floorMigrationError - 若为
version > CURRENT_SCHEMA_VERSION请用户更新应用程序
登记处持有 只更改形状。只添加可选字段凸起的发布 CURRENT_SCHEMA_VERSION 且不需要输入 : migrateConfig 运行文件版本与目标之间的每一步顺序,然后设定目标版本. 超过1.24.0的配置不再装入(#151).
形状变化(从1.24.0层)
| 步骤 | 变动 |
|---|---|
| 1.2.4.0 − 1.2.5.0 | 转换为12列网格跨度的像素布局,取自目标屏幕配置 |
| 1.2.6.0 — 1.27.0 (中文(简体) ) | 顶级部件 type 已调整为 config.type |
| 1.2.8. − 1.29.0 (中文(简体) ) | 遗留旗上方栏移入音轨栏 |
| 1.29.0 − 1.30.0 (中文(简体) ) | 高盖 arcFillStyle 空出- 光谱限制填充 |
| 1.30.0 — 1.31.0 (中文(简体) ) | 扣子图标字段被剥除——破折号上没有图标 |
| 1.36.0 − 1.37.0 (简体中文) | 主题相配 theme.day 编号 : theme.night |
| 1.39.0 — 1.40.0 (中文(简体) ) | 高盖 alertThreshold 扔了,它没有武器 |
| 1.42.0 — 1.43.0 (中文(简体) ) | criticalAlert 成为单条目列表 criticalAlerts |
| 1.43.0 — 1.44.0 (中文(简体) ) | 字符串切入固件缓冲器(上条文本/格式 15, ids 31), zOrder 夹住 |
migrateConfig 在任何迁移运行前(# 282) 深切入输入, 所以单个迁移可以自由突变, 而不用化名调用对象 .
验证
验证是 佐德后卫 (Zod为: canshift-core唯一的运行时间
(b) 依赖性。 每个验证符返回 :
{ valid: boolean; errors: string[]; warnings: string[]; config?: T }
config 只在成功分支上出现,并且经过验证
DashboardConfig (或等值)随时可以消费.
validateDashboard 涵盖:
- 布局界限对齐
CANVAS财务报告和审定财务报表TOPBAR_HEIGHT - 十六进制颜色
HexColorSchema - 信号目录引用( 每个绑定的信号都存在)
- 复制部件标识
- 固件盖从
FIRMWARE_CAPS(每页最大部件,最大页等) - 歧视
WidgetConfig.type详尽无遗
维特套接字套接字行为与捆绑 dashboard.json fixture (# 287) 所以当形状变化在没有对齐迁移的情况下被引入时立即回归表面.
固件同步要求
config_types.h 内 canshift-firmware/src/config/ 在 C++ 中镜像这些 TypeScript 类型. 更改时 DashboardConfig, (中文(简体) ), PageConfig, (中文(简体) ), WidgetConfig,或 SignalDef数字 :
- 在此更新类型脚本类型
- 弹出
CURRENT_SCHEMA_VERSION如果改变并非纯粹是添加剂 - 在
migrations/migration-runner.ts和相应的测试 - 更新
config_types.h在坚固的软件中匹配 - 更新
config_loader.cpp在读取新字段的固件中
在运行时检测到固件和核心之间的 Schema 错配 stale 固件与更新的配置对齐, 记录一个明显的错误而不是 默读字节(# 259) 。 坚固的器皿 不运行迁移 链式 ——只有图纳人向前迁移配置. 问题1019(A-COMPAT-1) 跟踪将拒绝不匹配的推进的固件侧前飞行 而不是无声地侮辱.
正在安装的项目
从 npm 安装 :
npm install @canshift/core
地方发展与未公布的变化: npm link 或暂时的 file: 取消——从未承诺.
构建测试( T)
npm run build # tsc → dist/
npm run lint # eslint src
npm run format:check # prettier --check src/**/*.ts
npm test # Vitest
下方的维特套房 src/__tests__/ 涵盖迁移,仪表板验证(完整和端到端),信号验证,设备验证,并捆绑固定.
公约和规则
- 纯类型脚本 ——无节点,浏览器,或反应原生API
- 严格打字 没有
any缩; 窄unknown使用前带有类型守护符 - 仅公布条目 - 消费者从
@canshift/core或其子路径出口;dist/未导出路径 - 弹出
CURRENT_SCHEMA_VERSION任何时候DashboardConfig形状变化,并在同一 PR 中进行对齐迁移 - 歧视工会 —— 说
WidgetConfig用途type作为歧视者; 新的部件类型扩展联盟和验证者的详尽切换 - 镜像 C++ - 这里的每一个变化都必须在固件中反映出来
config_types.h
连接到其他项目
- 移动调试器 配置符; 导入类型、 验证符、 迁移、 部件度量器、 主题预设、 设计符
- 移动软件 —— 说
config_types.h在 C++ 中镜像这些类型; 加载器读取相同的 JSON 形状,而渲染器镜像widget-metrics.ts编号 :theme-presets.ts常数 - 移动式 ——当需要配置或遥测类型(BLE status schema,屏幕设置边框,设计符号)时,直接消耗同一包