建一个项目的"设备指令库"：宏/脚本/跨项目复用

你在第一个展厅项目里查完了投影手册、试通了串口、在中控软件里把开机/关机/切源指令一条条录进去。第二个项目进来，遇到同款投影——"我上次配过"，翻中控文件找了半天，找到了，导出，改参数，重录一遍。第三个项目、第四个项目……

这条路走了三次，你就会想：有没有一个地方把这些东西存起来、下次直接用？

答案是有，但需要你自己建。这就是"设备指令库"——一个独立于任何特定项目的、结构化的指令集合，里面记的不只是指令字节，还有"这条指令来自哪个手册版本、在哪台设备上验证过、怎么参数化适配不同场景"。

这一节把搭这个库的方法讲清楚，给你一个可以直接用的模板。

R2 内容，涉及设备接口参数和指令格式。文中以 Modbus、串口协议为例，具体字节以对应设备官方文档为准，模板为组织结构示意，不是字节模板。

---

为什么指令库要单独存，不能只靠中控项目文件

新手第一直觉是"指令配在中控软件里了，下次导出用就行"。这条路有几个具体问题：

1. 中控软件的格式和版本绑定。导出的是中控软件专有格式，换版本可能导入失败；换了中控平台，根本导不进去。

2. 中控项目文件混进了大量项目相关配置（界面布局、场景编排、IP 地址），把这堆东西整个搬到新项目，改起来还不如重配。

3. 无法管理"哪版手册、哪个固件"。同一台投影不同固件版本，某些指令可能改过。项目文件里录的指令不会注明"来自手册 v2.1、在固件 1.08 上验证过"——过了一年你自己都记不清。

4. 团队协作时互相覆盖。两个工程师同时改同一个中控项目文件，版本就乱了。

指令库不是替代中控软件的项目配置，而是比项目配置更底层的一层：原始指令的单一来源，中控项目配置从这里取用，而不是在项目里现查现录。

---

指令库的组织结构

一个实用的指令库，可以是一个文件夹（Git 仓库最好），里面按品牌/型号组织 JSON 或 YAML 文件。这里给一个 JSON 格式的示例，你可以按团队习惯换成 YAML 或 Excel，结构是一样的。

顶层目录结构

device-cmd-lib/
├── README.md                      # 说明：命名规范、贡献规则、版本策略
├── projectors/
│   ├── epson-eb-l1000u.json       # Epson EB-L1000U 投影
│   ├── nec-px2000ul.json          # NEC PX2000UL 投影
│   └── …
├── displays/
│   ├── samsung-qm65b.json         # 三星 QM65B 商显
│   └── …
├── matrices/
│   ├── extron-dxp-hdmi.json       # Extron DXP HDMI 矩阵
│   └── …
├── relay-io/
│   ├── corxnet-nr4-modbus.json    # 科星 4 路网络继电器
│   └── …
├── serial-servers/
│   ├── usr-tcp232-t2.json         # 有人 USR-TCP232-T2
│   └── …
└── macros/
    ├── projector-power-cycle.json # 跨设备宏：安全重启投影
    └── …

---

单台设备的指令文件模板

这是一个设备指令文件的完整模板，以一台支持 PJLink 的投影为例（字节值为示意，以手册为准）：

{
  "device": {
    "brand": "Epson",
    "model": "EB-L1000U",
    "category": "projector",
    "doc_version": "ESC/VP21 v2.0",
    "firmware_verified": "1.09",
    "verified_by": "张三",
    "verified_date": "2025-11-10",
    "notes": "该型号同时支持 ESC/VP21 和 PJLink；PJLink 走 TCP:4352；ESC/VP21 走 RS232"
  },
  "interfaces": {
    "rs232": {
      "baud_rate": 9600,
      "data_bits": 8,
      "stop_bits": 1,
      "parity": "none",
      "notes": "以手册为准"
    },
    "network_pjlink": {
      "protocol": "TCP",
      "port": 4352,
      "notes": "PJLink Class 1，以手册为准"
    }
  },
  "commands": [
    {
      "id": "power_on",
      "name": "开机",
      "interface": "rs232",
      "format": "ascii",
      "payload": "PWR ON\r",
      "response_pattern": "PWR=ON",
      "timeout_ms": 3000,
      "notes": "发出后投影进入预热，约 30-60s 出画面；以手册为准"
    },
    {
      "id": "power_off",
      "name": "关机",
      "interface": "rs232",
      "format": "ascii",
      "payload": "PWR OFF\r",
      "response_pattern": "PWR=OFF",
      "timeout_ms": 3000,
      "notes": "发出后进入冷却流程，冷却期间勿断电；以手册为准"
    },
    {
      "id": "power_query",
      "name": "查询电源状态",
      "interface": "rs232",
      "format": "ascii",
      "payload": "PWR?\r",
      "response_pattern": "PWR=(ON|OFF|WARM-UP|COOL-DOWN)",
      "timeout_ms": 1000,
      "notes": "可轮询，确认状态"
    },
    {
      "id": "input_hdmi1",
      "name": "切换到 HDMI1",
      "interface": "rs232",
      "format": "ascii",
      "payload": "SOURCE 30\r",
      "response_pattern": "SOURCE=30",
      "timeout_ms": 2000,
      "notes": "输入源编号 30=HDMI1，以该型号手册为准，型号不同编号可能不同"
    }
  ]
}

