Tutorial updates (#455)

Author: MikeWrock

doc/tutorials/pick_and_place_with_moveit_task_constructor/launch/pick_place_demo.launch.py

@@ -9,7 +9,7 @@ def generate_launch_description():
     # MTC Demo node
     pick_place_demo = Node(
         # package="mtc_tutorial",
-        # executable="mtc_tutorial",
+        # executable="mtc_node",
         package="moveit2_tutorials",
         executable="mtc_tutorial",
         output="screen",

doc/tutorials/pick_and_place_with_moveit_task_constructor/pick_and_place_with_moveit_task_constructor.rst

@@ -43,7 +43,7 @@ First, update the target pose with the following change to make the robot plan t
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In the next block of code, we create a collision object.
-The first thing to notice is that it is being placed in the frame of the robot.
+The first thing to notice is that it is being placed in the coordinate frame of the robot.
 If we had a perception system that reported the location of obstacles in our scene, then this is the sort of message it would build.
 Because this is just an example, we are creating it manually.
 One thing to notice at the end of this block of code is that we set the operation on this message to ``ADD``.
@@ -69,7 +69,7 @@ Place this code block between setting the target pose from the previous step and
 
       // Define the pose of the box (relative to the frame_id)
       geometry_msgs::msg::Pose box_pose;
-      box_pose.orientation.w = 1.0;
+      box_pose.orientation.w = 1.0;  // We can leave out the x, y, and z components of the quaternion since they are initialized to 0
       box_pose.position.x = 0.2;
       box_pose.position.y = 0.2;
       box_pose.position.z = 0.25;

doc/tutorials/planning_around_objects/planning_around_objects.rst

@@ -165,11 +165,11 @@ Step 4: Use Motion Planning with the Panda
 
   * Make sure both states are not in collision with the robot itself.
 
-  * Make sure the Planned Path is being visualized. Also check the
-    **Show Trail** checkbox in the **Planned Path** tree menu.
+  * Un-check the **Show Trail** checkbox in the **Planned Path** tree menu.
 
-* In the **MotionPlanning** window under the **Planning** tab, press the **Plan** button. You
-  should be able to see a visualization of the arm moving and a trail.
+* In the **MotionPlanning** window under the **Planning** tab, press the **Plan** button.
+
+* Check the **Show Trail** checkbox in the **Planned Path** tree menu. You should see the arm's path represented by a series of manipulator poses.
 
 .. image:: rviz_plugin_planned_path.png
    :width: 700px
@@ -185,7 +185,8 @@ You can visually introspect trajectories point by point in RViz.
 
 * Play with the "*Slider*" panel, e.g. move the slider, push "*Play*" button.
 
-NOTE: Once you placed your EEF to a new goal, be sure to run *Plan* before running *Play* -- otherwise you'll see the waypoints for the previous goal if available.
+Note: Once you placed your end-effector to a new goal, be sure to run *Plan* before running *Play* -- otherwise you'll see the waypoints for the previous goal if available.
+
 
 .. image:: rviz_plugin_slider.png
    :width: 700px

doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst

@@ -36,7 +36,7 @@ int main(int argc, char* argv[])
   auto const draw_title = [&moveit_visual_tools](auto text) {
     auto const text_pose = [] {
       auto msg = Eigen::Isometry3d::Identity();
-      msg.translation().z() = 1.0;
+      msg.translation().z() = 1.0;  // Place text 1m above the base link
       return msg;
     }();
     moveit_visual_tools.publishText(text_pose, text, rviz_visual_tools::WHITE, rviz_visual_tools::XLARGE);

doc/tutorials/visualizing_in_rviz/hello_moveit.cpp

@@ -55,32 +55,42 @@ To test that this all worked, open a terminal in the workspace directory (rememb
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Before we can initialize MoveItVisualTools, we need to have a executor spinning on our ROS node.
-This is necessary because of how MoveItVisualTools interacts with ROS services and topics.
+This is necessary because of how MoveItVisualTools interacts with ROS services and topics. First, add the threading library to your includes at the top.
 
 .. code-block:: C++
 
   #include <thread>  // <---- add this to the set of includes at the top
 
-    ...
+By creating and naming loggers, we are able to keep our program logs organized.
+
+  .. code-block:: C++
 
     // Create a ROS logger
     auto const logger = rclcpp::get_logger("hello_moveit");
 
-    // We spin up a SingleThreadedExecutor so MoveItVisualTools interact with ROS
+Next, add your executor before creating the MoveIt MoveGroup Interface.
+
+.. code-block:: C++
+
+    // Spin up a SingleThreadedExecutor for MoveItVisualTools to interact with ROS
     rclcpp::executors::SingleThreadedExecutor executor;
     executor.add_node(node);
     auto spinner = std::thread([&executor]() { executor.spin(); });
 
     // Create the MoveIt MoveGroup Interface
-    ...
+
+  ...
+
+Finally, make sure to join the thread before exiting.
+
+.. code-block:: C++
 
     // Shutdown ROS
     rclcpp::shutdown();  // <--- This will cause the spin function in the thread to return
     spinner.join();  // <--- Join the thread before exiting
     return 0;
-  }
 
-After each one of these changes, you should rebuild your workspace to make sure you don't have any syntax errors.
+After making these changes, rebuild your workspace to make sure you don't have any syntax errors.
 
 3 Create and Initialize MoveItVisualTools
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -116,7 +126,7 @@ After we've constructed and initialized, we now create some closures (function o
     auto const draw_title = [&moveit_visual_tools](auto text) {
       auto const text_pose = [] {
         auto msg = Eigen::Isometry3d::Identity();
-        msg.translation().z() = 1.0;
+        msg.translation().z() = 1.0;  // Place text 1m above the base link
         return msg;
       }();
       moveit_visual_tools.publishText(text_pose, text, rviz_visual_tools::WHITE,

doc/tutorials/visualizing_in_rviz/visualizing_in_rviz.rst

@@ -110,11 +110,24 @@ After that, we have the normal call to initialize rclcpp, and then we create our
     rclcpp::NodeOptions().automatically_declare_parameters_from_overrides(true)
   );
 
-The first argument is a string that ROS will use to make a unique node.
+The first argument is a string that ROS will use to name a unique node.
 The second is needed for MoveIt because of how we use ROS Parameters.
 
+Next, we `create a logger <https://docs.ros.org/en/humble/Tutorials/Demos/Logging-and-logger-configuration.html>`_ named "hello_moveit" to keep our log outputs organized and configurable.
+
+.. code-block:: C++
+
+  // Create a ROS logger
+  auto const logger = rclcpp::get_logger("hello_moveit");
+
 Lastly, we have the code to shutdown ROS.
 
+.. code-block:: C++
+
+  // Shutdown ROS
+  rclcpp::shutdown();
+  return 0;
+
 3 Plan and Execute using MoveGroupInterface
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^