RISC-V ROS2 机器人操作系统编程技术

课程介绍

本课程以 RISC-V 开源硬件平台（openEuler 24.03 LTS）为硬件基础，以 ROS2（Robot Operating System 2）Humble 为技术平台，系统讲授机器人的软件开发框架、分布式通信机制、实时控制系统以及智能终端装调技术。课程 ROS2 程序运行在 openEuler RISC-V 板卡上，Gazebo、RViz2 等仿真与可视化环境运行在 Windows x86 主机上，两端通过局域网内同一 DDS 域互联。

教学目标

课程大纲

Part 1: ROS2 编程基础（RISC-V 机器人终端软件平台，36 课时）

Part 2: SLAM 与自主导航（RISC-V 机器人环境感知与决策，62 课时）

Part 3: 机械臂编程技术（具身智能机器人操作系统，52 课时）

理论章节与实验手册对照

教学文档和课件仍按 35 个理论章节组织；实验代码和实验手册按 src/lab_code/ 的 21 个实验组织。多个理论章节共用一个综合实验手册，实验手册编号与代码目录保持一致。

课程资料索引

理论章节

实验手册

K3 平台适配

K3 Pico-ITX 第 1 章适配：先阅读公共双端环境，再完成第 1 章实验。运行证据与交付状态按章节记录；运行支持文件见 course_support/k3。 教师／课程文档见 K3 第一章教案。

原版课程使用 teaching_docs/、lab_manuals/ 和 src/；C++ / RISC-V K3 版使用 teaching_docs_k3_pico_itx/、lab_manuals_k3_pico_itx/ 和 src_k3_pico_itx/。K3 第一章源码通过 setup_course_k3.sh 在独立工作区 ~/ros2_course_k3_ws 构建。

COM260 Kit 第 1～6 章适配：公共环境、第一章实验、第二章实验、第三章实验、第四章实验、第五章实验、第六章实验、第一章教案、第二章教案、第三章教案、第四章教案、第五章教案、第六章教案及COM260 实测证据。

课时汇总

目录结构

ROS2/
├── README.md                    # 本文件，课程总览
├── teaching_docs/               # 教学文档（35 章，含 images/）
├── lecture_slides/              # 教学课件（35 章）
├── lab_manuals/                 # 实验手册（21 个，含 images/）
└── src/                         # ROS2 课程源码（46 个可构建包；ch16_lab 为非功能包示例）
    ├── topic_demo_cpp/          # 话题通信 C++ 示例（车载传感器数据流）
    ├── topic_demo_py/           # 话题通信 Python 示例
    ├── topic_demo_interfaces/   # 话题通信自定义接口
    ├── service_demo_cpp/        # 服务通信 C++ 示例（远程诊断指令）
    ├── service_demo_py/         # 服务通信 Python 示例
    ├── service_demo_interfaces/ # 服务通信自定义接口
    ├── action_demo_cpp/         # 动作通信 C++ 示例（路径规划任务）
    ├── action_demo_py/          # 动作通信 Python 示例
    ├── action_demo_interfaces/  # 动作通信自定义接口
    ├── msgs_demo_interfaces/    # 消息接口定义
    ├── param_demo_cpp/          # 参数 C++ 示例
    ├── param_demo_py/           # 参数 Python 示例
    ├── tf_demo_cpp/             # TF2 C++ 示例（多传感器标定）
    ├── tf_demo_py/              # TF2 Python 示例
    ├── name_demo_cpp/           # 节点命名 C++ 示例
    ├── robot_sim_demo/           # TurtleBot3 Burger + ISCAS Museum Gazebo 仿真
    ├── navigation_sim_demo_ros2/ # 导航仿真
    ├── slam_sim_demo_ros2/      # SLAM 仿真
    ├── urdf_demo_ros2/          # URDF 建模示例
    ├── tf_follower_ros2/        # TF 跟随机器人
    ├── xarm/                    # xArm6 + MoveIt2 仿真
    ├── xarm_description/        # xArm6 URDF、mesh 和 ros2_control 描述
    ├── course_lab_interfaces/   # 课程实验共享接口
    ├── course_lab_utils/        # 课程实验共享实现
    └── lab_code/                # 实验代码（21 章，ch01_lab/ ~ ch21_lab/）

环境要求

课程采用板卡 + 主机双端架构：

板卡端（课程程序运行平台）

• 操作系统： openEuler 24.03 LTS（riscv64），桌面环境可选
• ROS2 版本： Humble（openEuler ROS SIG 软件源）
• Python： 3.11（openEuler 系统 Python）
• 磁盘空间： 至少 15GB
• 可选硬件： RealSense、USB 摄像头、串口机械臂或 PAV-S 实训平台

