> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4_docs/working-with-stretch/getting-started/demo-mapping-and-navigation.md). # Demo - Mapping and Navigation A fundamental feature of mobile robots like Stretch is the ability to create a map of an environment and then navigate around it autonomously. The following tutorial will explain how to quickly build a 2-dimensional map that the robot can use to navigate around your current environment, using ROS 2 software called Nav2. ## Building a Map Building a map of the environment allows the robot to understand where it is currently located, and where you would like it to travel to. Stretch builds maps using the 3D LiDAR sensors located in the robot's head. These sensors allow Stretch to understand the structure of the space around the robot, including the floor, walls, and obstacles. By driving the robot slowly around the space, Stretch builds its understanding of the space, and will create a 2D map of all of the area that it can traverse freely. {% stepper %} {% step %} ### Home and Stow the Robot To make a map accurately, it is important that Stretch's arm and gripper are tucked out of the way so that they do not block the view of the sensors. To do this, run the following commands on Stretch, making sure the arm and wrist have free space to move. ``` stretch_robot_home stretch_robot_stow ``` Check the expected homing and stowing behaviours in [Robot Overview](/stretch4_docs/working-with-stretch/getting-started/robot-overview.md) {% endstep %} {% step %} ### Launch the ROS 2 Mapping Node Start the offline mapping launch file by running the following command in a terminal: ``` ros2 launch stretch_nav2 offline_mapping.launch.py ``` If you want to display the live feed from the robot cameras while driving, you can also run the following in a separate terminal window: ``` stretch_camera_show --opencv --right ``` {% endstep %} {% step %} ### Begin Teleoperation In a new terminal, start gamepad teleop by running: ``` stretch_gamepad_teleop ``` Just as you did in the [Broken mention](broken://pages/OHoQ2HEtx1R5cPw2nEaH), use the gamepad left stick and bumpers to move the robot around the space. You can watch the laser scan in RViz to understand what areas the robot has already scanned. Blank sections should be filled in by driving the robot around to get a better view. Once the map of your space looks fairly complete, you can move to the next step. We recommend starting with just one or two rooms for this initial demonstration. {% endstep %} {% step %} ### Save the Map Open a new terminal (leaving the one with the mapping node running) and use the following command to save the map to your fleet directory, replacing `` with the name you want to use (eg `stretch_demo_map`) ``` ros2 run nav2_map_server map_saver_cli -f ${HELLO_FLEET_PATH}/maps/ ``` {% endstep %} {% step %} ### Close the Mapping Node Go to the terminal window with the mapping launch file (the one from Step 2), and press Ctrl+C to close the stop the mapping script. {% endstep %} {% endstepper %} {% embed url="" %} ## Navigating the Map #### Phase 2: Navigating the Generated Map {% hint style="warning" %} Avoid initiating navigation while the robot is docked in the **Stretch Docking Station**. Always undock the robot completely before sending a navigation goal. {% endhint %} {% hint style="danger" %} This demo does **NOT** utilize the line sensors for small object or cliff detection. Keep the area clear, and **keep the robot away from stairs or ledges at all times** during this demo. {% endhint %} Now that we have saved a map, we can use it to tell the robot to autonomously navigate through your environment. Stretch will still look for new obstacles around its body, so if an object or person moves through the space, it will adjust and adapt to avoid collisions and plan its movements intelligently. {% stepper %} {% step %} ### Launch the ROS 2 Navigation Node Use the following terminal command to start Nav2 and point it to the .YAML file for the map you just created. Don't forget to update the `` parameter to the name you chose above. ``` ros2 launch stretch_nav2 navigation_mppi.launch.py map:=${HELLO_FLEET_PATH}/maps/.yaml ``` {% endstep %} {% step %} ### Set the Initial Robot Position You should now see the map open on Stretch in the RViz2 software. However, the robot doesn't yet know where it is currently positioned on the map. We'll need to tell it approximately where it is located and which direction it is facing. In the RViz2 window showing the map, click on the "2D Pose Estimate" button, then click on the robot's current location in the map, and hold and drag in the direction the robot is currently facing. Release to set the robot's orientation. \#this definitely needs a gif or short video {% endstep %} {% step %} ### Set a Navigation Goal In RViz2, click the "Nav2 Goal" button, then click a position on the map where you want the robot to navigate to. Make sure the position is inside the free area on the map. Stretch should now start driving to the location you selected autonomously! Try sending Stretch to different points in the room, then interact with it by moving objects around or standing in front of the robot to force it to react to these new obstacles and find alternative routes. {% endstep %} {% endstepper %}
Troubleshooting and Debugging 1. **Isolate node errors:** If navigation fails at startup, try adding `use_composition:=false` to the navigation launch command. This starts nodes outside a shared container, which makes errors easier to spot. 2. **Remote operation:** If you use a remote desktop session, you may need to plug in a dummy HDMI adapter so the display server starts correctly. One of these shipped in the accessory box along with your robot 3. **Navigation does not start after setting the pose:** If too much time passes before you set the robot's initial pose, the navigation stack may need to be reset. A common symptom is that the local costmap appears in RViz2, but the global costmap does not. To recover: 1. In the Navigation panel in RViz2, click **Startup**. 2. Click **Reset**. 3. Set the robot's initial pose again. Once the global costmap appears, the robot is ready to accept navigation goals.
#### Learn More To learn more information about ROS 2 Nav2 software, check out the official [Nav2 Getting Started guide](https://docs.nav2.org/getting_started/index.html) to learn the concepts in simulation. For more advanced topics and tuning guides for navigation on Stretch, you can also explore the tutorials in [Navigation University](/stretch4_docs/working-with-stretch/nav_u.md). In the next section, we'll learn how to launch the Web Teleoperation demo to drive Stretch with a user-friendly interface from a remote PC or mobile phone. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hello-robot.com/stretch4_docs/working-with-stretch/getting-started/demo-mapping-and-navigation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.