open-deploy-ws 配置¶

公开工作空间 open-deploy-ws 的详细配置指南。

仓库概述¶

URL： https://github.com/fiveages-sim/open-deploy-ws

open-deploy-ws 是 FiveAges Sim 生态系统的公开入口，提供：

预配置的子模块结构
默认仅公开可见
便于最小化编译的精简分支
OCS2（以及可选的 common / arms）的 GitHub Release .deb 集成

先完成环境安装（ROS apt 源 → Jazzy + rosdep）。然后用 ./init_repo.sh。colcon build 之后，在启动终端 source install/setup.bash。

克隆¶

git clone https://github.com/fiveages-sim/open-deploy-ws.git
cd open-deploy-ws

顶层克隆可以用 HTTPS。.gitmodules 里的嵌套远程仍是 git@github.com:…（arms_ros2_control 和 robot_descriptions 的嵌套 .gitmodules 同样如此）。

SSH 远程 vs HTTPS / `gh`¶

没有 ssh 可执行文件或 GitHub SSH 密钥的机器，拉取子模块会失败：error: cannot run ssh: No such file or directory。

仅设置 git config url.https://github.com/.insteadOf git@github.com: 不够让 git submodule update 走通。嵌套仓会读自己的 .gitmodules，并直接调用 ssh。

当前 open-deploy-ws main 上的 ./init_repo.sh 会把 .gitmodules 中的 GitHub git@ URL 改写成 HTTPS，执行 submodule sync / update，再还原 .gitmodules（工作区不会留下脏改动）。在没有 ssh、public 模式没有可用密钥、或传入 --https / OPEN_DEPLOY_GIT_HTTPS=1 时走这条路径。优先：

./init_repo.sh --public --ocs2=deb --arms=source --common=source
# force HTTPS even if ssh exists:
./init_repo.sh --public --https --ocs2=deb --arms=source --common=source

./init_repo.sh --help 列出其余参数（另见 open-deploy-ws README）。已有 SSH 密钥的主机（尤其是 private 嵌套）保持原来的 SSH URL，除非加了 --https。

若你的检出早于这些参数（./init_repo.sh --help 里没有 --https），先拉取 main 或重新克隆 open-deploy-ws。Taku 在初始化后再把描述切到 feature/agilex（见 Taku / feature/agilex）。

初始化¶

./init_repo.sh

不带参数时菜单是交互式的（read 提示：public/private，再按模块选 d/s）。脚本做什么（open-deploy-ws README）：

菜单	作用
1) 初始化工作空间（推荐）	嵌套可见性（`public` / `private`），再按模块选 `d`（GitHub Release `.deb`）或 `s`（源码）。随后同步子模块，对源码路径跑 `rosdep install`，并安装所选 deb。
2) 切换模块安装方式	按模块（OCS2、arms、common）在源码 ↔ deb 之间切换。清理冲突源码或卸载对应 deb，然后重新同步。
3) 仅安装/更新核心 deb	跳过 Git。`./scripts/install_core_debs.sh --only ocs2`（或 `common`、`arms`，逗号分隔）。
4) 卸载核心 deb	`./scripts/uninstall_core_debs.sh --only ocs2`
5) 仅运行 rosdep	`rosdep install --from-paths src --ignore-src -r -y` — 不拉 Git、不装 deb

init 之后仍需 colcon build。不要从 git submodule update --init --recursive 开始；脚本已经初始化你选中的模块。

核心模块选项（OCS2、arms、common）¶

出现提示时（d=deb，s=source；直接回车使用默认值）：

选项	描述	适用场景
`d`	GitHub Release `.deb`	快速入门；无需从源码编译该模块
`s`	源码编译	开发、调试或贡献代码

open-deploy-ws 的默认值：OCS2=d，arms=s，common=s。Deb 模式不会从 packages.ros.org 安装。

CI / 非交互初始化¶

没有 TTY 的容器或 CI 任务可以运行：

./init_repo.sh --public --ocs2=deb --arms=source --common=source

默认值与交互菜单一致：public，ocs2=deb，arms=source，common=source。传入 --public、--private 或任一模块参数即跳过键盘提示。./init_repo.sh --help 列出流程开关（--init、--switch、--deb-only、--rosdep 等）。

