环境安装¶

本页介绍如何安装 FiveAges Sim 工作空间所需的基础开发环境。

操作系统¶

支持的主机： Ubuntu 24.04 LTS（Noble Numbat）+ ROS 2 Jazzy。

Python： 仅 3.12（Ubuntu 24.04 上的 ROS 2 Jazzy）。本技术栈不要使用 3.10/3.11 虚拟环境。

其他 Linux 发行版（例如 Debian 13）没有原生支持。在该主机上用 ubuntu:24.04 容器跑下面同一套 apt 步骤是可行做法。open-deploy-ws 没有发布官方 Docker 镜像，也没有额外容器参数；使用原版 Ubuntu 24.04 用户空间和官方 ROS 2 Jazzy Ubuntu 安装即可。

ROS 2 + rosdep 就绪后，按 open-deploy-ws README。工作区入口是 ./init_repo.sh；colcon build 之后，在启动终端 source install/setup.bash。

在裸机或容器上安装 ROS 2 Jazzy¶

在裸 Ubuntu 24.04 机器或容器上，python3-colcon-common-extensions、python3-rosdep 和 python3-vcstool 不在默认 Ubuntu 索引里。在加入 ROS 2 apt 源并执行 apt update 之前，apt install 这些包会报 “Unable to locate package”。

依据：Ubuntu（deb 包）— ROS 2 Jazzy。顺序：

添加 ROS 密钥 + Noble 的 ROS 2 apt 源
apt update
安装 ros-jazzy-desktop、ros-dev-tools，以及 colcon / rosdep / vcstool 工具
rosdep init / rosdep update

1. Enable Universe, then add the ROS 2 apt source¶

当前官方做法 — ros2-apt-source 包会装好签名密钥和 Noble 的 packages.ros.org 源：

sudo apt update
sudo apt install software-properties-common curl -y
sudo add-apt-repository universe

export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb

等价的手工添加源（同一思路：ros.key + Noble 的 ROS 2 列表），若不用 ros2-apt-source：

sudo apt install curl gnupg lsb-release -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}}) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

部分 Ubuntu 24.04 镜像里，/etc/apt/sources.list.d/ubuntu.sources 只列了基础 noble 套件。官方 Jazzy 文档：安装 ros-dev-tools 前先纳入 noble-updates 和 noble-backports，然后执行 sudo apt clean && sudo apt update && sudo apt full-upgrade -y。

在容器或 CI 任务里，export DEBIAN_FRONTEND=noninteractive 是常见的 apt 设置（不是 open-deploy-ws 的参数）。

2. Update, then install desktop + dev tools¶

sudo apt update
sudo apt install ros-jazzy-desktop ros-dev-tools
sudo apt install python3-colcon-common-extensions python3-rosdep python3-vcstool

ros-dev-tools 通常已经带上 colcon / rosdep / vcstool。第二行在它们已安装时是无害的，用来确认这些包名在 ROS apt 源已存在之后 能解析到。

3. Overlay and rosdep¶

source /opt/ros/jazzy/setup.bash
sudo rosdep init   # first time on this machine; skip if already initialized
rosdep update

完成后，克隆部署工作区并运行 ./init_repo.sh。CI / 无 TTY：./init_repo.sh --public --ocs2=deb --arms=source --common=source（当前 main；参数见 ./init_repo.sh --help）。细节：open-deploy-ws 配置。colcon build 之后再 source install/setup.bash。

可选捷径：fishros¶

open-deploy-ws README 把 fishros 写在最前面。该助手可以帮你添加 ROS apt 源并安装 Jazzy。它是可选捷径，不是唯一路径，也不适合无交互容器（安装器是菜单）。

wget http://fishros.com/install -O fishros && bash fishros
sudo apt update
sudo apt install ros-jazzy-desktop
sudo rosdep init
rosdep update

若没有 fishros，或 apt 仍然看不到 python3-colcon-common-extensions / ros-jazzy-desktop，用上面的官方 apt 源顺序。

安装 OCS2¶

OCS2（切换系统最优控制，Optimal Control for Switched Systems）是核心依赖。

OCS2 没有发布到 Debian / ROS apt 软件源。.deb 包名仍是 ros-jazzy-ocs2。不要把 sudo apt install 或手跑 dpkg -i 当作主路径。

