Robot Configuration Tutorial#

This tutorial demonstrates how to configure robots for use with the cuMotion integration. You’ll learn how to load robot configurations from supported robots or create custom robot configurations from URDF and XRDF files.

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

  • How to load pre-configured robots using load_cumotion_supported_robot()

  • How to load custom robot configurations using load_cumotion_robot()

  • The structure of robot configuration directories

  • How to use robot configurations with cuMotion components

Prerequisites

  • Basic understanding of URDF and XRDF file formats

Key Concepts#

A CumotionRobot encapsulates all the necessary data for a robot to work with cuMotion:

  • robot_description: The cuMotion robot description loaded from URDF/XRDF files, which includes some key properties such as the default joint positions and the tool frame names

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

  • controlled_joint_names: List of joint names that are controlled by cuMotion software

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

Note

For generating new XRDF files, the Robot Description Editor tutorial is still valid.

The configuration is used by all cuMotion components including:

  • RmpFlowController - Reactive motion control

  • GraphBasedMotionPlanner - Path planning

  • TrajectoryGenerator - Trajectory generation

  • TrajectoryOptimizer - Trajectory optimization

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

To load a supported robot configuration:

    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, you can 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, you can 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.

Robot Configuration Directory Structure#

A robot configuration directory should contain:

  • robot.urdf - The URDF file describing the robot’s kinematic structure

  • robot.xrdf - The XRDF file containing additional cuMotion-specific configuration

  • meshes/ - Directory containing mesh files referenced by the URDF

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

  • graph_based_motion_planner_config.yaml (optional) - Graph planner configuration

Example directory structure:

robot_configurations/
└── franka/
    ├── robot.urdf
    ├── robot.xrdf
    ├── rmp_flow.yaml
    ├── graph_based_motion_planner_config.yaml
    └── meshes/
        ├── panda_link0.stl
        ├── panda_link1.stl
        └── ...

The URDF file describes the robot’s kinematic structure, joint limits, and link geometries. The XRDF file provides cuMotion-specific information such as collision-sphere geometries and self-collision settings.

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#

The directory attribute of the CumotionRobot object is useful for loading related configuration files. For example, RMPflow controllers can load their configuration from the robot directory:

    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,
    )

Similarly, graph-based motion planners can load their configuration using the same pattern:

    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,
    )

Summary#

This tutorial demonstrated:

  1. Loading Supported Robots: Using load_cumotion_supported_robot() to load pre-configured robots

  2. Custom Robots: Using load_cumotion_robot() to load robots from your own URDF/XRDF files

  3. Directory Structure: Understanding the required files and optional configuration files

  4. Using Configurations: Integrating robot configurations with cuMotion components

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

Robot configurations 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#