参数	环境变量	含义
`--public` / `--private`	`OPEN_DEPLOY_VISIBILITY`	嵌套可见性
`--ocs2=deb\|source`	`OPEN_DEPLOY_OCS2`	ocs2 安装方式
`--arms=deb\|source`	`OPEN_DEPLOY_ARMS`	arms 安装方式
`--common=deb\|source`	`OPEN_DEPLOY_COMMON`	common 安装方式
`--https`	`OPEN_DEPLOY_GIT_HTTPS=1`	强制用 HTTPS 拉取 GitHub 子模块
`-y` / `--yes`	`OPEN_DEPLOY_YES=1`	自动确认清理源码目录

命令行参数优先于对应的环境变量。若 ./init_repo.sh --help 没有列出 --public，先拉取 main。

精简分支¶

单一机型时，克隆对应分支（README 里的目录名）。只需要该机器人的包时用精简分支（克隆更小）。Taku 没有精简的 open-deploy-ws 分支 — 留在 main，把描述切到 feature/agilex。

# Dobot CR5
git clone -b dobot-cr5 git@github.com:fiveages-sim/open-deploy-ws.git dobot_cr5_ws
# ARX Lift 2S (full-body). Acone (dual-arm) is co-debug in this workspace, not a separate platform.
git clone -b arx-lift2s git@github.com:fiveages-sim/open-deploy-ws.git lift2s-ws
# HighTorque Panthera HT
git clone -b panthera-ht git@github.com:fiveages-sim/open-deploy-ws.git ht-deploy-ws

open-deploy-ws README 也列出了 arx-acone。然后按该分支 README 运行 ./init_repo.sh 和 ./quick_start.sh。见 ARX Lift 2S 和高擎 Panthera HT。

目录结构¶

初始化完成后：

来自 open-deploy-ws README（连字符，不是 robot_descriptions）：

open-deploy-ws/
├── src/
│   ├── arms_ros2_control/     # controllers / commands / hardware interfaces / shared libs
│   ├── robot-descriptions/    # common / manipulator / humanoid
│   └── ocs2_ros2/             # only if that module is installed as source
├── init_repo.sh
├── submodules_visibility.conf
├── deb_versions.conf
└── scripts/

Taku / `feature/agilex`¶

open-deploy-ws 的 .gitmodules 把 src/robot-descriptions 钉在 main。Taku 不在 main 上。

仓内包在 feature/agilex 的 humanoid/Dyna/taku_description（包 README）。常规初始化之后（或 HTTPS 克隆了 main 上的 robot_descriptions 之后）：

cd src/robot-descriptions
git fetch origin
git checkout feature/agilex
# common is required (sensor_models / robot_common_launch)
git clone https://github.com/fiveages-sim/robot-descriptions-common.git common
# or, if SSH works: git submodule update --init common

若从干净的 HTTPS 树开始，一步克隆该分支的描述：git clone -b feature/agilex https://github.com/fiveages-sim/robot_descriptions.git src/robot-descriptions。

该包 README 中已核实的启动键（robot:=taku → taku_description）：

colcon build --packages-up-to taku_description sensor_models --symlink-install
source install/setup.bash
ros2 launch robot_common_launch humanoid.launch.py robot:=taku

控制启动见该包 README §3.1 / §3.2（描述已切到 feature/agilex 之后）。默认 hardware:=mock_components。布局没有底盘或单臂 basic 控制器。Dynaclaw 使用 adaptive_gripper_controller（left/right_gripper_controller；关节为 *_gripper_joint，URDF 里另一侧爪为 mimic）。网格在 meshes/{chassis,body,head,arm,dynaclaw}/。

colcon build --packages-up-to ocs2_arm_controller taku_description
source install/setup.bash
# 分体 — public mock path (arm MPC + body/head basic + grippers)
ros2 launch ocs2_arm_controller split_body.launch.py robot:=taku
# 全身 — needs the private ocs2_wbc_controller submodule
ros2 launch ocs2_arm_controller full_body.launch.py robot:=taku

公开 mock 与私有 WBC

公开描述里有 config/ocs2/fixed_base_tcp.info 并不表示公开 mock 能跑 ocs2_wbc_controller。公开 mock 用 split_body.launch.py。full_body.launch.py 需要私有 WBC 子模块。

启动	控制器
`split_body.launch.py`	`ocs2_arm_controller`（双臂 MPC，`info_file_name: task`）+ `body_joint_controller`（`folding_low/high` + `waist_pitch/yaw`）+ `head_joint_controller`（`head_yaw/pitch/roll`）+ 夹爪
`full_body.launch.py`	`ocs2_wbc_controller`（身体 + 双臂 + 头，`info_file_name: fixed_base_tcp`）+ 夹爪

