Beamline configuration

Load and validate the selected beamline YAML, cache its shared mapping, resolve resource paths, and translate settings for ROS launch consumers.

beambot.config_loader · Source

Setup and deployment · Guide · Symbol index

How it is used

Launch files, the orchestrator, stages, and the GUI read the beamline selected by BEAMBOT_BEAMLINE_CONFIG. load_beamline_config() validates configured gripper payloads and voltages before caching the mapping and its source path. Treat that shared mapping as read-only.

Use validate_beamline_config() to check an already parsed mapping without loading a file. It checks tool mass, center of gravity, and voltage, not the complete deployment schema. Named accessors and path/launch helpers serve individual consumers; reset the cache only when deliberately reloading configuration.

Start here

Callable	Purpose
load_beamline_config	Load and validate configuration once under the shared cache lock. Later calls return the same mapping and path; treat nested values as read-only.
validate_beamline_config	Collect payload and voltage problems for every configured gripper. Missing tool sections are skipped; this is not a complete configuration-schema check.
resolve_beamline_path	Expand a configured path. Absolute inputs receive lexical normalization; relative inputs are joined to the nearest ancestor containing src, searched for at most ten levels, or to the configuration directory.
gripper_launch_config	Translate a configured gripper’s launch fields into a launch dictionary, converting voltage, communication flag and RS485 values to strings.
build_pipeline_param_args	Read the installed MoveIt configuration’s OMPL and Pilz YAML files and optional STOMP file, forwarding every top-level and nested value through _emit_param.

Example

With BEAMBOT_BEAMLINE_CONFIG already selecting a beamline, resolve its pose registry the same way as the orchestrator:

from beambot.config_loader import load_beamline_config, resolve_beamline_path

config, config_path = load_beamline_config()
poses_path = resolve_beamline_path(config["poses_file"], config_path)

The example reads configuration only. It assumes the selected YAML defines poses_file; do not modify the shared config mapping.

Functions

`load_beamline_config()`

Load and validate configuration once under the shared cache lock. Later calls return the same mapping and path; treat nested values as read-only.

Entry point · Source

load_beamline_config() -> tuple[dict, str]

Returns: Shared (configuration_dict, absolute_path) tuple.

Errors: Selection, file, YAML, and configuration-validation errors propagate without populating the cache, so a corrected file can be retried.

Side effects: On first successful call, reads YAML, validates configured tools, and stores process-wide state. Subsequent calls avoid both disk I/O and revalidation.

Referenced in source (12)

MTCOrchestratorServer.__init__ — beambot.action_servers.orchestrator
SampleActionServer.create_stages — beambot.action_servers.sample_pick_place_server
arm_joint_names — beambot.config_loader
configured_tip_frames — beambot.config_loader
description_package — beambot.config_loader
gripper_launch_config — beambot.config_loader
gripper_tip_frame — beambot.config_loader
gripper_urdf_file — beambot.config_loader
moveit_config_package — beambot.config_loader
z_offset_for_tip_frame — beambot.config_loader
MoveItLifecycleManager._load_collision_obstacles — beambot.core.moveit_lifecycle_manager
_load_tool_exchange_config — beambot.stages.tool_exchange_stages

`validate_beamline_config()`

Collect payload and voltage problems for every configured gripper. Missing tool sections are skipped; this is not a complete configuration-schema check.

Function · Source

validate_beamline_config(config: dict) -> list[str]

Parameter	Meaning
`config`	Parsed configuration dictionary. Each grippers entry should be a dictionary with payload_mass, payload_cog and optional tool_voltage.

Returns: List of diagnostic strings, empty when these checks pass. Mass must be finite and positive; CoG needs finite x/y/z; voltage must compare equal to 0, 12, or 24, excluding booleans. Omitted voltage means 0 V.

Errors: Reports invalid gripper entries and checked fields in the returned list. A malformed root or truthy nonmapping grippers container can raise Python errors rather than return diagnostics. Strings and booleans are rejected for payload values.

Side effects: Does not mutate the mapping, read files, or contact hardware.

Referenced in source (1)

_load_beamline_config_uncached — beambot.config_loader

`resolve_beamline_path()`

Expand a configured path. Absolute inputs receive lexical normalization; relative inputs are joined to the nearest ancestor containing src, searched for at most ten levels, or to the configuration directory.

Function · Source

resolve_beamline_path(rel_or_abs: str, config_path: str) -> str

Parameter	Meaning
`rel_or_abs`	Configured path, absolute or relative; an empty value means no path.
`config_path`	Beamline YAML filename whose resolved parent anchors the search.

Returns: Resolved path string, or an empty string for an empty input. Relative-path suffixes are joined without an additional resolve call.

