diff --git a/sphinx_doc/howtos/index.rst b/sphinx_doc/howtos/index.rst index a2e068d9eb..b69ccd03e6 100644 --- a/sphinx_doc/howtos/index.rst +++ b/sphinx_doc/howtos/index.rst @@ -6,5 +6,6 @@ How-Tos .. toctree:: :maxdepth: 1 + tutorials/index.rst docs/index.rst tunning/index.rst diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png new file mode 100644 index 0000000000..8c91a80d58 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png new file mode 100644 index 0000000000..ed5f5d2080 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png new file mode 100644 index 0000000000..1cb3a59609 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png new file mode 100644 index 0000000000..2475fa6e9c Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png new file mode 100644 index 0000000000..42fa031eb8 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_robot_reached_goal.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_robot_reached_goal.png new file mode 100644 index 0000000000..a14a4261f6 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_robot_reached_goal.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_turlebot3.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_turlebot3.png new file mode 100644 index 0000000000..b5776b16f4 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_turlebot3.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/navigation_with_recovery_behaviours.gif b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/navigation_with_recovery_behaviours.gif new file mode 100644 index 0000000000..58fd51cb78 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/navigation_with_recovery_behaviours.gif differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_initial_view.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_initial_view.png new file mode 100644 index 0000000000..5a1a4e505b Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_initial_view.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_robot_navigating.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_robot_navigating.png new file mode 100644 index 0000000000..aadbe2c040 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_robot_navigating.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_send_goal_pose.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_send_goal_pose.png new file mode 100644 index 0000000000..5f67ba5190 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_send_goal_pose.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_set_initial_pose.png b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_set_initial_pose.png new file mode 100644 index 0000000000..2b77d4ea68 Binary files /dev/null and b/sphinx_doc/howtos/tutorials/docs/images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_set_initial_pose.png differ diff --git a/sphinx_doc/howtos/tutorials/docs/navigation2_on_real_turtlebot3.rst b/sphinx_doc/howtos/tutorials/docs/navigation2_on_real_turtlebot3.rst new file mode 100644 index 0000000000..6ced5b45c9 --- /dev/null +++ b/sphinx_doc/howtos/tutorials/docs/navigation2_on_real_turtlebot3.rst @@ -0,0 +1,145 @@ +.. _navigation2-on-real-turtlebot3: + +Navigation2 on a Physical Turtlebot 3 +************************************* + +- `Overview`_ +- `Requirements`_ +- `Tutorial Steps`_ +- `Videos`_ + +Overview +======== + +This tutorial shows how to control and navigate Turtlebot 3 using the ROS2 Navigation2 on a physical Turtlebot 3 robot. +Before completing this tutorials, completing the :ref:`navigation2-with-turtlebot3-in-gazebo`. is highly recommended especially if you are new to ROS and Navigation2. + +This tutorial consists of two parts. In the first part, you learned how to use Turtlebot 3 robots in simulation (Gazebo). +In this part, you will learn how to control a physical Turtlebot Waffle using Navigation2. + +``ROS2 Dashing`` and ``Navigation2 Dashing 0.2.4`` are used to create this tutorial. +You should be able to do this tutorial using other Navigation2 versions as well. + +This tutorial may take about 1 hour to complete. +It depends on your experience with ROS, robots, and what computer system you have. + +Requirements +============ + +You must install Navigation2, Turtelbot3. +If you don't have them installed, please follow the steps in the previous tutorial. :ref:`navigation2-with-turtlebot3-in-gazebo` + +Tutorial Steps +============== + +0- Setup Your Enviroment Variables +---------------------------------- + +Run the following commands first whenever you open a new terminal during this tutorial. + +- ``source /opt/ros//setup.bash`` +- ``export TURTLEBOT3_MODEL=waffle`` + +1- Launch Turtlebot 3 Robot State Publisher +------------------------------------------- + +Launch Turtlebot 3 robot state publisher, + + ``ros2 launch turtlebot3_bringup turtlebot3_state_publisher.launch.py use_sim_time:=False`` + +Note: use_sim_time is set to **False** because we're on a physical robot. + +2- Launch Navigation2 +--------------------- + +You need to have a map of the environment where you want to Navigate Turtlebot 3, or create one live with SLAM. + +In case you are interested, there is a use case tutorial which shows how to use Navigation2 with SLAM. +`Navigation2 with SLAM `_ + +Required files: + + - ``your-map.map`` + - ``your-map.yaml`` + +``.yaml`` is the configuration file for the map we want to provide Navigation2. +In this case, it has the map resolution value, threshold values for obstacles and free spaces, and a map file location. +You need to make sure these values are correct. +More information about the map.yaml can be found `here `_. + +Launch Navigation 2. If you set autostart:=False, you need to click on the start button in RViz to initialize the nodes. +Make sure `use_sim time` is set to **False**, because we want to use the system time instead of the time simulation time from Gazebo. + +``ros2 launch nav2_bringup nav2_bringup_launch.py use_sim_time:=False autostart:=False map:=/path/to/your-map.yaml`` + +Note: Don't forget to change **/path/to/your-map.yaml** to the actual path to the your-map.yaml file. + +3- Launch RVIZ +--------------- + +Launch RVIZ with a pre-defined configuration file. + + ``ros2 run rviz2 rviz2 -d $(ros2 pkg prefix nav2_bringup)/share/nav2_bringup/launch/nav2_default_view.rviz`` + +Now, you should see a shadow of Turtlebot 3 robot model in the center of the plot in Rviz. +Click on the Start button (Bottom Left) if you set the auto_start parameter to false. + +.. image:: images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png + :height: 720px + :width: 1024px + :alt: RViz after launch, auto_start = False + +Now, the map should appear in RViz. + +.. image:: images/Navigation2_on_real_Turtlebot3/rviz_slam_map_view.png + :height: 720px + :width: 1024px + :alt: A map generated by using SLAM in RViz + +4- Initialize the Location of Turtlebot 3 +----------------------------------------- + +First, find where the robot is on the map. Check where your robot is in the room. + +Set the pose of the robot in RViz. +Click on the 2D Pose Estimate button and point the location of the robot on the map. +The direction of the green arrow is the orientation of Turtlebot. + +.. image:: images/Navigation2_on_real_Turtlebot3/rviz_set_initial_pose.png + :height: 720px + :width: 1024px + :alt: Set initial pose in RViz + +Now, the 3D model of Turtlebot should move to that location. +A small error in the estimated location is tolerable. + +5- Send a Goal Pose +-------------------- + +Pick a target location for Turtlebot on the map. +You can send Turtlebot 3 a goal position and a goal orientation by using the **Navigation2 Goal** or the **GoalTool** buttons. + +Note: Navigation2 Goal button uses a ROS2 Action to send the goal and the GoalTool publishes the goal to a topic. + +.. image:: images/Navigation2_on_real_Turtlebot3/rviz_send_goal.png + :height: 720px + :width: 1024px + :alt: Send goal pose in RViz + +Once you define the target pose, Navigation2 will find a global path and start navigating the robot on the map. + +.. image:: images/Navigation2_on_real_Turtlebot3/rviz_robot_navigating.png + :height: 720px + :width: 1024px + :alt: Robot navigating in RViz + +Now, you can see that Turtlebot 3 moves towards the goal position in the room. See the video below. + +Videos +------ + +.. raw:: html + +
+ +
diff --git a/sphinx_doc/howtos/tutorials/docs/navigation2_with_turtlebot3_in_gazebo.rst b/sphinx_doc/howtos/tutorials/docs/navigation2_with_turtlebot3_in_gazebo.rst new file mode 100644 index 0000000000..1396c5c73a --- /dev/null +++ b/sphinx_doc/howtos/tutorials/docs/navigation2_with_turtlebot3_in_gazebo.rst @@ -0,0 +1,192 @@ +.. _navigation2-with-turtlebot3-in-gazebo: + +Navigation2 with Turtlebot 3 in Gazebo +************************************** + +- `Overview`_ +- `Requirements`_ +- `Tutorial Steps`_ +- `Videos`_ + +Overview +======== + +This tutorial shows how to control and navigate Turtlebot 3 using the ROS2 Navigation2 in Gazebo. +Turtlebot is a low-cost, educational robot kit with open-source software (ROS2). +Turtblebot robots are widely supported by the ROS community. +You can find many applications and examples of Turtlebot projects on the Internet. +You can find more information about Turtlebot3 `here. `_ + +Links to the robot kits and Github repo. + + - `Turtlebot3 Kits `_ + - `Turtlebot 3 Github `_ + +This tutorial consists of two parts. +In the first part, you will learn how to use Turtlebot 3 robots in simulation (Gazebo). +And in the second part, you will learn how to control a real Turtlebot Waffle using Navigation2. + +``ROS2 Dashing`` and ``Navigation2 Dashing 0.2.4`` are used to create this tutorial. + +This tutorial may take about 30 minutes to complete. It depends on your experience with ROS, robots, and what computer system you have. + +Requirements +============ + +- [Install ROS2](https://index.ros.org/doc/ros2/Installation/) + +- Install Navigation2 + + - ``sudo apt install ros--navigation2 ros--nav2-bringup`` + +- Install Turtlebot 3 + + - ``sudo apt install ros--turtlebot3*`` + +- `Setup Turtlebot 3 `_ + +Tutorial Steps +============== + +0- Setup Your Environment Variables +----------------------------------- + +Run the following commands whenever you open a new terminal during this tutorial. + +- ``source /opt/ros//setup.bash`` +- ``export TURTLEBOT3_MODEL=waffle`` +- ``export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:/opt/ros/dashing/share/turtlebot3_gazebo/models`` + +Short-cut +--------- + +If you don't have the time to go through all the steps and only want to try Navigation2 in simulation, there is a solution for that. +After setting up your system variables, if you don't want to go through the step by step launch instructions, +you can use the launch file that does all the steps that are explained in the next sections for you. + +- ``ros2 launch nav2_bringup nav2_tb3_simulation_launch.py`` + +This launch file is going to launch Gazebo, Turtlebot3 specific nodes, Navigation2 and RViz2. +Once you see everything launced, you can jump to step 5. + +1- Launch Gazebo +---------------- + +Now, launch Gazebo with the world model, open a new terminal and type + + ``gazebo --verbose -s libgazebo_ros_init.so /opt/ros/dashing/share/turtlebot3_gazebo/worlds/turtlebot3_worlds/waffle.model`` + +Once, Gazebo is launched, you should see the Turtlebot3 world and Turtlebot 3 Waffle. + +If Gazebo fails to start, run the following commands and try to launch Gazebo again. + + - ``killall gzserver`` + - ``killall gzclient`` + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_turlebot3.png + :height: 720px + :width: 1024px + :alt: TB3 world and robot in Gazebo + +2- Launch Turtlebot 3 Robot State Publisher +------------------------------------------- + +Launch Turtlebot 3 specific nodes, + + ``ros2 launch turtlebot3_bringup turtlebot3_state_publisher.launch.py use_sim_time:=True`` + +Note : Make sure ``use_sim_time`` is set to **True** because our robot Turtlebot 3 is in Gazebo. + +3- Launch Navigation2 +--------------------- + +Launch Navigation 2. If you set ``autostart:=False``, you need to click on the start button in RVIZ to initialize the nodes. +Make sure `use_sim time` is set to **True**, because we want to use the time simulation time in Gazebo instead of the system time. + +turtlebot3_world.yaml is the configuration file for the map we want to provide Navigation2. +In this case, it has the map resolution value, threshold values for obstacles and free spaces, and a map file location. + + ``ros2 launch nav2_bringup nav2_bringup_launch.py use_sim_time:=True autostart:=False map:=/opt/ros/dashing/share/nav2_bringup/launch/turtlebot3_world.yaml`` + +4- Launch RViz +--------------- + +Launch RVIZ with a pre-defined configuration file. + + ``ros2 run rviz2 rviz2 -d $(ros2 pkg prefix nav2_bringup)/share/nav2_bringup/launch/nav2_default_view.rviz`` + +Now, you should see a shadow of Turtlebot 3 robot model in the center of the plot in RViz. +Click on the Start button (Bottom Left) if you set the auto_start parameter to false. + +.. image:: images/Navigation2_on_real_Turtlebot3/rviz_after_launch_view.png + :height: 720px + :width: 1024px + :alt: Rviz after launch, auto_start = false + +Now, the map should appear in RViz. + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_initial_view.png + :height: 720px + :width: 1024px + :alt: Turtlebot 3 map in RViz + +5- Initialize the location of Turtlebot 3 +----------------------------------------- + +First, find where the robot is in Gazebo. You can see where the robot's initial position in Gazebo. + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_turlebot3.png + :height: 720px + :width: 1024px + :alt: Turtlebot 3 world and robot in Gazebo + +Set the pose of the robot in RViz. Click on the 2D Pose Estimate button and point the location of the robot on the map. +The direction of the green arrow is the orientation of Turtlebot. + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_set_initial_pose.png + :height: 720px + :width: 1024px + :alt: Set initial pose in RViz + +Now, the 3D model of Turtlebot should move to that location. +A small error in the estimated location is tolerable. + +6- Send a Goal Pose +-------------------- + +Pick a target location for Turtlebot on the map. +You can send Turtlebot 3 a goal position and a goal orientation by using the **Navigation2 Goal** or the **GoalTool** buttons. + +Note: Navigation2 Goal button uses a ROS2 Action to send the goal and the GoalTool publishes the goal to a topic. + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_send_goal_pose.png + :height: 720px + :width: 1024px + :alt: Send goal pose in RViz + +Once you define the target pose, Navigation2 will find a global path and start navigating the robot on the map. + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/rviz_robot_navigating.png + :height: 720px + :width: 1024px + :alt: Turtlebot 3 navigating on a map in RViz + +You can also observe that Turtlebot 3 moves in the simulated environment in Gazebo as well. + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/gazebo_robot_reached_goal.png + :height: 720px + :width: 1024px + :alt: Turtlebot 3 navigating in Gazebo + +Next Tutorial +------------- + +:ref:`navigation2-on-real-turtlebot3` + +Videos +------ + +.. image:: images/Navigation2_with_Turtlebot3_in_Gazebo/navigation_with_recovery_behaviours.gif + :height: 480px + :width: 640px + :alt: Navigation2 with Turtlebot 3 Demo diff --git a/sphinx_doc/howtos/tutorials/index.rst b/sphinx_doc/howtos/tutorials/index.rst new file mode 100644 index 0000000000..b0ec0753dc --- /dev/null +++ b/sphinx_doc/howtos/tutorials/index.rst @@ -0,0 +1,13 @@ +.. _tutorials: + +Tutorials +######### + +Navigation2 Tutorials + +.. toctree:: + :maxdepth: 1 + + docs/navigation2_with_turtlebot3_in_gazebo.rst + docs/navigation2_on_real_turtlebot3.rst +