Update docs

修改了mix，仿真流程报错问题

.conda/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: unilabos
-  version: 0.10.7
+  version: 0.10.12
 
 source:
   path: ../unilabos

CONTRIBUTORS

@@ -1,15 +1,18 @@
-   156	Xuwznln <18435084+Xuwznln@users.noreply.github.com>
-    39	Junhan Chang <changjh@dp.tech>
-     9	wznln <18435084+Xuwznln@users.noreply.github.com>
-     8	Guangxin Zhang <guangxin.zhang.bio@gmail.com>
+    56	Xuwznln <18435084+Xuwznln@users.noreply.github.com>
+    10	wznln <18435084+Xuwznln@users.noreply.github.com>
+     6	Junhan Chang <changjh@dp.tech>
      5	ZiWei <131428629+ZiWei09@users.noreply.github.com>
+     2	Guangxin Zhang <guangxin.zhang.bio@gmail.com>
      2	Junhan Chang <changjh@pku.edu.cn>
-     2	Xie Qiming <97236197+Andy6M@users.noreply.github.com>
+     2	WenzheG <wenzheguo32@gmail.com>
+     1	Harry Liu <113173203+ALITTLELZ@users.noreply.github.com>
      1	Harvey Que <103566763+Mile-Away@users.noreply.github.com>
      1	Junhan Chang <1700011741@pku.edu.cn>
-     1	LccLink <1951855008@qq.com>
-     1	h840473807 <47357934+h840473807@users.noreply.github.com>
+     1	Xianwei Qi <qxw@stu.pku.edu.cn>
+     1	hh.(SII) <103566763+Mile-Away@users.noreply.github.com>
      1	lixinyu1011 <61094742+lixinyu1011@users.noreply.github.com>
-     1	shiyubo0410 <shiyubo@dp.tech>
+     1	q434343 <73513873+q434343@users.noreply.github.com>
+     1	tt <166512503+tt11142023@users.noreply.github.com>
+     1	xyc <49015816+xiaoyu10031@users.noreply.github.com>
      1	王俊杰 <1800011822@pku.edu.cn>
      1	王俊杰 <43375851+wjjxxx@users.noreply.github.com>

MANIFEST.in

@@ -1,3 +1,4 @@
+recursive-include unilabos/test *
 recursive-include unilabos/registry *.yaml
 recursive-include unilabos/app/web/static *
 recursive-include unilabos/app/web/templates *

README.md

@@ -39,7 +39,9 @@ Uni-Lab-OS recommends using `mamba` for environment management. Choose the appro
 
 ```bash
 # Create new environment
-mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+mamba create -n unilab python=3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```
 
 ## Install Dev Uni-Lab-OS

README_zh.md

@@ -41,7 +41,9 @@ Uni-Lab-OS 建议使用 `mamba` 管理环境。根据您的操作系统选择适
 
 ```bash
 # 创建新环境
-mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+mamba create -n unilab python=3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```
 
 2. 安装开发版 Uni-Lab-OS:

docs/advanced_usage/configuration.md

@@ -0,0 +1,726 @@
+# Uni-Lab 配置指南
+
+本文档详细介绍 Uni-Lab 配置文件的结构、配置项、命令行覆盖和环境变量的使用方法。
+
+## 配置文件概述
+
+Uni-Lab 使用 Python 格式的配置文件（`.py`），默认为 `unilabos_data/local_config.py`。配置文件采用类属性的方式定义各种配置项，比 YAML 或 JSON 提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
+
+## 获取实验室密钥
+
+在配置文件或启动命令中，您需要提供实验室的访问密钥（ak）和私钥（sk）。
+
+**获取方式：**
+
+进入 [Uni-Lab 实验室](https://uni-lab.bohrium.com)，点击左下角的头像，在实验室详情中获取所在实验室的 ak 和 sk：
+
+![copy_aksk.gif](image/copy_aksk.gif)
+
+## 配置文件格式
+
+### 默认配置示例
+
+首次使用时，系统会自动创建一个基础配置文件 `local_config.py`：
+
+```python
+# unilabos的配置文件
+
+class BasicConfig:
+    ak = ""  # 实验室网页给您提供的ak代码
+    sk = ""  # 实验室网页给您提供的sk代码
+
+
+# WebSocket配置，一般无需调整
+class WSConfig:
+    reconnect_interval = 5  # 重连间隔（秒）
+    max_reconnect_attempts = 999  # 最大重连次数
+    ping_interval = 30  # ping间隔（秒）
+```
+
+### 完整配置示例
+
+您可以根据需要添加更多配置选项：
+
+```python
+#!/usr/bin/env python
+# coding=utf-8
+"""Uni-Lab 配置文件"""
+
+# 基础配置
+class BasicConfig:
+    ak = ""  # 实验室访问密钥
+    sk = ""  # 实验室私钥
+    working_dir = ""  # 工作目录（通常自动设置）
+    config_path = ""  # 配置文件路径（自动设置）
+    is_host_mode = True  # 是否为主站模式
+    slave_no_host = False  # 从站模式下是否跳过等待主机服务
+    upload_registry = False  # 是否上传注册表
+    machine_name = "undefined"  # 机器名称（自动获取）
+    vis_2d_enable = False  # 是否启用2D可视化
+    enable_resource_load = True  # 是否启用资源加载
+    communication_protocol = "websocket"  # 通信协议
+    log_level = "DEBUG"  # 日志级别：TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+# WebSocket配置
+class WSConfig:
+    reconnect_interval = 5  # 重连间隔（秒）
+    max_reconnect_attempts = 999  # 最大重连次数
+    ping_interval = 30  # ping间隔（秒）
+
+# HTTP配置
+class HTTPConfig:
+    remote_addr = "https://uni-lab.bohrium.com/api/v1"  # 远程服务器地址
+
+# ROS配置
+class ROSConfig:
+    modules = [
+        "std_msgs.msg",
+        "geometry_msgs.msg",
+        "control_msgs.msg",
+        "control_msgs.action",
+        "nav2_msgs.action",
+        "unilabos_msgs.msg",
+        "unilabos_msgs.action",
+    ]  # 需要加载的ROS模块
+```
+
+## 配置优先级
+
+配置项的生效优先级从高到低为：
+
+1. **命令行参数**：最高优先级
+2. **环境变量**：中等优先级
+3. **配置文件**：基础优先级
+
+这意味着命令行参数会覆盖环境变量和配置文件，环境变量会覆盖配置文件。
+
+## 推荐配置方式
+
+根据参数特性，不同配置项有不同的推荐配置方式：
+
+### 建议通过命令行指定的参数（不需要写入配置文件）
+
+以下参数推荐通过命令行或环境变量指定，**一般不需要在配置文件中配置**：
+
+| 参数              | 命令行参数          | 原因                                 |
+| ----------------- | ------------------- | ------------------------------------ |
+| `ak` / `sk`       | `--ak` / `--sk`     | **安全考虑**：避免敏感信息泄露       |
+| `working_dir`     | `--working_dir`     | **灵活性**：不同环境可能使用不同目录 |
+| `is_host_mode`    | `--is_slave`        | **运行模式**：由启动场景决定，不固定 |
+| `slave_no_host`   | `--slave_no_host`   | **运行模式**：从站特殊配置，按需使用 |
+| `upload_registry` | `--upload_registry` | **临时操作**：仅首次启动或更新时需要 |
+| `vis_2d_enable`   | `--2d_vis`          | **调试功能**：按需临时启用           |
+| `remote_addr`     | `--addr`            | **环境切换**：测试/生产环境快速切换  |
+
+**推荐用法示例：**
+
+```bash
+# 标准启动命令（所有必要参数通过命令行指定）
+unilab --ak your_ak --sk your_sk -g graph.json
+
+# 测试环境
+unilab --addr test --ak your_ak --sk your_sk -g graph.json
+
+# 从站模式
+unilab --is_slave --ak your_ak --sk your_sk
+
+# 首次启动上传注册表
+unilab --ak your_ak --sk your_sk -g graph.json --upload_registry
+```
+
+### 适合在配置文件中配置的参数
+
+以下参数适合在配置文件中配置，通常不会频繁更改：
+
+| 参数                     | 配置类      | 说明                   |
+| ------------------------ | ----------- | ---------------------- |
+| `log_level`              | BasicConfig | 日志级别配置           |
+| `reconnect_interval`     | WSConfig    | WebSocket 重连间隔     |
+| `max_reconnect_attempts` | WSConfig    | WebSocket 最大重连次数 |
+| `ping_interval`          | WSConfig    | WebSocket 心跳间隔     |
+| `modules`                | ROSConfig   | ROS 模块列表           |
+
+**配置文件示例（推荐最小配置）：**
+
+```python
+# unilabos的配置文件
+
+class BasicConfig:
+    log_level = "INFO"  # 生产环境建议 INFO，调试时用 DEBUG
+
+# WebSocket配置，一般保持默认即可
+class WSConfig:
+    reconnect_interval = 5
+    max_reconnect_attempts = 999
+    ping_interval = 30
+```
+
+**注意：** `ak` 和 `sk` 不建议写在配置文件中，始终通过命令行参数或环境变量传递。
+
+## 命令行参数覆盖配置
+
+Uni-Lab 允许通过命令行参数覆盖配置文件中的设置，提供更灵活的配置方式。
+
+### 支持命令行覆盖的配置项
+
+| 配置类        | 配置字段          | 命令行参数          | 说明                             |
+| ------------- | ----------------- | ------------------- | -------------------------------- |
+| `BasicConfig` | `ak`              | `--ak`              | 实验室访问密钥                   |
+| `BasicConfig` | `sk`              | `--sk`              | 实验室私钥                       |
+| `BasicConfig` | `working_dir`     | `--working_dir`     | 工作目录路径                     |
+| `BasicConfig` | `is_host_mode`    | `--is_slave`        | 主站模式（参数为从站模式，取反） |
+| `BasicConfig` | `slave_no_host`   | `--slave_no_host`   | 从站模式下跳过等待主机服务       |
+| `BasicConfig` | `upload_registry` | `--upload_registry` | 启动时上传注册表信息             |
+| `BasicConfig` | `vis_2d_enable`   | `--2d_vis`          | 启用 2D 可视化                   |
+| `HTTPConfig`  | `remote_addr`     | `--addr`            | 远程服务地址                     |
+
+### 特殊命令行参数
+
+除了直接覆盖配置项的参数外，还有一些特殊的命令行参数：
+
+| 参数                | 说明                                 |
+| ------------------- | ------------------------------------ |
+| `--config`          | 指定配置文件路径                     |
+| `--port`            | Web 服务端口（不影响配置文件）       |
+| `--disable_browser` | 禁用自动打开浏览器（不影响配置文件） |
+| `--visual`          | 可视化工具选择（不影响配置文件）     |
+| `--skip_env_check`  | 跳过环境检查（不影响配置文件）       |
+
+### 命令行覆盖使用示例
+
+```bash
+# 通过命令行覆盖认证信息
+unilab --ak "new_access_key" --sk "new_secret_key" -g graph.json
+
+# 覆盖服务器地址
+unilab --ak ak --sk sk --addr "https://custom.server.com/api/v1" -g graph.json
+
+# 启用从站模式并跳过等待主机
+unilab --is_slave --slave_no_host --ak ak --sk sk
+
+# 启用上传注册表和2D可视化
+unilab --upload_registry --2d_vis --ak ak --sk sk -g graph.json
+
+# 组合使用多个覆盖参数
+unilab --ak "key" --sk "secret" --addr "test" --upload_registry --2d_vis -g graph.json
+```
+
+### 预设环境地址
+
+`--addr` 参数支持以下预设值，会自动转换为对应的完整 URL：
+
+- `test` → `https://uni-lab.test.bohrium.com/api/v1`
+- `uat` → `https://uni-lab.uat.bohrium.com/api/v1`
+- `local` → `http://127.0.0.1:48197/api/v1`
+- 其他值 → 直接使用作为完整 URL
+
+## 配置选项详解
+
+### 1. BasicConfig - 基础配置
+
+基础配置包含了系统运行的核心参数：
+
+| 参数                     | 类型 | 默认值        | 说明                                       |
+| ------------------------ | ---- | ------------- | ------------------------------------------ |
+| `ak`                     | str  | `""`          | 实验室访问密钥（必需）                     |
+| `sk`                     | str  | `""`          | 实验室私钥（必需）                         |
+| `working_dir`            | str  | `""`          | 工作目录，通常自动设置                     |
+| `config_path`            | str  | `""`          | 配置文件路径，自动设置                     |
+| `is_host_mode`           | bool | `True`        | 是否为主站模式                             |
+| `slave_no_host`          | bool | `False`       | 从站模式下是否跳过等待主机服务             |
+| `upload_registry`        | bool | `False`       | 启动时是否上传注册表信息                   |
+| `machine_name`           | str  | `"undefined"` | 机器名称，自动从 hostname 获取（不可配置） |
+| `vis_2d_enable`          | bool | `False`       | 是否启用 2D 可视化                         |
+| `enable_resource_load`   | bool | `True`        | 是否启用资源加载                           |
+| `communication_protocol` | str  | `"websocket"` | 通信协议，固定为 websocket                 |
+| `log_level`              | str  | `"DEBUG"`     | 日志级别                                   |
+
+#### 日志级别选项
+
+- `TRACE` - 追踪级别（最详细）
+- `DEBUG` - 调试级别（默认）
+- `INFO` - 信息级别
+- `WARNING` - 警告级别
+- `ERROR` - 错误级别
+- `CRITICAL` - 严重错误级别（最简略）
+
+#### 认证配置（ak / sk）
+
+`ak` 和 `sk` 是必需的认证参数：
+
+1. **获取方式**：在 [Uni-Lab 官网](https://uni-lab.bohrium.com) 注册实验室后获得
+2. **配置方式**：
+   - **命令行参数**：`--ak "your_key" --sk "your_secret"`（最高优先级，推荐）
+   - **环境变量**：`UNILABOS_BASICCONFIG_AK` 和 `UNILABOS_BASICCONFIG_SK`
+   - **配置文件**：在 `BasicConfig` 类中设置（不推荐，安全风险）
+3. **安全注意**：请妥善保管您的密钥信息，不要提交到版本控制
+
+**推荐做法**：
+
+- **开发环境**：使用命令行参数或环境变量
+- **生产环境**：使用环境变量
+- **临时测试**：使用命令行参数
+
+### 2. WSConfig - WebSocket 配置
+
+WebSocket 是 Uni-Lab 的主要通信方式：
+
+| 参数                     | 类型 | 默认值 | 说明               |
+| ------------------------ | ---- | ------ | ------------------ |
+| `reconnect_interval`     | int  | `5`    | 断线重连间隔（秒） |
+| `max_reconnect_attempts` | int  | `999`  | 最大重连次数       |
+| `ping_interval`          | int  | `30`   | 心跳检测间隔（秒） |
+
+### 3. HTTPConfig - HTTP 配置
+
+HTTP 客户端配置用于与云端服务通信：
+
+| 参数          | 类型 | 默认值                                 | 说明         |
+| ------------- | ---- | -------------------------------------- | ------------ |
+| `remote_addr` | str  | `"https://uni-lab.bohrium.com/api/v1"` | 远程服务地址 |
+
+**预设环境地址**：
+
+- 生产环境：`https://uni-lab.bohrium.com/api/v1`（默认）
+- 测试环境：`https://uni-lab.test.bohrium.com/api/v1`
+- UAT 环境：`https://uni-lab.uat.bohrium.com/api/v1`
+- 本地环境：`http://127.0.0.1:48197/api/v1`
+
+### 4. ROSConfig - ROS 配置
+
+配置 ROS 消息转换器需要加载的模块：
+
+| 配置项    | 类型 | 默认值     | 说明         |
+| --------- | ---- | ---------- | ------------ |
+| `modules` | list | 见下方示例 | ROS 模块列表 |
+
+**默认模块列表：**
+
+```python
+class ROSConfig:
+    modules = [
+        "std_msgs.msg",           # 标准消息类型
+        "geometry_msgs.msg",      # 几何消息类型
+        "control_msgs.msg",       # 控制消息类型
+        "control_msgs.action",    # 控制动作类型
+        "nav2_msgs.action",       # 导航动作类型
+        "unilabos_msgs.msg",      # UniLab 自定义消息类型
+        "unilabos_msgs.action",   # UniLab 自定义动作类型
+    ]
+```
+
+您可以根据实际使用的设备和功能添加其他 ROS 模块。
+
+## 环境变量配置
+
+Uni-Lab 支持通过环境变量覆盖配置文件中的设置。
+
+### 环境变量命名规则
+
+```
+UNILABOS_<配置类名>_<配置项名>
+```
+
+**注意：**
+
+- 环境变量名不区分大小写
+- 配置类名和配置项名都会转换为大写进行匹配
+
+### 设置环境变量
+
+#### Linux / macOS
+
+```bash
+# 临时设置（当前终端）
+export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+
+# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
+echo 'export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO' >> ~/.bashrc
+source ~/.bashrc
+```
+
+#### Windows (cmd)
+
+```cmd
+# 临时设置
+set UNILABOS_BASICCONFIG_LOG_LEVEL=INFO
+set UNILABOS_BASICCONFIG_AK=your_access_key
+
+# 永久设置（系统环境变量）
+setx UNILABOS_BASICCONFIG_LOG_LEVEL INFO
+```
+
+#### Windows (PowerShell)
+
+```powershell
+# 临时设置
+$env:UNILABOS_BASICCONFIG_LOG_LEVEL="INFO"
+$env:UNILABOS_BASICCONFIG_AK="your_access_key"
+
+# 永久设置
+[Environment]::SetEnvironmentVariable("UNILABOS_BASICCONFIG_LOG_LEVEL", "INFO", "User")
+```
+
+### 环境变量类型转换
+
+系统会根据配置项的原始类型自动转换环境变量值：
+
+| 原始类型 | 转换规则                                |
+| -------- | --------------------------------------- |
+| `bool`   | "true", "1", "yes" → True；其他 → False |
+| `int`    | 转换为整数                              |
+| `float`  | 转换为浮点数                            |
+| `str`    | 直接使用字符串值                        |
+
+**示例：**
+
+```bash
+# 布尔值
+export UNILABOS_BASICCONFIG_IS_HOST_MODE=true  # 将设置为 True
+export UNILABOS_BASICCONFIG_IS_HOST_MODE=false  # 将设置为 False
+
+# 整数
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL=10  # 将设置为 10
+
+# 字符串
+export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO  # 将设置为 "INFO"
+```
+
+### 环境变量示例
+
+```bash
+# 设置基础配置
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+export UNILABOS_BASICCONFIG_IS_HOST_MODE="true"
+
+# 设置WebSocket配置
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL="10"
+export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS="500"
+
+# 设置HTTP配置
+export UNILABOS_HTTPCONFIG_REMOTE_ADDR="https://uni-lab.test.bohrium.com/api/v1"
+```
+
+## 配置文件使用方法
+
+### 1. 使用默认配置文件（推荐）
+
+系统会自动查找并加载配置文件：
+
+```bash
+# 直接启动，使用默认的 unilabos_data/local_config.py
+unilab --ak your_ak --sk your_sk -g graph.json
+```
+
+查找顺序：
+
+1. 环境变量 `UNILABOS_BASICCONFIG_CONFIG_PATH` 指定的路径
+2. 工作目录下的 `local_config.py`
+3. 首次使用时会引导创建配置文件
+
+### 2. 指定配置文件启动
+
+```bash
+# 使用指定配置文件启动
+unilab --config /path/to/your/config.py --ak ak --sk sk -g graph.json
+```
+
+### 3. 配置文件验证
+
+系统启动时会自动验证配置文件：
+
+- **语法检查**：确保 Python 语法正确
+- **类型检查**：验证配置项类型是否匹配
+- **加载确认**：控制台输出加载成功信息
+
+## 常用配置场景
+
+### 场景 1：调整日志级别
+
+**配置文件方式：**
+
+```python
+class BasicConfig:
+    log_level = "INFO"  # 生产环境建议使用 INFO 或 WARNING
+```
+
+**环境变量方式：**
+
+```bash
+export UNILABOS_BASICCONFIG_LOG_LEVEL=INFO
+unilab --ak ak --sk sk -g graph.json
+```
+
+**命令行方式**（需要配置文件已包含）：
+
+```bash
+# 配置文件无直接命令行参数，需通过环境变量
+UNILABOS_BASICCONFIG_LOG_LEVEL=INFO unilab --ak ak --sk sk -g graph.json
+```
+
+### 场景 2：配置 WebSocket 重连
+
+**配置文件方式：**
+
+```python
+class WSConfig:
+    reconnect_interval = 10  # 增加重连间隔到 10 秒
+    max_reconnect_attempts = 100  # 减少最大重连次数到 100 次
+```
+
+**环境变量方式：**
+
+```bash
+export UNILABOS_WSCONFIG_RECONNECT_INTERVAL=10
+export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS=100
+```
+
+### 场景 3：切换服务器环境
+
+**配置文件方式：**
+
+```python
+class HTTPConfig:
+    remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
+```
+
+**环境变量方式：**
+
+```bash
+export UNILABOS_HTTPCONFIG_REMOTE_ADDR=https://uni-lab.test.bohrium.com/api/v1
+```
+
+**命令行方式（推荐）：**
+
+```bash
+unilab --addr test --ak your_ak --sk your_sk -g graph.json
+```
+
+### 场景 4：从站模式配置
+
+**配置文件方式：**
+
+```python
+class BasicConfig:
+    is_host_mode = False  # 从站模式
+    slave_no_host = True  # 不等待主机服务
+```
+
+**命令行方式（推荐）：**
+
+```bash
+unilab --is_slave --slave_no_host --ak your_ak --sk your_sk
+```
+
+## 最佳实践
+
+### 1. 安全配置
+
+**不要在配置文件中存储敏感信息**
+
+- ❌ **不推荐**：在配置文件中明文存储 ak/sk
+- ✅ **推荐**：使用环境变量或命令行参数
+
+```bash
+# 生产环境 - 使用环境变量（推荐）
+export UNILABOS_BASICCONFIG_AK="your_access_key"
+export UNILABOS_BASICCONFIG_SK="your_secret_key"
+unilab -g graph.json
+
+# 或使用命令行参数
+unilab --ak "your_access_key" --sk "your_secret_key" -g graph.json
+```
+
+**其他安全建议：**
+
+- 不要将包含密钥的配置文件提交到版本控制系统
+- 限制配置文件权限：`chmod 600 local_config.py`
+- 定期更换访问密钥
+- 使用 `.gitignore` 排除配置文件
+
+### 2. 多环境配置
+
+为不同环境创建不同的配置文件：
+
+```
+configs/
+├── base_config.py       # 基础配置（非敏感）
+├── dev_config.py        # 开发环境
+├── test_config.py       # 测试环境
+├── prod_config.py       # 生产环境
+└── example_config.py    # 示例配置
+```
+
+**环境切换示例**：
+
+```bash
+# 本地开发环境
+unilab --config configs/dev_config.py --addr local --ak ak --sk sk -g graph.json
+
+# 测试环境
+unilab --config configs/test_config.py --addr test --ak ak --sk sk --upload_registry -g graph.json
+
+# 生产环境
+unilab --config configs/prod_config.py --ak "$PROD_AK" --sk "$PROD_SK" -g graph.json
+```
+
+### 3. 配置管理
+
+**配置文件最佳实践：**
+
+- 保持配置文件简洁，只包含需要修改的配置项
+- 为配置项添加注释说明其作用
+- 定期检查和更新配置文件
+- 版本控制仅保存示例配置，不包含实际密钥
+
+**命令行参数优先使用场景：**
+
+- 临时测试不同配置
+- CI/CD 流水线中的动态配置
+- 不同环境间快速切换
+- 敏感信息的安全传递
+
+### 4. 灵活配置策略
+
+**基础配置文件 + 命令行覆盖**的推荐方式：
+
+```python
+# base_config.py - 基础配置（非敏感信息）
+class BasicConfig:
+    # 非敏感配置写在文件中
+    is_host_mode = True
+    upload_registry = False
+    vis_2d_enable = False
+    log_level = "INFO"
+
+class WSConfig:
+    reconnect_interval = 5
+    max_reconnect_attempts = 999
+    ping_interval = 30
+```
+
+```bash
+# 启动时通过命令行覆盖关键参数
+unilab --config base_config.py \
+       --ak "$AK" \
+       --sk "$SK" \
+       --addr "test" \
+       --upload_registry \
+       --2d_vis \
+       -g graph.json
+```
+
+## 故障排除
+
+### 1. 配置文件加载失败
+
+**错误信息**：`[ENV] 配置文件 xxx 不存在`
+
+**解决方法**：
+
+- 确认配置文件路径正确
+- 检查文件权限是否可读
+- 确保配置文件是 `.py` 格式
+- 使用绝对路径或相对于当前目录的路径
+
+### 2. 语法错误
+
+**错误信息**：`[ENV] 加载配置文件 xxx 失败`
+
+**解决方法**：
+
+- 检查 Python 语法是否正确
+- 确认类名和字段名拼写正确
+- 验证缩进是否正确（使用空格而非制表符）
+- 确保字符串使用引号包裹
+
+### 3. 认证失败
+
+**错误信息**：`后续运行必须拥有一个实验室`
+
+**解决方法**：
+
+- 确认 `ak` 和 `sk` 已正确配置
+- 检查密钥是否有效（未过期或撤销）
+- 确认网络连接正常
+- 验证密钥是否来自正确的实验室
+
+### 4. 环境变量不生效
+
+**解决方法**：
+
+- 确认环境变量名格式正确（`UNILABOS_<类名>_<字段名>`）
+- 检查环境变量是否已正确设置（`echo $VARIABLE_NAME`）
+- 重启终端或重新加载环境变量
+- 确认环境变量值的类型正确
+
+### 5. 命令行参数不生效
+
+**错误现象**：设置了命令行参数但配置没有生效
+
+**解决方法**：
+
+- 确认参数名拼写正确（如 `--ak` 而不是 `--access_key`）
+- 检查参数格式是否正确（布尔参数如 `--is_slave` 不需要值）
+- 确认参数位置正确（所有参数都应在 `unilab` 之后）
+- 查看启动日志确认参数是否被正确解析
+- 检查是否有配置文件或环境变量与之冲突
+
+### 6. 配置优先级混淆
+
+**错误现象**：不确定哪个配置生效
+
+**解决方法**：
+
+- 记住优先级：**命令行参数 > 环境变量 > 配置文件**
+- 使用 `--ak` 和 `--sk` 参数时会看到提示信息："传入了 ak 参数，优先采用传入参数！"
+- 检查启动日志中的配置加载信息
+- 临时移除低优先级配置来测试高优先级配置是否生效
+- 使用 `printenv | grep UNILABOS` 查看所有相关环境变量
+
+## 配置验证
+
+### 检查配置是否生效
+
+启动 Uni-Lab 时，控制台会输出配置加载信息：
+
+```
+[ENV] 配置文件 /path/to/config.py 加载成功
+[ENV] 设置 BasicConfig.log_level = INFO
+传入了ak参数，优先采用传入参数！
+传入了sk参数，优先采用传入参数！
+```
+
+### 常见配置错误
+
+1. **配置文件格式错误**
+
+   ```
+   [ENV] 加载配置文件 /path/to/config.py 失败
+   ```
+
+   **解决方案**：检查 Python 语法，确保配置类定义正确
+
+2. **环境变量格式错误**
+
+   ```
+   [ENV] 环境变量格式不正确：UNILABOS_INVALID_VAR
+   ```
+
+   **解决方案**：确保环境变量遵循 `UNILABOS_<类名>_<字段名>` 格式
+
+3. **类或字段不存在**
+   ```
+   [ENV] 未找到类：UNKNOWNCONFIG
+   [ENV] 类 BasicConfig 中未找到字段：UNKNOWN_FIELD
+   ```
+   **解决方案**：检查配置类名和字段名是否正确
+
+## 相关文档
+
+- [工作目录详解](working_directory.md)
+- [启动参数详解](../user_guide/launch.md)
+- [快速安装指南](../user_guide/quick_install_guide.md)

docs/advanced_usage/working_directory.md

@@ -0,0 +1,218 @@
+# 工作目录详解
+
+本文档详细介绍 Uni-Lab 工作目录（`working_dir`）的判断逻辑和详细用法。
+
+## 什么是工作目录
+
+工作目录是 Uni-Lab 存储配置文件、日志和运行数据的目录。默认情况下，工作目录为 `当前目录/unilabos_data`。
+
+## 工作目录判断逻辑
+
+系统按以下决策树自动确定工作目录：
+
+### 第一步：初始判断
+
+```python
+# 检查当前目录
+if 当前目录以 "unilabos_data" 结尾:
+    working_dir = 当前目录的绝对路径
+else:
+    working_dir = 当前目录/unilabos_data
+```
+
+**解释：**
+- 如果您已经在 `unilabos_data` 目录内启动，系统直接使用当前目录
+- 否则，系统会在当前目录下创建或使用 `unilabos_data` 子目录
+
+### 第二步：处理 `--working_dir` 参数
+
+如果用户指定了 `--working_dir` 参数：
+
+```python
+working_dir = 用户指定的路径
+```
+
+此时还会检查配置文件：
+- 如果同时指定了 `--config` 但该文件不存在
+- 系统会尝试在 `working_dir/local_config.py` 查找
+- 如果仍未找到，报错退出
+
+### 第三步：处理 `--config` 参数
+
+如果用户指定了 `--config` 且文件存在：
+
+```python
+# 工作目录改为配置文件所在目录
+working_dir = config_path 的父目录
+```
+
+**重要：** 这意味着配置文件的位置会影响工作目录的判断。
+
+## 使用场景示例
+
+### 场景 1：默认场景（推荐）
+
+```bash
+# 当前目录：/home/user/project
+unilab --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /home/user/project/unilabos_data
+# config_path = /home/user/project/unilabos_data/local_config.py
+```
+
+### 场景 2：在 unilabos_data 目录内启动
+
+```bash
+cd /home/user/project/unilabos_data
+unilab --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /home/user/project/unilabos_data
+# config_path = /home/user/project/unilabos_data/local_config.py
+```
+
+### 场景 3：手动指定工作目录
+
+```bash
+unilab --working_dir /custom/path --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /custom/path
+# config_path = /custom/path/local_config.py （如果存在）
+```
+
+### 场景 4：通过配置文件路径推断工作目录
+
+```bash
+unilab --config /data/lab_a/local_config.py --ak your_ak --sk your_sk -g graph.json
+
+# 结果：
+# working_dir = /data/lab_a
+# config_path = /data/lab_a/local_config.py
+```
+
+## 高级用法：管理多个实验室配置
+
+### 方法 1：使用不同的工作目录
+
+```bash
+# 实验室 A
+unilab --working_dir ~/labs/lab_a --ak ak_a --sk sk_a -g graph_a.json
+
+# 实验室 B
+unilab --working_dir ~/labs/lab_b --ak ak_b --sk sk_b -g graph_b.json
+```
+
+### 方法 2：使用不同的配置文件
+
+```bash
+# 实验室 A
+unilab --config ~/labs/lab_a/config.py --ak ak_a --sk sk_a -g graph_a.json
+
+# 实验室 B
+unilab --config ~/labs/lab_b/config.py --ak ak_b --sk sk_b -g graph_b.json
+```
+
+### 方法 3：使用shell脚本管理
+
+创建 `start_lab_a.sh`：
+
+```bash
+#!/bin/bash
+cd ~/labs/lab_a
+unilab --ak your_ak_a --sk your_sk_a -g graph_a.json
+```
+
+创建 `start_lab_b.sh`：
+
+```bash
+#!/bin/bash
+cd ~/labs/lab_b
+unilab --ak your_ak_b --sk your_sk_b -g graph_b.json
+```
+
+## 完整决策流程图
+
+```
+开始
+  ↓
+判断当前目录是否以 unilabos_data 结尾？
+  ├─ 是 → working_dir = 当前目录
+  └─ 否 → working_dir = 当前目录/unilabos_data
+  ↓
+用户是否指定 --working_dir？
+  └─ 是 → working_dir = 指定路径
+  ↓
+用户是否指定 --config 且文件存在？
+  └─ 是 → working_dir = config 文件所在目录
+  ↓
+检查 working_dir/local_config.py 是否存在？
+  ├─ 是 → 加载配置文件 → 继续启动
+  └─ 否 → 询问是否首次使用
+      ├─ 是 → 创建目录和配置文件 → 继续启动
+      └─ 否 → 退出程序
+```
+
+## 常见问题
+
+### 1. 如何查看当前使用的工作目录？
+
+启动 Uni-Lab 时，系统会在控制台输出：
+
+```
+当前工作目录为 /path/to/working_dir
+```
+
+### 2. 可以在同一台机器上运行多个实验室吗？
+
+可以。使用不同的工作目录或配置文件即可：
+
+```bash
+# 终端 1
+unilab --working_dir ~/lab1 --ak ak1 --sk sk1 -g graph1.json
+
+# 终端 2
+unilab --working_dir ~/lab2 --ak ak2 --sk sk2 -g graph2.json
+```
+
+### 3. 工作目录中存储了什么？
+
+- `local_config.py` - 配置文件
+- 日志文件
+- 临时运行数据
+- 缓存文件
+
+### 4. 可以删除工作目录吗？
+
+可以，但会丢失：
+- 配置文件（需要重新创建）
+- 历史日志
+- 缓存数据
+
+建议定期备份配置文件。
+
+### 5. 如何迁移到新的工作目录？
+
+```bash
+# 1. 复制旧的工作目录
+cp -r ~/old_path/unilabos_data ~/new_path/unilabos_data
+
+# 2. 在新位置启动
+cd ~/new_path
+unilab --ak your_ak --sk your_sk -g graph.json
+```
+
+## 最佳实践
+
+1. **使用默认工作目录**：对于单一实验室，使用默认的 `./unilabos_data` 即可
+2. **组织多实验室**：为每个实验室创建独立的目录结构
+3. **版本控制**：将配置文件纳入版本控制，但排除日志和缓存
+4. **备份配置**：定期备份 `local_config.py` 文件
+5. **使用脚本**：为不同实验室创建启动脚本，简化操作
+
+## 相关文档
+
+- [配置文件指南](configuration.md)
+- [启动参数详解](../user_guide/launch.md)
+

docs/concepts/01-communication-instruction.md

@@ -1,7 +1,7 @@
 (instructions)=
 # 设备抽象、指令集与通信中间件
 
-Uni-Lab 操作系统的目的是将不同类型和厂家的实验仪器进行抽象统一，对应用层提供服务。因此，理清实验室设备之间的业务逻辑至关重要。
+Uni-Lab-OS的目的是将不同类型和厂家的实验仪器进行抽象统一，对应用层提供服务。因此，理清实验室设备之间的业务逻辑至关重要。
 
 ## 设备间通信模式
 

docs/conf.py

@@ -24,6 +24,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",  # 如果您使用 Google 或 NumPy 风格的 docstrings
     "sphinx_rtd_theme",
+    "sphinxcontrib.mermaid"
 ]
 
 source_suffix = {
@@ -42,6 +43,8 @@ myst_enable_extensions = [
     "substitution",
 ]
 
+myst_fence_as_directive = ["mermaid"]
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
@@ -203,3 +206,5 @@ def generate_action_includes(app):
 
 def setup(app):
     app.connect("builder-inited", generate_action_includes)
+    app.add_js_file("https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js")
+    app.add_js_file(None, body="mermaid.initialize({startOnLoad:true});")

docs/developer_guide/add_device.md

@@ -1,10 +1,18 @@
-# 添加新设备
+# 添加设备：编写驱动
 
-在 Uni-Lab 中，设备（Device）是实验操作的基础单元。Uni-Lab 使用**注册表机制**来兼容管理种类繁多的设备驱动程序。回顾 {ref}`instructions` 中的概念，抽象的设备对外拥有【话题】【服务】【动作】三种通信机制，因此将设备添加进 Uni-Lab，实际上是将设备驱动中的三种机制映射到 Uni-Lab 标准指令集上。
+在 Uni-Lab 中，设备（Device）是实验操作的基础单元。Uni-Lab 使用**注册表机制**来兼容管理种类繁多的设备驱动程序。抽象的设备对外拥有【话题】【服务】【动作】三种通信机制，因此将设备添加进 Uni-Lab，实际上是将设备驱动中的这三种机制映射到 Uni-Lab 标准指令集上。
 
-能被 Uni-Lab 添加的驱动程序类型有以下种类：
+> **💡 提示：** 本文档介绍如何使用已有的设备驱动（SDK）。若设备没有现成的驱动程序，需要自己开发驱动，请参考 {doc}`add_old_device`。
 
-1. Python Class，如
+## 支持的驱动类型
+
+Uni-Lab 支持以下两种驱动程序：
+
+### 1. Python Class（推荐）
+
+Python 类设备驱动在完成注册表后可以直接在 Uni-Lab 中使用，无需额外编译。
+
+**示例：**
 
 ```python
 class MockGripper:
@@ -31,12 +39,11 @@ class MockGripper:
     def status(self) -> str:
         return self._status
 
-    # 会被自动识别的设备动作，接入 Uni-Lab 时会作为 ActionServer 接受任意控制者的指令
     @status.setter
     def status(self, target):
         self._status = target
 
-    # 需要在注册表添加的设备动作，接入 Uni-Lab 时会作为 ActionServer 接受任意控制者的指令
+    # 会被自动识别的设备动作，接入 Uni-Lab 时会作为 ActionServer 接受任意控制者的指令
     def push_to(self, position: float, torque: float, velocity: float = 0.0):
         self._status = "Running"
         current_pos = self.position
@@ -53,9 +60,11 @@ class MockGripper:
         self._status = "Idle"
 ```
 
-Python 类设备驱动在完成注册表后可以直接在 Uni-Lab 使用。
+### 2. C# Class
 
-2. C# Class，如
+C# 驱动设备在完成注册表后，需要调用 Uni-Lab C# 编译后才能使用（仅需一次）。
+
+**示例：**
 
 ```csharp
 using System;
@@ -84,7 +93,7 @@ public class MockGripper
             position = currentPos + (Position - currentPos) / 20 * (i + 1);
             torque = Torque / (20 - i);
             velocity = Velocity;
-            await Task.Delay((int)(moveTime * 1000 / 20)); // Convert seconds to milliseconds
+            await Task.Delay((int)(moveTime * 1000 / 20));
         }
         torque = Torque;
         status = "Idle";
@@ -92,12 +101,16 @@ public class MockGripper
 }
 ```
 
-C# 驱动设备在完成注册表后，需要调用 Uni-Lab C# 编译后才能使用，但只需一次。
+---
 
-## 快速开始：使用注册表编辑器（推荐）
+## 快速开始：两种方式添加设备
+
+### 方式 1：使用注册表编辑器（推荐）
 
 推荐使用 Uni-Lab-OS 自带的可视化编辑器，它能自动分析您的设备驱动并生成大部分配置：
 
+**步骤：**
+
 1. 启动 Uni-Lab-OS
 2. 在浏览器中打开"注册表编辑器"页面
 3. 选择您的 Python 设备驱动文件
@@ -106,13 +119,18 @@ C# 驱动设备在完成注册表后，需要调用 Uni-Lab C# 编译后才能
 6. 点击"生成注册表"，复制生成的内容
 7. 保存到 `devices/` 目录下
 
----
+**优点：**
 
-## 手动编写注册表（简化版）
+- 自动识别设备属性和方法
+- 可视化界面，易于操作
+- 自动生成完整配置
+- 减少手动配置错误
+
+### 方式 2：手动编写注册表（简化版）
 
 如果需要手动编写，只需要提供两个必需字段，系统会自动补全其余内容：
 
-### 最小配置示例
+**最小配置示例：**
 
 ```yaml
 my_device: # 设备唯一标识符
@@ -121,22 +139,22 @@ my_device: # 设备唯一标识符
     type: python # 驱动类型
 ```
 
-### 注册表文件位置
+**注册表文件位置：**
 
 - 默认路径：`unilabos/registry/devices`
-- 自定义路径：启动时使用 `--registry` 参数指定
-- 可将多个设备写在同一个 yaml 文件中
+- 自定义路径：启动时使用 `--registry_path` 参数指定
+- 可将多个设备写在同一个 YAML 文件中
 
-### 系统自动生成的内容
+**系统自动生成的内容：**
 
 系统会自动分析您的 Python 驱动类并生成：
 
-- `status_types`：从 `get_*` 方法自动识别状态属性
+- `status_types`：从 `@property` 装饰的方法自动识别状态属性
 - `action_value_mappings`：从类方法自动生成动作映射
 - `init_param_schema`：从 `__init__` 方法分析初始化参数
 - `schema`：前端显示用的属性类型定义
 
-### 完整结构概览
+**完整结构概览：**
 
 ```yaml
 my_device:
@@ -151,4 +169,848 @@ my_device:
   schema: {} # 自动生成
 ```
 
-详细的注册表编写指南和高级配置，请参考{doc}`yaml 注册表编写指南 <add_yaml>`。
+> 💡 **提示：** 详细的注册表编写指南和高级配置，请参考 {doc}`03_add_device_registry`。
+
+---
+
+## Python 类结构要求
+
+Uni-Lab 设备驱动是一个 Python 类，需要遵循以下结构：
+
+```python
+from typing import Dict, Any
+
+class MyDevice:
+    """设备类文档字符串
+
+    说明设备的功能、连接方式等
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """初始化设备
+
+        Args:
+            config: 配置字典，来自图文件或注册表
+        """
+        self.port = config.get('port', '/dev/ttyUSB0')
+        self.baudrate = config.get('baudrate', 9600)
+        self._status = "idle"
+        # 初始化硬件连接
+
+    @property
+    def status(self) -> str:
+        """设备状态（会自动广播）"""
+        return self._status
+
+    def my_action(self, param: float) -> Dict[str, Any]:
+        """执行动作
+
+        Args:
+            param: 参数说明
+
+        Returns:
+            {"success": True, "result": ...}
+        """
+        # 执行设备操作
+        return {"success": True}
+```
+
+## 状态属性 vs 动作方法
+
+### 状态属性（@property）
+
+状态属性会被自动识别并定期广播：
+
+```python
+@property
+def temperature(self) -> float:
+    """当前温度"""
+    return self._read_temperature()
+
+@property
+def status(self) -> str:
+    """设备状态: idle, running, error"""
+    return self._status
+
+@property
+def is_ready(self) -> bool:
+    """设备是否就绪"""
+    return self._status == "idle"
+```
+
+**特点**:
+
+- 使用`@property`装饰器
+- 只读，不能有参数
+- 自动添加到注册表的`status_types`
+- 定期发布到 ROS2 topic
+
+### 动作方法
+
+动作方法是设备可以执行的操作：
+
+```python
+def start_heating(self, target_temp: float, rate: float = 1.0) -> Dict[str, Any]:
+    """开始加热
+
+    Args:
+        target_temp: 目标温度(°C)
+        rate: 升温速率(°C/min)
+
+    Returns:
+        {"success": bool, "message": str}
+    """
+    self._status = "heating"
+    self._target_temp = target_temp
+    # 发送命令到硬件
+    return {"success": True, "message": f"Heating to {target_temp}°C"}
+
+async def async_operation(self, duration: float) -> Dict[str, Any]:
+    """异步操作（长时间运行）
+
+    Args:
+        duration: 持续时间(秒)
+    """
+    # 使用 self.sleep 而不是 asyncio.sleep（ROS2 异步机制）
+    await self.sleep(duration)
+    return {"success": True}
+```
+
+**特点**:
+
+- 普通方法或 async 方法
+- 返回 Dict 类型的结果
+- 自动注册为 ROS2 Action
+- 支持参数和返回值
+
+### 返回值设计指南
+
+> **⚠️ 重要：返回值会自动显示在前端**
+>
+> 动作方法的返回值（字典）会自动显示在 Web 界面的工作流执行结果中。因此，**强烈建议**设计结构化、可读的返回值字典。
+
+**推荐的返回值结构：**
+
+```python
+def my_action(self, param: float) -> Dict[str, Any]:
+    """执行操作"""
+    try:
+        # 执行操作...
+        result = self._do_something(param)
+
+        return {
+            "success": True,              # 必需：操作是否成功
+            "message": "操作完成",          # 推荐：用户友好的消息
+            "result": result,             # 可选：具体结果数据
+            "param_used": param,          # 可选：记录使用的参数
+            # 其他有用的信息...
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "message": "操作失败"
+        }
+```
+
+**最佳实践示例（参考 `host_node.test_latency`）：**
+
+```python
+def test_latency(self) -> Dict[str, Any]:
+    """测试网络延迟
+
+    返回值会在前端显示，包含详细的测试结果
+    """
+    # 执行测试...
+    avg_rtt_ms = 25.5
+    avg_time_diff_ms = 10.2
+    test_count = 5
+
+    # 返回结构化的测试结果
+    return {
+        "status": "success",                    # 状态标识
+        "avg_rtt_ms": avg_rtt_ms,              # 平均往返时间
+        "avg_time_diff_ms": avg_time_diff_ms,  # 平均时间差
+        "max_time_error_ms": 5.3,              # 最大误差
+        "task_delay_ms": 15.7,                 # 任务延迟
+        "test_count": test_count,              # 测试次数
+    }
+```
+
+**前端显示效果：**
+
+当用户在 Web 界面执行工作流时，返回的字典会以 JSON 格式显示在结果面板中：
+
+```json
+{
+  "status": "success",
+  "avg_rtt_ms": 25.5,
+  "avg_time_diff_ms": 10.2,
+  "max_time_error_ms": 5.3,
+  "task_delay_ms": 15.7,
+  "test_count": 5
+}
+```
+
+**返回值设计建议：**
+
+1. **始终包含 `success` 字段**：布尔值，表示操作是否成功
+2. **包含 `message` 字段**：字符串，提供用户友好的描述
+3. **使用有意义的键名**：使用描述性的键名（如 `avg_rtt_ms` 而不是 `v1`）
+4. **包含单位**：在键名中包含单位（如 `_ms`、`_ml`、`_celsius`）
+5. **记录重要参数**：返回使用的关键参数值，便于追溯
+6. **错误信息详细**：失败时包含 `error` 字段和详细的错误描述
+7. **避免返回大数据**：不要返回大型数组或二进制数据，这会影响前端性能
+
+**错误处理示例：**
+
+```python
+def risky_operation(self, param: float) -> Dict[str, Any]:
+    """可能失败的操作"""
+    if param < 0:
+        return {
+            "success": False,
+            "error": "参数不能为负数",
+            "message": f"无效参数: {param}",
+            "param": param
+        }
+
+    try:
+        result = self._execute(param)
+        return {
+            "success": True,
+            "message": "操作成功",
+            "result": result,
+            "param": param
+        }
+    except IOError as e:
+        return {
+            "success": False,
+            "error": "通信错误",
+            "message": str(e),
+            "device_status": self._status
+        }
+```
+
+## 特殊参数类型：ResourceSlot 和 DeviceSlot
+
+Uni-Lab 提供特殊的参数类型，用于在方法中声明需要选择资源或设备。
+
+### 导入类型
+
+```python
+from unilabos.registry.placeholder_type import ResourceSlot, DeviceSlot
+from typing import List
+```
+
+### ResourceSlot - 资源选择
+
+用于需要选择物料资源的场景：
+
+```python
+def pipette_liquid(
+    self,
+    source: ResourceSlot,              # 单个源容器
+    target: ResourceSlot,              # 单个目标容器
+    volume: float
+) -> Dict[str, Any]:
+    """从源容器吸取液体到目标容器
+
+    Args:
+        source: 源容器（前端会显示资源选择下拉框）
+        target: 目标容器（前端会显示资源选择下拉框）
+        volume: 体积(μL)
+    """
+    print(f"Pipetting {volume}μL from {source.id} to {target.id}")
+    return {"success": True}
+```
+
+**多选示例**:
+
+```python
+def mix_multiple(
+    self,
+    containers: List[ResourceSlot],    # 多个容器选择
+    speed: float
+) -> Dict[str, Any]:
+    """混合多个容器
+
+    Args:
+        containers: 容器列表（前端会显示多选下拉框）
+        speed: 混合速度
+    """
+    for container in containers:
+        print(f"Mixing {container.name}")
+    return {"success": True}
+```
+
+### DeviceSlot - 设备选择
+
+用于需要选择其他设备的场景：
+
+```python
+def coordinate_with_device(
+    self,
+    other_device: DeviceSlot,          # 单个设备选择
+    command: str
+) -> Dict[str, Any]:
+    """与另一个设备协同工作
+
+    Args:
+        other_device: 协同设备（前端会显示设备选择下拉框）
+        command: 命令
+    """
+    print(f"Coordinating with {other_device.name}")
+    return {"success": True}
+```
+
+**多设备示例**:
+
+```python
+def sync_devices(
+    self,
+    devices: List[DeviceSlot],         # 多个设备选择
+    sync_signal: str
+) -> Dict[str, Any]:
+    """同步多个设备
+
+    Args:
+        devices: 设备列表（前端会显示多选下拉框）
+        sync_signal: 同步信号
+    """
+    for dev in devices:
+        print(f"Syncing {dev.name}")
+    return {"success": True}
+```
+
+### 完整示例：液体处理工作站
+
+```python
+from unilabos.registry.placeholder_type import ResourceSlot, DeviceSlot
+from typing import List, Dict, Any
+
+class LiquidHandler:
+    """液体处理工作站"""
+
+    def __init__(self, config: Dict[str, Any]):
+        self.simulation = config.get('simulation', False)
+        self._status = "idle"
+
+    @property
+    def status(self) -> str:
+        return self._status
+
+    def transfer_liquid(
+        self,
+        source: ResourceSlot,               # 源容器选择
+        target: ResourceSlot,               # 目标容器选择
+        volume: float,
+        tip: ResourceSlot = None            # 可选的枪头选择
+    ) -> Dict[str, Any]:
+        """转移液体
+
+        前端效果：
+        - source: 下拉框，列出所有可用容器
+        - target: 下拉框，列出所有可用容器
+        - volume: 数字输入框
+        - tip: 下拉框（可选），列出所有枪头
+        """
+        self._status = "transferring"
+
+        # source和target会被解析为实际的资源对象
+        print(f"Transferring {volume}μL")
+        print(f"  From: {source.id} ({source.name})")
+        print(f"  To: {target.id} ({target.name})")
+
+        if tip:
+            print(f"  Using tip: {tip.id}")
+
+        # 执行实际的液体转移
+        # ...
+
+        self._status = "idle"
+        return {
+            "success": True,
+            "volume_transferred": volume,
+            "source_id": source.id,
+            "target_id": target.id
+        }
+
+    def multi_dispense(
+        self,
+        source: ResourceSlot,               # 单个源
+        targets: List[ResourceSlot],        # 多个目标
+        volumes: List[float]
+    ) -> Dict[str, Any]:
+        """从一个源分配到多个目标
+
+        前端效果：
+        - source: 单选下拉框
+        - targets: 多选下拉框（可选择多个容器）
+        - volumes: 数组输入（每个目标对应一个体积）
+        """
+        results = []
+        for target, vol in zip(targets, volumes):
+            print(f"Dispensing {vol}μL to {target.name}")
+            results.append({
+                "target": target.id,
+                "volume": vol
+            })
+
+        return {
+            "success": True,
+            "dispense_results": results
+        }
+
+    def test_with_balance(
+        self,
+        target: ResourceSlot,               # 容器
+        balance: DeviceSlot                 # 天平设备
+    ) -> Dict[str, Any]:
+        """使用天平测量容器
+
+        前端效果：
+        - target: 容器选择下拉框
+        - balance: 设备选择下拉框（仅显示天平类型）
+        """
+        print(f"Weighing {target.name} on {balance.name}")
+
+        # 可以调用balance的方法
+        # weight = balance.get_weight()
+
+        return {
+            "success": True,
+            "container": target.id,
+            "balance_used": balance.id
+        }
+```
+
+### 工作原理
+
+#### 1. 类型识别
+
+注册表扫描方法签名时：
+
+```python
+def my_method(self, resource: ResourceSlot, device: DeviceSlot):
+    pass
+```
+
+系统识别到`ResourceSlot`和`DeviceSlot`类型。
+
+#### 2. 自动添加 placeholder_keys
+
+在注册表中自动生成：
+
+```yaml
+my_device:
+  class:
+    action_value_mappings:
+      my_method:
+        goal:
+          resource: resource
+          device: device
+        placeholder_keys:
+          resource: unilabos_resources # 自动添加！
+          device: unilabos_devices # 自动添加！
+```
+
+#### 3. 前端 UI 生成
+
+- `unilabos_resources`: 渲染为资源选择下拉框
+- `unilabos_devices`: 渲染为设备选择下拉框
+
+#### 4. 运行时解析
+
+用户选择资源/设备后，实际调用时会传入完整的资源/设备对象：
+
+```python
+# 用户在前端选择了 plate_1
+# 运行时，source参数会收到完整的Resource对象
+source.id        # "plate_1"
+source.name      # "96孔板"
+source.type      # "resource"
+source.class_    # "corning_96_wellplate_360ul_flat"
+```
+
+## 支持的通信方式
+
+### 1. 串口（Serial）
+
+```python
+import serial
+
+class SerialDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.port = config['port']
+        self.baudrate = config.get('baudrate', 9600)
+        self.ser = serial.Serial(
+            port=self.port,
+            baudrate=self.baudrate,
+            timeout=1
+        )
+
+    def send_command(self, cmd: str) -> str:
+        """发送命令并读取响应"""
+        self.ser.write(f"{cmd}\r\n".encode())
+        response = self.ser.readline().decode().strip()
+        return response
+
+    def __del__(self):
+        if hasattr(self, 'ser') and self.ser.is_open:
+            self.ser.close()
+```
+
+### 2. TCP/IP Socket
+
+```python
+import socket
+
+class TCPDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.host = config['host']
+        self.port = config['port']
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.sock.connect((self.host, self.port))
+
+    def send_command(self, cmd: str) -> str:
+        self.sock.sendall(cmd.encode())
+        response = self.sock.recv(1024).decode()
+        return response
+```
+
+### 3. Modbus
+
+```python
+from pymodbus.client import ModbusTcpClient
+
+class ModbusDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.host = config['host']
+        self.port = config.get('port', 502)
+        self.client = ModbusTcpClient(self.host, port=self.port)
+        self.client.connect()
+
+    def read_register(self, address: int) -> int:
+        result = self.client.read_holding_registers(address, 1)
+        return result.registers[0]
+
+    def write_register(self, address: int, value: int):
+        self.client.write_register(address, value)
+```
+
+### 4. OPC UA
+
+```python
+from opcua import Client
+
+class OPCUADevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.url = config['url']
+        self.client = Client(self.url)
+        self.client.connect()
+
+    def read_node(self, node_id: str):
+        node = self.client.get_node(node_id)
+        return node.get_value()
+
+    def write_node(self, node_id: str, value):
+        node = self.client.get_node(node_id)
+        node.set_value(value)
+```
+
+### 5. HTTP/RPC
+
+```python
+import requests
+
+class HTTPDevice:
+    def __init__(self, config: Dict[str, Any]):
+        self.base_url = config['url']
+        self.auth_token = config.get('token')
+
+    def send_command(self, endpoint: str, data: Dict) -> Dict:
+        url = f"{self.base_url}/{endpoint}"
+        headers = {'Authorization': f'Bearer {self.auth_token}'}
+        response = requests.post(url, json=data, headers=headers)
+        return response.json()
+```
+
+## 异步 vs 同步方法
+
+### 同步方法（适合快速操作）
+
+```python
+def quick_operation(self, param: float) -> Dict[str, Any]:
+    """快速操作，立即返回"""
+    result = self._do_something(param)
+    return {"success": True, "result": result}
+```
+
+### 异步方法（适合耗时操作）
+
+```python
+async def long_operation(self, duration: float) -> Dict[str, Any]:
+    """长时间运行的操作"""
+    self._status = "running"
+
+    # 使用 ROS2 提供的 sleep 方法（而不是 asyncio.sleep）
+    await self.sleep(duration)
+
+    # 可以在过程中发送feedback
+    # 需要配合ROS2 Action的feedback机制
+
+    self._status = "idle"
+    return {"success": True, "duration": duration}
+```
+
+> **⚠️ 重要提示：ROS2 异步机制 vs Python asyncio**
+>
+> Uni-Lab 的设备驱动虽然使用 `async def` 语法，但**底层是 ROS2 的异步机制，而不是 Python 的 asyncio**。
+>
+> **不能使用的 asyncio 功能：**
+>
+> - ❌ `asyncio.sleep()` - 会导致 ROS2 事件循环阻塞
+> - ❌ `asyncio.create_task()` - 任务不会被 ROS2 正确调度
+> - ❌ `asyncio.gather()` - 无法与 ROS2 集成
+> - ❌ 其他 asyncio 标准库函数
+>
+> **应该使用的方法（继承自 BaseROS2DeviceNode）：**
+>
+> - ✅ `await self.sleep(seconds)` - ROS2 兼容的睡眠
+> - ✅ `await self.create_task(func, **kwargs)` - ROS2 兼容的任务创建
+> - ✅ ROS2 的 Action/Service 回调机制
+>
+> **示例：**
+>
+> ```python
+> async def complex_operation(self, duration: float) -> Dict[str, Any]:
+>     """正确使用 ROS2 异步方法"""
+>     self._status = "processing"
+>
+>     # ✅ 正确：使用 self.sleep
+>     await self.sleep(duration)
+>
+>     # ✅ 正确：创建并发任务
+>     task = await self.create_task(self._background_work)
+>
+>     # ❌ 错误：不要使用 asyncio
+>     # await asyncio.sleep(duration)  # 这会导致问题！
+>     # task = asyncio.create_task(...)  # 这也不行！
+>
+>     self._status = "idle"
+>     return {"success": True}
+>
+> async def _background_work(self):
+>     """后台任务"""
+>     await self.sleep(1.0)
+>     self.lab_logger().info("Background work completed")
+> ```
+>
+> **为什么不能混用？**
+>
+> ROS2 使用 `rclpy` 的事件循环来管理所有异步操作。如果使用 `asyncio` 的函数，这些操作会在不同的事件循环中运行，导致：
+>
+> - ROS2 回调无法正确执行
+> - 任务可能永远不会完成
+> - 程序可能死锁或崩溃
+>
+> **参考实现：**
+>
+> `BaseROS2DeviceNode` 提供的方法定义（`base_device_node.py:563-572`）：
+>
+> ```python
+> async def sleep(self, rel_time: float, callback_group=None):
+>     """ROS2 兼容的异步睡眠"""
+>     if callback_group is None:
+>         callback_group = self.callback_group
+>     await ROS2DeviceNode.async_wait_for(self, rel_time, callback_group)
+>
+> @classmethod
+> async def create_task(cls, func, trace_error=True, **kwargs) -> Task:
+>     """ROS2 兼容的任务创建"""
+>     return ROS2DeviceNode.run_async_func(func, trace_error, **kwargs)
+> ```
+
+## 错误处理
+
+### 基本错误处理
+
+```python
+def operation_with_error_handling(self, param: float) -> Dict[str, Any]:
+    """带错误处理的操作"""
+    try:
+        result = self._risky_operation(param)
+        return {
+            "success": True,
+            "result": result
+        }
+    except ValueError as e:
+        return {
+            "success": False,
+            "error": "Invalid parameter",
+            "message": str(e)
+        }
+    except IOError as e:
+        self._status = "error"
+        return {
+            "success": False,
+            "error": "Communication error",
+            "message": str(e)
+        }
+```
+
+### 自定义异常
+
+```python
+class DeviceError(Exception):
+    """设备错误基类"""
+    pass
+
+class DeviceNotReadyError(DeviceError):
+    """设备未就绪"""
+    pass
+
+class DeviceTimeoutError(DeviceError):
+    """设备超时"""
+    pass
+
+class MyDevice:
+    def operation(self) -> Dict[str, Any]:
+        if self._status != "idle":
+            raise DeviceNotReadyError(f"Device is {self._status}")
+
+        # 执行操作
+        return {"success": True}
+```
+
+## 最佳实践
+
+### 1. 类型注解
+
+```python
+from typing import Dict, Any, Optional, List
+
+def method(
+    self,
+    param1: float,
+    param2: str,
+    optional_param: Optional[int] = None
+) -> Dict[str, Any]:
+    """完整的类型注解有助于自动生成注册表"""
+    pass
+```
+
+### 2. 文档字符串
+
+```python
+def method(self, param: float) -> Dict[str, Any]:
+    """方法简短描述
+
+    更详细的说明...
+
+    Args:
+        param: 参数说明，包括单位和范围
+
+    Returns:
+        Dict包含:
+        - success (bool): 是否成功
+        - result (Any): 结果数据
+
+    Raises:
+        DeviceError: 错误情况说明
+    """
+    pass
+```
+
+### 3. 配置验证
+
+```python
+def __init__(self, config: Dict[str, Any]):
+    # 验证必需参数
+    required = ['port', 'baudrate']
+    for key in required:
+        if key not in config:
+            raise ValueError(f"Missing required config: {key}")
+
+    self.port = config['port']
+    self.baudrate = config['baudrate']
+```
+
+### 4. 资源清理
+
+```python
+def __del__(self):
+    """析构函数，清理资源"""
+    if hasattr(self, 'connection') and self.connection:
+        self.connection.close()
+```
+
+### 5. 设计前端友好的返回值
+
+**记住：返回值会直接显示在 Web 界面**
+
+```python
+import time
+
+def measure_temperature(self) -> Dict[str, Any]:
+    """测量温度
+
+    ✅ 好的返回值设计：
+    - 包含 success 状态
+    - 使用描述性键名
+    - 在键名中包含单位
+    - 记录测量时间
+    """
+    temp = self._read_temperature()
+
+    return {
+        "success": True,
+        "temperature_celsius": temp,      # 键名包含单位
+        "timestamp": time.time(),          # 记录时间
+        "sensor_status": "normal",         # 额外状态信息
+        "message": f"温度测量完成: {temp}°C"  # 用户友好的消息
+    }
+
+def bad_example(self) -> Dict[str, Any]:
+    """❌ 不好的返回值设计"""
+    return {
+        "s": True,          # ❌ 键名不明确
+        "v": 25.5,          # ❌ 没有说明单位
+        "t": 1234567890,    # ❌ 不清楚是什么时间戳
+    }
+```
+
+**参考 `host_node.test_latency` 方法**（第 1216-1340 行），它返回详细的测试结果，在前端清晰显示：
+
+```python
+return {
+    "status": "success",
+    "avg_rtt_ms": 25.5,            # 有意义的键名 + 单位
+    "avg_time_diff_ms": 10.2,
+    "max_time_error_ms": 5.3,
+    "task_delay_ms": 15.7,
+    "test_count": 5,               # 记录重要信息
+}
+```
+
+## 下一步
+
+看完本文档后，建议继续阅读：
+
+- {doc}`add_action` - 了解如何添加新的动作指令
+- {doc}`add_yaml` - 学习如何编写和完善 YAML 注册表
+
+进阶主题：
+
+- {doc}`03_add_device_registry` - 了解如何配置注册表
+- {doc}`04_add_device_testing` - 学习如何测试设备
+- {doc}`add_old_device` - 没有 SDK 时如何开发设备驱动
+
+## 参考
+
+- [Python 类型注解](https://docs.python.org/3/library/typing.html)
+- [ROS2 rclpy 异步编程](https://docs.ros.org/en/humble/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.html) - Uni-Lab 使用 ROS2 的异步机制
+- [串口通信](https://pyserial.readthedocs.io/)
+
+> **注意：** 虽然设备驱动使用 `async def` 语法，但请**不要参考** Python 标准的 [asyncio 文档](https://docs.python.org/3/library/asyncio.html)。Uni-Lab 使用的是 ROS2 的异步机制，两者不兼容。请使用 `self.sleep()` 和 `self.create_task()` 等 BaseROS2DeviceNode 提供的方法。

docs/developer_guide/add_old_device.md

@@ -1,8 +1,10 @@
-# 设备 Driver 开发
+# 设备 Driver 开发（无 SDK 设备）
 
 我们对设备 Driver 的定义，是一个 Python/C++/C# 类，类的方法可以用于获取传感器数据、执行设备动作、更新物料信息。它们经过 Uni-Lab 的通信中间件包装，就能成为高效分布式通信的设备节点。
 
-因此，若已有设备的 SDK (Driver)，可以直接 [添加进 Uni-Lab](add_device.md)。仅当没有 SDK (Driver) 时，请参考本章作开发。
+因此，若已有设备的 SDK (Driver)，可以直接 [添加进 Uni-Lab](add_device.md)。**仅当没有 SDK (Driver) 时，请参考本章进行驱动开发。**
+
+> **💡 提示：** 本文档介绍如何为没有现成驱动的老设备开发驱动程序。如果您的设备已经有 SDK 或驱动，请直接参考 {doc}`add_device`。
 
 ## 有串口字符串指令集文档的设备：Python 串口通信（常见 RS485, RS232, USB）
 
@@ -12,13 +14,13 @@
 
 Modbus 与 RS485、RS232 不一样的地方在于，会有更多直接寄存器的读写，以及涉及字节序转换（Big Endian, Little Endian）。
 
-Uni-Lab 开发团队在仓库中提供了3个样例：
+Uni-Lab 开发团队在仓库中提供了 3 个样例：
 
-* 单一机械设备**电夹爪**，通讯协议可见 [增广夹爪通讯协议](https://doc.rmaxis.com/docs/communication/fieldbus/)，驱动代码位于 `unilabos/devices/gripper/rmaxis_v4.py`
-* 单一通信设备**IO板卡**，驱动代码位于 `unilabos/device_comms/gripper/SRND_16_IO.py`
-* 执行多设备复杂任务逻辑的**PLC**，Uni-Lab 提供了基于地址表的接入方式和点动工作流编写，测试代码位于 `unilabos/device_comms/modbus_plc/test/test_workflow.py`
+- 单一机械设备**电夹爪**，通讯协议可见 [增广夹爪通讯协议](https://doc.rmaxis.com/docs/communication/fieldbus/)，驱动代码位于 `unilabos/devices/gripper/rmaxis_v4.py`
+- 单一通信设备**IO 板卡**，驱动代码位于 `unilabos/device_comms/gripper/SRND_16_IO.py`
+- 执行多设备复杂任务逻辑的**PLC**，Uni-Lab 提供了基于地址表的接入方式和点动工作流编写，测试代码位于 `unilabos/device_comms/modbus_plc/test/test_workflow.py`
 
-****
+---
 
 ## 其他工业通信协议：CANopen, Ethernet, OPCUA...
 
@@ -26,32 +28,32 @@ Uni-Lab 开发团队在仓库中提供了3个样例：
 
 ## 没有接口的老设备老软件：使用 PyWinAuto
 
-**pywinauto**是一个 Python 库，用于自动化Windows GUI操作。它可以模拟用户的鼠标点击、键盘输入、窗口操作等，广泛应用于自动化测试、GUI自动化等场景。它支持通过两个后端进行操作：
+**pywinauto**是一个 Python 库，用于自动化 Windows GUI 操作。它可以模拟用户的鼠标点击、键盘输入、窗口操作等，广泛应用于自动化测试、GUI 自动化等场景。它支持通过两个后端进行操作：
 
-* **win32**后端：适用于大多数Windows应用程序，使用native Win32 API。（pywinauto_recorder默认使用win32后端）
-* **uia**后端：基于Microsoft UI Automation，适用于较新的应用程序，特别是基于WPF或UWP的应用程序。（在win10上，会有更全的目录，有的窗口win32会识别不到）
+- **win32**后端：适用于大多数 Windows 应用程序，使用 native Win32 API。（pywinauto_recorder 默认使用 win32 后端）
+- **uia**后端：基于 Microsoft UI Automation，适用于较新的应用程序，特别是基于 WPF 或 UWP 的应用程序。（在 win10 上，会有更全的目录，有的窗口 win32 会识别不到）
 
-### windows平台安装pywinauto和pywinauto_recorder
+### windows 平台安装 pywinauto 和 pywinauto_recorder
 
 直接安装会造成环境崩溃，需要下载并解压已经修改好的文件。
 
-cd到对应目录，执行安装
+cd 到对应目录，执行安装
 
-`pip install . -i ``https://pypi.tuna.tsinghua.edu.cn/simple`
+` pip install . -i ``https://pypi.tuna.tsinghua.edu.cn/simple `
 
 ![pywinauto_install](image/device_driver/pywinauto_install.png)
 
-windows平台测试 python pywinauto_recorder.py，退出使用两次ctrl+alt+r取消选中，关闭命令提示符。
+windows 平台测试 python pywinauto_recorder.py，退出使用两次 ctrl+alt+r 取消选中，关闭命令提示符。
 
 ### 计算器例子
 
-你可以先打开windows的计算器，然后在ilab的环境中运行下面的代码片段，可观察到得到结果，通过这一案例，你需要掌握的pywinauto用法：
+你可以先打开 windows 的计算器，然后在 ilab 的环境中运行下面的代码片段，可观察到得到结果，通过这一案例，你需要掌握的 pywinauto 用法：
 
-* 连接到指定进程
-* 利用dump_tree查找需要的窗口
-* 获取某个位置的信息
-* 模拟点击
-* 模拟输入
+- 连接到指定进程
+- 利用 dump_tree 查找需要的窗口
+- 获取某个位置的信息
+- 模拟点击
+- 模拟输入
 
 #### 代码学习
 
@@ -74,39 +76,39 @@ window.dump_tree(depth=3)
 Dialog - '计算器'    (L-419, T773, R-73, B1287)
 ['计算器Dialog', 'Dialog', '计算器', '计算器Dialog0', '计算器Dialog1', 'Dialog0', 'Dialog1', '计算器0', '计算器1']
 child_window(title="计算器", control_type="Window")
-   | 
+   |
    | Dialog - '计算器'    (L-269, T774, R-81, B806)
    | ['计算器Dialog2', 'Dialog2', '计算器2']
    | child_window(title="计算器", auto_id="TitleBar", control_type="Window")
-   |    | 
+   |    |
    |    | Menu - '系统'    (L0, T0, R0, B0)
    |    | ['Menu', '系统', '系统Menu', '系统0', '系统1']
    |    | child_window(title="系统", auto_id="SystemMenuBar", control_type="MenuBar")
-   |    | 
+   |    |
    |    | Button - '最小化 计算器'    (L-219, T774, R-173, B806)
    |    | ['Button', '最小化 计算器Button', '最小化 计算器', 'Button0', 'Button1']
    |    | child_window(title="最小化 计算器", auto_id="Minimize", control_type="Button")
-   |    | 
+   |    |
    |    | Button - '使 计算器 最大化'    (L-173, T774, R-127, B806)
    |    | ['Button2', '使 计算器 最大化', '使 计算器 最大化Button']
    |    | child_window(title="使 计算器 最大化", auto_id="Maximize", control_type="Button")
-   |    | 
+   |    |
    |    | Button - '关闭 计算器'    (L-127, T774, R-81, B806)
    |    | ['Button3', '关闭 计算器Button', '关闭 计算器']
    |    | child_window(title="关闭 计算器", auto_id="Close", control_type="Button")
-   | 
+   |
    | Dialog - '计算器'    (L-411, T774, R-81, B1279)
    | ['计算器Dialog3', 'Dialog3', '计算器3']
    | child_window(title="计算器", control_type="Window")
-   |    | 
+   |    |
    |    | Static - '计算器'    (L-363, T782, R-327, B798)
    |    | ['计算器Static', 'Static', '计算器4', 'Static0', 'Static1']
    |    | child_window(title="计算器", auto_id="AppName", control_type="Text")
-   |    | 
+   |    |
    |    | Custom - ''    (L-411, T806, R-81, B1279)
    |    | ['Custom', '计算器Custom']
    |    | child_window(auto_id="NavView", control_type="Custom")
-   | 
+   |
    | Pane - ''    (L-411, T806, R-81, B1279)
    | ['Pane', '计算器Pane']
 """
@@ -122,58 +124,58 @@ target_window.dump_tree(depth=3)
 Custom - ''    (L-411, T806, R-81, B1279)
 ['标准Custom', 'Custom']
 child_window(auto_id="NavView", control_type="Custom")
-   | 
+   |
    | Button - '打开导航'    (L-407, T812, R-367, B848)
    | ['打开导航Button', '打开导航', 'Button', 'Button0', 'Button1']
    | child_window(title="打开导航", auto_id="TogglePaneButton", control_type="Button")
-   |    | 
+   |    |
    |    | Static - ''    (L0, T0, R0, B0)
    |    | ['Static', 'Static0', 'Static1']
    |    | child_window(auto_id="PaneTitleTextBlock", control_type="Text")
-   | 
+   |
    | GroupBox - ''    (L-411, T814, R-81, B1275)
    | ['标准GroupBox', 'GroupBox', 'GroupBox0', 'GroupBox1']
-   |    | 
+   |    |
    |    | Static - '表达式为 '    (L0, T0, R0, B0)
    |    | ['表达式为 ', 'Static2', '表达式为 Static']
    |    | child_window(title="表达式为 ", auto_id="CalculatorExpression", control_type="Text")
-   |    | 
+   |    |
    |    | Static - '显示为 0'    (L-411, T875, R-81, B947)
    |    | ['显示为 0Static', '显示为 0', 'Static3']
    |    | child_window(title="显示为 0", auto_id="CalculatorResults", control_type="Text")
-   |    | 
+   |    |
    |    | Button - '打开历史记录浮出控件'    (L-121, T814, R-89, B846)
    |    | ['打开历史记录浮出控件', '打开历史记录浮出控件Button', 'Button2']
    |    | child_window(title="打开历史记录浮出控件", auto_id="HistoryButton", control_type="Button")
-   |    | 
+   |    |
    |    | GroupBox - '记忆控件'    (L-407, T948, R-85, B976)
    |    | ['记忆控件', '记忆控件GroupBox', 'GroupBox2']
    |    | child_window(title="记忆控件", auto_id="MemoryPanel", control_type="Group")
-   |    | 
+   |    |
    |    | GroupBox - '显示控件'    (L-407, T978, R-85, B1026)
    |    | ['显示控件', 'GroupBox3', '显示控件GroupBox']
    |    | child_window(title="显示控件", auto_id="DisplayControls", control_type="Group")
-   |    | 
+   |    |
    |    | GroupBox - '标准函数'    (L-407, T1028, R-166, B1076)
    |    | ['标准函数', '标准函数GroupBox', 'GroupBox4']
    |    | child_window(title="标准函数", auto_id="StandardFunctions", control_type="Group")
-   |    | 
+   |    |
    |    | GroupBox - '标准运算符'    (L-164, T1028, R-85, B1275)
    |    | ['标准运算符', '标准运算符GroupBox', 'GroupBox5']
    |    | child_window(title="标准运算符", auto_id="StandardOperators", control_type="Group")
-   |    | 
+   |    |
    |    | GroupBox - '数字键盘'    (L-407, T1078, R-166, B1275)
    |    | ['GroupBox6', '数字键盘', '数字键盘GroupBox']
    |    | child_window(title="数字键盘", auto_id="NumberPad", control_type="Group")
-   |    | 
+   |    |
    |    | Button - '正负'    (L-407, T1228, R-328, B1275)
    |    | ['Button32', '正负Button', '正负']
    |    | child_window(title="正负", auto_id="negateButton", control_type="Button")
-   | 
+   |
    | Static - '标准'    (L-363, T815, R-322, B842)
    | ['标准', '标准Static', 'Static4']
    | child_window(title="标准", auto_id="Header", control_type="Text")
-   | 
+   |
    | Button - '始终置顶'    (L-312, T814, R-280, B846)
    | ['始终置顶Button', '始终置顶', 'Button33']
    | child_window(title="始终置顶", auto_id="NormalAlwaysOnTopButton", control_type="Button")
@@ -187,47 +189,47 @@ numpad.dump_tree(depth=2)
 GroupBox - '数字键盘'    (L-334, T1350, R-93, B1547)
 ['GroupBox', '数字键盘', '数字键盘GroupBox']
 child_window(title="数字键盘", auto_id="NumberPad", control_type="Group")
-   | 
+   |
    | Button - '零'    (L-253, T1500, R-174, B1547)
    | ['零Button', 'Button', '零', 'Button0', 'Button1']
    | child_window(title="零", auto_id="num0Button", control_type="Button")
-   | 
+   |
    | Button - '一'    (L-334, T1450, R-255, B1498)
    | ['一Button', 'Button2', '一']
    | child_window(title="一", auto_id="num1Button", control_type="Button")
-   | 
+   |
    | Button - '二'    (L-253, T1450, R-174, B1498)
    | ['Button3', '二', '二Button']
    | child_window(title="二", auto_id="num2Button", control_type="Button")
-   | 
+   |
    | Button - '三'    (L-172, T1450, R-93, B1498)
    | ['Button4', '三', '三Button']
    | child_window(title="三", auto_id="num3Button", control_type="Button")
-   | 
+   |
    | Button - '四'    (L-334, T1400, R-255, B1448)
    | ['四', 'Button5', '四Button']
    | child_window(title="四", auto_id="num4Button", control_type="Button")
-   | 
+   |
    | Button - '五'    (L-253, T1400, R-174, B1448)
    | ['Button6', '五Button', '五']
    | child_window(title="五", auto_id="num5Button", control_type="Button")
-   | 
+   |
    | Button - '六'    (L-172, T1400, R-93, B1448)
    | ['六Button', 'Button7', '六']
    | child_window(title="六", auto_id="num6Button", control_type="Button")
-   | 
+   |
    | Button - '七'    (L-334, T1350, R-255, B1398)
    | ['Button8', '七Button', '七']
    | child_window(title="七", auto_id="num7Button", control_type="Button")
-   | 
+   |
    | Button - '八'    (L-253, T1350, R-174, B1398)
    | ['八', 'Button9', '八Button']
    | child_window(title="八", auto_id="num8Button", control_type="Button")
-   | 
+   |
    | Button - '九'    (L-172, T1350, R-93, B1398)
    | ['Button10', '九', '九Button']
    | child_window(title="九", auto_id="num9Button", control_type="Button")
-   | 
+   |
    | Button - '十进制分隔符'    (L-172, T1500, R-93, B1547)
    | ['十进制分隔符Button', 'Button11', '十进制分隔符']
    | child_window(title="十进制分隔符", auto_id="decimalSeparatorButton", control_type="Button")
@@ -262,13 +264,13 @@ r, g, b = pyautogui.pixel(point_x, point_y)
 
 ### pywinauto_recorder
 
-pywinauto_recorder是一个配合 pywinauto 使用的工具，用于录制用户的操作，并生成相应的 pywinauto 脚本。这对于一些暂时无法直接调用DLL的函数并且需要模拟用户操作的场景非常有用。同时，可以省去仅用pywinauto的一些查找UI步骤。
+pywinauto_recorder 是一个配合 pywinauto 使用的工具，用于录制用户的操作，并生成相应的 pywinauto 脚本。这对于一些暂时无法直接调用 DLL 的函数并且需要模拟用户操作的场景非常有用。同时，可以省去仅用 pywinauto 的一些查找 UI 步骤。
 
 #### 运行尝试
 
-请参照 上手尝试-环境创建-3 开启pywinauto_recorder
+请参照 上手尝试-环境创建-3 开启 pywinauto_recorder
 
-例如我们这里先启动一个windows自带的计算器软件
+例如我们这里先启动一个 windows 自带的计算器软件
 
 ![calculator_01](image/device_driver/calculator_01.png)
 
@@ -286,7 +288,7 @@ with UIPath(u"计算器||Window"):
         click(u"九||Button")
 ```
 
-执行该python脚本，可以观察到新开启的计算器被点击了数字9
+执行该 python 脚本，可以观察到新开启的计算器被点击了数字 9
 
 ![calculator_03](image/device_driver/calculator_03.png)
 
@@ -308,23 +310,38 @@ window.dump_tree(depth=[int类型数字], filename=None)
 GroupBox - '数字键盘'    (L-334, T1350, R-93, B1547)
 ['GroupBox', '数字键盘', '数字键盘GroupBox']
 child_window(title="数字键盘", auto_id="NumberPad", control_type="Group")
-   | 
+   |
    | Button - '零'    (L-253, T1500, R-174, B1547)
    | ['零Button', 'Button', '零', 'Button0', 'Button1']
    | child_window(title="零", auto_id="num0Button", control_type="Button")
 """
 ```
 
-这里以上面计算器的例子对dump_tree进行解读
+这里以上面计算器的例子对 dump_tree 进行解读
 
-2~4行为当前对象的窗口
+2~4 行为当前对象的窗口
 
-* 第2行分别是窗体的类型 `GroupBox`，窗体的题目 `数字键盘`，窗体的矩形区域坐标，对应的是屏幕上的位置（左、上、右、下）
-* 第3行是 `['GroupBox', '数字键盘', '数字键盘GroupBox']`，为控件的标识符列表，可以选择任意一个，使用 `child_window(best_match="标识符")`来获取该窗口
-* 第4行是获取该控件的方法，请注意该方法不能保证获取唯一，`title`如果是变化的，也需要删除 `title`参数
+- 第 2 行分别是窗体的类型 `GroupBox`，窗体的题目 `数字键盘`，窗体的矩形区域坐标，对应的是屏幕上的位置（左、上、右、下）
+- 第 3 行是 `['GroupBox', '数字键盘', '数字键盘GroupBox']`，为控件的标识符列表，可以选择任意一个，使用 `child_window(best_match="标识符")`来获取该窗口
+- 第 4 行是获取该控件的方法，请注意该方法不能保证获取唯一，`title`如果是变化的，也需要删除 `title`参数
 
-6~8行为当前对象窗口所包含的子窗口信息，信息类型对应2~4行
+6~8 行为当前对象窗口所包含的子窗口信息，信息类型对应 2~4 行
 
 ### 窗口获取注意事项
 
-1. 在 `child_window`的时候，并不会立刻报错，只有在执行窗口的信息获取时才会调用，查询窗口是否存在，因此要想确定 `child_window`是否正确，可以调用子窗口对象的属性 `element_info`，来保证窗口存在
+1. 在 `child_window`的时候，并不会立刻报错，只有在执行窗口的信息获取时才会调用，查询窗口是否存在，因此要想确定 `child_window`是否正确，可以调用子窗口对象的属性 `element_info`，来保证窗口存在
+
+---
+
+## 下一步
+
+完成设备驱动开发后，建议继续阅读：
+
+- {doc}`add_device` - 了解如何将驱动添加到 Uni-Lab 中
+- {doc}`add_action` - 学习如何添加新的动作指令
+- {doc}`add_yaml` - 编写和完善 YAML 注册表
+
+进阶主题：
+
+- {doc}`03_add_device_registry` - 详细的注册表配置
+- {doc}`04_add_device_testing` - 设备测试指南

docs/developer_guide/examples/battery_plc_workstation.md

@@ -1,6 +1,17 @@
-# 电池装配工站接入（PLC）
+# 实例：电池装配工站接入（PLC 控制）
 
-本指南将引导你完成电池装配工站（以 PLC 控制为例）的接入流程，包括新建工站文件、编写驱动与寄存器读写、生成注册表、上传及注意事项。
+> **文档类型**：实际应用案例  
+> **适用场景**：使用 PLC 控制的电池装配工站接入  
+> **前置知识**：{doc}`../add_device` | {doc}`../add_registry`
+
+本指南以电池装配工站为实际案例，引导你完成 PLC 控制设备的完整接入流程，包括新建工站文件、编写驱动与寄存器读写、生成注册表、上传及注意事项。
+
+## 案例概述
+
+**设备类型**：电池装配工站  
+**通信方式**：Modbus TCP (PLC)  
+**工站基类**：`WorkstationBase`  
+**主要功能**：电池组装、寄存器读写、数据采集
 
 ## 1. 新建工站文件
 
@@ -39,8 +50,6 @@ class CoinCellAssemblyWorkstation(WorkstationBase):
         self.client = tcp.register_node_list(self.nodes)
 ```
 
-
-
 ## 2. 编写驱动与寄存器读写
 
 ### 2.1 寄存器示例
@@ -84,49 +93,49 @@ def start_and_read_metrics(self):
 
 完成工站类与驱动后，需要生成（或更新）工站注册表供系统识别。
 
-
 ### 3.1 新增工站设备（或资源）首次生成注册表
-首先通过以下命令启动unilab。进入unilab系统状态检查页面
+
+首先通过以下命令启动 unilab。进入 unilab 系统状态检查页面
 
 ```bash
 python unilabos\app\main.py -g celljson.json --ak <user的AK> --sk <user的SK>
 ```
 
 点击注册表编辑，进入注册表编辑页面
-![Layers](image_add_batteryPLC/unilab_sys_status.png)
+
+![系统状态页面](image_battery_plc/unilab_sys_status.png)
 
 按照图示步骤填写自动生成注册表信息：
-![Layers](image_add_batteryPLC/unilab_registry_process.png)
+
+![注册表生成流程](image_battery_plc/unilab_registry_process.png)
 
 步骤说明：
+
 1. 选择新增的工站`coin_cell_assembly.py`文件
 2. 点击分析按钮，分析`coin_cell_assembly.py`文件
 3. 选择`coin_cell_assembly.py`文件中继承`WorkstationBase`类
-4. 填写新增的工站.py文件与`unilabos`目录的距离。例如，新增的工站文件`coin_cell_assembly.py`路径为`unilabos\devices\workstation\coin_cell_assembly\coin_cell_assembly.py`，则此处填写`unilabos.devices.workstation.coin_cell_assembly`。
+4. 填写新增的工站.py 文件与`unilabos`目录的距离。例如，新增的工站文件`coin_cell_assembly.py`路径为`unilabos\devices\workstation\coin_cell_assembly\coin_cell_assembly.py`，则此处填写`unilabos.devices.workstation.coin_cell_assembly`。
 5. 此处填写新定义工站的类的名字（名称可以自拟）
 6. 填写新的工站注册表备注信息
 7. 生成注册表
 
-以上操作步骤完成，则会生成的新的注册表ymal文件，如下图：
-![Layers](image_add_batteryPLC/unilab_new_yaml.png)
-
-
-
-
+以上操作步骤完成，则会生成的新的注册表 YAML 文件，如下图：
 
+![生成的YAML文件](image_battery_plc/unilab_new_yaml.png)
 
 ### 3.2 添加新生成注册表
-在`unilabos\registry\devices`目录下新建一个yaml文件，此处新建文件命名为`coincellassemblyworkstation_device.yaml`，将上面生成的新的注册表信息粘贴到`coincellassemblyworkstation_device.yaml`文件中。   
+
+在`unilabos\registry\devices`目录下新建一个 yaml 文件，此处新建文件命名为`coincellassemblyworkstation_device.yaml`，将上面生成的新的注册表信息粘贴到`coincellassemblyworkstation_device.yaml`文件中。
 
 在终端输入以下命令进行注册表补全操作。
+
 ```bash
 python unilabos\app\register.py --complete_registry
 ```
 
-
 ### 3.3 启动并上传注册表
 
-新增设备之后，启动unilab需要增加`--upload_registry`参数，来上传注册表信息。
+新增设备之后，启动 unilab 需要增加`--upload_registry`参数，来上传注册表信息。
 
 ```bash
 python unilabos\app\main.py -g celljson.json --ak <user的AK> --sk <user的SK> --upload_registry
@@ -134,14 +143,60 @@ python unilabos\app\main.py -g celljson.json --ak <user的AK> --sk <user的SK> -
 
 ## 4. 注意事项
 
-- 在新生成的 YAML 中，确认 `module` 指向新工站类，本例中需检查`coincellassemblyworkstation_device.yaml`文件中是否指向了`coin_cell_assembly.py`文件中定义的`CoinCellAssemblyWorkstation`类文件：
+### 4.1 验证模块路径
 
-```
+在新生成的 YAML 中，确认 `module` 指向新工站类。本例中需检查 `coincellassemblyworkstation_device.yaml` 文件中是否正确指向了 `CoinCellAssemblyWorkstation` 类：
+
+```yaml
 module: unilabos.devices.workstation.coin_cell_assembly.coin_cell_assembly:CoinCellAssemblyWorkstation
 ```
 
-- 首次新增设备（或资源）需要在网页端新增注册表信息，`--complete_registry`补全注册表，`--upload_registry`上传注册表信息。
+### 4.2 首次接入流程
 
-- 如果不是新增设备（或资源），仅对工站驱动的.py文件进行了修改，则不需要在网页端新增注册表信息。只需要运行补全注册表信息之后，上传注册表即可。
+首次新增设备（或资源）需要完整流程：
 
+1. ✅ 在网页端生成注册表信息
+2. ✅ 使用 `--complete_registry` 补全注册表
+3. ✅ 使用 `--upload_registry` 上传注册表信息
 
+### 4.3 驱动更新流程
+
+如果不是新增设备，仅修改了工站驱动的 `.py` 文件：
+
+1. ✅ 运行 `--complete_registry` 补全注册表
+2. ✅ 运行 `--upload_registry` 上传注册表
+3. ❌ 不需要在网页端重新生成注册表
+
+### 4.4 PLC 通信注意事项
+
+- **握手机制**：若需参数下发，建议在 PLC 端设置标志寄存器并完成握手复位，避免粘连与竞争
+- **字节序**：FLOAT32 等多字节数据类型需要正确指定字节序（如 `WorderOrder.LITTLE`）
+- **寄存器映射**：确保 CSV 文件中的寄存器地址与 PLC 实际配置一致
+- **连接稳定性**：在初始化时检查 PLC 连接状态，建议添加重连机制
+
+## 5. 扩展阅读
+
+### 相关文档
+
+- {doc}`../add_device` - 设备驱动编写通用指南
+- {doc}`../add_registry` - 注册表配置完整指南
+- {doc}`../workstation_architecture` - 工站架构详解
+
+### 技术要点
+
+- **Modbus TCP 通信**：PLC 通信协议和寄存器读写
+- **WorkstationBase**：工站基类的继承和使用
+- **寄存器映射**：CSV 格式的寄存器配置
+- **注册表生成**：自动化工具使用
+
+## 6. 总结
+
+通过本案例，你应该掌握：
+
+1. ✅ 如何创建 PLC 控制的工站驱动
+2. ✅ Modbus TCP 通信和寄存器读写
+3. ✅ 使用可视化编辑器生成注册表
+4. ✅ 注册表的补全和上传流程
+5. ✅ 新增设备与更新驱动的区别
+
+这个案例展示了完整的 PLC 设备接入流程，可以作为其他类似设备接入的参考模板。

docs/developer_guide/examples/materials_construction_guide.md

@@ -0,0 +1,409 @@
+# 实例：物料构建指南
+
+> **文档类型**：物料系统实战指南  
+> **适用场景**：工作站物料系统构建、Deck/Warehouse/Carrier/Bottle 配置  
+> **前置知识**：PyLabRobot 基础 | 资源管理概念
+
+## 概述
+
+在UniLab-OS系统中，任何工作站中所需要用到的物料主要包括四个核心组件：
+
+1. **桌子（Deck）** - 工作台面，定义整个工作空间的布局
+2. **堆栈（Warehouse）** - 存储区域，用于放置载具和物料
+3. **载具（Carriers）** - 承载瓶子等物料的容器架
+4. **瓶子（Bottles）** - 实际的物料容器
+
+本文档以BioYond工作站为例，详细说明如何构建这些物料组件。
+
+## 文件结构
+
+物料定义文件位于 `unilabos/resources/` 文件夹中：
+
+```
+unilabos/resources/bioyond/
+├── decks.py              # 桌子定义
+├── YB_warehouses.py      # 堆栈定义
+├── YB_bottle_carriers.py # 载具定义
+└── YB_bottles.py         # 瓶子定义
+```
+
+对应的注册表文件位于 `unilabos/registry/resources/bioyond/` 文件夹中：
+
+```
+unilabos/registry/resources/bioyond/
+├── deck.yaml               # 桌子注册表
+├── YB_bottle_carriers.yaml # 载具注册表
+└── YB_bottle.yaml          # 瓶子注册表
+```
+
+## 1. 桌子（Deck）构建
+
+桌子是整个工作站的基础，定义了工作空间的尺寸和各个组件的位置。
+
+### 代码示例 (decks.py)
+
+```python
+from pylabrobot.resources import Coordinate, Deck
+from unilabos.resources.bioyond.YB_warehouses import (
+    bioyond_warehouse_2x2x1,
+    bioyond_warehouse_3x5x1,
+    bioyond_warehouse_20x1x1,
+    bioyond_warehouse_3x3x1,
+    bioyond_warehouse_10x1x1
+)
+
+class BIOYOND_YB_Deck(Deck):
+    def __init__(
+        self, 
+        name: str = "YB_Deck",
+        size_x: float = 4150,      # 桌子X方向尺寸 (mm)
+        size_y: float = 1400.0,    # 桌子Y方向尺寸 (mm)
+        size_z: float = 2670.0,    # 桌子Z方向尺寸 (mm)
+        category: str = "deck",
+        setup: bool = False
+    ) -> None:
+        super().__init__(name=name, size_x=4150.0, size_y=1400.0, size_z=2670.0)
+        if setup:
+            self.setup() # 当在工作站配置中setup为True时，自动创建并放置所有预定义的堆栈
+
+    def setup(self) -> None:
+        # 定义桌子上的各个仓库区域
+        self.warehouses = {
+            "自动堆栈-左": bioyond_warehouse_2x2x1("自动堆栈-左"),
+            "自动堆栈-右": bioyond_warehouse_2x2x1("自动堆栈-右"),
+            "手动堆栈-左": bioyond_warehouse_3x5x1("手动堆栈-左"),
+            "手动堆栈-右": bioyond_warehouse_3x5x1("手动堆栈-右"),
+            "粉末加样头堆栈": bioyond_warehouse_20x1x1("粉末加样头堆栈"),
+            "配液站内试剂仓库": bioyond_warehouse_3x3x1("配液站内试剂仓库"),
+            "试剂替换仓库": bioyond_warehouse_10x1x1("试剂替换仓库"),
+        }
+  
+        # 定义各个仓库在桌子上的坐标位置
+        self.warehouse_locations = {
+            "自动堆栈-左": Coordinate(-100.3, 171.5, 0.0),
+            "自动堆栈-右": Coordinate(3960.1, 155.9, 0.0),
+            "手动堆栈-左": Coordinate(-213.3, 804.4, 0.0),
+            "手动堆栈-右": Coordinate(3960.1, 807.6, 0.0),
+            "粉末加样头堆栈": Coordinate(415.0, 1301.0, 0.0),
+            "配液站内试剂仓库": Coordinate(2162.0, 437.0, 0.0),
+            "试剂替换仓库": Coordinate(1173.0, 802.0, 0.0),
+        }
+
+        # 将仓库分配到桌子的指定位置
+        for warehouse_name, warehouse in self.warehouses.items():
+            self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name])
+```
+
+### 在工作站配置中的使用
+
+当在工作站配置文件中定义桌子时，可以通过`setup`参数控制是否自动建立所有堆栈：
+
+```json
+{
+  "id": "YB_Bioyond_Deck",
+  "name": "YB_Bioyond_Deck", 
+  "children": [],
+  "parent": "bioyond_cell_workstation",
+  "type": "deck",
+  "class": "BIOYOND_YB_Deck",
+  "config": {
+    "type": "BIOYOND_YB_Deck",
+    "setup": true
+  },
+  "data": {}
+}
+```
+
+**重要说明**：
+- 当 `"setup": true` 时，系统会自动调用桌子的 `setup()` 方法
+- 这将创建并放置所有预定义的堆栈到桌子上的指定位置
+- 如果 `"setup": false` 或省略该参数，则只创建空桌子，需要手动添加堆栈
+
+### 关键要点注释
+
+- `size_x`, `size_y`, `size_z`: 定义桌子的物理尺寸
+- `warehouses`: 字典类型，包含桌子上所有的仓库区域
+- `warehouse_locations`: 定义每个仓库在桌子坐标系中的位置
+- `assign_child_resource()`: 将仓库资源分配到桌子的指定位置
+- `setup()`: 可选的自动设置方法，初始化时可调用
+
+## 2. 堆栈（Warehouse）构建
+
+堆栈定义了存储区域的规格和布局，用于放置载具。
+
+### 代码示例 (YB_warehouses.py)
+
+```python
+from unilabos.resources.warehouse import WareHouse, YB_warehouse_factory
+
+def bioyond_warehouse_1x4x4(name: str) -> WareHouse:
+    """创建BioYond 1x4x4仓库
+  
+    Args:
+        name: 仓库名称
+  
+    Returns:
+        WareHouse: 仓库对象
+    """
+    return YB_warehouse_factory(
+        name=name,
+        num_items_x=1,      # X方向位置数量
+        num_items_y=4,      # Y方向位置数量  
+        num_items_z=4,      # Z方向位置数量（层数）
+        dx=10.0,            # X方向起始偏移
+        dy=10.0,            # Y方向起始偏移
+        dz=10.0,            # Z方向起始偏移
+        item_dx=137.0,      # X方向间距
+        item_dy=96.0,       # Y方向间距
+        item_dz=120.0,      # Z方向间距（层高）
+        category="warehouse",
+    )
+
+def bioyond_warehouse_2x2x1(name: str) -> WareHouse:
+    """创建BioYond 2x2x1仓库（自动堆栈）"""
+    return YB_warehouse_factory(
+        name=name,
+        num_items_x=2,
+        num_items_y=2,
+        num_items_z=1,      # 单层
+        dx=10.0,
+        dy=10.0,
+        dz=10.0,
+        item_dx=137.0,
+        item_dy=96.0,
+        item_dz=120.0,
+        category="YB_warehouse",
+    )
+```
+
+### 关键要点注释
+
+- `num_items_x/y/z`: 定义仓库在各个方向的位置数量
+- `dx/dy/dz`: 第一个位置的起始偏移坐标
+- `item_dx/dy/dz`: 相邻位置之间的间距
+- `category`: 仓库类别，用于分类管理
+- `YB_warehouse_factory`: 统一的仓库创建工厂函数
+
+## 3. 载具（Carriers）构建
+
+载具是承载瓶子的容器架，定义了瓶子的排列方式和位置。
+
+### 代码示例 (YB_bottle_carriers.py)
+
+```python
+from pylabrobot.resources import create_homogeneous_resources, Coordinate, ResourceHolder, create_ordered_items_2d
+from unilabos.resources.itemized_carrier import Bottle, BottleCarrier
+from unilabos.resources.bioyond.YB_bottles import YB_pei_ye_xiao_Bottle
+
+def YB_peiyepingxiaoban(name: str) -> BottleCarrier:
+    """配液瓶(小)板 - 4x2布局，8个位置
+  
+    Args:
+        name: 载具名称
+  
+    Returns:
+        BottleCarrier: 载具对象，包含8个配液瓶位置
+    """
+  
+    # 载具物理尺寸 (mm)
+    carrier_size_x = 127.8
+    carrier_size_y = 85.5
+    carrier_size_z = 65.0
+
+    # 瓶位参数
+    bottle_diameter = 35.0      # 瓶子直径
+    bottle_spacing_x = 42.0     # X方向瓶子间距
+    bottle_spacing_y = 35.0     # Y方向瓶子间距
+
+    # 计算起始位置 (居中排列)
+    start_x = (carrier_size_x - (4 - 1) * bottle_spacing_x - bottle_diameter) / 2
+    start_y = (carrier_size_y - (2 - 1) * bottle_spacing_y - bottle_diameter) / 2
+
+    # 创建瓶位布局：4列x2行
+    sites = create_ordered_items_2d(
+        klass=ResourceHolder,
+        num_items_x=4,          # 4列
+        num_items_y=2,          # 2行
+        dx=start_x,
+        dy=start_y,
+        dz=5.0,                 # 瓶子底部高度
+        item_dx=bottle_spacing_x,
+        item_dy=bottle_spacing_y,
+        size_x=bottle_diameter,
+        size_y=bottle_diameter,
+        size_z=carrier_size_z,
+    )
+  
+    # 为每个瓶位设置名称
+    for k, v in sites.items():
+        v.name = f"{name}_{v.name}"
+
+    # 创建载具对象
+    carrier = BottleCarrier(
+        name=name,
+        size_x=carrier_size_x,
+        size_y=carrier_size_y,
+        size_z=carrier_size_z,
+        sites=sites,
+        model="YB_peiyepingxiaoban",
+    )
+  
+    # 设置载具布局参数
+    carrier.num_items_x = 4
+    carrier.num_items_y = 2
+    carrier.num_items_z = 1
+  
+    # 定义瓶子排列顺序
+    ordering = ["A1", "A2", "A3", "A4", "B1", "B2", "B3", "B4"]
+  
+    # 为每个位置创建瓶子实例
+    for i in range(8):
+        carrier[i] = YB_pei_ye_xiao_Bottle(f"{name}_bottle_{ordering[i]}")
+  
+    return carrier
+```
+
+### 关键要点注释
+
+- `carrier_size_x/y/z`: 载具的物理尺寸
+- `bottle_diameter`: 瓶子的直径，用于计算瓶位大小
+- `bottle_spacing_x/y`: 瓶子之间的间距
+- `create_ordered_items_2d`: 创建二维排列的瓶位
+- `sites`: 瓶位字典，存储所有瓶子位置信息
+- `ordering`: 定义瓶位的命名规则（如A1, A2, B1等）
+
+## 4. 瓶子（Bottles）构建
+
+瓶子是最终的物料容器，定义了容器的物理属性。
+
+### 代码示例 (YB_bottles.py)
+
+```python
+from unilabos.resources.itemized_carrier import Bottle
+
+def YB_pei_ye_xiao_Bottle(
+    name: str,
+    diameter: float = 35.0,         # 瓶子直径 (mm)
+    height: float = 60.0,           # 瓶子高度 (mm)
+    max_volume: float = 30000.0,    # 最大容量 (μL) - 30mL
+    barcode: str = None,            # 条码
+) -> Bottle:
+    """创建配液瓶(小)
+  
+    Args:
+        name: 瓶子名称
+        diameter: 瓶子直径
+        height: 瓶子高度
+        max_volume: 最大容量（微升）
+        barcode: 条码标识
+  
+    Returns:
+        Bottle: 瓶子对象
+    """
+    return Bottle(
+        name=name,
+        diameter=diameter,
+        height=height,
+        max_volume=max_volume,
+        barcode=barcode,
+        model="YB_pei_ye_xiao_Bottle",    
+    )
+
+def YB_ye_Bottle(
+    name: str,
+    diameter: float = 40.0,
+    height: float = 70.0,
+    max_volume: float = 50000.0,    # 最大容量
+    barcode: str = None,
+) -> Bottle:
+    """创建液体瓶"""
+    return Bottle(
+        name=name,
+        diameter=diameter,
+        height=height,
+        max_volume=max_volume,
+        barcode=barcode,
+        model="YB_ye_Bottle",
+    )
+```
+
+### 关键要点注释
+
+- `diameter`: 瓶子直径，影响瓶位大小计算
+- `height`: 瓶子高度，用于碰撞检测和移液计算
+- `max_volume`: 最大容量，单位为微升（μL）
+- `barcode`: 条码标识，用于瓶子追踪
+- `model`: 型号标识，用于区分不同类型的瓶子
+
+## 5. 注册表配置
+
+创建完物料定义后，需要在注册表中注册这些物料，使系统能够识别和使用它们。
+
+在 `unilabos/registry/resources/bioyond/` 目录下创建：
+
+- `deck.yaml` - 桌子注册表
+- `YB_bottle_carriers.yaml` - 载具注册表
+- `YB_bottle.yaml` - 瓶子注册表
+
+### 5.1 桌子注册表 (deck.yaml)
+
+```yaml
+BIOYOND_YB_Deck:
+  category:
+    - deck                          # 前端显示的分类存放
+  class:
+    module: unilabos.resources.bioyond.decks:BIOYOND_YB_Deck  # 定义桌子的类的路径
+    type: pylabrobot              
+  description: BIOYOND_YB_Deck     # 描述信息
+  handles: []                     
+  icon: 配液站.webp               # 图标文件
+  init_param_schema: {}         
+  registry_type: resource         # 注册类型
+  version: 1.0.0                  # 版本号
+```
+
+### 5.2 载具注册表 (YB_bottle_carriers.yaml)
+
+```yaml
+YB_peiyepingxiaoban:
+  category:
+    - yb3                          
+    - YB_bottle_carriers          
+  class:
+    module: unilabos.resources.bioyond.YB_bottle_carriers:YB_peiyepingxiaoban
+    type: pylabrobot
+  description: YB_peiyepingxiaoban  
+  handles: []
+  icon: ''                      
+  init_param_schema: {}
+  registry_type: resource
+  version: 1.0.0
+```
+
+### 5.3 瓶子注册表 (YB_bottle.yaml)
+
+```yaml
+YB_pei_ye_xiao_Bottle:
+  category:
+    - yb3                          
+    - YB_bottle                 
+  class:
+    module: unilabos.resources.bioyond.YB_bottles:YB_pei_ye_xiao_Bottle
+    type: pylabrobot
+  description: YB_pei_ye_xiao_Bottle
+  handles: []
+  icon: ''
+  init_param_schema: {}
+  registry_type: resource
+  version: 1.0.0
+```
+
+### 注册表关键要点注释
+
+- `category`: 物料分类，用于在云端（网页界面）中的分类中显示
+- `module`: Python模块路径，格式为 `模块路径:类名`
+- `type`: 框架类型，通常为 `pylabrobot`（默认即可）
+- `description`: 描述信息，显示在用户界面中
+- `icon`: （名称唯一自动匹配后端上传的图标文件名，显示在云端）
+- `registry_type`: 固定为 `resource`
+- `version`: 版本号，用于版本管理

docs/developer_guide/examples/materials_tutorial.md

@@ -1,6 +1,10 @@
-# 物料教程（Resource）
+# 实例：物料教程（Resource）
 
-本教程面向 Uni-Lab-OS 的开发者，讲解“物料”的核心概念、3种物料格式（UniLab、PyLabRobot、奔耀Bioyond）及其相互转换方法，并说明4种 children 结构表现形式及使用场景。
+> **文档类型**：物料系统完整教程  
+> **适用场景**：物料格式转换、多系统物料对接、资源结构理解  
+> **前置知识**：Python 基础 | JSON 数据结构
+
+本教程面向 Uni-Lab-OS 的开发者，讲解"物料"的核心概念、3种物料格式（UniLab、PyLabRobot、奔耀Bioyond）及其相互转换方法，并说明4种 children 结构表现形式及使用场景。
 
 ---
 

docs/developer_guide/examples/workstation_architecture.md

@@ -0,0 +1,782 @@
+# 实例：工作站模板架构设计与对接指南
+
+> **文档类型**：架构设计指南与实战案例  
+> **适用场景**：大型工作站接入、子设备管理、物料系统集成  
+> **前置知识**：{doc}`../add_device` | {doc}`../add_registry`
+
+## 0. 问题简介
+
+我们可以从以下几类例子，来理解对接大型工作站需要哪些设计。本文档之后的实战案例也将由这些组成。
+
+### 0.1 自研常量有机工站：最重要的是子设备管理和通信转发
+
+![workstation_organic_yed](../image/workstation_architecture/workstation_organic_yed.png)
+
+![workstation_organic](../image/workstation_architecture/workstation_organic.png)
+
+这类工站由开发者自研，组合所有子设备和实验耗材、希望让他们在工作站这一级协调配合；
+
+1. 工作站包含大量已经注册的子设备，可能各自通信组态很不相同；部分设备可能会拥有同一个通信设备作为出口，如 2 个泵共用 1 个串口、所有设备共同接入 PLC 等。
+2. 任务系统是统一实现的 protocols，protocols 中会将高层指令处理成各子设备配合的工作流 json 并管理执行、同时更改物料信息
+3. 物料系统较为简单直接，如常量有机化学仅为工作站内固定的瓶子，初始化时就已固定；随后在任务执行过程中，记录试剂量更改信息
+
+### 0.2 移液工作站：物料系统和工作流模板管理
+
+![workstation_liquid_handler](../image/workstation_architecture/workstation_liquid_handler.png)
+
+1. 绝大多数情况没有子设备，有时候选配恒温震荡等模块时，接口也由工作站提供
+2. 所有任务系统均由工作站本身实现并下发指令，有统一的抽象函数可实现（pick_up_tips, aspirate, dispense, transfer 等）。有时需要将这些指令组合、转化为工作站的脚本语言，再统一下发。因此会形成大量固定的 protocols。
+3. 物料系统为固定的板位系统：台面上有多个可摆放位置，摆放标准孔板。
+
+### 0.3 厂家开发的定制大型工站
+
+![workstation_by_supplier](../image/workstation_architecture/workstation_by_supplier.png)
+
+由厂家开发，具备完善的物料系统、任务系统甚至调度系统；由 PLC 或 OpenAPI TCP 协议统一通信
+
+1. 在监控状态时，希望展现子设备的状态；但子设备仅为逻辑概念，通信由工作站上位机接口提供；部分情况下，子设备状态是被记录在文件中的，需要读取
+2. 工作站有自己的工作流系统甚至调度系统；可以通过脚本/PLC 连续读写来配置工作站可用的工作流；
+3. 部分拥有完善的物料入库、出库、过程记录，需要与 Uni-Lab-OS 物料系统对接
+
+## 1. 整体架构图
+
+### 1.1 工作站核心架构
+
+```{mermaid}
+graph TB
+    subgraph "工作站模板组成"
+        WB[WorkstationBase<br/>工作流状态管理]
+        RPN[ROS2WorkstationNode<br/>Protocol执行引擎]
+        WB -.post_init关联.-> RPN
+    end
+
+    subgraph "物料管理系统"
+        DECK[Deck<br/>PLR本地物料系统]
+        RS[ResourceSynchronizer<br/>外部物料同步器]
+        WB --> DECK
+        WB --> RS
+        RS --> DECK
+    end
+
+    subgraph "通信与子设备管理"
+        HW[hardware_interface<br/>硬件通信接口]
+        SUBDEV[子设备集合<br/>pumps/grippers/sensors]
+        WB --> HW
+        RPN --> SUBDEV
+        HW -.代理模式.-> RPN
+    end
+
+    subgraph "工作流任务系统"
+        PROTO[Protocol定义<br/>LiquidHandling/PlateHandling]
+        WORKFLOW[Workflow执行器<br/>步骤管理与编排]
+        RPN --> PROTO
+        RPN --> WORKFLOW
+        WORKFLOW --> SUBDEV
+    end
+```
+
+### 1.2 外部系统对接关系
+
+```{mermaid}
+graph LR
+    subgraph "Uni-Lab-OS工作站"
+        WS[WorkstationBase + ROS2WorkstationNode]
+        DECK2[物料系统<br/>Deck]
+        HW2[通信接口<br/>hardware_interface]
+        HTTP[HTTP服务<br/>WorkstationHTTPService]
+    end
+
+    subgraph "外部物料系统"
+        BIOYOND[Bioyond物料管理]
+        LIMS[LIMS系统]
+        WAREHOUSE[第三方仓储]
+    end
+
+    subgraph "外部硬件系统"
+        PLC[PLC设备]
+        SERIAL[串口设备]
+        ROBOT[机械臂/机器人]
+    end
+
+    subgraph "云端系统"
+        CLOUD[UniLab云端<br/>资源管理]
+        MONITOR[监控与调度]
+    end
+
+    BIOYOND <-->|RPC双向同步| DECK2
+    LIMS -->|HTTP报送| HTTP
+    WAREHOUSE <-->|API对接| DECK2
+
+    PLC <-->|Modbus TCP| HW2
+    SERIAL <-->|串口通信| HW2
+    ROBOT <-->|SDK/API| HW2
+
+    WS -->|ROS消息| CLOUD
+    CLOUD -->|任务下发| WS
+    MONITOR -->|状态查询| WS
+```
+
+### 1.3 具体实现示例
+
+```{mermaid}
+graph TB
+    subgraph "工作站基类"
+        BASE[WorkstationBase<br/>抽象基类]
+    end
+
+    subgraph "Bioyond集成工作站"
+        BW[BioyondWorkstation]
+        BW_DECK[Deck + Warehouses]
+        BW_SYNC[BioyondResourceSynchronizer]
+        BW_HW[BioyondV1RPC]
+        BW_HTTP[HTTP报送服务]
+
+        BW --> BW_DECK
+        BW --> BW_SYNC
+        BW --> BW_HW
+        BW --> BW_HTTP
+    end
+
+    subgraph "纯协议节点"
+        PN[ProtocolNode]
+        PN_SUB[子设备集合]
+        PN_PROTO[Protocol工作流]
+
+        PN --> PN_SUB
+        PN --> PN_PROTO
+    end
+
+    subgraph "PLC控制工作站"
+        PW[PLCWorkstation]
+        PW_DECK[Deck物料系统]
+        PW_PLC[Modbus PLC客户端]
+        PW_WF[工作流定义]
+
+        PW --> PW_DECK
+        PW --> PW_PLC
+        PW --> PW_WF
+    end
+
+    BASE -.继承.-> BW
+    BASE -.继承.-> PN
+    BASE -.继承.-> PW
+```
+
+## 2. 类关系图
+
+```{mermaid}
+classDiagram
+    class WorkstationBase {
+        <<abstract>>
+        +_ros_node: ROS2WorkstationNode
+        +deck: Deck
+        +plr_resources: Dict[str, PLRResource]
+        +resource_synchronizer: ResourceSynchronizer
+        +hardware_interface: Union[Any, str]
+        +current_workflow_status: WorkflowStatus
+        +supported_workflows: Dict[str, WorkflowInfo]
+
+        +post_init(ros_node)*
+        +set_hardware_interface(interface)
+        +call_device_method(method, *args, **kwargs)
+        +get_device_status()
+        +is_device_available()
+
+        +get_deck()
+        +get_all_resources()
+        +find_resource_by_name(name)
+        +find_resources_by_type(type)
+        +sync_with_external_system()
+
+        +execute_workflow(name, params)
+        +stop_workflow(emergency)
+        +workflow_status
+        +is_busy
+    }
+
+    class ROS2WorkstationNode {
+        +device_id: str
+        +children: Dict[str, Any]
+        +sub_devices: Dict
+        +protocol_names: List[str]
+        +_action_clients: Dict
+        +_action_servers: Dict
+        +resource_tracker: DeviceNodeResourceTracker
+
+        +initialize_device(device_id, config)
+        +create_ros_action_server(action_name, mapping)
+        +execute_single_action(device_id, action, kwargs)
+        +update_resource(resources)
+        +transfer_resource_to_another(resources, target, sites)
+        +_setup_hardware_proxy(device, comm_device, read, write)
+    }
+
+    %% 物料管理相关类
+    class Deck {
+        +name: str
+        +children: List
+        +assign_child_resource()
+    }
+
+    class ResourceSynchronizer {
+        <<abstract>>
+        +workstation: WorkstationBase
+        +sync_from_external()*
+        +sync_to_external(plr_resource)*
+        +handle_external_change(change_info)*
+    }
+
+    class BioyondResourceSynchronizer {
+        +bioyond_api_client: BioyondV1RPC
+        +sync_interval: int
+        +last_sync_time: float
+
+        +initialize()
+        +sync_from_external()
+        +sync_to_external(resource)
+        +handle_external_change(change_info)
+    }
+
+    %% 硬件接口相关类
+    class HardwareInterface {
+        <<interface>>
+    }
+
+    class BioyondV1RPC {
+        +base_url: str
+        +api_key: str
+        +stock_material()
+        +add_material()
+        +material_inbound()
+    }
+
+    %% 服务类
+    class WorkstationHTTPService {
+        +workstation: WorkstationBase
+        +host: str
+        +port: int
+        +server: HTTPServer
+        +running: bool
+
+        +start()
+        +stop()
+        +_handle_step_finish_report()
+        +_handle_sample_finish_report()
+        +_handle_order_finish_report()
+        +_handle_material_change_report()
+        +_handle_error_handling_report()
+    }
+
+    %% 具体实现类
+    class BioyondWorkstation {
+        +bioyond_config: Dict
+        +workflow_mappings: Dict
+        +workflow_sequence: List
+
+        +post_init(ros_node)
+        +transfer_resource_to_another()
+        +resource_tree_add(resources)
+        +append_to_workflow_sequence(name)
+        +get_all_workflows()
+        +get_bioyond_status()
+    }
+
+    class ProtocolNode {
+        +post_init(ros_node)
+    }
+
+    %% 核心关系
+    WorkstationBase o-- ROS2WorkstationNode : post_init关联
+    WorkstationBase o-- WorkstationHTTPService : 可选服务
+
+    %% 物料管理侧
+    WorkstationBase *-- Deck : deck
+    WorkstationBase *-- ResourceSynchronizer : 可选组合
+    ResourceSynchronizer <|-- BioyondResourceSynchronizer
+
+    %% 硬件接口侧
+    WorkstationBase o-- HardwareInterface : hardware_interface
+    HardwareInterface <|.. BioyondV1RPC : 实现
+    BioyondResourceSynchronizer --> BioyondV1RPC : 使用
+
+    %% 继承关系
+    BioyondWorkstation --|> WorkstationBase
+    ProtocolNode --|> WorkstationBase
+    ROS2WorkstationNode --|> BaseROS2DeviceNode : 继承
+```
+
+## 3. 工作站启动时序图
+
+```{mermaid}
+sequenceDiagram
+    participant APP as Application
+    participant WS as WorkstationBase
+    participant DECK as PLR Deck
+    participant SYNC as ResourceSynchronizer
+    participant HW as HardwareInterface
+    participant ROS as ROS2WorkstationNode
+    participant HTTP as HTTPService
+
+    APP->>WS: 创建工作站实例(__init__)
+    WS->>DECK: 初始化PLR Deck
+    DECK->>DECK: 创建Warehouse等子资源
+    DECK-->>WS: Deck创建完成
+
+    WS->>HW: 创建硬件接口(如BioyondV1RPC)
+    HW->>HW: 建立连接(PLC/RPC/串口等)
+    HW-->>WS: 硬件接口就绪
+
+    WS->>SYNC: 创建ResourceSynchronizer(可选)
+    SYNC->>HW: 使用hardware_interface
+    SYNC->>SYNC: 初始化同步配置
+    SYNC-->>WS: 同步器创建完成
+
+    WS->>SYNC: sync_from_external()
+    SYNC->>HW: 查询外部物料系统
+    HW-->>SYNC: 返回物料数据
+    SYNC->>DECK: 转换并添加到Deck
+    SYNC-->>WS: 同步完成
+
+    Note over WS: __init__完成,等待ROS节点
+
+    APP->>ROS: 初始化ROS2WorkstationNode
+    ROS->>ROS: 初始化子设备(children)
+    ROS->>ROS: 创建Action客户端
+    ROS->>ROS: 设置硬件接口代理
+    ROS-->>APP: ROS节点就绪
+
+    APP->>WS: post_init(ros_node)
+    WS->>WS: self._ros_node = ros_node
+    WS->>ROS: update_resource([deck])
+    ROS->>ROS: 上传物料到云端
+    ROS-->>WS: 上传完成
+
+    WS->>HTTP: 创建WorkstationHTTPService(可选)
+    HTTP->>HTTP: 启动HTTP服务器线程
+    HTTP-->>WS: HTTP服务启动
+
+    WS-->>APP: 工作站完全就绪
+```
+
+## 4. 工作流执行时序图（Protocol 模式）
+
+```{mermaid}
+sequenceDiagram
+    participant CLIENT as 客户端
+    participant ROS as ROS2WorkstationNode
+    participant WS as WorkstationBase
+    participant HW as HardwareInterface
+    participant DECK as PLR Deck
+    participant CLOUD as 云端资源管理
+    participant DEV as 子设备
+
+    CLIENT->>ROS: 发送Protocol Action请求
+    ROS->>ROS: execute_protocol回调
+    ROS->>ROS: 从Goal提取参数
+    ROS->>ROS: 调用protocol_steps_generator
+    ROS->>ROS: 生成action步骤列表
+
+    ROS->>WS: 更新workflow_status = RUNNING
+
+    loop 执行每个步骤
+        alt 调用子设备
+            ROS->>ROS: execute_single_action(device_id, action, params)
+            ROS->>DEV: 发送Action Goal(通过Action Client)
+            DEV->>DEV: 执行设备动作
+            DEV-->>ROS: 返回Result
+        else 调用工作站自身
+            ROS->>WS: call_device_method(method, *args)
+            alt 直接模式
+                WS->>HW: 调用hardware_interface方法
+                HW->>HW: 执行硬件操作
+                HW-->>WS: 返回结果
+            else 代理模式
+                WS->>ROS: 转发到子设备
+                ROS->>DEV: 调用子设备方法
+                DEV-->>ROS: 返回结果
+                ROS-->>WS: 返回结果
+            end
+            WS-->>ROS: 返回结果
+        end
+
+        ROS->>DECK: 更新本地物料状态
+        DECK->>DECK: 修改PLR资源属性
+    end
+
+    ROS->>CLOUD: 同步物料到云端(可选)
+    CLOUD-->>ROS: 同步完成
+
+    ROS->>WS: 更新workflow_status = COMPLETED
+    ROS-->>CLIENT: 返回Protocol Result
+```
+
+## 5. HTTP 报送处理时序图
+
+```{mermaid}
+sequenceDiagram
+    participant EXT as 外部工作站/LIMS
+    participant HTTP as HTTPService
+    participant WS as WorkstationBase
+    participant DECK as PLR Deck
+    participant SYNC as ResourceSynchronizer
+    participant CLOUD as 云端
+
+    EXT->>HTTP: POST /report/step_finish
+    HTTP->>HTTP: 解析请求数据
+    HTTP->>HTTP: 验证LIMS协议字段
+    HTTP->>WS: process_step_finish_report(request)
+
+    WS->>WS: 增加接收计数(_reports_received_count++)
+    WS->>WS: 记录步骤完成事件
+    WS->>DECK: 更新相关物料状态(可选)
+    DECK->>DECK: 修改PLR资源状态
+
+    WS->>WS: 保存报送记录到内存
+
+    WS-->>HTTP: 返回处理结果
+    HTTP->>HTTP: 构造HTTP响应
+    HTTP-->>EXT: 200 OK + acknowledgment_id
+
+    Note over EXT,CLOUD: 类似处理sample_finish, order_finish等报送
+
+    alt 物料变更报送
+        EXT->>HTTP: POST /report/material_change
+        HTTP->>WS: process_material_change_report(data)
+        WS->>DECK: 查找或创建物料
+        WS->>SYNC: sync_to_external(resource)
+        SYNC->>SYNC: 同步到外部系统(如Bioyond)
+        SYNC-->>WS: 同步完成
+        WS->>CLOUD: update_resource(通过ROS节点)
+        CLOUD-->>WS: 上传完成
+        WS-->>HTTP: 返回结果
+        HTTP-->>EXT: 200 OK
+    end
+```
+
+## 6. 错误处理时序图
+
+```{mermaid}
+sequenceDiagram
+    participant DEV as 子设备/外部系统
+    participant ROS as ROS2WorkstationNode
+    participant WS as WorkstationBase
+    participant HW as HardwareInterface
+    participant HTTP as HTTPService
+    participant LOG as 日志系统
+
+    alt 设备错误(ROS Action失败)
+        DEV->>ROS: Action返回失败结果
+        ROS->>ROS: 记录错误信息
+        ROS->>WS: 更新workflow_status = ERROR
+        ROS->>LOG: 记录错误日志
+    else 外部系统错误报送
+        DEV->>HTTP: POST /report/error_handling
+        HTTP->>WS: handle_external_error(error_data)
+        WS->>WS: 记录错误历史
+        WS->>LOG: 记录错误日志
+    end
+
+    alt 关键错误需要停止
+        WS->>ROS: stop_workflow(emergency=True)
+        ROS->>ROS: 取消所有进行中的Action
+        ROS->>HW: 调用emergency_stop()(如果支持)
+        HW->>HW: 执行紧急停止
+        WS->>WS: 更新workflow_status = ERROR
+    else 可恢复错误
+        WS->>WS: 标记步骤失败
+        WS->>ROS: 触发重试逻辑(可选)
+        ROS->>DEV: 重新发送Action
+    end
+
+    WS-->>HTTP: 返回错误处理结果
+    HTTP-->>DEV: 200 OK + 处理状态
+```
+
+## 7. 典型工作站实现示例
+
+### 7.1 Bioyond 集成工作站实现
+
+```python
+class BioyondWorkstation(WorkstationBase):
+    def __init__(self, bioyond_config: Dict, deck: Deck, *args, **kwargs):
+        # 初始化deck
+        super().__init__(deck=deck, *args, **kwargs)
+
+        # 设置硬件接口为Bioyond RPC客户端
+        self.hardware_interface = BioyondV1RPC(bioyond_config)
+
+        # 创建资源同步器
+        self.resource_synchronizer = BioyondResourceSynchronizer(self)
+
+        # 从Bioyond同步物料到本地deck
+        self.resource_synchronizer.sync_from_external()
+
+        # 配置工作流
+        self.workflow_mappings = bioyond_config.get("workflow_mappings", {})
+
+    def post_init(self, ros_node: ROS2WorkstationNode):
+        """ROS节点就绪后的初始化"""
+        self._ros_node = ros_node
+
+        # 上传deck(包括所有物料)到云端
+        ROS2DeviceNode.run_async_func(
+            self._ros_node.update_resource,
+            True,
+            resources=[self.deck]
+        )
+
+    def resource_tree_add(self, resources: List[ResourcePLR]):
+        """添加物料并同步到Bioyond"""
+        for resource in resources:
+            self.deck.assign_child_resource(resource, location)
+            self.resource_synchronizer.sync_to_external(resource)
+```
+
+### 7.2 纯协议节点实现
+
+```python
+class ProtocolNode(WorkstationBase):
+    """纯协议节点,不需要物料管理和外部通信"""
+
+    def __init__(self, deck: Optional[Deck] = None, *args, **kwargs):
+        super().__init__(deck=deck, *args, **kwargs)
+        # 不设置hardware_interface和resource_synchronizer
+        # 所有功能通过子设备协同完成
+
+    def post_init(self, ros_node: ROS2WorkstationNode):
+        self._ros_node = ros_node
+        # 不需要上传物料或其他初始化
+```
+
+### 7.3 PLC 直接控制工作站
+
+```python
+class PLCWorkstation(WorkstationBase):
+    def __init__(self, plc_config: Dict, deck: Deck, *args, **kwargs):
+        super().__init__(deck=deck, *args, **kwargs)
+
+        # 设置硬件接口为Modbus客户端
+        from pymodbus.client import ModbusTcpClient
+        self.hardware_interface = ModbusTcpClient(
+            host=plc_config["host"],
+            port=plc_config["port"]
+        )
+        self.hardware_interface.connect()
+
+        # 定义支持的工作流
+        self.supported_workflows = {
+            "battery_assembly": WorkflowInfo(
+                name="电池组装",
+                description="自动化电池组装流程",
+                estimated_duration=300.0,
+                required_materials=["battery_cell", "connector"],
+                output_product="battery_pack",
+                parameters_schema={"quantity": int, "model": str}
+            )
+        }
+
+    def execute_workflow(self, workflow_name: str, parameters: Dict):
+        """通过PLC执行工作流"""
+        workflow_id = self._get_workflow_id(workflow_name)
+
+        # 写入PLC寄存器启动工作流
+        self.hardware_interface.write_register(100, workflow_id)
+        self.hardware_interface.write_register(101, parameters["quantity"])
+
+        self.current_workflow_status = WorkflowStatus.RUNNING
+        return True
+```
+
+## 8. 核心接口说明
+
+### 8.1 WorkstationBase 核心属性
+
+| 属性                      | 类型                    | 说明                            |
+| ------------------------- | ----------------------- | ------------------------------- |
+| `_ros_node`               | ROS2WorkstationNode     | ROS 节点引用，由 post_init 设置 |
+| `deck`                    | Deck                    | PyLabRobot Deck，本地物料系统   |
+| `plr_resources`           | Dict[str, PLRResource]  | 物料资源映射                    |
+| `resource_synchronizer`   | ResourceSynchronizer    | 外部物料同步器(可选)            |
+| `hardware_interface`      | Union[Any, str]         | 硬件接口或代理字符串            |
+| `current_workflow_status` | WorkflowStatus          | 当前工作流状态                  |
+| `supported_workflows`     | Dict[str, WorkflowInfo] | 支持的工作流定义                |
+
+### 8.2 必须实现的方法
+
+- `post_init(ros_node)`: ROS 节点就绪后的初始化，必须实现
+
+### 8.3 硬件接口相关方法
+
+- `set_hardware_interface(interface)`: 设置硬件接口
+- `call_device_method(method, *args, **kwargs)`: 统一设备方法调用
+  - 支持直接模式: 直接调用 hardware_interface 的方法
+  - 支持代理模式: hardware_interface="proxy:device_id"通过 ROS 转发
+- `get_device_status()`: 获取设备状态
+- `is_device_available()`: 检查设备可用性
+
+### 8.4 物料管理方法
+
+- `get_deck()`: 获取 PLR Deck
+- `get_all_resources()`: 获取所有物料
+- `find_resource_by_name(name)`: 按名称查找物料
+- `find_resources_by_type(type)`: 按类型查找物料
+- `sync_with_external_system()`: 触发外部同步
+
+### 8.5 工作流控制方法
+
+- `execute_workflow(name, params)`: 执行工作流
+- `stop_workflow(emergency)`: 停止工作流
+- `workflow_status`: 获取工作流状态(属性)
+- `is_busy`: 检查是否忙碌(属性)
+- `workflow_runtime`: 获取运行时间(属性)
+
+### 8.6 可选的 HTTP 报送处理方法
+
+- `process_step_finish_report()`: 步骤完成处理
+- `process_sample_finish_report()`: 样本完成处理
+- `process_order_finish_report()`: 订单完成处理
+- `process_material_change_report()`: 物料变更处理
+- `handle_external_error()`: 错误处理
+
+### 8.7 ROS2WorkstationNode 核心方法
+
+- `initialize_device(device_id, config)`: 初始化子设备
+- `create_ros_action_server(action_name, mapping)`: 创建 Action 服务器
+- `execute_single_action(device_id, action, kwargs)`: 执行单个动作
+- `update_resource(resources)`: 同步物料到云端
+- `transfer_resource_to_another(...)`: 跨设备物料转移
+
+## 9. 配置参数说明
+
+### 9.1 工作站初始化配置
+
+```python
+# 示例1: Bioyond集成工作站
+bioyond_config = {
+    "base_url": "http://192.168.1.100:8080",
+    "api_key": "your_api_key",
+    "sync_interval": 600,  # 同步间隔(秒)
+    "workflow_mappings": {
+        "样品制备": "workflow_uuid_1",
+        "质检流程": "workflow_uuid_2"
+    },
+    "material_type_mappings": {
+        "plate": "板",
+        "tube": "试管"
+    },
+    "warehouse_mapping": {
+        "冷藏区": {
+            "uuid": "warehouse_uuid_1",
+            "locations": {...}
+        }
+    }
+}
+
+# 创建Deck
+from pylabrobot.resources import Deck
+deck = Deck(name="main_deck", size_x=1000, size_y=800, size_z=200)
+
+workstation = BioyondWorkstation(
+    bioyond_config=bioyond_config,
+    deck=deck
+)
+```
+
+### 9.2 子设备配置(children)
+
+```python
+# 在devices.json中配置
+{
+    "bioyond_workstation": {
+        "type": "protocol",  # 表示这是工作站节点
+        "protocol_type": ["LiquidHandling", "PlateHandling"],
+        "children": {
+            "pump_1": {
+                "type": "device",
+                "driver": "TricontInnovaDriver",
+                "communication": "serial_1",
+                "config": {...}
+            },
+            "gripper_1": {
+                "type": "device",
+                "driver": "RobotiqGripperDriver",
+                "communication": "io_modbus_1",
+                "config": {...}
+            },
+            "serial_1": {
+                "type": "communication",
+                "protocol": "serial",
+                "port": "/dev/ttyUSB0",
+                "baudrate": 9600
+            },
+            "io_modbus_1": {
+                "type": "communication",
+                "protocol": "modbus_tcp",
+                "host": "192.168.1.101",
+                "port": 502
+            }
+        }
+    }
+}
+```
+
+### 9.3 HTTP 服务配置
+
+```python
+from unilabos.devices.workstation.workstation_http_service import WorkstationHTTPService
+
+# 创建HTTP服务(可选)
+http_service = WorkstationHTTPService(
+    workstation_instance=workstation,
+    host="0.0.0.0",  # 监听所有网卡
+    port=8081
+)
+http_service.start()
+```
+
+## 10. 架构设计特点总结
+
+这个简化后的架构设计具有以下特点：
+
+### 10.1 清晰的职责分离
+
+- **WorkstationBase**: 负责物料管理(deck)、硬件接口(hardware_interface)、工作流状态管理
+- **ROS2WorkstationNode**: 负责子设备管理、Protocol 执行、云端物料同步
+- **ResourceSynchronizer**: 可选的外部物料系统同步(如 Bioyond)
+- **WorkstationHTTPService**: 可选的 HTTP 报送接收服务
+
+### 10.2 灵活的硬件接口模式
+
+1. **直接模式**: hardware_interface 是具体对象(如 BioyondV1RPC、ModbusClient)
+2. **代理模式**: hardware_interface="proxy:device_id"，通过 ROS 节点转发到子设备
+3. **混合模式**: 工作站有自己的接口，同时管理多个子设备
+
+### 10.3 统一的物料系统
+
+- 基于 PyLabRobot Deck 的标准化物料表示
+- 通过 ResourceSynchronizer 实现与外部系统(如 Bioyond、LIMS)的双向同步
+- 通过 ROS2WorkstationNode 实现与云端的物料状态同步
+
+### 10.4 Protocol 驱动的工作流
+
+- ROS2WorkstationNode 负责 Protocol 的执行和步骤管理
+- 支持子设备协同(通过 Action Client 调用)
+- 支持工作站直接控制(通过 hardware_interface)
+
+### 10.5 可选的 HTTP 报送服务
+
+- 基于 LIMS 协议规范的统一报送接口
+- 支持步骤完成、样本完成、任务完成、物料变更等多种报送类型
+- 与工作站解耦，可独立启停
+
+### 10.6 简化的初始化流程
+
+```
+1. __init__: 创建deck、设置hardware_interface、创建resource_synchronizer
+2. 从外部系统同步物料(如果有)
+3. ROS节点初始化子设备
+4. post_init: 关联ROS节点、上传物料到云端
+5. (可选)启动HTTP服务
+```
+
+这种设计既保持了灵活性，又避免了过度抽象，更适合实际的工作站对接场景。

docs/developer_guide/http_api.md

@@ -0,0 +1,334 @@
+# HTTP API 指南
+
+本文档介绍如何通过 HTTP API 与 Uni-Lab-OS 进行交互，包括查询设备、提交任务和获取结果。
+
+## 概述
+
+Uni-Lab-OS 提供 RESTful HTTP API，允许外部系统通过标准 HTTP 请求控制实验室设备。API 基于 FastAPI 构建，默认运行在 `http://localhost:8002`。
+
+### 基础信息
+
+- **Base URL**: `http://localhost:8002/api/v1`
+- **Content-Type**: `application/json`
+- **响应格式**: JSON
+
+### 通用响应结构
+
+```json
+{
+    "code": 0,
+    "data": { ... },
+    "message": "success"
+}
+```
+
+| 字段      | 类型   | 说明               |
+| --------- | ------ | ------------------ |
+| `code`    | int    | 状态码，0 表示成功 |
+| `data`    | object | 响应数据           |
+| `message` | string | 响应消息           |
+
+## 快速开始
+
+以下是一个完整的工作流示例：查询设备 → 获取动作 → 提交任务 → 获取结果。
+
+### 步骤 1: 获取在线设备
+
+```bash
+curl -X GET "http://localhost:8002/api/v1/online-devices"
+```
+
+**响应示例**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "online_devices": {
+      "host_node": {
+        "device_key": "/host_node",
+        "namespace": "",
+        "machine_name": "本地",
+        "uuid": "xxx-xxx-xxx",
+        "node_name": "host_node"
+      }
+    },
+    "total_count": 1,
+    "timestamp": 1732612345.123
+  },
+  "message": "success"
+}
+```
+
+### 步骤 2: 获取设备可用动作
+
+```bash
+curl -X GET "http://localhost:8002/api/v1/devices/host_node/actions"
+```
+
+**响应示例**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "device_id": "host_node",
+    "actions": {
+      "test_latency": {
+        "type_name": "unilabos_msgs.action._empty_in.EmptyIn",
+        "type_name_convert": "unilabos_msgs/action/_empty_in/EmptyIn",
+        "action_path": "/devices/host_node/test_latency",
+        "goal_info": "{}",
+        "is_busy": false,
+        "current_job_id": null
+      },
+      "create_resource": {
+        "type_name": "unilabos_msgs.action._resource_create_from_outer_easy.ResourceCreateFromOuterEasy",
+        "action_path": "/devices/host_node/create_resource",
+        "goal_info": "{res_id: '', device_id: '', class_name: '', ...}",
+        "is_busy": false,
+        "current_job_id": null
+      }
+    },
+    "action_count": 5
+  },
+  "message": "success"
+}
+```
+
+**动作状态字段说明**:
+
+| 字段             | 说明                          |
+| ---------------- | ----------------------------- |
+| `type_name`      | 动作类型的完整名称            |
+| `action_path`    | ROS2 动作路径                 |
+| `goal_info`      | 动作参数模板                  |
+| `is_busy`        | 动作是否正在执行              |
+| `current_job_id` | 当前执行的任务 ID（如果繁忙） |
+
+### 步骤 3: 提交任务
+
+```bash
+curl -X POST "http://localhost:8002/api/v1/job/add" \
+  -H "Content-Type: application/json" \
+  -d '{"device_id":"host_node","action":"test_latency","action_args":{}}'
+```
+
+**请求体**:
+
+```json
+{
+  "device_id": "host_node",
+  "action": "test_latency",
+  "action_args": {}
+}
+```
+
+**请求参数说明**:
+
+| 字段          | 类型   | 必填 | 说明                               |
+| ------------- | ------ | ---- | ---------------------------------- |
+| `device_id`   | string | ✓    | 目标设备 ID                        |
+| `action`      | string | ✓    | 动作名称                           |
+| `action_args` | object | ✓    | 动作参数（根据动作类型不同而变化） |
+
+**响应示例**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "b6acb586-733a-42ab-9f73-55c9a52aa8bd",
+    "status": 1,
+    "result": {}
+  },
+  "message": "success"
+}
+```
+
+**任务状态码**:
+
+| 状态码 | 含义      | 说明                           |
+| ------ | --------- | ------------------------------ |
+| 0      | UNKNOWN   | 未知状态                       |
+| 1      | ACCEPTED  | 任务已接受，等待执行           |
+| 2      | EXECUTING | 任务执行中                     |
+| 3      | CANCELING | 任务取消中                     |
+| 4      | SUCCEEDED | 任务成功完成                   |
+| 5      | CANCELED  | 任务已取消                     |
+| 6      | ABORTED   | 任务中止（设备繁忙或执行失败） |
+
+### 步骤 4: 查询任务状态和结果
+
+```bash
+curl -X GET "http://localhost:8002/api/v1/job/b6acb586-733a-42ab-9f73-55c9a52aa8bd/status"
+```
+
+**响应示例（执行中）**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "b6acb586-733a-42ab-9f73-55c9a52aa8bd",
+    "status": 2,
+    "result": {}
+  },
+  "message": "success"
+}
+```
+
+**响应示例（执行完成）**:
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "b6acb586-733a-42ab-9f73-55c9a52aa8bd",
+    "status": 4,
+    "result": {
+      "error": "",
+      "suc": true,
+      "return_value": {
+        "avg_rtt_ms": 103.99,
+        "avg_time_diff_ms": 7181.55,
+        "max_time_error_ms": 7210.57,
+        "task_delay_ms": -1,
+        "raw_delay_ms": 33.19,
+        "test_count": 5,
+        "status": "success"
+      }
+    }
+  },
+  "message": "success"
+}
+```
+
+> **注意**: 任务结果在首次查询后会被自动删除，请确保保存返回的结果数据。
+
+## API 端点列表
+
+### 设备相关
+
+| 端点                                                       | 方法 | 说明                   |
+| ---------------------------------------------------------- | ---- | ---------------------- |
+| `/api/v1/online-devices`                                   | GET  | 获取在线设备列表       |
+| `/api/v1/devices`                                          | GET  | 获取设备配置           |
+| `/api/v1/devices/{device_id}/actions`                      | GET  | 获取指定设备的可用动作 |
+| `/api/v1/devices/{device_id}/actions/{action_name}/schema` | GET  | 获取动作参数 Schema    |
+| `/api/v1/actions`                                          | GET  | 获取所有设备的可用动作 |
+
+### 任务相关
+
+| 端点                          | 方法 | 说明               |
+| ----------------------------- | ---- | ------------------ |
+| `/api/v1/job/add`             | POST | 提交新任务         |
+| `/api/v1/job/{job_id}/status` | GET  | 查询任务状态和结果 |
+
+### 资源相关
+
+| 端点                | 方法 | 说明         |
+| ------------------- | ---- | ------------ |
+| `/api/v1/resources` | GET  | 获取资源列表 |
+
+## 常见动作示例
+
+### test_latency - 延迟测试
+
+测试系统延迟，无需参数。
+
+```bash
+curl -X POST "http://localhost:8002/api/v1/job/add" \
+  -H "Content-Type: application/json" \
+  -d '{"device_id":"host_node","action":"test_latency","action_args":{}}'
+```
+
+### create_resource - 创建资源
+
+在设备上创建新资源。
+
+```bash
+curl -X POST "http://localhost:8002/api/v1/job/add" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "device_id": "host_node",
+    "action": "create_resource",
+    "action_args": {
+        "res_id": "my_plate",
+        "device_id": "host_node",
+        "class_name": "Plate",
+        "parent": "deck",
+        "bind_locations": {"x": 0, "y": 0, "z": 0}
+    }
+}'
+```
+
+## 错误处理
+
+### 设备繁忙
+
+当设备正在执行其他任务时，提交新任务会返回 `status: 6`（ABORTED）：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "jobId": "xxx",
+    "status": 6,
+    "result": {}
+  },
+  "message": "success"
+}
+```
+
+此时应等待当前任务完成后重试，或使用 `/devices/{device_id}/actions` 检查动作的 `is_busy` 状态。
+
+### 参数错误
+
+```json
+{
+    "code": 2002,
+    "data": { ... },
+    "message": "device_id is required"
+}
+```
+
+## 轮询策略
+
+推荐的任务状态轮询策略：
+
+```python
+import requests
+import time
+
+def wait_for_job(job_id, timeout=60, interval=0.5):
+    """等待任务完成并返回结果"""
+    start_time = time.time()
+
+    while time.time() - start_time < timeout:
+        response = requests.get(f"http://localhost:8002/api/v1/job/{job_id}/status")
+        data = response.json()["data"]
+
+        status = data["status"]
+        if status in (4, 5, 6):  # SUCCEEDED, CANCELED, ABORTED
+            return data
+
+        time.sleep(interval)
+
+    raise TimeoutError(f"Job {job_id} did not complete within {timeout} seconds")
+
+# 使用示例
+response = requests.post(
+    "http://localhost:8002/api/v1/job/add",
+    json={"device_id": "host_node", "action": "test_latency", "action_args": {}}
+)
+job_id = response.json()["data"]["jobId"]
+result = wait_for_job(job_id)
+print(result)
+```
+
+## 相关文档
+
+- [设备注册指南](add_device.md)
+- [动作定义指南](add_action.md)
+- [网络架构概述](networking_overview.md)

docs/developer_guide/networking_overview.md

@@ -0,0 +1,594 @@
+# 组网部署与主从模式配置
+
+本文档介绍 Uni-Lab-OS 的组网架构、部署方式和主从模式的详细配置。
+
+## 目录
+
+- [架构概览](#架构概览)
+- [节点类型](#节点类型)
+- [通信机制](#通信机制)
+- [典型拓扑](#典型拓扑)
+- [主从模式配置](#主从模式配置)
+- [网络配置](#网络配置)
+- [示例：多房间部署](#示例多房间部署)
+- [故障处理](#故障处理)
+- [监控和维护](#监控和维护)
+
+---
+
+## 架构概览
+
+Uni-Lab-OS 支持多种部署模式：
+
+```
+┌──────────────────────────────────────────────┐
+│      Cloud Platform/Self-hosted Platform     │
+│           uni-lab.bohrium.com                │
+│  (Resource Management, Task Scheduling,      │
+│              Monitoring)                     │
+└────────────────────┬─────────────────────────┘
+                     │ WebSocket / HTTP
+                     │
+          ┌──────────┴──────────┐
+          │                     │
+     ┌────▼─────┐         ┌────▼─────┐
+     │  Master  │◄──ROS2──►│  Slave   │
+     │   Node   │         │   Node   │
+     │  (Host)  │         │ (Slave)  │
+     └────┬─────┘         └────┬─────┘
+          │                    │
+     ┌────┴────┐          ┌────┴────┐
+     │ Device A│          │ Device B│
+     │ Device C│          │ Device D│
+     └─────────┘          └─────────┘
+```
+
+---
+
+## 节点类型
+
+### 主节点（Host Node）
+
+**功能**:
+
+- 创建和管理全局资源
+- 提供 host_node 服务
+- 连接云端平台
+- 协调多个从节点
+- 提供 Web 管理界面
+
+**启动命令**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g host_devices.json
+```
+
+### 从节点（Slave Node）
+
+**功能**:
+
+- 管理本地设备
+- 不连接云端（可选）
+- 向主节点注册
+- 执行分配的任务
+
+**启动命令**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g slave_devices.json --is_slave
+```
+
+---
+
+## 通信机制
+
+### ROS2 通信
+
+**用途**: 节点间实时通信
+
+**通信方式**:
+
+- **Topic**: 状态广播（设备状态、传感器数据）
+- **Service**: 同步请求（资源查询、配置获取）
+- **Action**: 异步任务（设备操作、长时间运行）
+
+**示例**:
+
+```bash
+# 查看ROS2节点
+ros2 node list
+
+# 查看topic
+ros2 topic list
+
+# 查看action
+ros2 action list
+```
+
+### WebSocket 通信
+
+**用途**: 主节点与云端通信
+
+**特点**:
+
+- 实时双向通信
+- 自动重连
+- 心跳保持
+
+**配置**:
+
+```python
+# local_config.py
+BasicConfig.ak = "your_ak"
+BasicConfig.sk = "your_sk"
+```
+
+---
+
+## 典型拓扑
+
+### 单节点模式
+
+**适用场景**: 小型实验室、开发测试
+
+```
+┌──────────────────┐
+│  Uni-Lab Node    │
+│  ┌────────────┐  │
+│  │  Device A  │  │
+│  │  Device B  │  │
+│  │  Device C  │  │
+│  └────────────┘  │
+└──────────────────┘
+```
+
+**优点**:
+
+- 配置简单
+- 无网络延迟
+- 适合快速原型
+
+**启动**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g all_devices.json
+```
+
+### 主从模式
+
+**适用场景**: 多房间、分布式设备
+
+```
+┌─────────────┐      ┌──────────────┐
+│ Master Node │◄────►│ Slave Node 1 │
+│ Coordinator │      │   Liquid     │
+│ Web UI      │      │  Handling    │
+└──────┬──────┘      └──────────────┘
+       │
+       │             ┌──────────────┐
+       └────────────►│ Slave Node 2 │
+                     │  Analytical  │
+                     │  (NMR/GC)    │
+                     └──────────────┘
+```
+
+**优点**:
+
+- 物理分隔
+- 独立故障域
+- 易于扩展
+
+**适用场景**:
+
+- 设备物理位置分散
+- 不同房间的设备
+- 需要独立故障域
+- 分阶段扩展系统
+
+**主节点**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g host.json
+```
+
+**从节点**:
+
+```bash
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave
+unilab --ak your_ak --sk your_sk -g slave2.json --is_slave --port 8003
+```
+
+### 云端集成模式
+
+**适用场景**: 远程监控、多实验室协作
+
+```
+      Cloud Platform
+            │
+    ┌───────┴────────┐
+    │                │
+Laboratory A    Laboratory B
+(Master Node)   (Master Node)
+```
+
+**优点**:
+
+- 远程访问
+- 数据同步
+- 任务调度
+
+**启动**:
+
+```bash
+# 实验室A
+unilab --ak your_ak --sk your_sk --upload_registry --use_remote_resource
+
+# 实验室B
+unilab --ak your_ak --sk your_sk --upload_registry --use_remote_resource
+```
+
+---
+
+## 主从模式配置
+
+### 主节点配置
+
+#### 1. 创建主节点设备图
+
+`host.json`:
+
+```json
+{
+  "nodes": [],
+  "links": []
+}
+```
+
+#### 2. 启动主节点
+
+```bash
+# 基本启动
+unilab --ak your_ak --sk your_sk -g host.json
+
+# 带云端集成
+unilab --ak your_ak --sk your_sk -g host.json --upload_registry
+
+# 指定端口
+unilab --ak your_ak --sk your_sk -g host.json --port 8002
+```
+
+#### 3. 验证主节点
+
+```bash
+# 检查ROS2节点
+ros2 node list
+# 应该看到 /host_node
+
+# 检查服务
+ros2 service list | grep host_node
+
+# Web界面
+# 访问 http://localhost:8002
+```
+
+### 从节点配置
+
+#### 1. 创建从节点设备图
+
+`slave1.json`:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "liquid_handler_1",
+      "name": "液体处理工作站",
+      "type": "device",
+      "class": "liquid_handler",
+      "config": {
+        "simulation": false
+      }
+    }
+  ],
+  "links": []
+}
+```
+
+#### 2. 启动从节点
+
+```bash
+# 基本从节点启动
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave
+
+# 指定不同端口（如果多个从节点在同一台机器）
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave --port 8003
+
+# 跳过等待主节点（独立测试）
+unilab --ak your_ak --sk your_sk -g slave1.json --is_slave --slave_no_host
+```
+
+#### 3. 验证从节点
+
+```bash
+# 检查节点连接
+ros2 node list
+
+# 检查设备状态
+ros2 topic echo /liquid_handler_1/status
+```
+
+### 跨节点通信
+
+#### 资源访问
+
+主节点可以访问从节点的资源：
+
+```bash
+# 在主节点或其他节点调用从节点设备
+ros2 action send_goal /liquid_handler_1/transfer_liquid \
+  unilabos_msgs/action/TransferLiquid \
+  "{source: {...}, target: {...}, volume: 100.0}"
+```
+
+#### 状态监控
+
+主节点监控所有从节点状态：
+
+```bash
+# 订阅从节点状态
+ros2 topic echo /liquid_handler_1/status
+
+# 查看所有设备状态
+ros2 topic list | grep status
+```
+
+---
+
+## 网络配置
+
+### ROS2 DDS 配置
+
+确保主从节点在同一网络：
+
+```bash
+# 检查网络可达性
+ping <slave_node_ip>
+
+# 设置ROS_DOMAIN_ID（可选，用于隔离）
+export ROS_DOMAIN_ID=42
+```
+
+### 防火墙配置
+
+**建议做法**：
+
+为了确保 ROS2 DDS 通信正常，建议直接关闭防火墙，而不是配置特定端口。ROS2 使用动态端口范围，配置特定端口可能导致通信问题。
+
+**Linux**:
+
+```bash
+# 关闭防火墙
+sudo ufw disable
+
+# 或者临时停止防火墙
+sudo systemctl stop ufw
+```
+
+**Windows**:
+
+```powershell
+# 在Windows安全中心关闭防火墙
+# 控制面板 -> 系统和安全 -> Windows Defender 防火墙 -> 启用或关闭Windows Defender防火墙
+```
+
+### 验证网络连通性
+
+在配置完成后，使用 ROS2 自带的 demo 节点来验证跨节点通信是否正常：
+
+**在主节点机器上**（激活 unilab 环境后）：
+
+```bash
+# 启动talker
+ros2 run demo_nodes_cpp talker
+
+# 同时在另一个终端启动listener
+ros2 run demo_nodes_cpp listener
+```
+
+**在从节点机器上**（激活 unilab 环境后）：
+
+```bash
+# 启动talker
+ros2 run demo_nodes_cpp talker
+
+# 同时在另一个终端启动listener
+ros2 run demo_nodes_cpp listener
+```
+
+**注意**：必须在两台机器上**互相启动** talker 和 listener，否则可能出现只能收不能发的单向通信问题。
+
+**预期结果**：
+
+- 每台机器的 listener 应该能同时接收到本地和远程 talker 发送的消息
+- 如果只能看到本地消息，说明网络配置有问题
+- 如果两台机器都能互相收发消息，则组网配置正确
+
+### 本地网络要求
+
+**ROS2 通信**:
+
+- 同一局域网或 VPN
+- 端口：默认 DDS 端口（7400-7500）
+- 组播支持（或配置 unicast）
+
+**检查连通性**:
+
+```bash
+# Ping测试
+ping <target_ip>
+
+# ROS2节点发现
+ros2 node list
+ros2 daemon stop && ros2 daemon start
+```
+
+### 云端连接
+
+**要求**:
+
+- HTTPS (443)
+- WebSocket 支持
+- 稳定的互联网连接
+
+**测试连接**:
+
+```bash
+# 测试云端连接
+curl https://uni-lab.bohrium.com/api/v1/health
+
+# 测试WebSocket
+# 启动Uni-Lab后查看日志
+```
+
+---
+
+## 示例：多房间部署
+
+### 场景描述
+
+- **房间 A**: 主控室，有 Web 界面
+- **房间 B**: 液体处理室
+- **房间 C**: 分析仪器室
+
+### 房间 A - 主节点
+
+```bash
+# host.json
+unilab --ak your_ak --sk your_sk -g host.json --port 8002
+```
+
+### 房间 B - 从节点 1
+
+```bash
+# liquid_handler.json
+unilab --ak your_ak --sk your_sk -g liquid_handler.json --is_slave --port 8003
+```
+
+### 房间 C - 从节点 2
+
+```bash
+# analytical.json
+unilab --ak your_ak --sk your_sk -g analytical.json --is_slave --port 8004
+```
+
+---
+
+## 故障处理
+
+### 节点离线
+
+**检测**:
+
+```bash
+ros2 node list  # 查看在线节点
+```
+
+**处理**:
+
+1. 检查网络连接
+2. 重启节点
+3. 检查日志
+
+### 从节点无法连接主节点
+
+1. 检查网络：
+
+   ```bash
+   ping <host_ip>
+   ```
+
+2. 检查 ROS_DOMAIN_ID：
+
+   ```bash
+   echo $ROS_DOMAIN_ID
+   ```
+
+3. 使用`--slave_no_host`测试：
+   ```bash
+   unilab --ak your_ak --sk your_sk -g slave.json --is_slave --slave_no_host
+   ```
+
+### 通信延迟
+
+**排查**:
+
+```bash
+# 网络延迟
+ping <node_ip>
+
+# ROS2话题延迟
+ros2 topic hz /device_status
+ros2 topic bw /device_status
+```
+
+**优化**:
+
+- 减少发布频率
+- 使用 QoS 配置
+- 优化网络带宽
+
+### 数据同步失败
+
+**检查**:
+
+```bash
+# 查看日志
+tail -f unilabos_data/logs/unilab.log | grep sync
+```
+
+**解决**:
+
+- 检查云端连接
+- 验证 AK/SK
+- 手动触发同步
+
+### 资源不可见
+
+检查资源注册：
+
+```bash
+ros2 service call /host_node/resource_list \
+  unilabos_msgs/srv/ResourceList
+```
+
+---
+
+## 监控和维护
+
+### 节点状态监控
+
+```bash
+# 查看所有节点
+ros2 node list
+
+# 查看话题
+ros2 topic list
+```
+
+---
+
+## 相关文档
+
+- [最佳实践指南](../user_guide/best_practice.md) - 完整的实验室搭建流程
+- [安装指南](../user_guide/installation.md) - 环境安装步骤
+- [启动参数详解](../user_guide/launch.md) - 启动参数说明
+- [添加设备驱动](add_device.md) - 自定义设备开发
+- [工作站架构](workstation_architecture.md) - 复杂工作站搭建
+
+---
+
+## 参考资料
+
+- [ROS2 网络配置](https://docs.ros.org/en/humble/Tutorials/Advanced/Networking.html)
+- [DDS 配置](https://fast-dds.docs.eprosima.com/)
+- Uni-Lab 云平台文档

docs/developer_guide/workstation_architecture.md

@@ -1,378 +0,0 @@
-# 工作站基础架构设计文档
-
-## 1. 整体架构图
-
-```mermaid
-graph TB
-    subgraph "工作站基础架构"
-        WB[WorkstationBase]
-        WB --> |继承| RPN[ROS2WorkstationNode]
-        WB --> |组合| WCB[WorkstationCommunicationBase]
-        WB --> |组合| MMB[MaterialManagementBase]
-        WB --> |组合| WHS[WorkstationHTTPService]
-    end
-    
-    subgraph "通信层实现"
-        WCB --> |实现| PLC[PLCCommunication]
-        WCB --> |实现| SER[SerialCommunication]
-        WCB --> |实现| ETH[EthernetCommunication]
-    end
-    
-    subgraph "物料管理实现"
-        MMB --> |实现| PLR[PyLabRobotMaterialManager]
-        MMB --> |实现| BIO[BioyondMaterialManager]
-        MMB --> |实现| SIM[SimpleMaterialManager]
-    end
-    
-    subgraph "HTTP服务"
-        WHS --> |处理| LIMS[LIMS协议报送]
-        WHS --> |处理| MAT[物料变更报送]
-        WHS --> |处理| ERR[错误处理报送]
-    end
-    
-    subgraph "具体工作站实现"
-        WB --> |继承| WS1[PLCWorkstation]
-        WB --> |继承| WS2[ReportingWorkstation]
-        WB --> |继承| WS3[HybridWorkstation]
-    end
-    
-    subgraph "外部系统"
-        EXT1[PLC设备] --> |通信| PLC
-        EXT2[外部工作站] --> |HTTP报送| WHS
-        EXT3[LIMS系统] --> |HTTP报送| WHS
-        EXT4[Bioyond物料系统] --> |查询| BIO
-    end
-```
-
-## 2. 类关系图
-
-```mermaid
-classDiagram
-    class WorkstationBase {
-        <<abstract>>
-        +device_id: str
-        +communication: WorkstationCommunicationBase
-        +material_management: MaterialManagementBase
-        +http_service: WorkstationHTTPService
-        +workflow_status: WorkflowStatus
-        +supported_workflows: Dict
-        
-        +_create_communication_module()* 
-        +_create_material_management_module()*
-        +_register_supported_workflows()*
-        
-        +process_step_finish_report()
-        +process_sample_finish_report()
-        +process_order_finish_report()
-        +process_material_change_report()
-        +handle_external_error()
-        
-        +start_workflow()
-        +stop_workflow()
-        +get_workflow_status()
-        +get_device_status()
-    }
-    
-    class ROS2WorkstationNode {
-        +sub_devices: Dict
-        +protocol_names: List
-        +execute_single_action()
-        +create_ros_action_server()
-        +initialize_device()
-    }
-    
-    class WorkstationCommunicationBase {
-        <<abstract>>
-        +config: CommunicationConfig
-        +is_connected: bool
-        +connect()
-        +disconnect()
-        +start_workflow()*
-        +stop_workflow()*
-        +get_device_status()*
-        +write_register()
-        +read_register()
-    }
-    
-    class MaterialManagementBase {
-        <<abstract>>
-        +device_id: str
-        +deck_config: Dict
-        +resource_tracker: DeviceNodeResourceTracker
-        +plr_deck: Deck
-        +find_materials_by_type()
-        +update_material_location()
-        +convert_to_unilab_format()
-        +_create_resource_by_type()*
-    }
-    
-    class WorkstationHTTPService {
-        +workstation_instance: WorkstationBase
-        +host: str
-        +port: int
-        +start()
-        +stop()
-        +_handle_step_finish_report()
-        +_handle_material_change_report()
-    }
-    
-    class PLCWorkstation {
-        +plc_config: Dict
-        +modbus_client: ModbusTCPClient
-        +_create_communication_module()
-        +_create_material_management_module()
-        +_register_supported_workflows()
-    }
-    
-    class ReportingWorkstation {
-        +report_handlers: Dict
-        +_create_communication_module()
-        +_create_material_management_module()
-        +_register_supported_workflows()
-    }
-    
-    WorkstationBase --|> ROS2WorkstationNode
-    WorkstationBase *-- WorkstationCommunicationBase
-    WorkstationBase *-- MaterialManagementBase
-    WorkstationBase *-- WorkstationHTTPService
-    
-    PLCWorkstation --|> WorkstationBase
-    ReportingWorkstation --|> WorkstationBase
-    
-    WorkstationCommunicationBase <|-- PLCCommunication
-    WorkstationCommunicationBase <|-- DummyCommunication
-    
-    MaterialManagementBase <|-- PyLabRobotMaterialManager
-    MaterialManagementBase <|-- SimpleMaterialManager
-```
-
-## 3. 工作站启动时序图
-
-```mermaid
-sequenceDiagram
-    participant APP as Application
-    participant WS as WorkstationBase
-    participant COMM as CommunicationModule
-    participant MAT as MaterialManager
-    participant HTTP as HTTPService
-    participant ROS as ROS2WorkstationNode
-    
-    APP->>WS: 创建工作站实例
-    WS->>ROS: 初始化ROS2WorkstationNode
-    ROS->>ROS: 初始化子设备
-    ROS->>ROS: 设置硬件接口代理
-    
-    WS->>COMM: _create_communication_module()
-    COMM->>COMM: 初始化通信配置
-    COMM->>COMM: 建立PLC/串口连接
-    COMM-->>WS: 返回通信模块实例
-    
-    WS->>MAT: _create_material_management_module()
-    MAT->>MAT: 创建PyLabRobot Deck
-    MAT->>MAT: 初始化物料资源
-    MAT->>MAT: 注册到ResourceTracker
-    MAT-->>WS: 返回物料管理实例
-    
-    WS->>WS: _register_supported_workflows()
-    WS->>WS: _create_workstation_services()
-    WS->>HTTP: _start_http_service()
-    HTTP->>HTTP: 创建HTTP服务器
-    HTTP->>HTTP: 启动监听线程
-    HTTP-->>WS: HTTP服务启动完成
-    
-    WS-->>APP: 工作站初始化完成
-```
-
-## 4. 工作流执行时序图
-
-```mermaid
-sequenceDiagram
-    participant EXT as ExternalSystem
-    participant WS as WorkstationBase
-    participant COMM as CommunicationModule
-    participant MAT as MaterialManager
-    participant ROS as ROS2WorkstationNode
-    participant DEV as SubDevice
-    
-    EXT->>WS: start_workflow(type, params)
-    WS->>WS: 验证工作流类型
-    WS->>COMM: start_workflow(type, params)
-    COMM->>COMM: 发送启动命令到PLC
-    COMM-->>WS: 启动成功
-    
-    WS->>WS: 更新workflow_status = RUNNING
-    
-    loop 工作流步骤执行
-        WS->>ROS: execute_single_action(device_id, action, params)
-        ROS->>DEV: 发送ROS Action请求
-        DEV->>DEV: 执行设备动作
-        DEV-->>ROS: 返回执行结果
-        ROS-->>WS: 返回动作结果
-        
-        WS->>MAT: update_material_location(material_id, location)
-        MAT->>MAT: 更新PyLabRobot资源状态
-        MAT-->>WS: 更新完成
-    end
-    
-    WS->>COMM: get_workflow_status()
-    COMM->>COMM: 查询PLC状态寄存器
-    COMM-->>WS: 返回状态信息
-    
-    WS->>WS: 更新workflow_status = COMPLETED
-    WS-->>EXT: 工作流执行完成
-```
-
-## 5. HTTP报送处理时序图
-
-```mermaid
-sequenceDiagram
-    participant EXT as ExternalWorkstation
-    participant HTTP as HTTPService
-    participant WS as WorkstationBase
-    participant MAT as MaterialManager
-    participant DB as DataStorage
-    
-    EXT->>HTTP: POST /report/step_finish
-    HTTP->>HTTP: 解析请求数据
-    HTTP->>HTTP: 验证LIMS协议字段
-    HTTP->>WS: process_step_finish_report(request)
-    
-    WS->>WS: 增加接收计数
-    WS->>WS: 记录步骤完成事件
-    WS->>MAT: 更新相关物料状态
-    MAT->>MAT: 更新PyLabRobot资源
-    MAT-->>WS: 更新完成
-    
-    WS->>DB: 保存报送记录
-    DB-->>WS: 保存完成
-    
-    WS-->>HTTP: 返回处理结果
-    HTTP->>HTTP: 构造HTTP响应
-    HTTP-->>EXT: 200 OK + acknowledgment_id
-    
-    Note over EXT,DB: 类似处理sample_finish, order_finish, material_change等报送
-```
-
-## 6. 错误处理时序图
-
-```mermaid
-sequenceDiagram
-    participant DEV as Device
-    participant WS as WorkstationBase
-    participant COMM as CommunicationModule
-    participant HTTP as HTTPService
-    participant EXT as ExternalSystem
-    
-    DEV->>WS: 设备错误事件
-    WS->>WS: handle_external_error(error_data)
-    WS->>WS: 记录错误历史
-    
-    alt 关键错误
-        WS->>COMM: emergency_stop()
-        COMM->>COMM: 发送紧急停止命令
-        WS->>WS: 更新workflow_status = ERROR
-    else 普通错误
-        WS->>WS: 标记动作失败
-        WS->>WS: 触发重试逻辑
-    end
-    
-    WS->>HTTP: 记录错误报送
-    HTTP->>EXT: 主动通知错误状态
-    
-    WS-->>DEV: 错误处理完成
-```
-
-## 7. 典型工作站实现示例
-
-### 7.1 PLC工作站实现
-
-```python
-class PLCWorkstation(WorkstationBase):
-    def _create_communication_module(self):
-        return PLCCommunication(self.communication_config)
-    
-    def _create_material_management_module(self):
-        return PyLabRobotMaterialManager(
-            self.device_id, 
-            self.deck_config, 
-            self.resource_tracker
-        )
-    
-    def _register_supported_workflows(self):
-        self.supported_workflows = {
-            "battery_assembly": WorkflowInfo(...),
-            "quality_check": WorkflowInfo(...)
-        }
-```
-
-### 7.2 报送接收工作站实现
-
-```python
-class ReportingWorkstation(WorkstationBase):
-    def _create_communication_module(self):
-        return DummyCommunication(self.communication_config)
-    
-    def _create_material_management_module(self):
-        return SimpleMaterialManager(
-            self.device_id,
-            self.deck_config,
-            self.resource_tracker
-        )
-    
-    def _register_supported_workflows(self):
-        self.supported_workflows = {
-            "data_collection": WorkflowInfo(...),
-            "report_processing": WorkflowInfo(...)
-        }
-```
-
-## 8. 核心接口说明
-
-### 8.1 必须实现的抽象方法
-- `_create_communication_module()`: 创建通信模块
-- `_create_material_management_module()`: 创建物料管理模块
-- `_register_supported_workflows()`: 注册支持的工作流
-
-### 8.2 可重写的报送处理方法
-- `process_step_finish_report()`: 步骤完成处理
-- `process_sample_finish_report()`: 样本完成处理
-- `process_order_finish_report()`: 订单完成处理
-- `process_material_change_report()`: 物料变更处理
-- `handle_external_error()`: 错误处理
-
-### 8.3 工作流控制接口
-- `start_workflow()`: 启动工作流
-- `stop_workflow()`: 停止工作流
-- `get_workflow_status()`: 获取状态
-
-## 9. 配置参数说明
-
-```python
-workstation_config = {
-    "communication_config": {
-        "protocol": "modbus_tcp",
-        "host": "192.168.1.100",
-        "port": 502
-    },
-    "deck_config": {
-        "size_x": 1000.0,
-        "size_y": 1000.0,
-        "size_z": 500.0
-    },
-    "http_service_config": {
-        "enabled": True,
-        "host": "127.0.0.1",
-        "port": 8081
-    },
-    "communication_interfaces": {
-        "logical_device_1": CommunicationInterface(...)
-    }
-}
-```
-
-这个架构设计支持：
-1. **灵活的通信方式**: 通过CommunicationBase支持PLC、串口、以太网等
-2. **多样的物料管理**: 支持PyLabRobot、Bioyond、简单物料系统
-3. **统一的HTTP报送**: 基于LIMS协议的标准化报送接口
-4. **完整的工作流控制**: 支持动态和静态工作流
-5. **强大的错误处理**: 多层次的错误处理和恢复机制

docs/index.md

@@ -1,9 +1,23 @@
-# Uni-Lab 项目文档
+# Uni-Lab-OS 项目文档
 
-欢迎来到项目文档的首页！
+Uni-Lab-OS 是一个开源的实验室自动化操作系统，提供统一的设备接口、工作流管理和分布式部署能力。
 
 ```{toctree}
 :maxdepth: 3
 
 intro.md
 ```
+
+## 开发者指南
+
+```{toctree}
+:maxdepth: 2
+
+developer_guide/http_api.md
+developer_guide/networking_overview.md
+developer_guide/add_device.md
+developer_guide/add_action.md
+developer_guide/add_registry.md
+developer_guide/add_yaml.md
+developer_guide/action_includes.md
+```

docs/intro.md

@@ -10,31 +10,51 @@ concepts/01-communication-instruction.md
 concepts/02-topology-and-chemputer-compile.md
 ```
 
-## **用户指南**
+## 用户指南
 
-本指南将带你了解如何使用项目的功能。
+快速上手、系统配置与使用说明。
 
 ```{toctree}
 :maxdepth: 2
 
+user_guide/best_practice.md
 user_guide/installation.md
-user_guide/configuration.md
 user_guide/launch.md
+user_guide/graph_files.md
 boot_examples/index.md
 ```
 
+## 进阶配置
+
+高级配置和系统管理。
+
+```{toctree}
+:maxdepth: 2
+
+advanced_usage/configuration.md
+advanced_usage/working_directory.md
+```
+
 ## 开发者指南
 
+设备开发、系统扩展与架构说明。
+
 ```{toctree}
 :maxdepth: 2
 
-developer_guide/device_driver
-developer_guide/add_device
-developer_guide/add_action
-developer_guide/actions
-developer_guide/add_protocol
-developer_guide/add_batteryPLC
-developer_guide/materials_tutorial.md
+developer_guide/networking_overview.md
+developer_guide/add_device.md
+developer_guide/add_old_device.md
+developer_guide/add_registry.md
+developer_guide/add_yaml.md
+developer_guide/add_action.md
+developer_guide/actions.md
+developer_guide/action_includes.md
+developer_guide/add_protocol.md
+developer_guide/examples/workstation_architecture.md
+developer_guide/examples/materials_construction_guide.md
+developer_guide/examples/materials_tutorial.md
+developer_guide/examples/battery_plc_workstation.md
 ```
 
 ## 接口文档

docs/requirements.txt

@@ -2,6 +2,7 @@
 sphinx>=7.0.0
 sphinx-rtd-theme>=2.0.0
 myst-parser>=2.0.0
+sphinxcontrib-mermaid
 
 # 用于支持Jupyter notebook文档
 myst-nb>=1.0.0

docs/user_guide/configuration.md

@@ -1,442 +0,0 @@
-# Uni-Lab 配置指南
-
-Uni-Lab 支持通过 Python 配置文件进行灵活的系统配置。本指南将帮助您理解配置选项并设置您的 Uni-Lab 环境。
-
-## 配置文件格式
-
-Uni-Lab 支持 Python 格式的配置文件，它比 YAML 或 JSON 提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
-
-### 默认配置示例
-
-首次使用时，系统会自动创建一个基础配置文件 `local_config.py`：
-
-```python
-# unilabos的配置文件
-
-class BasicConfig:
-    ak = ""  # 实验室网页给您提供的ak代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --ak 传入，优先按照传入参数解析
-    sk = ""  # 实验室网页给您提供的sk代码，您可以在配置文件中指定，也可以通过运行unilabos时以 --sk 传入，优先按照传入参数解析
-
-
-# WebSocket配置，一般无需调整
-class WSConfig:
-    reconnect_interval = 5  # 重连间隔（秒）
-    max_reconnect_attempts = 999  # 最大重连次数
-    ping_interval = 30  # ping间隔（秒）
-```
-您可以进入实验室，点击左下角的头像在实验室详情中获取所在实验室的ak sk
-![copy_aksk.gif](image/copy_aksk.gif)
-
-### 完整配置示例
-
-您可以根据需要添加更多配置选项：
-
-```python
-#!/usr/bin/env python
-# coding=utf-8
-"""Uni-Lab 配置文件"""
-
-# 基础配置
-class BasicConfig:
-    ak = "your_access_key"  # 实验室访问密钥
-    sk = "your_secret_key"  # 实验室私钥
-    working_dir = ""  # 工作目录（通常自动设置）
-    config_path = ""  # 配置文件路径（自动设置）
-    is_host_mode = True  # 是否为主站模式
-    slave_no_host = False  # 从站模式下是否跳过等待主机服务
-    upload_registry = False  # 是否上传注册表
-    machine_name = "undefined"  # 机器名称（自动获取）
-    vis_2d_enable = False  # 是否启用2D可视化
-    enable_resource_load = True  # 是否启用资源加载
-    communication_protocol = "websocket"  # 通信协议
-
-# WebSocket配置
-class WSConfig:
-    reconnect_interval = 5  # 重连间隔（秒）
-    max_reconnect_attempts = 999  # 最大重连次数
-    ping_interval = 30  # ping间隔（秒）
-
-# OSS上传配置
-class OSSUploadConfig:
-    api_host = ""  # API主机地址
-    authorization = ""  # 授权信息
-    init_endpoint = ""  # 初始化端点
-    complete_endpoint = ""  # 完成端点
-    max_retries = 3  # 最大重试次数
-
-# HTTP配置
-class HTTPConfig:
-    remote_addr = "http://127.0.0.1:48197/api/v1"  # 远程地址
-
-# ROS配置
-class ROSConfig:
-    modules = [
-        "std_msgs.msg",
-        "geometry_msgs.msg",
-        "control_msgs.msg",
-        "control_msgs.action",
-        "nav2_msgs.action",
-        "unilabos_msgs.msg",
-        "unilabos_msgs.action",
-    ]  # 需要加载的ROS模块
-```
-
-## 命令行参数覆盖配置
-
-Uni-Lab 允许通过命令行参数覆盖配置文件中的设置，提供更灵活的配置方式。命令行参数的优先级高于配置文件。
-
-### 支持命令行覆盖的配置项
-
-以下配置项可以通过命令行参数进行覆盖：
-
-| 配置类        | 配置字段          | 命令行参数          | 说明                             |
-| ------------- | ----------------- | ------------------- | -------------------------------- |
-| `BasicConfig` | `ak`              | `--ak`              | 实验室访问密钥                   |
-| `BasicConfig` | `sk`              | `--sk`              | 实验室私钥                       |
-| `BasicConfig` | `working_dir`     | `--working_dir`     | 工作目录路径                     |
-| `BasicConfig` | `is_host_mode`    | `--is_slave`        | 主站模式（参数为从站模式，取反） |
-| `BasicConfig` | `slave_no_host`   | `--slave_no_host`   | 从站模式下跳过等待主机服务       |
-| `BasicConfig` | `upload_registry` | `--upload_registry` | 启动时上传注册表信息             |
-| `BasicConfig` | `vis_2d_enable`   | `--2d_vis`          | 启用 2D 可视化                   |
-| `HTTPConfig`  | `remote_addr`     | `--addr`            | 远程服务地址                     |
-
-### 特殊命令行参数
-
-除了直接覆盖配置项的参数外，还有一些特殊的命令行参数：
-
-| 参数                | 说明                                 |
-| ------------------- | ------------------------------------ |
-| `--config`          | 指定配置文件路径                     |
-| `--port`            | Web 服务端口（不影响配置文件）       |
-| `--disable_browser` | 禁用自动打开浏览器（不影响配置文件） |
-| `--visual`          | 可视化工具选择（不影响配置文件）     |
-| `--skip_env_check`  | 跳过环境检查（不影响配置文件）       |
-
-### 配置优先级
-
-配置项的生效优先级从高到低为：
-
-1. **命令行参数**：最高优先级
-2. **环境变量**：中等优先级
-3. **配置文件**：基础优先级
-
-### 使用示例
-
-```bash
-# 通过命令行覆盖认证信息
-unilab --ak "new_access_key" --sk "new_secret_key"
-
-# 覆盖服务器地址
-unilab --addr "https://custom.server.com/api/v1"
-
-# 启用从站模式并跳过等待主机
-unilab --is_slave --slave_no_host
-
-# 启用上传注册表和2D可视化
-unilab --upload_registry --2d_vis
-
-# 组合使用多个覆盖参数
-unilab --ak "key" --sk "secret" --addr "test" --upload_registry --2d_vis
-```
-
-### 预设环境地址
-
-`--addr` 参数支持以下预设值，会自动转换为对应的完整 URL：
-
-- `test` → `https://uni-lab.test.bohrium.com/api/v1`
-- `uat` → `https://uni-lab.uat.bohrium.com/api/v1`
-- `local` → `http://127.0.0.1:48197/api/v1`
-- 其他值 → 直接使用作为完整 URL
-
-## 配置选项详解
-
-### 基础配置 (BasicConfig)
-
-基础配置包含了系统运行的核心参数：
-
-| 参数                     | 类型 | 默认值        | 说明                                       |
-| ------------------------ | ---- | ------------- | ------------------------------------------ |
-| `ak`                     | str  | `""`          | 实验室访问密钥（必需）                     |
-| `sk`                     | str  | `""`          | 实验室私钥（必需）                         |
-| `working_dir`            | str  | `""`          | 工作目录，通常自动设置                     |
-| `is_host_mode`           | bool | `True`        | 是否为主站模式                             |
-| `slave_no_host`          | bool | `False`       | 从站模式下是否跳过等待主机服务             |
-| `upload_registry`        | bool | `False`       | 启动时是否上传注册表信息                   |
-| `machine_name`           | str  | `"undefined"` | 机器名称，自动从 hostname 获取（不可配置） |
-| `vis_2d_enable`          | bool | `False`       | 是否启用 2D 可视化                         |
-| `communication_protocol` | str  | `"websocket"` | 通信协议，固定为 websocket                 |
-
-#### 认证配置
-
-`ak` 和 `sk` 是必需的认证参数：
-
-1. **获取方式**：在 [Uni-Lab 官网](https://uni-lab.bohrium.com) 注册实验室后获得
-2. **配置方式**：
-   - **命令行参数**：`--ak "your_key" --sk "your_secret"`（最高优先级）
-   - **配置文件**：在 `BasicConfig` 类中设置
-   - **环境变量**：`UNILABOS_BASICCONFIG_AK` 和 `UNILABOS_BASICCONFIG_SK`
-3. **优先级顺序**：命令行参数 > 环境变量 > 配置文件
-4. **安全注意**：请妥善保管您的密钥信息
-
-**推荐做法**：
-
-- 开发环境：使用配置文件
-- 生产环境：使用环境变量或命令行参数
-- 临时测试：使用命令行参数
-
-### WebSocket 配置 (WSConfig)
-
-WebSocket 是 Uni-Lab 的主要通信方式：
-
-| 参数                     | 类型 | 默认值 | 说明               |
-| ------------------------ | ---- | ------ | ------------------ |
-| `reconnect_interval`     | int  | `5`    | 断线重连间隔（秒） |
-| `max_reconnect_attempts` | int  | `999`  | 最大重连次数       |
-| `ping_interval`          | int  | `30`   | 心跳检测间隔（秒） |
-
-### HTTP 配置 (HTTPConfig)
-
-HTTP 客户端配置用于与云端服务通信：
-
-| 参数          | 类型 | 默认值                            | 说明         |
-| ------------- | ---- | --------------------------------- | ------------ |
-| `remote_addr` | str  | `"http://127.0.0.1:48197/api/v1"` | 远程服务地址 |
-
-**预设环境地址**：
-
-- 生产环境：`https://uni-lab.bohrium.com/api/v1`
-- 测试环境：`https://uni-lab.test.bohrium.com/api/v1`
-- UAT 环境：`https://uni-lab.uat.bohrium.com/api/v1`
-- 本地环境：`http://127.0.0.1:48197/api/v1`
-
-### ROS 配置 (ROSConfig)
-
-配置 ROS 消息转换器需要加载的模块：
-
-```python
-class ROSConfig:
-    modules = [
-        "std_msgs.msg",           # 标准消息类型
-        "geometry_msgs.msg",      # 几何消息类型
-        "control_msgs.msg",       # 控制消息类型
-        "control_msgs.action",    # 控制动作类型
-        "nav2_msgs.action",       # 导航动作类型
-        "unilabos_msgs.msg",      # UniLab 自定义消息类型
-        "unilabos_msgs.action",   # UniLab 自定义动作类型
-    ]
-```
-
-您可以根据实际使用的设备和功能添加其他 ROS 模块。
-
-### OSS 上传配置 (OSSUploadConfig)
-
-对象存储服务配置，用于文件上传功能：
-
-| 参数                | 类型 | 默认值 | 说明                 |
-| ------------------- | ---- | ------ | -------------------- |
-| `api_host`          | str  | `""`   | OSS API 主机地址     |
-| `authorization`     | str  | `""`   | 授权认证信息         |
-| `init_endpoint`     | str  | `""`   | 上传初始化端点       |
-| `complete_endpoint` | str  | `""`   | 上传完成端点         |
-| `max_retries`       | int  | `3`    | 上传失败最大重试次数 |
-
-## 环境变量支持
-
-Uni-Lab 支持通过环境变量覆盖配置文件中的设置。环境变量格式为：
-
-```
-UNILABOS_{配置类名}_{字段名}
-```
-
-### 环境变量示例
-
-```bash
-# 设置基础配置
-export UNILABOS_BASICCONFIG_AK="your_access_key"
-export UNILABOS_BASICCONFIG_SK="your_secret_key"
-export UNILABOS_BASICCONFIG_IS_HOST_MODE="true"
-
-# 设置WebSocket配置
-export UNILABOS_WSCONFIG_RECONNECT_INTERVAL="10"
-export UNILABOS_WSCONFIG_MAX_RECONNECT_ATTEMPTS="500"
-
-# 设置HTTP配置
-export UNILABOS_HTTPCONFIG_REMOTE_ADDR="https://uni-lab.bohrium.com/api/v1"
-```
-
-### 环境变量类型转换
-
-- **布尔值**：`"true"`, `"1"`, `"yes"` → `True`；其他 → `False`
-- **整数**：自动转换为 `int` 类型
-- **浮点数**：自动转换为 `float` 类型
-- **字符串**：保持原值
-
-## 配置文件使用方法
-
-### 1. 指定配置文件启动
-
-```bash
-# 使用指定配置文件启动
-unilab --config /path/to/your/config.py
-```
-
-### 2. 使用默认配置文件
-
-如果不指定配置文件，系统会按以下顺序查找：
-
-1. 环境变量 `UNILABOS_BASICCONFIG_CONFIG_PATH` 指定的路径
-2. 工作目录下的 `local_config.py`
-3. 首次使用时会引导创建配置文件
-
-### 3. 配置文件验证
-
-系统启动时会自动验证配置文件：
-
-- **语法检查**：确保 Python 语法正确
-- **类型检查**：验证配置项类型是否匹配
-- **必需项检查**：确保 `ak` 和 `sk` 已配置
-
-## 最佳实践
-
-### 1. 安全配置
-
-- 不要将包含密钥的配置文件提交到版本控制系统
-- 使用环境变量或命令行参数在生产环境中配置敏感信息
-- 定期更换访问密钥
-- **推荐配置方式**：
-
-  ```bash
-  # 生产环境 - 使用环境变量
-  export UNILABOS_BASICCONFIG_AK="your_access_key"
-  export UNILABOS_BASICCONFIG_SK="your_secret_key"
-  unilab
-
-  # 或使用命令行参数
-  unilab --ak "your_access_key" --sk "your_secret_key"
-  ```
-
-### 2. 多环境配置
-
-为不同环境创建不同的配置文件并结合命令行参数：
-
-```
-configs/
-├── local_config.py      # 本地开发
-├── test_config.py       # 测试环境
-├── prod_config.py       # 生产环境
-└── example_config.py    # 示例配置
-```
-
-**环境切换示例**：
-
-```bash
-# 本地开发环境
-unilab --config configs/local_config.py --addr local
-
-# 测试环境
-unilab --config configs/test_config.py --addr test --upload_registry
-
-# 生产环境
-unilab --config configs/prod_config.py --ak "$PROD_AK" --sk "$PROD_SK"
-```
-
-### 3. 配置管理
-
-- 保持配置文件简洁，只包含需要修改的配置项
-- 为配置项添加注释说明其作用
-- 定期检查和更新配置文件
-- **命令行参数优先使用场景**：
-  - 临时测试不同配置
-  - CI/CD 流水线中的动态配置
-  - 不同环境间快速切换
-  - 敏感信息的安全传递
-
-### 4. 灵活配置策略
-
-**基础配置文件 + 命令行覆盖**的推荐方式：
-
-```python
-# base_config.py - 基础配置
-class BasicConfig:
-    # 非敏感配置写在文件中
-    is_host_mode = True
-    upload_registry = False
-    vis_2d_enable = False
-
-class WSConfig:
-    reconnect_interval = 5
-    max_reconnect_attempts = 999
-    ping_interval = 30
-```
-
-```bash
-# 启动时通过命令行覆盖关键参数
-unilab --config base_config.py \
-       --ak "$AK" \
-       --sk "$SK" \
-       --addr "test" \
-       --upload_registry \
-       --2d_vis
-```
-
-## 故障排除
-
-### 1. 配置文件加载失败
-
-**错误信息**：`[ENV] 配置文件 xxx 不存在`
-
-**解决方法**：
-
-- 确认配置文件路径正确
-- 检查文件权限是否可读
-- 确保配置文件是 `.py` 格式
-
-### 2. 语法错误
-
-**错误信息**：`[ENV] 加载配置文件 xxx 失败`
-
-**解决方法**：
-
-- 检查 Python 语法是否正确
-- 确认类名和字段名拼写正确
-- 验证缩进是否正确（使用空格而非制表符）
-
-### 3. 认证失败
-
-**错误信息**：`后续运行必须拥有一个实验室`
-
-**解决方法**：
-
-- 确认 `ak` 和 `sk` 已正确配置
-- 检查密钥是否有效
-- 确认网络连接正常
-
-### 4. 环境变量不生效
-
-**解决方法**：
-
-- 确认环境变量名格式正确（`UNILABOS_CLASS_FIELD`）
-- 检查环境变量是否已正确设置
-- 重启系统或重新加载环境变量
-
-### 5. 命令行参数不生效
-
-**错误现象**：设置了命令行参数但配置没有生效
-
-**解决方法**：
-
-- 确认参数名拼写正确（如 `--ak` 而不是 `--access_key`）
-- 检查参数格式是否正确（布尔参数如 `--is_slave` 不需要值）
-- 确认参数位置正确（所有参数都应在 `unilab` 之后）
-- 查看启动日志确认参数是否被正确解析
-
-### 6. 配置优先级混淆
-
-**错误现象**：不确定哪个配置生效
-
-**解决方法**：
-
-- 记住优先级：命令行参数 > 环境变量 > 配置文件
-- 使用 `--ak` 和 `--sk` 参数时会看到提示信息
-- 检查启动日志中的配置加载信息
-- 临时移除低优先级配置来测试高优先级配置是否生效

docs/user_guide/graph_files.md

@@ -0,0 +1,860 @@
+# 设备图文件说明
+
+设备图文件定义了实验室中所有设备、资源及其连接关系。本文档说明如何创建和使用设备图文件。
+
+## 概述
+
+设备图文件采用 JSON 格式，节点定义基于 **`ResourceDict`** 标准模型（定义在 `unilabos.ros.nodes.resource_tracker`）。系统会自动处理旧格式并转换为标准格式，确保向后兼容性。
+
+**核心概念**:
+
+- **Nodes（节点）**: 代表设备或资源，通过 `parent` 字段建立层级关系
+- **Links（连接）**: 可选的连接关系定义，用于展示设备间的物理或通信连接
+- **UUID**: 全局唯一标识符，用于跨系统的资源追踪
+- **自动转换**: 旧格式会通过 `ResourceDictInstance.get_resource_instance_from_dict()` 自动转换
+
+## 文件格式
+
+Uni-Lab 支持两种格式的设备图文件：
+
+### JSON 格式（推荐）
+
+**优点**:
+
+- 易于编辑和阅读
+- 支持注释（使用预处理）
+- 与 Web 界面完全兼容
+- 便于版本控制
+
+**示例**: `workshop1.json`
+
+### GraphML 格式
+
+**优点**:
+
+- 可用图形化工具编辑（如 yEd）
+- 适合复杂拓扑可视化
+
+**示例**: `setup.graphml`
+
+## JSON 文件结构
+
+一个完整的 JSON 设备图文件包含两个主要部分：
+
+```json
+{
+  "nodes": [
+    /* 设备和资源节点 */
+  ],
+  "links": [
+    /* 连接关系（可选）*/
+  ]
+}
+```
+
+### Nodes（节点）
+
+每个节点代表一个设备或资源。节点的定义遵循 `ResourceDict` 标准模型：
+
+```json
+{
+  "id": "liquid_handler_1",
+  "uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "液体处理工作站",
+  "type": "device",
+  "class": "liquid_handler",
+  "config": {
+    "port": "/dev/ttyUSB0",
+    "baudrate": 9600
+  },
+  "data": {},
+  "position": {
+    "x": 100,
+    "y": 200
+  },
+  "parent": null
+}
+```
+
+**字段说明（基于 ResourceDict 标准定义）**:
+
+| 字段          | 必需 | 说明                     | 示例                                                 | 默认值   |
+| ------------- | ---- | ------------------------ | ---------------------------------------------------- | -------- |
+| `id`          | ✓    | 唯一标识符               | `"pump_1"`                                           | -        |
+| `uuid`        |      | 全局唯一标识符 (UUID)    | `"550e8400-e29b-41d4-a716-446655440000"`             | 自动生成 |
+| `name`        | ✓    | 显示名称                 | `"主反应泵"`                                         | -        |
+| `type`        | ✓    | 节点类型                 | `"device"`, `"resource"`, `"container"`, `"deck"` 等 | -        |
+| `class`       | ✓    | 设备/资源类别            | `"liquid_handler"`, `"syringepump.runze"`            | `""`     |
+| `config`      |      | Python 类的初始化参数    | `{"port": "COM3"}`                                   | `{}`     |
+| `data`        |      | 资源的运行状态数据       | `{"status": "Idle", "position": 0.0}`                | `{}`     |
+| `position`    |      | 在图中的位置             | `{"x": 100, "y": 200}` 或完整的 pose 结构            | -        |
+| `pose`        |      | 完整的 3D 位置信息       | 参见下文                                             | -        |
+| `parent`      |      | 父节点 ID                | `"deck_1"`                                           | `null`   |
+| `parent_uuid` |      | 父节点 UUID              | `"550e8400-..."`                                     | `null`   |
+| `children`    |      | 子节点 ID 列表（旧格式） | `["child1", "child2"]`                               | -        |
+| `description` |      | 资源描述                 | `"用于精确控制试剂A的加料速率"`                      | `""`     |
+| `schema`      |      | 资源 schema 定义         | `{}`                                                 | `{}`     |
+| `model`       |      | 资源 3D 模型信息         | `{}`                                                 | `{}`     |
+| `icon`        |      | 资源图标                 | `"pump.webp"`                                        | `""`     |
+| `extra`       |      | 额外的自定义数据         | `{"custom_field": "value"}`                          | `{}`     |
+
+### Position 和 Pose（位置信息）
+
+**简单格式（旧格式，兼容）**:
+
+```json
+"position": {
+  "x": 100,
+  "y": 200,
+  "z": 0
+}
+```
+
+**完整格式（推荐）**:
+
+```json
+"pose": {
+  "size": {
+    "width": 127.76,
+    "height": 85.48,
+    "depth": 10.0
+  },
+  "scale": {
+    "x": 1.0,
+    "y": 1.0,
+    "z": 1.0
+  },
+  "layout": "x-y",
+  "position": {
+    "x": 100,
+    "y": 200,
+    "z": 0
+  },
+  "position3d": {
+    "x": 100,
+    "y": 200,
+    "z": 0
+  },
+  "rotation": {
+    "x": 0,
+    "y": 0,
+    "z": 0
+  },
+  "cross_section_type": "rectangle"
+}
+```
+
+### Links（连接）
+
+定义节点之间的连接关系（可选，主要用于物理连接或通信关系的可视化）：
+
+```json
+{
+  "source": "pump_1",
+  "target": "reactor_1",
+  "sourceHandle": "output",
+  "targetHandle": "input",
+  "type": "physical"
+}
+```
+
+**字段说明**:
+
+| 字段           | 必需 | 说明             | 示例                                     |
+| -------------- | ---- | ---------------- | ---------------------------------------- |
+| `source`       | ✓    | 源节点 ID        | `"pump_1"`                               |
+| `target`       | ✓    | 目标节点 ID      | `"reactor_1"`                            |
+| `sourceHandle` |      | 源节点的连接点   | `"output"`                               |
+| `targetHandle` |      | 目标节点的连接点 | `"input"`                                |
+| `type`         |      | 连接类型         | `"physical"`, `"communication"`          |
+| `port`         |      | 端口映射信息     | `{"source": "port1", "target": "port2"}` |
+
+**注意**: Links 主要用于图形化展示和文档说明，父子关系通过 `parent` 字段定义，不依赖 links。
+
+## 完整示例
+
+### 示例 1：液体处理工作站（PRCXI9300）
+
+这是一个真实的液体处理工作站配置，包含设备、工作台和多个板资源。
+
+**文件位置**: `test/experiments/prcxi_9300.json`
+
+```json
+{
+  "nodes": [
+    {
+      "id": "PRCXI9300",
+      "name": "PRCXI9300",
+      "parent": null,
+      "type": "device",
+      "class": "liquid_handler.prcxi",
+      "position": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "config": {
+        "deck": {
+          "_resource_child_name": "PRCXI_Deck_9300",
+          "_resource_type": "unilabos.devices.liquid_handling.prcxi.prcxi:PRCXI9300Deck"
+        },
+        "host": "10.181.214.132",
+        "port": 9999,
+        "timeout": 10.0,
+        "axis": "Left",
+        "channel_num": 8,
+        "setup": false,
+        "debug": true,
+        "simulator": true,
+        "matrix_id": "71593"
+      },
+      "data": {},
+      "children": ["PRCXI_Deck_9300"]
+    },
+    {
+      "id": "PRCXI_Deck_9300",
+      "name": "PRCXI_Deck_9300",
+      "parent": "PRCXI9300",
+      "type": "deck",
+      "class": "",
+      "position": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "config": {
+        "type": "PRCXI9300Deck",
+        "size_x": 100,
+        "size_y": 100,
+        "size_z": 100,
+        "rotation": {
+          "x": 0,
+          "y": 0,
+          "z": 0,
+          "type": "Rotation"
+        },
+        "category": "deck"
+      },
+      "data": {},
+      "children": [
+        "RackT1",
+        "PlateT2",
+        "trash",
+        "PlateT4",
+        "PlateT5",
+        "PlateT6"
+      ]
+    },
+    {
+      "id": "RackT1",
+      "name": "RackT1",
+      "parent": "PRCXI_Deck_9300",
+      "type": "tip_rack",
+      "class": "",
+      "position": {
+        "x": 0,
+        "y": 0,
+        "z": 0
+      },
+      "config": {
+        "type": "TipRack",
+        "size_x": 127.76,
+        "size_y": 85.48,
+        "size_z": 100
+      },
+      "data": {},
+      "children": []
+    }
+  ]
+}
+```
+
+**关键点**:
+
+- 使用 `parent` 字段建立层级关系（PRCXI9300 → Deck → Rack/Plate）
+- 使用 `children` 字段（旧格式）列出子节点
+- `config` 中包含设备特定的连接参数
+- `data` 存储运行时状态
+- `position` 使用简单的 x/y/z 坐标
+
+### 示例 2：有机合成工作站（带 Links）
+
+这是一个格林纳德反应的流动化学工作站配置，展示了完整的设备连接和通信关系。
+
+**文件位置**: `test/experiments/Grignard_flow_batchreact_single_pumpvalve.json`
+
+```json
+{
+  "nodes": [
+    {
+      "id": "YugongStation",
+      "name": "愚公常量合成工作站",
+      "parent": null,
+      "type": "device",
+      "class": "workstation",
+      "position": {
+        "x": 620.6111111111111,
+        "y": 171,
+        "z": 0
+      },
+      "config": {
+        "protocol_type": [
+          "PumpTransferProtocol",
+          "CleanProtocol",
+          "SeparateProtocol",
+          "EvaporateProtocol"
+        ]
+      },
+      "data": {},
+      "children": [
+        "serial_pump",
+        "pump_reagents",
+        "flask_CH2Cl2",
+        "reactor",
+        "pump_workup",
+        "separator_controller",
+        "flask_separator",
+        "rotavap",
+        "column"
+      ]
+    },
+    {
+      "id": "serial_pump",
+      "name": "serial_pump",
+      "parent": "YugongStation",
+      "type": "device",
+      "class": "serial",
+      "position": {
+        "x": 620.6111111111111,
+        "y": 171,
+        "z": 0
+      },
+      "config": {
+        "port": "COM7",
+        "baudrate": 9600
+      },
+      "data": {},
+      "children": []
+    },
+    {
+      "id": "pump_reagents",
+      "name": "pump_reagents",
+      "parent": "YugongStation",
+      "type": "device",
+      "class": "syringepump.runze",
+      "position": {
+        "x": 620.6111111111111,
+        "y": 171,
+        "z": 0
+      },
+      "config": {
+        "port": "/devices/PumpBackbone/Serial/serialwrite",
+        "address": "1",
+        "max_volume": 25.0
+      },
+      "data": {
+        "max_velocity": 1.0,
+        "position": 0.0,
+        "status": "Idle",
+        "valve_position": "0"
+      },
+      "children": []
+    },
+    {
+      "id": "reactor",
+      "name": "reactor",
+      "parent": "YugongStation",
+      "type": "container",
+      "class": null,
+      "position": {
+        "x": 430.4087301587302,
+        "y": 428,
+        "z": 0
+      },
+      "config": {},
+      "data": {},
+      "children": []
+    }
+  ],
+  "links": [
+    {
+      "source": "pump_reagents",
+      "target": "serial_pump",
+      "type": "communication",
+      "port": {
+        "pump_reagents": "port",
+        "serial_pump": "port"
+      }
+    },
+    {
+      "source": "pump_workup",
+      "target": "serial_pump",
+      "type": "communication",
+      "port": {
+        "pump_workup": "port",
+        "serial_pump": "port"
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+
+- 多级设备层次：工作站包含多个子设备和容器
+- `links` 定义通信关系（泵通过串口连接）
+- `data` 字段存储设备状态（如泵的位置、速度等）
+- `class` 可以使用点号分层（如 `"syringepump.runze"`）
+- 容器的 `class` 可以为 `null`
+
+## 格式兼容性和转换
+
+### 旧格式自动转换
+
+Uni-Lab 使用 `ResourceDictInstance.get_resource_instance_from_dict()` 方法自动处理旧格式的节点数据，确保向后兼容性。
+
+**自动转换规则**:
+
+1. **自动生成缺失字段**:
+
+   ```python
+   # 如果缺少 id，使用 name 作为 id
+   if "id" not in content:
+       content["id"] = content["name"]
+
+   # 如果缺少 uuid，自动生成
+   if "uuid" not in content:
+       content["uuid"] = str(uuid.uuid4())
+   ```
+
+2. **Position 格式转换**:
+
+   ```python
+   # 旧格式：简单的 x/y 坐标
+   "position": {"x": 100, "y": 200}
+
+   # 自动转换为新格式
+   "position": {
+       "position": {"x": 100, "y": 200}
+   }
+   ```
+
+3. **默认值填充**:
+
+   ```python
+   # 自动填充空字段
+   if not content.get("class"):
+       content["class"] = ""
+   if not content.get("config"):
+       content["config"] = {}
+   if not content.get("data"):
+       content["data"] = {}
+   if not content.get("extra"):
+       content["extra"] = {}
+   ```
+
+4. **Pose 字段同步**:
+   ```python
+   # 如果没有 pose，使用 position
+   if "pose" not in content:
+       content["pose"] = content.get("position", {})
+   ```
+
+### 使用示例
+
+```python
+from unilabos.ros.nodes.resource_tracker import ResourceDictInstance
+
+# 旧格式节点
+old_format_node = {
+    "name": "pump_1",
+    "type": "device",
+    "class": "syringepump",
+    "position": {"x": 100, "y": 200}
+}
+
+# 自动转换为标准格式
+instance = ResourceDictInstance.get_resource_instance_from_dict(old_format_node)
+
+# 访问标准化后的数据
+print(instance.res_content.id)      # "pump_1"
+print(instance.res_content.uuid)    # 自动生成的 UUID
+print(instance.res_content.config)  # {}
+print(instance.res_content.data)    # {}
+```
+
+### 格式迁移建议
+
+虽然系统会自动处理旧格式，但建议在新文件中使用完整的标准格式：
+
+| 字段   | 旧格式（兼容）                     | 新格式（推荐）                                   |
+| ------ | ---------------------------------- | ------------------------------------------------ |
+| 标识符 | 仅 `id` 或仅 `name`                | `id` + `uuid`                                    |
+| 位置   | `"position": {"x": 100, "y": 200}` | 完整的 `pose` 结构                               |
+| 父节点 | `"parent": "parent_id"`            | `"parent": "parent_id"` + `"parent_uuid": "..."` |
+| 配置   | 可省略                             | 显式设置为 `{}`                                  |
+| 数据   | 可省略                             | 显式设置为 `{}`                                  |
+
+## 节点类型详解
+
+### Device 节点
+
+设备节点代表实际的硬件设备：
+
+```json
+{
+  "id": "device_id",
+  "name": "设备名称",
+  "type": "device",
+  "class": "设备类别",
+  "parent": null,
+  "config": {
+    "port": "COM3"
+  },
+  "data": {},
+  "children": []
+}
+```
+
+**常见设备类别**:
+
+- `liquid_handler`: 液体处理工作站
+- `liquid_handler.prcxi`: PRCXI 液体处理工作站
+- `syringepump`: 注射泵
+- `syringepump.runze`: 润泽注射泵
+- `heaterstirrer`: 加热搅拌器
+- `balance`: 天平
+- `reactor_vessel`: 反应釜
+- `serial`: 串口通信设备
+- `workstation`: 自动化工作站
+
+### Resource 节点
+
+资源节点代表物料容器、载具等：
+
+```json
+{
+  "id": "resource_id",
+  "name": "资源名称",
+  "type": "resource",
+  "class": "资源类别",
+  "parent": "父节点ID",
+  "config": {
+    "size_x": 127.76,
+    "size_y": 85.48,
+    "size_z": 100
+  },
+  "data": {},
+  "children": []
+}
+```
+
+**常见资源类型**:
+
+- `deck`: 工作台/甲板
+- `plate`: 板（96 孔板等）
+- `tip_rack`: 枪头架
+- `tube`: 试管
+- `container`: 容器
+- `well`: 孔位
+- `bottle_carrier`: 瓶架
+
+## Handle（连接点）
+
+每个设备和资源可以有多个连接点（handles），用于定义可以连接的接口。
+
+### 查看可用 handles
+
+设备和资源的可用 handles 定义在注册表中：
+
+```yaml
+# 设备注册表示例
+liquid_handler:
+  handles:
+    - handler_key: pipette
+      io_type: source
+    - handler_key: deck
+      io_type: target
+```
+
+### 常见 handles
+
+| 设备类型   | Source Handles | Target Handles |
+| ---------- | -------------- | -------------- |
+| 泵         | output         | input          |
+| 反应釜     | output, vessel | input          |
+| 液体处理器 | pipette        | deck           |
+| 板         | wells          | access         |
+
+## 使用 Web 界面创建图文件
+
+Uni-Lab 提供 Web 界面来可视化创建和编辑设备图：
+
+### 1. 启动 Uni-Lab
+
+```bash
+unilab
+```
+
+### 2. 访问 Web 界面
+
+打开浏览器访问 `http://localhost:8002`
+
+### 3. 图形化编辑
+
+- 拖拽添加设备和资源
+- 连线建立连接关系
+- 编辑节点属性
+- 保存为 JSON 文件
+
+### 4. 导出图文件
+
+点击"导出"按钮，下载 JSON 文件到本地。
+
+## 从云端获取图文件
+
+如果不指定`-g`参数，Uni-Lab 会自动从云端获取：
+
+```bash
+# 使用云端配置
+unilab
+
+# 日志会显示:
+# [INFO] 未指定设备加载文件路径，尝试从HTTP获取...
+# [INFO] 联网获取设备加载文件成功
+```
+
+**云端图文件管理**:
+
+1. 登录 https://uni-lab.bohrium.com
+2. 进入"设备配置"
+3. 创建或编辑配置
+4. 保存到云端
+
+本地启动时会自动同步最新配置。
+
+## 调试图文件
+
+### 验证 JSON 格式
+
+```bash
+# 使用Python验证
+python -c "import json; json.load(open('workshop1.json'))"
+
+# 使用在线工具
+# https://jsonlint.com/
+```
+
+### 检查节点引用
+
+确保：
+
+- 所有`links`中的`source`和`target`都存在于`nodes`中
+- `parent`字段指向的节点存在
+- `class`字段对应的设备/资源在注册表中存在
+
+### 启动时验证
+
+```bash
+# Uni-Lab启动时会验证图文件
+unilab -g workshop1.json
+
+# 查看日志中的错误或警告
+# [ERROR] 节点 xxx 的source端点 yyy 不存在
+# [WARNING] 节点 zzz missing 'name', defaulting to ...
+```
+
+## 最佳实践
+
+### 1. 命名规范
+
+```json
+{
+  "id": "pump_reagent_1", // 小写+下划线，描述性
+  "name": "试剂进料泵A", // 中文显示名称
+  "class": "syringepump" // 使用注册表中的精确名称
+}
+```
+
+### 2. 层级组织
+
+```
+host_node (主节点)
+└── liquid_handler_1 (设备)
+    └── deck_1 (资源)
+        ├── tiprack_1 (资源)
+        ├── plate_1 (资源)
+        └── reservoir_1 (资源)
+```
+
+### 3. 配置分离
+
+将设备特定配置放在`config`中：
+
+```json
+{
+  "id": "pump_1",
+  "class": "syringepump",
+  "config": {
+    "port": "COM3", // 设备特定
+    "max_flow_rate": 10, // 设备特定
+    "volume": 50 // 设备特定
+  }
+}
+```
+
+### 4. 版本控制
+
+```bash
+# 使用Git管理图文件
+git add workshop1.json
+git commit -m "Add new liquid handler configuration"
+
+# 使用有意义的文件名
+workshop_v1.json
+workshop_production.json
+workshop_test.json
+```
+
+### 5. 注释（通过描述字段）
+
+虽然 JSON 不支持注释，但可以使用`description`字段：
+
+```json
+{
+  "id": "pump_1",
+  "name": "进料泵",
+  "description": "用于精确控制试剂A的加料速率，最大流速10mL/min",
+  "class": "syringepump"
+}
+```
+
+## 示例文件位置
+
+Uni-Lab 在安装时已预置了 **40+ 个真实的设备图文件示例**，位于 `unilabos/test/experiments/` 目录。这些都是真实项目中使用的配置文件，可以直接使用或作为参考。
+
+### 📁 主要示例文件
+
+```
+test/experiments/
+├── workshop.json                                 # 综合工作台（推荐新手）
+├── empty_devices.json                            # 空设备配置（最小化）
+├── prcxi_9300.json                               # PRCXI液体处理工作站（本文示例1）
+├── prcxi_9320.json                               # PRCXI 9320工作站
+├── biomek.json                                   # Biomek液体处理工作站
+├── Grignard_flow_batchreact_single_pumpvalve.json # 格林纳德反应工作站（本文示例2）
+├── dispensing_station_bioyond.json               # Bioyond配液站
+├── reaction_station_bioyond.json                 # Bioyond反应站
+├── HPLC.json                                     # HPLC分析系统
+├── plr_test.json                                 # PyLabRobot测试配置
+├── lidocaine-graph.json                          # 利多卡因合成工作站
+├── opcua_example.json                            # OPC UA设备集成示例
+│
+├── mock_devices/                                 # 虚拟设备（用于离线测试）
+│   ├── mock_all.json                             # 完整虚拟设备集
+│   ├── mock_pump.json                            # 虚拟泵
+│   ├── mock_stirrer.json                         # 虚拟搅拌器
+│   ├── mock_heater.json                          # 虚拟加热器
+│   └── ...                                       # 更多虚拟设备
+│
+├── Protocol_Test_Station/                        # 协议测试工作站
+│   ├── pumptransfer_test_station.json            # 泵转移协议测试
+│   ├── heatchill_protocol_test_station.json      # 加热冷却协议测试
+│   ├── filter_protocol_test_station.json         # 过滤协议测试
+│   └── ...                                       # 更多协议测试
+│
+└── comprehensive_protocol/                       # 综合协议示例
+    ├── comprehensive_station.json                # 综合工作站
+    └── comprehensive_slim.json                   # 精简版综合工作站
+```
+
+### 🚀 快速使用
+
+无需下载或创建，直接使用 `-g` 参数指定路径：
+
+```bash
+# 使用简单工作台（推荐新手）
+unilab --ak your_ak --sk your_sk -g test/experiments/workshop.json
+
+# 使用虚拟设备（无需真实硬件）
+unilab --ak your_ak --sk your_sk -g test/experiments/mock_devices/mock_all.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
+```
+
+### 📚 文件分类
+
+| 类别         | 说明                     | 文件数量 |
+| ------------ | ------------------------ | -------- |
+| **主工作站** | 完整的实验工作站配置     | 15+      |
+| **虚拟设备** | 用于开发测试的 mock 设备 | 10+      |
+| **协议测试** | 各种实验协议的测试配置   | 12+      |
+| **综合示例** | 包含多种协议的综合工作站 | 3+       |
+
+这些文件展示了不同场景下的设备图配置，涵盖液体处理、有机合成、分析检测等多个领域，是学习和创建自己配置的绝佳参考。
+
+## 快速参考：ResourceDict 完整字段列表
+
+基于 `unilabos.ros.nodes.resource_tracker.ResourceDict` 的完整字段定义：
+
+```python
+class ResourceDict(BaseModel):
+    # === 基础标识 ===
+    id: str                          # 资源ID（必需）
+    uuid: str                        # 全局唯一标识符（自动生成）
+    name: str                        # 显示名称（必需）
+
+    # === 类型和分类 ===
+    type: Union[Literal["device"], str]  # 节点类型（必需）
+    klass: str                       # 资源类别（alias="class"，必需）
+
+    # === 层级关系 ===
+    parent: Optional[ResourceDict]   # 父资源对象（不序列化）
+    parent_uuid: Optional[str]       # 父资源UUID
+
+    # === 位置和姿态 ===
+    position: ResourceDictPosition   # 位置信息
+    pose: ResourceDictPosition       # 姿态信息（推荐使用）
+
+    # === 配置和数据 ===
+    config: Dict[str, Any]           # 设备配置参数
+    data: Dict[str, Any]             # 运行时状态数据
+    extra: Dict[str, Any]            # 额外自定义数据
+
+    # === 元数据 ===
+    description: str                 # 资源描述
+    resource_schema: Dict[str, Any]  # schema定义（alias="schema"）
+    model: Dict[str, Any]            # 3D模型信息
+    icon: str                        # 图标路径
+```
+
+**Position/Pose 结构**:
+
+```python
+class ResourceDictPosition(BaseModel):
+    size: ResourceDictPositionSize           # width, height, depth
+    scale: ResourceDictPositionScale         # x, y, z
+    layout: Literal["2d", "x-y", "z-y", "x-z"]
+    position: ResourceDictPositionObject     # x, y, z
+    position3d: ResourceDictPositionObject   # x, y, z
+    rotation: ResourceDictPositionObject     # x, y, z
+    cross_section_type: Literal["rectangle", "circle", "rounded_rectangle"]
+```
+
+## 下一步
+
+- {doc}`../boot_examples/index` - 查看完整启动示例
+- {doc}`../developer_guide/add_device` - 了解如何添加新设备
+- {doc}`06_troubleshooting` - 图文件相关问题排查
+- 源码参考: `unilabos/ros/nodes/resource_tracker.py` - ResourceDict 标准定义
+
+## 获取帮助
+
+- 在 Web 界面中使用模板创建
+- 参考示例文件：`test/experiments/` 目录
+- 查看 ResourceDict 源码了解完整定义
+- [GitHub 讨论区](https://github.com/dptech-corp/Uni-Lab-OS/discussions)

docs/user_guide/installation.md

@@ -1,43 +1,516 @@
-# **Uni-Lab 安装**
+# Uni-Lab-OS 安装指南
 
-## 快速开始
+本指南提供 Uni-Lab-OS 的完整安装说明，涵盖从快速一键安装到完整开发环境配置的所有方式。
 
-1. **配置 Conda 环境**
+## 系统要求
 
-Uni-Lab-OS 建议使用 `mamba` 管理环境。创建新的环境：
+- **操作系统**: Windows 10/11, Linux (Ubuntu 20.04+), macOS (10.15+)
+- **内存**: 最小 4GB，推荐 8GB 以上
+- **磁盘空间**: 至少 10GB 可用空间
+- **网络**: 稳定的互联网连接（用于下载软件包）
+- **其他**:
+  - 已安装 Conda/Miniconda/Miniforge/Mamba
+  - 开发者需要 Git 和基本的 Python 开发知识
+  - 自定义 msgs 需要 GitHub 账号
 
-```shell
+## 安装方式选择
+
+根据您的使用场景，选择合适的安装方式：
+
+| 安装方式               | 适用人群             | 特点                           | 安装时间                     |
+| ---------------------- | -------------------- | ------------------------------ | ---------------------------- |
+| **方式一：一键安装**   | 实验室用户、快速体验 | 预打包环境，离线可用，无需配置 | 5-10 分钟 (网络良好的情况下) |
+| **方式二：手动安装**   | 标准用户、生产环境   | 灵活配置，版本可控             | 10-20 分钟                   |
+| **方式三：开发者安装** | 开发者、需要修改源码 | 可编辑模式，支持自定义 msgs    | 20-30 分钟                   |
+
+---
+
+## 方式一：一键安装（推荐新用户）
+
+使用预打包的 conda 环境，最快速的安装方法。
+
+### 前置条件
+
+确保已安装 Conda/Miniconda/Miniforge/Mamba。
+
+### 安装步骤
+
+#### 第一步：下载预打包环境
+
+1. 访问 [GitHub Actions - Conda Pack Build](https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/conda-pack-build.yml)
+
+2. 选择最新的成功构建记录（绿色勾号 ✓）
+
+3. 在页面底部的 "Artifacts" 部分，下载对应你操作系统的压缩包：
+   - Windows: `unilab-pack-win-64-{branch}.zip`
+   - macOS (Intel): `unilab-pack-osx-64-{branch}.tar.gz`
+   - macOS (Apple Silicon): `unilab-pack-osx-arm64-{branch}.tar.gz`
+   - Linux: `unilab-pack-linux-64-{branch}.tar.gz`
+
+#### 第二步：解压并运行安装脚本
+
+**Windows**:
+
+```batch
+REM 使用 Windows 资源管理器解压下载的 zip 文件
+REM 或使用命令行：
+tar -xzf unilab-pack-win-64-dev.zip
+
+REM 进入解压后的目录
+cd unilab-pack-win-64-dev
+
+REM 双击运行 install_unilab.bat
+REM 或在命令行中执行：
+install_unilab.bat
+```
+
+**macOS**:
+
+```bash
+# 解压下载的压缩包
+tar -xzf unilab-pack-osx-arm64-dev.tar.gz
+
+# 进入解压后的目录
+cd unilab-pack-osx-arm64-dev
+
+# 运行安装脚本
+bash install_unilab.sh
+```
+
+**Linux**:
+
+```bash
+# 解压下载的压缩包
+tar -xzf unilab-pack-linux-64-dev.tar.gz
+
+# 进入解压后的目录
+cd unilab-pack-linux-64-dev
+
+# 添加执行权限（如果需要）
+chmod +x install_unilab.sh
+
+# 运行安装脚本
+./install_unilab.sh
+```
+
+#### 第三步：激活环境
+
+```bash
+conda activate unilab
+```
+
+激活后，您的命令行提示符应该会显示 `(unilab)` 前缀。
+
+---
+
+## 方式二：手动安装（标准用户）
+
+适合生产环境和需要灵活配置的用户。
+
+### 第一步：安装 Mamba 环境管理器
+
+Mamba 是 Conda 的快速替代品，我们强烈推荐使用 Mamba 来管理 Uni-Lab 环境。
+
+#### Windows
+
+下载并安装 Miniforge（包含 Mamba）:
+
+```powershell
+# 访问 https://github.com/conda-forge/miniforge/releases
+# 下载 Miniforge3-Windows-x86_64.exe
+# 运行安装程序
+
+# 也可以使用镜像站 https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease/
+# 下载 Miniforge3-Windows-x86_64.exe
+# 运行安装程序
+```
+
+#### Linux/macOS
+
+```bash
+# 下载 Miniforge 安装脚本
+curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
+
+# 运行安装
+bash Miniforge3-$(uname)-$(uname -m).sh
+
+# 按照提示完成安装，建议选择 yes 来初始化
+```
+
+安装完成后，重新打开终端使 Mamba 生效。
+
+### 第二步：创建 Uni-Lab 环境
+
+使用以下命令创建 Uni-Lab 专用环境：
+
+```bash
+mamba create -n unilab python=3.11.11  # 目前ros2组件依赖版本大多为3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+```
+
+**参数说明**:
+
+- `-n unilab`: 创建名为 "unilab" 的环境
+- `uni-lab::unilabos`: 从 uni-lab channel 安装 unilabos 包
+- `-c robostack-staging -c conda-forge`: 添加额外的软件源
+
+**如果遇到网络问题**，可以使用清华镜像源加速下载：
+
+```bash
+# 配置清华镜像源
+mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
+mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
+mamba config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
+
+# 然后重新执行安装命令
+mamba create -n unilab uni-lab::unilabos -c robostack-staging
+```
+
+### 第三步：激活环境
+
+```bash
+conda activate unilab
+```
+
+---
+
+## 方式三：开发者安装
+
+适用于需要修改 Uni-Lab 源代码或开发新设备驱动的开发者。
+
+### 前置条件
+
+- 已安装 Git
+- 已安装 Mamba/Conda
+- 有 GitHub 账号（如需自定义 msgs）
+- 基本的 Python 开发知识
+
+### 第一步：克隆仓库
+
+```bash
+git clone https://github.com/dptech-corp/Uni-Lab-OS.git
+cd Uni-Lab-OS
+```
+
+如果您需要贡献代码，建议先 Fork 仓库：
+
+1. 访问 https://github.com/dptech-corp/Uni-Lab-OS
+2. 点击右上角的 "Fork" 按钮
+3. Clone 您的 Fork 版本：
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/Uni-Lab-OS.git
+   cd Uni-Lab-OS
+   ```
+
+### 第二步：安装基础环境
+
+**推荐方式**：先通过**方式一（一键安装）**或**方式二（手动安装）**完成基础环境的安装，这将包含所有必需的依赖项（ROS2、msgs 等）。
+
+#### 选项 A：通过一键安装（推荐）
+
+参考上文"方式一：一键安装"，完成基础环境的安装后，激活环境：
+
+```bash
+conda activate unilab
+```
+
+#### 选项 B：通过手动安装
+
+参考上文"方式二：手动安装"，创建并安装环境：
+
+```bash
+mamba create -n unilab python=3.11.11
+conda activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+```
+
+**说明**：这会安装包括 Python 3.11.11、ROS2 Humble、ros-humble-unilabos-msgs 和所有必需依赖
+
+### 第三步：切换到开发版本
+
+现在你已经有了一个完整可用的 Uni-Lab 环境，接下来将 unilabos 包切换为开发版本：
+
+```bash
+# 确保环境已激活
+conda activate unilab
+
+# 卸载 pip 安装的 unilabos（保留所有 conda 依赖）
+pip uninstall unilabos -y
+
+# 克隆 dev 分支（如果还未克隆）
+cd /path/to/your/workspace
+git clone -b dev https://github.com/dptech-corp/Uni-Lab-OS.git
+# 或者如果已经克隆，切换到 dev 分支
+cd Uni-Lab-OS
+git checkout dev
+git pull
+
+# 以可编辑模式安装开发版 unilabos
+pip install -e . -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+```
+
+**参数说明**：
+
+- `-e`: editable mode（可编辑模式），代码修改立即生效，无需重新安装
+- `-i`: 使用清华镜像源加速下载
+- `pip uninstall unilabos`: 只卸载 pip 安装的 unilabos 包，不影响 conda 安装的其他依赖（如 ROS2、msgs 等）
+
+### 第四步：安装或自定义 ros-humble-unilabos-msgs（可选）
+
+Uni-Lab 使用 ROS2 消息系统进行设备间通信。如果你使用方式一或方式二安装，msgs 包已经自动安装。
+
+#### 使用已安装的 msgs（大多数用户）
+
+如果你不需要修改 msgs，可以跳过此步骤，直接使用已安装的 msgs 包。验证安装：
+
+```bash
+# 列出所有 unilabos_msgs 接口
+ros2 interface list | grep unilabos_msgs
+
+# 查看特定 action 定义
+ros2 interface show unilabos_msgs/action/DeviceCmd
+```
+
+#### 自定义 msgs（高级用户）
+
+如果你需要：
+
+- 添加新的 ROS2 action 定义
+- 修改现有 msg/srv/action 接口
+- 为特定设备定制通信协议
+
+请参考 **[添加新动作指令（Action）指南](../developer_guide/add_action.md)**，该指南详细介绍了如何：
+
+- 编写新的 Action 定义
+- 在线构建 Action（通过 GitHub Actions）
+- 下载并安装自定义的 msgs 包
+- 测试和验证新的 Action
+
+```bash
+# 安装自定义构建的 msgs 包
+mamba remove --force ros-humble-unilabos-msgs
+mamba config set safety_checks disabled  # 关闭 md5 检查
+mamba install /path/to/ros-humble-unilabos-msgs-*.conda --offline
+```
+
+### 第五步：验证开发环境
+
+完成上述步骤后，验证开发环境是否正确配置：
+
+```bash
+# 确保环境已激活
+conda activate unilab
+
+# 检查 ROS2 环境
+ros2 --version
+
+# 检查 msgs 包
+ros2 interface list | grep unilabos_msgs
+
+# 检查 Python 可以导入 unilabos
+python -c "import unilabos; print(f'Uni-Lab版本: {unilabos.__version__}')"
+
+# 检查 unilab 命令
+unilab --help
+```
+
+如果所有命令都正常输出，说明开发环境配置成功！
+
+---
+
+## 验证安装
+
+无论使用哪种安装方式，都应该验证安装是否成功。
+
+### 基本验证
+
+```bash
+# 确保已激活环境
+conda activate unilab  # 或 unilab-dev
+
+# 检查 unilab 命令
+unilab --help
+```
+
+您应该看到类似以下的输出：
+
+```
+usage: unilab [-h] [-g GRAPH] [-c CONTROLLERS] [--registry_path REGISTRY_PATH]
+              [--working_dir WORKING_DIR] [--backend {ros,simple,automancer}]
+              ...
+```
+
+### 检查版本
+
+```bash
+python -c "import unilabos; print(f'Uni-Lab版本: {unilabos.__version__}')"
+```
+
+### 使用验证脚本（方式一）
+
+如果使用一键安装，可以运行预打包的验证脚本：
+
+```bash
+# 确保已激活环境
+conda activate unilab
+
+# 运行验证脚本
+python verify_installation.py
+```
+
+如果看到 "✓ All checks passed!"，说明安装成功！
+
+---
+
+## 常见问题
+
+### 问题 1: 找不到 unilab 命令
+
+**原因**: 环境未正确激活或 PATH 未设置
+
+**解决方案**:
+
+```bash
+# 确保激活了正确的环境
+conda activate unilab
+
+# 检查 unilab 是否在 PATH 中
+which unilab  # Linux/macOS
+where unilab  # Windows
+```
+
+### 问题 2: 包冲突或依赖错误
+
+**解决方案**:
+
+```bash
+# 删除旧环境重新创建
+conda deactivate
+conda env remove -n unilab
 mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```
 
-2. **安装开发版 Uni-Lab-OS**
+### 问题 3: 下载速度慢
 
-```shell
-# 配置好conda环境后，克隆仓库
-git clone https://github.com/dptech-corp/Uni-Lab-OS.git -b dev
-cd Uni-Lab-OS
+**解决方案**: 使用国内镜像源（清华、中科大等）
 
-# 安装 Uni-Lab-OS
-pip install -e .
+```bash
+# 查看当前 channel 配置
+conda config --show channels
+
+# 添加清华镜像
+conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
 ```
 
-3. **安装开发版 ros-humble-unilabos-msgs**
+### 问题 4: 权限错误
 
-**卸载老版本：**
-```shell
+**Windows 解决方案**: 以管理员身份运行命令提示符
+
+**Linux/macOS 解决方案**:
+
+```bash
+# 不要使用 sudo 安装 conda 包
+# 如果 conda 安装在需要权限的位置，考虑重新安装 conda 到用户目录
+```
+
+### 问题 5: 安装脚本找不到 conda（方式一）
+
+**解决方案**: 确保你已经安装了 conda/miniconda/miniforge，并且安装在标准位置：
+
+- **Windows**:
+
+  - `%USERPROFILE%\miniforge3`
+  - `%USERPROFILE%\miniconda3`
+  - `%USERPROFILE%\anaconda3`
+  - `C:\ProgramData\miniforge3`
+
+- **macOS/Linux**:
+  - `~/miniforge3`
+  - `~/miniconda3`
+  - `~/anaconda3`
+  - `/opt/conda`
+
+如果安装在其他位置，可以先激活 conda base 环境，然后手动运行安装脚本。
+
+### 问题 6: 安装后激活环境提示找不到？
+
+**解决方案**: 尝试以下方法：
+
+```bash
+# 方法 1: 使用 conda activate
 conda activate unilab
-conda remove --force ros-humble-unilabos-msgs
-```
-有时相同的安装包版本会由于dev构建得到的md5不一样，触发安全检查，可输入 `config set safety_checks disabled` 来关闭安全检查。
 
-**安装新版本：**
+# 方法 2: 使用完整路径激活（Windows）
+call C:\Users\{YourUsername}\miniforge3\envs\unilab\Scripts\activate.bat
 
-访问 https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/multi-platform-build.yml 选择最新的构建，下载对应平台的压缩包（仅解压一次，得到.conda文件）使用如下指令：
-```shell
-conda activate base
-conda install ros-humble-unilabos-msgs-<version>-<platform>.conda --offline -n <环境名>
+# 方法 2: 使用完整路径激活（Unix）
+source ~/miniforge3/envs/unilab/bin/activate
 ```
 
-4. **启动 Uni-Lab 系统**
+### 问题 7: conda-unpack 失败怎么办？（方式一）
 
-请参见{doc}`启动样例 <../boot_examples/index>`或{doc}`启动指南 <launch>`了解详细的启动方法。
+**解决方案**: 尝试手动运行：
+
+```bash
+# Windows
+cd %CONDA_PREFIX%\envs\unilab
+.\Scripts\conda-unpack.exe
+
+# macOS/Linux
+cd $CONDA_PREFIX/envs/unilab
+./bin/conda-unpack
+```
+
+### 问题 8: 环境很大，有办法减小吗？
+
+**解决方案**: 预打包的环境包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。如果空间有限，考虑使用方式二手动安装，只安装需要的组件。
+
+### 问题 9: 如何更新到最新版本？
+
+**解决方案**:
+
+**方式一用户**: 重新下载最新的预打包环境，运行安装脚本时选择覆盖现有环境。
+
+**方式二/三用户**: 在现有环境中更新：
+
+```bash
+conda activate unilab
+
+# 更新 unilabos
+cd /path/to/Uni-Lab-OS
+git pull
+pip install -e . --upgrade -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
+
+# 更新 ros-humble-unilabos-msgs
+mamba update ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge
+```
+
+---
+
+## 下一步
+
+安装完成后，请继续：
+
+- **快速启动**: 学习如何首次启动 Uni-Lab
+- **配置指南**: 配置您的实验室环境和设备
+- **运行示例**: 查看启动示例和最佳实践
+- **开发指南**:
+  - 添加新设备驱动
+  - 添加新物料资源
+  - 了解工作站架构
+
+## 需要帮助？
+
+- **故障排查**: 查看更详细的故障排查信息
+- **GitHub Issues**: [报告问题](https://github.com/dptech-corp/Uni-Lab-OS/issues)
+- **开发者文档**: 查看开发者指南获取更多技术细节
+- **社区讨论**: [GitHub Discussions](https://github.com/dptech-corp/Uni-Lab-OS/discussions)
+
+---
+
+**提示**:
+
+- 生产环境推荐使用方式二（手动安装）的稳定版本
+- 开发和测试推荐使用方式三（开发者安装）
+- 快速体验和演示推荐使用方式一（一键安装）

docs/user_guide/launch.md

@@ -132,15 +132,14 @@ unilab --config path/to/your/config.py
 
 使用 `-c` 传入控制逻辑配置。
 
-不管使用哪一种初始化方式，设备/物料字典均需包含 `class` 属性，用于查找注册表信息。默认查找范围都是 Uni-Lab 内部注册表 `unilabos/registry/{devices,device_comms,resources}`。要添加额外的注册表路径，可以使用 `--registry_path` 加入 `<your-registry-path>/{devices,device_comms,resources}`。
+不管使用哪一种初始化方式，设备/物料字典均需包含 `class` 属性，用于查找注册表信息。默认查找范围都是 Uni-Lab 内部注册表 `unilabos/registry/{devices,device_comms,resources}`。要添加额外的注册表路径，可以使用 `--registry_path` 加入 `<your-registry-path>/{devices,device_comms,resources}`，只输入<your-registry-path>即可，支持多次--registry_path指定多个目录。
 
 ## 通信中间件 `--backend`
 
 目前 Uni-Lab 支持以下通信中间件：
 
 - **ros** (默认)：基于 ROS2 的通信
-- **simple**：简化通信模式
-- **automancer**：Automancer 兼容模式
+- **automancer**：Automancer 兼容模式 (实验性)
 
 ## 端云桥接 `--app_bridges`
 
@@ -169,7 +168,7 @@ unilab --config path/to/your/config.py
 通过 `--visual` 参数选择：
 
 - **rviz**：使用 RViz 进行 3D 可视化
-- **web**：使用 Web 界面进行可视化
+- **web**：使用 Web 界面进行可视化 (基于Pylabrobot)
 - **disable** (默认)：禁用可视化
 
 ## 实验室管理
@@ -245,78 +244,3 @@ unilab --ak your_ak --sk your_sk --port 8080 --disable_browser
 - 检查图谱文件格式是否正确
 - 验证设备连接和端点配置
 - 确保注册表路径正确
-
-## 页面操作
-
-### 1. 启动成功
-当您启动成功后，可以看到物料列表，节点模版和组态图如图展示
-![material.png](image/material.png)
-
-### 2. 根据需求创建设备和物料
-我们可以做一个简单的案例  
-* 在容器1中加入水  
-* 通过传输泵将容器1中的水转移到容器2中
-#### 2.1 添加所需的设备和物料  
-仪器设备work_station中的workstation 数量x1  
-仪器设备virtual_device中的virtual_transfer_pump 数量x1    
-物料耗材container中的container 数量x2  
-
-#### 2.2 将设备和物料根据父子关系进行关联  
-当我们添加设备时，仪器耗材模块的物料列表也会实时更新  
-我们需要将设备和物料拖拽到workstation中并在画布上将它们连接起来，就像真实的设备操作一样  
-![links.png](image/links.png)
-
-### 3. 创建工作流
-进入工作流模块 → 点击"我创建的" → 新建工作流
-![new.png](image/new.png)
-
-#### 3.1 新增工作流节点
-我们可以进入指定工作流，在空白处右键   
-* 选择Laboratory→host_node中的creat_resource
-* 选择Laboratory→workstation中的PumpTransferProtocol
-
-![creatworkfollow.gif](image/creatworkfollow.gif)
-
-#### 3.2 配置节点参数
-根据案例，工作流包含两个步骤：
-1. 使用creat_resource在容器中创建水
-2. 通过泵传输协议将水传输到另一个容器
-
-我们点击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 运行工作流
-1. 连接两个节点卡片
-2. 点击底部保存按钮
-3. 点击运行按钮执行工作流
-
-![linksandrun.png](image/linksandrun.png)
-
-### 运行监控
-* 运行状态和消息实时显示在底部控制台
-* 如有报错，可点击查看详细信息
-
-### 结果验证
-工作流完成后，返回仪器耗材模块：
-* 点击 container1卡片查看详情
-* 确认其中包含参数指定的水和容量
-
-
-
-

docs/user_guide/quick_install_guide.md

@@ -1,197 +0,0 @@
-# Uni-Lab-OS 一键安装快速指南
-
-## 概述
-
-本指南提供最快速的 Uni-Lab-OS 安装方法，使用预打包的 conda 环境，无需手动配置依赖。
-
-## 前置要求
-
-- 已安装 Conda/Miniconda/Miniforge/Mamba
-- 至少 10GB 可用磁盘空间
-- Windows 10+, macOS 10.14+, 或 Linux (Ubuntu 20.04+)
-
-## 安装步骤
-
-### 第一步：下载预打包环境
-
-1. 访问 [GitHub Actions - Conda Pack Build](https://github.com/dptech-corp/Uni-Lab-OS/actions/workflows/conda-pack-build.yml)
-
-2. 选择最新的成功构建记录（绿色勾号 ✓）
-
-3. 在页面底部的 "Artifacts" 部分，下载对应你操作系统的压缩包：
-   - Windows: `unilab-pack-win-64-{branch}.zip`
-   - macOS (Intel): `unilab-pack-osx-64-{branch}.tar.gz`
-   - macOS (Apple Silicon): `unilab-pack-osx-arm64-{branch}.tar.gz`
-   - Linux: `unilab-pack-linux-64-{branch}.tar.gz`
-
-### 第二步：解压并运行安装脚本
-
-#### Windows
-
-```batch
-REM 使用 Windows 资源管理器解压下载的 zip 文件
-REM 或使用命令行：
-tar -xzf unilab-pack-win-64-dev.zip
-
-REM 进入解压后的目录
-cd unilab-pack-win-64-dev
-
-REM 双击运行 install_unilab.bat
-REM 或在命令行中执行：
-install_unilab.bat
-```
-
-#### macOS
-
-```bash
-# 解压下载的压缩包
-tar -xzf unilab-pack-osx-arm64-dev.tar.gz
-
-# 进入解压后的目录
-cd unilab-pack-osx-arm64-dev
-
-# 运行安装脚本
-bash install_unilab.sh
-```
-
-#### Linux
-
-```bash
-# 解压下载的压缩包
-tar -xzf unilab-pack-linux-64-dev.tar.gz
-
-# 进入解压后的目录
-cd unilab-pack-linux-64-dev
-
-# 添加执行权限（如果需要）
-chmod +x install_unilab.sh
-
-# 运行安装脚本
-./install_unilab.sh
-```
-
-### 第三步：激活环境
-
-```bash
-conda activate unilab
-```
-
-### 第四步：验证安装（推荐）
-
-```bash
-# 确保已激活环境
-conda activate unilab
-
-# 运行验证脚本
-python verify_installation.py
-```
-
-如果看到 "✓ All checks passed!"，说明安装成功！
-
-## 常见问题
-
-### Q: 安装脚本找不到 conda？
-
-**A:** 确保你已经安装了 conda/miniconda/miniforge，并且安装在标准位置：
-
-- **Windows**:
-
-  - `%USERPROFILE%\miniforge3`
-  - `%USERPROFILE%\miniconda3`
-  - `%USERPROFILE%\anaconda3`
-  - `C:\ProgramData\miniforge3`
-
-- **macOS/Linux**:
-  - `~/miniforge3`
-  - `~/miniconda3`
-  - `~/anaconda3`
-  - `/opt/conda`
-
-如果安装在其他位置，可以先激活 conda base 环境，然后手动运行安装脚本。
-
-### Q: 安装后激活环境提示找不到？
-
-**A:** 尝试以下方法：
-
-```bash
-# 方法 1: 使用 conda activate
-conda activate unilab
-
-# 方法 2: 使用完整路径激活（Windows）
-call C:\Users\{YourUsername}\miniforge3\envs\unilab\Scripts\activate.bat
-
-# 方法 2: 使用完整路径激活（Unix）
-source ~/miniforge3/envs/unilab/bin/activate
-```
-
-### Q: conda-unpack 失败怎么办？
-
-**A:** 尝试手动运行：
-
-```bash
-# Windows
-cd %CONDA_PREFIX%\envs\unilab
-.\Scripts\conda-unpack.exe
-
-# macOS/Linux
-cd $CONDA_PREFIX/envs/unilab
-./bin/conda-unpack
-```
-
-### Q: 验证脚本报错？
-
-**A:** 首先确认环境已激活：
-
-```bash
-# 检查当前环境
-conda env list
-
-# 应该看到 unilab 前面有 * 标记
-```
-
-如果仍有问题，查看具体报错信息，可能需要：
-
-- 重新运行安装脚本
-- 检查磁盘空间
-- 查看详细文档
-
-### Q: 环境很大，有办法减小吗？
-
-**A:** 预打包的环境包含所有依赖，通常较大（压缩后 2-5GB）。这是为了确保离线安装和完整功能。如果空间有限，考虑使用手动安装方式，只安装需要的组件。
-
-### Q: 如何更新到最新版本？
-
-**A:** 重新下载最新的预打包环境，运行安装脚本时选择覆盖现有环境。
-
-或者在现有环境中更新：
-
-```bash
-conda activate unilab
-
-# 更新 unilabos
-cd /path/to/Uni-Lab-OS
-git pull
-pip install -e . --upgrade
-
-# 更新 ros-humble-unilabos-msgs
-mamba update ros-humble-unilabos-msgs -c uni-lab -c robostack-staging -c conda-forge
-```
-
-## 下一步
-
-安装完成后，你可以：
-
-1. **查看启动指南**: {doc}`launch`
-2. **运行示例**: {doc}`../boot_examples/index`
-3. **配置设备**: 编辑 `unilabos_data/startup_config.json`
-4. **阅读开发文档**: {doc}`../developer_guide/workstation_architecture`
-
-## 需要帮助？
-
-- **文档**: [docs/user_guide/installation.md](installation.md)
-- **问题反馈**: [GitHub Issues](https://github.com/dptech-corp/Uni-Lab-OS/issues)
-- **开发版安装**: 参考 {doc}`installation` 的方式二
-
----
-
-**提示**: 这个预打包环境包含了从指定分支（通常是 `dev`）构建的最新代码。如果需要稳定版本，请使用方式二手动安装 release 版本。

recipes/msgs/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: ros-humble-unilabos-msgs
-  version: 0.10.7
+  version: 0.10.12
 source:
   path: ../../unilabos_msgs
   target_directory: src

recipes/ros-humble-unilabos-msgs/bld_ament_cmake.bat

@@ -0,0 +1,41 @@
+:: Generated by vinca http://github.com/RoboStack/vinca.
+:: DO NOT EDIT!
+setlocal EnableDelayedExpansion
+
+set "PYTHONPATH=%LIBRARY_PREFIX%\lib\site-packages;%SP_DIR%"
+
+:: MSVC is preferred.
+set CC=cl.exe
+set CXX=cl.exe
+
+rd /s /q build
+mkdir build
+pushd build
+
+:: set "CMAKE_GENERATOR=Ninja"
+
+:: try to fix long paths issues by using default generator
+set "CMAKE_GENERATOR=Visual Studio %VS_MAJOR% %VS_YEAR%"
+set "SP_DIR_FORWARDSLASHES=%SP_DIR:\=/%"
+
+set PYTHON="%PREFIX%\python.exe"
+
+cmake ^
+    -G "%CMAKE_GENERATOR%" ^
+    -DCMAKE_INSTALL_PREFIX=%LIBRARY_PREFIX% ^
+    -DCMAKE_BUILD_TYPE=Release ^
+    -DCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=True ^
+    -DPYTHON_EXECUTABLE=%PYTHON% ^
+    -DPython_EXECUTABLE=%PYTHON% ^
+    -DPython3_EXECUTABLE=%PYTHON% ^
+    -DSETUPTOOLS_DEB_LAYOUT=OFF ^
+    -DBUILD_SHARED_LIBS=ON ^
+    -DBUILD_TESTING=OFF ^
+    -DCMAKE_OBJECT_PATH_MAX=255 ^
+    -DPYTHON_INSTALL_DIR=%SP_DIR_FORWARDSLASHES% ^
+    --compile-no-warning-as-error ^
+    %SRC_DIR%\%PKG_NAME%\src\work
+if errorlevel 1 exit 1
+
+cmake --build . --config Release --target install
+if errorlevel 1 exit 1

recipes/ros-humble-unilabos-msgs/build_ament_cmake.sh

@@ -0,0 +1,71 @@
+# Generated by vinca http://github.com/RoboStack/vinca.
+# DO NOT EDIT!
+
+rm -rf build
+mkdir build
+cd build
+
+# necessary for correctly linking SIP files (from python_qt_bindings)
+export LINK=$CXX
+
+if [[ "$CONDA_BUILD_CROSS_COMPILATION" != "1" ]]; then
+  PYTHON_EXECUTABLE=$PREFIX/bin/python
+  PKG_CONFIG_EXECUTABLE=$PREFIX/bin/pkg-config
+  OSX_DEPLOYMENT_TARGET="10.15"
+else
+  PYTHON_EXECUTABLE=$BUILD_PREFIX/bin/python
+  PKG_CONFIG_EXECUTABLE=$BUILD_PREFIX/bin/pkg-config
+  OSX_DEPLOYMENT_TARGET="11.0"
+fi
+
+echo "USING PYTHON_EXECUTABLE=${PYTHON_EXECUTABLE}"
+echo "USING PKG_CONFIG_EXECUTABLE=${PKG_CONFIG_EXECUTABLE}"
+
+export ROS_PYTHON_VERSION=`$PYTHON_EXECUTABLE -c "import sys; print('%i.%i' % (sys.version_info[0:2]))"`
+echo "Using Python ${ROS_PYTHON_VERSION}"
+# Fix up SP_DIR which for some reason might contain a path to a wrong Python version
+FIXED_SP_DIR=$(echo $SP_DIR | sed -E "s/python[0-9]+\.[0-9]+/python$ROS_PYTHON_VERSION/")
+echo "Using site-package dir ${FIXED_SP_DIR}"
+
+# see https://github.com/conda-forge/cross-python-feedstock/issues/24
+if [[ "$CONDA_BUILD_CROSS_COMPILATION" == "1" ]]; then
+  find $PREFIX/lib/cmake -type f -exec sed -i "s~\${_IMPORT_PREFIX}/lib/python${ROS_PYTHON_VERSION}/site-packages~${BUILD_PREFIX}/lib/python${ROS_PYTHON_VERSION}/site-packages~g" {} + || true
+  find $PREFIX/share/rosidl* -type f -exec sed -i "s~$PREFIX/lib/python${ROS_PYTHON_VERSION}/site-packages~${BUILD_PREFIX}/lib/python${ROS_PYTHON_VERSION}/site-packages~g" {} + || true
+  find $PREFIX/share/rosidl* -type f -exec sed -i "s~\${_IMPORT_PREFIX}/lib/python${ROS_PYTHON_VERSION}/site-packages~${BUILD_PREFIX}/lib/python${ROS_PYTHON_VERSION}/site-packages~g" {} + || true
+  find $PREFIX/lib/cmake -type f -exec sed -i "s~message(FATAL_ERROR \"The imported target~message(WARNING \"The imported target~g" {} + || true
+fi
+
+if [[ $target_platform =~ linux.* ]]; then
+    export CFLAGS="${CFLAGS} -D__STDC_FORMAT_MACROS=1"
+    export CXXFLAGS="${CXXFLAGS} -D__STDC_FORMAT_MACROS=1"
+fi;
+
+# Needed for qt-gui-cpp ..
+if [[ $target_platform =~ linux.* ]]; then
+  ln -s $GCC ${BUILD_PREFIX}/bin/gcc
+  ln -s $GXX ${BUILD_PREFIX}/bin/g++
+fi;
+
+cmake \
+    -G "Ninja" \
+    -DCMAKE_INSTALL_PREFIX=$PREFIX \
+    -DCMAKE_PREFIX_PATH=$PREFIX \
+    -DAMENT_PREFIX_PATH=$PREFIX \
+    -DCMAKE_INSTALL_LIBDIR=lib \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DPYTHON_EXECUTABLE=$PYTHON_EXECUTABLE \
+    -DPython_EXECUTABLE=$PYTHON_EXECUTABLE \
+    -DPython3_EXECUTABLE=$PYTHON_EXECUTABLE \
+    -DPython3_FIND_STRATEGY=LOCATION \
+    -DPKG_CONFIG_EXECUTABLE=$PKG_CONFIG_EXECUTABLE \
+    -DPYTHON_INSTALL_DIR=$FIXED_SP_DIR \
+    -DSETUPTOOLS_DEB_LAYOUT=OFF \
+    -DCATKIN_SKIP_TESTING=$SKIP_TESTING \
+    -DCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=True \
+    -DBUILD_SHARED_LIBS=ON  \
+    -DBUILD_TESTING=OFF \
+    -DCMAKE_OSX_DEPLOYMENT_TARGET=$OSX_DEPLOYMENT_TARGET \
+    --compile-no-warning-as-error \
+    $SRC_DIR/$PKG_NAME/src/work
+
+cmake --build . --config Release --target install

recipes/ros-humble-unilabos-msgs/recipe.yaml

@@ -0,0 +1,61 @@
+package:
+  name: ros-humble-unilabos-msgs
+  version: 0.9.7
+source:
+  path: ../../unilabos_msgs
+  folder: ros-humble-unilabos-msgs/src/work
+
+build:
+  script:
+    sel(win): bld_ament_cmake.bat
+    sel(unix): build_ament_cmake.sh
+  number: 5
+about:
+  home: https://www.ros.org/
+  license: BSD-3-Clause
+  summary: |
+    Robot Operating System
+
+extra:
+  recipe-maintainers:
+    - ros-forge
+
+requirements:
+  build:
+    - "{{ compiler('cxx') }}"
+    - "{{ compiler('c') }}"
+    - sel(linux64): sysroot_linux-64 2.17
+    - ninja
+    - setuptools
+    - sel(unix): make
+    - sel(unix): coreutils
+    - sel(osx): tapi
+    - sel(build_platform != target_platform): pkg-config
+    - cmake
+    - cython
+    - sel(win): vs2022_win-64
+    - sel(build_platform != target_platform): python
+    - sel(build_platform != target_platform): cross-python_{{ target_platform }}
+    - sel(build_platform != target_platform): numpy
+  host:
+    - numpy
+    - pip
+    - sel(build_platform == target_platform): pkg-config
+    - robostack-staging::ros-humble-action-msgs
+    - robostack-staging::ros-humble-ament-cmake
+    - robostack-staging::ros-humble-ament-lint-auto
+    - robostack-staging::ros-humble-ament-lint-common
+    - robostack-staging::ros-humble-ros-environment
+    - robostack-staging::ros-humble-ros-workspace
+    - robostack-staging::ros-humble-rosidl-default-generators
+    - robostack-staging::ros-humble-std-msgs
+    - robostack-staging::ros-humble-geometry-msgs
+    - robostack-staging::ros2-distro-mutex=0.5.*
+  run:
+    - robostack-staging::ros-humble-action-msgs
+    - robostack-staging::ros-humble-ros-workspace
+    - robostack-staging::ros-humble-rosidl-default-runtime
+    - robostack-staging::ros-humble-std-msgs
+    - robostack-staging::ros-humble-geometry-msgs
+#    - robostack-staging::ros2-distro-mutex=0.6.*
+    - sel(osx and x86_64): __osx >={{ MACOSX_DEPLOYMENT_TARGET|default('10.14') }}

recipes/unilabos/recipe.yaml

@@ -1,6 +1,6 @@
 package:
   name: unilabos
-  version: "0.10.7"
+  version: "0.10.12"
 
 source:
   path: ../..

scripts/workflow.py

@@ -2,7 +2,6 @@ import json
 import logging
 import traceback
 import uuid
-import xml.etree.ElementTree as ET
 from typing import Any, Dict, List
 
 import networkx as nx
@@ -25,7 +24,15 @@ class SimpleGraph:
 
     def add_edge(self, source, target, **attrs):
         """添加边"""
-        edge = {"source": source, "target": target, **attrs}
+        # edge = {"source": source, "target": target, **attrs}
+        edge = {
+            "source": source, "target": target,
+            "source_node_uuid": source,
+            "target_node_uuid": target,
+            "source_handle_io": "source",
+            "target_handle_io": "target",
+            **attrs
+        }
         self.edges.append(edge)
 
     def to_dict(self):
@@ -42,6 +49,7 @@ class SimpleGraph:
             "multigraph": False,
             "graph": {},
             "nodes": nodes_list,
+            "edges": self.edges,
             "links": self.edges,
         }
 
@@ -58,495 +66,8 @@ def extract_json_from_markdown(text: str) -> str:
     return text
 
 
-def convert_to_type(val: str) -> Any:
-    """将字符串值转换为适当的数据类型"""
-    if val == "True":
-        return True
-    if val == "False":
-        return False
-    if val == "?":
-        return None
-    if val.endswith(" g"):
-        return float(val.split(" ")[0])
-    if val.endswith("mg"):
-        return float(val.split("mg")[0])
-    elif val.endswith("mmol"):
-        return float(val.split("mmol")[0]) / 1000
-    elif val.endswith("mol"):
-        return float(val.split("mol")[0])
-    elif val.endswith("ml"):
-        return float(val.split("ml")[0])
-    elif val.endswith("RPM"):
-        return float(val.split("RPM")[0])
-    elif val.endswith(" °C"):
-        return float(val.split(" ")[0])
-    elif val.endswith(" %"):
-        return float(val.split(" ")[0])
-    return val
 
 
-def refactor_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-    """统一的数据重构函数，根据操作类型自动选择模板"""
-    refactored_data = []
-
-    # 定义操作映射，包含生物实验和有机化学的所有操作
-    OPERATION_MAPPING = {
-        # 生物实验操作
-        "transfer_liquid": "SynBioFactory-liquid_handler.prcxi-transfer_liquid",
-        "transfer": "SynBioFactory-liquid_handler.biomek-transfer",
-        "incubation": "SynBioFactory-liquid_handler.biomek-incubation",
-        "move_labware": "SynBioFactory-liquid_handler.biomek-move_labware",
-        "oscillation": "SynBioFactory-liquid_handler.biomek-oscillation",
-        # 有机化学操作
-        "HeatChillToTemp": "SynBioFactory-workstation-HeatChillProtocol",
-        "StopHeatChill": "SynBioFactory-workstation-HeatChillStopProtocol",
-        "StartHeatChill": "SynBioFactory-workstation-HeatChillStartProtocol",
-        "HeatChill": "SynBioFactory-workstation-HeatChillProtocol",
-        "Dissolve": "SynBioFactory-workstation-DissolveProtocol",
-        "Transfer": "SynBioFactory-workstation-TransferProtocol",
-        "Evaporate": "SynBioFactory-workstation-EvaporateProtocol",
-        "Recrystallize": "SynBioFactory-workstation-RecrystallizeProtocol",
-        "Filter": "SynBioFactory-workstation-FilterProtocol",
-        "Dry": "SynBioFactory-workstation-DryProtocol",
-        "Add": "SynBioFactory-workstation-AddProtocol",
-    }
-
-    UNSUPPORTED_OPERATIONS = ["Purge", "Wait", "Stir", "ResetHandling"]
-
-    for step in data:
-        operation = step.get("action")
-        if not operation or operation in UNSUPPORTED_OPERATIONS:
-            continue
-
-        # 处理重复操作
-        if operation == "Repeat":
-            times = step.get("times", step.get("parameters", {}).get("times", 1))
-            sub_steps = step.get("steps", step.get("parameters", {}).get("steps", []))
-            for i in range(int(times)):
-                sub_data = refactor_data(sub_steps)
-                refactored_data.extend(sub_data)
-            continue
-
-        # 获取模板名称
-        template = OPERATION_MAPPING.get(operation)
-        if not template:
-            # 自动推断模板类型
-            if operation.lower() in ["transfer", "incubation", "move_labware", "oscillation"]:
-                template = f"SynBioFactory-liquid_handler.biomek-{operation}"
-            else:
-                template = f"SynBioFactory-workstation-{operation}Protocol"
-
-        # 创建步骤数据
-        step_data = {
-            "template": template,
-            "description": step.get("description", step.get("purpose", f"{operation} operation")),
-            "lab_node_type": "Device",
-            "parameters": step.get("parameters", step.get("action_args", {})),
-        }
-        refactored_data.append(step_data)
-
-    return refactored_data
-
-
-def build_protocol_graph(
-    labware_info: List[Dict[str, Any]], protocol_steps: List[Dict[str, Any]], workstation_name: str
-) -> SimpleGraph:
-    """统一的协议图构建函数，根据设备类型自动选择构建逻辑"""
-    G = SimpleGraph()
-    resource_last_writer = {}
-    LAB_NAME = "SynBioFactory"
-
-    protocol_steps = refactor_data(protocol_steps)
-
-    # 检查协议步骤中的模板来判断协议类型
-    has_biomek_template = any(
-        ("biomek" in step.get("template", "")) or ("prcxi" in step.get("template", ""))
-        for step in protocol_steps
-    )
-
-    if has_biomek_template:
-        # 生物实验协议图构建
-        for labware_id, labware in labware_info.items():
-            node_id = str(uuid.uuid4())
-
-            labware_attrs = labware.copy()
-            labware_id = labware_attrs.pop("id", labware_attrs.get("name", f"labware_{uuid.uuid4()}"))
-            labware_attrs["description"] = labware_id
-            labware_attrs["lab_node_type"] = (
-                "Reagent" if "Plate" in str(labware_id) else "Labware" if "Rack" in str(labware_id) else "Sample"
-            )
-            labware_attrs["device_id"] = workstation_name
-
-            G.add_node(node_id, template=f"{LAB_NAME}-host_node-create_resource", **labware_attrs)
-            resource_last_writer[labware_id] = f"{node_id}:labware"
-
-        # 处理协议步骤
-        prev_node = None
-        for i, step in enumerate(protocol_steps):
-            node_id = str(uuid.uuid4())
-            G.add_node(node_id, **step)
-
-            # 添加控制流边
-            if prev_node is not None:
-                G.add_edge(prev_node, node_id, source_port="ready", target_port="ready")
-            prev_node = node_id
-
-            # 处理物料流
-            params = step.get("parameters", {})
-            if "sources" in params and params["sources"] in resource_last_writer:
-                source_node, source_port = resource_last_writer[params["sources"]].split(":")
-                G.add_edge(source_node, node_id, source_port=source_port, target_port="labware")
-
-            if "targets" in params:
-                resource_last_writer[params["targets"]] = f"{node_id}:labware"
-
-        # 添加协议结束节点
-        end_id = str(uuid.uuid4())
-        G.add_node(end_id, template=f"{LAB_NAME}-liquid_handler.biomek-run_protocol")
-        if prev_node is not None:
-            G.add_edge(prev_node, end_id, source_port="ready", target_port="ready")
-
-    else:
-        # 有机化学协议图构建
-        WORKSTATION_ID = workstation_name
-
-        # 为所有labware创建资源节点
-        for item_id, item in labware_info.items():
-            # item_id = item.get("id") or item.get("name", f"item_{uuid.uuid4()}")
-            node_id = str(uuid.uuid4())
-
-            # 判断节点类型
-            if item.get("type") == "hardware" or "reactor" in str(item_id).lower():
-                if "reactor" not in str(item_id).lower():
-                    continue
-                lab_node_type = "Sample"
-                description = f"Prepare Reactor: {item_id}"
-                liquid_type = []
-                liquid_volume = []
-            else:
-                lab_node_type = "Reagent"
-                description = f"Add Reagent to Flask: {item_id}"
-                liquid_type = [item_id]
-                liquid_volume = [1e5]
-
-            G.add_node(
-                node_id,
-                template=f"{LAB_NAME}-host_node-create_resource",
-                description=description,
-                lab_node_type=lab_node_type,
-                res_id=item_id,
-                device_id=WORKSTATION_ID,
-                class_name="container",
-                parent=WORKSTATION_ID,
-                bind_locations={"x": 0.0, "y": 0.0, "z": 0.0},
-                liquid_input_slot=[-1],
-                liquid_type=liquid_type,
-                liquid_volume=liquid_volume,
-                slot_on_deck="",
-                role=item.get("role", ""),
-            )
-            resource_last_writer[item_id] = f"{node_id}:labware"
-
-        last_control_node_id = None
-
-        # 处理协议步骤
-        for step in protocol_steps:
-            node_id = str(uuid.uuid4())
-            G.add_node(node_id, **step)
-
-            # 控制流
-            if last_control_node_id is not None:
-                G.add_edge(last_control_node_id, node_id, source_port="ready", target_port="ready")
-            last_control_node_id = node_id
-
-            # 物料流
-            params = step.get("parameters", {})
-            input_resources = {
-                "Vessel": params.get("vessel"),
-                "ToVessel": params.get("to_vessel"),
-                "FromVessel": params.get("from_vessel"),
-                "reagent": params.get("reagent"),
-                "solvent": params.get("solvent"),
-                "compound": params.get("compound"),
-                "sources": params.get("sources"),
-                "targets": params.get("targets"),
-            }
-
-            for target_port, resource_name in input_resources.items():
-                if resource_name and resource_name in resource_last_writer:
-                    source_node, source_port = resource_last_writer[resource_name].split(":")
-                    G.add_edge(source_node, node_id, source_port=source_port, target_port=target_port)
-
-            output_resources = {
-                "VesselOut": params.get("vessel"),
-                "FromVesselOut": params.get("from_vessel"),
-                "ToVesselOut": params.get("to_vessel"),
-                "FiltrateOut": params.get("filtrate_vessel"),
-                "reagent": params.get("reagent"),
-                "solvent": params.get("solvent"),
-                "compound": params.get("compound"),
-                "sources_out": params.get("sources"),
-                "targets_out": params.get("targets"),
-            }
-
-            for source_port, resource_name in output_resources.items():
-                if resource_name:
-                    resource_last_writer[resource_name] = f"{node_id}:{source_port}"
-
-    return G
-
-
-def draw_protocol_graph(protocol_graph: SimpleGraph, output_path: str):
-    """
-    (辅助功能) 使用 networkx 和 matplotlib 绘制协议工作流图，用于可视化。
-    """
-    if not protocol_graph:
-        print("Cannot draw graph: Graph object is empty.")
-        return
-
-    G = nx.DiGraph()
-
-    for node_id, attrs in protocol_graph.nodes.items():
-        label = attrs.get("description", attrs.get("template", node_id[:8]))
-        G.add_node(node_id, label=label, **attrs)
-
-    for edge in protocol_graph.edges:
-        G.add_edge(edge["source"], edge["target"])
-
-    plt.figure(figsize=(20, 15))
-    try:
-        pos = nx.nx_agraph.graphviz_layout(G, prog="dot")
-    except Exception:
-        pos = nx.shell_layout(G)  # Fallback layout
-
-    node_labels = {node: data["label"] for node, data in G.nodes(data=True)}
-    nx.draw(
-        G,
-        pos,
-        with_labels=False,
-        node_size=2500,
-        node_color="skyblue",
-        node_shape="o",
-        edge_color="gray",
-        width=1.5,
-        arrowsize=15,
-    )
-    nx.draw_networkx_labels(G, pos, labels=node_labels, font_size=8, font_weight="bold")
-
-    plt.title("Chemical Protocol Workflow Graph", size=15)
-    plt.savefig(output_path, dpi=300, bbox_inches="tight")
-    plt.close()
-    print(f"  - Visualization saved to '{output_path}'")
-
-
-from networkx.drawing.nx_agraph import to_agraph
-import re
-
-COMPASS = {"n","e","s","w","ne","nw","se","sw","c"}
-
-def _is_compass(port: str) -> bool:
-    return isinstance(port, str) and port.lower() in COMPASS
-
-def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: str = "LR"):
-    """
-    使用 Graphviz 端口语法绘制协议工作流图。
-    - 若边上的 source_port/target_port 是 compass（n/e/s/w/...），直接用 compass。
-    - 否则自动为节点创建 record 形状并定义命名端口 <portname>。
-    最终由 PyGraphviz 渲染并输出到 output_path（后缀决定格式，如 .png/.svg/.pdf）。
-    """
-    if not protocol_graph:
-        print("Cannot draw graph: Graph object is empty.")
-        return
-
-    # 1) 先用 networkx 搭建有向图，保留端口属性
-    G = nx.DiGraph()
-    for node_id, attrs in protocol_graph.nodes.items():
-        label = attrs.get("description", attrs.get("template", node_id[:8]))
-        # 保留一个干净的“中心标签”，用于放在 record 的中间槽
-        G.add_node(node_id, _core_label=str(label), **{k:v for k,v in attrs.items() if k not in ("label",)})
-
-    edges_data = []
-    in_ports_by_node  = {}  # 收集命名输入端口
-    out_ports_by_node = {}  # 收集命名输出端口
-
-    for edge in protocol_graph.edges:
-        u = edge["source"]
-        v = edge["target"]
-        sp = edge.get("source_port")
-        tp = edge.get("target_port")
-
-        # 记录到图里（保留原始端口信息）
-        G.add_edge(u, v, source_port=sp, target_port=tp)
-        edges_data.append((u, v, sp, tp))
-
-        # 如果不是 compass，就按“命名端口”先归类，等会儿给节点造 record
-        if sp and not _is_compass(sp):
-            out_ports_by_node.setdefault(u, set()).add(str(sp))
-        if tp and not _is_compass(tp):
-            in_ports_by_node.setdefault(v, set()).add(str(tp))
-
-    # 2) 转为 AGraph，使用 Graphviz 渲染
-    A = to_agraph(G)
-    A.graph_attr.update(rankdir=rankdir, splines="true", concentrate="false", fontsize="10")
-    A.node_attr.update(shape="box", style="rounded,filled", fillcolor="lightyellow", color="#999999", fontname="Helvetica")
-    A.edge_attr.update(arrowsize="0.8", color="#666666")
-
-    # 3) 为需要命名端口的节点设置 record 形状与 label
-    #    左列 = 输入端口；中间 = 核心标签；右列 = 输出端口
-    for n in A.nodes():
-        node = A.get_node(n)
-        core = G.nodes[n].get("_core_label", n)
-
-        in_ports  = sorted(in_ports_by_node.get(n, []))
-        out_ports = sorted(out_ports_by_node.get(n, []))
-
-        # 如果该节点涉及命名端口，则用 record；否则保留原 box
-        if in_ports or out_ports:
-            def port_fields(ports):
-                if not ports:
-                    return " "  # 必须留一个空槽占位
-                # 每个端口一个小格子，<p> name
-                return "|".join(f"<{re.sub(r'[^A-Za-z0-9_:.|-]', '_', p)}> {p}" for p in ports)
-
-            left  = port_fields(in_ports)
-            right = port_fields(out_ports)
-
-            # 三栏：左(入) | 中(节点名) | 右(出)
-            record_label = f"{{ {left} | {core} | {right} }}"
-            node.attr.update(shape="record", label=record_label)
-        else:
-            # 没有命名端口：普通盒子，显示核心标签
-            node.attr.update(label=str(core))
-
-    # 4) 给边设置 headport / tailport
-    #    - 若端口为 compass：直接用 compass（e.g., headport="e"）
-    #    - 若端口为命名端口：使用在 record 中定义的 <port> 名（同名即可）
-    for (u, v, sp, tp) in edges_data:
-        e = A.get_edge(u, v)
-
-        # Graphviz 属性：tail 是源，head 是目标
-        if sp:
-            if _is_compass(sp):
-                e.attr["tailport"] = sp.lower()
-            else:
-                # 与 record label 中 <port> 名一致；特殊字符已在 label 中做了清洗
-                e.attr["tailport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(sp))
-
-        if tp:
-            if _is_compass(tp):
-                e.attr["headport"] = tp.lower()
-            else:
-                e.attr["headport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(tp))
-
-        # 可选：若想让边更贴边缘，可设置 constraint/spline 等
-        # e.attr["arrowhead"] = "vee"
-
-    # 5) 输出
-    A.draw(output_path, prog="dot")
-    print(f"  - Port-aware workflow rendered to '{output_path}'")
-
-
-def flatten_xdl_procedure(procedure_elem: ET.Element) -> List[ET.Element]:
-    """展平嵌套的XDL程序结构"""
-    flattened_operations = []
-    TEMP_UNSUPPORTED_PROTOCOL = ["Purge", "Wait", "Stir", "ResetHandling"]
-
-    def extract_operations(element: ET.Element):
-        if element.tag not in ["Prep", "Reaction", "Workup", "Purification", "Procedure"]:
-            if element.tag not in TEMP_UNSUPPORTED_PROTOCOL:
-                flattened_operations.append(element)
-
-        for child in element:
-            extract_operations(child)
-
-    for child in procedure_elem:
-        extract_operations(child)
-
-    return flattened_operations
-
-
-def parse_xdl_content(xdl_content: str) -> tuple:
-    """解析XDL内容"""
-    try:
-        xdl_content_cleaned = "".join(c for c in xdl_content if c.isprintable())
-        root = ET.fromstring(xdl_content_cleaned)
-
-        synthesis_elem = root.find("Synthesis")
-        if synthesis_elem is None:
-            return None, None, None
-
-        # 解析硬件组件
-        hardware_elem = synthesis_elem.find("Hardware")
-        hardware = []
-        if hardware_elem is not None:
-            hardware = [{"id": c.get("id"), "type": c.get("type")} for c in hardware_elem.findall("Component")]
-
-        # 解析试剂
-        reagents_elem = synthesis_elem.find("Reagents")
-        reagents = []
-        if reagents_elem is not None:
-            reagents = [{"name": r.get("name"), "role": r.get("role", "")} for r in reagents_elem.findall("Reagent")]
-
-        # 解析程序
-        procedure_elem = synthesis_elem.find("Procedure")
-        if procedure_elem is None:
-            return None, None, None
-
-        flattened_operations = flatten_xdl_procedure(procedure_elem)
-        return hardware, reagents, flattened_operations
-
-    except ET.ParseError as e:
-        raise ValueError(f"Invalid XDL format: {e}")
-
-
-def convert_xdl_to_dict(xdl_content: str) -> Dict[str, Any]:
-    """
-    将XDL XML格式转换为标准的字典格式
-
-    Args:
-        xdl_content: XDL XML内容
-
-    Returns:
-        转换结果，包含步骤和器材信息
-    """
-    try:
-        hardware, reagents, flattened_operations = parse_xdl_content(xdl_content)
-        if hardware is None:
-            return {"error": "Failed to parse XDL content", "success": False}
-
-        # 将XDL元素转换为字典格式
-        steps_data = []
-        for elem in flattened_operations:
-            # 转换参数类型
-            parameters = {}
-            for key, val in elem.attrib.items():
-                converted_val = convert_to_type(val)
-                if converted_val is not None:
-                    parameters[key] = converted_val
-
-            step_dict = {
-                "operation": elem.tag,
-                "parameters": parameters,
-                "description": elem.get("purpose", f"Operation: {elem.tag}"),
-            }
-            steps_data.append(step_dict)
-
-        # 合并硬件和试剂为统一的labware_info格式
-        labware_data = []
-        labware_data.extend({"id": hw["id"], "type": "hardware", **hw} for hw in hardware)
-        labware_data.extend({"name": reagent["name"], "type": "reagent", **reagent} for reagent in reagents)
-
-        return {
-            "success": True,
-            "steps": steps_data,
-            "labware": labware_data,
-            "message": f"Successfully converted XDL to dict format. Found {len(steps_data)} steps and {len(labware_data)} labware items.",
-        }
-
-    except Exception as e:
-        error_msg = f"XDL conversion failed: {str(e)}"
-        logger.error(error_msg)
-        return {"error": error_msg, "success": False}
 
 
 def create_workflow(

setup.py

@@ -4,7 +4,7 @@ package_name = 'unilabos'
 
 setup(
     name=package_name,
-    version='0.10.7',
+    version='0.10.12',
     packages=find_packages(),
     include_package_data=True,
     install_requires=['setuptools'],

test/experiments/reaction_station_bioyond.json

@@ -1,72 +0,0 @@
-{
-    "nodes": [
-        {
-            "id": "reaction_station_bioyond",
-            "name": "reaction_station_bioyond",
-            "parent": null,
-            "children": [
-                "Bioyond_Deck"
-            ],
-            "type": "device",
-            "class": "reaction_station.bioyond",
-            "config": {
-                "config": {
-                    "api_key": "DE9BDDA0",
-                    "api_host": "http://192.168.1.200:44402",
-                    "workflow_mappings": {
-                        "reactor_taken_out": "3a16081e-4788-ca37-eff4-ceed8d7019d1",
-                        "reactor_taken_in": "3a160df6-76b3-0957-9eb0-cb496d5721c6",
-                        "Solid_feeding_vials": "3a160877-87e7-7699-7bc6-ec72b05eb5e6",
-                        "Liquid_feeding_vials(non-titration)": "3a167d99-6158-c6f0-15b5-eb030f7d8e47",
-                        "Liquid_feeding_solvents": "3a160824-0665-01ed-285a-51ef817a9046",
-                        "Liquid_feeding(titration)": "3a16082a-96ac-0449-446a-4ed39f3365b6",
-                        "liquid_feeding_beaker": "3a16087e-124f-8ddb-8ec1-c2dff09ca784",
-                        "Drip_back": "3a162cf9-6aac-565a-ddd7-682ba1796a4a"
-                    },
-                    "material_type_mappings": {
-                        "烧杯": ["BIOYOND_PolymerStation_1FlaskCarrier", "3a14196b-24f2-ca49-9081-0cab8021bf1a"],
-                        "试剂瓶": ["BIOYOND_PolymerStation_1BottleCarrier", ""],
-                        "样品板": ["BIOYOND_PolymerStation_6StockCarrier", "3a14196e-b7a0-a5da-1931-35f3000281e9"],
-                        "分装板": ["BIOYOND_PolymerStation_6VialCarrier", "3a14196e-5dfe-6e21-0c79-fe2036d052c4"],
-                        "样品瓶": ["BIOYOND_PolymerStation_Solid_Stock", "3a14196a-cf7d-8aea-48d8-b9662c7dba94"],
-                        "90%分装小瓶": ["BIOYOND_PolymerStation_Solid_Vial", "3a14196c-cdcf-088d-dc7d-5cf38f0ad9ea"],
-                        "10%分装小瓶": ["BIOYOND_PolymerStation_Liquid_Vial", "3a14196c-76be-2279-4e22-7310d69aed68"]
-                    }
-                },
-                "deck": {
-                    "data": {
-                        "_resource_child_name": "Bioyond_Deck",
-                        "_resource_type": "unilabos.resources.bioyond.decks:BIOYOND_PolymerReactionStation_Deck"
-                    }
-                },
-                "protocol_type": []
-            },
-            "data": {}
-        },
-        {
-            "id": "Bioyond_Deck",
-            "name": "Bioyond_Deck",
-            "children": [
-            ],
-            "parent": "reaction_station_bioyond",
-            "type": "deck",
-            "class": "BIOYOND_PolymerReactionStation_Deck",
-            "position": {
-                "x": 0,
-                "y": 0,
-                "z": 0
-            },
-            "config": {
-                "type": "BIOYOND_PolymerReactionStation_Deck",
-                "setup": true,
-                "rotation": {
-                    "x": 0,
-                    "y": 0,
-                    "z": 0,
-                    "type": "Rotation"
-                }
-            },
-            "data": {}
-        }
-    ]
-}

test/workflow/merge_workflow.py

@@ -1,4 +1,3 @@
-import json
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -9,86 +8,28 @@ if str(ROOT_DIR) not in sys.path:
 
 import pytest
 
-from scripts.workflow import build_protocol_graph, draw_protocol_graph, draw_protocol_graph_with_ports
+from unilabos.workflow.convert_from_json import (
+    convert_from_json,
+    normalize_steps as _normalize_steps,
+    normalize_labware as _normalize_labware,
+)
+from unilabos.workflow.common import draw_protocol_graph_with_ports
 
 
-ROOT_DIR = Path(__file__).resolve().parents[2]
-if str(ROOT_DIR) not in sys.path:
-    sys.path.insert(0, str(ROOT_DIR))
-
-
-def _normalize_steps(data):
-    normalized = []
-    for step in data:
-        action = step.get("action") or step.get("operation")
-        if not action:
-            continue
-        raw_params = step.get("parameters") or step.get("action_args") or {}
-        params = dict(raw_params)
-
-        if "source" in raw_params and "sources" not in raw_params:
-            params["sources"] = raw_params["source"]
-        if "target" in raw_params and "targets" not in raw_params:
-            params["targets"] = raw_params["target"]
-
-        description = step.get("description") or step.get("purpose")
-        step_dict = {"action": action, "parameters": params}
-        if description:
-            step_dict["description"] = description
-        normalized.append(step_dict)
-    return normalized
-
-
-def _normalize_labware(data):
-    labware = {}
-    for item in data:
-        reagent_name = item.get("reagent_name")
-        key = reagent_name or item.get("material_name") or item.get("name")
-        if not key:
-            continue
-        key = str(key)
-        idx = 1
-        original_key = key
-        while key in labware:
-            idx += 1
-            key = f"{original_key}_{idx}"
-
-        labware[key] = {
-            "slot": item.get("positions") or item.get("slot"),
-            "labware": item.get("material_name") or item.get("labware"),
-            "well": item.get("well", []),
-            "type": item.get("type", "reagent"),
-            "role": item.get("role", ""),
-            "name": key,
-        }
-    return labware
-
-
-@pytest.mark.parametrize("protocol_name", [
-    "example_bio",
-    # "bioyond_materials_liquidhandling_1",
-    "example_prcxi",
-])
+@pytest.mark.parametrize(
+    "protocol_name",
+    [
+        "example_bio",
+        # "bioyond_materials_liquidhandling_1",
+        "example_prcxi",
+    ],
+)
 def test_build_protocol_graph(protocol_name):
     data_path = Path(__file__).with_name(f"{protocol_name}.json")
-    with data_path.open("r", encoding="utf-8") as fp:
-        d = json.load(fp)
 
-    if "workflow" in d and "reagent" in d:
-        protocol_steps = d["workflow"]
-        labware_info = d["reagent"]
-    elif "steps_info" in d and "labware_info" in d:
-        protocol_steps = _normalize_steps(d["steps_info"])
-        labware_info = _normalize_labware(d["labware_info"])
-    else:
-        raise ValueError("Unsupported protocol format")
+    graph = convert_from_json(data_path, workstation_name="PRCXi")
 
-    graph = build_protocol_graph(
-        labware_info=labware_info,
-        protocol_steps=protocol_steps,
-        workstation_name="PRCXi",
-    )
     timestamp = datetime.now().strftime("%Y%m%d_%H%M")
     output_path = data_path.with_name(f"{protocol_name}_graph_{timestamp}.png")
     draw_protocol_graph_with_ports(graph, str(output_path))
-    print(graph)
+    print(graph)

unilabos/__init__.py

@@ -1 +1 @@
-__version__ = "0.10.7"
+__version__ = "0.10.12"

unilabos/app/backend.py

@@ -13,7 +13,7 @@ def start_backend(
     graph=None,
     controllers_config: dict = {},
     bridges=[],
-    without_host: bool = False,
+    is_slave: bool = False,
     visual: str = "None",
     resources_mesh_config: dict = {},
     **kwargs,
@@ -32,7 +32,7 @@ def start_backend(
         raise ValueError(f"Unsupported backend: {backend}")
 
     backend_thread = threading.Thread(
-        target=main if not without_host else slave,
+        target=main if not is_slave else slave,
         args=(
             devices_config,
             resources_config,

unilabos/app/communication.py

@@ -141,7 +141,7 @@ class CommunicationClientFactory:
         """
         if cls._client_cache is None:
             cls._client_cache = cls.create_client(protocol)
-            logger.info(f"[CommunicationFactory] Created {type(cls._client_cache).__name__} client")
+            logger.trace(f"[CommunicationFactory] Created {type(cls._client_cache).__name__} client")
 
         return cls._client_cache
 

unilabos/app/main.py

@@ -20,6 +20,7 @@ if unilabos_dir not in sys.path:
 from unilabos.utils.banner_print import print_status, print_unilab_banner
 from unilabos.config.config import load_config, BasicConfig, HTTPConfig
 
+
 def load_config_from_file(config_path):
     if config_path is None:
         config_path = os.environ.get("UNILABOS_BASICCONFIG_CONFIG_PATH", None)
@@ -41,7 +42,7 @@ def convert_argv_dashes_to_underscores(args: argparse.ArgumentParser):
     for i, arg in enumerate(sys.argv):
         for option_string in option_strings:
             if arg.startswith(option_string):
-                new_arg = arg[:2] + arg[2:len(option_string)].replace("-", "_") + arg[len(option_string):]
+                new_arg = arg[:2] + arg[2 : len(option_string)].replace("-", "_") + arg[len(option_string) :]
                 sys.argv[i] = new_arg
                 break
 
@@ -49,6 +50,8 @@ def convert_argv_dashes_to_underscores(args: argparse.ArgumentParser):
 def parse_args():
     """解析命令行参数"""
     parser = argparse.ArgumentParser(description="Start Uni-Lab Edge server.")
+    subparsers = parser.add_subparsers(title="Valid subcommands", dest="command")
+
     parser.add_argument("-g", "--graph", help="Physical setup graph file path.")
     parser.add_argument("-c", "--controllers", default=None, help="Controllers config file path.")
     parser.add_argument(
@@ -105,7 +108,7 @@ def parse_args():
     parser.add_argument(
         "--port",
         type=int,
-        default=8002,
+        default=None,
         help="Port for web service information page",
     )
     parser.add_argument(
@@ -153,21 +156,54 @@ def parse_args():
         default=False,
         help="Complete registry information",
     )
+    # workflow upload subcommand
+    workflow_parser = subparsers.add_parser(
+        "workflow_upload",
+        aliases=["wf"],
+        help="Upload workflow from xdl/json/python files",
+    )
+    workflow_parser.add_argument(
+        "-f",
+        "--workflow_file",
+        type=str,
+        required=True,
+        help="Path to the workflow file (JSON format)",
+    )
+    workflow_parser.add_argument(
+        "-n",
+        "--workflow_name",
+        type=str,
+        default=None,
+        help="Workflow name, if not provided will use the name from file or filename",
+    )
+    workflow_parser.add_argument(
+        "--tags",
+        type=str,
+        nargs="*",
+        default=[],
+        help="Tags for the workflow (space-separated)",
+    )
+    workflow_parser.add_argument(
+        "--published",
+        action="store_true",
+        default=False,
+        help="Whether to publish the workflow (default: False)",
+    )
     return parser
 
 
 def main():
     """主函数"""
     # 解析命令行参数
-    args = parse_args()
-    convert_argv_dashes_to_underscores(args)
-    args_dict = vars(args.parse_args())
+    parser = parse_args()
+    convert_argv_dashes_to_underscores(parser)
+    args = parser.parse_args()
+    args_dict = vars(args)
 
     # 环境检查 - 检查并自动安装必需的包 (可选)
     if not args_dict.get("skip_env_check", False):
         from unilabos.utils.environment_check import check_environment
 
-        print_status("正在进行环境依赖检查...", "info")
         if not check_environment(auto_install=True):
             print_status("环境检查失败，程序退出", "error")
             os._exit(1)
@@ -218,19 +254,20 @@ def main():
 
     if hasattr(BasicConfig, "log_level"):
         logger.info(f"Log level set to '{BasicConfig.log_level}' from config file.")
-        configure_logger(loglevel=BasicConfig.log_level)
+    configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)
 
-    if args_dict["addr"] == "test":
-        print_status("使用测试环境地址", "info")
-        HTTPConfig.remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
-    elif args_dict["addr"] == "uat":
-        print_status("使用uat环境地址", "info")
-        HTTPConfig.remote_addr = "https://uni-lab.uat.bohrium.com/api/v1"
-    elif args_dict["addr"] == "local":
-        print_status("使用本地环境地址", "info")
-        HTTPConfig.remote_addr = "http://127.0.0.1:48197/api/v1"
-    else:
-        HTTPConfig.remote_addr = args_dict.get("addr", "")
+    if args.addr != parser.get_default("addr"):
+        if args.addr == "test":
+            print_status("使用测试环境地址", "info")
+            HTTPConfig.remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
+        elif args.addr == "uat":
+            print_status("使用uat环境地址", "info")
+            HTTPConfig.remote_addr = "https://uni-lab.uat.bohrium.com/api/v1"
+        elif args.addr == "local":
+            print_status("使用本地环境地址", "info")
+            HTTPConfig.remote_addr = "http://127.0.0.1:48197/api/v1"
+        else:
+            HTTPConfig.remote_addr = args.addr
 
     # 设置BasicConfig参数
     if args_dict.get("ak", ""):
@@ -239,9 +276,12 @@ def main():
     if args_dict.get("sk", ""):
         BasicConfig.sk = args_dict.get("sk", "")
         print_status("传入了sk参数，优先采用传入参数！", "info")
+    BasicConfig.working_dir = working_dir
+
+    workflow_upload = args_dict.get("command") in ("workflow_upload", "wf")
 
     # 使用远程资源启动
-    if args_dict["use_remote_resource"]:
+    if not workflow_upload and args_dict["use_remote_resource"]:
         print_status("使用远程资源启动", "info")
         from unilabos.app.web import http_client
 
@@ -252,7 +292,8 @@ def main():
         else:
             print_status("远程资源不存在，本地将进行首次上报！", "info")
 
-    BasicConfig.working_dir = working_dir
+    BasicConfig.port = args_dict["port"] if args_dict["port"] else BasicConfig.port
+    BasicConfig.disable_browser = args_dict["disable_browser"] or BasicConfig.disable_browser
     BasicConfig.is_host_mode = not args_dict.get("is_slave", False)
     BasicConfig.slave_no_host = args_dict.get("slave_no_host", False)
     BasicConfig.upload_registry = args_dict.get("upload_registry", False)
@@ -281,9 +322,31 @@ def main():
 
     # 注册表
     lab_registry = build_registry(
-        args_dict["registry_path"], args_dict.get("complete_registry", False), args_dict["upload_registry"]
+        args_dict["registry_path"], args_dict.get("complete_registry", False), BasicConfig.upload_registry
     )
 
+    if BasicConfig.upload_registry:
+        # 设备注册到服务端 - 需要 ak 和 sk
+        if BasicConfig.ak and BasicConfig.sk:
+            print_status("开始注册设备到服务端...", "info")
+            try:
+                register_devices_and_resources(lab_registry)
+                print_status("设备注册完成", "info")
+            except Exception as e:
+                print_status(f"设备注册失败: {e}", "error")
+        else:
+            print_status("未提供 ak 和 sk，跳过设备注册", "info")
+    else:
+        print_status("本次启动注册表不报送云端，如果您需要联网调试，请在启动命令增加--upload_registry", "warning")
+
+    # 处理 workflow_upload 子命令
+    if workflow_upload:
+        from unilabos.workflow.wf_utils import handle_workflow_upload_command
+
+        handle_workflow_upload_command(args_dict)
+        print_status("工作流上传完成，程序退出", "info")
+        os._exit(0)
+
     if not BasicConfig.ak or not BasicConfig.sk:
         print_status("后续运行必须拥有一个实验室，请前往 https://uni-lab.bohrium.com 注册实验室！", "warning")
         os._exit(1)
@@ -291,7 +354,9 @@ def main():
     resource_tree_set: ResourceTreeSet
     resource_links: List[Dict[str, Any]]
     request_startup_json = http_client.request_startup_json()
-    if args_dict["graph"] is None:
+
+    file_path = args_dict.get("graph", BasicConfig.startup_json_path)
+    if file_path is None:
         if not request_startup_json:
             print_status(
                 "未指定设备加载文件路径，尝试从HTTP获取失败，请检查网络或者使用-g参数指定设备加载文件路径", "error"
@@ -301,7 +366,11 @@ def main():
             print_status("联网获取设备加载文件成功", "info")
         graph, resource_tree_set, resource_links = read_node_link_json(request_startup_json)
     else:
-        file_path = args_dict["graph"]
+        if not os.path.isfile(file_path):
+            temp_file_path = os.path.abspath(str(os.path.join(__file__, "..", "..", file_path)))
+            if os.path.isfile(temp_file_path):
+                print_status(f"使用相对路径{temp_file_path}", "info")
+                file_path = temp_file_path
         if file_path.endswith(".json"):
             graph, resource_tree_set, resource_links = read_node_link_json(file_path)
         else:
@@ -354,20 +423,6 @@ def main():
     args_dict["devices_config"] = resource_tree_set
     args_dict["graph"] = graph_res.physical_setup_graph
 
-    if BasicConfig.upload_registry:
-        # 设备注册到服务端 - 需要 ak 和 sk
-        if BasicConfig.ak and BasicConfig.sk:
-            print_status("开始注册设备到服务端...", "info")
-            try:
-                register_devices_and_resources(lab_registry)
-                print_status("设备注册完成", "info")
-            except Exception as e:
-                print_status(f"设备注册失败: {e}", "error")
-        else:
-            print_status("未提供 ak 和 sk，跳过设备注册", "info")
-    else:
-        print_status("本次启动注册表不报送云端，如果您需要联网调试，请在启动命令增加--upload_registry", "warning")
-
     if args_dict["controllers"] is not None:
         args_dict["controllers_config"] = yaml.safe_load(open(args_dict["controllers"], encoding="utf-8"))
     else:
@@ -375,22 +430,24 @@ def main():
 
     args_dict["bridges"] = []
 
-    # 获取通信客户端（仅支持WebSocket）
-    comm_client = get_communication_client()
-
-    if "websocket" in args_dict["app_bridges"]:
-        args_dict["bridges"].append(comm_client)
     if "fastapi" in args_dict["app_bridges"]:
         args_dict["bridges"].append(http_client)
-    if "websocket" in args_dict["app_bridges"]:
+    # 获取通信客户端（仅支持WebSocket）
+    if BasicConfig.is_host_mode:
+        comm_client = get_communication_client()
+        if "websocket" in args_dict["app_bridges"]:
+            args_dict["bridges"].append(comm_client)
 
-        def _exit(signum, frame):
-            comm_client.stop()
-            sys.exit(0)
+            def _exit(signum, frame):
+                comm_client.stop()
+                sys.exit(0)
+
+            signal.signal(signal.SIGINT, _exit)
+            signal.signal(signal.SIGTERM, _exit)
+            comm_client.start()
+    else:
+        print_status("SlaveMode跳过Websocket连接")
 
-        signal.signal(signal.SIGINT, _exit)
-        signal.signal(signal.SIGTERM, _exit)
-        comm_client.start()
     args_dict["resources_mesh_config"] = {}
     args_dict["resources_edge_config"] = resource_edge_info
     # web visiualize 2D
@@ -412,26 +469,39 @@ def main():
             server_thread = threading.Thread(
                 target=start_server,
                 kwargs=dict(
-                    open_browser=not args_dict["disable_browser"],
-                    port=args_dict["port"],
+                    open_browser=not BasicConfig.disable_browser,
+                    port=BasicConfig.port,
                 ),
             )
             server_thread.start()
             asyncio.set_event_loop(asyncio.new_event_loop())
-            resource_visualization.start()
+            try:
+                resource_visualization.start()
+            except OSError as e:
+                if "AMENT_PREFIX_PATH" in str(e):
+                    print_status(f"ROS 2环境未正确设置，跳过3D可视化启动。错误详情: {e}", "warning")
+                    print_status(
+                        "建议解决方案：\n"
+                        "1. 激活Conda环境: conda activate unilab\n"
+                        "2. 或使用 --backend simple 参数\n"
+                        "3. 或使用 --visual disable 参数禁用可视化",
+                        "info",
+                    )
+                else:
+                    raise
             while True:
                 time.sleep(1)
         else:
             start_backend(**args_dict)
             start_server(
                 open_browser=not args_dict["disable_browser"],
-                port=args_dict["port"],
+                port=BasicConfig.port,
             )
     else:
         start_backend(**args_dict)
         start_server(
             open_browser=not args_dict["disable_browser"],
-            port=args_dict["port"],
+            port=BasicConfig.port,
         )
 
 

unilabos/app/model.py

@@ -51,21 +51,25 @@ class Resp(BaseModel):
 class JobAddReq(BaseModel):
     device_id: str = Field(examples=["Gripper"], description="device id")
     action: str = Field(examples=["_execute_driver_command_async"], description="action name", default="")
-    action_type: str = Field(examples=["unilabos_msgs.action._str_single_input.StrSingleInput"], description="action name", default="")
-    action_args: dict = Field(examples=[{'string': 'string'}], description="action name", default="")
-    task_id: str = Field(examples=["task_id"], description="task uuid")
-    job_id: str = Field(examples=["job_id"], description="goal uuid")
-    node_id: str = Field(examples=["node_id"], description="node uuid")
-    server_info: dict = Field(examples=[{"send_timestamp": 1717000000.0}], description="server info")
+    action_type: str = Field(
+        examples=["unilabos_msgs.action._str_single_input.StrSingleInput"], description="action type", default=""
+    )
+    action_args: dict = Field(examples=[{"string": "string"}], description="action arguments", default_factory=dict)
+    task_id: str = Field(examples=["task_id"], description="task uuid (auto-generated if empty)", default="")
+    job_id: str = Field(examples=["job_id"], description="goal uuid (auto-generated if empty)", default="")
+    node_id: str = Field(examples=["node_id"], description="node uuid", default="")
+    server_info: dict = Field(
+        examples=[{"send_timestamp": 1717000000.0}],
+        description="server info (auto-generated if empty)",
+        default_factory=dict,
+    )
 
-    data: dict = Field(examples=[{"position": 30, "torque": 5, "action": "push_to"}], default={})
+    data: dict = Field(examples=[{"position": 30, "torque": 5, "action": "push_to"}], default_factory=dict)
 
 
 class JobStepFinishReq(BaseModel):
     token: str = Field(examples=["030944"], description="token")
-    request_time: str = Field(
-        examples=["2024-12-12 12:12:12.xxx"], description="requestTime"
-    )
+    request_time: str = Field(examples=["2024-12-12 12:12:12.xxx"], description="requestTime")
     data: dict = Field(
         examples=[
             {
@@ -83,9 +87,7 @@ class JobStepFinishReq(BaseModel):
 
 class JobPreintakeFinishReq(BaseModel):
     token: str = Field(examples=["030944"], description="token")
-    request_time: str = Field(
-        examples=["2024-12-12 12:12:12.xxx"], description="requestTime"
-    )
+    request_time: str = Field(examples=["2024-12-12 12:12:12.xxx"], description="requestTime")
     data: dict = Field(
         examples=[
             {
@@ -102,9 +104,7 @@ class JobPreintakeFinishReq(BaseModel):
 
 class JobFinishReq(BaseModel):
     token: str = Field(examples=["030944"], description="token")
-    request_time: str = Field(
-        examples=["2024-12-12 12:12:12.xxx"], description="requestTime"
-    )
+    request_time: str = Field(examples=["2024-12-12 12:12:12.xxx"], description="requestTime")
     data: dict = Field(
         examples=[
             {
@@ -133,6 +133,10 @@ class JobData(BaseModel):
         default=0,
         description="0:UNKNOWN, 1:ACCEPTED, 2:EXECUTING, 3:CANCELING, 4:SUCCEEDED, 5:CANCELED, 6:ABORTED",
     )
+    result: dict = Field(
+        default_factory=dict,
+        description="Job result data (available when status is SUCCEEDED/CANCELED/ABORTED)",
+    )
 
 
 class JobStatusResp(Resp):

unilabos/app/oss_upload.py

@@ -1,161 +1,158 @@
 import argparse
 import os
 import time
-from typing import Dict, Optional, Tuple
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Optional, Tuple, Union
 
 import requests
 
-from unilabos.config.config import OSSUploadConfig
+from unilabos.app.web.client import http_client, HTTPClient
+from unilabos.utils import logger
 
 
-def _init_upload(file_path: str, oss_path: str, filename: Optional[str] = None,
-                process_key: str = "file-upload", device_id: str = "default",
-                expires_hours: int = 1) -> Tuple[bool, Dict]:
+def _get_oss_token(
+    filename: str,
+    driver_name: str = "default",
+    exp_type: str = "default",
+    client: Optional[HTTPClient] = None,
+) -> Tuple[bool, Dict]:
     """
-    初始化上传过程
+    获取OSS上传Token
 
     Args:
-        file_path: 本地文件路径
-        oss_path: OSS目标路径
-        filename: 文件名，如果为None则使用file_path的文件名
-        process_key: 处理键
-        device_id: 设备ID
-        expires_hours: 链接过期小时数
+        filename: 文件名
+        driver_name: 驱动名称
+        exp_type: 实验类型
+        client: HTTPClient实例，如果不提供则使用默认的http_client
 
     Returns:
-        (成功标志, 响应数据)
+        (成功标志, Token数据字典包含token/path/host/expires)
     """
-    if filename is None:
-        filename = os.path.basename(file_path)
+    # 使用提供的client或默认的http_client
+    if client is None:
+        client = http_client
 
-    # 构造初始化请求
-    url = f"{OSSUploadConfig.api_host}{OSSUploadConfig.init_endpoint}"
-    headers = {
-        "Authorization": OSSUploadConfig.authorization,
-        "Content-Type": "application/json"
-    }
+    # 构造scene参数: driver_name-exp_type
+    sub_path = f"{driver_name}-{exp_type}"
 
-    payload = {
-        "device_id": device_id,
-        "process_key": process_key,
-        "filename": filename,
-        "path": oss_path,
-        "expires_hours": expires_hours
-    }
+    # 构造请求URL，使用client的remote_addr（已包含/api/v1/）
+    url = f"{client.remote_addr}/applications/token"
+    params = {"sub_path": sub_path, "filename": filename, "scene": "job"}
 
     try:
-        response = requests.post(url, headers=headers, json=payload)
-        if response.status_code == 201:
-            result = response.json()
-            if result.get("code") == "10000":
-                return True, result.get("data", {})
+        logger.info(f"[OSS] 请求预签名URL: sub_path={sub_path}, filename={filename}")
+        response = requests.get(url, params=params, headers={"Authorization": f"Lab {client.auth}"}, timeout=10)
 
-        print(f"初始化上传失败: {response.status_code}, {response.text}")
+        if response.status_code == 200:
+            result = response.json()
+            if result.get("code") == 0:
+                data = result.get("data", {})
+
+                # 转换expires时间戳为可读格式
+                expires_timestamp = data.get("expires", 0)
+                expires_datetime = datetime.fromtimestamp(expires_timestamp)
+                expires_str = expires_datetime.strftime("%Y-%m-%d %H:%M:%S")
+
+                logger.info(f"[OSS] 获取预签名URL成功")
+                logger.info(f"[OSS]   - URL: {data.get('url', 'N/A')}")
+                logger.info(f"[OSS]   - Expires: {expires_str} (timestamp: {expires_timestamp})")
+
+                return True, data
+
+        logger.error(f"[OSS] 获取预签名URL失败: {response.status_code}, {response.text}")
         return False, {}
     except Exception as e:
-        print(f"初始化上传异常: {str(e)}")
+        logger.error(f"[OSS] 获取预签名URL异常: {str(e)}")
         return False, {}
 
 
 def _put_upload(file_path: str, upload_url: str) -> bool:
     """
-    执行PUT上传
+    使用预签名URL上传文件到OSS
 
     Args:
         file_path: 本地文件路径
-        upload_url: 上传URL
+        upload_url: 完整的预签名上传URL
 
     Returns:
         是否成功
     """
     try:
+        logger.info(f"[OSS] 开始上传文件: {file_path}")
+
         with open(file_path, "rb") as f:
-            response = requests.put(upload_url, data=f)
+            # 使用预签名URL上传，不需要额外的认证header
+            response = requests.put(upload_url, data=f, timeout=300)
+
             if response.status_code == 200:
+                logger.info(f"[OSS] 文件上传成功")
                 return True
 
-        print(f"PUT上传失败: {response.status_code}, {response.text}")
+        logger.error(f"[OSS] 上传失败: {response.status_code}")
+        logger.error(f"[OSS] 响应内容: {response.text[:500] if response.text else '无响应内容'}")
         return False
     except Exception as e:
-        print(f"PUT上传异常: {str(e)}")
+        logger.error(f"[OSS] 上传异常: {str(e)}")
         return False
 
 
-def _complete_upload(uuid: str) -> bool:
-    """
-    完成上传过程
-
-    Args:
-        uuid: 上传的UUID
-
-    Returns:
-        是否成功
-    """
-    url = f"{OSSUploadConfig.api_host}{OSSUploadConfig.complete_endpoint}"
-    headers = {
-        "Authorization": OSSUploadConfig.authorization,
-        "Content-Type": "application/json"
-    }
-
-    payload = {
-        "uuid": uuid
-    }
-
-    try:
-        response = requests.post(url, headers=headers, json=payload)
-        if response.status_code == 200:
-            result = response.json()
-            if result.get("code") == "10000":
-                return True
-
-        print(f"完成上传失败: {response.status_code}, {response.text}")
-        return False
-    except Exception as e:
-        print(f"完成上传异常: {str(e)}")
-        return False
-
-
-def oss_upload(file_path: str, oss_path: str, filename: Optional[str] = None,
-              process_key: str = "file-upload", device_id: str = "default") -> bool:
+def oss_upload(
+    file_path: Union[str, Path],
+    filename: Optional[str] = None,
+    driver_name: str = "default",
+    exp_type: str = "default",
+    max_retries: int = 3,
+    client: Optional[HTTPClient] = None,
+) -> Dict:
     """
     文件上传主函数，包含重试机制
 
     Args:
         file_path: 本地文件路径
-        oss_path: OSS目标路径
         filename: 文件名，如果为None则使用file_path的文件名
-        process_key: 处理键
-        device_id: 设备ID
+        driver_name: 驱动名称，用于构造scene
+        exp_type: 实验类型，用于构造scene
+        max_retries: 最大重试次数
+        client: HTTPClient实例，如果不提供则使用默认的http_client
 
     Returns:
-        是否成功上传
+        Dict: {
+            "success": bool,  # 是否上传成功
+            "original_path": str,  # 原始文件路径
+            "oss_path": str  # OSS路径（成功时）或空字符串（失败时）
+        }
     """
-    max_retries = OSSUploadConfig.max_retries
+    file_path = Path(file_path)
+    if filename is None:
+        filename = os.path.basename(file_path)
+
+    if not os.path.exists(file_path):
+        logger.error(f"[OSS] 文件不存在: {file_path}")
+        return {"success": False, "original_path": file_path, "oss_path": ""}
+
     retry_count = 0
+    oss_path = ""
 
     while retry_count < max_retries:
         try:
-            # 步骤1：初始化上传
-            init_success, init_data = _init_upload(
-                file_path=file_path,
-                oss_path=oss_path,
-                filename=filename,
-                process_key=process_key,
-                device_id=device_id
+            # 步骤1：获取预签名URL
+            token_success, token_data = _get_oss_token(
+                filename=filename, driver_name=driver_name, exp_type=exp_type, client=client
             )
 
-            if not init_success:
-                print(f"初始化上传失败，重试 {retry_count + 1}/{max_retries}")
+            if not token_success:
+                logger.warning(f"[OSS] 获取预签名URL失败，重试 {retry_count + 1}/{max_retries}")
                 retry_count += 1
-                time.sleep(1)  # 等待1秒后重试
+                time.sleep(1)
                 continue
 
-            # 获取UUID和上传URL
-            uuid = init_data.get("uuid")
-            upload_url = init_data.get("upload_url")
+            # 获取预签名URL和OSS路径
+            upload_url = token_data.get("url")
+            oss_path = token_data.get("path", "")
 
-            if not uuid or not upload_url:
-                print(f"初始化上传返回数据不完整，重试 {retry_count + 1}/{max_retries}")
+            if not upload_url:
+                logger.warning(f"[OSS] 无法获取上传URL，API未返回url字段")
                 retry_count += 1
                 time.sleep(1)
                 continue
@@ -163,69 +160,82 @@ def oss_upload(file_path: str, oss_path: str, filename: Optional[str] = None,
             # 步骤2：PUT上传文件
             put_success = _put_upload(file_path, upload_url)
             if not put_success:
-                print(f"PUT上传失败，重试 {retry_count + 1}/{max_retries}")
-                retry_count += 1
-                time.sleep(1)
-                continue
-
-            # 步骤3：完成上传
-            complete_success = _complete_upload(uuid)
-            if not complete_success:
-                print(f"完成上传失败，重试 {retry_count + 1}/{max_retries}")
+                logger.warning(f"[OSS] PUT上传失败，重试 {retry_count + 1}/{max_retries}")
                 retry_count += 1
                 time.sleep(1)
                 continue
 
             # 所有步骤都成功
-            print(f"文件 {file_path} 上传成功")
-            return True
+            logger.info(f"[OSS] 文件 {file_path} 上传成功")
+            return {"success": True, "original_path": file_path, "oss_path": oss_path}
 
         except Exception as e:
-            print(f"上传过程异常: {str(e)}，重试 {retry_count + 1}/{max_retries}")
+            logger.error(f"[OSS] 上传过程异常: {str(e)}，重试 {retry_count + 1}/{max_retries}")
             retry_count += 1
             time.sleep(1)
 
-    print(f"文件 {file_path} 上传失败，已达到最大重试次数 {max_retries}")
-    return False
+    logger.error(f"[OSS] 文件 {file_path} 上传失败，已达到最大重试次数 {max_retries}")
+    return {"success": False, "original_path": file_path, "oss_path": oss_path}
 
 
 if __name__ == "__main__":
-    # python -m unilabos.app.oss_upload -f /path/to/your/file.txt
+    # python -m unilabos.app.oss_upload -f /path/to/your/file.txt --driver HPLC --type test
+    # python -m unilabos.app.oss_upload -f /path/to/your/file.txt --driver HPLC --type test \
+    #        --ak xxx --sk yyy --remote-addr http://xxx/api/v1
     # 命令行参数解析
-    parser = argparse.ArgumentParser(description='文件上传测试工具')
-    parser.add_argument('--file', '-f', type=str, required=True, help='要上传的本地文件路径')
-    parser.add_argument('--path', '-p', type=str, default='/HPLC1/Any', help='OSS目标路径')
-    parser.add_argument('--device', '-d', type=str, default='test-device', help='设备ID')
-    parser.add_argument('--process', '-k', type=str, default='HPLC-txt-result', help='处理键')
+    parser = argparse.ArgumentParser(description="文件上传测试工具")
+    parser.add_argument("--file", "-f", type=str, required=True, help="要上传的本地文件路径")
+    parser.add_argument("--driver", "-d", type=str, default="default", help="驱动名称")
+    parser.add_argument("--type", "-t", type=str, default="default", help="实验类型")
+    parser.add_argument("--ak", type=str, help="Access Key，如果提供则覆盖配置")
+    parser.add_argument("--sk", type=str, help="Secret Key，如果提供则覆盖配置")
+    parser.add_argument("--remote-addr", type=str, help="远程服务器地址（包含/api/v1），如果提供则覆盖配置")
 
     args = parser.parse_args()
 
     # 检查文件是否存在
     if not os.path.exists(args.file):
-        print(f"错误：文件 {args.file} 不存在")
+        logger.error(f"错误：文件 {args.file} 不存在")
         exit(1)
 
-    print("=" * 50)
-    print(f"开始上传文件: {args.file}")
-    print(f"目标路径: {args.path}")
-    print(f"设备ID: {args.device}")
-    print(f"处理键: {args.process}")
-    print("=" * 50)
+    # 如果提供了ak/sk/remote_addr，创建临时HTTPClient
+    temp_client = None
+    if args.ak and args.sk:
+        import base64
+
+        auth = base64.b64encode(f"{args.ak}:{args.sk}".encode("utf-8")).decode("utf-8")
+        remote_addr = args.remote_addr if args.remote_addr else http_client.remote_addr
+        temp_client = HTTPClient(remote_addr=remote_addr, auth=auth)
+        logger.info(f"[配置] 使用自定义配置: remote_addr={remote_addr}")
+    elif args.remote_addr:
+        temp_client = HTTPClient(remote_addr=args.remote_addr, auth=http_client.auth)
+        logger.info(f"[配置] 使用自定义remote_addr: {args.remote_addr}")
+    else:
+        logger.info(f"[配置] 使用默认配置: remote_addr={http_client.remote_addr}")
+
+    logger.info("=" * 50)
+    logger.info(f"开始上传文件: {args.file}")
+    logger.info(f"驱动名称: {args.driver}")
+    logger.info(f"实验类型: {args.type}")
+    logger.info(f"Scene: {args.driver}-{args.type}")
+    logger.info("=" * 50)
 
     # 执行上传
-    success = oss_upload(
+    result = oss_upload(
         file_path=args.file,
-        oss_path=args.path,
         filename=None,  # 使用默认文件名
-        process_key=args.process,
-        device_id=args.device
+        driver_name=args.driver,
+        exp_type=args.type,
+        client=temp_client,
     )
 
     # 输出结果
-    if success:
-        print("\n√ 文件上传成功！")
+    if result["success"]:
+        logger.info(f"\n√ 文件上传成功！")
+        logger.info(f"原始路径: {result['original_path']}")
+        logger.info(f"OSS路径: {result['oss_path']}")
         exit(0)
     else:
-        print("\n× 文件上传失败！")
+        logger.error(f"\n× 文件上传失败！")
+        logger.error(f"原始路径: {result['original_path']}")
         exit(1)
-

unilabos/app/register.py

@@ -1,11 +1,12 @@
 import json
 import time
+from typing import Optional, Tuple, Dict, Any
 
 from unilabos.utils.log import logger
 from unilabos.utils.type_check import TypeEncoder
 
 
-def register_devices_and_resources(lab_registry):
+def register_devices_and_resources(lab_registry, gather_only=False) -> Optional[Tuple[Dict[str, Any], Dict[str, Any]]]:
     """
     注册设备和资源到服务器（仅支持HTTP）
     """
@@ -28,6 +29,8 @@ def register_devices_and_resources(lab_registry):
         resources_to_register[resource_info["id"]] = resource_info
         logger.debug(f"[UniLab Register] 收集资源: {resource_info['id']}")
 
+    if gather_only:
+        return devices_to_register, resources_to_register
     # 注册设备
     if devices_to_register:
         try:

unilabos/app/web/api.py

@@ -9,13 +9,22 @@ import asyncio
 
 import yaml
 
-from unilabos.app.web.controler import devices, job_add, job_info
+from unilabos.app.web.controller import (
+    devices,
+    job_add,
+    job_info,
+    get_online_devices,
+    get_device_actions,
+    get_action_schema,
+    get_all_available_actions,
+)
 from unilabos.app.model import (
     Resp,
     RespCode,
     JobStatusResp,
     JobAddResp,
     JobAddReq,
+    JobData,
 )
 from unilabos.app.web.utils.host_utils import get_host_node_info
 from unilabos.registry.registry import lab_registry
@@ -1234,6 +1243,65 @@ def get_devices():
     return Resp(data=dict(data))
 
 
+@api.get("/online-devices", summary="Online devices list", response_model=Resp)
+def api_get_online_devices():
+    """获取在线设备列表
+
+    返回当前在线的设备列表，包含设备ID、命名空间、机器名等信息
+    """
+    isok, data = get_online_devices()
+    if not isok:
+        return Resp(code=RespCode.ErrorHostNotInit, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
+@api.get("/devices/{device_id}/actions", summary="Device actions list", response_model=Resp)
+def api_get_device_actions(device_id: str):
+    """获取设备可用的动作列表
+
+    Args:
+        device_id: 设备ID
+
+    返回指定设备的所有可用动作，包含动作名称、类型、是否繁忙等信息
+    """
+    isok, data = get_device_actions(device_id)
+    if not isok:
+        return Resp(code=RespCode.ErrorInvalidReq, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
+@api.get("/devices/{device_id}/actions/{action_name}/schema", summary="Action schema", response_model=Resp)
+def api_get_action_schema(device_id: str, action_name: str):
+    """获取动作的Schema详情
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    返回动作的参数Schema、默认值、类型等详细信息
+    """
+    isok, data = get_action_schema(device_id, action_name)
+    if not isok:
+        return Resp(code=RespCode.ErrorInvalidReq, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
+@api.get("/actions", summary="All available actions", response_model=Resp)
+def api_get_all_actions():
+    """获取所有设备的可用动作
+
+    返回所有已注册设备的动作列表，包含设备信息和各动作的状态
+    """
+    isok, data = get_all_available_actions()
+    if not isok:
+        return Resp(code=RespCode.ErrorHostNotInit, message=data.get("error", "Unknown error"))
+
+    return Resp(data=data)
+
+
 @api.get("/job/{id}/status", summary="Job status", response_model=JobStatusResp)
 def job_status(id: str):
     """获取任务状态"""
@@ -1244,11 +1312,22 @@ def job_status(id: str):
 @api.post("/job/add", summary="Create job", response_model=JobAddResp)
 def post_job_add(req: JobAddReq):
     """创建任务"""
-    device_id = req.device_id
-    if not req.data:
-        return Resp(code=RespCode.ErrorInvalidReq, message="Invalid request data")
+    # 检查必要参数：device_id 和 action
+    if not req.device_id:
+        return JobAddResp(
+            data=JobData(jobId="", status=6),
+            code=RespCode.ErrorInvalidReq,
+            message="device_id is required",
+        )
+
+    action_name = req.data.get("action", req.action) if req.data else req.action
+    if not action_name:
+        return JobAddResp(
+            data=JobData(jobId="", status=6),
+            code=RespCode.ErrorInvalidReq,
+            message="action is required",
+        )
 
-    req.device_id = device_id
     data = job_add(req)
     return JobAddResp(data=data)
 

unilabos/app/web/client.py

@@ -76,7 +76,8 @@ class HTTPClient:
             Dict[str, str]: 旧UUID到新UUID的映射关系 {old_uuid: new_uuid}
         """
         with open(os.path.join(BasicConfig.working_dir, "req_resource_tree_add.json"), "w", encoding="utf-8") as f:
-            f.write(json.dumps({"nodes": [x for xs in resources.dump() for x in xs], "mount_uuid": mount_uuid}, indent=4))
+            payload = {"nodes": [x for xs in resources.dump() for x in xs], "mount_uuid": mount_uuid}
+            f.write(json.dumps(payload, indent=4))
         # 从序列化数据中提取所有节点的UUID（保存旧UUID）
         old_uuids = {n.res_content.uuid: n for n in resources.all_nodes}
         if not self.initialized or first_add:
@@ -331,6 +332,67 @@ class HTTPClient:
                 logger.error(f"响应内容: {response.text}")
         return None
 
+    def workflow_import(
+        self,
+        name: str,
+        workflow_uuid: str,
+        workflow_name: str,
+        nodes: List[Dict[str, Any]],
+        edges: List[Dict[str, Any]],
+        tags: Optional[List[str]] = None,
+        published: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        导入工作流到服务器
+
+        Args:
+            name: 工作流名称（顶层）
+            workflow_uuid: 工作流UUID
+            workflow_name: 工作流名称（data内部）
+            nodes: 工作流节点列表
+            edges: 工作流边列表
+            tags: 工作流标签列表，默认为空列表
+            published: 是否发布工作流，默认为False
+
+        Returns:
+            Dict: API响应数据，包含 code 和 data (uuid, name)
+        """
+        # target_lab_uuid 暂时使用默认值，后续由后端根据 ak/sk 获取
+        payload = {
+            "target_lab_uuid": "28c38bb0-63f6-4352-b0d8-b5b8eb1766d5",
+            "name": name,
+            "data": {
+                "workflow_uuid": workflow_uuid,
+                "workflow_name": workflow_name,
+                "nodes": nodes,
+                "edges": edges,
+                "tags": tags if tags is not None else [],
+                "published": published,
+            },
+        }
+        # 保存请求到文件
+        with open(os.path.join(BasicConfig.working_dir, "req_workflow_upload.json"), "w", encoding="utf-8") as f:
+            f.write(json.dumps(payload, indent=4, ensure_ascii=False))
+
+        response = requests.post(
+            f"{self.remote_addr}/lab/workflow/owner/import",
+            json=payload,
+            headers={"Authorization": f"Lab {self.auth}"},
+            timeout=60,
+        )
+        # 保存响应到文件
+        with open(os.path.join(BasicConfig.working_dir, "res_workflow_upload.json"), "w", encoding="utf-8") as f:
+            f.write(f"{response.status_code}" + "\n" + response.text)
+
+        if response.status_code == 200:
+            res = response.json()
+            if "code" in res and res["code"] != 0:
+                logger.error(f"导入工作流失败: {response.text}")
+            return res
+        else:
+            logger.error(f"导入工作流失败: {response.status_code}, {response.text}")
+            return {"code": response.status_code, "message": response.text}
+
 
 # 创建默认客户端实例
 http_client = HTTPClient()

unilabos/app/web/controler.py

@@ -1,45 +0,0 @@
-
-import json
-import traceback
-import uuid
-from unilabos.app.model import JobAddReq, JobData
-from unilabos.ros.nodes.presets.host_node import HostNode
-from unilabos.utils.type_check import serialize_result_info
-
-
-def get_resources() -> tuple:
-    if HostNode.get_instance() is None:
-        return False, "Host node not initialized"
-
-    return True, HostNode.get_instance().resources_config
-
-def devices() -> tuple:
-    if HostNode.get_instance() is None:
-        return False, "Host node not initialized"
-    
-    return True, HostNode.get_instance().devices_config
-
-def job_info(id: str):
-    get_goal_status = HostNode.get_instance().get_goal_status(id)
-    return JobData(jobId=id, status=get_goal_status)
-
-def job_add(req: JobAddReq) -> JobData:
-    if req.job_id is None:
-        req.job_id = str(uuid.uuid4())
-    action_name = req.data["action"]
-    action_type = req.data.get("action_type", "LocalUnknown")
-    action_args = req.data.get("action_kwargs", None)  # 兼容老版本，后续删除
-    if action_args is None:
-        action_args = req.data.get("action_args")
-    else:
-        if "command" in action_args:
-            action_args = action_args["command"]
-    # print(f"job_add:{req.device_id} {action_name} {action_kwargs}")
-    try:
-        HostNode.get_instance().send_goal(req.device_id, action_type=action_type, action_name=action_name, action_kwargs=action_args, goal_uuid=req.job_id, server_info=req.server_info)
-    except Exception as e:
-        for bridge in HostNode.get_instance().bridges:
-            traceback.print_exc()
-            if hasattr(bridge, "publish_job_status"):
-                bridge.publish_job_status({}, req.job_id, "failed", serialize_result_info(traceback.format_exc(), False, {}))
-    return JobData(jobId=req.job_id)

unilabos/app/web/controller.py

@@ -0,0 +1,587 @@
+"""
+Web API Controller
+
+提供Web API的控制器函数，处理设备、任务和动作相关的业务逻辑
+"""
+
+import threading
+import time
+import traceback
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Tuple
+
+from unilabos.app.model import JobAddReq, JobData
+from unilabos.ros.nodes.presets.host_node import HostNode
+from unilabos.utils import logger
+
+
+@dataclass
+class JobResult:
+    """任务结果数据"""
+
+    job_id: str
+    status: int  # 4:SUCCEEDED, 5:CANCELED, 6:ABORTED
+    result: Dict[str, Any] = field(default_factory=dict)
+    feedback: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+
+class JobResultStore:
+    """任务结果存储（单例）"""
+
+    _instance: Optional["JobResultStore"] = None
+    _lock = threading.Lock()
+
+    def __init__(self):
+        if not hasattr(self, "_initialized"):
+            self._results: Dict[str, JobResult] = {}
+            self._results_lock = threading.RLock()
+            self._initialized = True
+
+    def __new__(cls):
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def store_result(
+        self, job_id: str, status: int, result: Optional[Dict[str, Any]], feedback: Optional[Dict[str, Any]] = None
+    ):
+        """存储任务结果"""
+        with self._results_lock:
+            self._results[job_id] = JobResult(
+                job_id=job_id,
+                status=status,
+                result=result or {},
+                feedback=feedback or {},
+                timestamp=time.time(),
+            )
+            logger.debug(f"[JobResultStore] Stored result for job {job_id[:8]}, status={status}")
+
+    def get_and_remove(self, job_id: str) -> Optional[JobResult]:
+        """获取并删除任务结果"""
+        with self._results_lock:
+            result = self._results.pop(job_id, None)
+            if result:
+                logger.debug(f"[JobResultStore] Retrieved and removed result for job {job_id[:8]}")
+            return result
+
+    def get_result(self, job_id: str) -> Optional[JobResult]:
+        """仅获取任务结果（不删除）"""
+        with self._results_lock:
+            return self._results.get(job_id)
+
+    def cleanup_old_results(self, max_age_seconds: float = 3600):
+        """清理过期的结果"""
+        current_time = time.time()
+        with self._results_lock:
+            expired_jobs = [
+                job_id for job_id, result in self._results.items() if current_time - result.timestamp > max_age_seconds
+            ]
+            for job_id in expired_jobs:
+                del self._results[job_id]
+                logger.debug(f"[JobResultStore] Cleaned up expired result for job {job_id[:8]}")
+
+
+# 全局结果存储实例
+job_result_store = JobResultStore()
+
+
+def store_job_result(
+    job_id: str, status: str, result: Optional[Dict[str, Any]], feedback: Optional[Dict[str, Any]] = None
+):
+    """存储任务结果（供外部调用）
+
+    Args:
+        job_id: 任务ID
+        status: 状态字符串 ("success", "failed", "cancelled")
+        result: 结果数据
+        feedback: 反馈数据
+    """
+    # 转换状态字符串为整数
+    status_map = {
+        "success": 4,  # SUCCEEDED
+        "failed": 6,  # ABORTED
+        "cancelled": 5,  # CANCELED
+        "running": 2,  # EXECUTING
+    }
+    status_int = status_map.get(status, 0)
+
+    # 只存储最终状态
+    if status_int in (4, 5, 6):
+        job_result_store.store_result(job_id, status_int, result, feedback)
+
+
+def get_resources() -> Tuple[bool, Any]:
+    """获取资源配置
+
+    Returns:
+        Tuple[bool, Any]: (是否成功, 资源配置或错误信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, "Host node not initialized"
+
+    return True, host_node.resources_config
+
+
+def devices() -> Tuple[bool, Any]:
+    """获取设备配置
+
+    Returns:
+        Tuple[bool, Any]: (是否成功, 设备配置或错误信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, "Host node not initialized"
+
+    return True, host_node.devices_config
+
+
+def job_info(job_id: str, remove_after_read: bool = True) -> JobData:
+    """获取任务信息
+
+    Args:
+        job_id: 任务ID
+        remove_after_read: 是否在读取后删除结果（默认True）
+
+    Returns:
+        JobData: 任务数据
+    """
+    # 首先检查结果存储中是否有已完成的结果
+    if remove_after_read:
+        stored_result = job_result_store.get_and_remove(job_id)
+    else:
+        stored_result = job_result_store.get_result(job_id)
+
+    if stored_result:
+        # 有存储的结果，直接返回
+        return JobData(
+            jobId=job_id,
+            status=stored_result.status,
+            result=stored_result.result,
+        )
+
+    # 没有存储的结果，从 HostNode 获取当前状态
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return JobData(jobId=job_id, status=0)
+
+    get_goal_status = host_node.get_goal_status(job_id)
+    return JobData(jobId=job_id, status=get_goal_status)
+
+
+def check_device_action_busy(device_id: str, action_name: str) -> Tuple[bool, Optional[str]]:
+    """检查设备动作是否正在执行（被占用）
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    Returns:
+        Tuple[bool, Optional[str]]: (是否繁忙, 当前执行的job_id或None)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, None
+
+    device_action_key = f"/devices/{device_id}/{action_name}"
+
+    # 检查 _device_action_status 中是否有正在执行的任务
+    if device_action_key in host_node._device_action_status:
+        status = host_node._device_action_status[device_action_key]
+        if status.job_ids:
+            # 返回第一个正在执行的job_id
+            current_job_id = next(iter(status.job_ids.keys()), None)
+            return True, current_job_id
+
+    return False, None
+
+
+def _get_action_type(device_id: str, action_name: str) -> Optional[str]:
+    """从注册表自动获取动作类型
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    Returns:
+        动作类型字符串，未找到返回None
+    """
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+
+        # 方法1: 从运行时注册设备获取
+        if device_id in registered_devices:
+            device_info = registered_devices[device_id]
+            base_node = device_info.get("base_node_instance")
+            if base_node and hasattr(base_node, "_action_value_mappings"):
+                action_mappings = base_node._action_value_mappings
+                # 尝试直接匹配或 auto- 前缀匹配
+                for key in [action_name, f"auto-{action_name}"]:
+                    if key in action_mappings:
+                        action_type = action_mappings[key].get("type")
+                        if action_type:
+                            # 转换为字符串格式
+                            if hasattr(action_type, "__module__") and hasattr(action_type, "__name__"):
+                                return f"{action_type.__module__}.{action_type.__name__}"
+                            return str(action_type)
+
+        # 方法2: 从lab_registry获取
+        from unilabos.registry.registry import lab_registry
+
+        host_node = HostNode.get_instance(0)
+        if host_node and lab_registry:
+            devices_config = host_node.devices_config
+            device_class = None
+
+            for tree in devices_config.trees:
+                node = tree.root_node
+                if node.res_content.id == device_id:
+                    device_class = node.res_content.klass
+                    break
+
+            if device_class and device_class in lab_registry.device_type_registry:
+                device_type_info = lab_registry.device_type_registry[device_class]
+                class_info = device_type_info.get("class", {})
+                action_mappings = class_info.get("action_value_mappings", {})
+
+                for key in [action_name, f"auto-{action_name}"]:
+                    if key in action_mappings:
+                        action_type = action_mappings[key].get("type")
+                        if action_type:
+                            if hasattr(action_type, "__module__") and hasattr(action_type, "__name__"):
+                                return f"{action_type.__module__}.{action_type.__name__}"
+                            return str(action_type)
+
+    except Exception as e:
+        logger.warning(f"[Controller] Failed to get action type for {device_id}/{action_name}: {str(e)}")
+
+    return None
+
+
+def job_add(req: JobAddReq) -> JobData:
+    """添加任务（检查设备是否繁忙，繁忙则返回失败）
+
+    Args:
+        req: 任务添加请求
+
+    Returns:
+        JobData: 任务数据（包含状态）
+    """
+    # 服务端自动生成 job_id 和 task_id
+    job_id = str(uuid.uuid4())
+    task_id = str(uuid.uuid4())
+
+    # 服务端自动生成 server_info
+    server_info = {"send_timestamp": time.time()}
+
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        logger.error(f"[Controller] Host node not initialized for job: {job_id[:8]}")
+        return JobData(jobId=job_id, status=6)  # 6 = ABORTED
+
+    # 解析动作信息
+    action_name = req.data.get("action", req.action) if req.data else req.action
+    action_args = req.data.get("action_kwargs") or req.data.get("action_args") if req.data else req.action_args
+
+    if action_args is None:
+        action_args = req.action_args or {}
+    elif isinstance(action_args, dict) and "command" in action_args:
+        action_args = action_args["command"]
+
+    # 自动获取 action_type
+    action_type = _get_action_type(req.device_id, action_name)
+    if action_type is None:
+        logger.error(f"[Controller] Action type not found for {req.device_id}/{action_name}")
+        return JobData(jobId=job_id, status=6)  # ABORTED
+
+    # 检查设备动作是否繁忙
+    is_busy, current_job_id = check_device_action_busy(req.device_id, action_name)
+
+    if is_busy:
+        logger.warning(
+            f"[Controller] Device action busy: {req.device_id}/{action_name}, "
+            f"current job: {current_job_id[:8] if current_job_id else 'unknown'}"
+        )
+        # 返回失败状态，status=6 表示 ABORTED
+        return JobData(jobId=job_id, status=6)
+
+    # 设备空闲，提交任务执行
+    try:
+        from unilabos.app.ws_client import QueueItem
+
+        device_action_key = f"/devices/{req.device_id}/{action_name}"
+        queue_item = QueueItem(
+            task_type="job_call_back_status",
+            device_id=req.device_id,
+            action_name=action_name,
+            task_id=task_id,
+            job_id=job_id,
+            device_action_key=device_action_key,
+        )
+
+        host_node.send_goal(
+            queue_item,
+            action_type=action_type,
+            action_kwargs=action_args,
+            server_info=server_info,
+        )
+
+        logger.info(f"[Controller] Job submitted: {job_id[:8]} -> {req.device_id}/{action_name}")
+        # 返回已接受状态，status=1 表示 ACCEPTED
+        return JobData(jobId=job_id, status=1)
+
+    except ValueError as e:
+        # ActionClient not found 等错误
+        logger.error(f"[Controller] Action not available: {str(e)}")
+        return JobData(jobId=job_id, status=6)  # ABORTED
+
+    except Exception as e:
+        logger.error(f"[Controller] Error submitting job: {str(e)}")
+        traceback.print_exc()
+        return JobData(jobId=job_id, status=6)  # ABORTED
+
+
+def get_online_devices() -> Tuple[bool, Dict[str, Any]]:
+    """获取在线设备列表
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, 在线设备信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+
+        online_devices = {}
+        for device_key in host_node._online_devices:
+            # device_key 格式: "namespace/device_id"
+            parts = device_key.split("/")
+            if len(parts) >= 2:
+                device_id = parts[-1]
+            else:
+                device_id = device_key
+
+            # 获取设备详细信息
+            device_info = registered_devices.get(device_id, {})
+            machine_name = host_node.device_machine_names.get(device_id, "未知")
+
+            online_devices[device_id] = {
+                "device_key": device_key,
+                "namespace": host_node.devices_names.get(device_id, ""),
+                "machine_name": machine_name,
+                "uuid": device_info.get("uuid", "") if device_info else "",
+                "node_name": device_info.get("node_name", "") if device_info else "",
+            }
+
+        return True, {
+            "online_devices": online_devices,
+            "total_count": len(online_devices),
+            "timestamp": time.time(),
+        }
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting online devices: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
+
+
+def get_device_actions(device_id: str) -> Tuple[bool, Dict[str, Any]]:
+    """获取设备可用的动作列表
+
+    Args:
+        device_id: 设备ID
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, 动作列表信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+        from unilabos.app.web.utils.action_utils import get_action_info
+
+        # 检查设备是否已注册
+        if device_id not in registered_devices:
+            return False, {"error": f"Device not found: {device_id}"}
+
+        device_info = registered_devices[device_id]
+        actions = device_info.get("actions", {})
+
+        actions_list = {}
+        for action_name, action_server in actions.items():
+            try:
+                action_info = get_action_info(action_server, action_name)
+                # 检查动作是否繁忙
+                is_busy, current_job = check_device_action_busy(device_id, action_name)
+                actions_list[action_name] = {
+                    **action_info,
+                    "is_busy": is_busy,
+                    "current_job_id": current_job[:8] if current_job else None,
+                }
+            except Exception as e:
+                logger.warning(f"[Controller] Error getting action info for {action_name}: {str(e)}")
+                actions_list[action_name] = {
+                    "type_name": "unknown",
+                    "action_path": f"/devices/{device_id}/{action_name}",
+                    "is_busy": False,
+                    "error": str(e),
+                }
+
+        return True, {
+            "device_id": device_id,
+            "actions": actions_list,
+            "action_count": len(actions_list),
+        }
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting device actions: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
+
+
+def get_action_schema(device_id: str, action_name: str) -> Tuple[bool, Dict[str, Any]]:
+    """获取动作的Schema详情
+
+    Args:
+        device_id: 设备ID
+        action_name: 动作名称
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, Schema信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.registry.registry import lab_registry
+        from unilabos.ros.nodes.base_device_node import registered_devices
+
+        result = {
+            "device_id": device_id,
+            "action_name": action_name,
+            "schema": None,
+            "goal_default": None,
+            "action_type": None,
+            "is_busy": False,
+        }
+
+        # 检查动作是否繁忙
+        is_busy, current_job = check_device_action_busy(device_id, action_name)
+        result["is_busy"] = is_busy
+        result["current_job_id"] = current_job[:8] if current_job else None
+
+        # 方法1: 从 registered_devices 获取运行时信息
+        if device_id in registered_devices:
+            device_info = registered_devices[device_id]
+            base_node = device_info.get("base_node_instance")
+
+            if base_node and hasattr(base_node, "_action_value_mappings"):
+                action_mappings = base_node._action_value_mappings
+                if action_name in action_mappings:
+                    mapping = action_mappings[action_name]
+                    result["schema"] = mapping.get("schema")
+                    result["goal_default"] = mapping.get("goal_default")
+                    result["action_type"] = str(mapping.get("type", ""))
+
+        # 方法2: 从 lab_registry 获取注册表信息（如果运行时没有）
+        if result["schema"] is None and lab_registry:
+            # 尝试查找设备类型
+            devices_config = host_node.devices_config
+            device_class = None
+
+            # 从配置中获取设备类型
+            for tree in devices_config.trees:
+                node = tree.root_node
+                if node.res_content.id == device_id:
+                    device_class = node.res_content.klass
+                    break
+
+            if device_class and device_class in lab_registry.device_type_registry:
+                device_type_info = lab_registry.device_type_registry[device_class]
+                class_info = device_type_info.get("class", {})
+                action_mappings = class_info.get("action_value_mappings", {})
+
+                # 尝试直接匹配或 auto- 前缀匹配
+                for key in [action_name, f"auto-{action_name}"]:
+                    if key in action_mappings:
+                        mapping = action_mappings[key]
+                        result["schema"] = mapping.get("schema")
+                        result["goal_default"] = mapping.get("goal_default")
+                        result["action_type"] = str(mapping.get("type", ""))
+                        result["handles"] = mapping.get("handles", {})
+                        result["placeholder_keys"] = mapping.get("placeholder_keys", {})
+                        break
+
+        if result["schema"] is None:
+            return False, {"error": f"Action schema not found: {device_id}/{action_name}"}
+
+        return True, result
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting action schema: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}
+
+
+def get_all_available_actions() -> Tuple[bool, Dict[str, Any]]:
+    """获取所有设备的可用动作
+
+    Returns:
+        Tuple[bool, Dict]: (是否成功, 所有设备的动作信息)
+    """
+    host_node = HostNode.get_instance(0)
+    if host_node is None:
+        return False, {"error": "Host node not initialized"}
+
+    try:
+        from unilabos.ros.nodes.base_device_node import registered_devices
+        from unilabos.app.web.utils.action_utils import get_action_info
+
+        all_actions = {}
+        total_action_count = 0
+
+        for device_id, device_info in registered_devices.items():
+            actions = device_info.get("actions", {})
+            device_actions = {}
+
+            for action_name, action_server in actions.items():
+                try:
+                    action_info = get_action_info(action_server, action_name)
+                    is_busy, current_job = check_device_action_busy(device_id, action_name)
+                    device_actions[action_name] = {
+                        "type_name": action_info.get("type_name", ""),
+                        "action_path": action_info.get("action_path", ""),
+                        "is_busy": is_busy,
+                        "current_job_id": current_job[:8] if current_job else None,
+                    }
+                    total_action_count += 1
+                except Exception as e:
+                    logger.warning(f"[Controller] Error processing action {device_id}/{action_name}: {str(e)}")
+
+            if device_actions:
+                all_actions[device_id] = {
+                    "actions": device_actions,
+                    "action_count": len(device_actions),
+                    "machine_name": host_node.device_machine_names.get(device_id, "未知"),
+                }
+
+        return True, {
+            "devices": all_actions,
+            "device_count": len(all_actions),
+            "total_action_count": total_action_count,
+            "timestamp": time.time(),
+        }
+
+    except Exception as e:
+        logger.error(f"[Controller] Error getting all available actions: {str(e)}")
+        traceback.print_exc()
+        return False, {"error": str(e)}

unilabos/app/ws_client.py

@@ -261,29 +261,28 @@ class DeviceActionManager:
             device_key = job_info.device_action_key
 
             # 如果是正在执行的任务
-            if (
-                device_key in self.active_jobs and self.active_jobs[device_key].job_id == job_id
-            ):  # 后面需要和cancel_goal进行联动，而不是在这里进行处理，现在默认等待这个job结束
-                # del self.active_jobs[device_key]
-                # job_info.status = JobStatus.ENDED
-                # # 从all_jobs中移除
-                # del self.all_jobs[job_id]
-                # job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
-                # logger.info(f"[DeviceActionManager] Active job {job_log} cancelled for {device_key}")
+            if device_key in self.active_jobs and self.active_jobs[device_key].job_id == job_id:
+                # 清理active job状态
+                del self.active_jobs[device_key]
+                job_info.status = JobStatus.ENDED
+                # 从all_jobs中移除
+                del self.all_jobs[job_id]
+                job_log = format_job_log(job_info.job_id, job_info.task_id, job_info.device_id, job_info.action_name)
+                logger.info(f"[DeviceActionManager] Active job {job_log} cancelled for {device_key}")
 
-                # # 启动下一个任务
-                # if device_key in self.device_queues and self.device_queues[device_key]:
-                #     next_job = self.device_queues[device_key].pop(0)
-                #     # 将下一个job设置为READY状态并放入active_jobs
-                #     next_job.status = JobStatus.READY
-                #     next_job.update_timestamp()
-                #     next_job.set_ready_timeout(10)
-                #     self.active_jobs[device_key] = next_job
-                #     next_job_log = format_job_log(next_job.job_id, next_job.task_id,
-                #                                   next_job.device_id, next_job.action_name)
-                #     logger.info(f"[DeviceActionManager] Next job {next_job_log} can start after cancel")
-                #     return True
-                pass
+                # 启动下一个任务
+                if device_key in self.device_queues and self.device_queues[device_key]:
+                    next_job = self.device_queues[device_key].pop(0)
+                    # 将下一个job设置为READY状态并放入active_jobs
+                    next_job.status = JobStatus.READY
+                    next_job.update_timestamp()
+                    next_job.set_ready_timeout(10)
+                    self.active_jobs[device_key] = next_job
+                    next_job_log = format_job_log(
+                        next_job.job_id, next_job.task_id, next_job.device_id, next_job.action_name
+                    )
+                    logger.info(f"[DeviceActionManager] Next job {next_job_log} can start after cancel")
+                return True
 
             # 如果是排队中的任务
             elif device_key in self.device_queues:
@@ -360,6 +359,7 @@ class MessageProcessor:
         self.device_manager = device_manager
         self.queue_processor = None  # 延迟设置
         self.websocket_client = None  # 延迟设置
+        self.session_id = ""
 
         # WebSocket连接
         self.websocket = None
@@ -389,7 +389,7 @@ class MessageProcessor:
         self.is_running = True
         self.thread = threading.Thread(target=self._run, daemon=True, name="MessageProcessor")
         self.thread.start()
-        logger.info("[MessageProcessor] Started")
+        logger.trace("[MessageProcessor] Started")
 
     def stop(self) -> None:
         """停止消息处理线程"""
@@ -428,14 +428,17 @@ class MessageProcessor:
                     ssl=ssl_context,
                     ping_interval=WSConfig.ping_interval,
                     ping_timeout=10,
-                    additional_headers={"Authorization": f"Lab {BasicConfig.auth_secret()}"},
+                    additional_headers={
+                        "Authorization": f"Lab {BasicConfig.auth_secret()}",
+                        "EdgeSession": f"{self.session_id}",
+                    },
                     logger=ws_logger,
                 ) as websocket:
                     self.websocket = websocket
                     self.connected = True
                     self.reconnect_count = 0
 
-                    logger.info(f"[MessageProcessor] Connected to {self.websocket_url}")
+                    logger.trace(f"[MessageProcessor] Connected to {self.websocket_url}")
 
                     # 启动发送协程
                     send_task = asyncio.create_task(self._send_handler())
@@ -500,7 +503,7 @@ class MessageProcessor:
 
     async def _send_handler(self):
         """处理发送队列中的消息"""
-        logger.debug("[MessageProcessor] Send handler started")
+        logger.trace("[MessageProcessor] Send handler started")
 
         try:
             while self.connected and self.websocket:
@@ -573,6 +576,9 @@ class MessageProcessor:
                 await self._handle_resource_tree_update(message_data, "update")
             elif message_type == "remove_material":
                 await self._handle_resource_tree_update(message_data, "remove")
+            elif message_type == "session_id":
+                self.session_id = message_data.get("session_id")
+                logger.info(f"[MessageProcessor] Session ID: {self.session_id}")
             else:
                 logger.debug(f"[MessageProcessor] Unknown message type: {message_type}")
 
@@ -741,31 +747,51 @@ class MessageProcessor:
                 job_info.action_name if job_info else "",
             )
 
-            # 按job_id取消单个job
+            # 先通知HostNode取消ROS2 action（如果存在）
+            host_node = HostNode.get_instance(0)
+            ros_cancel_success = False
+            if host_node:
+                ros_cancel_success = host_node.cancel_goal(job_id)
+                if ros_cancel_success:
+                    logger.info(f"[MessageProcessor] ROS2 cancel request sent for job {job_log}")
+                else:
+                    logger.debug(
+                        f"[MessageProcessor] Job {job_log} not in ROS2 goals " "(may be queued or already finished)"
+                    )
+
+            # 按job_id取消单个job（清理状态机）
             success = self.device_manager.cancel_job(job_id)
             if success:
-                # 通知HostNode取消
-                host_node = HostNode.get_instance(0)
-                if host_node:
-                    host_node.cancel_goal(job_id)
-                logger.info(f"[MessageProcessor] Job {job_log} cancelled")
+                logger.info(f"[MessageProcessor] Job {job_log} cancelled from queue/active list")
 
                 # 通知QueueProcessor有队列更新
                 if self.queue_processor:
                     self.queue_processor.notify_queue_update()
             else:
-                logger.warning(f"[MessageProcessor] Failed to cancel job {job_log}")
+                logger.warning(f"[MessageProcessor] Failed to cancel job {job_log} from queue")
 
         elif task_id:
-            # 按task_id取消所有相关job
+            # 先通知HostNode取消所有ROS2 actions
+            # 需要先获取所有相关job_ids
+            jobs_to_cancel = []
+            with self.device_manager.lock:
+                jobs_to_cancel = [
+                    job_info for job_info in self.device_manager.all_jobs.values() if job_info.task_id == task_id
+                ]
+
+            host_node = HostNode.get_instance(0)
+            if host_node and jobs_to_cancel:
+                ros_cancelled_count = 0
+                for job_info in jobs_to_cancel:
+                    if host_node.cancel_goal(job_info.job_id):
+                        ros_cancelled_count += 1
+                logger.info(
+                    f"[MessageProcessor] Sent ROS2 cancel for " f"{ros_cancelled_count}/{len(jobs_to_cancel)} jobs"
+                )
+
+            # 按task_id取消所有相关job（清理状态机）
             cancelled_job_ids = self.device_manager.cancel_jobs_by_task_id(task_id)
             if cancelled_job_ids:
-                # 通知HostNode取消所有job
-                host_node = HostNode.get_instance(0)
-                if host_node:
-                    for cancelled_job_id in cancelled_job_ids:
-                        host_node.cancel_goal(cancelled_job_id)
-
                 logger.info(f"[MessageProcessor] Cancelled {len(cancelled_job_ids)} jobs for task_id: {task_id}")
 
                 # 通知QueueProcessor有队列更新
@@ -913,7 +939,7 @@ class QueueProcessor:
         # 事件通知机制
         self.queue_update_event = threading.Event()
 
-        logger.info("[QueueProcessor] Initialized")
+        logger.trace("[QueueProcessor] Initialized")
 
     def set_websocket_client(self, websocket_client: "WebSocketClient"):
         """设置WebSocket客户端引用"""
@@ -928,7 +954,7 @@ class QueueProcessor:
         self.is_running = True
         self.thread = threading.Thread(target=self._run, daemon=True, name="QueueProcessor")
         self.thread.start()
-        logger.info("[QueueProcessor] Started")
+        logger.trace("[QueueProcessor] Started")
 
     def stop(self) -> None:
         """停止队列处理线程"""
@@ -939,7 +965,7 @@ class QueueProcessor:
 
     def _run(self):
         """运行队列处理主循环"""
-        logger.debug("[QueueProcessor] Queue processor started")
+        logger.trace("[QueueProcessor] Queue processor started")
 
         while self.is_running:
             try:
@@ -1056,11 +1082,19 @@ class QueueProcessor:
         """处理任务完成"""
         # 获取job信息用于日志
         job_info = self.device_manager.get_job_info(job_id)
+
+        # 如果job不存在，说明可能已被手动取消
+        if not job_info:
+            logger.debug(
+                f"[QueueProcessor] Job {job_id[:8]} not found in manager " "(may have been cancelled manually)"
+            )
+            return
+
         job_log = format_job_log(
             job_id,
-            job_info.task_id if job_info else "",
-            job_info.device_id if job_info else "",
-            job_info.action_name if job_info else "",
+            job_info.task_id,
+            job_info.device_id,
+            job_info.action_name,
         )
 
         logger.info(f"[QueueProcessor] Job {job_log} completed with status: {status}")
@@ -1141,7 +1175,6 @@ class WebSocketClient(BaseCommunicationClient):
         else:
             url = f"{scheme}://{parsed.netloc}/api/v1/ws/schedule"
 
-        logger.debug(f"[WebSocketClient] URL: {url}")
         return url
 
     def start(self) -> None:
@@ -1154,13 +1187,11 @@ class WebSocketClient(BaseCommunicationClient):
             logger.error("[WebSocketClient] WebSocket URL not configured")
             return
 
-        logger.info(f"[WebSocketClient] Starting connection to {self.websocket_url}")
-
         # 启动两个核心线程
         self.message_processor.start()
         self.queue_processor.start()
 
-        logger.info("[WebSocketClient] All threads started")
+        logger.trace("[WebSocketClient] All threads started")
 
     def stop(self) -> None:
         """停止WebSocket客户端"""
@@ -1169,6 +1200,18 @@ class WebSocketClient(BaseCommunicationClient):
 
         logger.info("[WebSocketClient] Stopping connection")
 
+        # 发送 normal_exit 消息
+        if self.is_connected():
+            try:
+                session_id = self.message_processor.session_id
+                message = {"action": "normal_exit", "data": {"session_id": session_id}}
+                self.message_processor.send_message(message)
+                logger.info(f"[WebSocketClient] Sent normal_exit message with session_id: {session_id}")
+                # 给一点时间让消息发送出去
+                time.sleep(1)
+            except Exception as e:
+                logger.warning(f"[WebSocketClient] Failed to send normal_exit message: {str(e)}")
+
         # 停止两个核心线程
         self.message_processor.stop()
         self.queue_processor.stop()
@@ -1268,3 +1311,19 @@ class WebSocketClient(BaseCommunicationClient):
             logger.info(f"[WebSocketClient] Job {job_log} cancelled successfully")
         else:
             logger.warning(f"[WebSocketClient] Failed to cancel job {job_log}")
+
+    def publish_host_ready(self) -> None:
+        """发布host_node ready信号"""
+        if self.is_disabled or not self.is_connected():
+            logger.debug("[WebSocketClient] Not connected, cannot publish host ready signal")
+            return
+
+        message = {
+            "action": "host_node_ready",
+            "data": {
+                "status": "ready",
+                "timestamp": time.time(),
+            },
+        }
+        self.message_processor.send_message(message)
+        logger.info("[WebSocketClient] Host node ready signal published")

unilabos/config/config.py

@@ -18,7 +18,11 @@ class BasicConfig:
     vis_2d_enable = False
     enable_resource_load = True
     communication_protocol = "websocket"
-    log_level: Literal['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = "DEBUG"  # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    startup_json_path = None  # 填写绝对路径
+    disable_browser = False  # 禁止浏览器自动打开
+    port = 8002  # 本地HTTP服务
+    # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    log_level: Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "DEBUG"
 
     @classmethod
     def auth_secret(cls):
@@ -36,18 +40,9 @@ class WSConfig:
     ping_interval = 30  # ping间隔（秒）
 
 
-# OSS上传配置
-class OSSUploadConfig:
-    api_host = ""
-    authorization = ""
-    init_endpoint = ""
-    complete_endpoint = ""
-    max_retries = 3
-
-
 # HTTP配置
 class HTTPConfig:
-    remote_addr = "http://127.0.0.1:48197/api/v1"
+    remote_addr = "https://uni-lab.bohrium.com/api/v1"
 
 
 # ROS配置
@@ -71,13 +66,14 @@ def _update_config_from_module(module):
                     if not attr.startswith("_"):
                         setattr(obj, attr, getattr(getattr(module, name), attr))
 
+
 def _update_config_from_env():
     prefix = "UNILABOS_"
     for env_key, env_value in os.environ.items():
         if not env_key.startswith(prefix):
             continue
         try:
-            key_path = env_key[len(prefix):]  # Remove UNILAB_ prefix
+            key_path = env_key[len(prefix) :]  # Remove UNILAB_ prefix
             class_field = key_path.upper().split("_", 1)
             if len(class_field) != 2:
                 logger.warning(f"[ENV] 环境变量格式不正确：{env_key}")

unilabos/device_comms/opcua_client/README.md

@@ -0,0 +1,19 @@
+# OPC UA 通用客户端
+
+本模块提供了一个通用的 OPC UA 客户端实现，可以通过外部配置（CSV文件）来定义节点，并通过JSON配置来执行工作流。
+
+## 特点
+
+- 支持通过 CSV 文件配置 OPC UA 节点（只需提供名称、类型和数据类型,支持节点为中文名，需指定NodeLanguage）
+- 自动查找服务器中的节点，无需知道确切的节点ID
+- 提供工作流机制
+- 支持通过 JSON 配置创建工作流
+
+## 使用方法
+
+step1: 准备opcua_nodes.csv文件
+step2: 编写opcua_workflow_example.json,以定义工作流。指定opcua_nodes.csv
+step3: 编写工作流对应action
+step4: 编写opcua_example.yaml注册表
+step5: 编写opcua_example.json组态图。指定opcua_workflow_example.json定义工作流文件
+

unilabos/device_comms/opcua_client/__init__.py

@@ -0,0 +1,9 @@
+from unilabos.device_comms.opcua_client.node.uniopcua import Variable, Method, Object, NodeType, DataType
+
+__all__ = [
+    'Variable',
+    'Method',
+    'Object',
+    'NodeType',
+    'DataType',
+] 

unilabos/device_comms/opcua_client/node/__init__.py

@@ -0,0 +1,10 @@
+from unilabos.device_comms.opcua_client.node.uniopcua import Variable, Method, Object, NodeType, DataType, Base
+
+__all__ = [
+    'Variable',
+    'Method',
+    'Object',
+    'NodeType',
+    'DataType',
+    'Base',
+] 

unilabos/device_comms/opcua_client/node/uniopcua.py

@@ -0,0 +1,180 @@
+# coding=utf-8
+from enum import Enum
+from abc import ABC, abstractmethod
+from typing import Tuple, Union, Optional, Any, List
+
+from opcua import Client, Node
+from opcua.ua import NodeId, NodeClass, VariantType
+
+
+class DataType(Enum):
+    BOOLEAN = VariantType.Boolean
+    SBYTE = VariantType.SByte
+    BYTE = VariantType.Byte
+    INT16 = VariantType.Int16
+    UINT16 = VariantType.UInt16
+    INT32 = VariantType.Int32
+    UINT32 = VariantType.UInt32
+    INT64 = VariantType.Int64
+    UINT64 = VariantType.UInt64
+    FLOAT = VariantType.Float
+    DOUBLE = VariantType.Double
+    STRING = VariantType.String
+    DATETIME = VariantType.DateTime
+    BYTESTRING = VariantType.ByteString
+
+
+class NodeType(Enum):
+    VARIABLE = NodeClass.Variable
+    OBJECT = NodeClass.Object
+    METHOD = NodeClass.Method
+    OBJECTTYPE = NodeClass.ObjectType
+    VARIABLETYPE = NodeClass.VariableType
+    REFERENCETYPE = NodeClass.ReferenceType
+    DATATYPE = NodeClass.DataType
+    VIEW = NodeClass.View
+
+
+class Base(ABC):
+    def __init__(self, client: Client, name: str, node_id: str, typ: NodeType, data_type: DataType):
+        self._node_id: str = node_id
+        self._client = client
+        self._name = name
+        self._type = typ
+        self._data_type = data_type
+        self._node: Optional[Node] = None
+        
+    def _get_node(self) -> Node:
+        if self._node is None:
+            try:
+                # 检查是否是NumericNodeId(ns=X;i=Y)格式
+                if "NumericNodeId" in self._node_id:
+                    # 从字符串中提取命名空间和标识符
+                    import re
+                    match = re.search(r'ns=(\d+);i=(\d+)', self._node_id)
+                    if match:
+                        ns = int(match.group(1))
+                        identifier = int(match.group(2))
+                        node_id = NodeId(identifier, ns)
+                        self._node = self._client.get_node(node_id)
+                    else:
+                        raise ValueError(f"无法解析节点ID: {self._node_id}")
+                else:
+                    # 直接使用节点ID字符串
+                    self._node = self._client.get_node(self._node_id)
+            except Exception as e:
+                print(f"获取节点失败: {self._node_id}, 错误: {e}")
+                raise
+        return self._node
+
+    @abstractmethod
+    def read(self) -> Tuple[Any, bool]:
+        """读取节点值，返回(值, 是否出错)"""
+        pass
+    
+    @abstractmethod
+    def write(self, value: Any) -> bool:
+        """写入节点值，返回是否出错"""
+        pass
+    
+    @property
+    def type(self) -> NodeType:
+        return self._type
+    
+    @property
+    def node_id(self) -> str:
+        return self._node_id
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+
+class Variable(Base):
+    def __init__(self, client: Client, name: str, node_id: str, data_type: DataType):
+        super().__init__(client, name, node_id, NodeType.VARIABLE, data_type)
+
+    def read(self) -> Tuple[Any, bool]:
+        try:
+            value = self._get_node().get_value()
+            return value, False
+        except Exception as e:
+            print(f"读取变量 {self._name} 失败: {e}")
+            return None, True
+
+    def write(self, value: Any) -> bool:
+        try:
+            self._get_node().set_value(value)
+            return False
+        except Exception as e:
+            print(f"写入变量 {self._name} 失败: {e}")
+            return True
+
+
+class Method(Base):
+    def __init__(self, client: Client, name: str, node_id: str, parent_node_id: str, data_type: DataType):
+        super().__init__(client, name, node_id, NodeType.METHOD, data_type)
+        self._parent_node_id = parent_node_id
+        self._parent_node = None
+        
+    def _get_parent_node(self) -> Node:
+        if self._parent_node is None:
+            try:
+                # 检查是否是NumericNodeId(ns=X;i=Y)格式
+                if "NumericNodeId" in self._parent_node_id:
+                    # 从字符串中提取命名空间和标识符
+                    import re
+                    match = re.search(r'ns=(\d+);i=(\d+)', self._parent_node_id)
+                    if match:
+                        ns = int(match.group(1))
+                        identifier = int(match.group(2))
+                        node_id = NodeId(identifier, ns)
+                        self._parent_node = self._client.get_node(node_id)
+                    else:
+                        raise ValueError(f"无法解析父节点ID: {self._parent_node_id}")
+                else:
+                    # 直接使用节点ID字符串
+                    self._parent_node = self._client.get_node(self._parent_node_id)
+            except Exception as e:
+                print(f"获取父节点失败: {self._parent_node_id}, 错误: {e}")
+                raise
+        return self._parent_node
+
+    def read(self) -> Tuple[Any, bool]:
+        """方法节点不支持读取操作"""
+        return None, True
+
+    def write(self, value: Any) -> bool:
+        """方法节点不支持写入操作"""
+        return True
+        
+    def call(self, *args) -> Tuple[Any, bool]:
+        """调用方法，返回(返回值, 是否出错)"""
+        try:
+            result = self._get_parent_node().call_method(self._get_node(), *args)
+            return result, False
+        except Exception as e:
+            print(f"调用方法 {self._name} 失败: {e}")
+            return None, True
+
+
+class Object(Base):
+    def __init__(self, client: Client, name: str, node_id: str):
+        super().__init__(client, name, node_id, NodeType.OBJECT, None)
+        
+    def read(self) -> Tuple[Any, bool]:
+        """对象节点不支持直接读取操作"""
+        return None, True
+
+    def write(self, value: Any) -> bool:
+        """对象节点不支持直接写入操作"""
+        return True
+    
+    def get_children(self) -> Tuple[List[Node], bool]:
+        """获取子节点列表，返回(子节点列表, 是否出错)"""
+        try:
+            children = self._get_node().get_children()
+            return children, False
+        except Exception as e:
+            print(f"获取对象 {self._name} 的子节点失败: {e}")
+            return [], True 

unilabos/device_comms/opcua_client/opcua_config.json

@@ -0,0 +1,98 @@
+{
+    "register_node_list_from_csv_path": {
+        "path": "simple_opcua_nodes.csv"
+    },
+    "create_flow": [
+        {
+            "name": "温度控制流程",
+            "action": [
+                {
+                    "name": "温度控制动作",
+                    "node_function_to_create": [
+                        {
+                            "func_name": "read_temperature",
+                            "node_name": "Temperature",
+                            "mode": "read"
+                        },
+                        {
+                            "func_name": "read_heating_status",
+                            "node_name": "HeatingStatus",
+                            "mode": "read"
+                        },
+                        {
+                            "func_name": "set_heating",
+                            "node_name": "HeatingEnabled",
+                            "mode": "write",
+                            "value": true
+                        }
+                    ],
+                    "create_init_function": {
+                        "func_name": "init_setpoint",
+                        "node_name": "Setpoint",
+                        "mode": "write",
+                        "value": 25.0
+                    },
+                    "create_start_function": {
+                        "func_name": "start_heating_control",
+                        "node_name": "HeatingEnabled",
+                        "mode": "write",
+                        "write_functions": [
+                            "set_heating"
+                        ],
+                        "condition_functions": [
+                            "read_temperature",
+                            "read_heating_status"
+                        ],
+                        "stop_condition_expression": "read_temperature >= 25.0 and read_heating_status"
+                    },
+                    "create_stop_function": {
+                        "func_name": "stop_heating",
+                        "node_name": "HeatingEnabled",
+                        "mode": "write",
+                        "value": false
+                    },
+                    "create_cleanup_function": null
+                }
+            ]
+        },
+        {
+            "name": "报警重置流程",
+            "action": [
+                {
+                    "name": "报警重置动作",
+                    "node_function_to_create": [
+                        {
+                            "func_name": "reset_alarm",
+                            "node_name": "ResetAlarm",
+                            "mode": "call",
+                            "value": []
+                        }
+                    ],
+                    "create_init_function": null,
+                    "create_start_function": {
+                        "func_name": "start_reset_alarm",
+                        "node_name": "ResetAlarm",
+                        "mode": "call",
+                        "write_functions": [],
+                        "condition_functions": [
+                            "reset_alarm"
+                        ],
+                        "stop_condition_expression": "True"
+                    },
+                    "create_stop_function": null,
+                    "create_cleanup_function": null
+                }
+            ]
+        },
+        {
+            "name": "完整控制流程",
+            "action": [
+                "温度控制流程",
+                "报警重置流程"
+            ]
+        }
+    ],
+    "execute_flow": [
+        "完整控制流程"
+    ]
+}

unilabos/device_comms/opcua_client/opcua_nodes_example.csv

@@ -0,0 +1,2 @@
+Name,EnglishName,NodeType,DataType,NodeLanguage
+中文名,EnglishName,VARIABLE,INT32,Chinese

unilabos/device_comms/opcua_client/opcua_workflow_example.json

@@ -0,0 +1,30 @@
+{
+    "register_node_list_from_csv_path": {
+        "path": "opcua_nodes_example.csv"
+    },
+    "create_flow": [
+        {
+            "name": "name",
+            "description": "description",
+            "parameters": ["parameter1", "parameter2"],
+            "action": [
+                {
+                    "init_function": {
+                        "func_name": "init_grab_params",
+                        "write_nodes": ["parameter1", "parameter2"]
+                    },
+                    "start_function": {
+                        "func_name": "start_grab",
+                        "write_nodes": {"parameter_start": true},
+                        "condition_nodes": ["parameter_condition"],
+                        "stop_condition_expression": "parameter_condition == True"
+                    },
+                    "stop_function": {
+                        "func_name": "stop_grab",
+                        "write_nodes": {"parameter_start": false}
+                    }
+                }
+            ]
+        }       
+    ]
+} 

unilabos/device_comms/opcua_client/server.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+OPC UA测试服务器
+用于测试OPC UA客户端功能，特别是temperature_control和valve_control工作流
+"""
+
+import sys
+import time
+import logging
+from opcua import Server, ua
+import threading
+
+# 设置日志
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class OpcUaTestServer:
+    """OPC UA测试服务器类"""
+    
+    def __init__(self, endpoint="opc.tcp://localhost:4840/freeopcua/server/"):
+        """
+        初始化OPC UA服务器
+        
+        Args:
+            endpoint: 服务器端点URL
+        """
+        self.server = Server()
+        self.server.set_endpoint(endpoint)
+        
+        # 设置服务器名称
+        self.server.set_server_name("UniLabOS OPC UA Test Server")
+        
+        # 设置服务器命名空间
+        self.idx = self.server.register_namespace("http://unilabos.com/opcua/test")
+        
+        # 获取Objects节点
+        self.objects = self.server.get_objects_node()
+        
+        # 创建设备对象
+        self.device = self.objects.add_object(self.idx, "TestDevice")
+        
+        # 存储所有节点的字典
+        self.nodes = {}
+        
+        # 初始化标志
+        self.running = False
+        
+        # 控制标志
+        self.simulation_active = True
+    
+    def add_variable(self, name, value, data_type=None):
+        """
+        添加变量节点
+        
+        Args:
+            name: 变量名称
+            value: 初始值
+            data_type: 数据类型 (可选)
+        """
+        if data_type is None:
+            var = self.device.add_variable(self.idx, name, value)
+        else:
+            var = self.device.add_variable(self.idx, name, value, data_type)
+        
+        # 设置变量可写
+        var.set_writable()
+        
+        # 存储节点
+        self.nodes[name] = var
+        logger.info(f"添加变量节点: {name}, 初始值: {value}")
+        return var
+    
+    def add_method(self, name, callback, inputs=None, outputs=None):
+        """
+        添加方法节点
+        
+        Args:
+            name: 方法名称
+            callback: 回调函数
+            inputs: 输入参数列表 [(name, type), ...]
+            outputs: 输出参数列表 [(name, type), ...]
+        """
+        if inputs is None:
+            inputs = []
+        if outputs is None:
+            outputs = []
+        
+        # 创建输入参数
+        input_args = []
+        for arg_name, arg_type in inputs:
+            input_args.append(ua.Argument())
+            input_args[-1].Name = arg_name
+            input_args[-1].DataType = arg_type
+            input_args[-1].ValueRank = -1
+        
+        # 创建输出参数
+        output_args = []
+        for arg_name, arg_type in outputs:
+            output_args.append(ua.Argument())
+            output_args[-1].Name = arg_name
+            output_args[-1].DataType = arg_type
+            output_args[-1].ValueRank = -1
+        
+        # 添加方法
+        method = self.device.add_method(
+            self.idx, 
+            name, 
+            callback, 
+            input_args, 
+            output_args
+        )
+        
+        # 存储节点
+        self.nodes[name] = method
+        logger.info(f"添加方法节点: {name}")
+        return method
+    
+    def start(self):
+        """启动服务器"""
+        if not self.running:
+            self.server.start()
+            self.running = True
+            logger.info("OPC UA服务器已启动")
+            
+            # 启动模拟线程
+            self.simulation_thread = threading.Thread(target=self.run_simulation)
+            self.simulation_thread.daemon = True
+            self.simulation_thread.start()
+    
+    def stop(self):
+        """停止服务器"""
+        if self.running:
+            self.simulation_active = False
+            if hasattr(self, 'simulation_thread'):
+                self.simulation_thread.join(timeout=2)
+            self.server.stop()
+            self.running = False
+            logger.info("OPC UA服务器已停止")
+    
+    def get_node(self, name):
+        """获取节点"""
+        if name in self.nodes:
+            return self.nodes[name]
+        return None
+    
+    def update_variable(self, name, value):
+        """更新变量值"""
+        if name in self.nodes:
+            self.nodes[name].set_value(value)
+            logger.debug(f"更新变量 {name} = {value}")
+            return True
+        logger.warning(f"变量 {name} 不存在")
+        return False
+    
+    def run_simulation(self):
+        """运行模拟线程"""
+        logger.info("启动模拟线程")
+        
+        temp = 20.0
+        valve_position = 0.0
+        flow_rate = 0.0
+        
+        while self.simulation_active and self.running:
+            try:
+                # 温度控制模拟
+                heating_enabled = self.get_node("HeatingEnabled").get_value()
+                setpoint = self.get_node("Setpoint").get_value()
+                
+                if heating_enabled:
+                    self.update_variable("HeatingStatus", True)
+                    if temp < setpoint:
+                        temp += 0.5  # 加快温度上升速度
+                    else:
+                        temp -= 0.1
+                else:
+                    self.update_variable("HeatingStatus", False)
+                    if temp > 20.0:
+                        temp -= 0.2
+                
+                # 更新温度
+                self.update_variable("Temperature", round(temp, 2))
+                
+                # 阀门控制模拟
+                valve_control = self.get_node("ValveControl").get_value()
+                valve_setpoint = self.get_node("ValveSetpoint").get_value()
+                
+                if valve_control:
+                    if valve_position < valve_setpoint:
+                        valve_position += 5.0  # 加快阀门开启速度
+                        if valve_position > valve_setpoint:
+                            valve_position = valve_setpoint
+                    else:
+                        valve_position -= 1.0
+                        if valve_position < 0:
+                            valve_position = 0
+                else:
+                    if valve_position > 0:
+                        valve_position -= 5.0
+                        if valve_position < 0:
+                            valve_position = 0
+                
+                # 更新阀门位置
+                self.update_variable("ValvePosition", round(valve_position, 2))
+                
+                # 流量模拟 - 与阀门位置成正比
+                flow_rate = valve_position * 0.2  # 简单线性关系
+                self.update_variable("FlowRate", round(flow_rate, 2))
+                
+                # 更新系统状态
+                status = []
+                if heating_enabled:
+                    status.append("Heating")
+                if valve_control:
+                    status.append("Valve_Open")
+                
+                if status:
+                    self.update_variable("SystemStatus", "_".join(status))
+                else:
+                    self.update_variable("SystemStatus", "Idle")
+                
+                # 每200毫秒更新一次
+                time.sleep(0.2)
+                
+            except Exception as e:
+                logger.error(f"模拟线程错误: {e}")
+                time.sleep(1)  # 出错时稍等一会再继续
+        
+        logger.info("模拟线程已停止")
+
+def reset_alarm_callback(parent, *args):
+    """重置报警的回调函数"""
+    logger.info("调用了重置报警方法")
+    return True
+
+def start_process_callback(parent, *args):
+    """启动流程的回调函数"""
+    process_id = args[0] if args else 0
+    logger.info(f"启动流程 ID: {process_id}")
+    return process_id
+
+def stop_process_callback(parent, *args):
+    """停止流程的回调函数"""
+    process_id = args[0] if args else 0
+    logger.info(f"停止流程 ID: {process_id}")
+    return True
+
+def main():
+    """主函数"""
+    try:
+        # 创建服务器
+        server = OpcUaTestServer()
+        
+        # 添加变量节点 - 温度控制相关
+        server.add_variable("Temperature", 20.0, ua.VariantType.Float)
+        server.add_variable("Setpoint", 22.0, ua.VariantType.Float)
+        server.add_variable("HeatingEnabled", False, ua.VariantType.Boolean)
+        server.add_variable("HeatingStatus", False, ua.VariantType.Boolean)
+        
+        # 添加变量节点 - 阀门控制相关
+        server.add_variable("ValvePosition", 0.0, ua.VariantType.Float)
+        server.add_variable("ValveSetpoint", 0.0, ua.VariantType.Float)
+        server.add_variable("ValveControl", False, ua.VariantType.Boolean)
+        server.add_variable("FlowRate", 0.0, ua.VariantType.Float)
+        
+        # 其他状态变量
+        server.add_variable("SystemStatus", "Idle", ua.VariantType.String)
+        
+        # 添加方法节点
+        server.add_method(
+            "ResetAlarm", 
+            reset_alarm_callback, 
+            [], 
+            [("Result", ua.VariantType.Boolean)]
+        )
+        
+        server.add_method(
+            "StartProcess", 
+            start_process_callback, 
+            [("ProcessId", ua.VariantType.Int32)], 
+            [("Result", ua.VariantType.Int32)]
+        )
+        
+        server.add_method(
+            "StopProcess", 
+            stop_process_callback, 
+            [("ProcessId", ua.VariantType.Int32)], 
+            [("Result", ua.VariantType.Boolean)]
+        )
+        
+        # 启动服务器
+        server.start()
+        logger.info("服务器已启动，按Ctrl+C停止")
+        
+        # 保持服务器运行
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            logger.info("收到键盘中断，正在停止服务器...")
+        
+        # 停止服务器
+        server.stop()
+        
+    except Exception as e:
+        logger.error(f"服务器错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main() 

unilabos/device_mesh/devices/dummy2_robot/config/default_kinematics.yaml

@@ -0,0 +1,25 @@
+dummy2_robot:
+  kinematics:
+    # DH parameters for Dummy2 6-DOF robot arm
+    # [theta, d, a, alpha] for each joint
+    joint_1: [0.0, 0.1, 0.0, 1.5708]      # Base rotation
+    joint_2: [0.0, 0.0, 0.2, 0.0]         # Shoulder
+    joint_3: [0.0, 0.0, 0.15, 0.0]        # Elbow  
+    joint_4: [0.0, 0.1, 0.0, 1.5708]      # Wrist roll
+    joint_5: [0.0, 0.0, 0.0, -1.5708]     # Wrist pitch
+    joint_6: [0.0, 0.06, 0.0, 0.0]        # Wrist yaw
+  
+  # Tool center point offset from last joint
+  tcp_offset:
+    x: 0.0
+    y: 0.0  
+    z: 0.04
+    
+  # Workspace limits
+  workspace:
+    x_min: -0.5
+    x_max: 0.5
+    y_min: -0.5
+    y_max: 0.5
+    z_min: 0.0
+    z_max: 0.6

unilabos/device_mesh/devices/dummy2_robot/config/dummy2.srdf

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--This does not replace URDF, and is not an extension of URDF.
+    This is a format for representing semantic information about the robot structure.
+    A URDF file must exist for this robot as well, where the joints and the links that are referenced are defined
+-->
+<robot name="dummy2">
+    <!--GROUPS: Representation of a set of joints and links. This can be useful for specifying DOF to plan for, defining arms, end effectors, etc-->
+    <!--LINKS: When a link is specified, the parent joint of that link (if it exists) is automatically included-->
+    <!--JOINTS: When a joint is specified, the child link of that joint (which will always exist) is automatically included-->
+    <!--CHAINS: When a chain is specified, all the links along the chain (including endpoints) are included in the group. Additionally, all the joints that are parents to included links are also included. This means that joints along the chain and the parent joint of the base link are included in the group-->
+    <!--SUBGROUPS: Groups can also be formed by referencing to already defined group names-->
+    <group name="dummy2_arm">
+        <joint name="virtual_joint"/>
+        <joint name="Joint1"/>
+        <joint name="Joint2"/>
+        <joint name="Joint3"/>
+        <joint name="Joint4"/>
+        <joint name="Joint5"/>
+        <joint name="Joint6"/>
+    </group>
+    <!--GROUP STATES: Purpose: Define a named state for a particular group, in terms of joint values. This is useful to define states like 'folded arms'-->
+    <group_state name="home" group="dummy2_arm">
+        <joint name="Joint1" value="0"/>
+        <joint name="Joint2" value="0"/>
+        <joint name="Joint3" value="0"/>
+        <joint name="Joint4" value="0"/>
+        <joint name="Joint5" value="0"/>
+        <joint name="Joint6" value="0"/>
+    </group_state>
+    <!--VIRTUAL JOINT: Purpose: this element defines a virtual joint between a robot link and an external frame of reference (considered fixed with respect to the robot)-->
+    <virtual_joint name="virtual_joint" type="fixed" parent_frame="world" child_link="base_link"/>
+    <!--DISABLE COLLISIONS: By default it is assumed that any link of the robot could potentially come into collision with any other link in the robot. This tag disables collision checking between a specified pair of links. -->
+    <disable_collisions link1="J1_1" link2="J2_1" reason="Adjacent"/>
+    <disable_collisions link1="J1_1" link2="J3_1" reason="Never"/>
+    <disable_collisions link1="J1_1" link2="J4_1" reason="Never"/>
+    <disable_collisions link1="J1_1" link2="base_link" reason="Adjacent"/>
+    <disable_collisions link1="J2_1" link2="J3_1" reason="Adjacent"/>
+    <disable_collisions link1="J3_1" link2="J4_1" reason="Adjacent"/>
+    <disable_collisions link1="J3_1" link2="J5_1" reason="Never"/>
+    <disable_collisions link1="J3_1" link2="J6_1" reason="Never"/>
+    <disable_collisions link1="J3_1" link2="base_link" reason="Never"/>
+    <disable_collisions link1="J4_1" link2="J5_1" reason="Adjacent"/>
+    <disable_collisions link1="J4_1" link2="J6_1" reason="Never"/>
+    <disable_collisions link1="J5_1" link2="J6_1" reason="Adjacent"/>
+</robot>

unilabos/device_mesh/devices/dummy2_robot/config/dummy2.trans

@@ -0,0 +1,70 @@
+<?xml version="1.0" ?>
+<robot name="dummy2" xmlns:xacro="http://www.ros.org/wiki/xacro" >
+
+<transmission name="Joint1_tran">
+  <type>transmission_interface/SimpleTransmission</type>
+  <joint name="Joint1">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+  </joint>
+  <actuator name="Joint1_actr">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+    <mechanicalReduction>1</mechanicalReduction>
+  </actuator>
+</transmission>
+
+<transmission name="Joint2_tran">
+  <type>transmission_interface/SimpleTransmission</type>
+  <joint name="Joint2">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+  </joint>
+  <actuator name="Joint2_actr">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+    <mechanicalReduction>1</mechanicalReduction>
+  </actuator>
+</transmission>
+
+<transmission name="Joint3_tran">
+  <type>transmission_interface/SimpleTransmission</type>
+  <joint name="Joint3">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+  </joint>
+  <actuator name="Joint3_actr">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+    <mechanicalReduction>1</mechanicalReduction>
+  </actuator>
+</transmission>
+
+<transmission name="Joint4_tran">
+  <type>transmission_interface/SimpleTransmission</type>
+  <joint name="Joint4">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+  </joint>
+  <actuator name="Joint4_actr">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+    <mechanicalReduction>1</mechanicalReduction>
+  </actuator>
+</transmission>
+
+<transmission name="Joint5_tran">
+  <type>transmission_interface/SimpleTransmission</type>
+  <joint name="Joint5">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+  </joint>
+  <actuator name="Joint5_actr">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+    <mechanicalReduction>1</mechanicalReduction>
+  </actuator>
+</transmission>
+
+<transmission name="Joint6_tran">
+  <type>transmission_interface/SimpleTransmission</type>
+  <joint name="Joint6">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+  </joint>
+  <actuator name="Joint6_actr">
+    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
+    <mechanicalReduction>1</mechanicalReduction>
+  </actuator>
+</transmission>
+
+</robot>

unilabos/device_mesh/devices/dummy2_robot/config/dummy2.urdf.xacro

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="dummy2">
+    <xacro:arg name="initial_positions_file" default="initial_positions.yaml" />
+
+    <!-- Import dummy2 urdf file -->
+    <xacro:include filename="$(find dummy2_description)/urdf/dummy2.xacro" />
+
+    <!-- Import control_xacro -->
+    <xacro:include filename="dummy2.ros2_control.xacro" />
+
+
+    <xacro:dummy2_ros2_control name="FakeSystem" initial_positions_file="$(arg initial_positions_file)"/>
+
+</robot>

unilabos/device_mesh/devices/dummy2_robot/config/dummy2_simulated_config.yaml

@@ -0,0 +1,73 @@
+###############################################
+# Modify all parameters related to servoing here
+###############################################
+# adapt to dummy2 by Muzhxiaowen, check out the details on bilibili.com
+
+use_gazebo: false # Whether the robot is started in a Gazebo simulation environment
+
+## Properties of incoming commands
+command_in_type: "unitless" # "unitless"> in the range [-1:1], as if from joystick. "speed_units"> cmds are in m/s and rad/s
+scale:
+  # Scale parameters are only used if command_in_type=="unitless"
+  linear:  0.4  # Max linear velocity. Unit is [m/s]. Only used for Cartesian commands.
+  rotational:  0.8 # Max angular velocity. Unit is [rad/s]. Only used for Cartesian commands.
+  # Max joint angular/linear velocity. Only used for joint commands on joint_command_in_topic.
+  joint: 0.5
+
+# Optionally override Servo's internal velocity scaling when near singularity or collision (0.0 = use internal velocity scaling)
+# override_velocity_scaling_factor = 0.0 # valid range [0.0:1.0]
+
+## Properties of outgoing commands
+publish_period: 0.034  # 1/Nominal publish rate [seconds]
+low_latency_mode: false  # Set this to true to publish as soon as an incoming Twist command is received (publish_period is ignored)
+
+# What type of topic does your robot driver expect?
+# Currently supported are std_msgs/Float64MultiArray or trajectory_msgs/JointTrajectory
+command_out_type: trajectory_msgs/JointTrajectory
+
+# What to publish? Can save some bandwidth as most robots only require positions or velocities
+publish_joint_positions: true
+publish_joint_velocities: true
+publish_joint_accelerations: false
+
+## Plugins for smoothing outgoing commands
+smoothing_filter_plugin_name: "online_signal_smoothing::ButterworthFilterPlugin"
+
+# If is_primary_planning_scene_monitor is set to true, the Servo server's PlanningScene advertises the /get_planning_scene service,
+# which other nodes can use as a source for information about the planning environment.
+# NOTE: If a different node in your system is responsible for the "primary" planning scene instance (e.g. the MoveGroup node),
+# then is_primary_planning_scene_monitor needs to be set to false.
+is_primary_planning_scene_monitor: true
+
+## MoveIt properties
+move_group_name:  dummy2_arm  # Often 'manipulator' or 'arm'
+planning_frame: base_link  # The MoveIt planning frame. Often 'base_link' or 'world'
+
+## Other frames
+ee_frame_name: J6_1 # The name of the end effector link, used to return the EE pose
+robot_link_command_frame:  base_link  # commands must be given in the frame of a robot link. Usually either the base or end effector
+
+## Stopping behaviour
+incoming_command_timeout:  0.1  # Stop servoing if X seconds elapse without a new command
+# If 0, republish commands forever even if the robot is stationary. Otherwise, specify num. to publish.
+# Important because ROS may drop some messages and we need the robot to halt reliably.
+num_outgoing_halt_msgs_to_publish: 4
+
+## Configure handling of singularities and joint limits
+lower_singularity_threshold:  170.0  # Start decelerating when the condition number hits this (close to singularity)
+hard_stop_singularity_threshold: 3000.0 # Stop when the condition number hits this
+joint_limit_margin: 0.1 # added as a buffer to joint limits [radians]. If moving quickly, make this larger.
+leaving_singularity_threshold_multiplier: 2.0 # Multiply the hard stop limit by this when leaving singularity (see https://github.com/ros-planning/moveit2/pull/620)
+
+## Topic names
+cartesian_command_in_topic: ~/delta_twist_cmds  # Topic for incoming Cartesian twist commands
+joint_command_in_topic: ~/delta_joint_cmds # Topic for incoming joint angle commands
+joint_topic: /joint_states
+status_topic: ~/status # Publish status to this topic
+command_out_topic: /dummy2_arm_controller/joint_trajectory # Publish outgoing commands here
+
+## Collision checking for the entire robot body
+check_collisions: true # Check collisions?
+collision_check_rate: 10.0 # [Hz] Collision-checking can easily bog down a CPU if done too often.
+self_collision_proximity_threshold: 0.001 # Start decelerating when a self-collision is this far [m]
+scene_collision_proximity_threshold: 0.002 # Start decelerating when a scene collision is this far [m]

unilabos/device_mesh/devices/dummy2_robot/config/initial_positions.yaml

@@ -0,0 +1,9 @@
+# Default initial positions for dummy2's ros2_control fake system
+
+initial_positions:
+  Joint1: 0
+  Joint2: 0
+  Joint3: 0
+  Joint4: 0
+  Joint5: 0
+  Joint6: 0

unilabos/device_mesh/devices/dummy2_robot/config/joint_limits.yaml

@@ -0,0 +1,40 @@
+# joint_limits.yaml allows the dynamics properties specified in the URDF to be overwritten or augmented as needed
+
+# For beginners, we downscale velocity and acceleration limits.
+# You can always specify higher scaling factors (<= 1.0) in your motion requests.  # Increase the values below to 1.0 to always move at maximum speed.
+default_velocity_scaling_factor: 0.1
+default_acceleration_scaling_factor: 0.1
+
+# Specific joint properties can be changed with the keys [max_position, min_position, max_velocity, max_acceleration]
+# Joint limits can be turned off with [has_velocity_limits, has_acceleration_limits]
+joint_limits:
+  joint_1:
+    has_velocity_limits: true
+    max_velocity: 2.0
+    has_acceleration_limits: false
+    max_acceleration: 0
+  joint_2:
+    has_velocity_limits: true
+    max_velocity: 2.0
+    has_acceleration_limits: false
+    max_acceleration: 0
+  joint_3:
+    has_velocity_limits: true
+    max_velocity: 2.0
+    has_acceleration_limits: false
+    max_acceleration: 0
+  joint_4:
+    has_velocity_limits: true
+    max_velocity: 2.0
+    has_acceleration_limits: false
+    max_acceleration: 0
+  joint_5:
+    has_velocity_limits: true
+    max_velocity: 2.0
+    has_acceleration_limits: false
+    max_acceleration: 0
+  joint_6:
+    has_velocity_limits: true
+    max_velocity: 2.0
+    has_acceleration_limits: false
+    max_acceleration: 0

unilabos/device_mesh/devices/dummy2_robot/config/kinematics.yaml

@@ -0,0 +1,4 @@
+dummy2_arm:
+  kinematics_solver: kdl_kinematics_plugin/KDLKinematicsPlugin
+  kinematics_solver_search_resolution: 0.0050000000000000001
+  kinematics_solver_timeout: 0.5

unilabos/device_mesh/devices/dummy2_robot/config/macro.ros2_control.xacro

@@ -0,0 +1,60 @@
+<?xml version="1.0"?>
+<robot xmlns:xacro="http://www.ros.org/wiki/xacro">
+    <xacro:macro name="dummy2_robot_ros2_control" params="device_name mesh_path">
+        <xacro:property name="initial_positions" value="${load_yaml(mesh_path + '/devices/dummy2_robot/config/initial_positions.yaml')['initial_positions']}"/>
+
+        <ros2_control name="${device_name}dummy2" type="system">
+            <hardware>
+                <!-- By default, set up controllers for simulation. This won't work on real hardware -->
+                <plugin>mock_components/GenericSystem</plugin>
+            </hardware>
+
+                <!-- <plugin>mock_components/GenericSystem</plugin> -->
+            <joint name="${device_name}Joint1">
+                <command_interface name="position"/>
+                <state_interface name="position">
+                  <param name="initial_value">${initial_positions['Joint1']}</param>
+                </state_interface>
+                <state_interface name="velocity"/>
+            </joint>
+            <joint name="${device_name}Joint2">
+                <command_interface name="position"/>
+                <state_interface name="position">
+                  <param name="initial_value">${initial_positions['Joint2']}</param>
+                </state_interface>
+                <state_interface name="velocity"/>
+            </joint>
+            <joint name="${device_name}Joint3">
+                <command_interface name="position"/>
+                <state_interface name="position">
+                  <param name="initial_value">${initial_positions['Joint3']}</param>
+                </state_interface>
+                <state_interface name="velocity"/>
+            </joint>
+            <joint name="${device_name}Joint4">
+                <command_interface name="position"/>
+                <state_interface name="position">
+                  <param name="initial_value">${initial_positions['Joint4']}</param>
+                </state_interface>
+                <state_interface name="velocity"/>
+            </joint>
+            <joint name="${device_name}Joint5">
+                <command_interface name="position"/>
+                <state_interface name="position">
+                  <param name="initial_value">${initial_positions['Joint5']}</param>
+                </state_interface>
+                <state_interface name="velocity"/>
+            </joint>
+            <joint name="${device_name}Joint6">
+                <command_interface name="position"/>
+                <state_interface name="position">
+                  <param name="initial_value">${initial_positions['Joint6']}</param>
+                </state_interface>
+                <state_interface name="velocity"/>
+            </joint>
+
+
+        </ros2_control>
+    </xacro:macro>
+
+</robot>

unilabos/device_mesh/devices/dummy2_robot/config/macro.srdf.xacro

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<robot xmlns:xacro="http://www.ros.org/wiki/xacro">
+    <xacro:macro name="dummy2_robot_srdf" params="device_name">
+
+        <!--GROUPS: Representation of a set of joints and links. This can be useful for specifying DOF to plan for, defining arms, end effectors, etc-->
+        <!--LINKS: When a link is specified, the parent joint of that link (if it exists) is automatically included-->
+        <!--JOINTS: When a joint is specified, the child link of that joint (which will always exist) is automatically included-->
+        <!--CHAINS: When a chain is specified, all the links along the chain (including endpoints) are included in the group. Additionally, all the joints that are parents to included links are also included. This means that joints along the chain and the parent joint of the base link are included in the group-->
+        <!--SUBGROUPS: Groups can also be formed by referencing to already defined group names
+            This is a format for representing semantic information about the robot structure.
+            A URDF file must exist for this robot as well, where the joints and the links that are referenced are defined
+        -->
+            <group name="${device_name}dummy2_arm">
+                <joint name="${device_name}virtual_joint"/>
+                <joint name="${device_name}Joint1"/>
+                <joint name="${device_name}Joint2"/>
+                <joint name="${device_name}Joint3"/>
+                <joint name="${device_name}Joint4"/>
+                <joint name="${device_name}Joint5"/>
+                <joint name="${device_name}Joint6"/>
+            </group>
+            <!--GROUP STATES: Purpose: Define a named state for a particular group, in terms of joint values. This is useful to define states like 'folded arms'-->
+            <group_state name="home" group="${device_name}dummy2_arm">
+                <joint name="${device_name}Joint1" value="0"/>
+                <joint name="${device_name}Joint2" value="0"/>
+                <joint name="${device_name}Joint3" value="0"/>
+                <joint name="${device_name}Joint4" value="0"/>
+                <joint name="${device_name}Joint5" value="0"/>
+                <joint name="${device_name}Joint6" value="0"/>
+            </group_state>
+            <!--VIRTUAL JOINT: Purpose: this element defines a virtual joint between a robot link and an external frame of reference (considered fixed with respect to the robot)-->
+            <virtual_joint name="${device_name}virtual_joint" type="fixed" parent_frame="world" child_link="${device_name}base_link"/>
+            <!--DISABLE COLLISIONS: By default it is assumed that any link of the robot could potentially come into collision with any other link in the robot. This tag disables collision checking between a specified pair of links. -->
+            <disable_collisions link1="${device_name}J1_1" link2="${device_name}J2_1" reason="Adjacent"/>
+            <disable_collisions link1="${device_name}J1_1" link2="${device_name}J3_1" reason="Never"/>
+            <disable_collisions link1="${device_name}J1_1" link2="${device_name}J4_1" reason="Never"/>
+            <disable_collisions link1="${device_name}J1_1" link2="${device_name}base_link" reason="Adjacent"/>
+            <disable_collisions link1="${device_name}J2_1" link2="${device_name}J3_1" reason="Adjacent"/>
+            <disable_collisions link1="${device_name}J3_1" link2="${device_name}J4_1" reason="Adjacent"/>
+            <disable_collisions link1="${device_name}J3_1" link2="${device_name}J5_1" reason="Never"/>
+            <disable_collisions link1="${device_name}J3_1" link2="${device_name}J6_1" reason="Never"/>
+            <disable_collisions link1="${device_name}J3_1" link2="${device_name}base_link" reason="Never"/>
+            <disable_collisions link1="${device_name}J4_1" link2="${device_name}J5_1" reason="Adjacent"/>
+            <disable_collisions link1="${device_name}J4_1" link2="${device_name}J6_1" reason="Never"/>
+            <disable_collisions link1="${device_name}J5_1" link2="${device_name}J6_1" reason="Adjacent"/>
+
+    </xacro:macro>
+
+</robot>

unilabos/device_mesh/devices/dummy2_robot/config/materials.xacro

@@ -0,0 +1,8 @@
+<?xml version="1.0" ?>
+<robot name="dummy2" xmlns:xacro="http://www.ros.org/wiki/xacro" >
+
+<material name="silver">
+  <color rgba="0.700 0.700 0.700 1.000"/>
+</material>
+
+</robot>

unilabos/device_mesh/devices/dummy2_robot/config/move_group.json

@@ -0,0 +1,14 @@
+{
+    "arm": {
+        "joint_names": [
+            "joint_1",
+            "joint_2",
+            "joint_3",
+            "joint_4",
+            "joint_5",
+            "joint_6"
+        ],
+        "base_link_name": "base_link",
+        "end_effector_name": "J6_1"
+    }
+}

unilabos/device_mesh/devices/dummy2_robot/config/moveit.rviz

@@ -0,0 +1,51 @@
+Panels:
+  - Class: rviz_common/Displays
+    Name: Displays
+    Property Tree Widget:
+      Expanded:
+        - /MotionPlanning1
+  - Class: rviz_common/Help
+    Name: Help
+  - Class: rviz_common/Views
+    Name: Views
+Visualization Manager:
+  Displays:
+    - Class: rviz_default_plugins/Grid
+      Name: Grid
+      Value: true
+    - Class: moveit_rviz_plugin/MotionPlanning
+      Name: MotionPlanning
+      Planned Path:
+        Loop Animation: true
+        State Display Time: 0.05 s
+        Trajectory Topic: display_planned_path
+      Planning Scene Topic: monitored_planning_scene
+      Robot Description: robot_description
+      Scene Geometry:
+        Scene Alpha: 1
+      Scene Robot:
+        Robot Alpha: 0.5
+      Value: true
+  Global Options:
+    Fixed Frame: base_link
+  Tools:
+    - Class: rviz_default_plugins/Interact
+    - Class: rviz_default_plugins/MoveCamera
+    - Class: rviz_default_plugins/Select
+  Value: true
+  Views:
+    Current:
+      Class: rviz_default_plugins/Orbit
+      Distance: 2.0
+      Focal Point:
+        X: -0.1
+        Y: 0.25
+        Z: 0.30
+      Name: Current View
+      Pitch: 0.5
+      Target Frame: base_link
+      Yaw: -0.623
+Window Geometry:
+  Height: 975
+  QMainWindow State: 000000ff00000000fd0000000100000000000002b400000375fc0200000005fb00000044004d006f00740069006f006e0050006c0061006e006e0069006e00670020002d0020005400720061006a006500630074006f0072007900200053006c00690064006500720000000000ffffffff0000004100fffffffb000000100044006900730070006c006100790073010000003d00000123000000c900fffffffb0000001c004d006f00740069006f006e0050006c0061006e006e0069006e00670100000166000001910000018800fffffffb0000000800480065006c0070000000029a0000006e0000006e00fffffffb0000000a0056006900650077007301000002fd000000b5000000a400ffffff000001f60000037500000004000000040000000800000008fc0000000100000002000000010000000a0054006f006f006c00730100000000ffffffff0000000000000000
+  Width: 1200

unilabos/device_mesh/devices/dummy2_robot/config/moveit_controllers.yaml

@@ -0,0 +1,21 @@
+# MoveIt uses this configuration for controller management
+
+moveit_controller_manager: moveit_simple_controller_manager/MoveItSimpleControllerManager
+
+moveit_simple_controller_manager:
+  controller_names:
+    - dummy2_arm_controller
+
+  dummy2_arm_controller:
+    type: FollowJointTrajectory
+    action_ns: follow_joint_trajectory
+    default: true
+    joints:
+      - Joint1
+      - Joint2
+      - Joint3
+      - Joint4
+      - Joint5
+      - Joint6
+    action_ns: follow_joint_trajectory
+    default: true

unilabos/device_mesh/devices/dummy2_robot/config/physical_parameters.yaml

@@ -0,0 +1,39 @@
+dummy2_robot:
+  # Physical properties for each link
+  link_masses:
+    base_link: 5.0
+    link_1: 3.0
+    link_2: 2.5
+    link_3: 2.0
+    link_4: 1.5
+    link_5: 1.0
+    link_6: 0.5
+  
+  # Center of mass for each link (relative to joint frame)
+  link_com:
+    base_link: [0.0, 0.0, 0.05]
+    link_1: [0.0, 0.0, 0.05]
+    link_2: [0.1, 0.0, 0.0]
+    link_3: [0.08, 0.0, 0.0]
+    link_4: [0.0, 0.0, 0.05]
+    link_5: [0.0, 0.0, 0.03]
+    link_6: [0.0, 0.0, 0.02]
+  
+  # Moment of inertia matrices
+  link_inertias:
+    base_link: [0.02, 0.0, 0.0, 0.02, 0.0, 0.02]
+    link_1: [0.01, 0.0, 0.0, 0.01, 0.0, 0.01]
+    link_2: [0.008, 0.0, 0.0, 0.008, 0.0, 0.008]
+    link_3: [0.006, 0.0, 0.0, 0.006, 0.0, 0.006]
+    link_4: [0.004, 0.0, 0.0, 0.004, 0.0, 0.004]
+    link_5: [0.002, 0.0, 0.0, 0.002, 0.0, 0.002]
+    link_6: [0.001, 0.0, 0.0, 0.001, 0.0, 0.001]
+  
+  # Motor specifications
+  motor_specs:
+    joint_1: { max_torque: 150.0, max_speed: 2.0, gear_ratio: 100 }
+    joint_2: { max_torque: 150.0, max_speed: 2.0, gear_ratio: 100 }
+    joint_3: { max_torque: 150.0, max_speed: 2.0, gear_ratio: 100 }
+    joint_4: { max_torque: 50.0, max_speed: 2.0, gear_ratio: 50 }
+    joint_5: { max_torque: 50.0, max_speed: 2.0, gear_ratio: 50 }
+    joint_6: { max_torque: 25.0, max_speed: 2.0, gear_ratio: 25 }

unilabos/device_mesh/devices/dummy2_robot/config/pilz_cartesian_limits.yaml

@@ -0,0 +1,6 @@
+# Limits for the Pilz planner
+cartesian_limits:
+  max_trans_vel: 1.0
+  max_trans_acc: 2.25
+  max_trans_dec: -5.0
+  max_rot_vel: 1.57

unilabos/device_mesh/devices/dummy2_robot/config/ros2_controllers.yaml

@@ -0,0 +1,26 @@
+# This config file is used by ros2_control
+controller_manager:
+  ros__parameters:
+    update_rate: 100  # Hz
+
+    dummy2_arm_controller:
+      type: joint_trajectory_controller/JointTrajectoryController
+
+
+    joint_state_broadcaster:
+      type: joint_state_broadcaster/JointStateBroadcaster
+
+dummy2_arm_controller:
+  ros__parameters:
+    joints:
+      - Joint1
+      - Joint2
+      - Joint3
+      - Joint4
+      - Joint5
+      - Joint6
+    command_interfaces:
+      - position
+    state_interfaces:
+      - position
+      - velocity

unilabos/device_mesh/devices/dummy2_robot/config/visual_parameters.yaml

@@ -0,0 +1,35 @@
+dummy2_robot:
+  # Visual appearance settings
+  materials:
+    base_material:
+      color: [0.8, 0.8, 0.8, 1.0]  # Light gray
+      metallic: 0.1
+      roughness: 0.3
+    
+    link_material:
+      color: [0.2, 0.2, 0.8, 1.0]  # Blue
+      metallic: 0.3
+      roughness: 0.2
+    
+    joint_material:
+      color: [0.6, 0.6, 0.6, 1.0]  # Dark gray
+      metallic: 0.5
+      roughness: 0.1
+    
+    camera_material:
+      color: [0.1, 0.1, 0.1, 1.0]  # Black
+      metallic: 0.0
+      roughness: 0.8
+  
+  # Mesh scaling factors
+  mesh_scale: [0.001, 0.001, 0.001]  # Convert mm to m
+  
+  # Collision geometry simplification
+  collision_geometries:
+    base_link: "cylinder"  # radius: 0.08, height: 0.1
+    link_1: "cylinder"     # radius: 0.05, height: 0.15
+    link_2: "box"          # size: [0.2, 0.08, 0.08]
+    link_3: "box"          # size: [0.15, 0.06, 0.06]
+    link_4: "cylinder"     # radius: 0.03, height: 0.1
+    link_5: "cylinder"     # radius: 0.025, height: 0.06
+    link_6: "cylinder"     # radius: 0.02, height: 0.04

unilabos/device_mesh/devices/dummy2_robot/dummy2.xacro

@@ -0,0 +1,237 @@
+<?xml version="1.0" ?>
+<robot name="dummy2" xmlns:xacro="http://www.ros.org/wiki/xacro">
+
+<xacro:include filename="$(find dummy2_description)/urdf/materials.xacro" />
+<xacro:include filename="$(find dummy2_description)/urdf/dummy2.trans" />
+<xacro:include filename="$(find dummy2_description)/urdf/dummy2.gazebo" />
+<link name="world" />
+<joint name="world_joint" type="fixed">
+  <parent link="world" />
+  <child link = "base_link" />
+  <origin xyz="0.0 0.0 0.0" rpy="0.0 0.0 0.0" />
+</joint>
+
+<link name="base_link">
+  <inertial>
+    <origin xyz="0.00010022425916431473 -6.186605493937309e-05 0.05493640543484716" rpy="0 0 0"/>
+    <mass value="1.2152141810431654"/>
+    <inertia ixx="0.002105" iyy="0.002245" izz="0.002436" ixy="-0.0" iyz="-1.1e-05" ixz="0.0"/>
+  </inertial>
+  <visual>
+    <origin xyz="0 0 0" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/base_link.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="0 0 0" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/base_link.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="J1_1">
+  <inertial>
+    <origin xyz="-0.00617659688932347 0.007029599744830012 0.012866826083045027" rpy="0 0 0"/>
+    <mass value="0.1332774369186824"/>
+    <inertia ixx="6e-05" iyy="5e-05" izz="8.8e-05" ixy="2.1e-05" iyz="-1.4e-05" ixz="8e-06"/>
+  </inertial>
+  <visual>
+    <origin xyz="-0.0001 0.000289 -0.097579" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J1_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="-0.0001 0.000289 -0.097579" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J1_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="J2_1">
+  <inertial>
+    <origin xyz="0.019335709221765855 0.0019392793940843159 0.07795928103332703" rpy="0 0 0"/>
+    <mass value="1.9268013917303417"/>
+    <inertia ixx="0.006165" iyy="0.006538" izz="0.00118" ixy="-3e-06" iyz="4.7e-05" ixz="0.0007"/>
+  </inertial>
+  <visual>
+    <origin xyz="0.011539 -0.034188 -0.12478" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J2_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="0.011539 -0.034188 -0.12478" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J2_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="J3_1">
+  <inertial>
+    <origin xyz="-0.010672101243726572 -0.02723871972304964 0.04876701375652198" rpy="0 0 0"/>
+    <mass value="0.30531962155452225"/>
+    <inertia ixx="0.00029" iyy="0.000238" izz="0.000191" ixy="-1.3e-05" iyz="4.1e-05" ixz="3e-05"/>
+  </inertial>
+  <visual>
+    <origin xyz="-0.023811 -0.034188 -0.28278" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J3_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="-0.023811 -0.034188 -0.28278" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J3_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="J4_1">
+  <inertial>
+    <origin xyz="-0.005237398377441591 0.06002028183461833 0.0005891767740203724" rpy="0 0 0"/>
+    <mass value="0.14051172121899885"/>
+    <inertia ixx="0.000245" iyy="7.9e-05" izz="0.00027" ixy="1.6e-05" iyz="-2e-06" ixz="1e-06"/>
+  </inertial>
+  <visual>
+    <origin xyz="-0.010649 -0.038288 -0.345246" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J4_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="-0.010649 -0.038288 -0.345246" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J4_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="J5_1">
+  <inertial>
+    <origin xyz="-0.014389813882964664 0.07305218143664277 -0.0009243405950149497" rpy="0 0 0"/>
+    <mass value="0.7783315754227634"/>
+    <inertia ixx="0.000879" iyy="0.000339" izz="0.000964" ixy="0.000146" iyz="1e-06" ixz="-5e-06"/>
+  </inertial>
+  <visual>
+    <origin xyz="-0.031949 -0.148289 -0.345246" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J5_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="-0.031949 -0.148289 -0.345246" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J5_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="J6_1">
+  <inertial>
+    <origin xyz="3.967160300787087e-07 0.0004995066702210837 1.4402781733924286e-07" rpy="0 0 0"/>
+    <mass value="0.0020561527568204153"/>
+    <inertia ixx="0.0" iyy="0.0" izz="0.0" ixy="0.0" iyz="0.0" ixz="0.0"/>
+  </inertial>
+  <visual>
+    <origin xyz="-0.012127 -0.267789 -0.344021" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J6_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="-0.012127 -0.267789 -0.344021" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/J6_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<link name="camera">
+  <inertial>
+    <origin xyz="-0.0006059984983273845 0.0005864706438700462 0.04601775357664567" rpy="0 0 0"/>
+    <mass value="0.21961029019655884"/>
+    <inertia ixx="2.9e-05" iyy="0.000206" izz="0.000198" ixy="-0.0" iyz="2e-06" ixz="-0.0"/>
+  </inertial>
+  <visual>
+    <origin xyz="-0.012661 -0.239774 -0.37985" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/camera_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+    <material name="silver"/>
+  </visual>
+  <collision>
+    <origin xyz="-0.012661 -0.239774 -0.37985" rpy="0 0 0"/>
+    <geometry>
+      <mesh filename="file://$(find dummy2_description)/meshes/camera_1.stl" scale="0.001 0.001 0.001"/>
+    </geometry>
+  </collision>
+</link>
+
+<joint name="Joint1" type="revolute">
+  <origin xyz="0.0001 -0.000289 0.097579" rpy="0 0 0"/>
+  <parent link="base_link"/>
+  <child link="J1_1"/>
+  <axis xyz="-0.0 -0.0 1.0"/>
+  <limit upper="3.054326" lower="-3.054326" effort="100" velocity="100"/>
+</joint>
+
+<joint name="Joint2" type="revolute">
+  <origin xyz="-0.011639 0.034477 0.027201" rpy="0 0 0"/>
+  <parent link="J1_1"/>
+  <child link="J2_1"/>
+  <axis xyz="1.0 0.0 -0.0"/>
+  <limit upper="1.308997" lower="-2.007129" effort="100" velocity="100"/>
+</joint>
+
+<joint name="Joint3" type="revolute">
+  <origin xyz="0.03535 0.0 0.158" rpy="0 0 0"/>
+  <parent link="J2_1"/>
+  <child link="J3_1"/>
+  <axis xyz="-1.0 0.0 -0.0"/>
+  <limit upper="1.570796" lower="-1.047198" effort="100" velocity="100"/>
+</joint>
+
+<joint name="Joint4" type="revolute">
+  <origin xyz="-0.013162 0.0041 0.062466" rpy="0 0 0"/>
+  <parent link="J3_1"/>
+  <child link="J4_1"/>
+  <axis xyz="0.0 1.0 -0.0"/>
+  <limit upper="3.141593" lower="-3.141593" effort="100" velocity="100"/>
+</joint>
+
+<joint name="Joint5" type="revolute">
+  <origin xyz="0.0213 0.110001 0.0" rpy="0 0 0"/>
+  <parent link="J4_1"/>
+  <child link="J5_1"/>
+  <axis xyz="-1.0 -0.0 -0.0"/>
+  <limit upper="2.094395" lower="-1.919862" effort="100" velocity="100"/>
+</joint>
+
+<joint name="Joint6" type="continuous">
+  <origin xyz="-0.019822 0.1195 -0.001225" rpy="0 0 0"/>
+  <parent link="J5_1"/>
+  <child link="J6_1"/>
+  <axis xyz="0.0 -1.0 0.0"/>
+</joint>
+
+<joint name="camera" type="fixed">
+  <origin xyz="-0.019988 0.091197 0.024883" rpy="0 0 0"/>
+  <parent link="J5_1"/>
+  <child link="camera"/>
+  <axis xyz="1.0 -0.0 0.0"/>
+  <limit upper="0.0" lower="0.0" effort="100" velocity="100"/>
+</joint>
+
+</robot>

unilabos/device_mesh/devices/dummy2_robot/joint_limit.yaml

@@ -0,0 +1,37 @@
+joint_limits:
+
+  joint_1:
+    effort: 150
+    velocity: 2.0
+    lower: !degrees  -180
+    upper: !degrees  180
+
+  joint_2:
+    effort: 150
+    velocity: 2.0
+    lower: !degrees  -90
+    upper: !degrees  90
+
+  joint_3:
+    effort: 150
+    velocity: 2.0
+    lower: !degrees  -90
+    upper: !degrees  90
+
+  joint_4:
+    effort: 50
+    velocity: 2.0
+    lower: !degrees  -180
+    upper: !degrees  180
+
+  joint_5:
+    effort: 50
+    velocity: 2.0
+    lower: !degrees  -90
+    upper: !degrees  90
+
+  joint_6:
+    effort: 25
+    velocity: 2.0
+    lower: !degrees  -180
+    upper: !degrees  180

unilabos/device_mesh/devices/dummy2_robot/macro_device.xacro

@@ -0,0 +1,249 @@
+<?xml version="1.0" ?>
+<robot name="dummy2" xmlns:xacro="http://www.ros.org/wiki/xacro">
+
+
+  <xacro:macro name="dummy2_robot" params="mesh_path:='' parent_link:='' station_name:='' device_name:='' x:=0 y:=0 z:=0 rx:=0 ry:=0 r:=0">
+
+    <xacro:include filename="${mesh_path}/devices/dummy2_robot/config/materials.xacro" />
+    <xacro:include filename="${mesh_path}/devices/dummy2_robot/config/dummy2.trans" />
+
+    <joint name="${station_name}${device_name}base_link_joint" type="fixed">
+      <origin xyz="${x} ${y} ${z}" rpy="${rx} ${ry} ${r}" />
+      <parent link="${parent_link}"/>
+      <child link="${station_name}${device_name}device_link"/>
+      <axis xyz="0 0 0"/>
+    </joint>
+
+    <link name="${station_name}${device_name}device_link"/>
+    <joint name="${station_name}${device_name}device_link_joint" type="fixed">
+      <origin xyz="0 0 0" rpy="0 0 0" />
+      <parent link="${station_name}${device_name}device_link"/>
+      <child link="${station_name}${device_name}base_link"/>
+      <axis xyz="0 0 0"/>
+    </joint>
+
+    <link name="${station_name}${device_name}base_link">
+      <inertial>
+        <origin xyz="0.00010022425916431473 -6.186605493937309e-05 0.05493640543484716" rpy="0 0 0"/>
+        <mass value="1.2152141810431654"/>
+        <inertia ixx="0.002105" iyy="0.002245" izz="0.002436" ixy="-0.0" iyz="-1.1e-05" ixz="0.0"/>
+      </inertial>
+      <visual>
+        <origin xyz="0 0 0" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/base_link.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="0 0 0" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/base_link.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}J1_1">
+      <inertial>
+        <origin xyz="-0.00617659688932347 0.007029599744830012 0.012866826083045027" rpy="0 0 0"/>
+        <mass value="0.1332774369186824"/>
+        <inertia ixx="6e-05" iyy="5e-05" izz="8.8e-05" ixy="2.1e-05" iyz="-1.4e-05" ixz="8e-06"/>
+      </inertial>
+      <visual>
+        <origin xyz="-0.0001 0.000289 -0.097579" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J1_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="-0.0001 0.000289 -0.097579" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J1_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}J2_1">
+      <inertial>
+        <origin xyz="0.019335709221765855 0.0019392793940843159 0.07795928103332703" rpy="0 0 0"/>
+        <mass value="1.9268013917303417"/>
+        <inertia ixx="0.006165" iyy="0.006538" izz="0.00118" ixy="-3e-06" iyz="4.7e-05" ixz="0.0007"/>
+      </inertial>
+      <visual>
+        <origin xyz="0.011539 -0.034188 -0.12478" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J2_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="0.011539 -0.034188 -0.12478" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J2_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}J3_1">
+      <inertial>
+        <origin xyz="-0.010672101243726572 -0.02723871972304964 0.04876701375652198" rpy="0 0 0"/>
+        <mass value="0.30531962155452225"/>
+        <inertia ixx="0.00029" iyy="0.000238" izz="0.000191" ixy="-1.3e-05" iyz="4.1e-05" ixz="3e-05"/>
+      </inertial>
+      <visual>
+        <origin xyz="-0.023811 -0.034188 -0.28278" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J3_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="-0.023811 -0.034188 -0.28278" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J3_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}J4_1">
+      <inertial>
+        <origin xyz="-0.005237398377441591 0.06002028183461833 0.0005891767740203724" rpy="0 0 0"/>
+        <mass value="0.14051172121899885"/>
+        <inertia ixx="0.000245" iyy="7.9e-05" izz="0.00027" ixy="1.6e-05" iyz="-2e-06" ixz="1e-06"/>
+      </inertial>
+      <visual>
+        <origin xyz="-0.010649 -0.038288 -0.345246" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J4_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="-0.010649 -0.038288 -0.345246" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J4_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}J5_1">
+      <inertial>
+        <origin xyz="-0.014389813882964664 0.07305218143664277 -0.0009243405950149497" rpy="0 0 0"/>
+        <mass value="0.7783315754227634"/>
+        <inertia ixx="0.000879" iyy="0.000339" izz="0.000964" ixy="0.000146" iyz="1e-06" ixz="-5e-06"/>
+      </inertial>
+      <visual>
+        <origin xyz="-0.031949 -0.148289 -0.345246" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J5_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="-0.031949 -0.148289 -0.345246" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J5_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}J6_1">
+      <inertial>
+        <origin xyz="3.967160300787087e-07 0.0004995066702210837 1.4402781733924286e-07" rpy="0 0 0"/>
+        <mass value="0.0020561527568204153"/>
+        <inertia ixx="0.0" iyy="0.0" izz="0.0" ixy="0.0" iyz="0.0" ixz="0.0"/>
+      </inertial>
+      <visual>
+        <origin xyz="-0.012127 -0.267789 -0.344021" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J6_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="-0.012127 -0.267789 -0.344021" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/J6_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <link name="${station_name}${device_name}camera">
+      <inertial>
+        <origin xyz="-0.0006059984983273845 0.0005864706438700462 0.04601775357664567" rpy="0 0 0"/>
+        <mass value="0.21961029019655884"/>
+        <inertia ixx="2.9e-05" iyy="0.000206" izz="0.000198" ixy="-0.0" iyz="2e-06" ixz="-0.0"/>
+      </inertial>
+      <visual>
+        <origin xyz="-0.012661 -0.239774 -0.37985" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/camera_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+        <material name="silver"/>
+      </visual>
+      <collision>
+        <origin xyz="-0.012661 -0.239774 -0.37985" rpy="0 0 0"/>
+        <geometry>
+          <mesh filename="file://${mesh_path}/devices/dummy2_robot/meshes/camera_1.stl" scale="0.001 0.001 0.001"/>
+        </geometry>
+      </collision>
+    </link>
+
+    <joint name="${station_name}${device_name}Joint1" type="revolute">
+      <origin xyz="0.0001 -0.000289 0.097579" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}base_link"/>
+      <child link="${station_name}${device_name}J1_1"/>
+      <axis xyz="-0.0 -0.0 1.0"/>
+      <limit upper="3.054326" lower="-3.054326" effort="100" velocity="100"/>
+    </joint>
+
+    <joint name="${station_name}${device_name}Joint2" type="revolute">
+      <origin xyz="-0.011639 0.034477 0.027201" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}J1_1"/>
+      <child link="${station_name}${device_name}J2_1"/>
+      <axis xyz="1.0 0.0 -0.0"/>
+      <limit upper="1.308997" lower="-2.007129" effort="100" velocity="100"/>
+    </joint>
+
+    <joint name="${station_name}${device_name}Joint3" type="revolute">
+      <origin xyz="0.03535 0.0 0.158" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}J2_1"/>
+      <child link="${station_name}${device_name}J3_1"/>
+      <axis xyz="-1.0 0.0 -0.0"/>
+      <limit upper="1.570796" lower="-1.047198" effort="100" velocity="100"/>
+    </joint>
+
+    <joint name="${station_name}${device_name}Joint4" type="revolute">
+      <origin xyz="-0.013162 0.0041 0.062466" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}J3_1"/>
+      <child link="${station_name}${device_name}J4_1"/>
+      <axis xyz="0.0 1.0 -0.0"/>
+      <limit upper="3.141593" lower="-3.141593" effort="100" velocity="100"/>
+    </joint>
+
+    <joint name="${station_name}${device_name}Joint5" type="revolute">
+      <origin xyz="0.0213 0.110001 0.0" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}J4_1"/>
+      <child link="${station_name}${device_name}J5_1"/>
+      <axis xyz="-1.0 -0.0 -0.0"/>
+      <limit upper="2.094395" lower="-1.919862" effort="100" velocity="100"/>
+    </joint>
+
+    <joint name="${station_name}${device_name}Joint6" type="continuous">
+      <origin xyz="-0.019822 0.1195 -0.001225" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}J5_1"/>
+      <child link="${station_name}${device_name}J6_1"/>
+      <axis xyz="0.0 -1.0 0.0"/>
+    </joint>
+
+    <joint name="${station_name}${device_name}camera" type="fixed">
+      <origin xyz="-0.019988 0.091197 0.024883" rpy="0 0 0"/>
+      <parent link="${station_name}${device_name}J5_1"/>
+      <child link="${station_name}${device_name}camera"/>
+      <axis xyz="1.0 -0.0 0.0"/>
+      <limit upper="0.0" lower="0.0" effort="100" velocity="100"/>
+    </joint>
+  </xacro:macro>
+
+</robot>