# Stuntman SiLA 2 接口：对接调度软件和 LIMS

- 网址:https://unchainedlabs.help/product/stuntman/resources/sila-api

**Stuntman SiLA 2 接口 让调度软件或 LIMS 远程排队、启动和监控运行**

SiLA 2 是实验室自动化设备之间通信的开放标准。Stuntman 对外的控制接口只有 SiLA，没有 REST 或 OPC UA 接口。调度软件、LIMS 或自己写的客户端通过它载入设计队列、启动运行、读取状态、回答提示。

内容依据原厂 Stuntman SiLA API Reference（Rev A）。命令、属性和返回值的名称保留英文原文。

## 两个 Windows 程序各提供一个 SiLA 服务器

安装 Stuntman 软件后，Windows 用户登录时自动启动 Stuntman Launcher.exe。Launcher 只提供 DeviceService，用来以 SiLA 模式启动和关闭 Stuntman Run.exe。

Stuntman Run.exe 在 SiLA 模式下运行时，提供另外四个 feature。两个服务器都按惯例实现 SiLAService，用来识别服务器。

> | 服务器 | Feature | 用途 |
> | --- | --- | --- |
> | Stuntman Launcher | DeviceService | 启动、关闭 SiLA 模式的 Stuntman Run.exe |
> | Stuntman（RUN） | QueueRunService | 载入运行队列，启动、暂停、停止执行 |
> | Stuntman（RUN） | ExperimentStatusService | 读取执行状态，回答等待输入的提示 |
> | Stuntman（RUN） | SystemScriptService | 在仪器上运行独立的 Python 脚本，执行系统初始化 |
> | Stuntman（RUN） | ManagerStateService | 读写台面、吸头、Hotel、Liconic、Carousel 等资源管理器的状态 |

## 默认端口 50253 和 50052，默认不用 SSL

> | 项目 | Stuntman Launcher | Stuntman（RUN） |
> | --- | --- | --- |
> | 首选 TCP 端口 | 50253 | 50052 |
> | ServerName 默认值 | Stuntman Launcher | Stuntman |
> | 固定 UUID 的文件名 | sila-launcher.guid | sila.guid |

首选端口被其他服务占用时，服务器把端口号逐个加 1，直到找到空闲端口。所以端口一般是表中的值，但不保证。Rev A 参考手册没有写服务器自动发现的方法。

ServerName 可以在运行中修改，但不会保存，服务器每次启动都恢复默认值。SiLAService 的 ServerDescription 填的是仪器上配置的系统名和序列号。

默认情况下，服务器每次启动都随机生成 ServerUUID。要固定 UUID，把自己的 UUID 写进一个文本文件，按上表命名。文件放进 C:\Program Files\Unchained Labs\Stuntman，扩展名要改成 .guid。

默认安装不用 SSL，客户端必须允许不加密的连接才能连上。要用 SSL，准备 PEM 编码的 .key 和 .crt 文件，放进同一个目录。服务器启动时载入这两个文件，用于建立 SSL 连接。证书的配置方法不在参考手册范围内。

## 多数命令返回一个四字段的 JSON 字符串

- Status：Success 或 Failure。
- Content：命令的输出（有输出时）。
- Error：出错时的错误说明。
- StatusCode：成功时大于等于 0，失败时小于 0。

总能成功的少数命令只返回数据本身，没有这四个字段。Status 和 Error 是给人看的文字，调试客户端时有用。

## 从启动 RUN 到拿到结果的调用顺序

