常见问题¶

常见问题与故障排除方案。

安装问题¶

问：`apt` 找不到 `python3-colcon-common-extensions` / `python3-rosdep` / `python3-vcstool`¶

这些包在 ROS 2 apt 索引里，不在原版 Ubuntu。在裸 24.04 主机或容器上，先添加 ROS 密钥 + Noble 的 ROS 2 源，再 apt update，然后才安装它们。完整顺序：环境安装。fishros 是可选捷径，不是唯一路径。

问： rosdep init fails with “already initialized”¶

如果以前使用过 ROS 2，这是正常现象。直接执行更新即可：

rosdep update

问：apt install 后找不到软件包¶

这适用于 ROS 2 apt 源已存在之后、确实在 ROS apt 索引中的软件包（例如 ros-jazzy-desktop）。装好 ROS 后，克隆部署工作区并运行 ./init_repo.sh，colcon build 之后 source install/setup.bash。

sudo apt update

问：用 apt 找不到 OCS2 `.deb`¶

OCS2 没有发布到 ROS 2 / Ubuntu apt 软件源。sudo apt install ros-jazzy-ocs2 找不到该包。

主路径： 在 open-deploy-ws / fa-deploy-ws 中运行 ./init_repo.sh。给 OCS2 选 d（菜单 1），用菜单 2 在源码 ↔ deb 之间切换，或用菜单 3 安装/更新（./scripts/install_core_debs.sh --only ocs2）。

要从源码构建，在 init（或菜单 2）时选 s。

手动回退

仅当你没有使用部署工作空间时，才从 ocs2_ros2 Releases 下载匹配资源并执行 sudo dpkg -i ros-jazzy-ocs2_*.deb。

子模块问题¶

问：克隆后子模块为空¶

在 open-deploy-ws / fa-deploy-ws 中再跑 ./init_repo.sh（菜单 1）。在 FaSim-Isaac / fa-py-libraries / lerobot_ros2 中再跑该仓库的 ./init.sh（或 ./init.sh all）。不要从递归的 git submodule update --init --recursive 开始。

问：`error: cannot run ssh: No such file or directory`¶

.gitmodules 使用 git@github.com:…。仅设置 git config url.https://github.com/.insteadOf git@github.com: 不能修好 git submodule update（嵌套仓读自己的 .gitmodules 并直接调 ssh）。当前 main 上的 ./init_repo.sh 会临时把这些 URL 改写成 HTTPS。用 --https / OPEN_DEPLOY_GIT_HTTPS=1 强制。步骤：open-deploy-ws 配置。

问：如何在 CI / 容器（无 TTY）里运行 `init_repo.sh`？¶

当前 open-deploy-ws main 上：

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

默认值与交互菜单相同。另外还有：--https / OPEN_DEPLOY_GIT_HTTPS=1、-y / --yes，以及环境变量 OPEN_DEPLOY_VISIBILITY、OPEN_DEPLOY_OCS2、OPEN_DEPLOY_ARMS、OPEN_DEPLOY_COMMON。其余见 ./init_repo.sh --help。若你的检出早于这些参数，先拉取 main。

问：子模块访问被拒绝¶

这通常表示正在访问没有权限的私有子模块，或远程仍是 SSH 而本机没有密钥。

对于 open-deploy-ws： 只需公开子模块。请确认：

当前位于正确的分支
该子模块在 submodules_visibility.conf 中列为公开
已有 ssh + 密钥，或已传入 --https / OPEN_DEPLOY_GIT_HTTPS=1

对于 fa-deploy-ws： 确认你的 GitHub SSH 密钥有权访问私有仓库：

ssh -T git@github.com

问：更新时出现子模块冲突¶

git submodule foreach git checkout .
git submodule update --init

编译问题¶

问：colcon 在 `arms_ros2_control` 下的空目录失败¶

