from grid_nexus_client.nav import make_nav and pass
the RemoteRobot returned by grid_nexus_client.make_robot.
Return types below describe the current implementation; see data schemas.
Attach and inspect
make_nav(robot, cfg=None, **options) -> RemoteNav
A new instance is cold. A no-option attach can also return an existing instance,
including one already running a mission. Check nav.status() before changing it.
This call does not start navigation motion, but creates or attaches runtime state.
With no config, the robot uses its
GRID_NAV_CONFIG path when set, otherwise
the bundled profile for its robot type. Resolution applies schema defaults,
profile/config values, dotted overrides, then explicit construction keywords.
Avoid copying controller or localization tuning from a different robot. Follow
Configure navigation for examples, YAML shape,
precedence, validation, and a complete downloadable config/schema.
Options require updated Edge Comms and PointNav (attach capability version 2
or later). Any settings supplied while a Nav already exists are refused,
even if identical. stop() does not release the instance. Coordinate with
other users, call shutdown(), and construct a new Nav to change settings.
nav.config is the resolved configuration as a plain dictionary (or None
if the robot did not report one). Editing it does not reconfigure the robot.
nav.instance and nav.robot_instance identify the instances the handle owns.
nav.robot is the borrowed robot proxy.
Catalogs and localization
Pagination is explicit:
page is an integer starting at 1 and limit is an
integer from 1 to 100. Continue until a page contains fewer than limit
records. Names need not be unique; prefer IDs. start and set_map accept
positive timeout_s or None for no localization deadline. This does not
disable independent network timeouts.
Lookup, planning, and motion
ATarget is a semantic string, a Waypoint, or an (x, y) pair in map
metres. It is not a displacement relative to the robot.
find preserves server order, not nearest-first order, and currently returns
confidence=None. Inspect matches before selecting. A string passed to
plan or move_to resolves to the first semantic match, not a saved path
name or an authored waypoint-name lookup. No match raises UnknownWaypoint.
run_mission("name") instead resolves a saved mission on the active map.
find supports these keyword query controls:
Planning can snap targets to navigable locations. Inspect the returned
path.waypoints and dense path.route. A sparse Path passed to run_mission
is planned before motion. A path with a dense route is validated and executed;
it is not automatically replanned from a new start. Map IDs must match, all
coordinates must be finite, and execution needs at least one waypoint and
a dense route with at least two points. Replan stored waypoints before reuse.
Serializable mission overrides include record, run_name, enable_cloud_replan,
cloud_replan_cooldown_s, cloud_replan_timeout_s, stream_viz_grx,
stream_viz_port, and constraints. See per-mission options
for meanings and the supported polygon-policy schema. They affect that run,
not nav.config. Do not pass robot-side worker objects or arbitrary controller
fields through Nexus. Use construction-time overrides for configuration.
Non-blocking missions and completion
run_mission(..., blocking=False) and move_to(..., blocking=False) leave
execution on the robot. Discard the return value over Nexus. The local
PointNav Run object is not a remote handle; the current transport falls back
to its string representation. Do not call .wait() or .cancel() on it.
The raw result includes
success: bool, exit_cause: str,
waypoints_reached: int, and total_waypoints: int, plus diagnostics.
Require success is True to report success. A stopped mission alone does not
prove arrival. If the result is None after the run ends, inspect
telemetry()["status"]["error"] and the events. Read results before
stop(), shutdown(), or another mission replaces the current run.
A keyboard interrupt during a Nexus method call attempts cancellation, but
this is best-effort. Interrupting a camera or GRID cloud loop does not itself
cancel the mission. Wrap such loops in cleanup that calls cancel_mission.
A network timeout is not evidence that a motion request was rejected: inspect
status before deciding what to do. Nexus never automatically retries nav calls.
Stop, restart, and finish
stop and shutdown accept a nonnegative stop timeout. stop can raise if
a mission has not joined by that deadline; inspect the state instead of
assuming teardown completed. A retained localization seed is inert while
stopped and only usable on the same map. Restart still needs a fresh accepted
cloud validation and never resumes the old mission.
These operations affect every client sharing the Nav. They leave the borrowed
robot connection available. Finish navigation first, then call
robot.shutdown() when done with the robot session. A stale Nav after shutdown,
or a stale robot after restart, produces an instance error; reconnect/reattach.
Viewer and diagnostics
view(open_browser=True) -> str is client-side. It opens the local CLI viewer
and returns its URL; False only returns the URL. A CLI dev session on the
same computer must supply that URL. It does not start navigation.
telemetry(since=0) -> dict reads a bounded snapshot/delta without starting
navigation. Its envelope has version, epoch, sequence, since, t_ns,
errors, log_id, streams, and status. Start at zero, then use the returned
sequence for the next poll; reset to zero when epoch changes. status
contains the NavState fields plus progress, result, and error diagnostics.
log_chunk(log_id, *, offset=None, before=None, limit=65536) -> dict reads
bounded terminal text using the opaque log_id from telemetry. Omit cursors
for the tail, use before for history or offset to follow, never both.
limit is an integer from 1 to 65536 bytes; cursors are nonnegative byte
positions within the current log. The response has log_id: str, start: int,
end: int, size: int, and text: str. Use the returned end as the next
offset, or start as before to read older text. Boundaries are adjusted for
UTF-8. No filesystem path is accepted. Prefer the viewer for routine inspection.
Errors
Import navigation errors fromgrid_nexus_client.nav (shared base errors also
live in grid_types.nav_errors). These derive from NavError / RuntimeError.
Transport errors and serialization errors can remain plain runtime exceptions;
catching
NavError alone does not catch all failures. Invalid values can be
ValueError locally but become NavError across Nexus.
Agent call sequence
- Connect the explicitly selected robot and attach navigation. Inspect the served methods and current state; do not stop another run implicitly.
- Discover a completed map and resolve IDs. Start that map and verify the localized pose against the physical robot.
- Resolve target ambiguity, plan, and inspect the resulting path. Planning and semantic lookup do not authorize a new physical mission.
- Execute the user-requested mission. Do not retry an uncertain motion request automatically. Observe status and verify its result.
- Cancel or shut down when requested or when the owning workflow fails.
nav/{robot_name}/attach, introspection at
nav/{robot_name}/query/introspect, and calls at nav/{robot_name}/{method}.
The SDK handles serialization and both instance IDs. These are Zenoh query
surfaces, not agent tool names or plain HTTP/JSON endpoints. Use the SDK for
these tutorials; use a future tool’s own advertised schema when available.