viam.services.navigation

Submodules

• viam.services.navigation.client
• viam.services.navigation.navigation
• viam.services.navigation.service

Classes

GetCostmapResponse	Abstract base class for protocol messages.
GoalState
GoalStatus	GoalStatus is one goal and its lifecycle. Returned (embedded in Status) by
Location	Location is a named Position on the active map.
MapType	MapType represents the type of map the navigation service operates on.
NavError	Abstract base class for protocol messages.
NavErrorCode
NavMode
Plan	Plan is a path preview returned by PlanToPoint and PlanToLocation.
Position	Position is a shared oneof for any map-typed position. Exactly one of pose or
Progress	Abstract base class for protocol messages.
Properties	Properties are returned by GetProperties and do not change while the service
Route	Route is an ordered list of waypoints. A location can appear in more than one
RouteProgress	Abstract base class for protocol messages.
Status	Status is the robot navigation state returned by GetNavigationStatus and by methods that
Velocity	Abstract base class for protocol messages.
Waypoint	Waypoint is a route stop: either the name of a saved Location or an inline
Zone	Zone is a named region on the active map. Geometry is a Struct following the
NavigationClient	Connect to the NavigationService, which allows the robot to navigate to specified locations.

Package Contents

class viam.services.navigation.GetCostmapResponse(*, available: bool = ..., layer: str = ..., nav_backend: str = ..., origin_x: float = ..., origin_y: float = ..., resolution: float = ..., width: int = ..., height: int = ..., encoding: str = ..., data: bytes = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

available: bool

layer: str

nav_backend: str

origin_x: float

Map-frame origin, meters

origin_y: float

resolution: float

Meters per cell

width: int

Cells

height: int

encoding: str

“uint8_row_major”

data: bytes

Costs 0–100; unknown cells are 255

class viam.services.navigation.GoalState

Bases: _GoalState

class viam.services.navigation.GoalStatus(*, state: Global___GoalState = ..., mode: Global___NavMode = ..., target: Global___Position | None = ..., location: str | None = ..., progress: Global___Progress | None = ..., route: Global___RouteProgress | None = ..., suspend_reason: str | None = ..., error: Global___NavError | None = ..., started_at: google.protobuf.timestamp_pb2.Timestamp | None = ..., finished_at: google.protobuf.timestamp_pb2.Timestamp | None = ...)

Bases: google.protobuf.message.Message

GoalStatus is one goal and its lifecycle. Returned (embedded in Status) by every method that starts, suspends, resumes, or cancels motion, and embedded in Status from GetNavigationStatus. Only the latest goal is kept. SUCCEEDED, FAILED, and CANCELED are terminal.

state: Global___GoalState

mode: Global___NavMode

location: str

Set when the target is a saved location

suspend_reason: str

When SUSPENDED

target() → Global___Position

For a route, the current waypoint

progress() → Global___Progress

While ACTIVE

route() → Global___RouteProgress

When mode == NAV_MODE_ROUTE

error() → Global___NavError

When FAILED

started_at() → google.protobuf.timestamp_pb2.Timestamp

finished_at() → google.protobuf.timestamp_pb2.Timestamp

Set once terminal

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: _WhichOneofArgType__error) → _WhichOneofReturnType__error | None

WhichOneof(oneof_group: _WhichOneofArgType__finished_at) → _WhichOneofReturnType__finished_at | None

WhichOneof(oneof_group: _WhichOneofArgType__location) → _WhichOneofReturnType__location | None

WhichOneof(oneof_group: _WhichOneofArgType__progress) → _WhichOneofReturnType__progress | None

WhichOneof(oneof_group: _WhichOneofArgType__route) → _WhichOneofReturnType__route | None

WhichOneof(oneof_group: _WhichOneofArgType__suspend_reason) → _WhichOneofReturnType__suspend_reason | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.services.navigation.Location(*, name: str = ..., position: Global___Position | None = ...)

Bases: google.protobuf.message.Message

Location is a named Position on the active map.

name: str

position() → Global___Position

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.services.navigation.MapType

Bases: _MapType

MapType represents the type of map the navigation service operates on. Each service instance uses exactly one map type.

