> ## 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 telemetry and notebook logging

> View robot navigation and log notebook images and measurements in the CLI telemetry page.

Use a CLI and workflow environment that include the unified telemetry page.
The CLI requires GRX HTTP API version 2. An older GRX package can prevent the viewer from starting.

## Start the notebook session

From your notebook folder, run:

```sh theme={null}
grid skill run --dev --robot YOUR_ROBOT_NAME
```

Keep the CLI open. Select the generated workspace's `.venv` kernel.
The CLI supplies `GRID_TELEMETRY_URL` to this environment.
After connecting your notebook's `nav` object, run `nav.view()` and open Telemetry.

The page combines two sources: live robot navigation and GRX samples from your notebook.
A connected robot with no samples is different from a lost connection.
Check the displayed source and connection state before interpreting a plot.

## Inspect navigation data and logs

For your first run, follow [Run a saved mission](/navigation/first-mission).
Use this page when you need more detail or want to add notebook measurements.

Use **Add view** to select available robot data or logged outputs.
Navigation data can include map layers, localization health, recovery state,
and the latest mission result. Availability depends on the robot runtime.
Check the connection state and sample age. A connection alone does not prove fresh data.

Open the robot log view to inspect **Robot messages**. Use **Load older**,
**Pause logs** / **Follow new logs**, and **Download full log** where available.
The visible log window holds up to 256 KiB. Log history is separate from retained GRX history.
If the run changes, use the new run's log identity.

For a Python monitor, see the [diagnostics API](/navigation/api-reference#viewer-and-diagnostics)
and [data schemas](/navigation/data-types). They describe `telemetry(since=...)`,
`log_chunk(...)`, and how to request the next batch of data.

### Reopen the viewer

Call `nav.view()` from the connected notebook. To print the URL only, use
`nav.view(open_browser=False)`. You can also run this inside the GRID terminal:

```text theme={null}
nav view YOUR_ROBOT
```

Use the same GRID process that holds the development session.
`nav view YOUR_ROBOT --no-open` prints the URL instead.
Reopen the page after changing account or cluster. A separate CLI process does not share the held session.

The viewer observes the robot. Close it without ending the mission.
To stop motion, use the [owning mission workflow](/navigation/first-mission#cancel-if-needed).
`nav.stop()` stops navigation workers; `nav.shutdown()` releases Nav.
Both affect clients sharing that navigation instance.

## Log a measurement

```python theme={null}
import os
import numpy as np
from grx.viewer import RemoteLiveSession

url = os.environ.get("GRID_TELEMETRY_URL", "").strip()
if not url:
    raise RuntimeError("Start the CLI dev session and select its kernel first.")
telemetry = RemoteLiveSession(url)
telemetry.log("inspection/detection_count", np.array([2], dtype=np.float32))
```

Select the new stream in the Telemetry page. Logging a measurement does not move the robot.
Use the same shape and data type for each later sample in that stream.
Use a new stream name if you change the camera resolution or data layout.

## Log a camera image

Use the camera selected in your notebook. This example requires an RGB image.

```python theme={null}
frame = robot.getImage(CAMERA)
if frame is None:
    raise RuntimeError("The camera did not return an image.")
pixels = frame.decode()
telemetry.log("inspection/rgb", pixels, kind="image")
```

Logging time is the host time unless you supply `t_ns`.
It does not establish the camera's capture time or prove that a frame is fresh.
The notebook can read and log images while `nav.run_mission(..., blocking=False)` runs.
Logging is synchronous. Slow sensor or viewer requests can delay the notebook's cancellation path.
Keep the mission's cancellation and cleanup code.

## Save and finish

```python theme={null}
from pathlib import Path

recording = Path("inspection.grx").resolve()
print(telemetry.save(str(recording)))
telemetry.stop()
```

Choose a new filename for each recording. The path is on the CLI host.
This saves retained GRX streams, not all robot navigation data shown on the page.
The shared viewer can contain samples from more than one notebook.
Review recordings before sharing them.

The viewer retains up to 600 seconds, subject to its storage limit.
Large images can remove older samples sooner. Save important results separately during long missions.
`telemetry.stop()` detaches the notebook client. It does not stop the robot or close the CLI-owned viewer.
Run the notebook's Nav and robot cleanup separately. The viewer stops when the CLI exits.

For standalone playback, run:

```sh theme={null}
python -m grx.viewer /absolute/path/inspection.grx
```

## If the page is empty

* Check `GRID_TELEMETRY_URL` in the selected kernel. Do not reuse a URL from an earlier CLI process.
* Confirm that the first log call succeeded and that the stream is selected.
* Keep the CLI running. Reconnect the notebook client after a viewer replacement.
* Check the timeline's retained range. A paused time can expire as old data is removed.
* Check that later samples use the first sample's shape and data type.

For agent-controlled navigation, see [Agentic navigation](/cli/agentic-navigation).


## Related topics

- [Navigation through GRID CLI](/navigation/overview.md)
- [Navigation troubleshooting](/navigation/troubleshooting.md)
- [Agentic navigation](/cli/agentic-navigation.md)
- [Chapter 1 — Run your first mission](/navigation/first-mission.md)
- [Navigation data schemas](/navigation/data-types.md)


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