Stunner 自动化交付:验证、速查、示例与清单

系列指南 · 第 6 篇

Stunner 自动化交付：验证、速查、示例与清单

脚本写完之后还不算交付。Stunner 进自动化产线之前，需要先用真实样品跑一轮湿跑验证；现场出问题时，要能从一串负数状态码里快速看出原因；机柜布置、工作台开孔、机械臂路径规划，要按官方图纸的精确尺寸来。这三件事在现场最常需要随手查；文末另附端到端 C# 示例、Performance Verification 要点和交付清单。

先认识几个名词

• 湿跑(wet run) — 用真实样品(而不是空跑)把整套系统从加样、测量到结果落盘走一遍。验证脚本、机械、字符串、数据流都对得上。
• 状态码体系 — Stunner API 用整数返回结果。约定：0 是成功，正数是状态/补充信息(不是错)，负数是错误，不同负数对应不同原因。
• 降级处理 — 出错时不停下来等人，改用一种不那么自动但仍可继续的方式。比如条码读不到时，从 autodetect 退回到明确传 plate_ID。
• "返回码 → 动作" 映射 — 把"看到状态码 X 该做什么"统一写成一个查找表(重试 / 降级 / 停产线 / 报警)。这比每个调用各自写 try/catch 更易维护。
• pump profile — Stunner 测量时控制微流控泵推进样品的运行参数文件。仪器内置一组，新应用刷进去时一起更新。
• chip ID — Stunner Plate 上的微流控芯片标识。仪器测量前要先识别 chip ID，识别不到会报 −26。
• reference plane(参考平面) — 工作台上由两根定位销定义的水平基准面。所有 (X, Y, Z) 坐标都从这个面起算。
• 交付清单 — 系统调试完毕、交给客户接手时，需要一并提供给客户的资料清单。半年后排查问题时，要查的资料应该都在这一份清单里。

交付前要过的五道关

自动化整合的验收，按下面这个顺序进行最稳。每一步都对应不同的验证目标；前一关通过再进下一关，出了问题就能定位到具体环节。

湿跑验证：由简到繁跑四轮

这四轮覆盖了整条链路里最容易出问题的几个环节。前三轮各跑一块板，第四轮连续跑多块。建议按顺序跑，每轮验证通过之后再进入下一轮。这样一旦出现异常，问题范围比较容易锁定。

板 / 用途 / 关注点

1:用途 空板自检;关注点 不加样品，让机械臂搬一块空 Stunner Plate 进出几次。看机械臂能否每次精准入位、条码能否每次读到、托盘机械动作有无卡顿。

2:用途 已知浓度样品板;关注点 用 BSA、IgG 等标准品配 3 个浓度梯度，每浓度 4 复孔，加 4 个 PBS 空白(共 16 孔)。比对测出来的浓度和标定值的偏差，确认仪器、应用、字符串字段、E1% 都对得上。

3:用途 真实样品单板;关注点 实际项目要测的样品，先单独跑一板。人工对照 Stunner Client 直接测出来的结果，确认 API 和 Client 给的数据一致；不一致时，先查字符串字段是否写错。

4:用途 连续多板;关注点 让机械臂连续搬 5–10 块真实样品板，中间不人工干预。看 Get_Status 轮询是否稳定、Get_Results 一次取走是否成功、.bin 文件是否每块都正确落到共享目录。

几条排查经验:第 2 板浓度偏差，先查实验定义里的 application_name 和样品定义里的 E1% 列。第 3 板和 Client 数据不一致，多数情况是 blanking_information 模式或 column_BSRF 标错。第 4 板偶发失败，通常是轮询频率太快，或网络共享在并发场景下不稳定。

状态码速查表

湿跑过程中要是出现问题，Stunner 不会弹任何对话框，所有信息都通过命令的整数状态码反馈出来。脚本拿到状态码后自己判断怎么处理。约定：0 是成功，正数是状态信息(不是错)，负数是错误。下表把全部状态码按数值排好，现场出问题时直接对照查。