当该配置和私有模块都在时，全身默认 headMode 是 HEAD_GAZE（注视 head_camera_mid_optical_frame）。target_manager.yaml 里 enable_head_control: false，因此头跟随 OCS2，而不是关节空间 marker。分体仍通过 head_joint_controller（RViz 关节面板）遥操头部。Taku 身体相对静止位大约在 x≈−0.21，不是 Bot2 的 [0, 0.25]。

在 RViz 中把 Fixed Frame 设为 base_link（或重合的 base_footprint）。OCS2 的 baseFrame / marker 使用 base_link。没有 hardware:=mock — 默认键是 mock_components。hardware:=gz 可能需要 GPU；默认验证路径是 mock + RViz。包 README 在同一套分体 / 全身启动上也列出了 hardware:=isaac。

ocs2_arm_controller 的 split_body.launch.py / full_body.launch.py 使用同一套 robot:=<key> → {key}_description 查找。Taku 带有 config/ocs2/（分体用 task.info，全身用 fixed_base_tcp.info）以及点名 ocs2_arm_controller / ocs2_wbc_controller 的 ros2_control yaml，因此 robot:=taku 是同一约定 — 不是单独特判的参数。

该描述是推断的（公开的 Dyna 运动学；不是官方 Dyna 规格）。包 README 写明了这一点。

空的私有目录与 `COLCON_IGNORE`¶

public 模式下，./init_repo.sh 会跳过 submodules_visibility.conf 里列出的私有嵌套模块。在 src/arms_ros2_control 下这些占位目录会保持为空，包括：

controller/ocs2_wbc_controller
libraries/lina_planning
libraries/ocs2_humanoid

空的私有 / 未初始化硬件目录会让 colcon build 失败（colcon 仍会走进去）。

