Initial commit

docs/concepts/01-communication-instruction.md

@@ -0,0 +1,45 @@
+(instructions)=
+# 设备抽象、指令集与通信中间件
+
+Uni-Lab 操作系统的目的是将不同类型和厂家的实验仪器进行抽象统一，对应用层提供服务。因此，理清实验室设备之间的业务逻辑至关重要。
+
+## 设备间通信模式
+
+### **[话题（一对多发送，一对多订阅）](https://book.guyuehome.com/ROS2/2.%E6%A0%B8%E5%BF%83%E6%A6%82%E5%BF%B5/2.4_%E8%AF%9D%E9%A2%98/)**
+
+典型的话题通信有：
+
+* 传感器连续发送设备状态和数据；
+* 连续时间控制器发送控制指令，如控温、连续称量、机械臂轨迹跟随、视觉识别操作等
+
+![](image/01-communication-instruction/topic.gif)
+
+### **[服务（短时请求与响应）](https://book.guyuehome.com/ROS2/2.%E6%A0%B8%E5%BF%83%E6%A6%82%E5%BF%B5/2.5_%E6%9C%8D%E5%8A%A1/)**
+
+典型的服务通信有：
+
+* 查/改全局参数如物料、设备
+* 使用其他通信接口发送/接收数据
+
+![](image/01-communication-instruction/service.gif)
+
+### **[动作（长时任务启动，随后连续收到反馈值，直到达到目标）](https://book.guyuehome.com/ROS2/2.%E6%A0%B8%E5%BF%83%E6%A6%82%E5%BF%B5/2.7_%E5%8A%A8%E4%BD%9C/)**
+
+动作机制主要用于处理运行时长较长的单点任务或任务组合，如：
+
+* 执行工作流
+* 执行工作流的子动作
+
+![](image/01-communication-instruction/action.gif)
+
+## 通信指令集
+
+Uni-Lab 目前使用 ROS2 作为通信中间件，因此大量使用其标准消息作为话题、服务、动作。新增指令位于仓库中的 `unilabos_msgs` ，各类实验动作指令集分类整理于 {ref}`actions`
+
+## 通信中间件层
+
+通信中间件层的一个重要设计思想是：将业务逻辑开发，与实际部署中的通信和运行解耦。开发者在实现具体业务逻辑时，可以不用关心最终运行时的 **部署方式** 、 **通信方式** 。当用户开发完成后，再根据实际情况决定部署、通信方案。
+
+* 对于 **“流动化学实验室”和“桌面机器人”** 来说，一台电脑通过串口控制所有设备足够。**此时在这台电脑启动 Uni-Lab 作为 Server 即可。**
+* 对于 **“移动机器人”大型实验室** ，典型场景是，一个实验室由多台不同位置的工作站组成，每台大型设备有一台工控机，通过串口再控制子设备。同时有 AGV/机械臂 负责转运。**此时，在每台工控机启动 Uni-Lab，完成通信中间件层的包装之后，只要处于同一局域网下，他们将能自动互相发现并组成分布式的“Uni-Lab-Edge Server”。**
+* 通信中间件层的分布式机制，使得 Node 之间做好了隔离，一台设备故障时只需重启单个 Node。很像微服务、微内核的设计理念。

docs/concepts/02-topology-and-chemputer-compile.md

