Kinematics

Kinematics wraps MoveIt for robot model inspection, live state, trajectory planning/execution, and end-effector control.

Kinematics wrapper over olo.kinematics.v1.Kinematics.

Client interfaces

class olo.kinematics.Kinematics[source]

Bases: object

Sync wrapper for the kinematics gRPC service.

__init__(session)[source]

Bind to a channel session.

command_end_effector(position, *, robot_namespace='', planning_group=None, max_effort=None, accept_stall=False, timeout=5.0)[source]

Command the gripper end-effector to a position.

Return type:

GripperResult

Parameters:

  • position (float)

  • robot_namespace (str)

  • planning_group (str | None)

  • max_effort (float | None)

  • accept_stall (bool)

  • timeout (float)

execute_trajectory(trajectory, *, robot_namespace='', execution_timeout=10.0, timeout=None)[source]
Overloads:

  • self, trajectory (Trajectory), robot_namespace (str), execution_timeout (float), timeout (Optional[float]) → None

  • self, trajectory (PlanResult), robot_namespace (str), execution_timeout (float), timeout (Optional[float]) → None

Parameters:
Return type:

None

Execute a pre-planned trajectory (accepts a PlanResult directly).

By default the RPC deadline is derived from the trajectory’s own duration (plus slack) so long trajectories are never cancelled mid-motion; an explicit timeout overrides it.

get_joints(robot_namespace='', *, timeout=5.0)[source]

Fetch current joint states for a robot.

Return type:

JointStates

Parameters:
get_model(robot_namespace='', *, timeout=10.0)[source]

Fetch kinematics model metadata for a robot.

Return type:

RobotModel

Parameters:
get_pose(robot_namespace='', *, planning_group=None, ee_link=None, timeout=10.0)[source]

Fetch the end-effector pose for a robot.

The pose is expressed in the group’s planning frame (see PlanningGroup.planning_frame on the robot model).

Return type:

Pose

Parameters:

  • robot_namespace (str)

  • planning_group (str | None)

  • ee_link (str | None)

  • timeout (float)

get_state(robot_namespace='', *, timeout=5.0)[source]

Fetch the executor-owned kinematics snapshot for a robot.

Activity reflects motion started by any client, not just this one.

Return type:

KinematicsState

Parameters:
handle(namespace=None)[source]

Return a namespace-scoped kinematics handle.

Return type:

KinematicsHandle

Parameters:

namespace (str | None)