使用 open-deploy-ws 或 fa-deploy-ws 的部署工作空间脚本。它们已经负责切换并安装 OCS2（GitHub Release .deb 或源码）。

cd ~/open-deploy-ws   # or fa-deploy-ws
./init_repo.sh

脚本做什么（摘自 open-deploy-ws README）：

菜单	作用
1) 初始化工作空间	先选嵌套可见性，再按模块选 `d`（GitHub Release `.deb`）或 `s`（源码）。OCS2 默认是 deb。
2) 切换模块安装方式	把已初始化模块在源码 ↔ deb 之间切换（清理冲突源码或卸载对应 deb）。用这个改 OCS2 安装路径。
3) 仅安装/更新核心 deb	跳过 Git；例如 `./scripts/install_core_debs.sh --only ocs2`
4) 卸载核心 deb	例如 `./scripts/uninstall_core_debs.sh --only ocs2`
5) 仅运行 rosdep	只对 `src/` 跑 `rosdep install`

选 d 会通过 scripts/install_core_debs.sh 下载匹配的 GitHub Release 资源。不会从 packages.ros.org 安装。init 之后仍需 colcon build。

手动回退

仅当你没有使用部署工作空间时。从 ocs2_ros2 Releases 下载匹配架构和 ROS 发行版的资源（文件名形如 ros-jazzy-ocs2_*_<arch>.deb），然后 sudo dpkg -i ros-jazzy-ocs2_*.deb；若 dpkg 报缺依赖再 sudo apt-get install -f。源码：把 ros2 分支克隆进 src/ — 或在 ./init_repo.sh 里选 s。

仿真依赖¶

Gazebo Harmonic¶

sudo apt install ros-jazzy-gz-*

Isaac Sim¶

使用 FaSim-Isaac 脚本。路径和版本写在配置里，不要在这些文档里写死某一个次版本号。

默认安装目录：ISAACSIM_DIR（除非在 config/fa_sim.local.conf 或环境变量里设置，否则为 ~/isaacsim）
可选 Isaac ROS 2 Jazzy 工作空间版本：./init.sh 操作 2 菜单（查询 GitHub 稳定 tag；回退列表见 config/fa_sim.conf，目前是 6.0.1 / 6.0.0 / 5.1.0）。用 ISAAC_SIM_VERSION=… ./init.sh 覆盖。

git clone git@github.com:fiveages-sim/FaSim-Isaac.git
cd FaSim-Isaac
./init.sh    # 1) submodules  2) optional Isaac ROS 2 Jazzy workspace
./run.sh     # menu: PhysX / Newton / Headless Streaming

复制 config/fa_sim.local.template.conf → config/fa_sim.local.conf 以修改 ISAACSIM_DIR 或默认版本。见 Isaac Sim 操作指南。

验证¶

./init_repo.sh 之后（若已克隆工作区则再加上 colcon build）：

ros2 --help
ros2 pkg list | grep ocs2   # after OCS2 deb or source via init

./init_repo.sh 已在源码路径上跑过 rosdep。不要把手工 ~/.bashrc source 链当作文档推荐配置。

常见问题¶

找不到软件包（colcon / rosdep / vcstool / ros-jazzy-desktop）¶

缺少 ROS 2 apt 源，或添加后没有执行 apt update。按在裸机或容器上安装 ROS 2 Jazzy 的官方顺序。只跑 sudo apt update 不会加入 packages.ros.org。

软件包 Not Found After apt install¶

这适用于源已配置之后、确实在 ROS apt 索引中的软件包（例如 ros-jazzy-desktop）。不适用于 OCS2。

sudo apt update

安装后找不到 OCS2¶

OCS2 不在 packages.ros.org / Ubuntu apt 中。sudo apt update 不会让 ros-jazzy-ocs2 出现。

在部署工作空间再跑 ./init_repo.sh：选 1 并为 OCS2 选 d，或选 3（./scripts/install_core_debs.sh --only ocs2）。要改已有安装，用菜单 2) 切换模块安装方式。

dpkg-query -W ros-jazzy-ocs2

rosdep 错误¶

rosdep update --include-eol-distros

Colcon Build Warnings¶

Most warnings can be ignored. For “missing resource index” warnings:

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

下一步¶

快速演示 — 克隆 open-deploy-ws，./init_repo.sh，构建并启动
open-deploy-ws 配置 — 工作区细节、SSH / CI 初始化、Taku