Lunatic API 快速操作指南

系列指南 · 快速操作指南

Lunatic API 快速操作指南

Lunatic 第一次接进自动化，顺序是：先在 Lunatic & Stunner Client 软件里激活 License、配好网络；再打开 API Tester 验证脚本能远程调用仪器；最后断开 USB、给仪器断电重启一次，Lunatic 就准备好接受外部脚本控制了。完整的原理和 19 个 API 命令的细节，在系列另外 6 篇正文里。

先认识几个名词

• Lunatic & Stunner Client — Lunatic 和 Stunner 共用的 PC 端控制软件。首次配置、激活 License、把应用传到仪器都在这里完成，通过 USB 线和仪器通信。
• API License — 让外部脚本远程调用 Lunatic 的授权。出厂不带，需要向 Unchained Labs 单独申请，激活码按仪器序列号生成。
• API Tester — Unchained Labs 自带的桌面工具。不接工作站也能直接对着 Lunatic 把命令逐条试通，问题在接工作站之前就能暴露出来。
• TCP 端口 — Lunatic API 通信用的端口，在仪器上可配置(重启后生效)。Manual 文档里 Figure 10 截图显示 6700、Appendix 1 示例代码用 6300，具体值以 Client 软件 Settings/Info 页面为准。外部脚本(包括 API Tester)统一通过 仪器 IP + 这个端口的组合连接。
• .bin 文件 — Lunatic 每次 API 测量生成的原始数据文件。日常自动化用不到，但出问题排查或重新做图时要拿这份原始数据。

激活与配置：Lunatic & Stunner Client 里的 7 步

这 7 步都在 Lunatic & Stunner Client 的 Automation 页面里完成。动手之前，先准备好三样东西：一根 USB 线、一段网线、一份 API License 激活码。激活码向 Unchained Labs 申请，按仪器序列号绑定。

Manual Figure 10 — Automation 页面顶部 Activation code 区域。下面 7 步按这一页的版面顺序走(激活码 → Transfer Apps → Network Settings → DHCP/Static IP)。Settings/Info 区域显示这台样机的 TCP port 是 6700(右上角 注明重启后生效);实际值以你这台仪器的 Client 显示为准。*

关于 .bin 文件:每次 API 测量，Lunatic 都会在你指定的网络共享目录里生成一个 .bin 原始数据文件。日常自动化流程不需要它，但以后会用到它：在 Lunatic & Stunner Analysis 软件里看更详细的图；出问题时交给 Unchained Labs 工程师协助排查。

接通验证：先 API Tester，再真实驱动

7 步配完之后，Lunatic 这一侧已经准备好接受外部脚本控制。接真实工作站之前，建议先用 API Tester 把命令逐条试通，再换成真实驱动复核。问题在 API Tester 这一步暴露，就不会在工作站上浪费已加样的 Lunatic Plate。

日常切换：API 模式 ↔ 单机模式

日常用 Lunatic 有两种方式。API 模式由外部脚本通过网线远程调用。单机模式把 USB 接上 Lunatic & Stunner Client，人工在界面里操作。两种方式同一时刻只能开一个。USB 和网线如果都接着，仪器会同时收到两路指令，容易加载不出正确的实验参数。

从单机模式切到 API 模式，先把 USB 线从 PC 上拔掉(网线保持接着)，再给仪器断电重启一次；反方向切换同样要重启。拔 USB 是 QSG 的要求，断电重启是 Manual §3.1 的要求。按 Manual §3.1，集成模式下 USB 只在三种场景需要重接：(a) 首次使用前配置仪器、(b) 升级、(c) 做仪器校准。日常 API 运行不用 USB。

### 两种连接同时存在时怎么办

比如忘了拔 USB，两路连接就同时开着。Manual §3.1 写，这时会出现连接冲突，某些参数无法正确设置。典型表现是实验定义或板布局加载不出来。三种方式可以恢复：在 Client 里编辑 Plate layout 的过程中点界面上的"X"重置；或者在 API 模式下调一次 DQ_Reset() 命令；也可以把仪器断电再开机，这样同样能清除冲突。

想了解更多，去哪查

仪器能被脚本调用之后，写脚本、定义实验、处理错误、做合规验证还会碰到更细的问题，答案分散在下面几处。

• 系列正文 #01–#06 — 依次讲整合场景、装机、配置、命令、字符串和验证，展开这份指南的每一步；三段字符串的字段定义、状态码表和外形尺寸都在这里。
• 官方 Lunatic API Manual — Rev D,2026-04 发布。19 个命令的完整签名、全部状态码、字段定义、外形图纸都能在这里查到。
• 官方技术支持 — 需要 Unchained Labs 工程师专门支持时，联系 support@unchainedlabs.com。带上 .bin 原始数据文件，工程师可以直接导入 Analysis 软件排查。
• Lunatic IQ/OQ/PV 文档 — GMP 项目验收用。涵盖三阶段验证协议和 21 CFR Part 11 合规材料。中国团队可以协助提供。