主机端（仿真与可视化平台，Windows x86）

• Gazebo 仿真与 RViz2 可视化： 推荐使用 Windows 主机的 WSL2（Ubuntu 24.04 + ROS 2 Jazzy）；Ubuntu 22.04 + ROS 2 Humble 适用于课程兼容环境
• 互联： 主机与板卡处于同一局域网，共用 ROS_DOMAIN_ID 与 CycloneDDS，主机端 RViz2/Nav2 可视化并操控板卡上的课程节点

机器人端（K3/Licheepi4A Linux RISC-V）

• 机器人： TurtleBot3 Burger
• 开发板 + 操作系统： K3/Licheepi4A + openEuler/openKylin/?

安装器优先通过 package.xml 和 rosdep 解析 ROS 依赖。NumPy、OpenCV、SciPy

等 ABI 敏感依赖由 dnf 安装；ML 依赖进入独立 venv，不会覆盖 cv_bridge 使用的

系统 Python 包。Gazebo、RViz2 没有 riscv64 软件包，一律不安装到板卡。

快速开始

# 板卡端默认：配置 RISC-V 软件源 + ROS2 Humble + src/lab 依赖 + 编译课程包 + ~/.bashrc 配置
bash setup_course.sh
 
# 先检查将执行的安装命令
bash setup_course.sh --dry-run
 
# 安装后验证
bash setup_course.sh --verify

默认安装不包含体积较大或依赖硬件的组件，可按需组合 profile：

# FilterPy、OpenAI、EVO（安装到独立 venv，riscv64 上部分需要源码编译）
bash setup_course.sh --with-ml
 
# USB Camera 和串口依赖
bash setup_course.sh --with-hardware
 
# 启用全部 profile，并在编译后运行 colcon 测试
bash setup_course.sh --all-profiles --run-tests

纯净 Ubuntu 安装 ROS2（主机端）

以下步骤适用于新安装的 Ubuntu 主机或 WSL2。Ubuntu 24.04 使用 ROS 2 Jazzy，Ubuntu 22.04 使用 ROS 2 Humble；当前仓库的 Gazebo、MoveIt 2 和 xArm6 主机仿真已在 Ubuntu 22.04 + ROS 2 Jazzy 环境中完成验证，优先推荐 Jazzy。setup_course.sh 是 openEuler RISC-V 板卡端安装器，不要在 Ubuntu/WSL 主机端执行。

1. 配置 ROS2 官方软件源

sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
 
sudo apt update
sudo apt install -y software-properties-common curl ca-certificates
sudo add-apt-repository universe
 
sudo curl -L 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) main" | \
sudo tee /etc/apt/sources.list.d/ros2.list >/dev/null
sudo apt update

2. 安装 ROS2 和开发工具

根据 Ubuntu 版本选择一个发行版，不要同时安装两套 ROS2：

# Ubuntu 24.04 LTS：推荐用于 Gazebo、MoveIt 2 和 xArm6 主机仿真
export ROS_DISTRO=jazzy
sudo apt install -y ros-jazzy-desktop
 
# Ubuntu 22.04 LTS：课程 Humble 兼容环境，改用上一段后不要重复执行
# export ROS_DISTRO=humble
# sudo apt install -y ros-humble-desktop

安装编译、依赖解析和课程 Python 节点所需工具：

sudo apt install -y \
  build-essential cmake git \
  python3-pip python3-rosdep python3-colcon-common-extensions python3-vcstool \
  python3-numpy python3-opencv python3-yaml ffmpeg

3. 初始化环境并安装源码依赖

sudo rosdep init
rosdep update
echo "source /opt/ros/${ROS_DISTRO}/setup.bash" >> ~/.bashrc
source ~/.bashrc
 
cd /path/to/ROS2
rosdep install --from-paths src --ignore-src --rosdistro "${ROS_DISTRO}" -r -y

4. 编译和验证课程源码

从仓库根目录使用 --base-paths src，避免把根目录中的非 ROS 文件夹当成软件包：

cd /path/to/ROS2
colcon list --base-paths src --names-only | sort -u | wc -l  # 应为 46
colcon build --base-paths src --symlink-install \
  --event-handlers console_cohesion+ \
  --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
source install/setup.bash
colcon test --base-paths src --executor sequential \
  --return-code-on-test-failure
colcon test-result --verbose

当前源码应发现并安装 46 个 ROS 2 包；src/lab_code/ch16_lab/ 是不带 package.xml 的纯文件 示例，不属于遗漏的构建包。安装后可检查：

