di-omics/plr-reverse-engineer

# plr-reverse-engineer 逆向工程手册和工具，旨在将没有公开自动化 API 的实验室仪器纳入 PyLabRobot 控制，从而实现以无头（headless）方式驱动运行（例如通过 Raspberry Pi），而不是通过厂商控制台。 本仓库负责逆向工程部分。实际与硬件通信的 PyLabRobot 后端位于 [di-omics/pylabrobot](https://github.com/di-omics/pylabrobot) 中。这种拆分是刻意为之：这里的工作旨在还原厂商指令集，并将其捕获为 `ProtocolMap`（一组已解码、可重放的指令）；而那边的后端则负责加载完成的 ProtocolMap，并在严格的硬件安全保护下进行重放。捕获、关联和解码过程不放入 PyLabRobot 代码树中；库中仅包含读取部分。 该方法遵循 PyLabRobot 自身的逆向工程方法（Rick Wierenga 及 PLR 维护者），并针对不同仪器进行了标注来源和适配。根据 PLR 指南，其核心原则是：如果你能读取 OEM 软件发送的所有数据，你就可以复现它：运行小型的 OEM 测试程序，捕获流量，改变一个参数并对比差异（diff），将频繁重复的数据帧视为状态/保活（keep-alive）消息。请参阅 [PLR RE 指南](https://discuss.pylabrobot.org/t/is-there-guide-to-reverse-engineer-a-machine-to-be-supported-to-plr/285)、[贡献者指南](https://docs.pylabrobot.org/stable/contributor_guide/new-machine-type.html)以及演讲[“如何逆向工程实验室设备”](https://www.youtube.com/watch?v=waHR1ErHN-Y)。 ## 仪器 | 仪器 | 类别 | 手册 | 状态 | | --- | --- | --- | --- | | BD FACSMelody | 细胞分选仪 (FACS) | [instruments/bd-facsmelody](instruments/bd-facsmelody/README.md) | 后端已在 PyLabRobot 中（已经过试运行测试）；正在还原指令集 | | Agilent 6530 Q-TOF | 高精度质量数 LC/MS | [instruments/agilent-6530-qtof](instruments/agilent-6530-qtof/README.md) | 优先级高；Tier 0 触点闭合（contact closure）无需解码，LAN 控制映射正在进行中 | | Biotage V-10 Touch | 溶剂蒸发仪 | [instruments/biotage-v10-touch](instruments/biotage-v10-touch/README.md) | 传输分支已在实验台上解决，接下来进行 ProtocolMap 还原 | | Element AVITI | DNA 测序仪 (NGS) | [instruments/element-aviti](instruments/element-aviti/README.md) | Tier 0 运行文件夹遥测目前已可用；正在还原 HTTP/JSON 控制 API | | Namocell Hana | 单细胞分配器 | [instruments/namocell-hana](instruments/namocell-hana/README.md) | Tier 0 USB 发现目前已可用；正在还原字节指令集 | [PREFLIGHT.md](PREFLIGHT.md) 是采购与打包核对清单，[PI-SETUP.md](PI-SETUP.md) 用于准备 Raspberry Pi 捕获主机，[bench-kit.md](bench-kit.md) 是包含选型依据的物料清单 (BOM)，[APPROACH.md](APPROACH.md) 是按小时规划的实验台操作手册，[instruments/agilent-6530-qtof/WIRING.md](instruments/agilent-6530-qtof/WIRING.md) 是包含 APG 引脚分布的触点闭合接线说明，[instruments/element-aviti/CAPTURE.md](instruments/element-aviti/CAPTURE.md) 介绍如何捕获用于解码的 AVITI 控制平面流量，而 [instruments/namocell-hana/CAPTURE.md](instruments/namocell-hana/CAPTURE.md) 介绍如何捕获 Namocell 主机到仪器的字节流量。 ## 可以即插即用吗？ 部分可以，明确的界限很重要： - **质谱仪 Tier 0（触点闭合）：是的，即插即用。** 它不需要解码。将 Pi 连接到背面的远程控制线路上，使用万用表和逻辑分析仪识别哪个引脚是 Ready/Start/Stop，填写引脚映射，然后武装（armed）运行。`plr_re.instruments.agilent6530` 会在安全保护下读取 Ready 并发出 Start/Stop 脉冲。 - **AVITI Tier 0（运行文件夹状态）：是的，目前为只读。** AVITI 将每次运行写入一个输出文件夹，以 `RunUploaded.json`（包含 `outcome`）结束。`plr-re aviti watch ` 无需解码且毫无风险地报告 running/complete/outcome，从而让编排器获得真实的运行状态并顺利交接给 Bases2Fastq。 - **Namocell Tier 0（传输发现）：是的，目前为只读。** Hana 是一种采用字节协议的仪器，没有即插即用的控制路径，但 `plr-re namocell discover` 会以只读方式枚举 USB/serial 链路，无需解码，以便在捕获前找到物理连接。驱动该分配器是一项类似于 FACSMelody 的实验台捕获与解码工作。 - **已解码的协议控制（Q-TOF 的 LAN、V-10 的 HMI 总线、AVITI 的 AvitiOS HTTP API、Hana 的字节链路）：在上实验台之前不行。** 根据定义：除非你从仪器上捕获到这些指令，否则它们是未知的，因此没人能预先硬编码出可用的 `start_run` 或 `set_temperature`。已经预先构建好的，是让每个步骤只需一条指令的工具体系：带有动作标记的捕获器、字节差异对比工具（byte-diff correlator）、Modbus 解码器、HAR 解码器，以及一个在映射完成后立即运行映射的受保护重放器。 简而言之：触点闭合 MVP 已经可以运行；其余部分是一个快速、受保护的捕获与解码循环，而不是纯手工操作。 ## 快速开始（工具包） ``` pip install -e . # core is stdlib-only; add [serial] or [pi] extras on the Pi # Tier 0 质谱仪、触点闭合。默认 Dry-run（仅记录日志，不进行任何操作）： plr-re agilent status --config configs/agilent-pinmap.example.json plr-re agilent start --config configs/agilent-pinmap.example.json # dry-run plr-re agilent start --config configs/agilent-pinmap.example.json --armed --allow-actuation plr-re agilent scan --pins 17 5 6 13 19 26 --armed # find which pin is Ready plr-re agilent probe 169.254.1.10 # Tier 1 LAN, read-only # Element AVITI。Tier 0 run-folder 状态为只读，无需解码： plr-re aviti watch /mnt/aviti-output/20260713_AV1_run42 # running/complete/outcome plr-re aviti probe 192.168.1.50 # find the control endpoint plr-re aviti status --config configs/aviti.example.json # dry-run until armed # Namocell Hana。Tier 0 USB/serial 发现为只读，无需解码： plr-re namocell discover # find the control link plr-re namocell status --config configs/namocell.example.json # dry-run until armed plr-re namocell sort --protocol single_gfp --plate 384 # dry-run: previews the sequence # 在标记每个离散操作的同时捕获 OEM 流量： plr-re capture lan --iface eth1 --hosts 169.254.1.10 --out cap.pcap --mark plr-re capture serial --port /dev/ttyUSB0 --baud 19200 --out v10.jsonl plr-re capture http --out aviti.har # AvitiOS UI/service traffic # 解码：对比两个单参数 frame、解码一个 Modbus frame、将整个 # serial 捕获扫描成 register map，或从 AVITI HAR 中读取 API 调用： plr-re decode diff aa0128cc aa0129cc plr-re decode modbus 0106001000288811 plr-re decode modbus-log v10.jsonl plr-re decode har aviti.har # writes first = actuation # 构建并追踪 ProtocolMap： plr-re map seed biotage_v10 --out maps/biotage_v10.json plr-re map coverage maps/biotage_v10.json # exits non-zero while anything is undecoded # Biotie setpoint（受保护，带有硬性温度上限）。在 armed 之前保持 Dry-run： plr-re biotage set-temp 40 --map maps/biotage_v10.json ``` 所有能驱动硬件的操作在添加 `--armed` 之前均处于试运行状态，而执行动作的指令还需要额外加上 `--allow-actuation`。正式运行会拒绝在映射不完整的情况下启动。无设备测试涵盖了安全保护、覆盖率门槛、触点闭合与 HTTP 试运行、运行文件夹读取器以及各种解码器（`pytest`）。 ## 方法 每台仪器都遵循相同的脉络；各仪器的专用手册会填充具体细节。 1. 映射 OEM 协议栈和传输层。找出厂商软件是如何连接到设备的（USB、serial、TCP、触点闭合，或 HTTP/JSON 微服务 API）并记录 endpoint。这将填充 `ProtocolMap.transport` 和 `endpoint`。 2. 捕获带有 UI 动作标签的流量。在捕获运行期间，每次只执行一个独立的厂商动作，并标记每个动作发生的瞬间，以便将捕获的数据切分为与动作对齐的时间窗口。执行一个动作，确切地查看它生成了哪些字节。 3. 将动作与字节关联并解码数据帧结构。分离出某个动作产生的数据帧，并解码 header、length、payload 和 checksum。改变单个参数并对比数据帧差异，以解码出每个参数的编码方式。根据 PLR 方法，频繁重复的数据帧通常是状态/保活消息，而不是你想要的动作；请将其搁置（对于 HTTP 仪器，HAR 解码器会自动标记这些内容）。 4. 构建带有覆盖率追踪的 ProtocolMap。将每条解码后的指令记录为带有参数编码器和成功响应的帧模板。必需的指令列表会预先播种（seeded），因此覆盖率检查始终能准确报告当前是什么阻碍了正式运行。 5. 受保护的重放。首先确认只读指令。在后端被武装（armed）之前，重放始终保持试运行状态；对于执行动作的指令，必须在有人工监督（human in the loop）的情况下明确允许其执行动作。 6. 在仪器上进行验证。只有在 ProtocolMap 完成并确认了只读重放后，才在有人在场的情况下端到端运行实际操作。 ## 安全态势 这些都是真实的仪器，带有激光、高压、加压气体、高温、真空、危险溶剂以及花费真金白银购买的一次性耗材。每个后端在默认情况下都是极其谨慎的： - 默认试运行：它会记录将要发送的确切数据帧或请求，但不会进行任何传输。 - 执行动作的指令（任何涉及移动流体、执行分选、启动泵或气体或高压、加热、抽真空或提交测序运行的操作）即使在武装后，也需要明确、单独的授权。 - 只要 ProtocolMap 中有任何必需指令未被解码，正式运行就会拒绝启动，因此映射一半的协议无法驱动硬件。 对自有的仪器进行逆向工程以实现互操作性，是一种合理且成熟的做法。安全保护和厂商互锁机制保持不变：此工具体系仅用于编排，它不会移除仪器自身的限制。

标签：PyLabRobot, 云资产清单, 实验室自动化, 嵌入式系统, 硬件控制, 逆向工具, 逆向工程