Kinematics and mass

A robot’s kinematic model tells Motorcortex how the segments of the arm are connected, so it can turn joint angles into a tool pose and back. Add the mass of each segment, and it also calculates the torque that gravity puts on every joint. Both are in mech/mech-parameters.xml in the configuration package, or the file that Path › Mechanism in config.json points to.

This is the outline of the file, with the step of this page that fills in each part:

<robot name="Cobot" numberDoFs="6" ik_type="anthropomorphic2">   <!-- 1. the solver -->
    <segment number="1">                                            <!-- 2. one per joint -->
        <tippose><position x="0" y="0" z="0.147"/></tippose>
        <jointaxis>rot_z</jointaxis>
        <mass>...</mass> <cog>...</cog> <inertia>...</inertia>      <!-- 4. optional -->
    </segment>
    <!-- segments 2 to 6 -->
    <tool name="tool">...</tool>                                    <!-- 3. the tool point -->
</robot>

Work through it in this order; click a step to jump to it.

Choose the solver

The solver turns a tool pose into joint angles. It is set on the root element, together with the robot’s name and number of axes:

Pick the solver that fits your arm. An analytical solver is exact and fast, so use one when your robot fits it:

In detail:

The two six-axis layouts, each with its axes drawn in:

anthropomorphic

Axes 4, 5 and 6 meet in one point: the wrist.

anthropomorphic2

Axes 2, 3 and 4 are parallel. The wrist is offset sideways.

A parallel mechanism, such as a delta robot, uses a .json file and the parallel solver. See the mech-parameters.xml reference.

Describe the segments

Picture the robot with all joint angles at 0. For anthropomorphic2 that is the arm stretched straight up. Each segment is one step up the arm, from its own joint to the next one:

Each <segment number="N"> has two parts:

• <tippose> › <position>: where the next joint sits, in m, measured from this segment’s joint. For the last segment, that is the flange.
• <jointaxis>: the axis this segment’s joint turns around or slides along: rot_x, rot_y, rot_z, tran_x, tran_y or tran_z. Any other text, trans_x for example, silently makes a fixed joint.

An analytical solver reads only some position values of each segment:

Example: from DH parameters

Robot data sheets usually give the geometry as DH parameters. This cobot fits anthropomorphic2:

Each length becomes the one tip-pose value that anthropomorphic2 reads. The DH signs of a2 and a3 do not carry over: in the zero pose the arm points up, so those lengths are positive z.

<?xml version="1.0"?>
<robot name="Cobot" numberDoFs="6" ik_type="anthropomorphic2">
    <segment number="1">
        <tippose><position x="0.0" y="0.0" z="0.147"/></tippose>
        <jointaxis>rot_z</jointaxis>
    </segment>
    <segment number="2">
        <tippose><position x="0.0" y="0.0" z="0.427"/></tippose>
        <jointaxis>rot_y</jointaxis>
    </segment>
    <segment number="3">
        <tippose><position x="0.0" y="0.0" z="0.357"/></tippose>
        <jointaxis>rot_y</jointaxis>
    </segment>
    <segment number="4">
        <tippose><position x="0.0" y="0.141" z="0.0"/></tippose>
        <jointaxis>rot_y</jointaxis>
    </segment>
    <segment number="5">
        <tippose><position x="0.0" y="0.0" z="0.116"/></tippose>
        <jointaxis>rot_z</jointaxis>
    </segment>
    <segment number="6">
        <tippose><position x="0.0" y="0.1045" z="0.0"/></tippose>
        <jointaxis>rot_y</jointaxis>
    </segment>
    <tool name="tool">
        <tippose><position x="0" y="0" z="0"/></tippose>
    </tool>
</robot>

Set the tool point

The <tool> element places the tool point, seen from the flange. Unlike a segment, its <orientation> is used too, as a, b and c in rad around Z, Y and X:

<tool name="gripper">
    <tippose>
        <position x="0" y="0" z="0.12"/>
        <orientation a="0" b="0" c="0"/>
    </tippose>
</tool>

The <basepose> and <tool-offset> elements of older files are ignored. Set where the robot stands, and an extra tool offset, as in Frames and tool offset.

Add mass and inertia

You can move the robot without this step, but the model’s torques under root/ManipulatorControl/idJointTorque/ depend on it, and three features use them:

With every mass at 0 there is no error: all model torques are simply 0, so there is no gravity compensation and a collision detector compares against zero.

Add these to each segment, and to the tool if it carries weight:

• Count each part once. The output shaft of a gearbox belongs to the segment it drives; the rest of the gearbox and the motor belong to the segment before it.
• Use the Motorcortex frame. Data sheets and CAD often give these values in their own frame. Turn them into x forward, y left, z up, with the robot in its zero pose.

<segment number="1">
    <tippose><position x="0.0" y="0.0" z="0.147"/></tippose>
    <jointaxis>rot_z</jointaxis>
    <mass>5.096092</mass>
    <cog><position x="0.00004" y="0.01290" z="-0.01726"/></cog>
    <inertia>
        <Ixx>0.0127270</Ixx> <Ixy>0</Ixy> <Ixz>0</Ixz>
        <Iyx>0</Iyx> <Iyy>0.0096427</Iyy> <Iyz>0</Iyz>
        <Izx>0</Izx> <Izy>0</Izy> <Izz>0.0119825</Izz>
    </inertia>
</segment>

Apply your changes

The file is not the only place these values live. control.xml can hold them too, and it wins:

Every save of the parameter tree, including Save Settings in the robot GUI, writes the segment and tool values into control.xml. From then on, a change in mech-parameters.xml has no effect until you remove those lines again. So how you apply a change depends on what you changed:

Change values live

Each segment is under root/ManipulatorControl/mechanism/segmentN/, the tool under mechanism/tool/:

The model is rebuilt as soon as you write a value. Save the parameter tree to keep it; the values then go into control.xml. Copy them into mech-parameters.xml too, so the file stays a correct description of the robot.

Change the solver, axes or joint axes

These are read only from the file:

1. Edit mech-parameters.xml.
2. Open control.xml and delete every line whose path starts with root/ManipulatorControl/mechanism/segment or root/ManipulatorControl/mechanism/tool. Keep the mechanism/frames/ lines: the base and tool offset are not in the file.

   

3. Deploy the configuration.
4. Check root/ManipulatorControl/mechanism/info/: ikType and numJoints must match the file, and the segmentN/tippose values must match your segments.

Check the model

1. In simulation mode, jog the robot in joint mode to a few poses, and compare root/ManipulatorControl/manipulatorToolPoseActual with the pose you expect.
2. Jog in Cartesian mode: the tool must move along the axis you jog, without jumps.
3. On the real robot, measure the tool point in a few poses and compare again.