当前 ./init_repo.sh 会给未初始化的嵌套路径写入 COLCON_IGNORE（包括 hardwares/* 和 private 可见性条目）。之后若做 private 初始化，会在克隆前去掉该标记。不必再手工 touch。

若 colcon 仍会走进空目录（检出早于该行为），先拉取 main 并再跑 ./init_repo.sh，或 touch <empty-dir>/COLCON_IGNORE。

编译¶

./init_repo.sh 已经对源码路径跑过 rosdep install。你仍需 colcon 编译：

colcon build --symlink-install

然后在启动终端执行 source install/setup.bash。README 除 ./init_repo.sh 外没有工作区环境脚本。

部分编译¶

仅编译指定软件包：

# Just descriptions
colcon build --packages-select robot-descriptions-dobot

# Up to a specific package
colcon build --packages-up-to ocs2_arm_controller

支持机器人¶

机器人	描述软件包	驱动层	说明
Dobot CR5	robot-descriptions-dobot	dobot-cr-ros2-control	`dobot-cr5` 分支
ARX X5	robot-descriptions-arx	arx-ros2-control	在 `arx-lift2s` 中联调
Acone / AC One	robot-descriptions-arx	arx-ros2-control	双臂（不是 Lift 2S）
方舟无限 Lift 2S	robot-descriptions-arx	arx-ros2-control	全身（手臂 + 升降 + 底盘）；分支 `arx-lift2s`
Galbot	robot-descriptions-galbot	（视情况而定）	面向仿真
高擎 Panthera HT	描述	ht-ros2-control	双臂；分支 `panthera-ht`；伞形仓路径 `manipulator/HighTorque/panthera_ht_description`
Taku（Dyna / DVT1）	`taku_description`	包内 xacro 的 mock / gz / isaac	`robot_descriptions` `feature/agilex` 仓内路径 `humanoid/Dyna/taku_description`；可视化用 `humanoid.launch.py`；控制用 `split_body.launch.py` / `full_body.launch.py`
四足机器人	robot-descriptions-quadruped	unitree-ros2-control	面向仿真

真实硬件部署

方舟无限 Lift 2S 是全身移动操作臂。Acone / AC One 是双臂。高擎 Panthera HT 是双臂操作臂。见方舟无限 Lift 2S、高擎 Panthera HT 和部署到真实机器人。

启动示例¶

模拟硬件演示¶

source install/setup.bash
ros2 launch ocs2_arm_controller demo.launch.py

demo.launch.py 默认：robot:=cr5、hardware:=mock_components。没有 hardware:=mock。

指定机器人¶

# Acone (dual-arm, not Lift 2S). Omit hardware:= to keep mock_components.
ros2 launch ocs2_arm_controller demo.launch.py robot:=arx_acone

# Taku (descriptions on feature/agilex). RViz Fixed Frame: base_link (or base_footprint).
ros2 launch ocs2_arm_controller split_body.launch.py robot:=taku

Taku 可视化路径（包 README）：ros2 launch robot_common_launch humanoid.launch.py robot:=taku。控制用 split_body.launch.py / full_body.launch.py — 编译、WBC 与 Fixed Frame 说明见 Taku / feature/agilex

末端执行器（`type`）¶

不是 gripper:=。对称末端：type:=<eef_key>。左右不同：同时传 left_type:= / right_type:=（此时不要再传 type:=）。use_profile_eef:=true（默认）时使用 profile 的 defaults.end_effectors。见 robot_common_launch。

ros2 launch ocs2_arm_controller demo.launch.py \
  robot:=<robot_name> \
  use_profile_eef:=false \
  left_type:=rg75 right_type:=linkerhand_o7

添加机器人描述¶

向工作空间添加新机器人：

优先用 ./init_repo.sh，让 src/robot-descriptions/ 下嵌套模块与 submodules_visibility.conf 一致。不要 git submodule update --init --recursive。然后 colcon build 所需软件包。

子模块管理¶

优先用 ./init_repo.sh（菜单 1 或 2），不要递归初始化子模块。用 git submodule status 查看状态。要更新已经初始化的某个源码树，pull 该模块再编译。

GitHub Release `.deb` 与源码对照表¶

组件	GitHub Release `.deb`	源路径
OCS2	`ros-jazzy-ocs2`（发行版）	`src/ocs2_ros2`
通用描述包	`ros-jazzy-robot-descriptions-common`（发行版）	`src/robot_descriptions/robot-descriptions-common`
arms_ros2_control	`ros-jazzy-arms-ros2-control`（可选；发行版）	`src/arms_ros2_control`

查看 deb_versions.conf 以了解 scripts/install_core_debs.sh 使用的 GitHub 仓库与发行标签。这些包不在 ROS apt 索引中。

常见问题¶

子模块为空¶

再跑 ./init_repo.sh（菜单 1）。不要把 git submodule update --init --recursive 当作主要恢复手段。

`cannot run ssh` / 子模块拒绝访问¶

.gitmodules 的 URL 是 SSH。仅靠 insteadOf 改写成 HTTPS 不能修好 git submodule update。当前 ./init_repo.sh 会在拉取时把 .gitmodules 改写成 HTTPS，结束后再还原 — 用 --https / OPEN_DEPLOY_GIT_HTTPS=1 强制走这条路径。

部分嵌套模块是私有的。在 open-deploy-ws 中只需公开嵌套模块。若出现访问错误：

确认当前位于正确的分支（不要误入私有分支）
确认该子模块在 submodules_visibility.conf 中列为公开
若空的私有目录仍导致 colcon 失败，再跑 ./init_repo.sh 让它写入 COLCON_IGNORE，或 touch <empty-dir>/COLCON_IGNORE

因 numpy 导致编译失败¶

pip install 'numpy<2'

需要重命名 CAN 接口¶

对于基于 CAN 的机器人，可能需要重命名接口：

sudo ip link set can0 down
sudo ip link set can0 name <expected_name>
sudo ip link set <expected_name> up

open-deploy-ws 配置¶

仓库 概述¶

克隆¶

SSH 远程 vs HTTPS / gh¶

初始化¶

核心模块选项（OCS2、arms、common）¶

CI / 非交互初始化¶

精简分支¶

目录结构¶

Taku / feature/agilex¶

空的私有目录与 COLCON_IGNORE¶

编译¶

部分编译¶

支持 机器人¶

启动示例¶

模拟硬件演示¶

指定机器人¶

末端执行器（type）¶

添加机器人描述¶

子模块管理¶

GitHub Release .deb 与源码对照表¶

常见问题¶

子模块为空¶

cannot run ssh / 子模块拒绝访问¶

因 numpy 导致编译失败¶

需要重命名 CAN 接口¶

下一步¶

仓库概述¶

SSH 远程 vs HTTPS / `gh`¶

Taku / `feature/agilex`¶

空的私有目录与 `COLCON_IGNORE`¶

支持机器人¶

末端执行器（`type`）¶

GitHub Release `.deb` 与源码对照表¶

`cannot run ssh` / 子模块拒绝访问¶