How to Configure MoveIt2 with SRDF for Robot Planning: A Complete Guide

To configure MoveIt2 with SRDF for robot planning, generate a Semantic Robot Description Format file that defines planning groups, end-effectors, and collision pairs, then launch the MoveIt2 server from the CAD Viewer skill to enable interactive inverse kinematics and path planning.

The earthtojake/text-to-cad repository provides a complete pipeline for configuring MoveIt2 with SRDF for robot planning. The SRDF augments a standard URDF with the semantic information MoveIt2 requires—planning groups, end-effectors, disabled collision pairs, and default states—while the optional MoveIt2 server exposes these capabilities via WebSocket for interactive control in the CAD Viewer.

Understanding the SRDF and MoveIt2 Architecture

Before generating configuration files, understand how the components interact. The URDF (skills/urdf/SKILL.md) provides the physical robot model with links, joints, and meshes. The SRDF (skills/srdf/SKILL.md) layers planning semantics on top, defining which joints constitute kinematic chains and which links may collide. The MoveIt2 server (skills/cad-viewer/references/moveit2-server.md) consumes both files through the context builder (viewer/moveit2_server/moveit2_server/context.py) to provide planning services.

Key architectural components include:

• build_moveit2_context in viewer/moveit2_server/moveit2_server/context.py — Merges URDF and SRDF payloads into a validated configuration object
• srdf_source.py — Reads user-supplied SRDF files and validates them against the linked URDF
• WebSocket server — Listens on ws://127.0.0.1:8765/ws by default to expose IK and planning APIs

Step 1: Prepare a Valid URDF Model

All planning semantics depend on a correct URDF. Use the urdf skill or edit the file manually, ensuring the robot name matches exactly what you will reference in the SRDF.

Generate a URDF from a Python source:

python skills/urdf/scripts/urdf/source.py path/to/robot_source.py -o models/robot.urdf

The URDF must remain accessible at the absolute path you will later pass to the SRDF generator and context builder.

Step 2: Generate the SRDF Configuration

The SRDF is produced via the srdf skill. The CLI accepts a Python source file that returns a dictionary describing semantic entities. Run:

python skills/srdf/scripts/srdf.py path/to/srdf_source.py -o models/robot.srdf

According to skills/srdf/SKILL.md, your SRDF must define:

• Planning groups — Kinematic chains from base link to tip link
• End-effectors — Tool links that must not overlap with their parent planning group
• Group states — Default joint values in URDF-native units (radians for revolute joints, meters for prismatic)
• Disabled collisions — Explicit collision pairs with provenance reasoning, never wildcard lists

Ensure the SRDF references the same robot name as the URDF (<robot name="my_robot">).

Step 3: Validate the SRDF Against the URDF

Validation occurs automatically when loading into the MoveIt2 context. The build_moveit2_context function in viewer/moveit2_server/moveit2_server/context.py parses the payload and raises MotionProtocolError for mismatches.

Validate programmatically before starting the server:

from moveit2_server.context import build_moveit2_context
from moveit2_server.protocol import MotionProtocolError

payload = {
    "urdf": {"path": "models/robot.urdf"},
    "srdf": {"path": "models/robot.srdf"},
    # optional moveit2 settings

}
try:
    context = build_moveit2_context(payload)
    print("Validation successful")
except MotionProtocolError as e:
    print("SRDF validation failed:", e)

Step 4: Launch the MoveIt2 Server

To enable interactive IK and planning inside CAD Viewer, start the optional MoveIt2 server from the cad-viewer skill directory:

# From `skills/cad-viewer` directory

npm --prefix scripts/viewer run moveit2:setup   # Install ROS2 dependencies (once)

npm --prefix scripts/viewer run moveit2:check   # Verify ROS2/MoveIt2 environment

npm --prefix scripts/viewer run moveit2:serve   # Start the WebSocket server

The server listens on ws://127.0.0.1:8765/ws by default, though you can override the port with MOVEIT2_WS_PORT before running the serve command.

Step 5: Connect the CAD Viewer

Start CAD Viewer and point it to your model directory:

npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir $PWD/models

Append query parameters to the printed URL to load your SRDF and connect to the MoveIt2 server:

http://127.0.0.1:12345/?dir=/absolute/path/to/models&file=robot.srdf&moveit2Ws=ws://127.0.0.1:8765/ws

