MatthewRyanWeber/CrestronConvert

# CrestronConvert 将 Crestron 控制系统项目文件转换为可浏览的 HTML，直接基于处理器和触摸面板实际出厂时携带的编译文件运行。无需安装 SIMPL Windows 或 VTPro-e。 当前状态：**可用的转换器和 HTML5 接口生成器**，已通过 10 个真实项目集验证。剩余路线图见 [NEXT.md](NEXT.md)。 ## 截图 生成的 HTML5 接口，包含从面板文件中恢复的每个页面：  点击控件会发出它将通过 CH5 发送的真实 join。这里 `Vol+` 发送数字 join 1，而 `Mute` 发送 join 3，与它们在原始面板中的连线完全一致，并且模拟总线会回显反馈：  由相同源文件生成的分析报告：  ## 一键转换 ``` py -3.12 run.py --session "Hamilton 406" --only "Hamilton" ``` 该单一命令会在桌面上创建一个会话文件夹，并执行以下所有操作： ``` Hamilton 406/ original crestron files/ verbatim copies, sha256-verified, read-only html5// preview.html offline preview with a mock join bus ch5/index.html deployable CH5 project ch5/project.json the join contract, for diffing CHECKLIST.md what needs a human before deployment reports/ full analysis report session.json provenance chain: source path, sha256, timestamps ``` 在转换开始前，备份会被写入**并进行校验**。如果 HTML5 接口在硬件上表现异常，`original crestron files` 中的原始文件将作为重新加载到处理器和面板上的内容。 ## 目前支持的功能 读取编译产物，对它们进行交叉引用，并为每个项目集生成一份独立的 HTML 报告： | 输入 | 格式（通过 magic bytes 校验） | 提取内容 | |---|---|---| | `.sig` | `[RLSIG0001]` 或 `[LOGOSSIG001.000]` | 完整的 signal 表，包含命名和 symbol 作用域 | | `.spz` | ZIP | 从内嵌的 `.rvi` 中提取 Fusion/RoomView join 映射 | | `.vtz` | ZIP | 从 `Environment.xml` 中提取面板页面、控件和所有 join | | `.vtp` | OLE2 复合文件 | Stream 清单（在没有 `.vtz` 时作为备选方案） | 该报告包含六个标签页：Overview、Join 交叉对照、Panel 对象、Program signal、Fusion 映射和 Orphans。所有内容均为内联，因此该报告是一个单一份文件，您可以通过电子邮件发送或作为附件添加到工单中。 ### Join 交叉对照 这是该工具的核心所在。面板端和程序端都各自知道 join 编号，但没有任何 Crestron 工具能将它们并排显示。将它们关联起来可以揭示： - **面板独有**的 join：一个控件驱动了一个程序中从未声明过的 join - **程序独有**的 join：没有用户界面的逻辑 - **共享**的 join：一个 join 被多个对象驱动，有时是故意的，有时则是 bug ## 用法 ``` py -3.12 run.py --list # show discovered project sets py -3.12 run.py # convert everything under source_root py -3.12 run.py --only "Hamilton" # convert one project set py -3.12 run.py --session "Room 406" # session folder with verified backups py -3.12 run.py --profile epson # manufacturer string variant py -3.12 run.py --no-html5 # analysis report only py -3.12 run.py --list-profiles # available string profiles py -3.12 run.py --list-sessions # existing sessions py -3.12 run.py --verify-session # re-check a session's backups py -3.12 run.py --source "D:\Some\Other\Folder" ``` 路径存在于 `config.json` 中，而不是代码中。 ### 为什么 HTML5 接口能够起作用 Crestron 触摸面板不运行任何逻辑。它与处理器交换 **join**：digital 用于按钮和反馈，analog 用于级别，serial 用于文本。每个投影仪命令、serial 字符串和 IR 突发都存在于处理器程序中，并保持原样运行。 因此，将面板转换为 HTML5 绝不是重新实现设备控制。它重现了 join 契约，而处理器继续像以前一样驱动显示。这就是为什么上面截图中的 `Vol+` 只需要发送 digital join 1：程序已经知道该如何处理它。 可部署的输出目标是 **CH5**，即 Crestron 受支持的 HTML5 机制，并且需要 CH5 工具链中的 `cr-com-lib.js` 配合使用。`preview.html` 是独立的，什么都不需要，这使得转换能够在不涉及任何硬件的情况下进行测试。 ### 制造商字符串变体 相同的 UI 会发布到具有不同显示品牌的房间中。配置信息以数据形式存在于 `strings.json` 中，而不是代码中： ``` py -3.12 run.py --session "Lab" --profile epson # "Display" becomes "Projector" ``` ## 本项目遵循的设计规则 - **依赖检查优先。** `deps.py` 会校验 Python 3.12+，安装缺失的包，并在可用磁盘空间低于 50 GB 时中止。它从不静默跳过。 - **带检查点的流式传输。** 记录一条一条地通过 pipeline 进入 SQLite，并按间隔进行检查点保存。如果在第 10,000 条记录（共 18,565 条）时发生崩溃，将从第 10,001 条恢复。内存占用保持平稳。 - **快速失败。** 如果超过 1% 的 signal 记录未通过语法校验，运行将中止，而不是输出一份不完整的报告。这在开发过程中发现了一个真实的 bug：16.41% 的记录被误读，阈值机制强制要求进行正确的修复，而不是悄悄地退回默认处理。 - **格式校验，绝不臆测。** 每个容器都通过 magic bytes 进行识别。当一个文件两次声明同一个值时（signal id 既是尾随的 hex，也是二进制 trailer），解析器会对它们进行交叉检查，如果不一致则中止操作。 ## 格式说明 根据真实文件记录，因为 Crestron 没有发布任何此类信息。 ### `.sig` signal 表 ``` [RLSIG0001] record text is cp1252 [LOGOSSIG001.000] record text is UTF-16LE per record: uint16 LE total_len self-inclusive, counts these 2 bytes payload (total_len - 2) encoded text + 6-byte trailer trailer[0:4] uint32 LE signal id trailer[4] flag_a trailer[5] flag_b ``` 两种记录形式，都是有效的： - **named**：程序员自定义的全局变量，例如 `Display-01_Power_On`、`TP_Room_Name$`。前缀 `//` 表示已声明但从未被驱动。 - **symbol**：作用域限定在一个带有路径和重复 hex id 的 SIMPL symbol 上，例如 `::Trig$:S-1.1:S-3:S-8.10.2.00004FD1` ### `.vtz` 面板存档 ZIP。`swf/Environment.xml` 是一个包含整个项目的 UTF-16LE XML 文件。任何具有 `ControlName` 子元素的元素都是一个对象；join 是任何匹配 `*Join*` 的后代标签，这涵盖了观察到的 31 种不同的 join 标签名称，而无需对控件类型进行硬编码。 ## 验证 十个项目集，连续三次干净运行，退出代码为 0，在 130,000 多条 signal 记录中未识别记录率为 0.00%。

标签：Crestron, HTML5, 文件解析, 格式转换, 物联网, 音视频集成