mirror of
https://github.com/dptech-corp/Uni-Lab-OS.git
synced 2025-12-17 04:51:10 +00:00
clean files
This commit is contained in:
Xuwznln
15
CONTRIBUTORS
Normal file
15
CONTRIBUTORS
Normal file
@@ -0,0 +1,15 @@
|
||||
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>
|
||||
5 ZiWei <131428629+ZiWei09@users.noreply.github.com>
|
||||
2 Junhan Chang <changjh@pku.edu.cn>
|
||||
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 <shiyubo@dp.tech>
|
||||
1 王俊杰 <1800011822@pku.edu.cn>
|
||||
1 王俊杰 <43375851+wjjxxx@users.noreply.github.com>
|
||||
@@ -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. **易于扩展**: 模块化设计支持功能扩展
|
||||
|
||||
这种架构使得用户可以专注于实验逻辑，而无需关心底层硬件控制的复杂性。
|
||||
221
XYZ_集成功能说明.md
221
XYZ_集成功能说明.md
@@ -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**: 完善错误处理和状态监控
|
||||
|
||||
## 技术支持
|
||||
|
||||
如有技术问题，请联系开发团队或查阅相关技术文档。
|
||||
22
package.xml
22
package.xml
@@ -1,22 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
|
||||
<package format="3">
|
||||
<name>unilabos</name>
|
||||
<version>0.0.0</version>
|
||||
<description>ROS2 package for unilabos server</description>
|
||||
<maintainer email="changjh@pku.edu.cn">changjh</maintainer>
|
||||
<license>TODO: License declaration</license>
|
||||
|
||||
<build_depend>action_msgs</build_depend>
|
||||
<exec_depend>action_msgs</exec_depend>
|
||||
<member_of_group>rosidl_interface_packages</member_of_group>
|
||||
|
||||
<test_depend>ament_copyright</test_depend>
|
||||
<test_depend>ament_flake8</test_depend>
|
||||
<test_depend>ament_pep257</test_depend>
|
||||
<test_depend>python3-pytest</test_depend>
|
||||
|
||||
<export>
|
||||
<build_type>ament_python</build_type>
|
||||
</export>
|
||||
</package>
|
||||
5
setup.py
5
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 <changjh@pku.edu.cn>, Xuwznln <18435084+Xuwznln@users.noreply.github.com>',
|
||||
description='',
|
||||
license='GPL v3',
|
||||
tests_require=['pytest'],
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
<version>0.10.7</version>
|
||||
<description>ROS2 Messages package for unilabos devices</description>
|
||||
<maintainer email="changjh@pku.edu.cn">Junhan Chang</maintainer>
|
||||
<maintainer email="18435084+Xuwznln@users.noreply.github.com">Xuwznln</maintainer>
|
||||
<license>MIT</license>
|
||||
|
||||
<buildtool_depend>ament_cmake</buildtool_depend>
|
||||
|
||||
Reference in New Issue
Block a user