Errors: Filesystem/path resolution errors propagate.

Side effects: Checks ancestor directories; does not create or read the target file.

Referenced in source (2)

MTCOrchestratorServer.__init__ — beambot.action_servers.orchestrator
MoveItLifecycleManager._load_collision_obstacles — beambot.core.moveit_lifecycle_manager

`gripper_launch_config()`

Translate a configured gripper’s launch fields into a launch dictionary, converting voltage, communication flag and RS485 values to strings.

Function · Source

gripper_launch_config(gripper: str) -> dict

Parameter	Meaning
`gripper`	Gripper key under grippers.

Returns: Dictionary containing urdf_xacro, moveit_controllers, tool_voltage, use_tool_communication and tool_comm_params.

Errors: Raises BeamlineConfigError for an undeclared gripper; missing required fields raise KeyError. Configuration and malformed-data errors propagate.

Side effects: May initialize the shared configuration cache.

Referenced in source (1)

launch_setup — src.custom-ur-descriptions.cms_moveit_config.launch.robot_bringup.launch

`build_pipeline_param_args()`

Read the installed MoveIt configuration’s OMPL and Pilz YAML files and optional STOMP file, forwarding every top-level and nested value through _emit_param.

Function · Source

build_pipeline_param_args() -> list

Returns: Flat list of ROS -p argument pairs, prefixed by pipeline name.

Errors: Package lookup, required-file I/O, YAML parsing, malformed mappings and leaf serialization errors propagate. A missing STOMP file is skipped.

Side effects: Locates an ament package and reads planning YAML files; may load the shared beamline configuration.

Referenced in source (1)

generate_launch_description — src.beambot.launch.beambot_bringup.launch

`get_beamline_config_path()`

Read BEAMBOT_BEAMLINE_CONFIG, trim whitespace, expand the home directory and normalize an absolute filename without following symlinks.

Function · Source

get_beamline_config_path() -> str

Returns: Absolute filename of an existing regular file.

Errors: Raises BeamlineConfigError when the environment variable is empty or the file does not exist.

Side effects: Reads the environment and checks the filesystem.

Referenced in source (1)

_load_beamline_config_uncached — beambot.config_loader

`is_finite_number()`

Check for a finite real number, excluding booleans and numeric strings.

Function · Source

is_finite_number(value) -> bool

Parameter	Meaning
`value`	Value to inspect without coercing it to a number.

Returns: True for nonboolean numbers.Real values accepted as finite by math.isfinite; otherwise False.

Errors: No exception conversion; unusual numeric conversion failures, such as an integer too large for math.isfinite, can propagate.

Referenced in source (4)

validate_beamline_config — beambot.config_loader
_finite_number — beambot.core.task_script
flange_offset_error — beambot.core.task_script
moveto_goal_error — beambot.core.task_script

`reset_beamline_config_cache()`

Clear the process-wide configuration reference under its lock so the next load rereads the selected file.

Function · Source

reset_beamline_config_cache() -> None

Returns: None.

Errors: No explicit validation or error conversion.

Side effects: Invalidates the loader cache; previously returned mapping objects and caller-specific cached properties remain unchanged.

`arm_joint_names()`

Return the configured robot.arm_joints order used to align positional pose values, falling back to the standard six UR arm joints.

Function · Source

arm_joint_names() -> list[str]

Returns: New list of configured joint names, or the six default shoulder-to-wrist names when absent or loading fails.

Errors: Suppresses every exception from configuration access.

Side effects: May initialize the shared configuration cache.

Referenced in source (1)

MoveItLifecycleManager.__init__ — beambot.core.moveit_lifecycle_manager

`gripper_tip_frame()`

Look up grippers.<gripper>.tip_frame for TF and IK consumers.

Function · Source

gripper_tip_frame(gripper: str, default: str='flange') -> str

Parameter	Meaning
`gripper`	Gripper key in the beamline configuration.
`default`	Fallback frame name; flange by default.

Returns: Configured value, or default when the key is absent or loading fails.

Errors: Suppresses configuration lookup exceptions.

Side effects: May initialize the shared configuration cache.

`z_offset_for_tip_frame()`

Search configured grippers in insertion order for a matching tip frame and convert its z_offset to a float.

Function · Source

z_offset_for_tip_frame(tip_frame: str, default: float=0.0) -> float

Parameter	Meaning
`tip_frame`	TF tip-frame name to match.
`default`	Fallback offset in metres, default 0.0.

Returns: First matching gripper offset in metres, or default if no match or a read/conversion fails.

Errors: Suppresses configuration and float-conversion exceptions.

Side effects: May initialize the shared configuration cache.

`configured_tip_frames()`

