Navigation

Autonomous navigation and mapping.

Note

robot.navigation does not launch or tear down Nav2 — it only sends goals and queries the live stack. Start and stop the engine with client.platform.navigation.start / stop (see Simple navigation and Platform). Call robot.navigation.state() to probe NavigateToPose readiness after the deployment reports ready. Operations report typed errors when their runtime dependencies are unavailable.

Python

import math
import time

from olo import Client
from olo.locomotion import PlanarMotion
from olo.navigation import Nav2ErrorCode, NavigationFeedback
from olo.platform import NavigationMode, NavigationObservedState
from olo.spatial import Pose

EXAMPLE_MAP_NAME = "example-map"


def on_feedback(feedback: NavigationFeedback) -> None:
    # Do something with the feedback
    pass


with Client() as client:
    configs = client.platform.navigation.get_configs(NavigationMode.SLAM)
    if not configs:
        raise RuntimeError("No navigation configs support SLAM mode")
    config = configs[0]
    print(f"Using navigation config: {config.name = }, {config.id = }")

    # Start navigation engine (namespace resolves like client.robot())
    client.platform.navigation.start(mode=NavigationMode.SLAM, config_id=config.id)
    last_state = None
    deadline = time.time() + 60
    while time.time() < deadline:
        observed = client.platform.navigation.deployment().observed
        state = observed.state if observed else None
        if state != last_state:
            print(f"Navigation engine: {state}")
            last_state = state
        if state == NavigationObservedState.READY:
            break
        if observed is not None and state == NavigationObservedState.FAILED:
            raise RuntimeError(f"Navigation failed to launch: {observed.error_message}")
        time.sleep(2)
    else:
        raise TimeoutError(f"Navigation engine did not become ready within 60s (last state: {last_state})")

    # Move the robot to build a map
    robot = client.robot()
    robot.locomotion.move(PlanarMotion(x=1.0, yaw=2 * math.pi))

    # Once the map has some substance, send the robot a pose goal
    target = Pose.from_xy_yaw(1.5, 0.5, 1.5708)
    result = robot.navigation.navigate_to(target, on_feedback=on_feedback)
    print(f"Navigation outcome: {result.outcome.value} ({result.reason})")
    if result.nav2_error_code:
        print(f"Error: {Nav2ErrorCode.name_for(result.nav2_error_code)}")

    # Persist the SLAM map for reuse
    saved = robot.navigation.save_map(EXAMPLE_MAP_NAME)
    print(f"Saved map: {saved.name} [{saved.id}]")

TypeScript

import { connect } from "olo/web";
import { nav2ErrorCodeName, type NavigationFeedback } from "olo/navigation";
import { Pose } from "olo/spatial";

const EXAMPLE_MAP_NAME = "example-map";

function onFeedback(_feedback: NavigationFeedback): void {
  // Do something with the feedback
}

const client = connect();

const configs = await client.platform.navigation.getConfigs("slam");
const config = configs[0];
if (config === undefined) {
  throw new Error("No navigation configs support SLAM mode");
}
console.log(`Using navigation config: name=${config.name}, id=${config.id}`);

// Start navigation engine (namespace resolves like client.robot())
await client.platform.navigation.start({
  mode: "slam",
  configId: config.id,
});
let lastState: string | undefined;
const deadline = Date.now() + 60_000;
while (Date.now() < deadline) {
  const info = await client.platform.navigation.deployment();
  const state = info.observed?.state;
  if (state !== lastState) {
    console.log(`Navigation engine: ${state}`);
    lastState = state;
  }
  if (state === "ready") break;
  if (state === "failed") {
    throw new Error(`Navigation failed to launch: ${info.observed?.errorMessage}`);
  }
  await new Promise((r) => setTimeout(r, 2000));
}
if (lastState !== "ready") {
  throw new Error(`Navigation engine did not become ready within 60s (last state: ${lastState})`);
}

// Move the robot to build a map
const robot = await client.robot();
await robot.locomotion.move({ x: 1.0, y: 0, yaw: 2 * Math.PI });

// Once the map has some substance, send the robot a pose goal
const target = Pose.fromXyYaw(1.5, 0.5, 1.5708);
const result = await robot.navigation.navigateTo(target, { onFeedback });
console.log(`Navigation outcome: ${result.outcome} (${result.reason})`);
if (result.nav2ErrorCode) {
  console.log(`Error: ${nav2ErrorCodeName(result.nav2ErrorCode)}`);
}

// Persist the SLAM map for reuse
const saved = await robot.navigation.saveMap(EXAMPLE_MAP_NAME);
console.log(`Saved map: ${saved.name} [${saved.id}]`);

Python

Navigation wrapper over olo.navigation.v1.Navigation.

Client interfaces

class olo.navigation.Navigation

Bases: object

