• The kinematics/dynamics model of an articulated robot is the primary input of RobCoGen
• This page documents the meta-model assumed by RobCoGen, and the procedure to make a conforming model with the Kinematics-DSL (or "KinDSL", where DSL stands for Domain Specific Language). The KinDSL is a text format with a simple syntax tailored for the job.
• RobCoGen also accepts robot models in the URDF format. The URDF essentially conforms to the same meta-model

KinDSL overview

The logical structure of a file ("document", or "model") is the following:

Robot <name>

  <link 0 spec> // the robot base
  <link 1 spec>
  //...
  <link n spec>

  <joint 1 spec>
  //...
  <joint n spec>

Any link block contains an id, the inertia properties, and a possibly empty list of children links. The geometrical constants of the robot are encoded in the joint parameters, which are extensively explained below.

The format allows to model any kinematic tree, a mechanism where each rigid body has one and only one parent (except the base), and may have zero or multiple children.

Example

Here is the model for my "Fancy" robot, the example included in the distribution of RobCoGen:

Geometry

This section walks you through the procedure required to model an articulated mechanism with the Kinematics-DSL. It explains how to place the coordinate frames and how to measure lengths and angles. The convention about the placement of reference frames (or "coordinate frames") is definitely the aspect that can be most confusing, and that is typically not documented enough. I tried to avoid such a mistake.

Terminology first:

• A kinematic-pair is a pair of links connected by a joint

• The links of a pair, in relation with the joint, are called predecessor and successor.

• The links of a pair, in relation with each other, are called parent and child.

• We say that a parent/predecessor/joint supports the child/joint/successor; the opposite relation is supported by.

Basic modeling

The following applies to kinematic trees (no loops), with one-dof joints only.

1. Ordering. Choose the topological ordering for your robot: which link is the base, which are the parents/children, etc. This choice induces a total ordering with respect to the relation supports/supported by
2. Zero configuration. Choose the configuration of the robot you wish to identify with the zero joint-status vector; consider the robot assembled, but neglect joint limits. That is, the zero configuration must comply with the holonomic constraints of the real joints, but it need not respect the range of motion; it might very well be unreachable by the actual robot.¹ Note that no reference frame was mentioned yet.
3. Link-frames. Consider each individual link (in isolation), and attach a Cartesian frame to it. The Z axis must lie along the axis of the supporting joint (e.g. the Z axis of a forearm is the elbow axis), but you are otherwise free to choose the pose.² The link-frame of the base link of the robot can be placed anywhere.
More
The link-frame is the reference used for any quantity related to the link itself (e.g. the center of mass, the pose of other attached frames, the location of the joint axis, etc.).
4. Joint-frames. Consider the robot assembled, freezed in the zero configuration. For each joint of the robot, attach a new frame onto its predecessor, in the same pose of the frame of its successor (i.e. the two frames coincide). This is the joint-frame.
5. Geometrical properties. The pose of any joint-frame relative to the predecessor-frame is a geometrical constant of the robot. This pose is represented in the joint sections of a Kinematics-DSL model.

Example

Let's consider a simple kinematic pair, as the extension to a general tree would simply require to reiterate the same steps. This screenshot shows the links and the ideal joint axes (in red):

The corresponding section of a model would look like this:

// ...

link Blue {
    id = <i>
    inertia_properties {
        // ...
    }
    children {
        Green via TheJoint
    }
}

link Green {
    id = <i+1>
    inertia_properties {
        // ...
    }
    children { }
}

r_joint TheJoint { // 'r_' stands for revolute
    ref_frame {
        // ...
    }
}

1. Ordering. We choose the blue link to be the parent. Therefore it is the predecessor of the joint between the two links.
2. Zero configuration. The zero configuration is an entirely free choice, pick an intuitive one in the context of your application. Here are two examples:

   

3. Link-frames. The figures below illustrate a couple of examples: the Z axis always lies on the joint axis, but the frame is otherwise free to "move"

   

   The Z axis could also be pointing in the opposite versus; the right hand rule on the Z axis determines the direction of rotation which corresponds to an increase/decrease of the joint status (choose the versus of Z to fix the preferred convention).

   Also, note that all combinations between the previous and these screenshots are possible, i.e., the choice of the zero configuration is independent of the choice of link frames.

4. Joint frames. At this point, the zero configuration and the link frames have been chosen. The joint frame coincides with the successor frame, when in the zero configuration:

   

   There is no need for the origin to coincide with a material point of the link, similarly as for the link frame.