代码:含义

正数：状态信息

999:Stunner Client 已接受退出

52:已连接，托盘正在移动

51:已连接，托盘已关闭

50:已连接，托盘已打开

33:已连接，测量已暂停

32:已连接，等待加载下一块 Stunner Plate

31:已连接，测量进行中

30:已连接，测量正在初始化

25:已连接，测量成功

23:已连接，测量已启动

21:已连接，无测量任务

20:访问权空闲

4:托盘本来就是关着的

3:托盘本来就是开着的

1:访问权已经在你手里

0:成功

0:命令执行成功

负数：错误(脚本必须处理)

−1:无访问权

−2:仪器状态不对(常因前一动作未完成)

−3:打不开托盘

−4:关不上托盘

−5:托盘位置不对

−9:解析实验定义出错

−10:解析样品定义出错

−11:找不到 pump profile

−12:pump profile 里没数值

−13:未定义样品

−14:托盘开位超时

−15:条码无效

−16:没有条码扫描器

−17:条码扫描器超时

−22:测量初始化失败

−24:测量失败

−26:测量失败：chip ID 未知

−31:测量进行中，命令无法执行

−52:托盘移动中，命令无法执行

−61:存空白：空白实验来自其他仪器

−62:存空白：空白实验超过 100 天

−63:存空白：仪器在空白测量后做过校准

−64:存空白：找不到可复现的空白

−65:存空白：找不到文件

−66:存空白：按列指定的 sample group 名错误

−67:存空白：按名称指定的 sample group 错误

−68:存空白：存在多个 sample group，需明确指定

−99:超时

−100:访问被本地操作中断

−102:plate ID 无效

−103:plate ID 已经测过

−104:必须等所有板测完才能取结果

−106:仪器里没有板

−111:仪器状态不对(描述与 −2 相同)

−120:自动化 License 未激活

负数：Stunner.dll / 通信内部错(可调 GetLastInternalError)

−200:TCP 连不上

−201:DLL 内部错：无法把返回字符串转成期望参数

−202:DLL 内部错：无法把状态码转成整数

负数：命令 / 参数 / 板型 / 应用层

−300:未知命令

−400:参数不全

−401:作为参数的文件找不到或读不到

−500:未明确错误

−901:仪器上未安装该应用

−902:实验定义里 plate type 不识别

−903:plate type 不能用于该应用

−904:plate type 不能用于该仪器

−905:应用加载失败

−906:该板需要更新光程文件

常见错误码怎么应对

上面的完整表平时作为字典查就够了。日常生产里高频出现的只有下面几个，先把它们的处理逻辑写进脚本。

### 推荐的统一处理方式

生产脚本里比较整齐的做法，是把"看到这个状态码该做什么"集中写在一个地方。不必每条命令调完都各自处理一遍。常见的做法是把应对动作归成四种：

- 能自动重试就重试；

- 不行就降级用备选方案(比如条码读不到就改用明确的 plate_ID);

- 再不行就停产线；

- 最严重就报警让人介入。

绝大多数错误码都能归到这四种之一，极少数需要特殊处理的单独列出来。这样的好处：脚本本身更整齐，出问题时也容易看出是在哪一步触发的。

仪器外形尺寸

下面两张是 Stunner RADLS S/N 903001 及以上、Stunner AF S/N 904001 及以上的官方尺寸图。S/N 902001–903000 这一段的图纸在 Manual Appendix 3 里，数据略有差异。主要差异是 Stunner Plate 中心在工作平面上的 Y 坐标：老批次 428.08 mm，新批次 423.44 mm。机械臂落板位置要按实际序列号调整。

Stunner 仪器底面尺寸图(S/N 903001+ / 904001+)。从仪器后参考边到 Stunner Plate 中心是 423.44 mm，从侧参考边到 Stunner Plate 中心是 338.2 mm;两个 12 mm 定位销孔的间距是 200 mm;托盘伸出方向相对底板的偏移分别是 139.59 mm 和 60.41 mm。所有尺寸单位 mm。

