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

Tool dock and load stages

Compose load/dock motion from beamline YAML, including reference-dock offset and full-fraction Cartesian insertion/retraction. Voltage and runtime relaunch are handled separately by ToolExchangeManager.

beambot.stages.tool_exchange_stages · Source

Tools and end effectors · Guide · Symbol index

How it is used

ToolExchangeActionServer calls run() to build the beamline’s configured dock/load sequence. It first moves to the configured reference-dock approach pose, applies dock spacing, then executes Cartesian insertion and retraction moves.

A load requires the declared current attachment to be none. Dock-tool matching is checked by ToolExchangeManager before voltage release; calling the action server directly bypasses that check. These stages handle arm motion only. The surrounding ToolExchangeManager coordinates voltage release, attached-tool state, MoveIt relaunch, and vision resets.

Start here

Callable

Purpose

ToolExchangeStages.run

Reject loading while a tool is declared attached, approach the reference dock, and execute the configured load/dock sequence with complete Cartesian paths. Dock-tool matching is checked by the manager, not this method.

ToolExchangeStages

BaseStages subclass for configured magnetic-dock motion. It reads the tool-exchange block, rejects a load while a tool is declared attached, and requires complete Cartesian insertion/retraction paths. Dock-tool matching belongs to the manager.

Inherits from: BaseStages.

ToolExchangeStages.run()

Reject loading while a tool is declared attached, approach the reference dock, and execute the configured load/dock sequence with complete Cartesian paths. Dock-tool matching is checked by the manager, not this method.

Entry point · Source

run(self, goal) -> str | None

Parameter

Meaning

goal

ToolExchange goal with operation, attached/requested gripper, dock_number, approach_pose and poses_json.

Returns: None on success; descriptive configuration, load-attachment, pose, sequence or planning/execution error string.

Errors: Catches only ValueError from configuration loading; later numeric/direction/MTC errors can propagate. Unknown operations return an error after task setup. Direct dock goals do not validate the requested tool against current_attached_gripper.

Side effects: Plans/executes physical tool-exchange motion; sets the task-local Cartesian min_fraction to 1.0. Does not switch voltage or relaunch MoveIt.

Functions

Internal callbacks and helpers

_load_tool_exchange_config()

Read the tool_exchange block and require nonempty dock_spacing_m, reference_dock, load_sequence and dock_sequence entries.

Internal helper · Source

_load_tool_exchange_config() -> dict

Returns: Shared tool-exchange configuration mapping.

Errors: Raises ValueError listing missing keys. Beamline load errors propagate; sequence shapes and numeric values are not validated here.

Side effects: May initialize the shared configuration cache.

Referenced in source (1)