5. Geometrical properties. The relative pose of the red frame with respect to the blue frame is a constant that must be included in the robot model. The previous example would correspond to something like this:

   r_joint TheJoint {
       ref_frame {
           translation = (... , 0.0, ...)  // some translation along X and Z
           rotation    = (0.0, ..., 0.0)   // rotation Y
       }
   }
   

   Where the dots represent a non-zero value. The complete specification of the format for the joint frame is in the next section.

Pose of the joint frame

The ref_frame block within a joint block defines the relative pose of the joint frame with respect to the predecessor frame (which is a link frame). The pose is represented with a translation vector and with three Euler angles, representing three successive, intrinsic rotations about the X, Y and Z axis. The rotations are applied after the translation. Distances are in meters, angles in radians.

For instance, the frame of the second joint of Fancy (see above) is modeled with this text:

p_joint jB {
    ref_frame {
        translation = (1.0, 0.0, 0.0)
        rotation = (-PI/2.0, 0.0, 0.0)
    }
}

And the frames can be visualized like this:

Discussion

This is an optional section, with more information about the reference frames of the robot model.

Optional frames

More reference frames can be optionally added to any link of the model. Any frame must be defined with respect to the default frame of the link it is attached to. The format to specify the relative pose is the same as for the joint frames. The keyword for the subsection is frames. For example:

link link5 {
    // ...
    inertia_properties { /*...*/ }
    children { /* ... */ }

    frames {
        end_effector { // a custom name
            translation = ( /* ... */ )
            rotation    = ( /* ... */ )
        }
    }
}

Inertia

Any link block must specify the inertia properties of the rigid body: total mass (Kilograms), position of the center of mass (coordinates in meters), moments of inertia (Kilograms * meter squared). All the properties must be expressed in the link-frame.

link link1 {
    // ...
    inertia_properties {
        mass = 1.0
        CoM = (0.5, .0, .0)
        Ix=0.0025  Iy=0.33458  Iz=0.33458  Ixy=0.0  Ixz=0.0  Iyz=0.0
    }
    // ...
}

The example above is a model of a hollow, infinitely thin cylinder of unit length and unit mass, radius equal to 0.05. The link-frame has its origin in the center of one of the bases of the cylinder, with the x axis aligned with the height of the cylinder.

Definitions

Here are the definitions of all the six moments of inertia (discrete case):

Where $m$_i is the mass of the $i-th$ point of the body, while $x$_i, $y$_i, $z$_i are its coordinates. The 3 by 3 inertia tensor is defined as follows:

The robot model document requires $I$_x, $I$_y, $I$_z, $I$_xy, $I$_xz, $I$_yz, in any order, not the elements of the tensor (note the sign differences). Thus, if you happen to have the inertia tensor of the links (e.g. from the documentation of the robot), then you will have to switch the signs of the off-diagonal elements before filling in the robot model.

Numerical properties

RobCoGen and the KinDSL format distinguish three classes of numerical properties in a robot model: variables, parameters and constants. Conceptually, the distinction is based on the average changing frequency characteristic of each class: variables change in general continuously, parameters may change, with a lower frequency, constants do not change.³

In any robot model:

• the variables are all and only the joint status variables; the variables are implicit, they do not appear in the robot model
• any numerical property of a robot model can be represented with a parameter or a constant; this is a modeling choice of the user
• any symbolic identifier (such as mass_link1) appearing where a numerical property is expected, is considered a parameter. Square brackets can be optionally used to set the default value, as in mass_link1[1]
• all float literals (e.g. 1.5) and expressions involving PI (e.g. PI/2.0) are considered constants
• explicitly named constants may also be used in a model, with the syntax <myconstant=value>, where the angle brackets are required literally; replace myconstant with a valid identifier, and value with a float literal.

For example:

// [..]

p_joint jB {
    ref_frame {
        translation = (<mylength=1.0>, 0.0, 0.0)      // constant
        rotation    = (-PI/2.0, 0.0, 0.0)  // constant
    }
}
r_joint jC {
    ref_frame {
        translation = (0.0, 0.0, jC_tz)  // parameter
        rotation = (0.0, 0.0, 0.0)
    }
}

// [..]

Parametric models

If any parameter is included in a robot model, the model is said to be parametric. In this case, the model effectively represent a class of mechanisms, defined by topological equivalence.