Task execution

The orchestrator runs a task script from validation through planning, execution, and the final result. Clients submit the JSON in MTCExecution.full_json to /beambot_execution; the separate dry_run field selects a plan-only preview.

Open the full-size diagram

Accept and validate

The orchestrator accepts one goal at a time. It rejects new goals while another sequence is active or the orchestrator is faulted.

parse_task_script() prepares the script before MoveIt startup:

Check the JSON structure, configured start_gripper, and nonempty task list.
Validate task types, then expand pickup macros into task steps.
Check MoveTo target modes, explicitly selected end-effector names, flange offsets, and preview compatibility.
Look up missing pose names in the configured registry. Inline poses take precedence.

An invalid task type rejects the whole script before execution. Successful parsing does not guarantee that every pose exists or that a movement is feasible; task servers and planners check those later. See task scripts for the input format.

Prepare MoveIt

The orchestrator asks the lifecycle manager for a MoveIt stack matching start_gripper. The manager reuses a healthy matching stack or launches and verifies a replacement. If initialization fails, execution stops before the first step.

start_gripper selects the initial tool model; it does not perform a physical tool exchange. Model changes during the sequence follow the tool and MoveIt lifecycle.

Run the sequence

group_into_batches() divides the expanded task list into execution units. With batching enabled, consecutive moveto and end_effector steps share one MTC task. Every other task forms its own unit. With batching disabled, each step is a separate unit.

Before each unit, the orchestrator checks cancellation, pending pause, and whether its MoveIt subprocess is still running. A pause task waits for Resume or cancellation. Pause and cancellation do not interrupt an active unit; see execution controls. A unit that fails while cancellation is pending faults the orchestrator.

Task	Execution route
Batched MoveTo and end-effector steps	Stage builders run inside the orchestrator and form one MTC task
Unbatched MoveTo or end-effector step	Its ROS action server builds and executes the task
Tool exchange	The exchange manager coordinates dock/load actions and model changes
Vision task or vision preset	The unified vision-task server detects a feature, computes a target, and handles the requested operation
Pick/place with `use_vision: false`	The sample pick/place server runs the configured non-vision sequence
Vision scan	The scan server measures markers and updates its own cache
Pipettor	The pipettor server forwards the operation to the external driver

The module guide links these routes to their implementations. Automatic vacuum-loss checks are currently disabled.

Plan a movement

BaseStages creates the MTC task and loads its robot model. MoveToStages.add_to_task() builds stages for a named pose, Cartesian target, or relative move.

Automatic planner selection depends on the target. Pilz provides point-to-point motion (PTP) and straight-line Cartesian motion (LIN):

MoveTo target	Automatic fallback order
Named joint pose or SRDF state	PTP → configured planning pipeline
Cartesian target	PTP if deterministic inverse kinematics succeeds → LIN → CartesianPath
Relative move	LIN → CartesianPath → PTP

For Cartesian targets, IK starts from a rounded copy of the current joints, so repeated requests usually pick the same joint solution. PTP moves in joint space, so the tool does not follow a straight line. Set planning_type to pilz when a straight path matters.

An omitted planning_type, "auto", and "joint" all select this automatic behavior. The configured pipeline uses STOMP when its parameters are available, otherwise OMPL/RRTstar. Tool exchange and vision build their own motion sequences.

A successful plan becomes a serialized solution, which the shared execution code submits to MoveIt’s execute_task_solution action. Eligible single-batch goals can reuse a stored solution when expanded tasks, resolved poses, model identity, and starting joints match; see batching and caches.

Preview instead of execute

With dry_run: true, only moveto and end_effector steps are accepted. The orchestrator still prepares MoveIt and plans the request, then publishes a DisplayTrajectory on /beambot/preview_trajectory instead of executing it.

Preview stays inside the orchestrator even when batching is disabled. In that case, each step is planned from the live robot state, rather than the previous step’s planned endpoint. It therefore does not verify the transitions between those steps. See preview start states.

Return the result

The result reports success, error_message, completed_steps, and total_steps. Counts refer to the expanded task list. A failed batch adds no completed steps, even if part of its motion occurred. A cancellation request received during the final unit is checked before reporting success.

An ordinary task failure aborts the remaining sequence. Child-action waits distinguish server availability, goal acceptance, and completion; timeouts fault the orchestrator and block new goals. Each planned unit must be accepted by the MoveIt executor within 10 s and finish within 120 s. Exceeding either aborts the unit and faults the orchestrator; the error begins with REPLAY_TIMEOUT even for a fresh plan. Use execution controls to interpret the state and recover.

Cached replay has one exception to ordinary failure handling: an error other than REPLAY_TIMEOUT triggers fresh planning and execution of the entire eligible batch. Earlier effects may repeat. A replay timeout aborts without another dispatch; see replay failure handling.