# How to Integrate MoveIt2 with the SRDF Skill in text-to-cad

> Learn to integrate MoveIt2 with the SRDF skill for real-time inverse kinematics and motion planning. Follow simple steps to connect your CAD viewer and enable advanced robot control.

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

---

**To integrate MoveIt2 with the SRDF skill, launch the Python MoveIt2 server from `viewer/moveit2_server`, configure the CAD Viewer WebSocket client, and include a `moveit2` configuration payload when handing off the generated SRDF file to enable real-time inverse kinematics and motion planning.**

The `text-to-cad` repository by earthtojake provides a complete pipeline for generating robot descriptions from natural language inputs. While the SRDF skill (`skills/srdf`) creates semantic robot description files that define planning groups and end-effectors, these definitions remain static until you connect the CAD Viewer to a live MoveIt2 server for interactive kinematic calculations.

## Launching the MoveIt2 Server

The MoveIt2 server is a lightweight Python process that creates a ROS-free MoveIt2 adapter to handle planning requests. Located under `viewer/moveit2_server`, the server exposes a WebSocket interface that speaks the MoveIt2 protocol.

Start the server using the provided shell script:

```bash
cd viewer/moveit2_server
./run-moveit2-server.sh

```

Alternatively, invoke the server module directly:

```bash
python -m moveit2_server.server

```

The server launches on `ws://127.0.0.1:8765/ws` by default and initializes a `MoveItPyAdapter` that parses incoming SRDF files. In [`viewer/moveit2_server/moveit2_server/srdf_source.py`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/moveit2_server/srdf_source.py), the `read_srdf_source()` function extracts the robot name and planning configuration:

```python
def read_srdf_source(srdf_path: Path) -> SrdfSource:
    root = ET.fromstring(resolved_path.read_text())
    return parse_srdf_root(root, source_path=resolved_path)

```

This function (lines 84-99) reads the SRDF XML, resolves file paths, and returns a structured `SrdfSource` object containing planning groups, end-effectors, and disabled collision pairs.

## Configuring the CAD Viewer WebSocket Connection

