> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SLAM & Navigation

These workflows require [TurtleBot3 Bringup](./turtlebot3#bringup) to already be running in a separate terminal.

## SLAM — Building a Map

### Start Cartographer

```bash theme={null}
ros2 launch turtlebot3_cartographer cartographer.launch.py use_sim_time:=false
```

RViz will fail to open if there is no display connected — this is expected. Cartographer and the `/map` topic continue working headlessly.

### Drive to Build Coverage

Use [TurtleBot3 keyboard teleop](./turtlebot3#teleoperation) (`ros2 run turtlebot3_teleop teleop_keyboard`) or publish velocity commands to move the robot around the space. More coverage produces better map quality.

### Save the Map

```bash theme={null}
ros2 run nav2_map_server map_saver_cli -t /map -f ~/my_map
```

Output files:

* `~/my_map.pgm` — occupancy grid image
* `~/my_map.yaml` — map metadata (resolution, origin)

Stop Cartographer after saving.

## Navigation — Autonomous Driving

Requires a saved map from the SLAM step above.

```bash theme={null}
ros2 launch turtlebot3_navigation2 navigation2.launch.py \
  use_sim_time:=false \
  map:=$HOME/my_map.yaml
```

Set a 2D pose estimate in RViz, then send a navigation goal. For headless operation:

```bash theme={null}
ros2 action send_goal /navigate_to_pose nav2_msgs/action/NavigateToPose \
  '{pose: {header: {frame_id: "map"}, pose: {position: {x: 1.0, y: 0.5}}}}'
```

## RViz on the Physical Screen (via SSH)

The GNOME desktop uses Wayland, but RViz2's Ogre renderer requires GLX (X11). GNOME runs XWayland automatically — but the auth file (`XAUTHORITY`) has a random suffix that changes every reboot. Add a helper function to `~/.bashrc` to resolve it automatically.

### Add `export-display` to `~/.bashrc`

```bash theme={null}
cat >> ~/.bashrc << 'EOF'

export-display() {
  local xauth
  xauth=$(find /run/user/1000 -name '.mutter-Xwaylandauth.*' 2>/dev/null | head -1)
  export DISPLAY=:0
  export XAUTHORITY="$xauth"
  export XDG_RUNTIME_DIR=/run/user/1000
  echo "DISPLAY=$DISPLAY  XAUTHORITY=$XAUTHORITY"
}
EOF
source ~/.bashrc
```

### Run Before Any RViz Session Over SSH

```bash theme={null}
export-display
```

Output:

```
DISPLAY=:0  XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.XXXXXX
```

### SLAM + RViz on the Physical Screen (Full Example)

```bash theme={null}
# Terminal 1 – bringup
ros2 launch turtlebot3_bringup robot.launch.py

# Terminal 2 – SLAM + RViz on the connected screen
export-display
ros2 launch turtlebot3_cartographer cartographer.launch.py use_sim_time:=false
```

<Tip>If you open a terminal directly on the GNOME desktop (not over SSH), `DISPLAY` and `XAUTHORITY` are already set — run RViz normally without `export-display`.</Tip>

## RViz on a Remote Machine

To run RViz on a laptop or workstation on the same network:

1. On **both** machines set the same domain ID:
   ```bash theme={null}
   export ROS_DOMAIN_ID=30
   ```
2. Install ROS 2 Jazzy on the remote machine.
3. On the remote machine, open RViz:
   ```bash theme={null}
   rviz2
   ```
   Then add a **Map** display and set the topic to `/map`. The map data is discovered automatically over the network — no extra configuration needed.

Topics are discovered automatically over the network — no extra configuration needed.