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

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

<div role="img" aria-label="Your computer communicates with the robot. The robot communicates with GRID cloud." style={{display: "flex", alignItems: "center", gap: "0.5rem", margin: "1.5rem 0", textAlign: "center", fontSize: "0.875rem", fontWeight: 600}}>
  <div style={{flex: 1, padding: "1rem 0.5rem", border: "1px solid #88888840", borderRadius: "0.75rem"}}>Your computer</div>
  <span aria-hidden="true" style={{color: "#e52222", fontSize: "1.5rem"}}>↔</span>
  <div style={{flex: 1, padding: "1rem 0.5rem", border: "1px solid #88888840", borderRadius: "0.75rem"}}>On the robot</div>
  <span aria-hidden="true" style={{color: "#e52222", fontSize: "1.5rem"}}>↔</span>
  <div style={{flex: 1, padding: "1rem 0.5rem", border: "1px solid #88888840", borderRadius: "0.75rem"}}>GRID cloud</div>
</div>

<CardGroup cols={1}>
  <Card title="Your computer" icon="laptop" horizontal>
    **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.
  </Card>

  <Card title="On the robot" icon="robot" horizontal>
    **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.
  </Card>

  <Card title="GRID cloud" icon="cloud" horizontal>
    **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.
  </Card>
</CardGroup>

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](/support/grid-navigator) captures scans used to build maps.
The [mission editor](/navigation/mission-editor) 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](/get-started/first-skill). 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](/navigation/mission-editor): open the editor, select/build a map, place waypoints, and save.
2. [Chapter 1 — Run your first mission](/navigation/first-mission): connect, discover, localize, execute, and clean up.
3. [Chapter 2 — Plan your own routes](/navigation/planning): semantic lookup, multi-stop paths, return trips, and restart.
4. [Chapter 3 — Detect objects while navigating](/navigation/observation): non-blocking execution with camera and GRID cloud calls.
5. [Use the telemetry UI](/cli/nav-telemetry): inspect diagnostics and log notebook images and measurements.
6. [Configure navigation](/navigation/configuration): overrides, custom YAML/dictionaries, recording, and constraints.

The three Python walkthroughs also have downloadable notebooks. The [API contract](/navigation/api-reference),
[data schemas](/navigation/data-types), and [config field reference](/navigation/config-reference)
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](/cli/nav-telemetry).

The CLI agent can find targets, plan a route, show its preview, and request approval
before movement. See [Agentic navigation](/cli/agentic-navigation) 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](/get-started/first-skill.md)
- [Configure navigation](/navigation/configuration.md)
- [Agentic navigation](/cli/agentic-navigation.md)
- [Navigation data schemas](/navigation/data-types.md)
- [Navigation troubleshooting](/navigation/troubleshooting.md)


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