- 连 Launcher（端口 50253），调用 DeviceService.Start。StatusCode 0 表示 RUN 已启动并可远程访问；-2 表示 RUN 已在远程模式运行。
- 连 Stuntman 服务器（端口 50052）。调用 GetInformation，核对 SystemName 和 InstrumentSerial。
- 调用 SetQueue，传入队列 JSON。成功时 Content 为 Queue successfully loaded.
- 调用 RunQueue 并等它结束；或调用 StartQueue，它提交后立即返回。
- 运行中读属性 QueueStatus、QueueItemsRemaining、QueueItemsCount 看进度。GetExperimentStatus 返回当前设计和步骤。
- ExecutionStatus 变成 WaitingForInput 时，先用 GetActivePrompt 读提示。再用 SetInput 回答。
- RunQueue 结束后检查 Status、Content 和 StatusCode。用 ListQueue 看每一项的结果。
- 移除所有属性订阅，再调用 Launcher 的 DeviceService.Shutdown 关闭 RUN。

队列 JSON 是一个数组，每项是一个对象。第一个字段必须是 $type，后面的字段名用 camelCase。DesignItem 运行 .stunt 文件里的一个设计，ScriptItem 运行一个独立的 Python 脚本。

SetQueue 会校验队列：每个 filePath 必须是仪器上存在的文件；designName 必须在对应的 .stunt 文件里；脚本不能有 Python 语法错误。不通过时 StatusCode 为 -2，Error 逐条列出失败项。

> | 命令 | StatusCode | 含义 |
> | --- | --- | --- |
> | Start | 0 | Stuntman Run.exe 已启动，可通过 SiLA 远程访问 |
> | Start | -1 | Run.exe 已在运行但不在远程模式，是在 Launcher 之外启动的 |
> | Start | -2 | Run.exe 已在远程模式运行 |
> | Start | -3 | 在预期位置找不到 Run.exe |
> | Start | -4 | Run.exe 已启动，但没能进入 SiLA 远程模式 |
> | Start | -5 | 其他错误，看 Error 字段 |
> | Shutdown | 0 | Run.exe 已退出 |
> | Shutdown | -1 | Run.exe 在运行，但不是这个 Launcher 启动的 |
> | Shutdown | -2 | Run.exe 没有在运行 |
> | Shutdown | -3 | 有实验正在运行，不能关闭 |
> | Shutdown | -4 | 有未保存的更改，需先保存或放弃 |
> | Shutdown | -5 | 有脚本正在运行，不能关闭 |
> | Shutdown | -6 | 其他错误，看 Error 字段 |

## QueueRunService 载入并控制运行队列

> | 命令 | 作用 | 失败时的 StatusCode |
> | --- | --- | --- |
> | SetQueue | 载入队列，不启动 | -1 JSON 无法解析；-2 校验失败；-3 其他错误 |
> | StartQueue | 启动最近载入的队列，提交后立即返回 | -1 没有载入队列；-2 已有队列在运行；-3 准备时校验失败；-4 准备时其他错误 |
> | RunQueue | 可观察命令，队列结束才返回 | -1 至 -4 同 StartQueue；-5 意外异常；-6 某一项执行出错导致中止 |
> | DiscontinueQueue | 当前项跑完，后面未开始的项取消 | -1 没有队列在运行；-2 其他错误 |
> | AbortQueue | 当前项立即中止，后面未开始的项取消 | -1 没有队列在运行；-2 其他错误 |
> | PauseQueue | 暂停正在执行的实验或脚本，队列保留 | -1 没有队列在运行；-2 已暂停；-3 其他错误 |
> | ResumeQueue | 继续 PauseQueue 暂停的执行 | -1 没有队列在运行；-2 已在运行；-3 其他错误 |
> | GetQueueStatus | 返回队列整体状态 | -1 没有载入队列；-2 其他错误 |
> | ListQueue | 按提交顺序返回每一项的 FilePath、DesignName、Status | -1 其他错误 |

StartQueue 和 RunQueue 都会用掉已载入的队列。再跑一次之前，必须重新调用 SetQueue。ListQueue 的 Content 是 JSON 数组，不是字符串；队列还没启动时，数组为空。