move_joints(joint_positions, *, robot_namespace='', planning_group=None, planning_timeout=5.0, execution_timeout=10.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan and execute a move to target joint positions.

Return type:

PlanResult

Parameters:
move_linear(target_pose, *, robot_namespace='', planning_group=None, ee_link=None, planning_timeout=5.0, execution_timeout=10.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan and execute a linear move to a target pose.

Return type:

PlanResult

Parameters:

  • target_pose (Pose)

  • robot_namespace (str)

  • planning_group (str | None)

  • ee_link (str | None)

  • planning_timeout (float)

  • execution_timeout (float)

  • start_state (JointStates | None)

  • gripper_position (float | None)

  • speed_scaling (float)

  • timeout (float | None)

move_linear_sequence(poses, *, robot_namespace='', planning_group=None, ee_link=None, blend_radius=0.0, planning_timeout=5.0, execution_timeout=10.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Plan and execute a linear sequence through poses.

Return type:

PlanResult

Parameters:
move_pose(target_pose, *, robot_namespace='', planning_group=None, ee_link=None, avoid_obstacles=False, planning_timeout=5.0, execution_timeout=10.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan and execute a move to a target pose (in the planning frame).

Return type:

PlanResult

Parameters:

  • target_pose (Pose)

  • robot_namespace (str)

  • planning_group (str | None)

  • ee_link (str | None)

  • avoid_obstacles (bool)

  • planning_timeout (float)

  • execution_timeout (float)

  • start_state (JointStates | None)

  • gripper_position (float | None)

  • speed_scaling (float)

  • timeout (float | None)

move_pose_sequence(poses, *, robot_namespace='', planning_group=None, ee_link=None, blend_radius=0.0, planning_timeout=5.0, execution_timeout=10.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Plan and execute a point-to-point sequence through poses.

Return type:

PlanResult

Parameters:
plan_joints(joint_positions, *, robot_namespace='', planning_group=None, planning_timeout=5.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan a trajectory to target joint positions.

Return type:

PlanResult

Parameters:
plan_linear(target_pose, *, robot_namespace='', planning_group=None, ee_link=None, planning_timeout=5.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan a linear trajectory to a target pose.

target_pose must be expressed in the group’s planning frame.

Return type:

PlanResult

Parameters:

  • target_pose (Pose)

  • robot_namespace (str)

  • planning_group (str | None)

  • ee_link (str | None)

  • planning_timeout (float)

  • start_state (JointStates | None)

  • gripper_position (float | None)

  • speed_scaling (float)

  • timeout (float | None)

plan_linear_sequence(poses, *, robot_namespace='', planning_group=None, ee_link=None, blend_radius=0.0, planning_timeout=5.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Plan a linear sequence through poses.

Requires at least two poses. blend_radius is applied to every non-final item; the final item always uses radius 0.

Return type:

PlanResult

Parameters:
plan_pose(target_pose, *, robot_namespace='', planning_group=None, ee_link=None, avoid_obstacles=False, planning_timeout=5.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan a trajectory to a target pose.

target_pose must be expressed in the group’s planning frame (see PlanningGroup.planning_frame on the robot model).

Return type:

PlanResult

Parameters:

  • target_pose (Pose)

  • robot_namespace (str)

  • planning_group (str | None)

  • ee_link (str | None)

  • avoid_obstacles (bool)

  • planning_timeout (float)

  • start_state (JointStates | None)

  • gripper_position (float | None)

  • speed_scaling (float)

  • timeout (float | None)

plan_pose_sequence(poses, *, robot_namespace='', planning_group=None, ee_link=None, blend_radius=0.0, planning_timeout=5.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Plan a point-to-point sequence through poses.

Requires at least two poses. blend_radius is applied to every non-final item; the final item always uses radius 0.

Return type:

PlanResult

Parameters:
class olo.kinematics.KinematicsHandle[source]

Bases: object

Namespace-scoped robot handle for common kinematics operations.

Optionally bound to a planning group. Unbound handles resolve the sole manipulator group lazily; multi-arm robots must call group() first. Model-dependent properties fetch and cache the model on first access and may raise typed availability errors. Failed fetches are not cached.

__init__(client, namespace, *, group=None, model=None, _holder=None)[source]

Bind to a client and normalized namespace.

The kinematics model is fetched on first model-dependent use and cached for the handle’s lifetime — including across group() rebinding. Failed fetches are not cached, so a later call retries. Use Kinematics.get_model() for a fresh fetch outside this cache. Accessing model, ee, planning_frame, or end_effector_link may perform an RPC and raise typed errors such as OloFailedPrecondition.

Parameters:
property ee: Gripper | None

Return the gripper, fetching the model on first access.

Return the end-effector link, fetching the model on first access.

execute_trajectory(trajectory, *, execution_timeout=10.0, timeout=None)[source]
Overloads:

  • self, trajectory (Trajectory), execution_timeout (float), timeout (Optional[float]) → None

  • self, trajectory (PlanResult), execution_timeout (float), timeout (Optional[float]) → None

Parameters:
Return type:

None

Execute a trajectory for this robot.

get_state(*, timeout=5.0)[source]

Fetch the executor-owned kinematics snapshot for this robot.

Return type:

KinematicsState

Parameters:

timeout (float)

group(name)[source]

Return a handle bound to name, sharing this handle’s model cache.

Return type:

KinematicsHandle

Parameters:

name (str)

joints(*, timeout=5.0)[source]

Fetch current joint states for this robot.

Return type:

JointStates

Parameters:

timeout (float)

property model: RobotModel

Return the cached kinematics model for this robot.

Fetches the model on first access. Failed fetches are not cached.

move_joints(joint_positions, *, planning_timeout=5.0, execution_timeout=10.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Move to target joint positions for this robot.

Return type:

PlanResult

Parameters:
move_linear(target_pose, *, ee_link=None, planning_timeout=5.0, execution_timeout=10.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Move linearly to a target pose for this robot.

Return type:

PlanResult

Parameters:
move_linear_sequence(poses, *, ee_link=None, blend_radius=0.0, planning_timeout=5.0, execution_timeout=10.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Move through a linear sequence for this robot.

Return type:

PlanResult

Parameters:
move_pose(target_pose, *, ee_link=None, avoid_obstacles=False, planning_timeout=5.0, execution_timeout=10.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Move to a target pose for this robot.

Return type:

PlanResult

Parameters:
move_pose_sequence(poses, *, ee_link=None, blend_radius=0.0, planning_timeout=5.0, execution_timeout=10.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Move through a point-to-point sequence for this robot.

Return type:

PlanResult

Parameters:
plan_joints(joint_positions, *, planning_timeout=5.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan to target joint positions for this robot.

Return type:

PlanResult

Parameters:
plan_linear(target_pose, *, ee_link=None, planning_timeout=5.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan a linear move for this robot.

Return type:

PlanResult

Parameters:
plan_linear_sequence(poses, *, ee_link=None, blend_radius=0.0, planning_timeout=5.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Plan a linear sequence for this robot.

Return type:

PlanResult

Parameters:
plan_pose(target_pose, *, ee_link=None, avoid_obstacles=False, planning_timeout=5.0, start_state=None, gripper_position=None, speed_scaling=0.5, timeout=None)[source]

Plan to a target pose for this robot.

Return type:

PlanResult

Parameters:
plan_pose_sequence(poses, *, ee_link=None, blend_radius=0.0, planning_timeout=5.0, start_state=None, speed_scaling=0.5, timeout=None)[source]

Plan a point-to-point sequence for this robot.

Return type:

PlanResult

Parameters:
property planning_frame: str

Return the planning frame, fetching the model on first access.

pose(*, ee_link=None, timeout=10.0)[source]

Fetch the end-effector pose for this robot.

Return type:

Pose

Parameters:
class olo.kinematics.Gripper[source]

Bases: EndEffectorHandle

Gripper end-effector handle.

__init__(client, namespace, info, gripper_info)[source]
Parameters:
Return type:

None

close(*, max_effort=None, timeout=5.0)[source]

Close the gripper to its declared closed target.

Uses the closed position from the robot description and treats a stall as success, since closing onto an object is the expected grasp outcome.

Return type:

GripperResult

Parameters:
goal(position, *, max_effort=None, timeout=5.0)[source]

Command the gripper to a raw controller-coordinate target.

position is passed straight through to the active controller, so its meaning depends on the underlying hardware: it may be a physical aperture distance or an actuator joint value. Use open() and close() for portable, direction-independent intent. Treats a stall as success.

Return type:

GripperResult

Parameters:
open(*, max_effort=None, timeout=5.0)[source]

Open the gripper to its declared open target.

Uses the open position from the robot description rather than a joint limit, so it opens correctly regardless of controller direction. Strict: a stall is treated as a failure.

Return type:

GripperResult

Parameters:

Types

class olo.kinematics.RobotModel[source]

Bases: object

Kinematics model metadata for a robot.

__init__(robot_namespace='', default_group='', groups=(), joints=(), end_effectors=())
Parameters:
Return type:

None

end_effector_for(group)[source]

Return the end effector attached to a planning group, if any.

Return type:

EndEffector | None

Parameters:

group (str)

group(name=None)[source]

Resolve a planning group by name or the model default.

Return type:

PlanningGroup

Parameters:

name (str | None)

class olo.kinematics.PlanningGroup[source]

Bases: object

MoveIt planning group metadata.

__init__(name, joints=(), end_effector_link='', planning_frame='', group_states=())
Parameters:
Return type:

None

group_state(name)[source]

Resolve a named SRDF group state for this planning group.

Return type:

GroupState

Parameters:

name (str)

class olo.kinematics.GroupState[source]

Bases: object

Named joint target declared by an SRDF planning group.

__init__(name, joints)
Parameters:
Return type:

None

class olo.kinematics.JointInfo[source]

Bases: object

Joint limits and type from the robot model.

__init__(name, type=JointType.UNSPECIFIED, lower_limit=0.0, upper_limit=0.0, max_velocity=0.0, max_effort=0.0)
Parameters:
Return type:

None

class olo.kinematics.JointStates[source]

Bases: object

Sampled joint states for a robot.

__init__(names=(), positions=(), velocities=(), efforts=(), sample_time=None)
Parameters:
Return type:

None

property position_by_name: dict[str, float]

Map joint name to position.

class olo.kinematics.JointTarget[source]

Bases: object

Target joint positions (parallel names and positions).

__init__(names, positions)
Parameters:
Return type:

None

class olo.kinematics.Trajectory[source]

Bases: object

Joint-space trajectory.

__init__(joint_names=(), points=(), planning_group='')
Parameters:
Return type:

None

property duration: float

Trajectory duration in seconds (final point’s time_from_start).

class olo.kinematics.TrajectoryPoint[source]

Bases: object

Single trajectory sample; time_from_start is in seconds.

__init__(positions=(), velocities=(), accelerations=(), efforts=(), time_from_start=0.0)
Parameters:
Return type:

None

class olo.kinematics.PlanResult[source]

Bases: object

Outcome of a plan or move call; planning_time is in seconds.

__init__(trajectory, planning_time)
Parameters:
Return type:

None

property duration: float

Duration of the planned trajectory in seconds.

class olo.kinematics.GripperInfo[source]

Bases: object

Gripper metadata from the robot model.

open_position and closed_position are the semantic targets declared by the robot description (SRDF group states). They are not assumed to equal max_position/min_position because some grippers open at the lower joint limit.

__init__(min_position, max_position, max_effort, joints=(), open_position=0.0, closed_position=0.0)
Parameters:
Return type:

None

class olo.kinematics.GripperResult[source]

Bases: object

Outcome of a gripper command.

__init__(reached_goal, stalled, position)
Parameters:
Return type:

None

class olo.kinematics.EndEffector[source]

Bases: object

End-effector metadata from the robot model.

__init__(parent_group, parent_link, planning_group, gripper)
Parameters:
Return type:

None

property type: EndEffectorType

Classify the end-effector kind.

Enums

class olo.kinematics.JointType[source]

Bases: str, Enum

Joint kinematic type, mirroring olo.kinematics.v1.JointType.

__new__(value)
class olo.kinematics.EndEffectorType[source]

Bases: str, Enum

SDK-only end-effector kind derived from proto EndEffectorInfo.kind.

__new__(value)

Import from olo/kinematics:

The TypeScript surface mirrors the Python module: method names are camelCase and keyword arguments become an options object with millisecond timeouts (timeoutMs, planningTimeoutMs, executionTimeoutMs) and shared planning options such as speedScaling (default 0.5, range (0, 1]).

Client interfaces

  • Kinematics — service wrapper for model/state reads, planning, execution, and end-effector commands.

  • KinematicsHandle — namespace-scoped robot handle with a lazily cached model (created via client.kinematics.handle()).

  • Gripper — gripper end-effector handle (await robot.kinematics.getEndEffector()), with goal(), open(), and close().

Types

Enums