Tool and MoveIt lifecycle

The orchestrator starts and manages the MoveIt stack for the selected tool. It reuses that stack between requests and replaces it when the tool configuration changes. The top-level EROBS launch starts task servers and optional devices; MoveIt starts when the orchestrator handles a task.

start_gripper declares the tool already attached. It selects the initial model and does not perform a physical exchange. See tools and end effectors for operator settings.

Start or reuse MoveIt

MoveItLifecycleManager.launch_moveit_with_gripper() reads the selected tool’s beamline configuration. It reuses the existing stack when the launch process is running and its model revision matches the requested gripper and cup profile. Otherwise, it stops the previous stack and launches a replacement. Cup overrides apply only to tools that define a cup profile.

Payload and voltage settings are validated when the beamline configuration loads. Both real and mock startup launch MoveIt, load collision objects, and read its robot descriptions. Real-hardware startup also sets tool voltage, restarts the UR external-control program, checks hardware readiness, and applies the payload.

A failed real-hardware startup is retried once. Mock startup has no automatic retry. This retries initialization, not the preceding tool-exchange movement.

Keep the robot model consistent

A tool change updates both robot descriptions: URDF describes geometry and joints; SRDF supplies planning groups, named states, and collision rules. Mixing descriptions from different launches can produce an inconsistent model.

The lifecycle manager reads the pair used by /move_group, requires both descriptions to be nonempty, and republishes them on dedicated ROS topics. Rebuild and restart the model consumers after changing model files or tool configuration.

The model revision identifies the gripper and its configured cup profile. MTC stages use it to reuse the matching model; MoveIt-using child action goals carry it and batches read it from the lifecycle manager. The same tool/cup combination keeps the same revision across launches. It is not a hash of the model files, so model-file edits require restarting the model consumers. See batching and caches for trajectory reuse.

Dock and load

ToolExchangeManager.exchange() coordinates the movement and the model update. Replacing Hand-E with ePick, for example, uses two operations: dock Hand-E → prepare the none model → load ePick → prepare the ePick model.

Open the full-size diagram

Each operation follows this sequence:

Check the request. Accept dock or load. For a load, confirm that the requested tool is configured; for a dock, require it to match the declared current tool. A mismatch stops the exchange before voltage changes or motion.
Prepare docking power. On real hardware, a dock request sets tool voltage to 0 V through the UR I/O service. If the service does not confirm success, the exchange stops before sending the motion goal.
Validate and execute the movement. The tool action server rejects a load unless the declared attachment is none; dock-tool matching has already been checked by the manager. ToolExchangeStages.run() builds the approach, lateral dock alignment, and configured load/dock moves as one MTC task. Dock spacing, the reference dock, and movement sequences come from the beamline YAML.
Update the tool model. After motion succeeds, the manager records and publishes the new gripper: none after docking or the requested tool after loading. If this differs from the previous tool, it starts the matching MoveIt configuration and reads its robot descriptions.
Reset vision transforms. After the model is ready, the manager requests a TF-buffer reset from the unified vision-task server. A missing service, failed reset, or service exception produces a warning; it does not fail the exchange. The standalone scan server has no reset service.

If the reported tool is unchanged, the manager skips the model restart and TF resets.

Failure boundaries

The physical exchange and model update complete separately. A failed exchange result does not establish which tool is attached.

Failure point	What may already have happened
Dock-tool mismatch at the manager	No voltage change or motion has been requested
Exchange motion	Some movement may have completed; the manager updates the recorded gripper only after action success
New MoveIt startup	Exchange motion has succeeded and the new gripper state has been published, but the model is not ready
Vision TF reset	Motion and model startup have succeeded; the exchange remains successful, but a vision server may retain old transforms

/beambot/current_gripper reports the orchestrator’s state, not a tool-presence measurement. Establish the physical attachment and controller state before retrying a failed exchange. Resubmitting the original script can repeat an operation that already completed.

Shutdown

The orchestrator stops MoveIt when its node shuts down, while ROS is still running. MoveItLifecycleManager.kill_current_process() sends SIGTERM to the launch’s process group, waits up to three seconds for every process in the group to exit, then sends SIGKILL to any that remain.

The same stop runs before a replacement launch during a tool change. It is followed by a wait of up to ten seconds for the old /execute_trajectory action to leave ROS discovery, so the new stack is not mistaken for ready.

After the first Ctrl+C, EROBS task servers ignore further interrupt signals until their cleanup finishes. A second signal therefore cannot stop the orchestrator midway and leave MoveIt running.

Processes that start their own session are outside the MoveIt process group and are not stopped this way. These shutdown changes have not yet been rechecked on the CMS hardware.

Confirm the remaining process and ROS state before restarting after a failed or interrupted shutdown. Keep the orchestrator as the owner of MoveIt startup so tool configuration, model revisions, and cache reuse remain coordinated.