open_pub/Uni-Lab-OS

Fork 0

mirror of https://github.com/dptech-corp/Uni-Lab-OS.git synced 2025-12-17 13:01:12 +00:00

Files

LccLink c6c2da69ba frontend_docs

2025-09-26 23:20:22 +08:00

10 KiB

Raw Blame History

Uni-Lab 启动指南

安装完毕后，可以通过 unilab 命令行启动：

Start Uni-Lab Edge server.

options:
  -h, --help            show this help message and exit
  -g GRAPH, --graph GRAPH
                        Physical setup graph file path.
  -c CONTROLLERS, --controllers CONTROLLERS
                        Controllers config file path.
  --registry_path REGISTRY_PATH
                        Path to the registry directory
  --working_dir WORKING_DIR
                        Path to the working directory
  --backend {ros,simple,automancer}
                        Choose the backend to run with: 'ros', 'simple', or 'automancer'.
  --app_bridges APP_BRIDGES [APP_BRIDGES ...]
                        Bridges to connect to. Now support 'websocket' and 'fastapi'.
  --is_slave            Run the backend as slave node (without host privileges).
  --slave_no_host       Skip waiting for host service in slave mode
  --upload_registry     Upload registry information when starting unilab
  --use_remote_resource Use remote resources when starting unilab
  --config CONFIG       Configuration file path, supports .py format Python config files
  --port PORT           Port for web service information page
  --disable_browser     Disable opening information page on startup
  --2d_vis              Enable 2D visualization when starting pylabrobot instance
  --visual {rviz,web,disable}
                        Choose visualization tool: rviz, web, or disable
  --ak AK               Access key for laboratory requests
  --sk SK               Secret key for laboratory requests
  --addr ADDR           Laboratory backend address
  --skip_env_check      Skip environment dependency check on startup
  --complete_registry   Complete registry information

启动流程详解

Uni-Lab 的启动过程分为以下几个阶段：

1. 参数解析阶段

解析命令行参数
处理参数格式转换（支持 dash 和 underscore 格式）

2. 环境检查阶段 (可选)

默认进行环境依赖检查并自动安装必需包
使用 --skip_env_check 可跳过此步骤

3. 配置文件处理阶段

您可以直接跟随 unilabos 的提示进行，无需查阅本节

工作目录设置：
- 如果当前目录以 unilabos_data 结尾，则使用当前目录
- 否则使用 当前目录/unilabos_data 作为工作目录
- 可通过 --working_dir 指定自定义工作目录
配置文件查找顺序：
1. 使用 --config 参数指定的配置文件
2. 在工作目录中查找 local_config.py
3. 首次使用时会引导创建配置文件

4. 服务器地址配置

支持多种后端环境：