几个关键字段说明：

• doc_version：这是对哪版手册的录入。手册版本变了要更新。
• firmware_verified：在哪个固件上验证过的，字段标注，避免固件升级后指令失效没有记录。
• verified_by / verified_date：谁在什么时候在真实设备上验证了这条指令有效。
• response_pattern：设备应答的正则匹配，中控软件可以用来判断指令是否成功执行。
• timeout_ms：超时等多少毫秒，投影开机/关机的超时要设长一些（3000ms 甚至更多），查询指令可以短一些。
• notes：每条指令都写 notes，特别是那些"坑"——什么情况下不能发、和其他指令的依赖关系、厂商的已知 bug。

---

参数化：一条模板，多个场景

很多指令只有参数不同，把它们抽象成模板而不是一条条罗列：

{
  "id": "input_switch",
  "name": "切换输入源",
  "interface": "rs232",
  "format": "ascii",
  "payload_template": "SOURCE {input_code}\r",
  "parameters": {
    "input_code": {
      "type": "enum",
      "values": {
        "30": "HDMI1",
        "A0": "HDMI2",
        "14": "VGA",
        "52": "HDBaseT"
      },
      "notes": "以该型号手册输入源列表为准"
    }
  },
  "response_pattern": "SOURCE={input_code}"
}

用参数化模板的好处：在中控软件里配"切换到 HDMI2"这个指令时，只需要选"input_switch"模板、选参数"A0"，不用把每个输入源单独写一条指令。更重要的是，如果厂商改了 HDMI1 的编码，只改模板里的那一个值就好，不用找所有配置过这条指令的地方逐一修改。

---

宏：多条指令打包成原子操作

宏（Macro）：把几条必须按顺序执行的指令打包成一个命名操作，对外只暴露这个操作名，不暴露内部细节。

最典型的例子——安全关投影。投影不能直接断电，流程是：

[宏] 安全关投影 (projector_safe_shutdown)
  1. 发"关机"指令                    → 等应答或超时
  2. 轮询"电源状态查询"              → 等状态变为 COOL-DOWN 或 OFF
  3. 等待 90 秒（冷却缓冲期）        → 确认风扇停转
  4. 发"继电器断电"指令（可选）      → 断开投影强电

如果把这个流程散在中控场景里，不同工程师可能有不同写法，容易漏步骤（比如忘了等冷却直接断电）。把它封装成宏，场景里只调用"安全关投影"这一个操作，内部逻辑统一管理。

宏文件格式示例：

{
  "macro_id": "projector_safe_shutdown",
  "name": "安全关投影",
  "description": "发关机指令后轮询冷却状态，冷却完毕后可选断电",
  "steps": [
    {
      "action": "send_command",
      "command_id": "power_off",
      "wait_response": true,
      "timeout_ms": 3000
    },
    {
      "action": "poll_command",
      "command_id": "power_query",
      "until_response_matches": "PWR=(OFF|COOL-DOWN)",
      "poll_interval_ms": 5000,
      "max_polls": 30,
      "notes": "最多等 150 秒，视投影冷却时间以手册为准"
    },
    {
      "action": "wait",
      "duration_ms": 90000,
      "notes": "冷却缓冲，确认风扇停转"
    },
    {
      "action": "send_command",
      "command_id": "relay_power_off",
      "optional": true,
      "notes": "如接了继电器控制强电，可选断电；不接继电器跳过"
    }
  ]
}

宏的关键设计原则：宏里的步骤应该尽量有应答确认，而不是只靠 sleep 等时间。靠时间等，就是假设设备一定在规定时间内完成，现实里投影冷却时间可能因温度/工作时长而变化。

---

版本管理：指令库要上 Git

指令库应该用 Git 管理，理由很具体：

• 手册版本迭代，指令改了有历史可查（git blame 可以看是谁在什么时候改的那一行）
• 多人协作时不会互相覆盖，用分支隔离各自修改
• 出了问题可以回滚到上一个验证通过的版本
• 配合 code review，新指令或修改要经过另一个人确认再合并

