diff --git a/docs/developer_guide/materials_construction_guide.md b/docs/developer_guide/materials_construction_guide.md new file mode 100644 index 00000000..a19fa05c --- /dev/null +++ b/docs/developer_guide/materials_construction_guide.md @@ -0,0 +1,405 @@ +# 物料构建指南 + +## 概述 + +在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`: 版本号，用于版本管理 diff --git a/docs/intro.md b/docs/intro.md index 3b176daf..4c1cd4c7 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -26,6 +26,7 @@ boot_examples/index.md ## 开发者指南 ```{toctree} + :maxdepth: 2 developer_guide/device_driver @@ -34,6 +35,10 @@ developer_guide/add_action developer_guide/actions developer_guide/workstation_architecture developer_guide/add_protocol +developer_guide/add_batteryPLC +developer_guide/materials_tutorial +developer_guide/materials_construction_guide + ``` ## 接口文档 diff --git a/unilabos/resources/bioyond/decks.py b/unilabos/resources/bioyond/decks.py index 187f17e8..19e0347e 100644 --- a/unilabos/resources/bioyond/decks.py +++ b/unilabos/resources/bioyond/decks.py @@ -136,7 +136,6 @@ class BIOYOND_YB_Deck(Deck): for warehouse_name, warehouse in self.warehouses.items(): self.assign_child_resource(warehouse, location=self.warehouse_locations[warehouse_name]) - def YB_Deck(name: str) -> Deck: by=BIOYOND_YB_Deck(name=name) by.setup() diff --git a/unilabos/resources/bioyond/warehouses.py b/unilabos/resources/bioyond/warehouses.py index 66697be6..0d536feb 100644 --- a/unilabos/resources/bioyond/warehouses.py +++ b/unilabos/resources/bioyond/warehouses.py @@ -5,15 +5,15 @@ def bioyond_warehouse_1x4x4(name: str) -> WareHouse: """创建BioYond 4x4x1仓库 (左侧堆栈: A01～D04)""" return warehouse_factory( name=name, - num_items_x=4, + num_items_x=1, num_items_y=4, - num_items_z=1, + num_items_z=4, dx=10.0, dy=10.0, dz=10.0, - item_dx=147.0, - item_dy=106.0, - item_dz=130.0, + item_dx=137.0, + item_dy=96.0, + item_dz=120.0, category="warehouse", col_offset=0, # 从01开始: A01, A02, A03, A04 )