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

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:

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

Alternatively, invoke the server module directly:

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, the read_srdf_source() function extracts the robot name and planning configuration:

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.

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:

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

The viewer UI consumes these settings in 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:

# 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 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
• Parse SRDF semantics through read_srdf_source() in 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 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 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 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 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.

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