SiLA 2 是实验室自动化设备之间通信的开放标准。Stuntman 对外的控制接口只有 SiLA,没有 REST 或 OPC UA 接口。调度软件、LIMS 或自己写的客户端通过它载入设计队列、启动运行、读取状态、回答提示。
内容依据原厂 Stuntman SiLA API Reference(Rev A)。命令、属性和返回值的名称保留英文原文。
安装 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 等资源管理器的状态
项目 / 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 连接。证书的配置方法不在参考手册范围内。
总能成功的少数命令只返回数据本身,没有这四个字段。Status 和 Error 是给人看的文字,调试客户端时有用。
队列 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 字段
命令 / 作用 / 失败时的 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,就是队列已推进到第几项。
命令 / 返回 / 失败时的 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
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 汉堡菜单里的初始化是同一个。
每个资源管理器有一对 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。
ExperimentStatusService 和 QueueRunService 的可观察属性使用订阅。订阅由 Stuntman RUN 记录。客户端用过这些属性,就必须在 RUN 关闭前移除订阅。否则所有窗口关掉后,RUN 仍在后台运行。
用 C# 的 Tecan SiLA 库时,对访问过可观察属性的每个 feature 客户端对象都要调用 Dispose。即使代码没有订阅 PropertyChanged 事件,Tecan 库也会在访问属性时自动建立订阅。其他库建立订阅的条件可能不同。