Stunner 仪器顶面投影尺寸(S/N 903001+ / 904001+)。主机箱体 575 × 371.6 mm;托盘从主机伸出 153.12 mm，机械臂搬板时要为这段空间留出余量。

机械臂路径要注意两件事:一是托盘伸出后的 153.12 mm 区域要保持留空。机械臂从板的正上方垂直下放，不能沿托盘伸出方向斜插。二是 Stunner 顶部有进气口，做堆叠或加防尘罩之前要参照说明书，留足散热空间。

Stunner Plate 尺寸

Stunner Plate 的外框尺寸遵循 SBS 96 板标准，机械臂的抓取参数可以直接套用 SBS 设置。但孔位排布和普通 96 板不一样：板上横排 6 条微流控 strip，每条 16 个加样孔，共 96 个。脚本里写孔位时，要按 Stunner 自己的命名规则。

Stunner Plate 工程图。外框 85.48 × 127.76 mm，符合 SBS 96 板标准；Frame 高 10 mm，上面贴 1.54 mm 厚的微流控 Strip，总高约 11.5 mm。三视图含正面孔位、侧面剖视(Section A-A)和背面定位特征，单位 mm。

• 外框 — 85.48 × 127.76 mm — SBS 96 板标准，机械臂抓取参数可直接套用。
• 总高 — 约 11.5 mm — Frame 10 mm + Strip 1.54 mm。机械臂的垂直抓取间距按这个高度配置。
• 孔位间距 — 9 mm — SBS 标准；96 个加样孔分布在 6 条 strip 上。
• 边缘公差 — ±0.25 mm 或 ±0.5 mm — 从角向内 12.7 mm 内的边缘 ±0.25 mm，其余区域 ±0.5 mm。这部分是给机械臂边缘抓取预留的精度余量。

比色皿适配板：更适合单机使用

除 Stunner Plate 之外，Stunner 还支持一种比色皿适配板(Cuvette Plate)。外框尺寸和 Stunner Plate 一样，也符合 SBS 标准，但高度和重量差别比较大。机械臂的抓取参数和搬运速度都要按 Cuvette Plate 单独配置。在 API 中使用时，实验定义里 dropplate_type 改成 "Cuvette Plate"。

• 外框 — 85.48 × 127.76 mm — 和 Stunner Plate 一样，符合 SBS 96 板标准。
• 总高 — 14.7 mm — 比 Stunner Plate 的 11.5 mm 高约 3 mm。机械臂的垂直抓取间距按这个高度配置。
• 总重 — 320 g — 含全部 8 个比色皿。约是空的 Stunner Plate (38 g) 的 8 倍，机械臂的搬运加速度和夹持力都要相应调整。
• 比色皿 — 8 个 — 排成 A1–D2 两列各 4 个。图中 100 mm 沿 127.76 mm 长边标注，是 1 列到 2 列槽口的跨距。

合适

单机使用

手动加样、对样品体积或波长有特殊要求、需要更大光程的场景。一次测 8 个样品，适合手动加样。

不太合适

自动化场景

一次只能测 8 个样品，比色皿的装填和密封需要人工完成。自动化带来的效率提升有限，反而会增加机械臂操作的出错概率。

如果客户场景确实需要用比色皿，通常把比色皿测量留在单机模式下进行。自动化的范围只覆盖 Stunner Plate 上的测量。

端到端示例：一段完整的 C# 脚本

手册 Appendix 1 给了一段完整的 C# 脚本，把整套指南讲过的概念串在一起。这里做了少量注释和缩进调整。它展示一次"两个 sample group、8 个孔的实验"从建立连接到取结果的完整流程。

这段代码里有几处工程细节，写生产脚本时要保留：