Inside the viewer interface, you can:

• Select planning groups, end-effectors, and target frames
• Adjust IK tolerance, timeout, and attempts
• Choose planning pipelines, planner IDs, and planning time
• Execute solve pose (IK) or plan to pose actions and visualize trajectories

Common Configuration Pitfalls

Avoid these frequent errors when you configure MoveIt2 with SRDF for robot planning:

• SRDF references non-existent URDF — Ensure urdf.path points to the exact file and that <robot name> attributes match between files
• Group states in degrees — The SRDF expects URDF-native units; convert all revolute joint values to radians
• Broad disabled-collision lists — Populate collision pairs only from sampling, adjacency analysis, or explicit user data per references/disabled-collisions.md
• WebSocket connection failures — Verify VIEWER_MOVEIT2_WS_URL or the ?moveit2Ws= query matches the server address, and ensure you sourced the ROS2 workspace before launching the server
• Port conflicts — The serve script retries automatically, but you can prevent conflicts by setting MOVEIT2_WS_PORT beforehand

Complete End-to-End Example

This workflow generates a URDF and SRDF, validates the configuration, and launches the interactive viewer:

# 1. Generate URDF

python skills/urdf/scripts/urdf/source.py examples/simple_arm.py -o models/simple_arm.urdf

# 2. Generate SRDF with planning groups and end-effector

python skills/srdf/scripts/srdf.py examples/simple_arm_srdf.py -o models/simple_arm.srdf

# 3. Validate the configuration

python - <<'PY'
from moveit2_server.context import build_moveit2_context
payload = {
    "urdf": {"path": "models/simple_arm.urdf"},
    "srdf": {"path": "models/simple_arm.srdf"},
    "moveit2": {"planningGroup": "arm", "endEffector": "gripper"}
}
print(build_moveit2_context(payload))
PY

# 4. Start MoveIt2 server

cd skills/cad-viewer
npm --prefix scripts/viewer run moveit2:setup
npm --prefix scripts/viewer run moveit2:check
npm --prefix scripts/viewer run moveit2:serve

# 5. Launch CAD Viewer with MoveIt2 integration

npm --prefix scripts/viewer run agent:start -- --host 127.0.0.1 --dir $(pwd)/../models

# Append to URL: &file=simple_arm.srdf&moveit2Ws=ws://127.0.0.1:8765/ws

Summary

• The SRDF (skills/srdf/SKILL.md) provides MoveIt2 with planning semantics including groups, end-effectors, and collision rules
• Validation occurs through build_moveit2_context in viewer/moveit2_server/moveit2_server/context.py, which raises MotionProtocolError for mismatched URDF/SRDF pairs
• The MoveIt2 server starts via npm run moveit2:serve and exposes planning APIs on WebSocket port 8765
• The CAD Viewer connects to the server via the ?moveit2Ws= URL parameter, enabling interactive IK and trajectory planning directly in the browser

Frequently Asked Questions

What is the relationship between URDF and SRDF in MoveIt2?

The URDF describes the physical robot geometry and kinematics, while the SRDF augments it with planning-specific metadata. According to the text-to-cad source code, the SRDF defines planning groups, end-effectors, disabled collision pairs, and default states, allowing MoveIt2 to understand which joints constitute manipulable chains and which links may safely collide.

Why does my SRDF validation fail with MotionProtocolError?

Validation fails when the SRDF references a robot name that does not match the URDF, when joint values use degrees instead of radians, or when specified links do not exist in the URDF. The build_moveit2_context function in viewer/moveit2_server/moveit2_server/context.py performs strict validation and raises MotionProtocolError when it detects these mismatches.

How do I connect the CAD Viewer to a running MoveIt2 server?

Pass the WebSocket URL via the moveit2Ws query parameter when opening the viewer, or set the VIEWER_MOVEIT2_WS_URL environment variable. The default server address is ws://127.0.0.1:8765/ws. Ensure you launched the server using npm run moveit2:serve from the skills/cad-viewer directory after sourcing your ROS2 environment.

Can I use the MoveIt2 configuration without the CAD Viewer?

Yes. The SRDF file is a standard MoveIt2 configuration format. While the text-to-cad repository provides the optional MoveIt2 WebSocket server (viewer/moveit2_server/moveit2_server/server.py) for browser-based interaction, the generated SRDF works with any standard MoveIt2 setup in ROS2.

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