队列状态有五个值：Pending、Running、Completed、Aborted、Cancelled。任何原因导致的失败都记为 Aborted，因为出错时操作员通常可以选择重试或中止。Cancelled 只表示队列被 DiscontinueQueue 停下，剩下的项没有运行。

> | RunQueue 的结局 | 客户端收到什么 |
> | --- | --- |
> | 队列正常跑完 | 正常完成，Content 为 Completed |
> | 被 DiscontinueQueue 停下 | 正常完成，Content 为 Cancelled |
> | 启动失败或执行中出错 | 正常完成，Status 为 Failure，看 StatusCode 和 Error |
> | 被中止 | 命令以取消结束，没有返回内容 |

被中止有三种来源：客户端取消 RunQueue 本身、另一个客户端调用 AbortQueue、操作员在仪器上中止实验。三种情况客户端收到的结果相同。失败不会让命令抛出错误，客户端要自己检查 Status、Error 和 StatusCode。

> | 可观察属性 | 内容 |
> | --- | --- |
> | QueueStatus | 与 GetQueueStatus 的 Content 相同；载入队列前为 null |
> | QueueItemsRemaining | 当前项之后还要跑的项数；启动前等于载入的项数，结束后为 0 |
> | QueueItemsCount | 队列总项数，SetQueue 后确定，运行中不变 |

QueueItemsCount 减去 QueueItemsRemaining，就是队列已推进到第几项。

## ExperimentStatusService 报告状态并回答提示

> | 命令 | 返回 | 失败时的 StatusCode |
> | --- | --- | --- |
> | GetExecutionStatus | 执行状态字符串 | -1 其他错误 |
> | GetActivePrompt | 等待回答的提示：Title、Message、AvailableOptions | -1 没有等待中的提示；-2 其他错误 |
> | SetInput | 用参数 Option 回答当前提示 | -1 没有等待中的提示；-2 Option 为空；-3 不在可选项里，Error 列出有效选项；-4 其他错误 |
> | GetExperimentStatus | ExperimentStatus、DesignName、ScriptName、CurrentStep | -1 没有载入队列；-2 其他错误 |
> | GetInformation | Application、Version、SystemName、InstrumentSerial、ActiveItemType、ActiveItemPath、QueueItemsRemaining | -1 其他错误 |

GetExecutionStatus 返回一个值，按优先顺序依次判断：WaitingForInput、Paused、Running、Idle。WaitingForInput 表示有提示等待回答。它只说明是否正在执行，运行怎样结束要看 GetExperimentStatus 和 GetQueueStatus。

ExperimentStatus 有四个值：Pending、Running、Completed、Aborted。实验指最近一次启动的队列项，所以实验结束后 DesignName 和 ScriptName 仍保留。脚本项的 DesignName 为空字符串。CurrentStep 在第一步上报前是 Initializing，脚本项是 Executing Script。

SetInput 的 Option 忽略首尾空格，不区分大小写。独立脚本暂停或中止时弹出的提示，也在这里读取和回答。

> | 可观察属性 | 内容 |
> | --- | --- |
> | ExecutionStatus | Idle、Running、Paused 或 WaitingForInput，变化时更新 |
> | ActivePrompt | 与 GetActivePrompt 的 Content 相同；没有提示时为 null |
> | ExperimentStatus | 只有状态值，不含设计、脚本和步骤；载入队列前为 null |

## SystemScriptService 在仪器上运行 Python 脚本

StartScript 和 RunScript 的参数是 Script JSON，含两个字段。ScriptPath 是脚本完整路径；Parameters 是命令行形式的参数字符串。脚本不需要参数时，Parameters 可以省略或留空。脚本与已在执行的队列同时运行。

