Is this page helpful?

Robot Configuration Tutorial#

This tutorial covers configuring robots for use with the cuMotion integration — from generating the required XRDF file to loading it into your application.

By the end of this tutorial, you’ll understand:

  • How to load pre-configured or custom robot configurations using load_cumotion_supported_robot() and load_cumotion_robot()

  • How to use robot configurations with cuMotion components

Prerequisites

  • Basic understanding of URDF and XRDF file formats

Overview#

An XRDF file is the main configuration file required by cuMotion for a specific robot. It supplements the robot’s URDF with cuMotion-specific data: collision-sphere geometries, self-collision settings, joint properties, tool frames, and modifiers.

Active and Fixed Joints

A key aspect of the XRDF is defining the robot’s configuration space. Joints are classified as either active or fixed. Active joints are directly controlled by cuMotion; fixed joints are held at a specified default position. For example, on a seven-DOF arm with an attached gripper, the arm joints are active and the gripper joints are fixed. The fixed-joint positions define the robot’s default configuration, which is used for null-space behavior in reactive control.

Collision Spheres

cuMotion uses a set of spheres attached to each robot link for collision avoidance. These spheres must roughly cover the robot’s surface. The cuMotion/Lula Robot Description Editor provides tools to generate and tune this sphere set for any robot. For a full tutorial on XRDF and URDF file generation, see Generate Robot Description Files and Collision Spheres.

Robot Configuration Files#

cuMotion expects the following files for each robot, organized in a single directory:

robot_config/
├── robot.urdf
├── robot.xrdf
├── rmp_flow.yaml                          (optional)
├── graph_based_motion_planner_config.yaml (optional)
└── meshes/
    ├── link_0.stl
    ├── link_1.stl
    └── ...

  • robot.urdf — The URDF file describing the robot’s kinematic structure, joint limits, and link geometries.

  • robot.xrdf — The XRDF file containing cuMotion-specific configuration: collision-sphere geometries, active/fixed joint assignments, default joint positions, tool frames, and self-collision rules.

  • meshes/ — Directory containing the mesh files referenced by the URDF.

  • rmp_flow.yaml (optional) — RMPflow configuration for reactive control.

  • graph_based_motion_planner_config.yaml (optional) — Graph-based motion planner configuration.

Both the URDF and XRDF files can be generated directly from a robot USD asset using extensions provided with Isaac Sim:

Note

For a complete step-by-step walkthrough generating XRDF and URDF files for a UR10e with a Robotiq 2F-140 gripper, see Generate Robot Description Files and Collision Spheres.

Loading Robot Configurations#

Once you have URDF and XRDF files, load them into a CumotionRobot object, which encapsulates all data needed to work with cuMotion:

  • robot_description: The cuMotion robot description loaded from URDF/XRDF files, including default joint positions and tool frame names

  • kinematics: The cuMotion kinematics solver for forward kinematics and Jacobian computation

  • controlled_joint_names: List of joint names controlled by cuMotion

  • directory: Path to the robot configuration directory (useful for loading related config files)

The provided functions for loading a CumotionRobot object are:

  • load_cumotion_supported_robot() - Load a pre-configured robot from the extension’s robot_configurations directory.

  • load_cumotion_robot() - Load a custom robot from a given directory.

Loading Supported Robots#

The easiest way to get started is to use a pre-configured robot that comes with the extension. Currently supported robots include:

  • franka - Franka Emika Panda robot

  • ur10 - Universal Robots UR10 robot

    import isaacsim.robot_motion.cumotion as cu_mg

    # Load a supported robot
    robot = cu_mg.load_cumotion_supported_robot("franka")

The function automatically locates the robot configuration directory within the extension and loads the URDF and XRDF files. If the robot name is not supported, a FileNotFoundError will be raised.

Creating Custom Robot Configurations#

If you have your own robot with URDF and XRDF files, load it using load_cumotion_robot():

    import isaacsim.robot_motion.cumotion as cu_mg

    # Generate configuration with default filenames (robot.urdf, robot.xrdf)
    robot = cu_mg.load_cumotion_robot(directory=robot_directory)

