Uni-Lab-OS/unilabos/devices/laiyu_liquid/docs/readme.md

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导出和版本管理
  • 依赖检查和安装验证
  • 专业的模块信息展示

🚀 核心功能特性

液体处理能力

• 精密体积控制: 支持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. 安装和验证

# 验证模块安装
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. 基本使用示例

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. 后端驱动使用

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. 资源管理示例

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协议: 标准化的设备通信协议
• 错误检测: 完整的通信错误检测和恢复

安全机制

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

🧪 验证和测试

功能验证

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

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

硬件连接测试

# 测试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设计