实际操作上，一个 GitHub 私有仓库或公司内网 GitLab 就够用。分支策略不需要复杂，main 只收验证过的内容，新设备新指令开个 feature 分支，验证通了再合主干。

---

跨项目复用时的陷阱

有了指令库，下次新项目就能"直接用"——但有几个具体的坑提前知道：

陷阱一：同型号不同批次固件差异。你库里那条"Epson EB-L1000U 开机"指令在 1.08 固件验证过，甲方采购的是新批次机器、固件 1.12，某个命令格式改了。新机器上线前，必须重新跑一遍验证流程，不能直接上。

陷阱二：IP 和串口号是项目相关的，不能进指令库。指令库存的是设备类型和控制逻辑，IP 地址、串口服务器端口这些是每个项目现场的参数，单独在项目配置里管，不要混进指令库。

陷阱三：厂商换型号、老型号停产。"这台矩阵我们用了 5 年，指令库里有"——但厂商已经出了换代型号，指令改了 30%。复用前先确认型号一致，同一品牌同一系列的新旧型号指令可能不通用。

陷阱四：宏里的时序依赖现场条件。投影冷却 90 秒在气温 25°C 的空调环境里够用，在夏天 37°C 的室外展棚里可能不够。宏里的等待时间是工程经验值，不是硬件保证，新环境里要实测。

---

与中控软件的关系

指令库是"原材料仓库"，中控软件的项目文件是"按项目加工好的成品"。两者的分工：

设备指令库（Git 仓库）
    │
    │  工程师查库取指令
    ▼
中控软件项目文件
    │
    │  配置 IP/串口参数、界面、场景编排
    ▼
现场部署

理想工作流是：

1. 建库：新设备首次接触时，工程师在现场边验证边录入指令库
2. 取用：下个项目需要同型号设备时，从库里取出指令，只需填写现场的 IP/端口
3. 反哺：现场发现指令有问题或有更好的写法，更新库里的记录

一些中控软件（比如 SoftControl）支持"设备模板"或"指令模板"导入，如果格式对得上，可以把指令库里的 JSON 转换成软件支持的导入格式，进一步省去手动录入的环节——但这个转换脚本要自己写或者让厂商支持，不是所有软件都原生支持外部库导入。

---

指令库文件模板：可直接套用的结构

这是可以直接 Fork 使用的最小化目录和文件结构：

device-cmd-lib/
├── README.md            ← 必须写：命名规范 + 贡献流程 + 版本号规则
├── _template.json       ← 新设备文件的模板，复制改字段
├── projectors/
│   └── _template.json   ← 可选：细化到品类的模板
├── displays/
├── matrices/
├── relay-io/
├── serial-servers/
└── macros/
    └── _template.json

_template.json 内容（给团队成员用的填空单）：

{
  "_note": "复制此文件，按设备 brand-model.json 命名，删掉所有注释字段",
  "device": {
    "brand": "",
    "model": "",
    "category": "projector|display|matrix|relay-io|serial-server|other",
    "doc_version": "",
    "firmware_verified": "",
    "verified_by": "",
    "verified_date": "",
    "verified_in_projects": [],
    "notes": ""
  },
  "interfaces": {},
  "commands": [],
  "macros": []
}

---

学会之后你能做出什么——效果与应用场景

回到开头那条动线：第一个项目查手册、第二个项目翻文件、第三个项目还在重录——建完这个库，这条循环就断了。把指令库落到日常工作里，它能帮你做出这些实实在在的改变：

你能做到	具体怎么体现
新项目开工"取货"而不是"从头查"	遇到库里有的型号，直接取出验证过的开机/关机/切源指令，现场只补 IP 和串口号，一台设备省掉半天查手册试串口
陌生设备一次录入、终身受益	第一次接某台矩阵边验证边录进库，后面每个用到它的项目都白捡，越做库越厚、越做越快
把"安全关投影"这类危险操作封成一键宏	关机→轮询冷却→等风扇停→再断电，整套封成 projector_safe_shutdown，谁调都是同一套正确流程，杜绝新人漏步骤烧灯泡
交接项目不靠口头传功	verified_by/verified_date/verified_in_projects 写清楚，接手的人一看就知道哪条指令可信、在哪些项目跑过，不用追着老同事问
团队并行改指令不打架	指令库上 Git，各开分支、code review 再合主干，两个工程师同时录设备也不会互相覆盖
厂商改编码只改一处	参数化模板把输入源编号收在一个地方，厂商换了 HDMI 编码只动模板那一行，全项目自动跟着对

这套功底用在哪些展厅场景：