If your URDF or XRDF files have different names, specify them explicitly:

    import isaacsim.robot_motion.cumotion as cu_mg

    robot = cu_mg.load_cumotion_robot(
        directory=absolute_path_to_robot_directory,
        urdf_filename="robot.urdf",  # if your URDF has a different name, use it.
        xrdf_filename="robot.xrdf",  # if your XRDF has a different name, use it.
    )

The function will raise a FileNotFoundError if the specified files cannot be found.

Accessing Robot Description and Kinematics#

The robot configuration provides direct access to the underlying cuMotion objects:

    robot = load_cumotion_supported_robot("franka")

    # Access the robot description
    robot_description = robot.robot_description

    # Get tool frame names
    tool_frames = robot_description.tool_frame_names()

    # Get number of configuration space coordinates
    num_dofs = robot_description.num_cspace_coords()

    # Access the kinematics solver
    # (See cuMotion documentation for kinematics API)
    kinematics = robot.kinematics

The controlled joint names are automatically extracted from the robot description and represent all joints in the configuration space:

    robot = load_cumotion_supported_robot("franka")

    # Controlled joints match the configuration space coordinates
    controlled_joints = robot.controlled_joint_names

    # This is equivalent to:
    controlled_joints = [
        robot.robot_description.cspace_coord_name(i) for i in range(robot.robot_description.num_cspace_coords())
    ]

Loading Configuration Files for Reactive Control and Path Planning#

The directory attribute of the CumotionRobot object is useful for loading related configuration files.

For RMPflow controllers:

    robot = load_cumotion_supported_robot("franka")

    # The RmpFlowController automatically resolves relative paths relative to robot.directory
    controller = RmpFlowController(
        cumotion_robot=robot,
        cumotion_world_interface=world_interface,
        robot_joint_space=robot_joint_space,
        robot_site_space=robot_site_space,
        rmp_flow_configuration_filename="rmp_flow.yaml",  # Relative to robot.directory
    )

Or specify an absolute path:

    robot = load_cumotion_supported_robot("franka")

    # Or specify an absolute path
    controller = RmpFlowController(
        cumotion_robot=robot,
        cumotion_world_interface=world_interface,
        robot_joint_space=robot_joint_space,
        robot_site_space=robot_site_space,
        rmp_flow_configuration_filename=absolute_path_to_config,
    )

For graph-based motion planners:

    robot = load_cumotion_supported_robot("franka")

    # Relative paths are automatically resolved relative to robot.directory
    planner = GraphBasedMotionPlanner(
        cumotion_robot=robot,
        cumotion_world_interface=world_interface,
        graph_planner_config_filename="graph_based_motion_planner_config.yaml",
    )

Or specify an absolute path:

    robot = load_cumotion_supported_robot("franka")

    # Or specify an absolute path
    planner = GraphBasedMotionPlanner(
        cumotion_robot=robot,
        cumotion_world_interface=world_interface,
        graph_planner_config_filename=absolute_path_to_config,
    )

The configuration files are subsequently used by all of the integrated cuMotion planners and controllers:

  • RmpFlowController

  • GraphBasedMotionPlanner

  • TrajectoryGenerator

  • TrajectoryOptimizer

See the relevant tutorials under Next Steps at the end of this tutorial for more information on each of the cuMotion components.

Summary#

This tutorial covered:

  1. XRDF Overview: The structure of XRDF files and the concepts of active/fixed joints and collision spheres

  2. Robot Configuration Files: The URDF, XRDF, and optional configuration files required by cuMotion, and the Isaac Sim tools used to generate them from a USD asset

  3. Loading Supported Robots: Using load_cumotion_supported_robot() for pre-configured robots

  4. Custom Robots: Using load_cumotion_robot() for your own URDF/XRDF files

  5. Accessing Robot Data: Using the robot description and kinematics objects directly

Robot configurations are foundational for all cuMotion motion planning and control. Once you have a configuration, you can use it with any cuMotion component to generate motions for your robot.

Next Steps#