The CAD Viewer JavaScript client maintains the WebSocket connection to the MoveIt2 server. The client implementation lives in [`packages/cadjs/src/lib/urdf/moveit2ServerClient.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/urdf/moveit2ServerClient.js).

The viewer resolves the server URL through the following priority chain:

1. Query string parameter: `?moveit2Ws=ws://localhost:8765/ws`
2. Vite environment variable: `VIEWER_MOVEIT2_WS_URL`
3. Default fallback: `ws://127.0.0.1:8765/ws`

Key helper functions exported by the client include:

- **`moveit2ServerEnabled()`** – Toggles the MoveIt2 integration feature on or off
- **`moveit2ServerUrl()`** – Resolves the final WebSocket URL using the priority chain above
- **`requestMoveIt2Server()`** – Sends JSON-RPC requests (e.g., `"compute_ik"`) to the server and returns promises
- **`checkMoveIt2ServerLive()`** – Verifies server availability before enabling UI controls

When the viewer loads an SRDF file, it automatically detects the server and enables interactive controls for inverse kinematics and motion planning.

## Handing Off SRDF Data with MoveIt2 Configuration

The SRDF skill generates semantic robot description files but does not embed MoveIt2 execution parameters directly. Instead, the integration occurs through the `$cad-viewer` hand-off mechanism after SRDF generation.

When invoking the CAD Viewer from the SRDF skill, include a `moveit2` field in the JSON payload:

```json
{
  "moveit2": {
    "ikTimeout": 0.05,
    "plannerId": "RRTConnect",
    "planningTime": 2
  }
}

```

The viewer UI consumes these settings in [`viewer/src/client/components/workbench/UrdfFileSheet.js`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/src/client/components/workbench/UrdfFileSheet.js) (lines 386-657). This component builds a `moveit2Settings` object from the hand-off payload and binds the values to UI controls for IK timeout, planner ID, and planning time limits.

If the viewer detects a live MoveIt2 server via `checkMoveIt2ServerLive()`, it automatically enables the planning interface and sends kinematic requests using `requestMoveIt2Server("compute_ik", {...})`.

## Complete Integration Workflow

Follow this sequence to connect a generated SRDF with live MoveIt2 planning capabilities:

```bash

# 1. Start the MoveIt2 server (once per session)

cd viewer/moveit2_server
./run-moveit2-server.sh

# 2. Launch the CAD Viewer (auto-detects server at ws://127.0.0.1:8765/ws)

npx skills install earthtojake/text-to-cad
cad-viewer serve --dir $(pwd)/models

# 3. Generate an SRDF from a URDF

python -m skills.srdf.scripts.srdf path/to/robot.urdf -o robot.srdf

# 4. Hand off to viewer with MoveIt2 settings

$cad-viewer \
  --file robot.srdf \
  --payload '{"moveit2":{"ikTimeout":0.05,"plannerId":"RRTConnect","planningTime":2}}'

```

When the viewer loads `robot.srdf`, it detects the active server, enables the IK and planning UI panels, and visualizes computed poses directly in the 3-D viewport. The `MoveItPyAdapter` in the server handles all kinematic calculations using the planning groups defined in your SRDF file.

## Summary

- **Start the server** using [`viewer/moveit2_server/run-moveit2-server.sh`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/run-moveit2-server.sh) to launch the WebSocket service on port 8765
- **Configure the connection** via query parameters, environment variables, or default to `ws://127.0.0.1:8765/ws` in [`moveit2ServerClient.js`](https://github.com/earthtojake/text-to-cad/blob/main/moveit2ServerClient.js)
- **Parse SRDF semantics** through `read_srdf_source()` in [`srdf_source.py`](https://github.com/earthtojake/text-to-cad/blob/main/srdf_source.py) to extract robot configuration and planning groups
- **Enable interactivity** by including a `moveit2` payload in the `$cad-viewer` hand-off, which [`UrdfFileSheet.js`](https://github.com/earthtojake/text-to-cad/blob/main/UrdfFileSheet.js) binds to UI controls
- **Execute planning** using `requestMoveIt2Server()` to send JSON-RPC calls for inverse kinematics and motion planning

## Frequently Asked Questions

### What is the default WebSocket URL for the MoveIt2 server?

The default WebSocket URL is `ws://127.0.0.1:8765/ws`. The `moveit2ServerUrl()` function in [`moveit2ServerClient.js`](https://github.com/earthtojake/text-to-cad/blob/main/moveit2ServerClient.js) falls back to this address when no `?moveit2Ws` query parameter or `VIEWER_MOVEIT2_WS_URL` environment variable is provided.

### How does the SRDF skill pass MoveIt2 configuration to the viewer?

The SRDF skill invokes `$cad-viewer` with a JSON payload containing a `moveit2` object. This payload includes parameters like `ikTimeout`, `plannerId`, and `planningTime`. The viewer's [`UrdfFileSheet.js`](https://github.com/earthtojake/text-to-cad/blob/main/UrdfFileSheet.js) component reads these values into a `moveit2Settings` object and binds them to the UI controls.

### Which file handles server-side SRDF parsing?

The [`viewer/moveit2_server/moveit2_server/srdf_source.py`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/moveit2_server/moveit2_server/srdf_source.py) file handles server-side SRDF parsing. The `read_srdf_source()` function reads the SRDF file, parses the XML, and extracts the robot name, URDF reference, planning groups, and collision exclusions needed by the MoveIt2 planning context.

### Do I need ROS installed to run the MoveIt2 server?

No. The MoveIt2 server in `viewer/moveit2_server` is designed as a ROS-free Python process. It uses a `MoveItPyAdapter` class to provide MoveIt2 functionality without requiring a full ROS2 installation, making it suitable for lightweight deployment alongside the CAD Viewer.