From 54f75183ffd3eecd2fe93f6277aef7953731f112 Mon Sep 17 00:00:00 2001 From: Xuwznln <18435084+Xuwznln@users.noreply.github.com> Date: Sun, 12 Oct 2025 23:26:49 +0800 Subject: [PATCH] clean files --- CONTRIBUTORS | 15 + UniLab_LaiYu_控制架构详解.md | 259 ------------------ XYZ_集成功能说明.md | 221 --------------- package.xml | 22 -- .../unilabos-linux-64.yaml | 0 .../unilabos-osx-64.yaml | 0 .../unilabos-osx-arm64.yaml | 0 .../unilabos-win64.yaml | 0 setup.py | 5 +- unilabos_msgs/package.xml | 1 + 10 files changed, 19 insertions(+), 504 deletions(-) create mode 100644 CONTRIBUTORS delete mode 100644 UniLab_LaiYu_控制架构详解.md delete mode 100644 XYZ_集成功能说明.md delete mode 100644 package.xml rename unilabos-linux-64.yaml => scripts/unilabos-linux-64.yaml (100%) rename unilabos-osx-64.yaml => scripts/unilabos-osx-64.yaml (100%) rename unilabos-osx-arm64.yaml => scripts/unilabos-osx-arm64.yaml (100%) rename unilabos-win64.yaml => scripts/unilabos-win64.yaml (100%) diff --git a/CONTRIBUTORS b/CONTRIBUTORS new file mode 100644 index 00000000..9d0b395d --- /dev/null +++ b/CONTRIBUTORS @@ -0,0 +1,15 @@ + 156 Xuwznln <18435084+Xuwznln@users.noreply.github.com> + 39 Junhan Chang + 9 wznln <18435084+Xuwznln@users.noreply.github.com> + 8 Guangxin Zhang + 5 ZiWei <131428629+ZiWei09@users.noreply.github.com> + 2 Junhan Chang + 2 Xie Qiming <97236197+Andy6M@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 lixinyu1011 <61094742+lixinyu1011@users.noreply.github.com> + 1 shiyubo0410 + 1 王俊杰 <1800011822@pku.edu.cn> + 1 王俊杰 <43375851+wjjxxx@users.noreply.github.com> diff --git a/UniLab_LaiYu_控制架构详解.md b/UniLab_LaiYu_控制架构详解.md deleted file mode 100644 index efa3333f..00000000 --- a/UniLab_LaiYu_控制架构详解.md +++ /dev/null @@ -1,259 +0,0 @@ -# UniLab 控制 LaiYu_Liquid 设备架构详解 - -## 概述 - -UniLab 通过分层架构控制 LaiYu_Liquid 设备，实现了从高级实验协议到底层硬件驱动的完整控制链路。 - -## 🏗️ 架构层次 - -### 1. 应用层 (Application Layer) -- **实验协议**: 用户定义的实验流程 -- **设备抽象**: 通过 `LaiYu_Liquid` 类提供统一接口 - -### 2. 控制层 (Control Layer) -- **LaiYuLiquidBackend**: 设备业务逻辑控制器 -- **PipetteController**: 移液器控制器 -- **XYZController**: 三轴运动控制器 - -### 3. 驱动层 (Driver Layer) -- **SOPAPipetteDriver**: SOPA 移液器驱动 -- **XYZStepperDriver**: 三轴步进电机驱动 - -### 4. 硬件层 (Hardware Layer) -- **串口通信**: 通过 `/dev/cu.usbserial-3130` 等串口设备 -- **物理设备**: 移液器和三轴运动平台 - -## 🔧 核心组件详解 - -### LaiYu_Liquid 主类 -```python -class LaiYu_Liquid: - """LaiYu液体处理设备的主要接口类""" - - def __init__(self, config: LaiYuLiquidConfig): - self.config = config - self.deck = LaiYuLiquidDeck(config) - self.backend = LaiYuLiquidBackend(config, self.deck) -``` - -**核心功能**: -- 设备配置管理 -- 工作台资源管理 -- 硬件控制接口封装 - -### LaiYuLiquidBackend 控制器 -```python -class LaiYuLiquidBackend: - """设备后端控制逻辑""" - - async def setup(self): - """初始化硬件控制器""" - # 初始化移液器控制器 - self.pipette_controller = PipetteController( - port=self.config.port, - address=self.config.address - ) - - # 初始化XYZ控制器 - self.xyz_controller = XYZController( - port=self.config.port, - baudrate=self.config.baudrate, - machine_config=MachineConfig() - ) -``` - -**核心功能**: -- 硬件初始化和连接 -- 移液操作控制 -- 运动控制 -- 错误处理和状态管理 - -## 🎯 控制流程 - -### 1. 设备初始化流程 -``` -用户代码 → LaiYu_Liquid.setup() → LaiYuLiquidBackend.setup() - ↓ -PipetteController 初始化 ← → XYZController 初始化 - ↓ ↓ -SOPAPipetteDriver.connect() XYZStepperDriver.connect() - ↓ ↓ -串口连接 (/dev/cu.usbserial-3130) -``` - -### 2. 移液操作流程 -``` -用户调用 aspirate(volume) → LaiYuLiquidBackend.aspirate() - ↓ -检查设备状态 (连接、枪头、体积) - ↓ -PipetteController.aspirate(volume) - ↓ -SOPAPipetteDriver.aspirate_volume() - ↓ -串口命令发送到移液器硬件 -``` - -### 3. 运动控制流程 -``` -用户调用 move_to(position) → LaiYuLiquidBackend.move_to() - ↓ -坐标转换和安全检查 - ↓ -XYZController.move_to_work_coord() - ↓ -XYZStepperDriver.move_to() - ↓ -串口命令发送到步进电机 -``` - -## 🔌 硬件通信 - -### 串口配置 -- **端口**: `/dev/cu.usbserial-3130` (macOS) -- **波特率**: 115200 (移液器), 可配置 (XYZ控制器) -- **协议**: SOPA协议 (移液器), 自定义协议 (XYZ) - -### 通信协议 -1. **SOPA移液器协议**: - - 地址寻址: `address` 参数 - - 命令格式: 二进制协议 - - 响应处理: 异步等待 - -2. **XYZ步进电机协议**: - - G代码风格命令 - - 坐标系管理 - - 实时状态反馈 - -## 🛡️ 安全机制 - -### 1. 连接检查 -```python -def _check_hardware_ready(self): - """检查硬件是否就绪""" - if not self.is_connected: - raise DeviceError("设备未连接") - if not self.is_initialized: - raise DeviceError("设备未初始化") -``` - -### 2. 状态验证 -- 移液前检查枪头状态 -- 体积范围验证 -- 位置边界检查 - -### 3. 错误处理 -- 硬件连接失败自动切换到模拟模式 -- 异常捕获和日志记录 -- 优雅的错误恢复 - -## 📊 配置管理 - -### LaiYuLiquidConfig -```python -@dataclass -class LaiYuLiquidConfig: - port: str = "/dev/cu.usbserial-3130" - address: int = 1 - baudrate: int = 115200 - max_volume: float = 1000.0 - min_volume: float = 0.1 - # ... 其他配置参数 -``` - -### 配置文件支持 -- **YAML**: `laiyu_liquid.yaml` -- **JSON**: `laiyu_liquid.json` -- **环境变量**: 动态配置覆盖 - -## 🔄 异步操作 - -所有硬件操作都是异步的，支持: -- 并发操作 -- 非阻塞等待 -- 超时处理 -- 取消操作 - -```python -async def aspirate(self, volume: float) -> bool: - """异步吸液操作""" - try: - # 硬件操作 - result = await self.pipette_controller.aspirate(volume) - # 状态更新 - self._update_volume_state(volume) - return result - except Exception as e: - logger.error(f"吸液失败: {e}") - return False -``` - -## 🎮 实际使用示例 - -```python -# 1. 创建设备配置 -config = LaiYuLiquidConfig( - port="/dev/cu.usbserial-3130", - address=1, - baudrate=115200 -) - -# 2. 初始化设备 -device = LaiYu_Liquid(config) -await device.setup() - -# 3. 执行移液操作 -await device.pick_up_tip() -await device.aspirate(100.0) # 吸取100μL -await device.move_to((50, 50, 10)) # 移动到目标位置 -await device.dispense(100.0) # 分配100μL -await device.drop_tip() - -# 4. 清理 -await device.stop() -``` - -## 🔍 调试和监控 - -### 日志系统 -- 详细的操作日志 -- 错误追踪 -- 性能监控 - -### 状态查询 -```python -# 实时状态查询 -print(f"连接状态: {device.is_connected}") -print(f"当前位置: {device.current_position}") -print(f"当前体积: {device.current_volume}") -print(f"枪头状态: {device.tip_attached}") -``` - -## 📈 扩展性 - -### 1. 新设备支持 -- 继承抽象基类 -- 实现标准接口 -- 插件式架构 - -### 2. 协议扩展 -- 新通信协议支持 -- 自定义命令集 -- 协议适配器 - -### 3. 功能扩展 -- 新的移液模式 -- 高级运动控制 -- 智能优化算法 - -## 🎯 总结 - -UniLab 通过精心设计的分层架构，实现了对 LaiYu_Liquid 设备的完整控制: - -1. **高层抽象**: 提供简洁的API接口 -2. **中层控制**: 实现复杂的业务逻辑 -3. **底层驱动**: 处理硬件通信细节 -4. **安全可靠**: 完善的错误处理机制 -5. **易于扩展**: 模块化设计支持功能扩展 - -这种架构使得用户可以专注于实验逻辑，而无需关心底层硬件控制的复杂性。 \ No newline at end of file diff --git a/XYZ_集成功能说明.md b/XYZ_集成功能说明.md deleted file mode 100644 index 301b1136..00000000 --- a/XYZ_集成功能说明.md +++ /dev/null @@ -1,221 +0,0 @@ -# XYZ步进电机与移液器集成功能说明 - -## 概述 - -本文档描述了XYZ步进电机控制器与SOPA移液器的集成功能，实现了移液器在Z轴方向的精确运动控制，特别是在吸头装载过程中的自动定位功能。 - -## 新增功能 - -### 1. XYZ控制器集成 - -#### 初始化参数 -```python -controller = PipetteController( - port="/dev/ttyUSB0", # 移液器串口 - address=4, # 移液器Modbus地址 - xyz_port="/dev/ttyUSB1" # XYZ控制器串口（可选） -) -``` - -#### 连接管理 -- 自动检测并连接XYZ步进电机控制器 -- 支持独立的移液器操作（不依赖XYZ控制器） -- 提供连接状态查询功能 - -### 2. Z轴运动控制 - -#### 相对运动功能 -```python -# 向下移动10mm（用于吸头装载） -success = controller.move_z_relative(-10.0, speed=2000, acceleration=500) - -# 向上移动5mm -success = controller.move_z_relative(5.0, speed=1500) -``` - -#### 参数说明 -- `distance_mm`: 移动距离（毫米），负值向下，正值向上 -- `speed`: 运动速度（100-5000 rpm） -- `acceleration`: 加速度（默认500） - -#### 步距转换 -- 转换比例: 1mm = 1638.4步 -- 支持精确的毫米到步数转换 -- 自动处理位置计算和验证 - -### 3. 安全检查机制 - -#### 运动限制 -- **移动距离限制**: 单次移动最大15mm -- **速度限制**: 100-5000 rpm -- **位置限制**: Z轴位置范围 -50000 到 50000步 -- **单次移动步数限制**: 最大20000步（约12mm） - -#### 安全检查功能 -```python -def _check_xyz_safety(self, axis: MotorAxis, target_position: int) -> bool: - """执行XYZ轴运动前的安全检查""" - # 检查电机使能状态 - # 检查错误状态 - # 验证位置限制 - # 验证移动距离 -``` - -### 4. 增强的吸头装载功能 - -#### 自动Z轴定位 -```python -def pickup_tip(self) -> bool: - """装载吸头（包含Z轴自动定位）""" - # 检查当前吸头状态 - # 执行Z轴下降运动（10mm） - # 执行移液器吸头装载 - # 更新吸头状态 -``` - -#### 工作流程 -1. 检查是否已有吸头装载 -2. 如果配置了XYZ控制器，执行Z轴下降10mm -3. 执行移液器的吸头装载动作 -4. 更新吸头状态和统计信息 - -### 5. 紧急停止功能 - -#### 全系统停止 -```python -def emergency_stop(self) -> bool: - """紧急停止所有运动""" - # 停止移液器运动 - # 停止XYZ步进电机运动 - # 记录停止状态 -``` - -#### 使用场景 -- 检测到异常情况时立即停止 -- 用户手动中断操作 -- 系统故障保护 - -### 6. 状态监控 - -#### 设备状态查询 -```python -status = controller.get_status() -# 返回包含移液器和XYZ控制器状态的字典 -{ - 'pipette': { - 'connected': True, - 'tip_status': 'tip_attached', - 'current_volume': 0.0, - # ... - }, - 'xyz_controller': { - 'connected': True, - 'port': '/dev/ttyUSB1' - } -} -``` - -## 使用示例 - -### 基本使用流程 - -```python -from unilabos.devices.LaiYu_Liquid.controllers.pipette_controller import PipetteController - -# 1. 创建控制器实例 -controller = PipetteController( - port="/dev/ttyUSB0", - address=4, - xyz_port="/dev/ttyUSB1" # 可选 -) - -# 2. 连接设备 -if controller.connect(): - print("设备连接成功") - - # 3. 初始化 - if controller.initialize(): - print("设备初始化成功") - - # 4. 装载吸头（自动Z轴定位） - if controller.pickup_tip(): - print("吸头装载成功") - - # 5. 执行液体操作 - controller.aspirate(100.0) # 吸取100μL - controller.dispense(100.0) # 排出100μL - - # 6. 弹出吸头 - controller.eject_tip() - - # 7. 断开连接 - controller.disconnect() -``` - -### 手动Z轴控制 - -```python -# 精确的Z轴运动控制 -controller.move_z_relative(-5.0, speed=1000) # 下降5mm -time.sleep(1) # 等待运动完成 -controller.move_z_relative(5.0, speed=1000) # 上升5mm -``` - -## 集成测试 - -### 测试脚本 -使用 `test_xyz_pipette_integration.py` 脚本进行完整的集成测试： - -```bash -python test_xyz_pipette_integration.py -``` - -### 测试项目 -1. **连接状态测试** - 验证设备连接 -2. **Z轴运动测试** - 验证运动控制 -3. **吸头装载测试** - 验证集成功能 -4. **安全检查测试** - 验证安全机制 -5. **紧急停止测试** - 验证停止功能 -6. **液体操作测试** - 验证基本功能 - -## 配置要求 - -### 硬件要求 -- SOPA移液器（支持Modbus RTU通信） -- XYZ步进电机控制器（可选） -- 串口连接线 - -### 软件依赖 -- Python 3.7+ -- pymodbus库 -- pyserial库 - -### 串口配置 -- 波特率: 9600 -- 数据位: 8 -- 停止位: 1 -- 校验位: None - -## 注意事项 - -### 安全提醒 -1. **首次使用前必须进行安全检查** -2. **确保Z轴运动范围内无障碍物** -3. **紧急情况下立即使用紧急停止功能** -4. **定期检查设备连接状态** - -### 故障排除 -1. **连接失败**: 检查串口配置和设备电源 -2. **运动异常**: 检查电机使能状态和位置限制 -3. **吸头装载失败**: 检查Z轴位置和吸头供应 -4. **通信错误**: 检查Modbus地址和通信参数 - -## 更新记录 - -- **2024-01**: 初始版本，实现基本集成功能 -- **2024-01**: 添加安全检查和紧急停止功能 -- **2024-01**: 完善错误处理和状态监控 - -## 技术支持 - -如有技术问题，请联系开发团队或查阅相关技术文档。 \ No newline at end of file diff --git a/package.xml b/package.xml deleted file mode 100644 index 97415270..00000000 --- a/package.xml +++ /dev/null @@ -1,22 +0,0 @@ - - - - unilabos - 0.0.0 - ROS2 package for unilabos server - changjh - TODO: License declaration - - action_msgs - action_msgs - rosidl_interface_packages - - ament_copyright - ament_flake8 - ament_pep257 - python3-pytest - - - ament_python - - diff --git a/unilabos-linux-64.yaml b/scripts/unilabos-linux-64.yaml similarity index 100% rename from unilabos-linux-64.yaml rename to scripts/unilabos-linux-64.yaml diff --git a/unilabos-osx-64.yaml b/scripts/unilabos-osx-64.yaml similarity index 100% rename from unilabos-osx-64.yaml rename to scripts/unilabos-osx-64.yaml diff --git a/unilabos-osx-arm64.yaml b/scripts/unilabos-osx-arm64.yaml similarity index 100% rename from unilabos-osx-arm64.yaml rename to scripts/unilabos-osx-arm64.yaml diff --git a/unilabos-win64.yaml b/scripts/unilabos-win64.yaml similarity index 100% rename from unilabos-win64.yaml rename to scripts/unilabos-win64.yaml diff --git a/setup.py b/setup.py index 6d0f2d89..508ff337 100644 --- a/setup.py +++ b/setup.py @@ -9,8 +9,9 @@ setup( include_package_data=True, install_requires=['setuptools'], zip_safe=True, - maintainer='Junhan Chang', - maintainer_email='changjh@pku.edu.cn', + author="The unilabos developers", + maintainer='Junhan Chang, Xuwznln', + maintainer_email='Junhan Chang , Xuwznln <18435084+Xuwznln@users.noreply.github.com>', description='', license='GPL v3', tests_require=['pytest'], diff --git a/unilabos_msgs/package.xml b/unilabos_msgs/package.xml index 0b1224d4..c6e274a2 100644 --- a/unilabos_msgs/package.xml +++ b/unilabos_msgs/package.xml @@ -5,6 +5,7 @@ 0.10.7 ROS2 Messages package for unilabos devices Junhan Chang + Xuwznln MIT ament_cmake