• 多设备大型展厅：投影、大屏、矩阵、继电器几十上百台设备，全靠一个结构化库管住控制指令，中控编排时从库里取"弹药"，不在项目文件里现查现录。
• 同一甲方多期项目 / 连锁展馆：一期建库、二期三期直接复用，连锁品牌馆各地同型号设备一套指令走天下，只换现场 IP。
• 需要长期运维的场馆：设备固件升级、型号换代时，doc_version/firmware_verified 字段让你一眼看出哪些指令该重新验证，避免"升完固件突然关不了机"这种运维事故。
• 多人协作的集成公司：新人入职翻库就能上手配设备，老师傅的经验沉淀在 notes 里（哪条指令有坑、和谁有依赖），不随人走。

同一套方法，换个行业照样能用：不只是展厅，智能会议室、指挥中心、酒店客控、楼宇智控——凡是要"用软件统一控一堆异构硬件"的活儿，这套"命名规范 + 参数化 + 宏封装 + Git 版本 + 验证字段"的功夫都能平移过去，底层逻辑一模一样。你在展厅练出来的这套"把指令当资产管"的习惯，是集成工程师真正值钱的地方——它比记住某台投影的字节更保值。

---

动手挑战

1. 从你当前或上一个项目里，挑出最常用的一台设备（投影或大屏），按上面的模板把它的 3 条核心指令（开机、关机、查询状态）录成 JSON 文件，只录已在真实设备上验证过的，确认每个字段都有值。
2. 把"安全关投影"写成一个宏 JSON，步骤里用你录的指令 ID，加上等冷却的轮询步骤。把它和设备文件放在同一个 Git 仓库里，提交第一个 commit。
3. 找队友互相 review：对方能不能只看你的文件，知道怎么配这台设备？找到什么信息缺失。

---

本节学到的知识

• 指令库要独立于中控项目文件单独存：中控导出是专有格式、和版本/平台绑定，还混进了 IP、界面、场景等项目相关配置，搬不动也管不了手册/固件版本。
• 指令库定位是**"原始指令的单一来源"，比中控项目配置更底层的一层**，项目从库里取用，而不是现查现录。
• 库的组织形态：一个 Git 仓库，按品牌/型号存 JSON 或 YAML（换成 Excel 结构也一样），按 projectors/displays/matrices/relay-io/serial-servers/macros 分类。
• 单台设备文件要记的不只是指令字节，还有三个**"质量字段"：doc_version（哪版手册）、firmware_verified（哪个固件验证的）、verified_by/verified_date（谁在何时在真机上验过）**。
• 每条指令都要写 notes，尤其是坑——什么情况不能发、和别的指令的依赖、厂商已知 bug。
• 超时要分场景：投影开机/关机 timeout 设长（3000ms 甚至更多），查询类可以短。
• 参数化模板（payload_template + parameters）把只有参数不同的指令收成一条，厂商改编码只改模板那一个值，不用逐处找。
• 宏（Macro）= 把几条必须按顺序执行的指令封成一个命名原子操作，典型是安全关投影：关机→轮询冷却状态→等 90 秒冷却→可选断电。
• 宏的核心设计原则：尽量用应答确认（poll 到状态匹配）替代死等 sleep，因为投影冷却时间会随温度/工作时长变化，固定等时间不可靠。
• 指令库必须上 Git：git blame 追溯改动、分支隔离防覆盖、出问题可回滚、配合 code review 才合主干；main 只收验证过的内容。
• 建议加 verified_in_projects 数组记录这条指令在哪些项目跑过且良好，交接/接手时判断可信度成本极低。
• 跨项目复用四大陷阱：同型号不同批次固件差异（新机上线前必重验）、IP/串口号是项目参数不进库、厂商换型号老型号停产（新旧型号指令可能不通用）、宏里的时序是工程经验值需按现场环境实测。
• 一条落地死规矩：没有 verified_date 和 verified_by 的指令条目不得合并进主干，挡住"网上抄来未验证的指令"混进库。

---

小结 · 你现在掌握了什么

• 你明白了为什么要建独立指令库：避免每次翻手册、抵抗中控软件版本绑定、支持团队协作和版本追踪。
• 你有了一个具体的 JSON 文件结构模板，知道每个字段的用途：特别是 doc_version、firmware_verified、verified_by 这三个"质量字段"。
• 你理解了宏的设计原则：用应答确认替代固定等时间，把多步骤操作封装成原子宏，比如"安全关投影"。
• 你知道跨项目复用时的四类陷阱：固件差异、IP 不入库、型号换代、时序依赖现场。
• 你有了一套可以直接建起来的目录结构和最小化模板，今天就能开始用。

把指令库建起来之后，第 9 章的中控实战就有了可靠的"弹药库"——整场联调实战里我们会把库里的指令真正编排进 SoftControl 的场景，做出"一键开馆"。