• goto End / goto Exit 模式:每条命令的返回值都判断 < 0，出错就跳到 End 标签；End 里统一调 Release_Access。手册用 goto 是为了让示例最短最直白，生产代码里换成 try/finally 也是一样的意思。核心是无论成败，Release_Access 都要执行。
• 轮询条件 != 32 && != 25 && != 31:意思是"状态在'测量中(31)'、'测完(25)'、'等下一块板(32)'之外的任何值，都视为异常退出"。循环本身由 while 条件收尾：读到 32 或 25 就结束，读到 31 继续等。
• Get_Results 上的 -104 重试:多板实验里，只要还有板没测完，Get_Results 就返回 -104。手册的写法是 while (status == -104) 死循环等，生产代码里建议加超时(比如累计等 10 分钟还在 -104，就报警)。
• Get_Results 第二个参数留空:留空表示"返回所有板的结果"，一次取走；传具体 plate_ID 才是只取那一块。

这段脚本跑完之后，Get_Results 返回的 results 字符串格式如下(手册 Table 14):

几个读结果的要点：

• 第一行是表头，后续每行一个孔。分隔符是 ;，跟 result_parameters 里 separator=; 对应。
• A1 和 E1 是空白行，浓度、A280、粒径都是 - 或 0，跟 result_parameters 里 no_result_value="-" 对应。
• 同组的 3 个复孔(B1/C1/D1 和 F1/G1/H1)浓度高度一致(2.10/2.11/2.10 和 4.08/4.06/4.02)。这本身就是个隐式的质量信号：复孔差异大就说明加样或测量有问题。
• SG1 用 Water 做缓冲液 + BSA 算 E1%=6.67;SG2 用 PBS + IgG 算 E1%=13.70。两组各扣各的空白(SG1 用 A1,SG2 用 E1)，互不影响。

替换 IP 和三段字符串之后，这段代码可以直接作为第一个 Stunner 自动化脚本的起点。

Performance Verification:仪器准确性验证

Performance Verification(PV，性能验证)是一套独立的仪器准确性检查流程。它用一组 Hellma 认证参考物质(CRM)，装在 Cuvette Plate 里。验证项包括吸光度准确性、精密度和线性，以及波长准确性、杂散光和分辨率，看 Stunner 是否仍然符合规范。验收标准跟美国药典 USP <857> 和欧洲药典 Ph. Eur. 2.2.25 对齐，是 GMP 项目里 IQ/OQ/PV 流程的一部分。

跟日常自动化测量不同，PV 的实验定义、样品定义、结果定义都是专门格式：

• 实验定义里 application_name 固定填 "Hellma CRM check",dropplate_type 必须是 "Cuvette Plate"。
• 样品定义是一段 JSON(不是 CSV)，装 CRM 认证数据和验收 criteria，下文逐段说明。
• 结果定义返回 PASS/FAIL 报告，不是 CSV 数据列。

推荐做法:JSON 字符串手写很容易出错。Stunner Client 软件里有 Edit CRM 和 Edit Criteria 两个工具。用它们在界面上配好每支 Hellma 比色皿的认证数据和需要的验收标准。然后导出成字符串，粘进 API 脚本。手册原文(§6)推荐用这种方式代替手写。详细流程见 Stunner Software User Guide §3.5。

在自动化集成项目里，PV 通常作为独立的合规验证脚本单独维护，不混在日常生产脚本里。一般由 QA 团队按周期(比如每月或每季度)手动触发，或者由调度系统在排程窗口里调用。

手册 §6.1 给出了 PV 的三段字符串示例：

实验定义(PV 专用)

和普通实验比，PV 实验定义短得多，不需要 [Import samples] 段，也不需要 DLS 参数。三行写定：实验名随意，后两行是 PV 的硬约束。

样品定义(JSON，结构示意)

这里有两段独立的 JSON。前一段(以 CRM_ 开头的部分) 装的是每支 Hellma 比色皿的认证数据。内容有名称、型号、序列号、校准证书编号。还有每个特征波长上的认证吸光度和不确定度(MU)。换了不同序列号的比色皿，这一段就要换。建议用 Stunner Client 的 Edit CRM 工具配好后导出，不要手填：序列号和小数位太多，手输容易错。