find -L install -path '*/share/ament_index/resource_index/packages/*' -type f | wc -l  # 应为 46
test -f install/setup.bash && echo 'ROS 2 workspace ready'

机械臂安装（Windows x86 主机端）

下面的 xArm6 机械臂仿真步骤在 Windows x86 主机端执行（WSL2 或 Windows 原生），不安装在 openEuler RISC-V 板卡上。本次验证环境为 WSL2 Ubuntu 22.04 + ROS 2 Jazzy；使用 Humble 时将发行版名替换为 humble。

xArm6 机械臂仿真

1. 安装依赖并编译课程包

cd /path/to/ROS2
 
# 主机端需预先安装 ROS 2、ros2_control、MoveIt 2、Gazebo Harmonic 和 RViz2
source /opt/ros/jazzy/setup.bash
colcon build --base-paths src --symlink-install \
  --packages-select xarm_description xarm_ros2_arm_only
source install/setup.bash

本项目的 xarm_ros2_arm_only 位于 src/xarm/，兼容的 xarm_description 已包含在 src/xarm_description/。安装后检查：

ros2 pkg prefix xarm_description
ros2 pkg prefix xarm_ros2_arm_only
ros2 pkg prefix moveit_ros_move_group
ros2 pkg prefix gz_ros2_control

如果只需要重新构建机械臂包：

cd /path/to/ROS2
colcon build --symlink-install --packages-select xarm_description xarm_ros2_arm_only
source install/setup.bash

2. 启动和验证机械臂

完整模式会启动 Gazebo、ros2_control、MoveIt 2 和 RViz2：

source install/setup.bash
ros2 launch xarm_ros2_arm_only arm_only.launch.py

完整模式启动后，另开一个终端执行动作序列；启动命令本身只负责保持仿真和 RViz2 运行：

source install/setup.bash
ros2 run xarm_ros2_arm_only arm_only_moveit_sequence --timeout 60

只查看 RViz2 中的机械臂和 MoveIt MotionPlanning 面板时，可使用轻量模式：

ros2 launch xarm_ros2_arm_only arm_only.launch.py \
  use_gazebo:=false use_sim_time:=false

完整模式启动后，在另一个已加载环境的终端中验证规划链路：

ros2 control list_controllers
ros2 topic echo /joint_states --once
ros2 run xarm_ros2_arm_only arm_only_runtime_smoke

启动后的 xArm6 Gazebo/MoveIt 动作画面（约 71 秒录制）：

源码会使用 rsync --delete 同步到脚本管理的 ~/ros2_course_ws：课程 ROS 包位于

src/course/，实验代码位于 src/labs/；源码树中的 src/lab_code/ 不会再次复制到

src/course/，以避免嵌套实验包重复发现。比如源码中的 src/xarm/ 在托管工作空间中

对应 src/course/xarm/。这样也能避开 WSL 中 /mnt/c 的编译性能和中文路径问题。

脚本不会修改已有的非托管工作空间；可通过 --workspace /absolute/path 选择新的目标目录。

安装完成后重新打开终端，或执行：

 
source ~/.config/ros2-course/env.bash
 
cd ~/ros2_course_ws

Gazebo 仿真启动（robot_sim_demo）

robot_sim_demo 使用 Gazebo Sim 启动 TurtleBot3 Burger 机器人（官方 ROBOTIS 网格与尺寸参数）。原有 gazebo2.launch.py 继续使用 ISCAS Museum 的 museum.sdf；新增 campus_pucrs.launch.py 使用 Campus PUCRS 的 campus_pucrs.world.sdf，并将车辆 放在黄色 X 标志中心 (20.0, 0.0) 的无障碍区域。

默认启动（Gazebo + 机器人 + 自动巡航）

source ~/ros2_course_ws/install/setup.bash
ros2 launch robot_sim_demo gazebo2.launch.py

默认启动 GUI 和自动巡航，RViz 默认关闭。需要手动控制时，先关闭自动巡航：

 
ros2 launch robot_sim_demo gazebo2.launch.py rviz:=true drive:=false

然后在另一终端运行键盘控制：

ros2 run teleop_twist_keyboard teleop_twist_keyboard

Campus PUCRS 世界

 
ros2 launch robot_sim_demo campus_pucrs.launch.py

Campus 入口默认启动 GUI、传感器桥和 RViz 可选项，但不自动巡航；车辆初始位姿 为 x=20.0, y=0.0, z=0.010, yaw=0.0，对应世界中黄色标志的中心。

Launch 参数

常用启动方式

# 无 GUI、无 RViz、无自动巡航
ros2 launch robot_sim_demo gazebo2.launch.py gui:=false rviz:=false drive:=false
 
