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

> Learn to configure MoveIt2 with SRDF for robot planning. Generate an SRDF file and launch the MoveIt2 server for interactive inverse kinematics and path planning with this complete guide.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md)) provides the physical robot model with links, joints, and meshes. The **SRDF** ([`skills/srdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/references/moveit2-server.md)) consumes both files through the context builder ([`viewer/moveit2_server/moveit2_server/context.py`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/moveit2_server/context.py) — Merges URDF and SRDF payloads into a validated configuration object
- **[`srdf_source.py`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
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:

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

```

According to [`skills/srdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/moveit2_server/context.py) parses the payload and raises `MotionProtocolError` for mismatches.

Validate programmatically before starting the server:

```python
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:

```bash

# 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:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash

# 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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/moveit2_server/server.py)) for browser-based interaction, the generated SRDF works with any standard MoveIt2 setup in ROS2.