后一段(以 Criteria_ 开头的部分) 是验收标准：吸光度的最大允差、精密度、线性度；波长准确性、杂散光、分辨率的阈值。这部分对齐 USP <857> / Ph. Eur. 2.2.25，通常一份配好就长期不动。如果实验室有自己的内控标准想拧得更严，也可以在 Client 的 Edit Criteria 里改。

结果定义

PV 的 return text 是按 Test 项分行的 PASS/FAIL 报告(Date / Time / Plate ID / Test / Result)，不是一堆数据列。Get_Results 触发后，还会在结果共享目录里另外生成 6 份 PDF 报告 + 1 份原始数据文件。这些文件可以直接进合规归档。

交付清单

验收完成之后，系统通常由客户接手维护。建议在交付时把下面这份清单一并留给客户。半年甚至一年后再去排查问题，要查的资料应该都能在这一份里找到。

• overview · 交付前要过的五道关
• wet-run · 湿跑验证：由简到繁跑四轮
• status-table · 状态码速查表
• common-errors · 常见错误码怎么应对
• instrument-dim · 仪器外形尺寸
• plate-dim · Stunner Plate 尺寸
• cuvette-plate · 比色皿适配板
• end-to-end · 端到端示例(C#)
• 湿跑(wet run) · 用真实样品(而不是空跑)把整套系统从加样、测量到结果落盘走一遍。验证脚本、机械、字符串、数据流都对得上。
• 状态码体系 · Stunner API 用整数返回结果。约定：0 是成功，正数是状态/补充信息(不是错)，负数是错误，不同负数对应不同原因。
• 降级处理 · 出错时不停下来等人，改用一种不那么自动但仍可继续的方式。比如条码读不到时，从 autodetect 退回到明确传 plate_ID。
• "返回码 → 动作" 映射 · 把"看到状态码 X 该做什么"统一写成一个查找表(重试 / 降级 / 停产线 / 报警)。这比每个调用各自写 try/catch 更易维护。
• pump profile · Stunner 测量时控制微流控泵推进样品的运行参数文件。仪器内置一组，新应用刷进去时一起更新。
• chip ID · Stunner Plate 上的微流控芯片标识。仪器测量前要先识别 chip ID，识别不到会报 −26。
• reference plane(参考平面) · 工作台上由两根定位销定义的水平基准面。所有 (X, Y, Z) 坐标都从这个面起算。
• 交付清单 · 系统调试完毕、交给客户接手时，需要一并提供给客户的资料清单。半年后排查问题时，要查的资料应该都在这一份清单里。
• 字符串 · 在 API Tester 上验字符串 · 把三段字符串塞进 API Tester，挨条命令调一遍。确认 Define_Experiment、Measure、Get_Results 全部返回 0，字符串里没有语法或列号错误。
• 脚本 · 脚本独立跑一遍 · 在客户脚本的运行环境里，先绕开机械臂，直接连 Stunner，手动放板、关托盘，跑一遍完整流程。验证脚本的命令顺序、异常处理和轮询逻辑都对。
• 湿跑 · 湿跑验证 · 把机械臂或液体工作站接进来，用真实样品按下一节的四轮湿跑跑一遍。核对结果是否符合预期。
• 故障演练 · 故障演练 · 人为制造几个常见异常(条码读不到、放板倾斜、网络断开)。观察脚本和上层调度的反应是否符合预期。
• 交付 · 整理交付文档 · 把脚本源码、API License、Stunner Client 版本、网络配置、空白库内容、错误码处理逻辑全部整理给客户。完整清单见本篇最后一节。
• 网络 · −200 · TCP 连不上 · 多半是网络或 IP 配置出了问题。脚本里可以先重试 3 次，每次间隔 2 秒，仍然失败再让上层调度报警并停产线。同时调一次 GetLastInternalError()，拿 DLL 那一层的详细信息。
• License · −120 · License 未激活 · 激活码没填，或者 Automation 页面顶部没出绿色对勾。这种错脚本无法自动恢复，只能停下来等人去 Stunner Client 里重新激活。
• 会话 · −1 · 无访问权 · 上一个用 Stunner 的脚本没释放访问权，或者 USB 那边同时连着 Stunner Client。重新发 Request_Access;如果还不行，报警让人介入。
• 字符串 · −9 / −10 · 解析实验或样品定义出错 · 字符串语法有问题。脚本本身没法自动重试，要回去核对字符串。生产脚本里建议先用一个校验值(比如 hash)，比对当前要发的字符串和已验证过的版本是否一致。一致就跳过，不一致再去查改了什么。
• 逻辑 · −104 · 没测完就取结果 · 还有 Stunner Plate 没测完。多板实验里这是正常返回，按示例代码循环重试并加超时。如果超时报警，查轮询逻辑：Measure 之后有没有等 Get_Status 返回 25(测量成功)再发 Get_Results。
• 条码 · −15 / −17 · 条码无效或扫描超时 · 板贴反、条码污损是最常见原因。处理方式是降级：不用 "autodetect"，改用 Define_Experiment 返回的明确 plate_ID 去测。
• 硬件 · −22 / −24 / −26 · 测量初始化或测量失败 · 这一组通常是真正的设备问题：芯片识别失败、样品板装载异常，或者仪器自身故障。脚本可以先发一次 Reset() 再重试，仍失败就停产线、走维护流程。
• 空白 · −61 ~ −68 · 存空白相关错误 · 多数是 sample group 命名或时间过期。生产脚本里通常先用 Get_Stored_Blanks 查一下仪器里现存什么空白，再根据返回结果决定下一步怎么走。
• 外框 · 85.48 × 127.76 mm · SBS 96 板标准，机械臂抓取参数可直接套用。
• 总高 · 约 11.5 mm · Frame 10 mm + Strip 1.54 mm。机械臂的垂直抓取间距按这个高度配置。
• 孔位间距 · 9 mm · SBS 标准；96 个加样孔分布在 6 条 strip 上。
• 边缘公差 · ±0.25 mm 或 ±0.5 mm · 从角向内 12.7 mm 内的边缘 ±0.25 mm，其余区域 ±0.5 mm。这部分是给机械臂边缘抓取预留的精度余量。
• 外框 · 85.48 × 127.76 mm · 和 Stunner Plate 一样，符合 SBS 96 板标准。
• 总高 · 14.7 mm · 比 Stunner Plate 的 11.5 mm 高约 3 mm。机械臂的垂直抓取间距按这个高度配置。
• 总重 · 320 g · 含全部 8 个比色皿。约是空的 Stunner Plate (38 g) 的 8 倍，机械臂的搬运加速度和夹持力都要相应调整。
• 比色皿 · 8 个 · 排成 A1–D2 两列各 4 个。图中 100 mm 沿 127.76 mm 长边标注，是 1 列到 2 列槽口的跨距。
• 仪器 · 仪器 S/N、Stunner Client 软件版本号、API License 激活码(建议把 Unchained Labs 发的原始邮件一起存档)。
• 网络 · 固定 IP 配置；若用 DHCP，记录当前 IP 和 MAC 地址，方便 IT 在路由器里做绑定。
• 共享 · 网络共享目录路径、账号、密码失效日期(到期之前需要更新)。
• 脚本 · 客户脚本的源码、依赖(语言运行时、Stunner.dll 版本)以及运行环境部署说明。
• 字符串 · 已经验证过的实验定义、样品定义、结果定义字符串模板，每种实验类型留一份。
• 空白 · 仪器空白库当前内容：Plate type、sample group、有效期。
• 错误处理 · 错误码处理逻辑文档：哪些情况自动重试、哪些直接停产线、哪些需要人工介入。
• 基线 · 湿跑验证那四轮的结果存档，作为后续维护时的对照基线。
• PV · 如果做了 Performance Verification，保留 PV 的 6 份 PDF 报告和原始数据，以及对应的 CRM/Criteria 字符串模板；后续周期性 PV 沿用同一份配置。