Skip to main content

View as Markdown

Page content converted to Markdown. Use the original page link at the end to explore interactive graphics.

ROS2

This tutorial connects kinematics, ROS2 engineering, and MoveIt 2 planning through a working two-link arm example. It is for developers who want to assemble and run a robot system, from the equations to the complete application.

A two-link arm plans around an obstacle in RViz2

A two-link arm plans around an obstacle in RViz2

The final demonstration shows the end effector following a planned trajectory with ROS2 Jazzy and MoveIt 2.

1. Why study this tutorial​

Knowing individual concepts is often easier than connecting them. This tutorial addresses three gaps:

  • Math to engineering: derive FK/IK and implement reusable functions.
  • Nodes to systems: combine Topics, Services, Actions, parameters, and Launch files.
  • Models to planning: integrate tf2, URDF, and MoveIt 2 into one planning system.

2. Topics covered​

LessonMain topicsPractical result
1. System introductionSix robot layers, ROS2, learning sequenceA system overview
2. Kinematics and transformsFrames, rotation, translation, homogeneous transformsFoundations for FK
3. Forward and inverse kinematicsTwo-link FK/IK derivation and implementationReusable functions
4. ROS2 engineeringWorkspaces, packages, nodesMove from scripts to packages
5. TopicsPublishers, subscribers, message typesContinuous communication
6. Services and ActionsRequests, responses, long-running tasksIK service and action execution
7. Parameters and LaunchConfiguration and coordinated startupCentralized node configuration
8. tf2Transform trees, broadcasting, lookupConsistent coordinate frames
9. URDF and robot_state_publisherRobot models and state publicationModel-driven TF
10. MoveIt 2 basicsSetup and motion planningVisualize the first plan
11. MoveIt 2 projectTarget input, IK, planning, executionAn integrated simulated system
12. Review and next stepsReview, adaptation, extensionsA path for further learning

3. Lessons​

The detailed lessons are currently in Chinese.

4. Suggested sequence​

Introduction → Kinematics (2–3) → ROS2 engineering (4–7) → Frames and models (8–9) → MoveIt 2 (10–11) → Review (12)

If time is limited, prioritize 1 → 3 → 5 → 8 → 9 → 10 → 11 to assemble a working system.

Environment setup​

The companion code is included at codes/foundations/robotics-and-ros2/ros_ws. The old ros_learning path is obsolete; no separate project of that name is needed. See the code README for dependencies and staged instructions.

Prepare Ubuntu 24.04 and ROS2 Jazzy following lesson 1. The commands below use Bash. Run the first two lines only if you have not cloned the repository; otherwise enter its root directory:

git clone https://github.com/datawhalechina/dive-into-embodied-ai.git
cd dive-into-embodied-ai

export ROS_WS="$(pwd)/codes/foundations/robotics-and-ros2/ros_ws"
echo "$ROS_WS"

The output is an absolute path such as /home/yourname/dive-into-embodied-ai/codes/foundations/robotics-and-ros2/ros_ws. Set ROS_WS in each new terminal, or add an export ROS_WS="..." line with that absolute path to ~/.bashrc. Images and videos use Git LFS; see the contributor guide for downloading all assets.

Companion code​

  • $ROS_WS/scripts/: standalone examples for lessons 2–3. Install NumPy; ROS is not needed.
  • $ROS_WS/src/: your exercise packages, initially empty. Create them as you follow the lessons.
  • $ROS_WS/reference/src/: reference packages assembled from the tutorial. Copy individual files as instructed. Keep reference/COLCON_IGNORE to prevent duplicate package discovery.
PackageContents
my_robot_basicsKinematics, basic nodes, parameters, and tf2 (4–8)
my_robot_interfacesCustom Service/Action interfaces (6)
my_robot_descriptionURDF and visualization Launch files, including lesson 10 ros2_control tags (9–10)
my_robot_plannerPlanning clients (10–11)
my_robot_bringupSystem Launch file (11)

Generate my_robot_moveit_config with MoveIt Setup Assistant in lesson 10; it is not bundled. That lesson's demo_sim.launch.py is stored separately in $ROS_WS/reference/moveit/ for copying after configuration generation. The code README explains how to build lessons 4–9 before moving on to MoveIt.

The reference packages incorporate changes from later lessons for comparison. ROS, RViz2, and MoveIt experiments require Ubuntu / Jazzy; math scripts and static checks do not replace full runtime validation.

Usage notes​

  • The tutorial defaults to ROS2 Jazzy on Ubuntu 24.04. When using another distribution, substitute its name for jazzy; the core concepts remain the same.
  • The MoveIt 2 lessons distinguish C++ MoveGroupInterface from Python moveit_py.
  • Shell examples consistently use vim to edit files.