Lunatic Client 一次性配置:让脚本能调用仪器

系列指南 · 第 3 篇

Lunatic Client 一次性配置：让脚本能调用仪器

Lunatic 物理装好之后，还没法立刻被脚本调用。要先在 Lunatic & Stunner Client 软件里做一次配置：

• 激活 API License
• 把应用传到仪器
• 告诉仪器把原始数据写到哪个共享目录
• 给仪器分配 IP 地址：DHCP 还是固定 IP
• 把常用空白存进去

这些配置都在同一个 Automation 页面里完成。配完一次，日常运行就不用再开这台 PC。

先认识几个名词

• Automation 页面 — Lunatic & Stunner Client 软件里的一个页面，从左上角的菜单按钮进入。所有跟自动化集成相关的配置(激活码、应用、网络、空白)都集中在这一页。
• API License — 让外部脚本调用 Lunatic 的授权。出厂不带，要单独申请；激活码按仪器序列号生成，绑定到具体一台仪器。
• Applications — Lunatic 的应用，每个对应一种 UV-Vis 测量方法，例如 Protein (Turbidity)、A280、Oligo、RNA quality check 等。Lunatic & Stunner Client 把这些应用传到仪器上，脚本里 application_name 字段就要引用其中一个名字。
• Blank(空白) — 不含待测物的对照样品，通常就是样品所用的缓冲液(PBS、Tris 等)本身。UV/Vis 测量时，用空白吸光度扣除缓冲液本底信号，样品的真实浓度才能算准。
• 网络共享目录 — 仪器和脚本 PC 都能访问的网络文件夹，用 Windows SMB 共享。Lunatic 把每次测量的原始数据(.bin 文件)写到这里，脚本后续从这里读取。
• DHCP / 静态 IP — 仪器拿 IP 地址的两种方式。DHCP 由路由器自动分配，IP 可能变化；静态 IP 手动填地址、子网掩码、网关，IP 从此固定。

Automation 页面的四个区域

用 USB 线把 Lunatic 接到一台装了 Lunatic & Stunner Client 的 PC 上，登录之后，从左上角的菜单按钮进入 Automation 页面。整页分四个区域，上面列的各项配置都在这里完成；应用和空白共用右上同一个区域。

• Activation code — 页面顶部 — 激活 API License。填四段激活码，绿色对勾表示成功。
• Applications & Blanks — 右上 — 把应用和空白传到仪器。Transfer Apps、Transfer Blanks 两个按钮。
• Network Settings — 左下 — 配置 .bin 文件的存储位置。Folder/Domain/User/Password 四个字段。
• DHCP / Static IP — 右下 — 给 Lunatic 分配 IP 地址。DHCP 自动分配，或填一个静态 IP。

顺序约束:激活码要最先填；Manual 软件设置一节给的顺序是先激活 License，再传应用，最后配网络共享目录。配置时 Lunatic 要同时接 USB 线(连这台 PC)和网线(进局域网);配 Network Settings 之前，网线必须先插好。

USB 和 TCP 不能同时启用:配完之后日常运行用 TCP,USB 线就拔掉。Manual §3.1 写明，两路同时开着会出现连接冲突、某些参数无法正确设置；并要求在单机模式和 API 模式之间切换时，把仪器断电重启一次。所以切换时既要拔 USB，也要断电重启。

激活 API License

没有 License,API 这边一条命令都发不出去。激活码按仪器序列号绑定生成，所以申请时记得把序列号一起发过去。较老的系统还要在仪器背面插一个 USB dongle 才能用 License。申请前，先和 Unchained Labs 中国团队确认这台机器是否需要。

Manual Figure 10 — Activation code 区域。两个箭头分别标了激活后绿对勾的位置和 Add Activation Code 按钮。Settings/Info 区域显示这台样机的 TCP port 是 6700(右上角 注明该设置仅在重启仪器后生效)。*

把应用传到仪器

计算结果要用的应用，仪器上默认没有装，所以第一次使用之前要手动传一次。以后每次升级 Lunatic & Stunner Client 软件，也要再传一次。

在 Automation 页面右上的 Applications & Blanks 区域，点 Transfer Apps。Transfer 完成后，仪器侧显示的应用数会和 PC 侧一致，看这个数能确认应用送到了。后面写实验定义字符串时，application_name 字段就要引用这里传过去的某个应用名。

同一区域里还有一个 Transfer Blanks 按钮，留到最后一节专门讲。