class viam.services.navigation.NavError(*, code: Global___NavErrorCode = ..., message: str = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

code: Global___NavErrorCode

message: str

class viam.services.navigation.NavErrorCode

Bases: _NavErrorCode

class viam.services.navigation.NavMode

Bases: _NavMode

class viam.services.navigation.Plan(*, path: collections.abc.Iterable[Global___Position] | None = ..., location: str | None = ..., length_m: float = ...)

Bases: google.protobuf.message.Message

Plan is a path preview returned by PlanToPoint and PlanToLocation.

location: str

Set by PlanToLocation

length_m: float

path() → google.protobuf.internal.containers.RepeatedCompositeFieldContainer[Global___Position]

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: _WhichOneofArgType__location) → _WhichOneofReturnType__location | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.services.navigation.Position(*, pose: common.v1.common_pb2.Pose | None = ..., geo_pose: common.v1.common_pb2.GeoPose | None = ...)

Bases: google.protobuf.message.Message

Position is a shared oneof for any map-typed position. Exactly one of pose or geo_pose is set; the service rejects a value that does not match GetProperties map type.

pose() → common.v1.common_pb2.Pose

MAP_TYPE_LOCAL — common.Pose in the map frame

geo_pose() → common.v1.common_pb2.GeoPose

MAP_TYPE_GPS — common.GeoPose

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: _WhichOneofArgType_value) → _WhichOneofReturnType_value | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.services.navigation.Progress(*, distance_remaining_m: float = ..., path: collections.abc.Iterable[Global___Position] | None = ..., length_m: float = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

distance_remaining_m: float

length_m: float

Same meaning as Plan.length_m

path() → google.protobuf.internal.containers.RepeatedCompositeFieldContainer[Global___Position]

PLANNED and ROUTE only; updates on replan

class viam.services.navigation.Properties(*, map_type: Global___MapType = ..., footprint_length_m: float = ..., footprint_width_m: float = ..., robot_radius_m: float = ..., planning_supported: bool = ..., costmap_supported: bool = ..., zones_supported: bool = ..., routes_supported: bool = ...)

Bases: google.protobuf.message.Message

Properties are returned by GetProperties and do not change while the service is running.

map_type: Global___MapType

footprint_length_m: float

footprint_width_m: float

robot_radius_m: float

planning_supported: bool

PlanTo*, ExecutePlan, NavigateTo*

costmap_supported: bool

GetCostmap

zones_supported: bool

Keep-out / speed-limit zones

routes_supported: bool

Route store + NavigateRoute

class viam.services.navigation.Route(*, name: str = ..., waypoints: collections.abc.Iterable[Global___Waypoint] | None = ...)

Bases: google.protobuf.message.Message

Route is an ordered list of waypoints. A location can appear in more than one route, and more than once in the same route.

name: str

waypoints() → google.protobuf.internal.containers.RepeatedCompositeFieldContainer[Global___Waypoint]

class viam.services.navigation.RouteProgress(*, name: str = ..., waypoints: collections.abc.Iterable[Global___Waypoint] | None = ..., index: int = ..., loop: bool = ..., lap: int = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str

Empty for inline routes

index: int

Current waypoint; waypoints[index] is the target

loop: bool

lap: int

waypoints() → google.protobuf.internal.containers.RepeatedCompositeFieldContainer[Global___Waypoint]

class viam.services.navigation.Status(*, position: Global___Position | None = ..., localized: bool = ..., velocity: Global___Velocity | None = ..., goal: Global___GoalStatus | None = ..., updated_at: google.protobuf.timestamp_pb2.Timestamp | None = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Status is the robot navigation state returned by GetNavigationStatus and by methods that start, suspend, or resume motion. The robot is idle when goal is unset or goal.state is terminal. It is moving when goal.state == GOAL_STATE_ACTIVE. Methods that start motion fail while localized is false.

localized: bool

Pose is trusted; false blocks new goals

position() → Global___Position

Same as GetPosition

velocity() → Global___Velocity

Current body-frame velocity; zero when stopped

goal() → Global___GoalStatus

Latest goal; unset until the first one

updated_at() → google.protobuf.timestamp_pb2.Timestamp

extra() → google.protobuf.struct_pb2.Struct

Backend-specific diagnostics

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: _WhichOneofArgType__goal) → _WhichOneofReturnType__goal | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.services.navigation.Velocity(*, linear_m_per_sec: float = ..., angular_deg_per_sec: float = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

linear_m_per_sec: float

Forward linear velocity

angular_deg_per_sec: float

Yaw rate, counterclockwise positive

class viam.services.navigation.Waypoint(*, location: str = ..., position: Global___Position | None = ...)

Bases: google.protobuf.message.Message

Waypoint is a route stop: either the name of a saved Location or an inline Position.

location: str

position() → Global___Position

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: _WhichOneofArgType_value) → _WhichOneofReturnType_value | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.services.navigation.Zone(*, name: str = ..., type: str = ..., geometry: google.protobuf.struct_pb2.Struct | None = ..., max_speed: float | None = ...)

Bases: google.protobuf.message.Message

Zone is a named region on the active map. Geometry is a Struct following the Geometry shapes described in the Navigation API (circle, box, or polygon). Units follow the map type: millimeters on local maps, meters for GPS radii and sizes.

name: str

type: str

“keepout” or “speed_limit”

max_speed: float

Max speed in meters/sec; required when type is “speed_limit”

geometry() → google.protobuf.struct_pb2.Struct

HasField(field_name: _HasFieldArgType) → bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: _WhichOneofArgType__max_speed) → _WhichOneofReturnType__max_speed | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.services.navigation.NavigationClient(name: str, channel: grpclib.client.Channel)

Bases: viam.services.navigation.navigation.Navigation, viam.resource.rpc_client_base.ReconfigurableResourceRPCClientBase

Connect to the NavigationService, which allows the robot to navigate to specified locations.

client: viam.proto.service.navigation.NavigationServiceStub

channel

async add_location(location_name: str, position: viam.proto.service.navigation.Position | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Location

Save a named Location on the active map.

Parameters:

• location_name (str) – The name of the location to save.

• position (Optional[navigation.Position]) – The position to save. Omit to use the robot’s current position.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The saved location.

Return type:

navigation.Location

async get_location(location_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Location

Get a previously saved Location by name.

Parameters:

• location_name (str) – The name of the location to retrieve.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The requested location.

Return type:

navigation.Location

async list_locations(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → List[viam.proto.service.navigation.Location]

List all previously saved Locations.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

All saved locations.

Return type:

List[navigation.Location]

async update_location(location_name: str, position: viam.proto.service.navigation.Position | None = None, new_name: str | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Location

Update a previously saved Location.

Parameters:

• location_name (str) – The name of the location to update.

• position (Optional[navigation.Position]) – The new position. Omit to leave the position unchanged.

• new_name (Optional[str]) – The new name for the location. Omit to leave the name unchanged.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The updated location.

Return type:

navigation.Location

async delete_location(location_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → None

Delete a previously saved Location.

Parameters:

• location_name (str) – The name of the location to delete.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

async add_route(route_name: str, waypoints: List[viam.proto.service.navigation.Waypoint] | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Route

Save a named Route, an ordered list of waypoints.

Parameters:

• route_name (str) – The name of the route to save.

• waypoints (Optional[List[navigation.Waypoint]]) – The ordered waypoints that make up the route.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The saved route.

Return type:

navigation.Route

async get_route(route_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Route

Get a previously saved Route by name.

Parameters:

• route_name (str) – The name of the route to retrieve.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The requested route.

Return type:

navigation.Route

async list_routes(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → List[viam.proto.service.navigation.Route]

List all previously saved Routes.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

All saved routes.

Return type:

List[navigation.Route]

async update_route(route_name: str, new_name: str | None = None, waypoints: List[viam.proto.service.navigation.Waypoint] | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Route

Update a previously saved Route.

Parameters:

• route_name (str) – The name of the route to update.

• new_name (Optional[str]) – The new name for the route. Omit to leave the name unchanged.

• waypoints (Optional[List[navigation.Waypoint]]) – The new ordered waypoints. Omit to leave the waypoints unchanged; pass an empty list to clear them.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The updated route.

Return type:

navigation.Route

async delete_route(route_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → None

Delete a previously saved Route.

Parameters:

• route_name (str) – The name of the route to delete.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

async add_zone(zone_name: str, type: str, geometry: Dict[str, Any], max_speed: float | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Zone

Save a named Zone, a region on the active map.

Parameters:

• zone_name (str) – The name of the zone to save.

• type (str) – The type of zone, either “keepout” or “speed_limit”.

• geometry (Dict[str, Any]) – The shape of the zone (circle, box, or polygon).

• max_speed (Optional[float]) – Max speed in meters/sec; required when type is “speed_limit”.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The saved zone.

Return type:

navigation.Zone

async get_zone(zone_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Zone

Get a previously saved Zone by name.

Parameters:

• zone_name (str) – The name of the zone to retrieve.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The requested zone.

Return type:

navigation.Zone

async list_zones(type: str | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → List[viam.proto.service.navigation.Zone]

List all previously saved Zones.

Parameters:

• type (Optional[str]) – Filter by zone type, either “keepout” or “speed_limit”.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

All saved zones matching the filter, if provided.

Return type:

List[navigation.Zone]

async update_zone(zone_name: str, type: str | None = None, geometry: Dict[str, Any] | None = None, max_speed: float | None = None, new_name: str | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Zone

Update a previously saved Zone.

Parameters:

• zone_name (str) – The name of the zone to update.

• type (Optional[str]) – The new zone type. Omit to leave unchanged.

• geometry (Optional[Dict[str, Any]]) – The new shape of the zone. Omit to leave unchanged.

• max_speed (Optional[float]) – The new max speed in meters/sec. Omit to leave unchanged.

• new_name (Optional[str]) – The new name for the zone. Omit to leave the name unchanged.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The updated zone.

Return type:

navigation.Zone

async delete_zone(zone_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → None

Delete a previously saved Zone.

Parameters:

• zone_name (str) – The name of the zone to delete.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

async navigate_to_location(location_name: str, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Start navigating to a previously saved Location.

Parameters:

• location_name (str) – The name of the location to navigate to.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async navigate_to_point(destination: viam.proto.service.navigation.Position, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Start navigating to a destination Position.

Parameters:

• destination (navigation.Position) – The destination to navigate to.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async navigate_route(route_name: str | None = None, waypoints: List[viam.proto.service.navigation.Waypoint] | None = None, start_index: int = 0, start_nearest: bool = False, loop: bool = False, wait: bool = False, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Start navigating a Route, either a previously saved one or an inline list of waypoints.

Parameters:

• route_name (Optional[str]) – The name of a previously saved route.

• waypoints (Optional[List[navigation.Waypoint]]) – An inline list of waypoints.

• start_index (int) – The index of the waypoint to start at.

• start_nearest (bool) – Start at the waypoint nearest to the robot’s current position, overriding start_index.

• loop (bool) – Loop the route indefinitely.

• wait (bool) – With loop, only return once the robot has stopped.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async plan_to_point(destination: viam.proto.service.navigation.Position, start: viam.proto.service.navigation.Position | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Plan

Preview a path to a destination Position without moving the robot.

Parameters:

• destination (navigation.Position) – The destination to plan to.

• start (Optional[navigation.Position]) – The position to plan from. Defaults to the robot’s current position.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The planned path.

Return type:

navigation.Plan

async plan_to_location(location_name: str, start: viam.proto.service.navigation.Position | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Plan

Preview a path to a previously saved Location without moving the robot.

Parameters:

• location_name (str) – The name of the location to plan to.

• start (Optional[navigation.Position]) – The position to plan from. Defaults to the robot’s current position.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The planned path.

Return type:

navigation.Plan

async execute_plan(plan: viam.proto.service.navigation.Plan, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Start navigating a previously previewed Plan.

Parameters:

• plan (navigation.Plan) – The plan to execute, as returned by plan_to_point or plan_to_location.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async go_to_location(location_name: str, wait: bool | None = None, linear_m_per_sec: float | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Drive directly to a previously saved Location, without planning around zones or obstacles.

Parameters:

• location_name (str) – The name of the location to drive to.

• wait (Optional[bool]) – Whether to wait until the robot has arrived. Defaults to true.

• linear_m_per_sec (Optional[float]) – The linear speed to drive at.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async go_to_point(destination: viam.proto.service.navigation.Position, wait: bool | None = None, linear_m_per_sec: float | None = None, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Drive directly to a destination Position, without planning around zones or obstacles.

Parameters:

• destination (navigation.Position) – The destination to drive to.

• wait (Optional[bool]) – Whether to wait until the robot has arrived. Defaults to true.

• linear_m_per_sec (Optional[float]) – The linear speed to drive at.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async suspend(reason: str = '', *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Suspend the current goal, holding position until resume is called.

Parameters:

• reason (str) – The reason for suspending, reported on the suspended goal.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async resume(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Resume a previously suspended goal.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async cancel(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Cancel the current goal.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The resulting navigation status.

Return type:

navigation.Status

async get_position(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Position

Get the current position of the robot in the navigation service.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The current position of the robot.

Return type:

navigation.Position

async get_navigation_status(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Status

Get the current navigation state of the robot.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The current navigation status.

Return type:

navigation.Status

async get_properties(*, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.Properties

Get information about the navigation service that does not change while the service is running.

Parameters:

timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

Information about the navigation service.

Return type:

navigation.Properties

async get_costmap(layer: str = '', stride: int = 0, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) → viam.proto.service.navigation.GetCostmapResponse

Get a costmap describing the obstacles known to the navigation service.

Parameters:

• layer (str) – Which costmap layer to retrieve, one of “auto”, “local”, or “global”. Defaults to “auto”.

• stride (int) – Downsample factor. Defaults to 2.

• timeout (Optional[float]) – An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

The requested costmap.

Return type:

navigation.GetCostmapResponse

async do_command(command: Mapping[str, viam.utils.ValueTypes], *, timeout: float | None = None, **kwargs) → Mapping[str, viam.utils.ValueTypes]

Send/receive arbitrary commands.

service = SERVICE.from_robot(robot=machine, "builtin")  # replace SERVICE with the appropriate class

my_command = {
  "cmnd": "dosomething",
  "someparameter": 52
}

# Can be used with any resource, using the motion service as an example
await service.do_command(command=my_command)

Parameters:

command (Dict[str, ValueTypes]) – The command to execute

Returns:

Result of the executed command

Return type:

Dict[str, ValueTypes]

async get_status(*, timeout: float | None = None, **kwargs) → Mapping[str, viam.utils.ValueTypes]

Get the current status of the service as a dictionary.

status = await service.get_status()

Returns:

The status of the service

Return type:

Mapping[str, ValueTypes]

classmethod from_robot(robot: viam.robot.client.RobotClient, name: str) → Self

Get the service named name from the provided robot.

async def connect() -> RobotClient:
    # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
    options = RobotClient.Options.with_api_key("<API-KEY>", "<API-KEY-ID>")
    # Replace "<MACHINE-URL>" (included brackets) with your machine's connection URL or FQDN
    return await RobotClient.at_address("<MACHINE-URL>", options)

async def main():
    robot = await connect()

    # Can be used with any resource, using the motion service as an example
    motion = MotionClient.from_robot(robot=machine, name="builtin")

    robot.close()

Parameters:

• robot (RobotClient) – The robot

• name (str) – The name of the service

Returns:

The service, if it exists on the robot

Return type:

Self

classmethod get_resource_name(name: str) → viam.proto.common.ResourceName

Get the ResourceName for this Resource with the given name

# Can be used with any resource, using an arm as an example
my_arm_name = Arm.get_resource_name("my_arm")

Parameters:

name (str) – The name of the Resource

Returns:

The ResourceName of this Resource

Return type:

ResourceName

get_operation(kwargs: Mapping[str, Any]) → viam.operations.Operation

Get the Operation associated with the currently running function.

When writing custom resources, you should get the Operation by calling this function and check to see if it’s cancelled. If the Operation is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc. ).

Parameters:

kwargs (Mapping[str, Any]) – The kwargs object containing the operation

Returns:

The operation associated with this function

Return type:

viam.operations.Operation

async close()

Safely shut down the resource and prevent further use.

Close must be idempotent. Later configuration may allow a resource to be “open” again. If a resource does not want or need a close function, it is assumed that the resource does not need to return errors when future non-Close methods are called.

await component.close()