6.1. Lula Robot Description Editor
6.1.1. Learning Objectives
This tutorial shows how to use the Robot Description Editor UI tool to generate a required robot_description.yaml config file for all Lula algorithms. This tutorial describes the motivation for needing specific config files for Lula algorithms, and goes over the minimal set of data that needs to be written into a robot_description.yaml file for each available Lula algorithm.
This tutorial then shows how to use the Robot Description Editor UI tool to automatically write the appropriate information into a robot_description.yaml file, or edit a pre-existing robot_description.yaml file.
6.1.2. What is in a Robot Description File?
A Robot Description File is the main configuration file that is required along with the robot URDF to use all Lula algorithms. Creating a robot_description.yaml file is the first and most time-consuming step that a user must take when hoping to use Lula algorithms on a new robot.
6.1.2.1. Defining the Robot C-Space: Active and Fixed Joints
A key aspect of a Robot Description File is defining the robot c-space. For example, suppose we have a 7 DOF robot manipulator such as the Franka arm with an attached 2 DOF gripper. In the robot URDF file, there are a total of 9 non-fixed joints that could be considered controllable. However, the set of Lula algorithms (RMPflow, Lula RRT, Lula Trajectory Generator, etc.) are designed to move the robot into position but not to control the end effector. In a typical use-case, we might use RmpFlow to move the robot end effector into position above a block and then separately open and close the gripper.
A Robot Description File must distinguish each joint as either an “Active Joint” or a “Fixed Joint”. Anything marked as an “Active Joint” will be directly controlled, while anything marked as a “Fixed Joint” will be assumed to be fixed from the perspective of Lula algorithms. In the case of using RmpFlow on the Franka robot, the seven joints in the Franka’s arm are marked as “Active Joints”, and the gripper joints are marked as “Fixed Joints”.
In the Robot Description Editor, positions must be selected for both active and fixed joints. The positions of “Active Joints” are taken to be default positions. When RmpFlow is not given any target, it will move the robot towards the default position. And when it is given a target, it will use the default positions of the “Active Joints” to resolve null-space behavior; i.e. there are many ways for a 7 DOF robot to reach a single target, and RmpFlow will be biased towards a c-space position that is close to the default position.
There is no way of telling RmpFlow that the “Fixed Joints” are in any other position than the position written into the Robot Description File, and as such it is important to choose a reasonable value for the positions of fixed joints. In the Franka example, the gripper joint positions are given a fixed value corresponding to the gripper being open, as this best facilitates RmpFlow avoiding collisions between the gripper and obstacles no matter the gripper state (when closed, the gripper fingers are inside the convex hull of an open gripper).
6.1.2.2. Collision Spheres
Lula algorithms use a custom configuration in order to perform efficient collision avoidance. For a given robot, a set of collision spheres must be defined that roughly cover the surface of the robot. Lula algorithms will not allow any collision sphere defined in the Robot Description File to intersect any obstacle in the USD world. The Robot Description Editor provides multiple tools that allow the user to quickly define a complete set of collision spheres for any robot.
6.1.3. What Information is Required for Each Lula Algorithm?
Different Lula algorithms require different levels of completion of the Robot Description File. Every algorithm requires the user to appropriately choose active and fixed joints. However, collision spheres are only necessary to configure when using algorithms that perform collision avoidance with external obstacles. For example, the Lula Kinematics Solver is purely kinematic, and it does not interact with the outside world. As such, the collision sphere representation may be ommitted from the Robot Description File. RMPflow can function without any collision spheres being defined, but it will not be able to avoid obstacles.
6.1.4. Using the Robot Description Editor
This section of the tutorial includes brief text descriptions of the different panels in the Robot Description Editor UI tool, and a more detailed walkthrough is presented in video form to capture the interactive nature of the extension. If the generated robot description file appears to be causing undesirable results, it will be worth the time to watch the tutorial videos thoroughly to understand each field.
The Robot Description Editor is not compatible with Instanceable Assets, but a Robot Description File generated for an asset that was later converted to an instanceable asset will still work on the instanceable asset.
6.1.4.1. Getting Started
The Robot Description Editor can be found from the tool bar under Isaac Utils -> Lula Robot Description Editor. To get started, open the USD file of your chosen robot and click the “Play Button” on the left-hand side.
In the Selection Panel, once a robot is on the stage and the stage is playing, a drop-down menu will populate where your robot can be selected. Select the prim path of your robot Articulation from the “Select Articulation” field. Once this is done, another drop-down labeled “Select Link” will populate with the names of each link in our robot. This will be needed later as we use the tool.
We have done everything we need to do to start making our Robot Description File. Other panels will populate with robot-specific information, and we can move on to the Command Panel.
6.1.4.2. Command Panel
Once the robot Articulation has been selected from the “Select Articulation” menu, the Command Panel will expand and populate. The Command Panel requires the user to supply critical information for the Robot Description File to be properly generated. Watch the included video or carefully read Defining the Robot C-Space: Active and Fixed Joints.
In the Command Panel select a “Joint Position” and a “Joint Status” for each joint in the robot Articulation. Keep in mind the following:
Joints are marked as “Active Joints” if and only if the user intends for that joint to be directly controlled by Lula algorithms. Typically this involves marking each joint in the robot arm as active while leaving the joints in the manipulator attached to the arm as “Fixed Joints”. At least one joints must be marked as an “Active Joint”
The joint positions of “Fixed Joints” can matter, depending on the use-case and are worth some thought. The positions of “Fixed Joints” will be assumed by Lula to be truly fixed; i.e. there is no way override the positions at runtime.
The positions of “Active Joints” are considered to be the default configuration of the robot. This default configuration is used by a subset of Lula algorithms, with the main case being RmpFlow. A default configuration should be chosen that is in front of the robot (along the +X axis by convention in Isaac Sim) and is not near any joint limits.
6.1.4.3. Adding Collision Spheres
Collision spheres are added to the robot one link at a time. The user may select the link of interest from the “Select Link” field of the Selection Panel. The Link Sphere Editor panel contains functions that are within the scope of the selected link such as adding spheres, scaling spheres, and clearing spheres only within the link. The Editor Tools panel contains functions that are outside the scope of the selected link such as “Undo” and “Redo” buttons, changing the color of collision spheres, and toggling the visibility of the robot.
When spheres are added to a link, they are added to the USD stage as a prim that is nested under the selected link. The user may click on and modify any sphere by moving it around on the stage or changing its radius. The position of a sphere relative to the origin of the link that contains it is written as a fixed value into the Robot Description File.
There are three main ways to add a sphere to a link:
Add Sphere: Add a single sphere with a specified relative translation from the origin of the link. This translation can be easily changed after creation by modifying the sphere prim.
Connect Spheres: Select two spheres that have already been created under a link and connect them with a specified number of spheres in between. The locations and sizes of the connecting spheres are interpolated to best fill the volume of the cone-section defined by the two spheres being connected.
Generate Spheres: Select a mesh that defines the volume of the link, and automatically generate a set of N spheres that best fill the volume of the mesh. When a number of generated spheres is specified, a preview of the generated spheres will automatically appear, which can be finalized by clicking the “Generate Spheres” button. Any visible robot must will at least one mesh defining its link. When there are more than one mesh, it is best to try each of them to figure out the minimal set of spheres that can be generated for good coverage. It is typically better to “Connect Spheres” by hand for links with simple cylindrical shapes.
6.1.4.4. Saving Robot Description File
After completing the Command Panel and creating a collision sphere representation of the robot, the Robot Description File may be exported easily by using the Export Robot Description File panel. A file path to your local machine must be selected with a file name ending in .yaml. The “Save” button will become enabled when a valid file path has been typed.
6.1.4.5. Loading Robot Description File
A pre-existing Robot Description File may be imported into the editor by using the Import Robot Description File panel. This will overwrite all information in the Robot Description Editor.
6.1.5. Summary
This tutorial shows how to use the Lula Robot Description Editor to efficiently generate a Lula Robot Description File. This covers most or all of the configuration information required for different Lula algorithms!
6.1.5.1. Further Learning
Now that we’ve seen how to generate Robot Description Files, it’s time to get our robot moving around with Lula algorithms. See: