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

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:Feature DeviceService;用途 启动、关闭 SiLA 模式的 Stuntman Run.exe

Stuntman(RUN):Feature QueueRunService;用途 载入运行队列,启动、暂停、停止执行

Stuntman(RUN):Feature ExperimentStatusService;用途 读取执行状态,回答等待输入的提示

Stuntman(RUN):Feature SystemScriptService;用途 在仪器上运行独立的 Python 脚本,执行系统初始化

Stuntman(RUN):Feature ManagerStateService;用途 读写台面、吸头、Hotel、Liconic、Carousel 等资源管理器的状态

默认端口 50253 和 50052,默认不用 SSL

项目 / Stuntman Launcher / Stuntman(RUN)

首选 TCP 端口:Stuntman Launcher 50253;Stuntman(RUN) 50052

ServerName 默认值:Stuntman Launcher Stuntman Launcher;Stuntman(RUN) Stuntman

固定 UUID 的文件名:Stuntman Launcher sila-launcher.guid;Stuntman(RUN) 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:StatusCode 0;含义 Stuntman Run.exe 已启动,可通过 SiLA 远程访问

Start:StatusCode -1;含义 Run.exe 已在运行但不在远程模式,是在 Launcher 之外启动的

Start:StatusCode -2;含义 Run.exe 已在远程模式运行

Start:StatusCode -3;含义 在预期位置找不到 Run.exe

Start:StatusCode -4;含义 Run.exe 已启动,但没能进入 SiLA 远程模式

Start:StatusCode -5;含义 其他错误,看 Error 字段

Shutdown:StatusCode 0;含义 Run.exe 已退出

Shutdown:StatusCode -1;含义 Run.exe 在运行,但不是这个 Launcher 启动的

Shutdown:StatusCode -2;含义 Run.exe 没有在运行

Shutdown:StatusCode -3;含义 有实验正在运行,不能关闭

Shutdown:StatusCode -4;含义 有未保存的更改,需先保存或放弃

Shutdown:StatusCode -5;含义 有脚本正在运行,不能关闭

Shutdown:StatusCode -6;含义 其他错误,看 Error 字段

QueueRunService 载入并控制运行队列

命令 / 作用 / 失败时的 StatusCode

SetQueue:作用 载入队列,不启动;失败时的 StatusCode -1 JSON 无法解析;-2 校验失败;-3 其他错误

StartQueue:作用 启动最近载入的队列,提交后立即返回;失败时的 StatusCode -1 没有载入队列;-2 已有队列在运行;-3 准备时校验失败;-4 准备时其他错误

RunQueue:作用 可观察命令,队列结束才返回;失败时的 StatusCode -1 至 -4 同 StartQueue;-5 意外异常;-6 某一项执行出错导致中止

DiscontinueQueue:作用 当前项跑完,后面未开始的项取消;失败时的 StatusCode -1 没有队列在运行;-2 其他错误

AbortQueue:作用 当前项立即中止,后面未开始的项取消;失败时的 StatusCode -1 没有队列在运行;-2 其他错误

PauseQueue:作用 暂停正在执行的实验或脚本,队列保留;失败时的 StatusCode -1 没有队列在运行;-2 已暂停;-3 其他错误

ResumeQueue:作用 继续 PauseQueue 暂停的执行;失败时的 StatusCode -1 没有队列在运行;-2 已在运行;-3 其他错误

GetQueueStatus:作用 返回队列整体状态;失败时的 StatusCode -1 没有载入队列;-2 其他错误

ListQueue:作用 按提交顺序返回每一项的 FilePath、DesignName、Status;失败时的 StatusCode -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:返回 执行状态字符串;失败时的 StatusCode -1 其他错误

GetActivePrompt:返回 等待回答的提示:Title、Message、AvailableOptions;失败时的 StatusCode -1 没有等待中的提示;-2 其他错误

SetInput:返回 用参数 Option 回答当前提示;失败时的 StatusCode -1 没有等待中的提示;-2 Option 为空;-3 不在可选项里,Error 列出有效选项;-4 其他错误

GetExperimentStatus:返回 ExperimentStatus、DesignName、ScriptName、CurrentStep;失败时的 StatusCode -1 没有载入队列;-2 其他错误

GetInformation:返回 Application、Version、SystemName、InstrumentSerial、ActiveItemType、ActiveItemPath、QueueItemsRemaining;失败时的 StatusCode -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:作用 启动脚本后立即返回,不报告成败;失败时的 StatusCode -1 已有本命令启动的脚本在运行;-2 JSON 无法解析;-3 ScriptPath 为空或文件不存在;-4 其他错误

RunScript:作用 可观察命令,脚本结束才返回,报告成败;失败时的 StatusCode -1 至 -4 同 StartScript;-5 意外异常;-6 脚本出错停止

PauseScript:作用 在下一条可追踪语句处暂停,并弹出提示;失败时的 StatusCode -1 没有脚本在运行;-2 正在中止;-3 已暂停;-4 其他错误

ResumeScript:作用 继续暂停的脚本;失败时的 StatusCode -1 没有脚本在运行;-2 脚本没有暂停;-3 还没到可继续的位置;-4 其他错误

AbortScript:作用 在下一条可追踪语句处中止,不要求确认;失败时的 StatusCode -1 没有脚本在运行;-2 其他错误

InitializeSystem:作用 运行仪器配置的系统初始化脚本,完成后才返回;失败时的 StatusCode -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;Set 的失败 StatusCode -1 XML 为空;-2 XML 格式不正确;-3 其他错误

吸头管理:命令 GetTipManagementState / SetTipManagementState;Set 的失败 StatusCode -1 XML 为空;-2 XML 格式不正确;-3 无法导入;-4 其他错误

Hotel:命令 GetHotelState / SetHotelState;Set 的失败 StatusCode -1 XML 为空;-2 XML 格式不正确;-3 其他错误

Liconic:命令 GetLiconicState / SetLiconicState;Set 的失败 StatusCode -1 本系统没有 Liconic;-2 XML 为空;-3 XML 格式不正确;-4 其他错误

Carousel:命令 GetCarouselState / SetCarouselState;Set 的失败 StatusCode -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