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

Tool exchange coordination

Coordinate tool-exchange actions, real-hardware quick-changer voltage release, model relaunch and vision TF invalidation.

beambot.core.tool_exchange_manager · Source

Tools and end effectors · Guide · Symbol index

How it is used

The orchestrator calls exchange() for a task’s dock/load request. Before docking, it rejects a request whose tool does not match the declared current attachment. The manager then coordinates voltage release, the tool-exchange action, active-tool updates, MoveIt relaunch, and a vision-task TF reset in that order where applicable.

ToolExchangeStages supplies the physical motion sequence. Keep callers at the manager boundary when they need the complete tool transition rather than only dock/load motion. Only the vision-task server is reset: its tool-tip lookup depends on the mounted tool; the scan server’s camera chain does not.

Start here

Callable	Purpose
ToolExchangeManager.exchange	Validate dock/load and reject a dock-tool mismatch before changing voltage or sending motion. Release voltage for a real dock, execute the exchange, then update the active tool and relaunch MoveIt if it changed. Reset vision-task TF only after a successful relaunch.

ToolExchangeManager

Coordinator that connects tool-exchange motion with robot and vision state. It uses the caller’s action-wait and gripper-change callbacks and an existing MoveItLifecycleManager.

ToolExchangeManager.exchange()

Validate dock/load and reject a dock-tool mismatch before changing voltage or sending motion. Release voltage for a real dock, execute the exchange, then update the active tool and relaunch MoveIt if it changed. Reset vision-task TF only after a successful relaunch.

Method · Source

exchange(
    self,
    step: dict[str, Any],
    poses_json: str,
    current_gripper: str,
    timeout: float,
) -> bool

Parameter	Meaning
step	Task fields including operation, gripper, dock_number and approach_pose.
poses_json	Serialized named joint poses forwarded to the action.
current_gripper	Currently attached gripper name.
timeout	Child action timeout in seconds.

Returns: True on completed exchange/synchronization; False on validation, voltage, action or relaunch failure.

Errors: Sets last_error for an invalid operation, unknown load tool, dock-tool mismatch, voltage failure, or relaunch failure; delegated child-action failure may leave it empty. Dock matching compares the requested tool to current_gripper, not a physical sensor. Integer conversion and callback exceptions propagate. TF reset failures are warnings and do not turn an otherwise successful exchange into failure.

Side effects: May set tool voltage to 0 V, wait 0.5 s, move the robot, update attached-tool state, restart MoveIt and reset the vision-task TF buffer. State update is not rolled back if relaunch fails.

ToolExchangeManager.__init__()

Store coordination callbacks and create the tool-exchange action client and vision-task TF-reset service client.

Lifecycle · Source

__init__(
    self,
    node: Node,
    grippers: Mapping[str, Any],
    moveit_manager,
    callback_group,
    *,
    use_mock_hardware: bool,
    send_and_wait: Callable[..., bool],
    on_gripper_changed: Callable[[str], None],
)

Parameter	Meaning
node	ROS node owning clients and logger.
grippers	Mapping of valid gripper configurations.
moveit_manager	MoveItLifecycleManager providing voltage notification and gripper relaunch.
callback_group	Callback group for action/service responses.
use_mock_hardware	Skip real tool-voltage release when true.
send_and_wait	Callback that sends a child action and returns success.
on_gripper_changed	Callback that updates the orchestrator’s active gripper before relaunch.

Errors: ROS client-construction errors propagate.

Side effects: Creates one action client and one Trigger client; initializes last_error.

Referenced in source (1)

• MTCOrchestratorServer.__init__ — beambot.action_servers.orchestrator

Internal callbacks and helpers

ToolExchangeManager._set_tool_voltage_via_io()

Call the UR set_io service using FUN_SET_TOOL_VOLTAGE without stopping the external-control program.

Internal helper · Source

_set_tool_voltage_via_io(self, voltage: int) -> bool

Parameter	Meaning
voltage	Tool supply voltage in volts, converted to float for the service request.

Returns: True only for a successful service response; False for service absence, timeout, negative response, or a caught call error.

Errors: Client creation, request conversion, and service exceptions are logged and return False. Import errors occur before the try block; client-destruction errors in finally can propagate.

Side effects: Creates a temporary service client and destroys it in finally. Waits up to 3 s for discovery, then makes a blocking 5 s service call requiring another executor thread. Requests a physical voltage change; timeout does not establish the resulting voltage.

Referenced in source (1)

• ToolExchangeManager.exchange — beambot.core.tool_exchange_manager

ToolExchangeManager._reset_vision_tf()

Request a TF-buffer reset from the vision-task server after the robot description changes.

Internal helper · Source

_reset_vision_tf(self)

Returns: None.

Errors: Unavailable service, failed/timed-out response, and service exceptions are logged as warnings. The method returns no success flag and does not fail the completed exchange.

Side effects: Waits up to 3 s for beambot_vision_task_reset_tf, then makes a blocking Trigger call with a 5 s timeout. Another executor thread must deliver the response. Successful service handling clears that server’s TF state.

Referenced in source (1)

• ToolExchangeManager.exchange — beambot.core.tool_exchange_manager