Initial commit

docs/developer_guide/add_protocol.md

@@ -0,0 +1,50 @@
+# 添加新实验操作（Protocol）
+
+在 `Uni-Lab` 中，实验操作（Protocol）指的是**对实验有意义的单个完整动作**——加入某种液体多少量；萃取分液；洗涤仪器；机械+末端执行器等等，就像实验步骤文字书写的那样。
+
+而这些对实验有意义的单个完整动作，**一般需要多个设备的协同**，或者同一设备连续动作，还依赖于他们的**物理连接关系（管道相连；机械臂可转运）**。`Protocol` 根据实验操作目标和设备物理连接关系，通过 `unilabos/compile` 中的“编译”过程产生硬件可执行的机器指令，并依次执行。
+
+开发一个 `Protocol` 一般共需要修改6个文件：
+
+1. 在 `unilabos_msgs/action` 中新建实验操作名和参数列表，如 `PumpTransfer.action`。一个 Action 定义由三个部分组成，分别是目标（Goal）、结果（Result）和反馈（Feedback），之间使用 `---` 分隔：
+
+```{literalinclude} ../../unilabos_msgs/action/PumpTransfer.action
+```
+
+2. 在 `unilabos_msgs/CMakeLists.txt` 中添加新定义的 action
+因为在指令集中新建了指令，因此调试时需要编译，并在终端环境中加载临时路径：
+```bash
+cd unilabos_msgs
+colcon build
+source ./install/local_setup.sh
+cd ..
+```
+
+调试成功后，发起 pull request，Uni-Lab 的 CI/CD 系统会自动将新的指令集编译打包，mamba执行升级即可永久生效：
+
+```bash
+mamba update ros-humble-unilabos-msgs -c http://quetz.dp.tech:8088/get/unilab -c robostack-humble -c robostack-staging
+```
+
+3. 在 `unilabos/messages/__init__.py` 中添加 Pydantic 定义的实验操作名和参数列表
+```{literalinclude} ../../unilabos/messages/__init__.py
+:start-after: Start Protocols
+:end-before: End Protocols
+```
+
+4. 在 `unilabos/compile` 中新建编译为机器指令的函数，函数入参为设备连接图 `G` 和实验操作参数。
+```{literalinclude} ../../unilabos/compile/pump_protocol.py
+:start-after: Pump protocol compilation
+:end-before: End Protocols
+```
+
+5. 将该函数加入 `unilabos/compile/__init__.py` 的 `action_protocol_generators` 中：
+```{literalinclude} ../../unilabos/compile/__init__.py
+:start-after: Define
+:end-before: End Protocols
+```
+
+6. 记得将新开发的 `Protocol` 添加至启动时的 `devices.json` 中。
+```{literalinclude} ../../devices.json
+:lines: 2-4
+```