--addr test：测试环境 (https://uni-lab.test.bohrium.com/api/v1)
--addr uat：UAT 环境 (https://uni-lab.uat.bohrium.com/api/v1)
--addr local：本地环境 (http://127.0.0.1:48197/api/v1)
自定义地址：直接指定完整 URL

5. 认证配置

必需参数：--ak 和 --sk 必须同时提供
命令行参数优先于配置文件中的设置
未提供认证信息会导致启动失败并提示注册实验室

6. 设备图谱加载

支持两种方式：

本地文件：使用 -g 指定图谱文件（支持 JSON 和 GraphML 格式）
远程资源：使用 --use_remote_resource 从云端获取

7. 注册表构建

构建设备和资源注册表
支持自定义注册表路径 (--registry_path)
可选择补全注册表信息 (--complete_registry)

8. 设备验证和注册

验证设备连接和端点配置
自动注册设备到云端服务

9. 通信桥接配置

WebSocket：实时通信和任务下发
FastAPI：HTTP API 服务和物料更新

10. 可视化和服务启动

可选启动可视化工具 (--visual)
启动 Web 信息服务 (默认端口 8002)
启动后端通信服务

使用配置文件

Uni-Lab 支持使用 Python 格式的配置文件进行系统设置。通过 --config 参数指定配置文件路径：

# 使用配置文件启动
unilab --config path/to/your/config.py

配置文件包含实验室和 WebSocket 连接等设置。有关配置文件的详细信息，请参阅配置指南。

初始化信息来源

启动 Uni-Lab 时，可以选用两种方式之一配置实验室设备：

1. 组态&拓扑图

使用 -g 时，组态&拓扑图应包含实验室所有信息，详见{ref}graph。目前支持 GraphML 和 node-link JSON 两种格式。格式可参照 tests/experiments 下的启动文件。

2. 分别指定控制逻辑

使用 -c 传入控制逻辑配置。

不管使用哪一种初始化方式，设备/物料字典均需包含 class 属性，用于查找注册表信息。默认查找范围都是 Uni-Lab 内部注册表 unilabos/registry/{devices,device_comms,resources}。要添加额外的注册表路径，可以使用 --registry_path 加入 <your-registry-path>/{devices,device_comms,resources}。

通信中间件 `--backend`

目前 Uni-Lab 支持以下通信中间件：

ros (默认)：基于 ROS2 的通信
simple：简化通信模式
automancer：Automancer 兼容模式

端云桥接 `--app_bridges`

目前 Uni-Lab 提供 WebSocket、FastAPI (http) 两种端云通信方式：

WebSocket：负责实时通信和任务下发
FastAPI：负责端对云物料更新和 HTTP API

分布式组网

启动 Uni-Lab 时，加入 --is_slave 将作为从站，不加将作为主站：

主站 (host)：持有物料修改权以及对云端的通信
从站 (slave)：无主机权限，可选择跳过等待主机服务 (--slave_no_host)

局域网内分别启动的 Uni-Lab 主站/从站将自动组网，互相能访问所有设备状态、传感器信息并发送指令。

可视化选项

2D 可视化

使用 --2d_vis 在 PyLabRobot 实例启动时同时启动 2D 可视化。

3D 可视化

通过 --visual 参数选择：

rviz：使用 RViz 进行 3D 可视化
web：使用 Web 界面进行可视化
disable (默认)：禁用可视化

实验室管理

首次使用

如果是首次使用，系统会：

提示前往 https://uni-lab.bohrium.com 注册实验室
引导创建配置文件
设置工作目录

认证设置

--ak：实验室访问密钥
--sk：实验室私钥
两者必须同时提供才能正常启动

完整启动示例

以下是一些常用的启动命令示例：

# 使用组态图启动，上传注册表
unilab --ak your_ak --sk your_sk -g path/to/graph.json --upload_registry

# 使用远程资源启动
unilab --ak your_ak --sk your_sk --use_remote_resource

# 更新注册表
unilab --ak your_ak --sk your_sk --complete_registry

# 启动从站模式
unilab --ak your_ak --sk your_sk --is_slave

# 启用可视化
unilab --ak your_ak --sk your_sk --visual web --2d_vis

# 指定本地信息网页服务端口和禁用自动跳出浏览器
unilab --ak your_ak --sk your_sk --port 8080 --disable_browser

常见问题

1. 认证失败

如果提示 "后续运行必须拥有一个实验室"，请确保：

已在 https://uni-lab.bohrium.com 注册实验室
正确设置了 --ak 和 --sk 参数
配置文件中包含正确的认证信息

2. 配置文件问题

如果配置文件加载失败：

确保配置文件是 .py 格式
检查配置文件语法是否正确
首次使用可让系统自动创建示例配置文件

3. 网络连接问题

如果无法连接到服务器：

检查网络连接
确认服务器地址是否正确
尝试使用不同的环境地址（test、uat、local）

4. 设备图谱问题

如果设备加载失败：

检查图谱文件格式是否正确
验证设备连接和端点配置
确保注册表路径正确

页面操作

1. 启动成功

当您启动成功后，可以看到物料列表，节点模版和组态图如图展示

2. 根据需求创建设备和物料

我们可以做一个简单的案例

在容器1中加入水
通过传输泵将容器1中的水转移到容器2中

2.1 添加所需的设备和物料

仪器设备work_station中的workstation 数量x1
仪器设备virtual_device中的virtual_transfer_pump 数量x1
物料耗材container中的container 数量x2

2.2 将设备和物料根据父子关系进行关联

当我们添加设备时，仪器耗材模块的物料列表也会实时更新
我们需要将设备和物料拖拽到workstation中并在画布上将它们连接起来，就像真实的设备操作一样

3. 创建工作流

进入工作流模块 → 点击"我创建的" → 新建工作流

3.1 新增工作流节点

我们可以进入指定工作流，在空白处右键

选择Laboratory→host_node中的creat_resource
选择Laboratory→workstation中的PumpTransferProtocol

3.2 配置节点参数

根据案例，工作流包含两个步骤：

使用creat_resource在容器中创建水
通过泵传输协议将水传输到另一个容器

我们点击creat_resource卡片上的编辑按钮来配置参数⭐️
class_name ：container
device_id ： workstation
liquid_input_slot ： 0或-1均可
liquid_type : water
liquid_volume ：根据需求填写即可，默认单位ml，这里举例50
parent ： workstation
res_id ： containe
关联设备名称(原unilabos_device_id) ：这里就填写host_node
配置完成后点击底部保存按钮

我们点击PumpTransferProtocol卡片上的编辑按钮来配置参数⭐️
event ： transfer_liquid
from_vessel ： water
to_vessel ： container1
volume ：根据需求填写即可，默认单位ml，这里举例50
关联设备名称(原unilabos_device_id) ：这里就填写workstation
配置完成后点击底部保存按钮

3.3 运行工作流

连接两个节点卡片
点击底部保存按钮
点击运行按钮执行工作流

运行监控

运行状态和消息实时显示在底部控制台
如有报错，可点击查看详细信息

结果验证

工作流完成后，返回仪器耗材模块：

点击 container1卡片查看详情
确认其中包含参数指定的水和容量

10 KiB Raw Blame History Unescape Escape