Beamline configuration

Set BEAMBOT_BEAMLINE_CONFIG to the YAML file containing robot, tool, camera, and deployment settings. The main launch requires an explicit selection.

Selection and caching

Configuration loads once per process:

get_beamline_config_path() reads the environment variable, strips whitespace, expands ~, and resolves an absolute path. An unset variable or missing file is an error.
load_beamline_config() reads the YAML. Its root must be a mapping.
A successful load caches the mapping and resolved path for the process lifetime. Consumers share the mapping and must treat it as read-only.

Restart affected processes after changing the YAML or its environment variable. Running processes do not automatically refresh their cached configuration.

reset_beamline_config_cache() supports test isolation or an explicit in-process reload. It clears only the loader cache; existing references and consumer caches remain unchanged. Restarting the affected processes is the normal way to apply deployment changes.

Some convenience helpers catch configuration failures and return defaults so isolated imports or tests can work. Main application startup still requires the configuration file.

Configuration sections and consumers

Section	Meaning and principal consumers
`beamline`	Identity reported to clients; not a directory-discovery mechanism by itself
`poses_file`	Named joint-pose registry used by task parsing and pose tools
`scene_file`	Static planning-scene obstacle resource
`robot`	Robot address, arm group, IK frame, ordered joints, description/MoveIt packages, velocity and acceleration scaling
`grippers`	Tool launch arguments, voltage/communication, controller/group/states, tip frame, payload, geometry and viewer resources
`camera`	Camera adapter type, frame and ArUco dictionary; the current CMS files select Zivid
`tool_exchange`	Dock spacing, reference dock and physical load/dock moves
`collision_objects`	Optional marker-linked shapes; the sample-bar example is commented out in both CMS files
`vision_targets`	Marker-based offset or grid recipes used by task macros and MCP builders

The CMS values show every configured leaf value in cms_beamline.yaml. cms_drylab.yaml selects the dry-lab robot address while retaining the same CMS pose, scene and model resources. These values are specific to CMS. Check the consuming code before removing a configuration key.

How resource paths are resolved

CMS uses workspace-relative paths such as src/cms/poses.yaml. Do not assume every consumer resolves a relative resource against the YAML file’s directory. The orchestrator, MCP bridge, GUI, and installed package resources have distinct lookup code. The GUI’s saved-run directory also has CMS-specific behavior.

When moving a deployment, verify the resolved paths in each component. Check that every resolved file exists and that each consumer selects the intended resource. The configuration architecture traces these paths.

Tool settings must agree

Different tool fields configure different parts of the system:

Fields	What they configure
`tip_frame`	Working frame used for inverse kinematics (IK)
`gripper_group`, `states`	MoveIt gripper group and named states
`launch_urdf`, controller files, communication settings, payload	Robot and tool stack
`urdf_file`	GUI viewer model; this can differ from the launch Xacro

The shared configuration loader validates every configured tool before caching the YAML: positive finite payload_mass, finite numeric payload_cog.x, .y and .z, and an allowed tool voltage of 0, 12 or 24 V. These checks also apply to mock sessions. The current LIX file has only commented payload examples, so it fails configuration loading.

CMS’s velocity and acceleration scaling values are 0.2; these are configured values rather than immutable global limits. The ePick cup_profile and z_offset affect geometry/approach behavior. The configured z_offset is applied along base_link Z, in meters. The current ePick offset includes a documented compensation for modeled geometry; keep that physical calibration context when editing it.

The cup_profile ROS parameter is a runtime override managed outside the shared cached mapping. It takes effect when the relevant MoveIt model is subsequently launched. Changing the parameter does not trigger an immediate model rebuild or relaunch.

Vision-target example

A grid target combines marker detection with rows, columns, pitch, and direction conventions. After marker alignment, the selected row and column determine the movements to a grid cell. An offset target describes a single marker-relative location.

Both require deployment calibration: marker IDs, offsets, scan poses, and approach/retreat distances must match the physical setup.

The task parser and MCP grid helper share expand_grid_target() for grid validation and task expansion. Their request formats differ: the parser accepts pickup task fields, while MCP takes a target name and grid coordinates. See task macros and MCP tools.