Manual Figure 11 — TRANSFER APPS 按钮位置。按钮左侧 58 是 PC 上的应用数，右侧 2 是截图时仪器上的应用数；传完之后两边一致。

配网络共享目录

Lunatic 测完一板之后，会把原始数据写成一个 .bin 文件，文件落在哪里由这一步指定。在 Automation 页面左下的 Network Settings 区域填齐四个字段、点 Save Changes,Lunatic 就会把这套设置存到仪器里。哪一项填错或目录访问不到，会立刻弹窗提示，不用等到第一次取数据才发现。

有两处常见错误。第一,Folder 必须是仪器和脚本 PC 都能访问的网络共享目录，不能用任何一边的本地盘。填一个本地路径(比如 C:/Users/...)的话，Lunatic 会把它当成自己内置 PC 的硬盘，而不是脚本 PC 上的位置。第二,User / Password 不填登录这个软件的账号。这里填 Lunatic 仪器以后访问共享目录时要用的账号。这个账号必须事先在共享端授权、有读写权限。

• Folder — 网络路径，以 \\ 开头，后面接 IP、服务器名或计算机名，例：\\server\share。
• Domain — 通常留空，Windows 一般能自行解析。云域名容易出问题，需要时再单独填。
• User — 任意一个能访问这个共享的账号。建议使用密码不常变的账号，减少后续维护。
• Password — 账号密码。含空格时整段加半角双引号，例："your password"，否则解析可能崩溃。

.bin 文件的用途:脚本要的结果文本都从 DQ_Get_Results 拿，不需要直接读这份 .bin。但 Folder 仍然必须配，因为仪器每次测量都要把 .bin 写到这里。没配好的话，原始数据会丢失，Client 最多只能自动导入最近一次实验。这份 .bin 还有另一个用途：事后用 Lunatic & Stunner Analysis 软件打开看详细图形结果，要靠它；请 Unchained Labs 支持团队帮忙排查，也靠它。

Manual Figure 12 — Network Settings 区域。四个字段填了真实示例：Folder 一段以 \\\\ 开头的网络路径、Domain、User、Password。

网络配置的常见问题

配网络和共享目录时，常见的问题有下面几种。

• 接错网线 — 这一步配置的是 Lunatic 仪器的网络，所以网线要直接插在 Lunatic 背面的网口上。配完想验证通不通，先在 Lunatic & Stunner Client 的 Instrument 菜单里查到仪器 IP，再从脚本 PC 的命令行 ping 一下。
• 内网不允许新建共享 — 不少实验室的内网管控严格，无法临时建网络共享。比较省事的做法是在脚本 PC 上直接共享一个本地文件夹。右键文件夹 → 属性 → 共享标签 → 高级共享，勾上"共享此文件夹"。再把这个共享的读写权限给一个特定账号。完成后，属性页顶部会显示"网络路径":\\计算机名\文件夹名(见下图)。把这串路径原样填到 Lunatic 的 Folder 字段即可。
• 密码里含空格 — 密码本身可以含空格，但要给整段密码加上半角双引号，例 "your password"。不加引号时 Lunatic 解析可能临时崩溃。另外，推荐用一个密码不常变的账号，否则每次改密码都要回这一页重配。
• 没配好就开始测量 — .bin 是测量过程中写出的原始数据。要是网络共享配错了又开始测量，这些原始数据会丢失，只有最近一次实验可能被 Client 自动导入。配置完之后，先跑一板真实数据，确认 .bin 真的写到共享目录里，才算配通。这一步在第 6 篇的湿跑验证里再强调一次。

DHCP 还是固定 IP

Automation 页面右下的 DHCP / Static IP 区域决定 Lunatic 怎么拿 IP 地址。两种方式的差别在 IP 会不会变；IP 一变，脚本配置文件就要跟着改。改完这一项，要重启仪器才生效。

自动

DHCP

由路由器自动分配 IP，不用手动填字段。适合临时调试，或者 IP 偶尔变也不要紧的场景。

• · 配置最简单，即插即用
• · 路由器重启或租期到期后 IP 可能改变
• · IP 变了，脚本配置文件里的 Lunatic 地址要跟着更新

固定

静态 IP

手动指定一个固定 IP，从此不会变。自动化产线上更推荐这种方式，脚本不会因为路由器重启而连不上 Lunatic。

• · 填 IP 地址、子网掩码、默认网关三项(都不能留空)
• · IP 要事先和 IT 协调，避免跟现有设备冲突
• · 配完点 Save Changes;脚本配置文件一次写定，后面不用再改

