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

# Chapter 1 — Run your first mission

> Connect to a robot, choose a map, localize, and execute a saved route.

By the end of this guide you will have run a saved route and checked whether
the robot arrived. First [create a mission in the editor](/navigation/mission-editor)
if your map does not have one yet.

[Download this guide as a notebook](/assets/notebooks/navigation/first-mission.ipynb)

## 1. Connect to your robot

Start in a project folder with a [GRID development session](/get-started/first-skill):

```bash theme={null}
grid skill run --dev --robot YOUR_ROBOT
```

Keep that CLI process running. Use its workspace `.venv` Python environment
(or select that kernel if you use the downloadable notebook). Run the snippets
in order in one Python session. Set your registered robot name and use the numbered selectors.
The robot must have navigation enabled.

Attach navigation and check whether someone is already running a mission.
Attaching does not start a mission. A no-option attach shares an existing Nav;
it does not create an isolated controller.

```python theme={null}
from grid_nexus_client import make_robot
from grid_nexus_client.nav import make_nav

ROBOT = "YOUR_ROBOT"
robot = make_robot(ROBOT)
nav = make_nav(robot)
state = nav.status()
print(state)
if state.mission_running:
    raise RuntimeError("A mission is already running; coordinate with its operator first")
```

## 2. Choose a completed map and saved route

Select a completed map of the robot's actual surroundings. Change `MAP_PAGE` if it is on another page.

```python theme={null}
MAP_PAGE = 1
maps = [m for m in nav.list_maps(page=MAP_PAGE, limit=100) if m.status == "COMPLETED"]
if not maps:
    raise RuntimeError("No completed maps on this page. Check the account or MAP_PAGE.")
for number, item in enumerate(maps, 1):
    print(number, item.name, item.map_id)
choice = input("Map number: ").strip()
if not choice.isdecimal() or not 1 <= int(choice) <= len(maps):
    raise ValueError("Choose a listed map number.")
MAP_ID = maps[int(choice) - 1].map_id
```

Choose the saved mission you reviewed in the editor. Change `MISSION_PAGE` if needed.

```python theme={null}
MISSION_PAGE = 1
missions = nav.list_paths(MAP_ID, page=MISSION_PAGE, limit=100)
if not missions:
    raise RuntimeError("No saved missions on this page. Check MISSION_PAGE or save one in the editor.")
for number, item in enumerate(missions, 1):
    print(number, item.name, item.path_id)
choice = input("Reviewed mission number: ").strip()
if not choice.isdecimal() or not 1 <= int(choice) <= len(missions):
    raise ValueError("Choose a listed mission number.")
MISSION = missions[int(choice) - 1].path_id
```

The selection stores the mission ID, so duplicate names do not select the wrong record.

## 3. Start navigation and verify localization

Start loads the map and waits for localization; it does not execute a route.
The viewer opens in your browser. Compare its robot marker and heading with
the physical robot. `localize()` then waits for a fresh accepted localization
fix, and home keeps that map pose for a possible return trip.

```python theme={null}
nav.start(map_id=MAP_ID, timeout_s=90)
nav.view()
home = nav.localize(timeout_s=30)
print(home)
```

`home.x` and `home.y` are metres in the map frame; `home.yaw` is radians.
If localization fails or the marker is wrong, stop here and use
[troubleshooting](/navigation/troubleshooting). A successful API response does
not replace checking that you selected the correct physical map.

### Check the live view

Check the connection state and the age of the displayed pose. A connected robot
can still have stale position data. Compare the marker and heading with the physical robot.
Keep this page open while the mission runs. Opening or closing it does not start or stop motion.

## 4. Execute the saved mission

Position the robot at the saved route's intended start and review the path in
the editor. This call commands motion. Keep the e-stop accessible; type RUN
only after checking the route. The call blocks until the run finishes.

```python theme={null}
if input("Run this saved mission on the robot? Type RUN: ") != "RUN":
    raise RuntimeError("Mission not started")
result = nav.run_mission(MISSION)
print(result)
if result.status != "succeeded":
    raise RuntimeError(f"Mission {result.status}: {result.message}")
```

### Watch progress and check the result

While the Python call waits, watch the browser view. The map shows the planned
route, driven path, robot position, and current target when those streams are available.
Check progress through the stops. Missing data does not prove that the robot is stationary.
A stopped marker or a finished progress bar is not proof of success.

Completion is not automatically success: the returned `MissionResult` can be
succeeded, cancelled, or failed. Its message explains the result and
`final_pose` contains the final pose when available. A timeout does not prove
that the robot rejected the request; check status before retrying.

### Cancel if needed

To cancel a blocking notebook call, interrupt the running cell. The remote client
requests cancellation on interruption. Then check the physical robot.
A busy kernel cannot run another cell until the current call returns or is interrupted.

When the kernel can accept a command, `nav.cancel_mission()` requests cancellation
and keeps localization available. A successful request alone does not confirm a stop.
If stopping cannot be confirmed, use the physical e-stop and involve the operator.
Closing the viewer does not cancel navigation.

For layers, logs, and stale data, see [Telemetry UI](/cli/nav-telemetry#inspect-navigation-data-and-logs).

## 5. Finish

Shutdown releases the shared Nav instance and affects other clients attached
to it. Collect results first, then release navigation before the borrowed robot.
Run this cleanup even after an earlier step fails. If a connection failure
prevents stopping motion, use the robot's e-stop.

```python theme={null}
nav.shutdown()
robot.shutdown()
```

Continue with [planning your own routes](/navigation/planning), or choose
[configuration overrides](/navigation/configuration) before creating your next Nav.


## Related topics

- [Navigation through GRID CLI](/navigation/overview.md)
- [Chapter 2 — Plan your own routes](/navigation/planning.md)
- [Chapter 3 — Detect objects while navigating](/navigation/observation.md)
- [Your first skill](/get-started/first-skill.md)
- [Build a mission in the UI](/navigation/mission-editor.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.