• activate · 激活与配置：7 步
• verify · 接通验证：API Tester → 真实驱动
• swap · 日常切换：API ↔ 单机
• Lunatic & Stunner Client · Lunatic 和 Stunner 共用的 PC 端控制软件。首次配置、激活 License、把应用传到仪器都在这里完成，通过 USB 线和仪器通信。
• API License · 让外部脚本远程调用 Lunatic 的授权。出厂不带，需要向 Unchained Labs 单独申请，激活码按仪器序列号生成。
• API Tester · Unchained Labs 自带的桌面工具。不接工作站也能直接对着 Lunatic 把命令逐条试通，问题在接工作站之前就能暴露出来。
• TCP 端口 · Lunatic API 通信用的端口，在仪器上可配置(重启后生效)。Manual 文档里 Figure 10 截图显示 6700、Appendix 1 示例代码用 6300，具体值以 Client 软件 Settings/Info 页面为准。外部脚本(包括 API Tester)统一通过 仪器 IP + 这个端口的组合连接。
• .bin 文件 · Lunatic 每次 API 测量生成的原始数据文件。日常自动化用不到，但出问题排查或重新做图时要拿这份原始数据。
• 接好两根线，进 Automation 页面 · 先用 USB 线把 Lunatic 连到一台装了 Lunatic & Stunner Client 的 PC;同时把网线接到仪器背面的网口。打开 Client，点左上角三横线菜单按钮，进 Automation 页面。
• 填激活码 · 在 Activation code 区域，把激活码分成 4 段分别填进四个输入框，点 Add Activation Code。激活成功之后，API/DropControl 旁边会出现一个绿色对勾。判断是否激活，以这个对勾为准；按钮颜色是否变化不能用来判断。
• 把应用传到仪器(Transfer Apps) · 点 Transfer Apps,Client 把 PC 上的应用包传到仪器(Manual §3.2.2)。传完之后，仪器侧显示的应用数和 PC 侧一致，看一眼就能确认传到位。以后每次更新应用或升级 Client 软件，都要回到这里再传一次。
• 把空白传到仪器(Transfer Blanks，可选) · 如果想把 Client 里已经测过、可以复用的空白存到仪器本地，点 Transfer Blanks。在弹出的对话框里，选要传的空白实验。不打算复用空白，这一步可以跳过。
• 配 Network Settings · 在左下 Network Settings 区域填四个字段：Folder / Domain / User / Password。Domain 多数情况可以留空。填好后点 Save Changes。Folder 要以 \\IP 地址\路径 的格式开头(必须是网络共享目录，不能是本地盘)。这里填的 User / Password 是 Lunatic 仪器以后访问这个共享目录时用的账号，不是你的登录账号。官方 QSG 强烈建议配好 Folder:不配的话，每次测量后的 .bin 原始数据会丢失。
• 选 DHCP 或静态 IP · 右下 DHCP / Static IP 区域二选一。DHCP 让路由器自动分配 IP，适合临时调试；静态 IP 需要手动填地址、子网掩码、默认网关，IP 从此固定不变。自动化产线更推荐用静态 IP，以免重启路由器后 IP 改了，脚本连不上。
• 记下 IP，断开 USB · 回到 Client 左侧菜单的 Instrument 页面，确认这里显示了一个 IP 地址(而不是"No connection")。把这个 IP 记下来，后面写脚本要用。然后关闭 Client，把 USB 线从 PC 上拔下来，再给仪器断电重启一次(Manual §3.1 要求模式切换时断电重启)。后面进入 API 模式只走网线，USB 就不再需要。
• 先用 API Tester 单机试通 · 安装并启动 API Tester，选择 Lunatic。把左上角默认的 "localhost" 改成上一步记下的仪器 IP。然后依次点几条命令：DQ_Request_Access → DQ_Get_Instrument_Serial_Number(确认返回的序列号就是这台仪器)→ DQ_Open_Tray → DQ_Close_Tray(看托盘真的能开能关)→(可选)装板跑一次完整实验 → DQ_Release_Access。如果每一条都返回 0、25、50 这一类正常状态码，API 通路就验证好了。
• 再用真实驱动跑一遍 · 把客户脚本，或者第三方工作站自带的 Lunatic 驱动接上，按同样的顺序再走一遍。如果结果和 API Tester 一致，集成这一侧就可以交付，剩下的工作就是把脚本嵌进自动化调度流程里。
• 系列正文 #01–#06 · 依次讲整合场景、装机、配置、命令、字符串和验证，展开这份指南的每一步；三段字符串的字段定义、状态码表和外形尺寸都在这里。
• 官方 Lunatic API Manual · Rev D,2026-04 发布。19 个命令的完整签名、全部状态码、字段定义、外形图纸都能在这里查到。
• 官方技术支持 · 需要 Unchained Labs 工程师专门支持时，联系 support@unchainedlabs.com。带上 .bin 原始数据文件，工程师可以直接导入 Analysis 软件排查。
• Lunatic IQ/OQ/PV 文档 · GMP 项目验收用。涵盖三阶段验证协议和 21 CFR Part 11 合规材料。中国团队可以协助提供。