# Uni-Lab-OS 最佳实践指南 ## 关于本指南 本指南将引导您从零开始完成 Uni-Lab-OS 实验室系统的完整搭建，从环境安装到高级设备开发。无论您是初次接触 Uni-Lab-OS 的用户，还是希望深入定制开发的开发者，都能在本指南中找到清晰的步骤和实用建议。 ### 适用对象 - **实验室管理员**：负责实验室系统部署和维护 - **实验操作人员**：日常使用系统进行实验操作 - **设备开发者**：为实验室添加自定义设备和功能 - **系统集成商**：集成多个实验室系统 ### 完整流程概览 ``` 环境准备 → 创建实验室账号 → 系统启动 → 上传注册表 ↓ 在线创建设备图 → 测试系统运行 → 运行工作流 ↓ 多节点部署（可选）→ 自定义设备开发 → 复杂工作站搭建 ``` --- ## 第一部分：快速上手 ### 1. 环境准备（主机 Host） #### 1.1 安装 Uni-Lab-OS 详细的安装步骤请参考 [安装指南](installation.md)。 **关键步骤：** ```bash # 1. 安装 Mamba（如果尚未安装） # 下载 Miniforge: https://github.com/conda-forge/miniforge/releases # 2. 创建 Conda 环境 mamba create -n unilab python=3.11.11 # 3. 激活环境 mamba activate unilab # 4. 安装 Uni-Lab-OS mamba install uni-lab::unilabos -c robostack-staging -c conda-forge ``` #### 1.2 验证安装 ```bash # 检查 unilabos 是否安装成功 python -c "import unilabos; print(unilabos.__version__)" # 验证 ROS 消息包 python -c "from unilabos_msgs.msg import Resource; print('ROS msgs OK')" ``` 如果两条命令都正常输出，说明安装成功。 --- ### 2. 创建您的第一个实验室 #### 2.1 注册实验室账号 1. 访问 [https://uni-lab.bohrium.com](https://uni-lab.bohrium.com) 2. 注册账号并登录 3. 创建新实验室 #### 2.2 获取 Access Key 和 Secret Key 1. 在实验室管理界面，找到"密钥管理" 2. 创建新的 AK/SK 密钥对 3. **妥善保管这些密钥**（类似于密码，不要泄露） ![复制 AK/SK](image/copy_aksk.gif) **重要提示：** - AK (Access Key)：实验室的唯一标识 - SK (Secret Key)：实验室的访问密码 - 这两个密钥在后续启动命令中都需要使用 #### 2.3 首次启动配置 首次启动时，系统会自动引导您创建配置文件： ```bash # 首次启动 conda activate unilab unilab --ak your_ak --sk your_sk ``` 系统会询问是否创建配置文件，输入 `Y` 确认。配置文件会自动生成在 `./unilabos_data/local_config.py`。 更多配置选项请参考 [配置指南](../advanced_usage/configuration.md)。 --- ### 3. 启动系统 详细的启动参数说明请参考 [启动指南](launch.md)。 #### 3.1 基本启动命令 ```bash conda activate unilab unilab --ak your_ak --sk your_sk -g path/to/graph.json ``` **关键参数说明：** - `--ak`：您的 Access Key（必需） - `--sk`：您的 Secret Key（必需） - `-g`：设备组态图文件路径（必需） #### 3.2 首次启动注意事项 **第一次启动时，如果没有组态图文件：** 由于首次启动需要 `-g` 参数指定组态图，您可以： **方案 1：使用预先创建好的示例组态图（推荐）** Uni-Lab-OS 在安装时已经预置了大量真实的设备图文件示例，无需下载或创建，直接使用 `-g` 参数指定即可： ```bash # 使用简单的工作台示例（推荐新手） unilab --ak your_ak --sk your_sk -g test/experiments/workshop.json # 使用 PRCXI 液体处理工作站示例 unilab --ak your_ak --sk your_sk -g test/experiments/prcxi_9300.json # 使用格林纳德反应工作站示例（有机合成） unilab --ak your_ak --sk your_sk -g test/experiments/Grignard_flow_batchreact_single_pumpvalve.json # 使用 Bioyond 配液站示例 unilab --ak your_ak --sk your_sk -g test/experiments/dispensing_station_bioyond.json # 使用 HPLC 分析系统示例 unilab --ak your_ak --sk your_sk -g test/experiments/HPLC.json # 使用空设备配置（最小化配置） unilab --ak your_ak --sk your_sk -g test/experiments/empty_devices.json ``` **更多可用示例**：系统预置了 40+ 个组态图文件，涵盖液体处理、有机合成、分析检测等多个领域。完整列表请查看 `unilabos/test/experiments/` 目录。 **方案 2：创建一个空的组态图** 如果您想从零开始配置，可以创建一个简单的主机节点配置： ```bash # 创建 example_empty.json cat > example_empty.json << 'EOF' { "nodes": [], "links": [] } EOF # 使用该配置启动 unilab --ak your_ak --sk your_sk -g example_empty.json ``` > **提示**：详细的组态图文件编写指南，请参考 [设备图文件说明](graph_files.md)。 **启动成功标志：** - 终端显示 `[Host Node] Host node initialized.` - 自动打开浏览器，显示 Web 管理界面 - 地址：`http://localhost:8002` #### 3.3 常用启动选项 ```bash # 禁用自动打开浏览器 unilab --ak your_ak --sk your_sk -g graph.json --disable_browser # 使用不同端口 unilab --ak your_ak --sk your_sk -g graph.json --port 8080 # 测试环境 unilab --addr test --ak your_ak --sk your_sk -g graph.json # 跳过环境检查（加快启动） unilab --ak your_ak --sk your_sk -g graph.json --skip_env_check ``` --- ### 4. 上传注册表（一次性操作） #### 4.1 什么是注册表上传？ 注册表包含您的设备和物料的完整定义。上传到云端后，在线界面才能识别和使用这些设备。 #### 4.2 何时需要上传？ **必须上传的情况：** - 首次启动实验室 - 添加了新的设备类型 - 修改了设备的注册表定义 #### 4.3 如何上传注册表 ```bash unilab --ak your_ak --sk your_sk -g graph.json --upload_registry ``` **性能影响说明：** - 上传注册表会增加启动时间（通常 5-15 秒） - 上传时间取决于： - 设备和物料的数量 - 网络速度 - 建议：开发调试时首次上传，后续本地测试可省略 **验证上传成功：** 在 Web 界面的"仪器设备"或"物料耗材"模块中，应该能看到您的设备和物料列表。 --- ### 5. 在线创建您的第一个设备图 #### 5.1 使用预设组态图（推荐新手） Uni-Lab-OS 在安装时已经包含了大量真实的设备图文件，位于 `unilabos/test/experiments/` 目录，涵盖： - 液体处理：PRCXI、Biomek 等自动化移液工作站 - 有机合成：格林纳德反应、流动化学等工作站 - 分析检测：HPLC、光谱仪等分析仪器 - 生物实验：Bioyond 配液站、反应站等 - 协议测试：各种实验协议的测试工作站 - 虚拟设备：用于开发调试的 mock 设备 **常用示例组态图：** | 组态图文件 | 说明 | 适合场景 | | ------------------------------------------------ | -------------------- | -------------------- | | `workshop.json` | 综合工作台 | 新手入门推荐 | | `empty_devices.json` | 空设备配置 | 最小化配置，快速启动 | | `prcxi_9300.json` | PRCXI 液体处理工作站 | 液体处理自动化 | | `Grignard_flow_batchreact_single_pumpvalve.json` | 格林纳德反应工作站 | 有机合成流动化学 | | `dispensing_station_bioyond.json` | Bioyond 配液站 | 生物样品配液 | | `reaction_station_bioyond.json` | Bioyond 反应站 | 生物化学反应 | | `HPLC.json` | HPLC 分析系统 | 色谱分析 | | `plr_test.json` | PyLabRobot 测试 | PyLabRobot 集成测试 | | `mock_devices/mock_all.json` | 完整虚拟设备集 | 开发调试，离线测试 | **使用方法：** ```bash # 使用简单工作台（推荐新手第一次启动） unilab --ak your_ak --sk your_sk -g test/experiments/workshop.json # 使用 PRCXI 液体处理工作站 unilab --ak your_ak --sk your_sk -g test/experiments/prcxi_9300.json # 使用格林纳德反应工作站（有机合成） unilab --ak your_ak --sk your_sk -g test/experiments/Grignard_flow_batchreact_single_pumpvalve.json # 使用虚拟设备（无需真实硬件，用于学习和测试） unilab --ak your_ak --sk your_sk -g test/experiments/mock_devices/mock_all.json ``` **注意**：所有组态图文件都是真实项目中使用的配置，可以直接学习和参考。完整文件列表请查看 `unilabos/test/experiments/` 目录。 > 关于设备图文件的结构、字段定义、格式兼容性等完整指南，请参考 [设备图文件说明](graph_files.md)。 #### 5.2 访问 Web 界面 启动系统后，访问[https://uni-lab.bohrium.com](https://uni-lab.bohrium.com) #### 5.3 添加设备和物料 进入"仪器耗材"模块： **示例场景：** 创建一个简单的液体转移实验 1. **添加工作站（必需）：** - 在"仪器设备"中找到 `work_station` - 添加 `workstation` x1 2. **添加虚拟转移泵：** - 在"仪器设备"中找到 `virtual_device` - 添加 `virtual_transfer_pump` x1 3. **添加容器：** - 在"物料耗材"中找到 `container` - 添加 `container` x2 ![物料列表](image/material.png) #### 5.4 建立设备连接关系 将设备和物料拖拽到画布上，建立父子关系： 1. 将两个 `container` 拖拽到 `workstation` 中 2. 将 `virtual_transfer_pump` 拖拽到 `workstation` 中 3. 在画布上连接它们（模拟真实的物理连接） ![设备连接](image/links.png) **连接规则：** - 所有设备和物料都必须有父节点（除了顶层工作站） - 连接关系反映真实的物理布局 - 连接后才能在工作流中使用 #### 5.5 保存组态图 1. 点击"保存"按钮 2. 系统会生成 JSON 格式的组态图 3. 可以下载保存为本地文件，下次使用 `-g` 参数启动 --- ### 6. 测试实验室运行状态 在运行实际工作流之前，建议先测试系统是否正常运行。 #### 6.1 使用 host_node 的 test_latency `test_latency` 是 host_node 提供的测试方法，用于： - 测试网络延迟 - 校准时间误差 - 验证系统响应 **通过 Web 界面测试：** 1. 在 Web 界面找到"工作流"模块 2. 新建空白工作流 3. 右键画布空白处，找到 `laboratory` -> `host_node` 在动作列表中找到 `test_latency` 4. 设置"关联设备名称"为 `host_node` ![选择 host_node](image/test_latency_select_device.png) 5. 点击保存，然后运行工作流 ![运行测试](image/test_latency_running.png) 6. 在控制台查看执行结果，点击查看返回值 ![查看测试结果](image/test_latency_result.png) **测试结果解读：** 系统会进行 5 次 ping-pong 测试，返回 JSON 格式的结果，包含以下关键指标： - **avg_rtt_ms**：平均往返延迟（毫秒），正常应在几十到几百毫秒 - **avg_time_diff_ms**：主机与云端的平均时间差（毫秒） - **max_time_error_ms**：最大时间误差（毫秒） - **raw_delay_ms**：原始延迟测量值（毫秒） - **task_delay_ms**：任务处理延迟（毫秒） - **test_count**：测试次数 - **status**：测试状态（success 表示成功） **实际返回结果示例：** ```json { "error": "", "return_value": { "avg_rtt_ms": 49.64, "avg_time_diff_ms": 3872.43, "max_time_error_ms": 3885.34, "raw_delay_ms": 3900.24, "status": "success", "task_delay_ms": 27.8, "test_count": 5 }, "suc": true } ``` **结果评估：** - `avg_rtt_ms < 100ms`：网络连接良好 - `avg_rtt_ms 100-500ms`：网络可用，略有延迟 - `avg_rtt_ms > 500ms`：网络延迟较高，建议检查网络配置 - `status: "success"`：测试通过 --- ### 7. 运行您的第一个工作流 现在系统已经正常运行，让我们通过一个完整的案例来创建并执行第一个工作流。 #### 7.1 工作流场景 我们将实现一个简单的液体转移实验： 1. 在容器 1 中加入水 2. 通过传输泵将容器 1 中的水转移到容器 2 #### 7.2 添加所需的设备和物料 在创建工作流之前，我们需要先在"仪器耗材"模块中添加必要的设备和物料。 **所需设备和物料清单：** - 仪器设备 `work_station` 中的 `workstation` 数量 x1 - 仪器设备 `virtual_device` 中的 `virtual_transfer_pump` 数量 x1 - 物料耗材 `container` 中的 `container` 数量 x2 **操作步骤：** 1. 访问 Web 界面，进入"仪器耗材"模块 2. 在"仪器设备"区域找到并添加上述设备 3. 在"物料耗材"区域找到并添加容器 ![物料列表](image/material.png) #### 7.3 建立设备和物料的关联关系 当我们添加设备时，仪器耗材模块的物料列表会实时更新。我们需要将设备和物料拖拽到 workstation 中并在画布上将它们连接起来，就像真实的设备操作一样。 **操作步骤：** 1. 将两个 `container` 拖拽到 `workstation` 中 2. 将 `virtual_transfer_pump` 拖拽到 `workstation` 中 3. 在画布上连接它们（建立父子关系） ![设备连接](image/links.png) **连接规则：** - 所有设备和物料都必须有父节点（除了顶层工作站） - 连接关系反映真实的物理布局 - 连接后才能在工作流中使用 #### 7.4 创建工作流 1. 进入"工作流"模块 2. 点击"我创建的" 3. 点击"新建工作流" ![新建工作流](image/new.png) #### 7.5 新增工作流节点 我们可以进入指定工作流，在空白处右键，添加以下节点： - 选择 **Laboratory → host_node** 中的 `creat_resource` - 选择 **Laboratory → workstation** 中的 `PumpTransferProtocol` ![创建工作流](image/creatworkfollow.gif) #### 7.6 配置节点参数 根据案例，工作流包含两个步骤： 1. 使用 `creat_resource` 在容器中创建水 2. 通过泵传输协议将水传输到另一个容器 **配置 creat_resource 节点：** 点击 `creat_resource` 卡片上的编辑按钮，配置参数： ``` class_name: container device_id: workstation liquid_input_slot: 0 或 -1 均可 liquid_type: water liquid_volume: 50（根据需求填写，默认单位 ml，这里举例 50） parent: workstation res_id: container 关联设备名称(原 unilabos_device_id): host_node ``` 配置完成后点击底部保存按钮。 **配置 PumpTransferProtocol 节点：** 点击 `PumpTransferProtocol` 卡片上的编辑按钮，配置参数： ``` event: transfer_liquid from_vessel: water to_vessel: container1 volume: 50（根据需求填写，默认单位 ml，这里举例 50） 关联设备名称(原 unilabos_device_id): workstation ``` 配置完成后点击底部保存按钮。 #### 7.7 运行工作流 1. 连接两个节点卡片（creat_resource → PumpTransferProtocol） 2. 点击底部保存按钮 3. 点击运行按钮执行工作流 ![连接并运行](image/linksandrun.png) #### 7.8 运行监控 - 运行状态和消息实时显示在底部控制台 - 如有报错，可点击查看详细信息 - 查看日志文件：`unilabos_data/logs/unilab.log` #### 7.9 结果验证 工作流完成后，返回"仪器耗材"模块： 1. 点击 `container1` 卡片查看详情 2. 确认其中包含参数指定的水和容量（50ml 的水） 至此，您已经成功运行了第一个工作流。 --- ## 第二部分：进阶部署 ### 8. 多节点部署（Slave 模式） 详细的组网部署和主从模式配置请参考 [组网部署与主从模式配置](../developer_guide/networking_overview.md)。 #### 8.1 主从模式概述 **适用场景：** - 设备物理位置分散在不同房间 - 需要独立的故障隔离域 - 逐步扩展实验室规模 - 分布式实验操作 **架构：** ``` 主节点（Host） ├── 本地设备A ├── 本地设备B └── ROS2 通信 ←→ 从节点（Slave） ├── 远程设备C └── 远程设备D ``` #### 8.2 准备工作 **主节点准备：** 1. 确保主节点已正常启动 2. 记录主节点的 IP 地址 3. 确保网络互通（同一局域网或 VPN） **网络要求：** - 主从节点在同一局域网 - 可以互相 ping 通 - 确保 ROS2 通信端口畅通 **验证网络连通性：** 在配置完成后，使用 ROS2 自带的 demo 节点来验证跨节点通信是否正常： **在主节点机器上**（激活 unilab 环境后）： ```bash # 终端1：启动 talker ros2 run demo_nodes_cpp talker # 终端2：启动 listener ros2 run demo_nodes_cpp listener ``` **在从节点机器上**（激活 unilab 环境后）： ```bash # 终端1：启动 talker ros2 run demo_nodes_cpp talker # 终端2：启动 listener ros2 run demo_nodes_cpp listener ``` **注意**：必须在两台机器上**互相启动** talker 和 listener，否则可能出现只能收不能发的单向通信问题。 **预期结果：** - 每台机器的 listener 应该能同时接收到本地和远程 talker 发送的消息 - 如果只能看到本地消息，说明网络配置有问题 - 如果两台机器都能互相收发消息，则组网配置正确 **如果验证失败，尝试关闭防火墙：** 为了确保 ROS2 DDS 通信正常，建议直接关闭防火墙，而不是配置特定端口。ROS2 使用动态端口范围，配置特定端口可能导致通信问题。 **Linux：** ```bash # 关闭防火墙 sudo ufw disable # 或者临时停止防火墙 sudo systemctl stop ufw ``` **Windows：** ```powershell # 在 Windows 安全中心关闭防火墙 # 控制面板 -> 系统和安全 -> Windows Defender 防火墙 -> 启用或关闭 Windows Defender 防火墙 ``` #### 8.3 启动主节点 ```bash # 在主机（Host）上启动 conda activate unilab unilab --ak your_ak --sk your_sk -g host.json --upload_registry ``` **主节点职责：** - 与云端通信 - 管理全局资源 - 协调所有节点 #### 8.4 启动从节点 在另一台机器上： ```bash # 在从机（Slave）上启动 conda activate unilab unilab --ak your_ak --sk your_sk -g slave.json --is_slave ``` **从节点职责：** - 管理本地设备 - 向主节点注册 - 执行分配的任务 - 不直接与云端通信 **重要：** 从节点使用相同的 AK/SK，因为它们属于同一个实验室。 #### 8.5 判断连接成功 **方法 1：检查 ROS2 节点列表** 在任一节点上运行： ```bash ros2 node list ``` 应该看到来自两个节点的设备： ``` /devices/host_node /devices/workstation /devices/liquid_handler_1 # 从节点的设备 ``` **方法 2：查看主节点设备列表** 在主节点的 Web 界面： 1. 进入"仪器耗材"模块 2. 查看设备列表 3. 从节点的设备应显示为"在线"状态 4. 设备卡片上会显示来源机器名称 **方法 3：查看日志** 主节点日志会显示： ``` [Host Node] Node info update request received [Host Node] Slave node registered: liquid_handler_1 from Machine_B ``` 从节点日志会显示： ``` Slave node info updated. Resource tree synchronized with host. ``` #### 8.6 注册机制说明 从节点启动时会自动向主节点注册： **注册流程（代码逻辑）：** 1. **从节点启动**（`base_device_node.py` 的 `register_device` 方法）： ```python # 检测到非 Host 模式 if not BasicConfig.is_host_mode: # 创建服务客户端 sclient = self.create_client(SerialCommand, "/node_info_update") # 发送注册信息 self.send_slave_node_info(sclient) ``` 2. **发送注册信息**（`main_slave_run.py`）： ```python request.command = json.dumps({ "machine_name": BasicConfig.machine_name, "type": "slave", "devices_config": devices_config.dump(), "registry_config": registry_config, }) ``` 3. **主节点接收**（`host_node.py` 的 `_node_info_update_callback` 方法）： ```python def _node_info_update_callback(self, request, response): info = json.loads(request.command) machine_name = info["machine_name"] edge_device_id = info["edge_device_id"] # 记录设备来源机器 self.device_machine_names[edge_device_id] = machine_name ``` **关键点：** - 注册是自动的，无需手动配置 - 主节点会记录每个设备来自哪台机器 - 从节点需要等待主节点的服务可用 #### 8.7 常见问题 **问题 1：从节点启动卡住** ``` Waiting for host service... ``` **解决方案：** - 检查主节点是否已启动 - 验证网络连通性 - 使用 `--slave_no_host` 参数跳过等待（仅用于测试） **问题 2：节点看不到彼此** **解决方案：** - 确保在同一网络 - 关闭防火墙 - 设置相同的 `ROS_DOMAIN_ID`（可选） **问题 3：注册失败** **解决方案：** - 检查 AK/SK 是否正确 - 查看主节点日志 - 重启从节点 --- ## 第三部分：自定义开发 ### 9. 创建您的第一个自定义设备 详细的设备驱动编写指南请参考 [添加设备驱动](../developer_guide/add_device.md)。 #### 9.1 为什么需要自定义设备？ Uni-Lab-OS 内置了常见设备，但您的实验室可能有特殊设备需要集成： - 自研仪器 - 定制化改造的商业设备 - 特殊的实验流程 - 第三方设备集成 #### 9.2 创建 Python 包 为了方便开发和管理，建议为您的实验室创建独立的 Python 包。 **包结构：** ``` my_lab_devices/ ├── setup.py ├── README.md ├── my_lab_devices/ │ ├── __init__.py │ ├── devices/ │ │ ├── __init__.py │ │ ├── my_pump.py │ │ └── my_sensor.py │ └── registry/ │ ├── devices/ │ │ ├── my_pump.yaml │ │ └── my_sensor.yaml │ └── resources/ │ └── my_container.yaml ``` **创建步骤：** ```bash # 1. 创建包目录 mkdir -p my_lab_devices/my_lab_devices/devices mkdir -p my_lab_devices/my_lab_devices/registry/devices mkdir -p my_lab_devices/my_lab_devices/registry/resources # 2. 创建 __init__.py touch my_lab_devices/my_lab_devices/__init__.py touch my_lab_devices/my_lab_devices/devices/__init__.py ``` #### 9.3 创建 setup.py ```python # my_lab_devices/setup.py from setuptools import setup, find_packages setup( name="my_lab_devices", version="0.1.0", description="My Laboratory Custom Devices", author="Your Name", author_email="your.email@example.com", packages=find_packages(), install_requires=[ "unilabos", # 依赖 Uni-Lab-OS # 添加其他依赖 # "pyserial", # "requests", ], python_requires=">=3.11", # 包含注册表文件 package_data={ "my_lab_devices": [ "registry/devices/*.yaml", "registry/resources/*.yaml", ], }, ) ``` #### 9.4 开发安装 使用 `-e` 参数进行可编辑安装，这样代码修改后立即生效： ```bash cd my_lab_devices pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple ``` **优势：** - 代码修改实时生效，无需重新安装 - 方便调试和测试 - 支持版本控制（git） #### 9.5 编写设备驱动 创建设备驱动文件： ```python # my_lab_devices/my_lab_devices/devices/my_pump.py from typing import Dict, Any from unilabos.registry.placeholder_type import ResourceSlot class MyPump: """自定义注射泵驱动 支持功能： - 注射液体 - 抽取液体 - 速率控制 """ def __init__(self, config: Dict[str, Any]): """初始化设备 Args: config: 配置字典，包含端口、波特率等 """ self.port = config.get('port', 'COM1') self.baudrate = config.get('baudrate', 9600) self._status = "idle" self._current_volume = 0.0 # 初始化串口连接 # self.serial = serial.Serial(self.port, self.baudrate) print(f"MyPump initialized on {self.port}") @property def status(self) -> str: """设备状态""" return self._status @property def current_volume(self) -> float: """当前注射器内液体体积（ml）""" return self._current_volume def infuse( self, target: ResourceSlot, volume: float, rate: float = 1.0 ) -> Dict[str, Any]: """注射液体到目标容器 Args: target: 目标容器（前端显示资源选择器） volume: 注射体积（ml） rate: 注射速率（ml/min） Returns: 执行结果 """ self._status = "infusing" print(f"Infusing {volume}ml to {target.name} at {rate}ml/min") # 发送命令到硬件 # self.serial.write(f"INF {volume} {rate}\r\n".encode()) # 模拟执行 import time time.sleep(volume / rate * 60) # 模拟注射时间 self._current_volume -= volume self._status = "idle" return { "success": True, "volume_infused": volume, "target": target.id, "message": f"Successfully infused {volume}ml" } def withdraw( self, source: ResourceSlot, volume: float, rate: float = 1.0 ) -> Dict[str, Any]: """从源容器抽取液体 Args: source: 源容器（前端显示资源选择器） volume: 抽取体积（ml） rate: 抽取速率（ml/min） Returns: 执行结果 """ self._status = "withdrawing" print(f"Withdrawing {volume}ml from {source.name} at {rate}ml/min") # 发送命令到硬件 # self.serial.write(f"WDR {volume} {rate}\r\n".encode()) # 模拟执行 import time time.sleep(volume / rate * 60) self._current_volume += volume self._status = "idle" return { "success": True, "volume_withdrawn": volume, "source": source.id, "message": f"Successfully withdrawn {volume}ml" } def set_rate(self, rate: float) -> Dict[str, Any]: """设置流速 Args: rate: 流速（ml/min） """ print(f"Setting rate to {rate}ml/min") # self.serial.write(f"RAT {rate}\r\n".encode()) return { "success": True, "rate": rate, "message": f"Rate set to {rate}ml/min" } ``` **关键点：** - **类型注解**：使用 `ResourceSlot` 等特殊类型 - **@property**：状态属性会自动广播 - **返回 Dict**：所有动作方法返回字典类型 - **文档字符串**：详细说明参数和功能 #### 9.6 测试设备驱动 创建简单的测试脚本： ```python # test_my_pump.py from my_lab_devices.devices.my_pump import MyPump # 创建设备实例 config = { "port": "COM1", "baudrate": 9600 } pump = MyPump(config) # 测试状态属性 print(f"Status: {pump.status}") print(f"Current volume: {pump.current_volume}ml") # 模拟注射（不使用 ResourceSlot） class MockResource: id = "test_container" name = "测试容器" result = pump.infuse(MockResource(), volume=5.0, rate=2.0) print(f"Result: {result}") ``` 运行测试： ```bash python test_my_pump.py ``` --- ### 10. 生成和完善设备注册表 注册表（Registry）是 Uni-Lab-OS 的核心配置文件，定义了设备的动作、状态、参数等信息。系统提供了自动生成功能，帮助您快速完成基础配置。 > 完整的注册表编写、字段说明、高级配置等内容，请参考 [添加设备注册表](../developer_guide/add_registry.md)。 #### 10.1 注册表目录结构 Uni-Lab-OS 使用三类注册表： ``` registry/ ├── devices/ # 设备注册表（仪器设备，如泵、加热器、机械臂等） ├── device_comms/ # 通信驱动注册表（如 Modbus、OPC UA） └── resources/ # 物料注册表（耗材、容器，如孔板、试管、试剂等） ``` #### 10.2 生成注册表（两种方式） **方式 1：使用 Web 界面注册表编辑器（推荐）** 1. 访问 Web 界面，进入"注册表编辑器" 2. 上传您的 Python 设备驱动文件 3. 点击"分析文件"，系统自动生成注册表 4. 填写描述、图标等元数据 5. 下载生成的 YAML 文件到您的注册表目录 **方式 2：使用 `--complete_registry` 参数（命令行）** ```bash unilab --ak your_ak --sk your_sk -g graph.json \ --registry_path ./my_lab_devices/registry \ --complete_registry ``` 系统会自动： - 扫描 Python 设备类 - 分析方法签名和类型注解 - 识别 `ResourceSlot`、`DeviceSlot` 等特殊类型 - 生成完整的 YAML 注册表文件 #### 10.3 生成的注册表示例 自动生成的注册表大致如下（已简化）： ```yaml my_pump: class: module: my_lab_devices.devices.my_pump:MyPump type: python status_types: # 自动提取的状态 status: str current_volume: float action_value_mappings: # 自动生成的动作 infuse: type: UniLabJsonCommand goal: target: target volume: volume placeholder_keys: target: unilabos_resources # 自动识别 ResourceSlot result: success: success description: '自定义注射泵驱动' version: '1.0.0' ``` 系统会自动识别特殊类型并生成前端选择器： | Python 类型 | 前端效果 | | -------------------- | -------------- | | `ResourceSlot` | 资源单选下拉框 | | `List[ResourceSlot]` | 资源多选下拉框 | | `DeviceSlot` | 设备单选下拉框 | | `List[DeviceSlot]` | 设备多选下拉框 | #### 10.4 使用自定义注册表 启动时指定注册表路径： ```bash unilab --ak your_ak --sk your_sk -g graph.json \ --registry_path ./my_lab_devices/registry \ --upload_registry ``` **支持多个注册表路径**（按顺序查找）： ```bash unilab --ak your_ak --sk your_sk -g graph.json \ --registry_path ./my_lab_devices/registry \ --registry_path ./another_lab/registry ``` #### 10.5 验证注册表 **验证方法：** 1. **查看启动日志**：确认设备被正确加载 2. **访问 Web 界面**："仪器设备"模块中应能看到您的自定义设备 3. **测试动作调用**：在工作流中测试设备动作是否正常 #### 10.6 手动完善注册表（可选） 自动生成的注册表已经可用，但您可以手动添加以下内容来提升用户体验： - **description**：设备详细描述 - **icon**：设备图标（支持 Base64 或 URL） - **category**：设备分类标签（用于前端分组显示） - **handles**：设备连接点定义（用于可视化连接） **示例：** ```yaml my_pump: description: '高精度注射泵，支持 0.001-100 ml/min 流速范围' icon: 'pump_icon.webp' category: - pump - liquid_handling # ... 其他配置 ``` > 关于注册表的高级配置、字段详解、最佳实践等，请参考 [添加设备注册表](../developer_guide/add_registry.md)。 --- ### 11. 创建复杂工作站 详细的工作站架构请参考 [工作站架构](../developer_guide/examples/workstation_architecture.md)。 #### 11.1 什么是复杂工作站？ 复杂工作站是多个设备和物料的集合，协同完成特定实验流程。 **示例场景：** - **液体处理工作站**：移液器 + 孔板 + 试剂槽 + 枪头架 - **有机合成工作站**：反应釜 + 注射泵 + 加热搅拌器 + 冷凝器 - **分析工作站**：色谱仪 + 进样器 + 流动相泵 #### 11.2 设计工作站 **设计原则：** 1. **模块化**：每个设备独立，可单独控制 2. **层次化**：使用父子关系组织设备 3. **标准化**：使用统一的接口和命名 **工作站结构：** ``` Workstation（工作站根节点） ├── Deck（甲板/平台） │ ├── PlateCarrier_1（板位） │ │ └── Plate_96（96孔板） │ ├── PlateCarrier_2 │ │ └── Plate_384（384孔板） │ └── TipRack（枪头架） ├── Pipette_8（8通道移液器） └── WashStation（清洗站） ``` #### 11.3 组合多个设备 在组态图中： 1. 创建工作站根节点（通常是 `workstation`） 2. 添加子设备 3. 建立连接关系 4. 配置每个设备的参数 **JSON 组态示例：** ```json { "nodes": [ { "id": "liquid_handler_ws", "name": "液体处理工作站", "type": "device", "class": "workstation", "config": {} }, { "id": "pipette_8ch", "name": "8通道移液器", "type": "device", "class": "pipette_8_channel", "config": { "volume_range": [0.5, 300] } }, { "id": "plate_carrier_1", "name": "板位1", "type": "resource", "class": "plate_carrier", "config": {} } ], "links": [ { "source": "liquid_handler_ws", "target": "pipette_8ch", "type": "contains" }, { "source": "liquid_handler_ws", "target": "plate_carrier_1", "type": "contains" } ] } ``` #### 11.4 设计工作流程 **复杂工作站的工作流特点：** - 多步骤协同 - 设备间依赖 - 状态管理 - 错误恢复 **示例：96 孔板液体分配流程** ``` 1. 准备阶段 ├── 检查枪头架 ├── 检查孔板位置 └── 检查试剂体积 2. 执行阶段 ├── 装载枪头 ├── 从试剂槽吸取 ├── 移动到目标孔板 ├── 分配液体 └── 退出枪头 3. 清理阶段 ├── 清洗移液器 └── 复位到初始位置 ``` **在 Uni-Lab 中实现：** 1. 创建工作流 2. 添加各步骤节点 3. 配置每个节点的设备和参数 4. 连接节点形成流程 5. 添加错误处理分支 #### 11.5 通信共享机制 在复杂工作站中，多个设备可能需要共享同一个通信端口（如串口、PLC），但大多数通信端口只能被一个实例占用。通信共享机制解决了这个问题，允许灵活控制连接到同一通信端口的多个设备。 ##### 11.5.1 应用场景 **典型场景：** - **多泵阀共享 PLC 串口**：所有泵阀通过同一个 PLC 控制，泵阀数量可灵活增减 - **多传感器共享 Modbus**：多个传感器通过同一个 Modbus 设备读取数据 - **多设备共享 TCP/IP**：多台设备共享一个 TCP/IP 通信接口 **解决思路：** 创建一个**通信设备作为代理**，所有需要使用该端口的设备通过代理进行通信，而不是直接访问端口。 ##### 11.5.2 配置步骤 **步骤 1：定义 workstation 并指定 protocol_type** 在组态图中，workstation 的 `config` 需要添加 `protocol_type`（协议类型列表，可为空）： ```json { "id": "simple_station", "name": "简单工作站", "type": "device", "class": "workstation", "parent": null, "config": { "protocol_type": ["PumpTransferProtocol", "CleanProtocol"] }, "children": ["serial_pump", "pump_1", "pump_2", "pump_3"] } ``` > **说明**：`children` 列表中，**通信设备必须排在最前面**（如 `"serial_pump"`），确保它先于其他设备初始化。 **步骤 2：创建通信设备（作为代理）** 在 workstation 的子设备中，**首先定义通信设备**（必须在其他设备之前初始化，因此放到启动 json 靠前的位置）： ```json { "id": "serial_pump", "type": "device", "class": "serial", "parent": "simple_station", "config": { "port": "COM7", "baudrate": 9600 } } ``` **步骤 3：配置使用该通信的设备** 其他设备的 `config` 中指向通信设备（字段名根据设备注册表定义，如 `port` 或 `io_device_port`，他们在驱动中）： ```json { "id": "pump_1", "type": "device", "class": "syringe_pump_with_valve.runze.SY03B-T06", "parent": "simple_station", "config": { "port": "serial_pump", // 直接使用通信设备的设备名，最终能够通过__init__实现self.hardware_interface变量设定为serial_pump的字符串 "address": "1", "max_volume": 25.0 } } ``` > 配置字段的值直接是**通信设备的设备名**（如 `"serial_pump"`），不是完整路径。系统会自动进行变量替换。 **步骤 4：建立通信连接关系** 在组态图的 `links` 中，建立 `communication` 类型的连接： ```json { "links": [ { "source": "pump_1", "target": "serial_pump", "type": "communication", "port": { "serial_pump": "1" // 通信端口号或地址 } }, { "source": "pump_2", "target": "serial_pump", "type": "communication", "port": { "serial_pump": "2" } } ] } ``` > **说明**：`port` 字段中的值是通信设备上的端口号或地址，具体含义取决于通信协议。 ##### 11.5.3 注册表配置 **通信设备的注册表**（例如`device_comms/modbus_ioboard.yaml`）： ```yaml io_snrd: class: module: unilabos.device_comms.SRND_16_IO:SRND_16_IO type: python # hardware_interface.name 对象是实际的通信实例（如 ModbusClient()） # 通过 Python 的 __init__ 方法初始化 hardware_interface: name: modbus_client read: read_io_coil write: write_io_coil description: 'IO Board with 16 IOs via Modbus' ``` **使用通信的设备注册表**（`devices/pump_and_valve.yaml`）： ```yaml syringe_pump_with_valve.runze.SY03B-T06: class: module: unilabos.devices.pump_and_valve.runze_backbone:RunzeSyringePump type: python # hardware_interface.name 初始化时是通信设备的设备名（字符串） # 通过启动 JSON 的 config 传入（如 "port": "serial_pump"） # 系统会自动将字符串替换为实际的通信实例 hardware_interface: name: hardware_interface read: send_command write: send_command action_value_mappings: # 设备的动作定义 solenoid_valve: class: module: unilabos.devices.pump_and_valve.solenoid_valve:SolenoidValve type: python # 使用 io_device_port 字段接收通信设备名 hardware_interface: name: io_device_port # 例如当前电磁阀修改了name，从默认的hardware_interface改成了io_device_port，那么启动json中就应该对__init__中的io_device_port进行赋值 read: read_io_coil write: write_io_coil ``` **关键机制：** | 设备类型 | hardware_interface.name | 初始化方式 | 运行时对象 | | ------------------ | ----------------------- | --------------------------------------------- | ----------------------------------- | | **通信设备** | `modbus_client` 等 | Python `__init__` 中创建实例 | `ModbusClient()`、`serial.Serial()` | | **使用通信的设备** | `hardware_interface` 等 | config 中传入设备名字符串（如 `"io_device"`） | **系统自动替换**为实际通信实例 | **自动替换流程：** 1. 设备初始化时，`self.hardware_interface = "io_device"`（字符串） 2. workstation 检测到 `config` 中有通信设备名 3. 系统自动将 `self.hardware_interface` 替换为 `io_device` 的实际通信实例 4. 设备可以直接调用 `self.hardware_interface.read_io_coil()` 等方法 **完整示例：Modbus IO 板控制多个电磁阀** ```json { "nodes": [ { "id": "WorkStationTestMinimumSystem", "name": "工作站节点", "children": [ "io_device", "Product1_Solenoid_Valve", "Water_Solenoid_Valve" ], "parent": null, "type": "device", "class": "workstation", "config": { "protocol_type": [] } }, { "id": "io_device", "class": "io_snrd", // 通信设备类型 "name": "io_device", "config": { "address": "192.168.1.7:23", // Modbus TCP 地址 "slave_id": "1" }, "parent": "WorkStationTestMinimumSystem", "type": "device" }, { "id": "Product1_Solenoid_Valve", "class": "solenoid_valve", "name": "Product1_Solenoid_Valve", "config": { "io_device_port": "io_device" // 通信设备的设备名（字符串） }, "parent": "WorkStationTestMinimumSystem", "type": "device" }, { "id": "Water_Solenoid_Valve", "class": "solenoid_valve", "name": "Water_Solenoid_Valve", "config": { "io_device_port": "io_device" // 同样使用这个通信设备 }, "parent": "WorkStationTestMinimumSystem", "type": "device" } ], "links": [] } ``` **工作原理：** 1. `io_device` 初始化时创建 `ModbusClient("192.168.1.7:23")` 2. 两个电磁阀的 `self.io_device_port` 初始化为字符串 `"io_device"` 3. workstation 自动将 `self.io_device_port` 替换为实际的 `ModbusClient` 实例 4. 电磁阀可以通过 `self.io_device_port.read_io_coil(15)` 或 `write_io_coil(14)` 操作 ##### 11.5.4 验证通信共享 **启动成功标志：** 系统启动时，在日志中查看以下提示信息： ``` 通信代理：为子设备 pump_1 配置通信代理 serial_pump 通信代理：为子设备 pump_2 配置通信代理 serial_pump 通信代理：为子设备 pump_3 配置通信代理 serial_pump ``` 看到此提示说明通信共享配置成功。 **测试步骤：** 1. 启动系统，查看日志确认通信代理配置成功 2. 在 Web 界面中，分别控制 `pump_1`、`pump_2`、`pump_3` 3. 确认所有泵都能正常响应（通过同一个串口） 4. 查看通信设备的状态，确认消息正常传递 --- ### 12. 撰写物料定义 详细的物料编写指南请参考： - [物料构建指南](../developer_guide/examples/materials_construction_guide.md) - [物料教程](../developer_guide/examples/materials_tutorial.md) #### 12.1 物料（Resource）概述 物料是实验中使用的消耗品和容器： - **容器**：孔板、试管、烧杯、反应瓶 - **耗材**：枪头、移液管、过滤器 - **试剂**：溶剂、试剂、样品 #### 12.2 创建自定义物料类型 **场景：** 创建实验室特殊规格的孔板 ```python # my_lab_devices/my_lab_devices/resources/custom_plate.py from pylabrobot.resources import Plate, Well from typing import List class CustomPlate48(Plate): """自定义 48 孔板 规格： - 6行 x 8列 - 孔体积：2ml - 孔间距：18mm """ def __init__(self, name: str): super().__init__( name=name, size_x=127.76, # mm size_y=85.48, # mm size_z=14.35, # mm model="custom_48_wellplate_2000ul" ) # 定义孔位 self._create_wells() def _create_wells(self): """创建 48 个孔位""" rows = "ABCDEF" cols = range(1, 9) well_size_x = 16.0 # mm well_size_y = 16.0 well_depth = 12.0 spacing_x = 18.0 spacing_y = 18.0 for row_idx, row in enumerate(rows): for col in cols: well_name = f"{row}{col}" x = (col - 1) * spacing_x + 10 # 10mm 边距 y = row_idx * spacing_y + 10 well = Well( name=well_name, size_x=well_size_x, size_y=well_size_y, size_z=well_depth, max_volume=2000, # μL ) well.location = (x, y, 0) self.children.append(well) ``` #### 12.3 物料注册表 创建物料注册表： ```yaml # my_lab_devices/my_lab_devices/registry/resources/custom_plate.yaml custom_48_wellplate_2000ul: class: module: my_lab_devices.resources.custom_plate:CustomPlate48 type: python description: '自定义 48 孔板，2ml 孔体积' version: '1.0.0' category: - plate - container # 物料属性 properties: rows: 6 columns: 8 well_count: 48 well_volume: 2000 # μL well_shape: 'round' material: 'polystyrene' # 尺寸信息 dimensions: size_x: 127.76 size_y: 85.48 size_z: 14.35 unit: 'mm' # 兼容性 compatible_with: - 'plate_carrier' - 'thermal_cycler' icon: '' ``` #### 12.4 物料属性定义 **常见属性：** ```yaml properties: # 容量相关 max_volume: 2000 # μL min_volume: 10 # μL dead_volume: 5 # μL（无法吸取的残留体积） # 几何形状 shape: 'round' # round, square, v_bottom diameter: 16.0 # mm depth: 12.0 # mm # 材质 material: 'polystyrene' # 聚苯乙烯 transparency: true # 透明 sterile: false # 无菌 # 温度范围 min_temperature: -80 # °C max_temperature: 121 # °C # 化学兼容性 chemical_compatibility: - 'water' - 'ethanol' - 'dmso' # 条形码 barcode_support: true barcode_type: '1D' ``` #### 12.5 在系统中使用自定义物料 1. **注册物料**： ```bash unilab --ak your_ak --sk your_sk -g graph.json \ --registry_path ./my_lab_devices/my_lab_devices/registry \ --upload_registry ``` 2. **在组态图中添加**： 在 Web 界面的"物料耗材"模块中，找到 `custom_48_wellplate_2000ul`，添加到实验室。 3. **在工作流中使用**： 工作流节点的参数中，涉及容器选择的地方会显示您的自定义物料。 --- ## 第四部分：最佳实践总结 ### 13. 开发流程建议 ``` 需求分析 → 环境搭建 → 原型验证 → 迭代开发 → 测试部署 → 生产运行 ``` **详细步骤：** 1. **需求分析**： - 明确实验流程 - 列出所需设备和物料 - 设计工作流程图 2. **环境搭建**： - 安装 Uni-Lab-OS - 创建实验室账号 - 准备开发工具（IDE、Git） 3. **原型验证**： - 使用虚拟设备测试流程 - 验证工作流逻辑 - 调整参数 4. **迭代开发**： - 实现自定义设备驱动（同时撰写单点函数测试） - 编写注册表 - 单元测试 - 集成测试 5. **测试部署**： - 连接真实硬件 - 空跑测试 - 小规模试验 6. **生产运行**： - 全量部署 - 监控运行状态 - 持续优化 --- ### 14. 进一步学习资源 #### 14.1 官方文档 - **安装指南**：[installation.md](installation.md) - **启动指南**：[launch.md](launch.md) - **配置指南**：[../advanced_usage/configuration.md](../advanced_usage/configuration.md) #### 14.2 开发者文档 - **组网部署与主从模式**：[../developer_guide/networking_overview.md](../developer_guide/networking_overview.md) - **添加设备驱动**：[../developer_guide/add_device.md](../developer_guide/add_device.md) - **老设备驱动开发**：[../developer_guide/add_old_device.md](../developer_guide/add_old_device.md) - **添加动作指令**：[../developer_guide/add_action.md](../developer_guide/add_action.md) - **YAML 注册表编写**：[../developer_guide/add_yaml.md](../developer_guide/add_yaml.md) - **添加设备注册表**：[../developer_guide/add_registry.md](../developer_guide/add_registry.md) - **工作站架构**：[../developer_guide/examples/workstation_architecture.md](../developer_guide/examples/workstation_architecture.md) - **物料构建指南**：[../developer_guide/examples/materials_construction_guide.md](../developer_guide/examples/materials_construction_guide.md) #### 14.3 进阶主题 - **工作目录详解**：[../advanced_usage/working_directory.md](../advanced_usage/working_directory.md) #### 14.4 外部资源 - **ROS 2 文档**：[https://docs.ros.org/en/humble/](https://docs.ros.org/en/humble/) - **PyLabRobot**：[https://github.com/PyLabRobot/pylabrobot](https://github.com/PyLabRobot/pylabrobot) - **Python 类型注解**：[https://docs.python.org/3/library/typing.html](https://docs.python.org/3/library/typing.html) - **YAML 语法**：[https://yaml.org/](https://yaml.org/) #### 14.5 社区支持 - **GitHub Issues**：[https://github.com/dptech-corp/Uni-Lab-OS/issues](https://github.com/dptech-corp/Uni-Lab-OS/issues) - **官方网站**：[https://uni-lab.bohrium.com](https://uni-lab.bohrium.com) --- ## 结语 通过本指南，您应该已经掌握了： - 安装和配置 Uni-Lab-OS 环境 - 创建和管理实验室 - 启动系统并运行工作流 - 部署多节点分布式系统 - 开发自定义设备驱动 - 创建和注册物料定义 - 构建复杂工作站 **下一步建议：** 1. 从简单的工作流开始实践，逐步尝试更复杂的场景 2. 在 GitHub 上提问和分享经验 3. 关注文档更新和新功能发布 4. 为 Uni-Lab-OS 社区贡献您的设备驱动和最佳实践 --- _本指南最后更新：2025-11_ _Uni-Lab-OS 版本：最新稳定版_