> | 命令 | 作用 | 失败时的 StatusCode |
> | --- | --- | --- |
> | StartScript | 启动脚本后立即返回，不报告成败 | -1 已有本命令启动的脚本在运行；-2 JSON 无法解析；-3 ScriptPath 为空或文件不存在；-4 其他错误 |
> | RunScript | 可观察命令，脚本结束才返回，报告成败 | -1 至 -4 同 StartScript；-5 意外异常；-6 脚本出错停止 |
> | PauseScript | 在下一条可追踪语句处暂停，并弹出提示 | -1 没有脚本在运行；-2 正在中止；-3 已暂停；-4 其他错误 |
> | ResumeScript | 继续暂停的脚本 | -1 没有脚本在运行；-2 脚本没有暂停；-3 还没到可继续的位置；-4 其他错误 |
> | AbortScript | 在下一条可追踪语句处中止，不要求确认 | -1 没有脚本在运行；-2 其他错误 |
> | InitializeSystem | 运行仪器配置的系统初始化脚本，完成后才返回 | -1 已有脚本或实验在执行；-2 初始化失败 |

RunScript 成功时 Content 为 Script completed. 脚本被中止时，命令以取消结束，没有返回内容，结果与 RunQueue 被中止时相同。

脚本停在两条可追踪语句之间时，例如在等一个耗时的硬件操作，要到下一条可追踪语句才暂停。暂停请求生效前调用 ResumeScript，暂停会被撤回，脚本继续运行。脚本已停在提示上时，AbortScript 直接回答这个提示，不再弹出第二个。

InitializeSystem 运行的脚本，与 Stuntman RUN 汉堡菜单里的初始化是同一个。

## ManagerStateService 用 XML 读写资源管理器状态

每个资源管理器有一对 Get 和 Set 命令。Get 在 Content 里返回 XML；Set 的参数 State XML 用与 Get 返回相同的格式。可以先读出 XML，修改后再写回。

> | 对象 | 命令 | Set 的失败 StatusCode |
> | --- | --- | --- |
> | 台面配置 | GetDeckConfigurationState / SetDeckConfigurationState | -1 XML 为空；-2 XML 格式不正确；-3 其他错误 |
> | 吸头管理 | GetTipManagementState / SetTipManagementState | -1 XML 为空；-2 XML 格式不正确；-3 无法导入；-4 其他错误 |
> | Hotel | GetHotelState / SetHotelState | -1 XML 为空；-2 XML 格式不正确；-3 其他错误 |
> | Liconic | GetLiconicState / SetLiconicState | -1 本系统没有 Liconic；-2 XML 为空；-3 XML 格式不正确；-4 其他错误 |
> | Carousel | GetCarouselState / SetCarouselState | -1 本系统没有 Carousel；-2 XML 为空；-3 XML 格式不正确；-4 板数据无法校验或导入；-5 其他错误 |

SetDeckConfigurationState 应用新状态后保存。SetCarouselState 先校验板数据，再应用并保存。系统没有 Liconic 或 Carousel 时，对应的 Get 命令返回 -1。

## 关闭 RUN 前移除所有属性订阅

ExperimentStatusService 和 QueueRunService 的可观察属性使用订阅。订阅由 Stuntman RUN 记录。客户端用过这些属性，就必须在 RUN 关闭前移除订阅。否则所有窗口关掉后，RUN 仍在后台运行。

用 C# 的 Tecan SiLA 库时，对访问过可观察属性的每个 feature 客户端对象都要调用 Dispose。即使代码没有订阅 PropertyChanged 事件，Tecan 库也会在访问属性时自动建立订阅。其他库建立订阅的条件可能不同。

- StartScript 启动的脚本还在运行时，再调用 StartScript 返回 -1；RunScript 同样如此。
- StartQueue 时已有队列在运行，返回 -2。
- 有实验、脚本或未保存的更改时，Shutdown 不能关闭 RUN。
- 只有 Launcher 自己启动的 RUN 才能用 Shutdown 关闭；在 Launcher 之外手动打开的 RUN 不在远程模式。

- servers · 两个 SiLA 服务器
- connect · 端口、UUID 与 SSL
