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

Task JSON reference

Use this page to look up task fields, defaults, and units. The orchestrator accepts this JSON and translates it into ROS action messages, resolving pose names, gripper groups, and the model revision along the way.

Defaults come from the parser, goal builders, and stages that use each field. Device and planning checks occur after parsing. The examples use illustrative coordinates; replace them with calibrated values for deployment.

For a complete introduction, start with Write task scripts. The concepts guide explains the frames, units, and planning terms used here; Vision-guided tasks introduces detectors and goal computers.

Document envelope

Field	Required/default	Meaning
start_gripper	Required string	Key in the active beamline’s grippers mapping; declares the already attached tool
tasks	Required, nonempty list	Ordered task objects, each with task_type
poses	Optional object, {}	Names mapped to six joint angles in degrees

Requesting preview

The ROS goal carries this JSON as full_json. Set the goal’s separate Boolean dry_run field to request preview. Adding dry_run inside the JSON does not set that field.

Preview accepts only moveto and end_effector after macro expansion.

With batching disabled, preview plans each row from live CurrentState without propagating prior preview endpoints. It does not validate a continuous multi-row path; see preview start states.

Resolving pose names

Inline poses override registry entries with the same name. For missing names, the parser checks the registry for these fields:

• target

• scan_positions and scan_pose

• approach_pose and target_pose

• place_pose and pickup_pose

This lookup does not automatically load an explicit retreat_pose or a name supplied only by a preset default. Include those poses in poses when required.

Task inventory

Type	Purpose	Preview
moveto	Named, relative, or Cartesian arm movement	Yes
end_effector	Move a gripper group to an SRDF state	Yes
tool_exchange	Dock or load a tool	No
vision_task	Explicit detector and goal-computer pipeline	No
vision_moveto	Marker/approach preset	No
vision_scan	Capture and average markers across scan poses	No
pick_sample	Vision pick preset or hardcoded joint-pose pick	No
place_sample	Vision place preset or hardcoded joint-pose place	No
pick_spincoater	Sample-angle detection and corrected joint target	No
place_spincoater	Pocket-angle detection and corrected joint target	No
pipettor	Forward an operation to the pipette driver	No
pause	Wait for Resume or cancellation	No
pickup_tip	Macro expanded from vision_targets.tip_rack	No
pickup_vial	Macro expanded from vision_targets.vial_rack	No

The first twelve are task types; the last two are parser macros. Result step counts refer to the expanded list.

moveto

Open the full-size diagram

Choose exactly one target mode: nonempty target, direction plus distance, or cartesian_target.

Field	Default	Meaning
target	""	Pose key; if absent from resolved poses, tried as an SRDF state
direction	""	Relative direction from the table below
distance	0.0	Metres; finite and strictly positive when relative mode is selected
cartesian_target	[]	Exactly 3 or 6 finite values: XYZ metres, then optional roll/pitch/yaw degrees
frame_id	"base_link"	Frame for the Cartesian target; an empty value also falls back to base_link in the stage
planning_type	""	"", auto, and joint select automatic fallback planning; cartesian selects CartesianPath; pilz selects LIN; pilz_ptp selects PTP
constraints	Absent	Joint/orientation path constraints described below

An XYZ-only target uses roll 180°, pitch 0°, and the current detected IK frame’s yaw in base_link, falling back to yaw 0° if TF lookup fails. Use six values when the intended orientation must be explicit.

Relative directions use the stage IK frame, which defaults to flange on the current orchestrator MoveTo routes. Cartesian targets separately auto-detect the configured tool-tip frame. The literal direction aliases are the repository’s convention; in particular y is not positive local Y:

Names	Local direction vector
forward, x	[1, 0, 0]
backward, -x	[-1, 0, 0]
right, y	[0, -1, 0]
left, -y	[0, 1, 0]
up, z	[0, 0, 1]
down, -z	[0, 0, -1]

{
  "start_gripper": "none",
  "tasks": [
    {
      "task_type": "moveto",
      "cartesian_target": [0.3, -0.2, 0.25, 180, 0, 0],
      "frame_id": "base_link"
    }
  ]
}

These coordinates illustrate the field format and have not been checked for reachability. Automatic planning depends on the target form; see execution architecture.

end_effector

Field	Default	Meaning
end_effector_type	Current gripper	Selects the configured gripper group; does not exchange tools. If supplied, it must be a string matching a configured gripper key. Unknown names are rejected during parsing.
end_effector_action	""	Literal SRDF state, such as hande_open or vacuum_on