Sync wrapper for the navigation gRPC service.

__init__(session)

Bind to a channel session.

Return type:

None

cancel_all(robot_namespace='', *, timeout=10.0)

Cancel all owned navigation goals for a namespace.

Return type:

tuple[str, ...]

Parameters:

• robot_namespace (str)

• timeout (float)

cancel_navigation(goal_id, *, timeout=10.0)

Cancel one owned navigation goal.

Return type:

None

Parameters:

• goal_id (str)

• timeout (float)

check_reachability(goal, *, robot_namespace='', frame='map', start=None, use_start=False, planner_id='', timeout=10.0)

Ask Nav2 whether a goal pose is planner-reachable.

Return type:

ReachabilityResult

Parameters:

• goal (Pose)

• robot_namespace (str)

• frame (str)

• start (Pose | None)

• use_start (bool)

• planner_id (str)

• timeout (float)

get_map(robot_namespace='', *, topic='map', timeout=10.0)

Fetch one occupancy-grid snapshot from the robot map topic.

Return type:

OccupancyGrid

Parameters:

• robot_namespace (str)

• topic (str)

• timeout (float)

handle(namespace=None)

Return a namespace-scoped navigation handle.

Return type:

NavigationHandle

Parameters:

namespace (str | None)

navigate_to(target, *, robot_namespace='', frame='map', navigation_timeout=120.0, on_feedback=None, timeout=10.0)

Start navigation and wait for the terminal outcome.

Return type:

NavigationResult

Parameters:

• target (Pose)

• robot_namespace (str)

• frame (str)

• navigation_timeout (float)

• on_feedback (Callable[[NavigationFeedback], None] | None)

• timeout (float)

save_map(name, *, robot_namespace='', description='', timeout=65.0)

Save the live occupancy grid to the organization’s map library.

Return type:

MapInfo

Parameters:

• name (str)

• robot_namespace (str)

• description (str)

• timeout (float)

send_navigation_goal(target, *, robot_namespace='', frame='map', navigation_timeout=120.0, timeout=10.0)

Send a NavigateToPose goal and return a goal handle.

Return type:

NavigationGoal

Parameters:

• target (Pose)

• robot_namespace (str)

• frame (str)

• navigation_timeout (float)

• timeout (float)

set_initial_pose(pose, *, robot_namespace='', frame='map', timeout=10.0)

Seed AMCL localization with the robot’s pose in the map frame.

Return type:

None

Parameters:

• pose (Pose)

• robot_namespace (str)

• frame (str)

• timeout (float)

state(robot_namespace='', *, timeout=10.0)

Fetch a live navigation capability snapshot.

Return type:

NavigationState

Parameters:

• robot_namespace (str)

• timeout (float)

class olo.navigation.NavigationHandle

Bases: object

Namespace-scoped handle for navigation behavior scripting.

__init__(client, namespace, session)

Bind to a client, resolved namespace, and spatial frames.

Parameters:

• client (Navigation)

• namespace (str)

Return type:

None

cancel_all(*, timeout=10.0)

Cancel all owned goals for this robot.

Return type:

tuple[str, ...]

Parameters:

timeout (float)

check_reachability(goal, *, frame='map', start=None, use_start=False, planner_id='', timeout=10.0)

Ask Nav2 whether a goal pose is planner-reachable for this robot.

Return type:

ReachabilityResult

Parameters:

• goal (Pose)

• frame (str)

• start (Pose | None)

• use_start (bool)

• planner_id (str)

• timeout (float)

current_pose(*, timeout=10.0)

Return the stamped map-to-base transform via spatial TF lookup.

Return type:

Transform

Parameters:

timeout (float)

get_map(*, topic='map', timeout=10.0)

Fetch one occupancy-grid snapshot for this robot.

Return type:

OccupancyGrid

Parameters:

• topic (str)

• timeout (float)

navigate_to(target, *, frame='map', navigation_timeout=120.0, on_feedback=None, timeout=10.0)

Start navigation and wait for completion.

Return type:

NavigationResult

Parameters:

• target (Pose)

• frame (str)

• navigation_timeout (float)

• on_feedback (Callable[[NavigationFeedback], None] | None)

• timeout (float)

save_map(name, *, description='', timeout=65.0)

Save this robot’s live occupancy grid to the map library.

Return type:

MapInfo

Parameters:

• name (str)

• description (str)

• timeout (float)

send_navigation_goal(target, *, frame='map', navigation_timeout=120.0, timeout=10.0)

Send a NavigateToPose goal without waiting for completion.

Return type:

NavigationGoal

Parameters:

• target (Pose)

• frame (str)

• navigation_timeout (float)

• timeout (float)

set_initial_pose(pose, *, frame='map', timeout=10.0)

Seed AMCL localization for this robot.

