# LaiYu_Liquid 液体处理工作站

## 概述

LaiYu_Liquid 是一个完全集成到 UniLabOS 的自动化液体处理工作站，基于 RS485 通信协议，专为精确的液体分配和转移操作而设计。本模块已完成生产环境部署准备，提供完整的硬件控制、资源管理和标准化接口。

## 系统组成

### 硬件组件
- **XYZ三轴运动平台**: 3个RS485步进电机驱动（地址：X轴=0x01, Y轴=0x02, Z轴=0x03）
- **SOPA气动式移液器**: RS485总线控制，支持精密液体处理操作
- **通信接口**: RS485转USB模块，默认波特率115200
- **机械结构**: 稳固工作台面，支持离心管架、96孔板等标准实验耗材

### 软件架构
- **驱动层**: 底层硬件通信驱动，支持RS485协议
- **控制层**: 高级控制逻辑和坐标系管理
- **抽象层**: 完全符合UniLabOS标准的液体处理接口
- **资源层**: 标准化的实验器具和耗材管理

## 🎯 生产就绪组件

### ✅ 核心驱动程序 (`drivers/`)
- **`sopa_pipette_driver.py`** - SOPA移液器完整驱动
  - 支持液体吸取、分配、检测
  - 完整的错误处理和状态管理
  - 生产级别的通信协议实现
  
- **`xyz_stepper_driver.py`** - XYZ三轴步进电机驱动
  - 精确的位置控制和运动规划
  - 安全限位和错误检测
  - 高性能运动控制算法

### ✅ 高级控制器 (`controllers/`)
- **`pipette_controller.py`** - 移液控制器
  - 封装高级液体处理功能
  - 支持多种液体类型和处理参数
  - 智能错误恢复机制
  
- **`xyz_controller.py`** - XYZ运动控制器
  - 坐标系管理和转换
  - 运动路径优化
  - 安全运动控制

### ✅ UniLabOS集成 (`core/LaiYu_Liquid.py`)
- **完整的液体处理抽象接口**
- **标准化的资源管理系统**
- **与PyLabRobot兼容的后端实现**
- **生产级别的错误处理和日志记录**

### ✅ 资源管理系统
- **`laiyu_liquid_res.py`** - 标准化资源定义
  - 96孔板、离心管架、枪头架等标准器具
  - 自动化的资源创建和配置函数
  - 与工作台布局的完美集成

### ✅ 配置管理 (`config/`)
- **`config/deck.json`** - 工作台布局配置
  - 精确的空间定义和槽位管理
  - 支持多种实验器具的标准化放置
  - 可扩展的配置架构

- **`__init__.py`** - 模块集成和导出
  - 完整的API导出和版本管理
  - 依赖检查和安装验证
  - 专业的模块信息展示

<!-- ### ✅ 可视化支持
- **`rviz_backend.py`** - RViz可视化后端
  - 实时运动状态可视化
  - 液体处理过程监控
  - 与ROS系统的无缝集成 -->

## 🚀 核心功能特性

### 液体处理能力
- **精密体积控制**: 支持1-1000μL精确分配
- **多种液体类型**: 水性、有机溶剂、粘稠液体等
- **智能检测**: 液位检测、气泡检测、堵塞检测
- **自动化流程**: 完整的吸取-转移-分配工作流

### 运动控制系统
- **三轴精密定位**: 微米级精度控制
- **路径优化**: 智能运动规划和碰撞避免
- **安全机制**: 限位保护、紧急停止、错误恢复
- **坐标系管理**: 工作坐标与机械坐标的自动转换

### 资源管理
- **标准化器具**: 支持96孔板、离心管架、枪头架等
- **状态跟踪**: 实时监控液体体积、枪头状态等
- **自动配置**: 基于JSON的灵活配置系统
- **扩展性**: 易于添加新的器具类型

## 📁 目录结构

```
LaiYu_Liquid/
├── __init__.py              # 模块初始化和API导出
├── readme.md               # 本文档
├── backend/                # 后端驱动模块
│   ├── __init__.py
│   └── laiyu_backend.py    # PyLabRobot兼容后端
├── core/                   # 核心模块
│   ├── core/
│   │   └── LaiYu_Liquid.py    # 主设备类
│   ├── abstract_protocol.py # 抽象协议
│   └── laiyu_liquid_res.py # 设备资源定义
├── config/                 # 配置文件目录
│   └── deck.json          # 工作台布局配置
├── controllers/           # 高级控制器
│   ├── __init__.py
│   ├── pipette_controller.py  # 移液控制器
│   └── xyz_controller.py      # XYZ运动控制器
├── docs/                  # 技术文档
│   ├── SOPA气动式移液器RS485控制指令.md
│   ├── 步进电机控制指令.md
│   └── hardware/          # 硬件相关文档
├── drivers/               # 底层驱动程序
│   ├── __init__.py
│   ├── sopa_pipette_driver.py  # SOPA移液器驱动
│   └── xyz_stepper_driver.py   # XYZ步进电机驱动
└── tests/                 # 测试文件
```