public 初始化会把私有嵌套模块留空（controller/ocs2_wbc_controller、libraries/lina_planning、libraries/ocs2_humanoid，以及未初始化的 hardwares/*）。当前 public 模式的 ./init_repo.sh 会给这些空目录写入 COLCON_IGNORE。若 colcon 仍会走进其中某个目录（旧检出），先拉取 main 并再跑 ./init_repo.sh，或 touch <empty-dir>/COLCON_IGNORE。细节：open-deploy-ws 配置。

问：Taku 在哪里？¶

在 robot_descriptions 分支 feature/agilex 的 humanoid/Dyna/taku_description — 不在默认钉住的 main 子模块上。可视化：ros2 launch robot_common_launch humanoid.launch.py robot:=taku。控制：split_body.launch.py / full_body.launch.py，并传 robot:=taku（包 README §3.1 / §3.2）。公开 mock 是 split_body.launch.py；full_body.launch.py 需要私有 ocs2_wbc_controller 子模块。没有精简的 open-deploy-ws Taku 分支。检出步骤：open-deploy-ws 配置。

问：colcon build 因缺少依赖而失败¶

通过 rosdep 安装依赖：

rosdep install --from-paths src --ignore-src -r -y

问：numpy 版本冲突¶

部分软件包要求 numpy < 2：

pip install 'numpy<2'

问：CMake 找不到软件包¶

在已经跑过 ./init_repo.sh 的工作区构建。若缺少 ros2 / colcon，先完成安装环境。构建成功后，在启动终端 source install/setup.bash。

问：编译时内存不足¶

限制并行任务数：

colcon build --parallel-workers 2

或者只编译指定软件包：

colcon build --packages-up-to <package-name>

运行时问题¶

问：找不到节点/话题¶

确认已加载工作空间环境：

source install/setup.bash

检查节点是否在运行：

ros2 node list
ros2 topic list

问：控制器无法启动¶

请检查：

硬件参数与当前环境匹配（mock、gz、isaac 或真实硬件）
机器人参数与可用描述包匹配
所需驱动层插件已初始化（ros2 control list_hardware_interfaces）

ros2 launch ocs2_arm_controller demo.launch.py

问：机器之间无法通信¶

请确认：

两台机器上的 ROS Domain ID 一致
网络连通正常
防火墙允许 ROS 2 通信

# Check domain ID
echo $ROS_DOMAIN_ID

# Test connectivity
ros2 topic list  # Should show topics from both machines

CAN 接口问题¶

问：找不到 CAN 接口¶

检查接口是否存在：

ip link show

若接口名称不同，请将其重命名：

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

问：CAN 通信超时¶

确认 CAN 总线已正确端接
确认波特率与机器人配置一致
确保没有冲突的 CAN 通信

仿真问题¶

问：Gazebo 启动时崩溃¶

安装全部 Gazebo 软件包：

sudo apt install ros-jazzy-gz-*

若使用硬件渲染，请检查 GPU 驱动。

问：Isaac Sim 无法启动或脚本失败¶

使用 FaSim-Isaac 的 ./init.sh / ./run.sh。默认 Isaac 路径是 ISAACSIM_DIR（除非在 config/fa_sim.local.conf 覆盖，否则为 ~/isaacsim）。可选 Isaac ROS 2 工作空间版本来自 ./init.sh 操作 2 菜单（GitHub tag；回退见 config/fa_sim.conf：6.0.1 / 6.0.0 / 5.1.0）— 不要假定某一个写死的次版本号。

确认 ISAACSIM_DIR 目录存在，且包含 config/fa_sim.conf 中的启动脚本（isaac-sim.sh 等）
若 Isaac 不在 ~/isaacsim，复制 config/fa_sim.local.template.conf → config/fa_sim.local.conf
再跑 ./run.sh，从菜单选 PhysX / Newton / Headless Streaming（./run.sh 没有 --headless / --robot 参数）

问：Isaac Sim 连接失败¶

确认 Isaac Sim 正在运行（从 FaSim-Isaac 执行 ./run.sh）
确认话题桥接已激活
确认 launch 中已设置 hardware:=isaac
确认 Isaac 与 ROS 2 的 Domain ID 一致

网络配置¶

问：如何查找正确的 Domain ID？¶

Domain ID 因机器人而异。内部部署请查阅机器人文档或向团队负责人确认。使用模拟硬件开发时，任意 ID 均可（默认为 0）。

问：Zenoh 与 DDS 如何选择？¶

DDS（默认）： 同网通信即开即用
Zenoh： 更适合跨网络、NAT 穿透或高延迟链路

使用 Zenoh：

sudo apt install ros-jazzy-rmw-zenoh-cpp
export RMW_IMPLEMENTATION=rmw_zenoh_cpp

获取帮助¶

如果这里没有覆盖你的问题：

查看相关软件包的 README
在仓库中搜索已有的 GitHub issues
新建 issue，并提供：
- Ubuntu/ROS 2 版本
- 复现步骤
- 完整错误信息
- 相关的 launch 命令

问题跟踪：

文档：fiveages-sim/docs/issues
手臂控制器：fiveages-sim/arms_ros2_control/issues
描述包：fiveages-sim/robot_descriptions/issues

常见问题¶

安装问题¶

问：apt 找不到 python3-colcon-common-extensions / python3-rosdep / python3-vcstool¶

问： rosdep init fails with “already initialized”¶

问：apt install 后找不到软件包¶

问：用 apt 找不到 OCS2 .deb¶

子模块问题¶

问：克隆后子模块为空¶

问：error: cannot run ssh: No such file or directory¶

问：如何在 CI / 容器（无 TTY）里运行 init_repo.sh？¶

问：子模块访问被拒绝¶

问：更新时出现子模块冲突¶

编译问题¶

问：colcon 在 arms_ros2_control 下的空目录失败¶

问：Taku 在哪里？¶

问：colcon build 因缺少依赖而失败¶

问：numpy 版本冲突¶

问：CMake 找不到软件包¶

问：编译时内存不足¶

运行时问题¶

问：找不到节点/话题¶

问：控制器无法启动¶

问：机器之间无法通信¶

CAN 接口问题¶

问：找不到 CAN 接口¶

问：CAN 通信超时¶

仿真问题¶

问：Gazebo 启动时崩溃¶

问：Isaac Sim 无法启动或脚本失败¶

问：Isaac Sim 连接失败¶

网络配置¶

问：如何查找正确的 Domain ID？¶

问：Zenoh 与 DDS 如何选择？¶

获取帮助¶

问：`apt` 找不到 `python3-colcon-common-extensions` / `python3-rosdep` / `python3-vcstool`¶

问：用 apt 找不到 OCS2 `.deb`¶

问：`error: cannot run ssh: No such file or directory`¶

问：如何在 CI / 容器（无 TTY）里运行 `init_repo.sh`？¶

问：colcon 在 `arms_ros2_control` 下的空目录失败¶