An action is required when the selected group is nonempty. An empty group returns no-op success, including the usual none/pipettor entries. Standalone end_effector does not translate grasp/release aliases; that translation is performed by the vision goal-computer path.

tool_exchange

Field	Default	Meaning
operation	""	Required valid value: dock or load
gripper	""	Configured tool to load; for dock, must match the attached tool
dock_number	0	Integer identifying the physical dock; choose the deployment’s calibrated value
approach_pose	""	Required usable joint-pose key for the approach

Loading requires no tool attached. Dock spacing, reference dock, and motion sequence come from beamline configuration. There is no universal safe default dock number or generic geometry. On a changed attachment, successful physical exchange is followed by a MoveIt relaunch and a TF reset in the vision-task server.

vision_task and vision presets

The canonical task defaults to detector: "marker" and goal_computer: "approach_pose". These fields also apply to the vision preset names below, subject to their preset overrides.

Detection fields

Field	Default	Meaning
detector	marker	marker, sample_roi, spincoater_pocket, or spincoater_sample
detection_type	Absent	Legacy selector used only when the task does not explicitly provide detector
goal_computer	approach_pose	approach_pose for pose detections; j6_snap for angle detections
tag_id	0	ArUco marker or sample-ROI anchor ID
sample_index	1	Forwarded reserved field; not used by the current unified detector
timeout	10.0	Seconds per detection attempt. Detection makes up to 4 attempts (0.5 s apart), repeated at each scan position. The whole vision action must still finish within the orchestrator’s vision_task limit (60 s by default, ROS parameter timeout.vision_task); exceeding it faults the orchestrator
strategy	Empty → farthest_edge	Sample ROI: center, farthest_edge, nearest_edge, farthest_corner, nearest_corner
edge_inset_mm	0.0	Finite nonnegative sample-ROI inset in millimetres
scan_positions	[]	Named six-joint poses for marker multi-position detection; flattened internally in radians. At least 2 positions must detect the marker for the averaged pose
settle_time	1.0	Orchestrator delay before dispatch, capped at 10 s; nonpositive values skip this delay

The vision stage also waits 0.3 s before detection by default. Spincoater capture has a separate 15 s timeout for 2D capture.

Unknown detector or goal-computer names produce a pipeline error. The lookup happens after the optional pre-scan move, so an invalid name can still result in motion before the error is reported.

Approach and execution fields

Field	Default	Meaning
z_offset	Current gripper’s offset	Base-frame Z displacement, metres; zero is interpreted by geometry code as use-gripper-default
marker_offset_x/y/z	0.0 each	Marker-frame offsets, metres
offset_direction	""	Direction for an additional flange-frame offset
offset_distance	0.0	Metres; finite and positive when a direction is set
scan_pose	""	Optional named pre-detection joint move
pre_open	false	Open the configured gripper before that scan move; no effect when scan_pose is empty or the gripper has no release state
terminal_action	""	grasp/release mapping key or literal SRDF state after approach
retreat_pose	""	Named joint-pose retreat appended to the Cartesian-target task when applicable; include its pose data explicitly
retreat_from_scan	false	If true, use scan_pose as retreat and ignore explicit retreat_pose
gripper	Current gripper	Selects gripper group/state mapping; IK frame and default Z offset still come from the current gripper
detect_only	false	approach_pose returns its computed pose instead of executing the target; earlier scans/pre-opening remain possible
constraints	Absent	Applied to named pre-scan motion, Cartesian approach/retreat, corrected joint motion, and optional forward contact; not applied to scan_positions movements

j6_snap ignores detect_only: it still executes the corrected joint target and any configured contact/gripper actions. For approach_pose, detection-only skips the computed target but can still perform earlier scan and pre-open actions.

Joint-6 fields

Field	Default	Meaning
target_pose	Empty	Base joint-pose key for correction
place_pose, pickup_pose	Empty	Legacy alternatives, tried after target_pose in that order
default_target_pose	Empty	Last fallback name; spincoater presets set spincoater_place
k_offset	0.0	Calibration angle added before modulo-90 correction, degrees
forward_distance	0.0	Optional forward contact movement, metres; only positive values add the move

Preset differences

