GRID Docs | General Robotics

Import these shared classes from grid_types. Nexus reconstructs them on the client; PointNav is not needed in the notebook. Attributes use Python names below. Their to_dict() / from_dict() methods describe application-level serialization; the Nexus wire envelope is handled by the SDK.

Coordinates and units

All public Waypoint, Path, and NavPose XY values use the active map frame in metres. Yaw is in radians, zero along map +X and positive toward +Y. Do not send grid-cell indices, image pixels, GPS coordinates, or robot-relative offsets. Public Waypoint has no yaw field; these examples cannot request terminal heading through a Waypoint. Saved missions can carry heading data.

Waypoint

Field	Type	Default / meaning
`x`, `y`	`float`	Required map coordinates.
`name`	`str`	`""`; descriptive identifier. Does not create a saved waypoint.
`label`	`str`	`""`; semantic label.
`confidence`	`float` or `None`	`None`; current semantic search provides no per-match confidence.

Path

Field	Type	Default / meaning
`waypoints`	`list[Waypoint]`	Required ordered sparse stops. Construction also accepts `(x, y)` pairs.
`route`	`list[Waypoint]` or `None`	`None` until planned; dense route through the stops.
`map_id`	`str`	`""`; set this to the map UUID to detect accidental map mismatch.
`name`	`str`	`""`; descriptive path name, not a persistence operation.

Constructing a Path does not plan or move. Path entries cannot be semantic strings; use nav.plan(["kitchen", "hallway"]) for those. Path.from_dict expects nested waypoint dictionaries. For example, this is an illustrative sparse-path dictionary, not a robot command:

{
  "waypoints": [
    {"x": 4.0, "y": 1.5, "name": "inspection", "label": "", "confidence": null}
  ],
  "route": null,
  "map_id": "YOUR_MAP_UUID",
  "name": "Inspection stops"
}

Store path.to_dict() as JSON if useful, but rebuild a sparse Path from its waypoints and plan it from the robot’s new pose before reuse. No save_path or list_waypoints method is provided by this remote workflow.

NavPose

Field	Type	Meaning
`x`, `y`, `yaw`	`float`	Required map-frame pose.
`quality`	`float`	Required localization quality; higher is better, not a calibrated probability or universal acceptance threshold.
`localized`	`bool`	Required flag indicating a valid localized estimate.

to_pose() converts to a 3D Pose at (x, y, 0) with a yaw quaternion. pose() reads the latest estimate; localize() waits for a fresh accepted fix.

NavState and NavLocalizationState

NavState field	Type	Default / meaning
`state`	`str`	Required: `cold`, `initializing`, `ready`, `running`, `stopping`, `stopped`, or `shutdown`.
`map_id`	`str`	`""` when no map is bound.
`localization`	`NavLocalizationState` or `None`	`None` without localization workers.
`mission_running`	`bool`	`False`; use this to poll completion.
`mission_id`	`str`	`""` before a run; otherwise the runtime run identifier.

NavLocalizationState field	Type	Default / meaning
`map_id`, `state`	`str`	Required map and localization state: `cold`, `warming`, `ready`, `degraded`, or `closed`.
`pose`	`NavPose` or `None`	`None` until available.
`quality`	`float`	`0.0`; quality of the localization estimate.
`fusion_decision`	`str`	`""`; diagnostic fusion decision.
`stamp`	`float`	`0.0`; pose timestamp in Unix seconds.

Runtime readiness and mission success are different: ready means another mission can be attempted, not that the preceding mission succeeded.

MissionResult

Returned by blocking run_mission / move_to:

Field	Type	Default / meaning
`run_id`	`str`	Required identifier for this execution.
`status`	`str`	Required terminal status: `succeeded`, `cancelled`, or `failed`.
`message`	`str`	`""`; exit reason or worker error.
`final_pose`	`NavPose` or `None`	`None` when unavailable; pose sampled when the result is collected.

Require result.status == "succeeded" before continuing an arrival-dependent task. nav.result() has a different, raw dictionary schema; see non-blocking completion.

Catalog records

These are immutable metadata records; every field is required and a str.

Record	Fields	Meaning
`NavMapInfo`	`map_id`, `name`, `status`, `updated_at`	Map-job ID, display name, build status, and server timestamp. Only `COMPLETED` maps are usable.
`NavPathInfo`	`path_id`, `map_id`, `name`, `created_at`, `updated_at`	Saved-path ID, owning map, name, and server timestamps. Does not contain waypoints or a route.

Timestamps are server strings, not Python datetime objects. Pass path_id to run_mission after starting the owning map. A catalog read does not select a map, download a route, or start motion.

Telemetry and log payloads

These diagnostic dictionaries are not shared data classes. Use the envelope keys below and tolerate additional diagnostic keys from newer runtimes.

Telemetry key	Type / meaning
`version`	Integer envelope version, currently 1.
`epoch`	Opaque string identifying the cache generation; reset the cursor to zero when it changes.
`sequence`, `since`	Nonnegative integer sequence cursors, not timestamps.
`t_ns`	Integer snapshot timestamp in nanoseconds.
`errors`	Integer count of telemetry errors/dropped data.
`log_id`	Opaque string identifying the current terminal log, or `None`.
`streams`	Mapping of stream names to entries with `sequence`, `data`, `t_ns`, `kind`, and `vis`. `data` is a NumPy array after Nexus decoding.
`status`	NavState fields plus `progress`, raw `result`, and `error` diagnostics.

A log reply has log_id (string), start, end, size (integer byte offsets/size), and text (UTF-8 string). Follow using end as the next offset; read history using start as the next before cursor. Do not compute byte cursors from Python string length. See viewer and diagnostics for call arguments. Stream internals and progress/event payloads are diagnostic, not a stable replacement for NavState or the mission result contract.

Configuration and policy schemas

Configuration JSON Schema describes the dictionary accepted as cfg at attach time. The configuration guide explains additional shape and cross-field validation. Polygon constraints have a separate versioned schema passed per mission. Neither schema defines agent tool names or bypasses the current runtime’s validation.

Get Started

Simulation

Navigation

Deployment

FAQ

Support

Navigation data schemas

Coordinates and units

Waypoint

Path

NavPose

NavState and NavLocalizationState

MissionResult

Catalog records

Telemetry and log payloads

Configuration and policy schemas

​Coordinates and units

​Waypoint

​Path

​NavPose

​NavState and NavLocalizationState

​MissionResult

​Catalog records

​Telemetry and log payloads

​Configuration and policy schemas

Coordinates and units

Waypoint

Path

NavPose

NavState and NavLocalizationState

MissionResult

Catalog records

Telemetry and log payloads

Configuration and policy schemas