What Is the SRDF Skill for Robot Planning? A MoveIt 2 Configuration Guide

The SRDF skill generates and validates MoveIt 2 semantic descriptions that define planning groups, end-effectors, and collision constraints for robot motion planning.

The SRDF (Semantic Robot Description Format) skill bridges the gap between a robot’s physical definition and its motion planning capabilities in the earthtojake/text-to-cad repository. While the URDF captures kinematic chains and geometry, the SRDF skill provides the programmatic interface to create, parse, and validate the semantic layer that MoveIt 2 requires to plan safe, collision-free trajectories.

Core Components Parsed by the SRDF Skill

The parser in skills/srdf/scripts/srdf/source.py transforms SRDF XML into strongly-typed Python dataclasses. Each component serves a distinct role in robot planning.

Planning Groups (SrdfPlanningGroup)

Planning groups are the fundamental units of motion in MoveIt 2. The SRDF skill parses these into SrdfPlanningGroup objects (lines 24-30 of source.py), which represent collections of joints, links, kinematic chains, or nested sub-groups that the planner manipulates as a single unit. Defining these groups tells MoveIt which degrees of freedom to control when generating arm motions or coordinated movements.

End-Effector Definitions (SrdfEndEffector)

Grippers and tools require semantic attachment points. The SrdfEndEffector dataclass (lines 33-38) captures the parent planning group, the TCP (Tool Center Point) link name, and the physical interface, enabling inverse kinematics solvers to compute reachable poses for manipulation tasks.

Named Group States (SrdfGroupState)

Group states store canonical joint configurations—such as "home," "ready," or "retracted"—in URDF-native units. The SrdfGroupState class (lines 41-46) validates these named poses, allowing planners to reference predefined configurations without hardcoding joint values in motion scripts.

Disabled Collision Pairs (SrdfDisabledCollisionPair)

Not all link pairs require collision checking. The SrdfDisabledCollisionPair dataclass (lines 53-58) encodes pairs of links that should ignore each other during planning, along with the reason (e.g., "adjacent" or "never collide") and source classification. This optimization reduces planning time by eliminating false-positive collision checks between permanently connected or non-interacting components.

SRDF Validation and Data Integrity

The SRDF skill enforces schema compliance through the SrdfSource aggregator class (lines 73-78). During parsing, it validates:

• Required attributes for each semantic element
• Duplicate group or state names
• Numeric joint values and finite number constraints

When violations occur, the parser raises SrdfSourceError with specific messaging, preventing malformed SRDF files from reaching the MoveIt pipeline.

Loading and Using SRDF Data Programmatically

The read_srdf_source function provides the primary entry point for consuming SRDF files in Python workflows.

from pathlib import Path
from skills.srdf.scripts.srdf.source import read_srdf_source

# Load an SRDF file relative to the repository root

srdf_path = Path("models/my_robot.srdf")
srdf = read_srdf_source(srdf_path)

# Iterate through planning groups to verify configuration

for group in srdf.planning_groups:
    print(f"Group {group.name} controls joints {group.joint_names}")

# Inspect collision exceptions with audit trails

for pair in srdf.disabled_collision_pairs:
    print(f"Disable {pair.link1} ↔ {pair.link2} because {pair.reason} (source: {pair.source})")

The file_ref_from_srdf_path utility (lines 73-78) generates repository-relative references, ensuring that SRDF assets remain portable across development environments.

Command-Line Validation Workflow

For continuous integration or pre-commit checks, the SRDF skill exposes a CLI through skills/srdf/scripts/srdf/cli.py.

# Validate SRDF syntax and semantic constraints

python -m skills.srdf.scripts.srdf.cli validate models/my_robot.srdf

This command invokes the same validation logic used by read_srdf_source, catching errors before the description reaches the CAD Viewer for visual inspection. The workflow documentation in skills/srdf/references/srdf-workflow.md details the iterative edit loop: modify XML, validate via CLI, and visualize in the viewer to confirm that planning groups and collision exclusions render correctly.

Summary

• The SRDF skill for robot planning converts XML semantic descriptions into validated Python objects that MoveIt 2 consumes for motion generation.
• SrdfPlanningGroup, SrdfEndEffector, and SrdfGroupState dataclasses encapsulate the kinematic and configuration semantics missing from raw URDF files.
• SrdfDisabledCollisionPair entries optimize planning performance by explicitly excluding non-colliding link pairs from collision detection.
• The validation layer in source.py raises SrdfSourceError for schema violations, ensuring only compliant SRDF files reach the planning pipeline.
• Developers can programmatically load descriptions via read_srdf_source or validate files via the CLI before visualization.

Frequently Asked Questions

What is the difference between URDF and SRDF in robot planning?

The URDF defines the physical robot—links, joints, geometry, and limits—while the SRDF adds the semantic layer required by motion planners. According to the earthtojake/text-to-cad source code, the SRDF skill manages planning groups, end-effector attachments, and collision exceptions that URDF cannot express, enabling MoveIt 2 to reason about which joints to move and which collisions to ignore.

How does the SRDF skill handle invalid or malformed SRDF files?

The parser in skills/srdf/scripts/srdf/source.py performs strict validation during instantiation. It checks for required attributes, unique naming conventions, and finite numeric values for joint states. When it encounters violations, the skill raises SrdfSourceError with descriptive messages, halting the workflow before the invalid configuration reaches the motion planner.

Why are disabled collision pairs important in SRDF files?

Disabled collision pairs prevent the motion planner from wasting computation checking collisions between links that are physically adjacent, permanently fixed, or designed to operate in close proximity. The SrdfDisabledCollisionPair class tracks both the link pair and the justification (e.g., "adjacent"), providing an auditable record of why specific safety checks are bypassed during trajectory generation.

Can the SRDF skill be used outside of the text-to-cad repository?

While designed for the earthtojake/text-to-cad ecosystem, the SRDF skill is a standalone Python module. The read_srdf_source function accepts any pathlib.Path to a valid SRDF file, and the dataclasses (SrdfSource, SrdfPlanningGroup, etc.) are agnostic to the specific robot model, making the skill reusable for any MoveIt 2 project requiring programmatic SRDF generation or validation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}