Task	Defaults layered over the canonical fields
vision_moveto	marker → approach_pose; no terminal action
pick_sample with vision	marker → approach_pose; terminal grasp, pre_open: true, retreat_from_scan: true
place_sample with vision	marker → approach_pose; terminal release, retreat_from_scan: true
pick_spincoater	spincoater_sample → j6_snap; scan_pose: spincoater_scan, default target spincoater_place, terminal vacuum_on, forward 0.003 m
place_spincoater	spincoater_pocket → j6_snap; same scan/target defaults, terminal vacuum_off, forward 0.003 m

Explicit task fields override these defaults. Put preset-only scan/target pose names in inline poses or explicitly reference them through fields the parser resolves. Do not assume a spincoater pose in the registry is loaded merely because the preset names it internally.

pick_sample and place_sample without vision

Set use_vision: false to route to the retained sample action server. use_vision defaults to true for these tasks.

The non-vision route uses approach_pose and target_pose (both default empty), optional gripper (current gripper), and constraints. It constructs a joint-pose sequence with the configured gripper states. Vision-specific fields are not forwarded through this route.

Bringup starts the sample server only when enable_vision is true, so turning vision off at launch also removes the non-vision sample-action route.

vision_scan

Field	Default	Meaning
scan_positions	Empty; must resolve at least one pose	Named joint positions to visit
scans_per_position	3	Captures at each position; nonpositive wire values also fall back to 3
timeout	10.0	Capture timeout in seconds; nonpositive wire values fall back to 10

Missing pose names are skipped with a warning; no usable poses is an error. The scan server succeeds when at least one tag is detected. Its tag cache stays in the scan-server process and is not shared with the unified vision server.

pipettor

Field	Default	Meaning
operation	""	Device operation: SUCK, EXPEL, EJECT_TIP, or SET_LED
volume_pct	0.0	Fraction of device range, conventionally 0–1; forwarded by EROBS but ignored by the imported pipette driver
led_color	Absent	Object with r, g, b floats, each defaulting to 0 when supplied; alpha is set to 1

The wrapper forwards these values to the external pipette action without enforcing the full operation or range contract.

The imported pipette driver uses fixed SUCK/EXPEL sequences and ignores volume_pct. This field does not specify microlitres or control volume in that driver version. A pipettor task can actuate the attached device even though it performs no arm planning.

pause

No additional fields are consumed. The task waits for Resume or cancellation and has no timer. See execution controls for service behavior and batch boundaries.

pickup_tip and pickup_vial macros

Both require a configured grid target (tip_rack or vial_rack) with mode: grid, a non-negative integer marker_id, positive grid.rows and grid.cols, and a non-empty moves list. Offsets are optional.

Field	Default	Meaning
element_index	0	Zero-based row-major element index
row, col	Absent	Zero-based coordinates; supply both; take precedence over element_index
config	{}	Override selected vision-target settings; its grid mapping merges with configured grid fields
pipettor_operation	Absent	pickup_vial only: SUCK, EXPEL, or RINSE
volume_pct	0.5	Fraction for inserted vial operations; parser checks finite numeric input
rinse_count	2	Positive integer for RINSE

Expansion emits an optional move to the configured scan pose, a vision_moveto for the marker, and configured relative moves. Grid column_offset/row_offset placeholders become Cartesian relative steps; offsets no larger than 1 μm are omitted. Addresses must lie inside the configured grid.

RINSE expands to SUCK, EXPEL repeated rinse_count times, followed by one final SUCK. Inserted pipettor operations occur before the final retreat move. The configuration must end with a move object for that insertion to be accepted.

Parser macros and the MCP pickup_tip/vision_target tools use the same grid-expansion helper. They remain separate interfaces: macros are submitted inside a task document; MCP tools return generated JSON for a later submission.

Path constraints

constraints can contain lists named joint_constraints and orientation_constraints. Angles use degrees and are converted internally.

Constraint list	Required fields	Defaults
joint_constraints	joint_name, position	tolerance_above: 1°; tolerance_below: 1°; weight: 1
orientation_constraints	link_name, three-element RPY orientation	frame_id: base_link; XYZ tolerance: [5, 5, 5] degrees; weight: 1; parameterization: rotation_vector

Orientation constraints also accept parameterization: euler_xyz.

Constraints apply only where the consuming stage attaches them. They do not change a relative move’s coordinate frame, provide automatic obstacle sensing, or constrain the multi-position scan moves supplied through scan_positions.