Manual Figure 13 — DHCP / Static IP 区域。示例选的是 DHCP，下面的 Static IP 三字段灰显待用。

存空白：供以后复用

一块板上，通常既要测样品孔，也要测对应缓冲液的空白孔。

自动化场景里，常用的缓冲液(PBS、HEPES、Tris 等)信号很稳定。每板都留几个孔做空白，既浪费板位也增加操作时间。Lunatic 允许把已经测过的空白结果存到仪器本地。后续实验直接引用这份"空白库"，每板就不用再加空白了。

仪器本地每种 plate type(Lunatic Plate 一份、High Lunatic Plate 一份)各保存 1 个实验文件作为空白库。但这一个文件里可以包含多个 sample group，对应不同种类的空白(比如 PBS 一组、Tris 一组)。每次新的存储会整文件覆盖旧的，所以存之前要确认现有那份不再需要。

Manual Figure 14 — TRANSFER BLANKS 按钮位置，在 TRANSFER APPS 下方。

• 日常用 — 从 Automation 页面手动选 — 点 Transfer Blanks 按钮。弹出的对话框会列出所有满足存储条件、已经测过的空白实验。可以按日期、用户、Plate type、实验名筛选。选中一行，点 Transfer 即可。
• 脚本即时 — 刚跑完就存 — 在脚本里调一次 API 命令 DQ_Store_Blanks(无参数)。这会把刚跑完的实验里的空白存为新的空白库。
• 脚本回溯 — 从早先文件存 — 在脚本里调 DQ_Store_Blanks，并指定一个实验文件名。这样可以把网络共享目录里早先某一板的空白存进去。需要事先确认那个 .bin 文件还在，因为这条命令不会重新跑测量。

Manual Figure 15(Transfer blanks selection screen)— 按上面那个 TRANSFER BLANKS 按钮，弹出这个对话框。对话框列出所有满足存储条件的空白实验。它们按 Date / User / Plate type / Experiment name 四列展示。选中一行点 TRANSFER 即可完成。

不是任何一次空白实验都能存进库里。Lunatic 会先检查下面四条标准，全部通过才允许存。没有全部通过，或指定的实验文件找不到时，会返回 −61 至 −65 中对应的错误码。第 6 篇速查表里另有几条存空白错误码，出在实验引用空白库时。

• 仪器在那次空白测量之后没有做过校准
• 同一空白至少 3 个重复孔，且通过了重复性检查
• 那次空白测量距今不超过 100 天
• 那次空白是在当前这台仪器上测的，不是从别的仪器拷过来的

配置完成后的自查清单

开始写脚本之前，对照检查下面六项。

这些都齐了，Lunatic 这边就准备好接受脚本调用了，可以转到第 4 篇看 19 个 API 命令。