## 🔧 快速开始

### 1. 安装和验证

```python
# 验证模块安装
from unilabos.devices.laiyu_liquid import (
    LaiYuLiquid,
    LaiYuLiquidConfig,
    create_quick_setup,
    print_module_info
)

# 查看模块信息
print_module_info()

# 快速创建默认资源
resources = create_quick_setup()
print(f"已创建 {len(resources)} 个资源")
```

### 2. 基本使用示例

```python
from unilabos.devices.LaiYu_Liquid import (
    create_quick_setup, 
    create_96_well_plate,
    create_laiyu_backend
)

# 快速创建默认资源
resources = create_quick_setup()
print(f"创建了以下资源: {list(resources.keys())}")

# 创建96孔板
plate_96 = create_96_well_plate("test_plate")
print(f"96孔板包含 {len(plate_96.children)} 个孔位")

# 创建后端实例（用于PyLabRobot集成）
backend = create_laiyu_backend("LaiYu_Device")
print(f"后端设备: {backend.name}")
```

### 3. 后端驱动使用

```python
from unilabos.devices.laiyu_liquid.backend import create_laiyu_backend

# 创建后端实例
backend = create_laiyu_backend("LaiYu_Liquid_Station")

# 连接设备
await backend.connect()

# 设备归位
await backend.home_device()

# 获取设备状态
status = await backend.get_status()
print(f"设备状态: {status}")

# 断开连接
await backend.disconnect()
```

### 4. 资源管理示例

```python
from unilabos.devices.LaiYu_Liquid import (
    create_centrifuge_tube_rack,
    create_tip_rack,
    load_deck_config
)

# 加载工作台配置
deck_config = load_deck_config()
print(f"工作台尺寸: {deck_config['size_x']}x{deck_config['size_y']}mm")

# 创建不同类型的资源
tube_rack = create_centrifuge_tube_rack("sample_rack")
tip_rack = create_tip_rack("tip_rack_200ul")

print(f"离心管架: {tube_rack.name}, 容量: {len(tube_rack.children)} 个位置")
print(f"枪头架: {tip_rack.name}, 容量: {len(tip_rack.children)} 个枪头")
```

## 🔍 技术架构

### 坐标系统
- **机械坐标**: 基于步进电机的原始坐标系统
- **工作坐标**: 用户友好的实验室坐标系统
- **自动转换**: 透明的坐标系转换和校准

### 通信协议
- **RS485总线**: 高可靠性工业通信标准
- **Modbus协议**: 标准化的设备通信协议
- **错误检测**: 完整的通信错误检测和恢复

### 安全机制
- **限位保护**: 硬件和软件双重限位保护
- **紧急停止**: 即时停止所有运动和操作
- **状态监控**: 实时设备状态监控和报警

## 🧪 验证和测试

### 功能验证
```python
# 验证模块安装
from unilabos.devices.laiyu_liquid import validate_installation
validate_installation()

# 查看模块信息
from unilabos.devices.laiyu_liquid import print_module_info
print_module_info()
```

### 硬件连接测试
```python
# 测试SOPA移液器连接
from unilabos.devices.laiyu_liquid.drivers import SOPAPipette, SOPAConfig

config = SOPAConfig(port="/dev/cu.usbserial-3130", address=4)
pipette = SOPAPipette(config)
success = pipette.connect()
print(f"SOPA连接状态: {'成功' if success else '失败'}")
```

## 📚 维护和支持

### 日志记录
- **结构化日志**: 使用Python logging模块的专业日志记录
- **错误追踪**: 详细的错误信息和堆栈跟踪
- **性能监控**: 操作时间和性能指标记录

### 配置管理
- **JSON配置**: 灵活的JSON格式配置文件
- **参数验证**: 自动配置参数验证和错误提示
- **热重载**: 支持配置文件的动态重载

### 扩展性
- **模块化设计**: 易于扩展和定制的模块化架构
- **插件接口**: 支持第三方插件和扩展
- **API兼容**: 向后兼容的API设计