Work in progress: this documentation is still being written and reviewed. Check details against the source code.

MoveTo planning stages

Compose and execute named, relative and Cartesian MoveTo goals, using shared validation, target-specific fallback planners and TF-based tool-tip selection.

beambot.stages.move_to_stages · Source

Motion planning · Guide · Symbol index

How it is used

MoveToActionServer uses run() to plan and execute one goal. The orchestrator instead uses add_to_task() to compose multiple moves into a batch. Both paths share target validation, planner selection, and tool-tip resolution.

Read add_to_task() for the differences between named, relative, and Cartesian targets. Temporary instances own TF subscriptions and should be released with close() after batch execution.

Start here

Callable

Purpose

MoveToStages.run

Create a fresh MoveTo task, append the goal’s stages, then plan and execute it.

MoveToStages.add_to_task

Validate a MoveTo goal and append target-specific stages. Automatic relative moves use LIN/Cartesian/PTP; named joints/states use PTP then the configured general pipeline; Cartesian goals prefer seeded IK/PTP then LIN/Cartesian. XYZ-only targets use roll 180°, pitch 0° and live tip yaw.

MoveToStages.close

Unregister this instance’s TF listener subscriptions.

MoveToStages

BaseStages subclass that converts MoveToAction fields into motion stages. It owns a TF listener for tool-frame selection and current orientation, and exposes separate composition and execution paths.

Inherits from: BaseStages.

MoveToStages.run()

Create a fresh MoveTo task, append the goal’s stages, then plan and execute it.

Entry point · Source

run(self, goal) -> str | None

Parameter

Meaning

goal

MoveTo action goal consumed by add_to_task.

Returns: None on completion or an error string from stage construction/planning/execution.

Errors: Unhandled construction/JSON errors propagate to the action-server boundary.

Side effects: Creates/plans a task and commands robot motion.

MoveToStages.add_to_task()

Validate a MoveTo goal and append target-specific stages. Automatic relative moves use LIN/Cartesian/PTP; named joints/states use PTP then the configured general pipeline; Cartesian goals prefer seeded IK/PTP then LIN/Cartesian. XYZ-only targets use roll 180°, pitch 0° and live tip yaw.

Method · Source

add_to_task(self, task: core.Task, goal, planner=None) -> str | None

Parameter

Meaning

task

MTC task receiving stages.

goal

MoveTo action goal: named target with poses_json, direction/distance in metres, or XYZ metres plus optional RPY degrees; planning_type and constraints_json select planning behavior.

planner

Optional explicit planner overriding automatic selection.

Returns: None when stages were appended; validation/pose error string otherwise.

Errors: Invalid motion selection becomes an error string; malformed constraints JSON/data and MTC/TF/helper errors can propagate.

Side effects: Appends stages, resets/sets endpoint pinning, queries TF/IK for Cartesian goals and populates planner caches; does not execute the task.

Referenced in source (1)

MoveToStages.close()

Unregister this instance’s TF listener subscriptions.

Lifecycle · Source

close(self) -> None

Returns: None.

Errors: Listener cleanup errors propagate.

Side effects: Releases TF subscriptions.

MoveToStages.__init__()

Initialize shared planning state and start a TF listener before Cartesian goals arrive.

Lifecycle · Source

__init__(self, rclpy_node, arm_group: str='', ik_frame: str='')

Parameter

Meaning

rclpy_node

Owning ROS node.

arm_group

Planning group; empty uses ur_arm.

ik_frame

Relative-motion IK frame; empty uses flange.

Errors: Base/TF construction errors propagate.

Side effects: Creates a TF buffer/listener and its subscriptions.

Referenced in source (2)

Internal callbacks and helpers

MoveToStages._get_current_yaw()

Look up the latest base_link-to-frame rotation and extract Euler yaw.

Internal helper · Source

_get_current_yaw(self, frame: str='flange') -> float

Parameter

Meaning

frame

Tool/link frame, flange by default.

Returns: Yaw in radians, or 0.0 on any lookup/conversion exception.

Errors: Logs and suppresses exceptions; TF lookup waits up to 2 s.

Side effects: Queries the TF buffer and may log a fallback warning.

Referenced in source (1)

MoveToStages._detect_gripper_ik_frame()

Probe configured tip frames in order for a transform from base_link, returning the first available frame.

Internal helper · Source

_detect_gripper_ik_frame(self) -> str

Returns: Detected tip frame name, or flange when none can be transformed.

Errors: Per-frame TF errors are ignored; configuration helper supplies its own empty fallback.

Side effects: Queries TF with up to 1 s per frame and logs selection.

Referenced in source (1)