• overview · Automation 页面的四个区域
• license · 激活 API License
• transfer-apps · 把应用传到仪器
• troubleshooting · 网络配置的常见问题
• checklist · 配置完成后的自查清单
• Automation 页面 · Lunatic & Stunner Client 软件里的一个页面，从左上角的菜单按钮进入。所有跟自动化集成相关的配置(激活码、应用、网络、空白)都集中在这一页。
• API License · 让外部脚本调用 Lunatic 的授权。出厂不带，要单独申请；激活码按仪器序列号生成，绑定到具体一台仪器。
• Applications · Lunatic 的应用，每个对应一种 UV-Vis 测量方法，例如 Protein (Turbidity)、A280、Oligo、RNA quality check 等。Lunatic & Stunner Client 把这些应用传到仪器上，脚本里 application_name 字段就要引用其中一个名字。
• Blank(空白) · 不含待测物的对照样品，通常就是样品所用的缓冲液(PBS、Tris 等)本身。UV/Vis 测量时，用空白吸光度扣除缓冲液本底信号，样品的真实浓度才能算准。
• 网络共享目录 · 仪器和脚本 PC 都能访问的网络文件夹，用 Windows SMB 共享。Lunatic 把每次测量的原始数据(.bin 文件)写到这里，脚本后续从这里读取。
• DHCP / 静态 IP · 仪器拿 IP 地址的两种方式。DHCP 由路由器自动分配，IP 可能变化；静态 IP 手动填地址、子网掩码、网关，IP 从此固定。
• Activation code · 页面顶部 · 激活 API License。填四段激活码，绿色对勾表示成功。
• Applications & Blanks · 右上 · 把应用和空白传到仪器。Transfer Apps、Transfer Blanks 两个按钮。
• Network Settings · 左下 · 配置 .bin 文件的存储位置。Folder/Domain/User/Password 四个字段。
• DHCP / Static IP · 右下 · 给 Lunatic 分配 IP 地址。DHCP 自动分配，或填一个静态 IP。
• 提交申请 · 把 S/N 发给 Unchained Labs，等回信里的激活码。
• 填入激活码 · 在 Automation 页面顶部 Activation code 区域，把激活码四段分别填进四个输入框，点 Add Activation Code。
• 看绿色对勾 · 输入框下方出现绿对勾，旁边写 API/DropControl，就代表激活成功。按钮变回灰色不算失败，看对勾就行。同一页 SiLA 那一栏的对勾要不要亮，得另买 SiLA license，跟 API License 是两件事。
• 记下端口 · API 的 TCP 端口在仪器上可配置(* 注明重启后生效),Settings/Info 区域会显示这台仪器的实际值。Manual 文档里 Figure 10 截图为 6700、Appendix 1 示例代码用 6300，实际值以这里显示的为准。这个值写脚本时构造 DropQuant 对象要用。
• Folder · 网络路径，以 \\ 开头，后面接 IP、服务器名或计算机名，例：\\server\share。
• Domain · 通常留空，Windows 一般能自行解析。云域名容易出问题，需要时再单独填。
• User · 任意一个能访问这个共享的账号。建议使用密码不常变的账号，减少后续维护。
• Password · 账号密码。含空格时整段加半角双引号，例："your password"，否则解析可能崩溃。
• 接错网线 · 这一步配置的是 Lunatic 仪器的网络，所以网线要直接插在 Lunatic 背面的网口上。配完想验证通不通，先在 Lunatic & Stunner Client 的 Instrument 菜单里查到仪器 IP，再从脚本 PC 的命令行 ping 一下。
• 内网不允许新建共享 · 不少实验室的内网管控严格，无法临时建网络共享。比较省事的做法是在脚本 PC 上直接共享一个本地文件夹。右键文件夹 → 属性 → 共享标签 → 高级共享，勾上"共享此文件夹"。再把这个共享的读写权限给一个特定账号。完成后，属性页顶部会显示"网络路径":\\计算机名\文件夹名(见下图)。把这串路径原样填到 Lunatic 的 Folder 字段即可。
• 密码里含空格 · 密码本身可以含空格，但要给整段密码加上半角双引号，例 "your password"。不加引号时 Lunatic 解析可能临时崩溃。另外，推荐用一个密码不常变的账号，否则每次改密码都要回这一页重配。
• 没配好就开始测量 · .bin 是测量过程中写出的原始数据。要是网络共享配错了又开始测量，这些原始数据会丢失，只有最近一次实验可能被 Client 自动导入。配置完之后，先跑一板真实数据，确认 .bin 真的写到共享目录里，才算配通。这一步在第 6 篇的湿跑验证里再强调一次。
• 日常用 · 从 Automation 页面手动选 · 点 Transfer Blanks 按钮。弹出的对话框会列出所有满足存储条件、已经测过的空白实验。可以按日期、用户、Plate type、实验名筛选。选中一行，点 Transfer 即可。
• 脚本即时 · 刚跑完就存 · 在脚本里调一次 API 命令 DQ_Store_Blanks(无参数)。这会把刚跑完的实验里的空白存为新的空白库。
• 脚本回溯 · 从早先文件存 · 在脚本里调 DQ_Store_Blanks，并指定一个实验文件名。这样可以把网络共享目录里早先某一板的空白存进去。需要事先确认那个 .bin 文件还在，因为这条命令不会重新跑测量。
• License · Automation 页面顶部出现 "API/DropControl" 绿色对勾。
• 端口与 IP · 记下 TCP 端口(从 Client Settings/Info 区域读；Manual 里出现过 6700 和 6300 两个值)和仪器 IP 地址(在 Instrument 菜单里查)，这两项写脚本时要用。
• 应用 · Transfer Apps 已经点过一次，仪器侧的应用数量和 PC 侧一致。
• 共享路径 · Folder 字段以 \\ 开头，不是 C:/;User / Password 是仪器访问共享时用的账号，在共享端已授权读写；密码含空格的话整段套了双引号。
• IP 模式 · 用 DHCP 就记下当前 IP;用静态 IP 则与 IT 确认地址不冲突，IP / 子网掩码 / 网关三个字段都填齐，改完重启仪器一次。
• 验证 · 用一板真实数据跑一次，确认 .bin 文件确实出现在指定的共享目录里。