Return type:

None

Parameters:

• pose (Pose)

• frame (str)

• timeout (float)

state(*, timeout=10.0)

Fetch a live capability snapshot for this robot.

Return type:

NavigationState

Parameters:

timeout (float)

class olo.navigation.NavigationGoal

Bases: object

Handle for an accepted long-running navigation goal.

__init__(client, goal_id)

Bind to a navigation client and server-generated goal id.

Parameters:

• client (Navigation)

• goal_id (str)

Return type:

None

cancel(*, timeout=10.0)

Cancel this goal.

Return type:

None

Parameters:

timeout (float)

wait(*, on_feedback=None, timeout=None)

Block until the goal reaches a terminal outcome.

Return type:

NavigationResult

Parameters:

• on_feedback (Callable[[NavigationFeedback], None] | None)

• timeout (float | None)

Types

class olo.navigation.NavigationState

Bases: object

Capability snapshot for a robot namespace.

__init__(availability=Availability.UNSPECIFIED, activity=Activity.UNSPECIFIED, owned_goal_ids=(), reason='')

Parameters:

• availability (Availability)

• activity (Activity)

• owned_goal_ids (tuple[str, ...])

• reason (str)

Return type:

None

property ready: bool

Return whether NavigateToPose is ready.

class olo.navigation.NavigationFeedback

Bases: object

Progress update for an active navigation goal.

__init__(distance_remaining=0.0, navigation_time=0.0, number_of_recoveries=0, current_pose=<factory>)

Parameters:

• distance_remaining (float)

• navigation_time (float)

• number_of_recoveries (int)

• current_pose (Pose)

Return type:

None

class olo.navigation.NavigationResult

Bases: object

Terminal result for a navigation goal.

__init__(outcome=NavigationOutcome.UNSPECIFIED, reason='', nav2_error_code=0)

Parameters:

• outcome (NavigationOutcome)

• reason (str)

• nav2_error_code (int)

Return type:

None

property nav2_error: Nav2ErrorCode | None

Return the Nav2 error code when present.

class olo.navigation.OccupancyGrid

Bases: object

Decoded occupancy grid with map-frame metadata.

__init__(frame_id, resolution, width, height, origin, data, stamp=None)

Parameters:

• frame_id (str)

• resolution (float)

• width (int)

• height (int)

• origin (Pose)

• data (ndarray)

• stamp (float | None)

Return type:

None

cell_to_world(cell_x, cell_y)

Return the map-frame centre of a grid cell.

Return type:

tuple[float, float]

Parameters:

• cell_x (int)

• cell_y (int)

in_bounds(cell_x, cell_y)

Return whether a grid cell lies inside the map.

Return type:

bool

Parameters:

• cell_x (int)

• cell_y (int)

is_free(cell_x, cell_y)

Return whether a cell is known free space.

Return type:

bool

Parameters:

• cell_x (int)

• cell_y (int)

is_occupied(cell_x, cell_y)

Return whether a cell is known occupied space.

Return type:

bool

Parameters:

• cell_x (int)

• cell_y (int)

is_unknown(cell_x, cell_y)

Return whether a cell is unexplored.

Return type:

bool

Parameters:

• cell_x (int)

• cell_y (int)

pose_at(cell_x, cell_y, *, yaw=0.0)

Return a map-frame pose at the centre of a grid cell.

Return type:

Pose

Parameters:

• cell_x (int)

• cell_y (int)

• yaw (float)

value_at(cell_x, cell_y)

Return the occupancy value for a grid cell.

Return type:

int

Parameters:

• cell_x (int)

• cell_y (int)

world_to_cell(x, y)

Convert a map-frame world point to grid indices.

Return type:

tuple[int, int]

Parameters:

• x (float)

• y (float)

class olo.navigation.ReachabilityResult

Bases: object

Planner-backed reachability for a map-frame goal.

__init__(reachable=False, planner_error_code=0, reason='', path_length=0.0)

Parameters:

• reachable (bool)

• planner_error_code (int)

• reason (str)

• path_length (float)

Return type:

None

Enums

class olo.navigation.Availability

Bases: Enum

Whether NavigateToPose is available for a namespace.

class olo.navigation.Activity

Bases: Enum

Whether this executor currently owns an active navigation goal.

class olo.navigation.NavigationOutcome

Bases: Enum

Terminal outcome for a navigation goal.

TypeScript

Import from olo/navigation:

Client interfaces

• Navigation — service wrapper with state, start, navigate, cancel, and handle().

• NavigationHandle — namespace-scoped scripting surface, including currentPose() via spatial TF.

• NavigationGoal — accepted goal with async result(), async iteration, and cancel().

Types

• NavigationState

• Availability

• Activity

• NavigationOutcome

• OccupancyGrid

• ReachabilityResult