mirror of
https://github.com/dptech-corp/Uni-Lab-OS.git
synced 2025-12-17 13:01:12 +00:00
143 lines
4.1 KiB
Markdown
143 lines
4.1 KiB
Markdown
# 添加新动作指令（Action）
|
||
|
||
本指南将引导你完成添加新动作指令的整个流程，包括编写、在线构建和测试。
|
||
|
||
## 1. 编写新的 Action
|
||
|
||
### 1.1 创建 Action 文件
|
||
|
||
在 `unilabos_msgs/action` 目录中新建实验操作文件，如 `MyDeviceCmd.action`。一个 Action 定义由三个部分组成，分别是目标（Goal）、结果（Result）和反馈（Feedback），之间使用 `---` 分隔：
|
||
|
||
```action
|
||
# 目标（Goal）- 定义动作执行所需的参数
|
||
string command
|
||
float64 timeout
|
||
---
|
||
# 结果（Result）- 定义动作完成后返回的结果
|
||
bool success # 要求必须包含success，以便回传执行结果
|
||
string return_info # 要求必须包含return_info，以便回传执行结果
|
||
... # 其他
|
||
---
|
||
# 反馈（Feedback）- 定义动作执行过程中的反馈信息
|
||
float64 progress
|
||
string status
|
||
```
|
||
|
||
### 1.2 更新 CMakeLists.txt
|
||
|
||
在 `unilabos_msgs/CMakeLists.txt` 中的 `add_action_files()` 部分添加新定义的 action：
|
||
|
||
```cmake
|
||
add_action_files(
|
||
FILES
|
||
MyDeviceCmd.action
|
||
# 其他已有的 action 文件...
|
||
)
|
||
```
|
||
|
||
## 2. 在线构建和测试
|
||
|
||
为了简化开发流程并确保构建环境的一致性，我们使用 GitHub Actions 进行在线构建。
|
||
|
||
### 2.1 Fork 仓库并创建分支
|
||
|
||
1. **Fork 仓库**：在 GitHub 上 fork `Uni-Lab-OS` 仓库到你的个人账户
|
||
|
||
2. **Clone 你的 fork**：
|
||
|
||
```bash
|
||
git clone https://github.com/YOUR_USERNAME/Uni-Lab-OS.git
|
||
cd Uni-Lab-OS
|
||
```
|
||
|
||
3. **创建功能分支**：
|
||
|
||
```bash
|
||
git checkout -b add-my-device-action
|
||
```
|
||
|
||
4. **提交你的更改**：
|
||
```bash
|
||
git add unilabos_msgs/action/MyDeviceCmd.action
|
||
git add unilabos_msgs/CMakeLists.txt
|
||
git commit -m "Add MyDeviceCmd action for device control"
|
||
git push origin add-my-device-action
|
||
```
|
||
|
||
### 2.2 触发在线构建
|
||
|
||
1. **访问你的 fork 仓库**：在浏览器中打开你的 fork 仓库页面
|
||
|
||
2. **手动触发构建**：
|
||
|
||
- 点击 "Actions" 标签
|
||
- 选择 "Multi-Platform Conda Build" 工作流
|
||
- 点击 "Run workflow" 按钮
|
||
|
||
3. **监控构建状态**：
|
||
- 构建过程大约需要 5-10 分钟
|
||
- 在 Actions 页面可以实时查看构建日志
|
||
- 构建完成后，可以下载生成的 conda 包进行测试
|
||
|
||
### 2.3 下载和测试构建包
|
||
|
||
1. **下载构建产物**：
|
||
|
||
- 在构建完成的 Action 页面，找到 "Artifacts" 部分
|
||
- 下载对应平台的 `conda-package-*` 文件
|
||
|
||
2. **本地测试安装**：
|
||
|
||
```bash
|
||
# 解压下载的构建产物
|
||
unzip conda-package-linux-64.zip # 或其他平台
|
||
|
||
# 安装测试包
|
||
mamba install ./ros-humble-unilabos-msgs-*.conda
|
||
```
|
||
|
||
3. **验证 Action 是否正确添加**：
|
||
```bash
|
||
# 检查 action 是否可用
|
||
ros2 interface show unilabos_msgs/action/MyDeviceCmd
|
||
```
|
||
|
||
## 3. 提交 Pull Request
|
||
|
||
测试成功后，向主仓库提交 Pull Request：
|
||
|
||
1. **创建 Pull Request**：
|
||
|
||
- 在你的 fork 仓库页面，点击 "New Pull Request"
|
||
- 选择你的功能分支作为源分支
|
||
- 填写详细的 PR 描述，包括：
|
||
- 添加的 Action 功能说明
|
||
- 测试结果
|
||
- 相关的设备或用例
|
||
|
||
2. **等待审核和合并**：
|
||
- 维护者会审核你的代码
|
||
- CI/CD 系统会自动运行完整的测试套件
|
||
- 合并后，新的指令集会自动发布到官方 conda 仓库
|
||
|
||
## 4. 使用新的 Action
|
||
|
||
如果采用自己构建的action包，可以通过以下命令更新安装：
|
||
|
||
```bash
|
||
mamba remove --force ros-humble-unilabos-msgs
|
||
mamba config set safety_checks disabled # 如果没有提升版本号，会触发md5与网络上md5不一致，是正常现象，因此通过本指令关闭md5检查
|
||
mamba install xxx.conda2 --offline
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
**Q: 构建失败怎么办？**
|
||
A: 检查 Actions 日志中的错误信息，通常是语法错误或依赖问题。修复后重新推送代码即可自动触发新的构建。
|
||
|
||
**Q: 如何测试特定平台？**
|
||
A: 在手动触发构建时，在平台选择中只填写你需要的平台，如 `linux-64` 或 `win-64`。
|
||
|
||
**Q: 构建包在哪里下载？**
|
||
A: 在 Actions 页面的构建结果中，查找 "Artifacts" 部分，每个平台都有对应的构建包可供下载。
|