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

Concepts and conventions

EROBS turns task scripts into coordinated robot, tool, and camera operations. This page explains the terms and conventions used by the platform. Linked framework terms open the official documentation for more detail.

The software building blocks

Term

Role in EROBS

Task script

JSON specifying the starting tool and an ordered sequence of operations

Orchestrator

Accepts scripts on /beambot_execution, coordinates their steps, and manages the active MoveIt stack

Batch

Consecutive compatible steps combined into one MTC task for planning and execution

ROS node

A ROS participant, such as the orchestrator or camera driver

Topic, service, action

Topics stream state and images; services handle requests such as capture; actions run tasks with feedback and a result

MoveIt 2

Plans motion using the selected arm/tool model and collision scene

MTC stage

One part of a MoveIt Task Constructor plan, such as a relative move or gripper motion

Controller

Carries out a planned trajectory—a timed sequence of robot states—or a device command

TF

Coordinate transforms connecting the robot base, flange, tool, and camera

Inverse kinematics (IK)

Finds joint angles for a target pose. The IK frame is the frame being positioned, such as the flange or tool tip.

A JSON task type, such as moveto, selects an EROBS operation. The ROS action type MTCExecution carries the complete script to the orchestrator. See the action contracts for its goal, feedback, and result fields.

Some tasks become child action goals: requests the orchestrator sends to another action server. Consecutive compatible tasks may instead be combined into one MTC task inside the orchestrator.

Geometry files describe different things

EROBS uses URDF (Unified Robot Description Format) for arm and tool geometry, Xacro templates to assemble model variants, and SRDF (Semantic Robot Description Format) for planning groups, named states, and collision exclusions. Controller and planning YAML files configure limits, planners, and execution.

The official URDF/SRDF guide and Xacro tutorial explain the formats. See EROBS model packages for the files used here and the tool lifecycle for how geometry, tip frames, payloads, and controllers change with a tool.

Units you must keep distinct

Value

Convention

Named joint-pose arrays in task JSON and pose YAML

Degrees; six values in configured arm-joint order

cartesian_target

XYZ in metres; optional roll/pitch/yaw in degrees

Relative movement distance

Metres

Revolute arm-joint positions on ROS /joint_states

Radians; prismatic gripper-joint positions on the same topic use metres

Flattened ROS vision scan joint poses

Radians

Result orientation arrays

Quaternion [x, y, z, w]

Sample edge inset

Millimetres where the field is named edge_inset_mm

For example, a 10 mm translation is 0.01 metres. A 90 in a pose YAML joint array is 90 degrees; 90 as a revolute arm-joint position in a ROS joint-state message means 90 radians.

RPY means roll, pitch, and yaw. EROBS task fields use the units above; the official rotation guide covers quaternions and RPY conversion.

Frames are part of the request

Coordinates need a frame and units A conceptual XY view compares a Cartesian position expressed in base_link with a forward displacement along an IK frame rotated ninety degrees. Forward is positive local X, so its direction in the room follows the frame. Distances use metres; task joint angles use degrees while ROS revolute joint states use radians. Illustrative coordinates are not calibrated robot targets. EROBS / SPATIAL CONVENTIONS Coordinates need a frame and units Conceptual XY view. The right-hand frame is rotated 90°; geometry is illustrative. Absolute position Relative displacement +X +Y Target 0.30 m 0.20 m frame_id: "base_link" Position is measured from this origin. local +Y local +X forward distance: 0.01 selected IK frame The local direction rotates with it. DISTANCE 10 mm = 0.01 m REVOLUTE JOINT ANGLE 90° = π/2 rad task pose → ROS arm joint state These are unit conventions, not calibrated targets. Prismatic joint positions use metres.
Open the full-size diagram

A Cartesian coordinate is incomplete without its reference frame. base_link describes a position relative to the robot base. flange is the robot’s flange frame. A tool tip frame describes the working end of a particular tool. The camera’s optical frame describes the measurement before transformation into the robot frame.

MoveTo relative directions apply in the flange frame. Vision marker offsets and final base-frame offsets have different meanings. flange and tool0 must not be treated as interchangeable orientation conventions. See vision and frames before interpreting a detected pose as a motion target.

Configuration is not calibration

The beamline YAML selects packages, resources, and per-tool settings. Calibration establishes physical relationships: robot geometry, camera mounting, tool tip offsets, and taught poses. Copying the CMS YAML to a new beamline does not calibrate that installation.