@@ -0,0 +1,79 @@
+(graph)=
+# 实验室组态图
+
+组态(configuration)图是指在自动化领域中，用来描述和展示控制系统中各个组件之间关系的图形化表示方法。
+它是一个系统的框架图，通过图形符号和连接线，将各个组件（如传感器、执行器、控制器等）以及它们之间的关系进行可视化展示。
+
+Uni-Lab 的组态图当前支持 node-link json 和 graphml 格式，其中包含4类重要信息：
+
+* 单个设备/物料配置，即图中节点的参数；
+* 父子关系，如一台工作站包含它的多个子设备、放置着多个物料耗材；
+* 物理连接关系，如流体管路连接、AGV/机械臂/直线模组转运连接。
+* 通信转接关系，如多个 IO 设备通过 IO 板卡或 PLC 转为 Modbus；串口转网口等
+* 控制逻辑关系，如某个输出量被某个输入量 PID 控制
+
+## 父子关系、物质流与"编译"操作
+
+在计算机操作系统下，软件操作数据和文件。在实验操作系统下，实验“软件”利用仪器“硬件”操作物质。实验人员能理解的操作，最终都是对物质的处理。将实验步骤，转化为硬件指令，这个操作我们可以类比为“编译”。
+
+对用户来说，“直接操作设备执行单个指令”不是个真实需求，真正的需求是**“执行对实验有意义的单个完整动作”——加入某种液体多少量；萃取分液；洗涤仪器等等。就像实验步骤文字书写的那样。**
+
+而这些对实验有意义的单个完整动作，**一般需要多个设备的协同**，还依赖于他们的**物理连接关系（管道相连；机械臂可转运）**。
+于是 Uni-Lab 实现了抽象的“工作站”，即注册表中的 `workstation` 设备（`ProtocolNode`类）来处理编译、规划操作。以泵骨架组成的自动有机实验室为例，设备管道连接关系如下：
+
+![topology](image/02-topology-and-chemputer-compile/topology.png)
+
+接收“移液”动作，编译为一系列泵指令和阀指令
+
+```text
+Goal received: {
+    'from_vessel': 'flask_acetone', 
+    'to_vessel': 'reactor', 
+    'volume': 2000.0, 
+    'flowrate': 100.0
+}, running steps: 
+```
+
+```JSON
+[
+{
+    "device_id": "pump_reagents", 
+    "action_name": "set_valve_position", 
+    "action_kwargs": {"command": "3"}
+}, 
+{
+    "device_id": "pump_reagents",   
+    "action_name": "set_position", 
+    "action_kwargs": {
+        "position": 2000.0, 
+        "max_velocity": 100.0
+    }
+}, 
+{
+    "device_id": "pump_reagents", 
+    "action_name": "set_valve_position", 
+    "action_kwargs": {"command": '5'}
+}, 
+{
+    "device_id": "pump_reagents", 
+    "action_name": "set_position", 
+    "action_kwargs": {
+        "position": 0.0, 
+        "max_velocity": 100.0
+    }
+}
+]
+```
+
+若想开发新的“编译”/“规划”功能，在 `unilabos/compilers` 实现一个新函数即可。详情请见 [添加新实验操作（Protocol）](../developer_guide/add_protocol.md)
+
+## 通信转接关系
+
+Uni-Lab 秉持着**通信逻辑**与**业务逻辑**分离的设计理念，以追求实验设备、通信设备最大的代码复用性。
+
+如对 IO 板卡8路 IO 控制的8个电磁阀，经过设备抽象层后，仅有逻辑意义上分立的8个电磁阀。在组态图中，他们通过代表通信关系的边（edge）与 IO 板卡设备相连，边的属性包含 IO 地址。
+在实际使用中，对抽象的电磁阀发送开关动作请求，将通过 Uni-Lab 设备抽象&通信中间件转化为对 IO 板卡发送 IO 读写指令。因此一定意义上，组态图的通信转接部分代表了简化的电气接线图。
+
+代码架构上，实验设备位于 Uni-Lab 仓库/注册表的 `devices` 目录，通信设备位于 Uni-Lab 仓库/注册表的 `device_comms` 目录。
+
+![configuration](image/01-communication-instruction/configuration.png)

docs/concepts/overview.md

@@ -0,0 +1,3 @@
+# Uni-Lab 操作系统总览
+
+![Layers](image/overview/Uni-Lab-layers.png)![Layers](image/overview/Uni-Lab-whiteboard.png)