# 启动 RViz 并关闭自动巡航
ros2 launch robot_sim_demo gazebo2.launch.py rviz:=true drive:=false
 
# 自定义机器人生成位置
ros2 launch robot_sim_demo gazebo2.launch.py \
  spawn_x:=1.0 spawn_y:=0.5 spawn_z:=0.010 spawn_yaw:=1.57

仿真包关键节点与话题

常用验证命令：

 
ros2 topic echo /odom --once
 
ros2 topic echo /scan --once
 
ros2 topic echo /camera/camera_info --once
 
ros2 topic hz /camera/image_raw

xArm MoveIt2 演示启动（xarm_ros2_arm_only）

xarm_ros2_arm_only 包位于 src/xarm/，为 xArm6 纯机械臂提供 Gazebo Harmonic、 ros2_control、MoveIt2 和 RViz 集成。兼容的 xarm_description 已包含在 src/xarm_description/，不需要另外准备底层描述包。

完整 MoveIt2 演示（含 RViz、move_group 和 Gazebo）

source install/setup.bash
 
# 启动完整 xArm6 仿真环境
ros2 launch xarm_ros2_arm_only arm_only.launch.py

此 Launch 文件启动：

• tf2_ros static_transform_publisher（world → base_link 静态变换）
• robot_state_publisher（发布机器人 TF）
• controller_manager + ros2_control 控制器
• move_group（MoveIt2 运动规划核心）
• RViz2（含 MoveIt2 MotionPlanning 插件）

启动后可在 RViz2 中通过 Interact 模式拖拽机械臂末端设定目标位姿，点击 Plan & Execute 执行运动规划。

仅启动 MoveIt2（不含 Gazebo）

 
ros2 launch xarm_ros2_arm_only arm_only.launch.py \
 
  use_gazebo:=false use_sim_time:=false

该模式使用 MoveIt mock components，适用于纯运动学验证和规划预览。

常用启动变体

# Gazebo 无头运行，不启动 RViz
ros2 launch xarm_ros2_arm_only arm_only.launch.py \
  gz_headless:=true use_rviz:=false
 
# 启动独立的 MoveIt2 + RViz launch
ros2 launch xarm_ros2_arm_only arm_only_move_group.launch.py use_rviz:=true
 
# 调整机械臂固定底座高度
ros2 launch xarm_ros2_arm_only arm_only.launch.py base_height:=0.20

包结构与关键配置

src/xarm/
├── config/
│   ├── arm_only_kinematics.yaml # 运动学求解器配置
│   ├── arm_only_joint_limits.yaml # 关节限位配置
│   ├── arm_only_ompl_planning.yaml # OMPL 规划器参数
│   ├── arm_only_controllers.yaml # ros2_control 控制器配置
│   ├── moveit_controllers.yaml # MoveIt2 控制器映射
│   ├── xarm.srdf              # 语义机器人描述（碰撞矩阵、组定义）
│   └── arm_only_moveit.rviz   # RViz MotionPlanning 配置
├── launch/
│   ├── arm_only.launch.py      # Gazebo + ros2_control + MoveIt2
│   └── arm_only_move_group.launch.py # MoveIt2 + RViz
├── urdf/
│   └── arm_only_xarm.urdf.xacro
└── worlds/
    └── arm_only.sdf

前置依赖：板卡端依赖由 setup_course.sh 和 rosdep 安装；Ubuntu 主机端依赖由本节的 apt 和 rosdep 步骤安装。机械臂 URDF 模型定义在 xarm_description 包中，meshes 文件位于 xarm_description/meshes/。

备注：

1. openEuler(x86/arm/RISC-V)下ROS2的安装

openEuler 24.03（x86 / ARM / RISC-V）安装 ROS2 Humble

课程安装器 setup_course.sh 默认即面向 openEuler 24.03 RISC-V；如只需安装 ROS2 Humble 本体（不编译课程包），可直接使用官方 ROS SIG 软件源：

# RISC-V 板卡一键安装（配置软件源 + 安装 ros-humble-* + 写入 ~/.bashrc）
sudo bash scripts/install_ros2_humble_riscv.sh
 
# 激活环境
source ~/.bashrc
 
# 测试小乌龟
ros2 run turtlesim turtlesim_node      # 终端1
ros2 run turtlesim turtle_teleop_key   # 终端2

要点（依据 openEuler 24.03 LTS SP3 官方《安装与部署》文档）：

openEuler 上 ROS 版本为 Humble。Gazebo、RViz2 openEuler RISC-V 有 riscv64 软件包，考虑到性能问题，统一运行在 Windows x86 主机端，与板卡共用同一局域网 DDS 域；RISC-V 源暂无 Noetic（ROS1）软件包。