Collect distinct truthy configured tip frames, preserving their configuration order and excluding flange.

Function · Source

configured_tip_frames() -> list[str]

Returns: List of candidate attached-tool frames; empty on missing configuration or any lookup failure.

Errors: Suppresses configuration lookup exceptions.

Side effects: May initialize the shared configuration cache.

`moveit_config_package()`

Read robot.moveit_config_package for consumers that locate planner and joint-limit resources.

Function · Source

moveit_config_package(default: str='cms_moveit_config') -> str

Parameter	Meaning
`default`	Package name used if absent or unreadable; cms_moveit_config by default.

Returns: Configured package value or default.

Errors: Suppresses configuration lookup exceptions.

Side effects: May initialize the shared configuration cache.

Referenced in source (5)

build_pipeline_param_args — beambot.config_loader
_build_cartesian_limit_args — beambot.stages.base_stages
_build_kinematics_args — beambot.stages.base_stages
_load_joint_accel_limits — beambot.stages.base_stages
generate_launch_description — src.beambot.launch.beambot_bringup.launch

`description_package()`

Read robot.description_package for consumers locating URDF and mesh resources.

Function · Source

description_package(default: str='cms_robot_description') -> str

Parameter	Meaning
`default`	Package name used if absent or unreadable; cms_robot_description by default.

Returns: Configured package value or default.

Errors: Suppresses configuration lookup exceptions.

Side effects: May initialize the shared configuration cache.

`gripper_urdf_file()`

Read a gripper’s urdf_file used by the viewer; this is separate from its launch_urdf xacro.

Function · Source

gripper_urdf_file(gripper: str, default: str='ur_standalone.urdf') -> str

Parameter	Meaning
`gripper`	Configured gripper key.
`default`	Fallback filename, ur_standalone.urdf by default.

Returns: Configured URDF filename or default.

Errors: Suppresses configuration lookup exceptions.

Side effects: May initialize the shared configuration cache.

Internal callbacks and helpers

`_load_beamline_config_uncached()`

Read the selected YAML, require a mapping, and validate all configured gripper payloads and tool voltages before returning it.

Internal helper · Source

_load_beamline_config_uncached() -> tuple[dict, str]

Returns: Fresh (configuration_dict, absolute_path) tuple.

Errors: YAML syntax, non-mapping roots, and reported gripper validation errors become BeamlineConfigError. Validation messages are collected into one error. File-open errors and malformed container errors not handled by the validator propagate.

Side effects: Reads the environment and YAML file without populating the memoized cache.

Referenced in source (1)

load_beamline_config — beambot.config_loader

`_emit_param()`

Recursively flatten mapping leaves into dotted ROS parameter names, JSON-render each leaf, and replace double quotes with single quotes.

Internal helper · Source

_emit_param(prefix: str, value, args: list) -> None

Parameter	Meaning
`prefix`	Dotted prefix for this value.
`value`	Mapping to recurse through or JSON-serializable leaf.
`args`	Mutable command-argument list receiving alternating -p and name:=value strings.

Returns: None.

Errors: JSON serialization errors propagate for unsupported leaf values.

Side effects: Appends arguments to the caller’s list in mapping iteration order.

Referenced in source (1)

build_pipeline_param_args — beambot.config_loader

`gripper_launch_config._s()`

Render a launch value as text, lowercasing Python boolean values.

Internal helper · Source

_s(v)

Parameter	Meaning
`v`	Value from the gripper launch configuration.

Returns: true or false for booleans; str(v) for other values.

Errors: Errors from a custom string conversion propagate.

Referenced in source (1)

gripper_launch_config — beambot.config_loader

Beamline configuration

How it is used

Start here

Example

Functions

load_beamline_config()

validate_beamline_config()

resolve_beamline_path()

gripper_launch_config()

build_pipeline_param_args()

get_beamline_config_path()

is_finite_number()

reset_beamline_config_cache()

arm_joint_names()

gripper_tip_frame()

z_offset_for_tip_frame()

configured_tip_frames()

moveit_config_package()

description_package()

gripper_urdf_file()

Internal callbacks and helpers

_load_beamline_config_uncached()

_emit_param()

gripper_launch_config._s()

`load_beamline_config()`

`validate_beamline_config()`

`resolve_beamline_path()`

`gripper_launch_config()`

`build_pipeline_param_args()`

`get_beamline_config_path()`

`is_finite_number()`

`reset_beamline_config_cache()`

`arm_joint_names()`

`gripper_tip_frame()`

`z_offset_for_tip_frame()`

`configured_tip_frames()`

`moveit_config_package()`

`description_package()`

`gripper_urdf_file()`

`_load_beamline_config_uncached()`

`_emit_param()`

`gripper_launch_config._s()`