> ## 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.

# Navigation through GRID CLI

> Discover maps, plan routes, and run robot missions from Python.

Use GRID to navigate a mobile robot through a mapped environment from your
Python program. Select a map, choose destinations, review a route, and run it.
You can check progress and read camera images while the robot follows the route.

> [!NOTE]
>
> Navigation is experimental and documented here for the Pre-release version.
> Import `make_nav` from `grid_nexus_client.nav`. The robot advertises the methods
> it serves; `dir(nav)` and `help(nav.plan)` describe your installed version.

## What you can build

| Task | Workflow |
| - | - |
| Build and edit a saved mission | Use the UI to select a map, place waypoints, set final heading, plan, and save. |
| Customize the robot runtime | Override individual fields or supply a complete calibrated config. |
| Repeat a saved inspection route | Discover a completed map and its saved paths, localize, then run a path ID. |
| Visit a mapped object | Use `find("table")`, inspect the matches, and plan to one. |
| Visit several coordinates | Build a `Path` of map-frame waypoints and plan the route. |
| Return to the starting location | Save the initial pose and plan a new route back to its XY position. |
| Inspect while moving | Start a non-blocking mission, sample a camera, and send images to GRID cloud. |
| Stop and continue working | Cancel a mission while keeping localization warm, or stop and later restart navigation. |

## How it fits together

Your program requests a mission. Navigation software on the robot executes it.
GRID cloud provides map data, route planning, and services that help locate the robot on the map.

Your computer

On the robot

GRID cloud

> **Your computer**
>
> **Choose and monitor the mission**
>
> Your Python notebook selects destinations, requests routes, and starts missions.
> The CLI connects to the robot. The browser viewer shows progress and camera images.

> **On the robot**
>
> **Execute the mission**
>
> The robot runs the navigation software that follows the planned route and sends
> movement commands to the robot's controller. It reports mission progress and
> results to your computer.

> **GRID cloud**
>
> **Provide maps and route plans**
>
> GRID cloud stores maps and saved missions, finds mapped objects, plans routes,
> and helps determine the robot's position on the map using visual localization.

The GRID connection carries requests and results between your program and the robot.
The robot runs the navigation control loop; your notebook does not send every movement command.
With `blocking=False`, Python can continue reading images or calling GRID cloud while navigation runs.
Keep the CLI session open. Closing a viewer or losing a notebook connection is not a stop command.

The [GRID Navigator app](https://docs.generalrobotics.dev/v2.4/support/grid-navigator.md) captures scans used to build maps.
The [mission editor](https://docs.generalrobotics.dev/v2.4/navigation/mission-editor.md) lets you submit a scan for map building
and create saved missions on completed maps.

In Python, use `robot` for camera and other robot calls. Use `nav` for navigation.
These objects access the same robot. They do not create separate control sessions.
Navigation state is shared: another connected client can observe or change it.
Use one controller for movement at a time.

## Before you begin

* Use a robot provisioned with the opt-in navigation capability and a matching
  robot profile. The documented provisioning path includes R1Pro and Vision60.
* Have a completed map of the robot's current physical area. Create a saved mission
  in the editor before the first Python tutorial.
* Start a [CLI development session](https://docs.generalrobotics.dev/v2.4/get-started/first-skill.md). It supplies the
  Python environment and connection settings. Run your notebook in that environment;
  navigation execution stays on the robot.
* Keep the robot's e-stop accessible and verify localization before motion.
  Execute the guided steps individually.

`make_nav()` attaches; `start()` warms sensors and localization. Neither starts
a navigation mission. **`run_mission()` and `move_to()` command motion.**
`cancel_mission()`, `stop()`, `set_map()`, and `shutdown()` change shared runtime
state; they are not read-only observations.

## Learn by doing

Work through Chapters 1–3 in order. Start with a saved mission, then plan your own routes, then add camera-based object detection.

1. [Build a mission in the UI](https://docs.generalrobotics.dev/v2.4/navigation/mission-editor.md): open the editor, select/build a map, place waypoints, and save.
2. [Chapter 1 — Run your first mission](https://docs.generalrobotics.dev/v2.4/navigation/first-mission.md): connect, discover, localize, execute, and clean up.
3. [Chapter 2 — Plan your own routes](https://docs.generalrobotics.dev/v2.4/navigation/planning.md): semantic lookup, multi-stop paths, return trips, and restart.
4. [Chapter 3 — Detect objects while navigating](https://docs.generalrobotics.dev/v2.4/navigation/observation.md): non-blocking execution with camera and GRID cloud calls.
5. [Use the telemetry UI](https://docs.generalrobotics.dev/v2.4/cli/nav-telemetry.md): inspect diagnostics and log notebook images and measurements.
6. [Configure navigation](https://docs.generalrobotics.dev/v2.4/navigation/configuration.md): overrides, custom YAML/dictionaries, recording, and constraints.

The three Python walkthroughs also have downloadable notebooks. The [API contract](https://docs.generalrobotics.dev/v2.4/navigation/api-reference.md),
[data schemas](https://docs.generalrobotics.dev/v2.4/navigation/data-types.md), and [config field reference](https://docs.generalrobotics.dev/v2.4/navigation/config-reference.md)
cover inputs, outputs, side effects,
and errors for both people and agents writing code.

## Telemetry and agent navigation

The CLI telemetry page can show navigation data and notebook GRX streams together.
See [Telemetry UI and notebook logging](https://docs.generalrobotics.dev/v2.4/cli/nav-telemetry.md).

The CLI agent can find targets, plan a route, show its preview, and request approval
before movement. See [Agentic navigation](https://docs.generalrobotics.dev/v2.4/cli/agentic-navigation.md) for setup,
route review, stopping, and current limits. Finish notebook-controlled motion
before using the agent to control the same robot.


## Related topics

- [Your first skill](https://docs.generalrobotics.dev/v2.4/get-started/first-skill.md)
- [Configure navigation](https://docs.generalrobotics.dev/v2.4/navigation/configuration.md)
- [Agentic navigation](https://docs.generalrobotics.dev/v2.4/cli/agentic-navigation.md)
- [Navigation data schemas](https://docs.generalrobotics.dev/v2.4/navigation/data-types.md)
- [Build a mission in the UI](https://docs.generalrobotics.dev/v2.4/navigation/mission-editor.md)


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