mech/mech-parameters.xml

The mechanism file: the solver, segments, joint axes and tool that let Motorcortex turn joint angles into a tool pose and back.

  7 minute read  

The mechanism file describes your robot arm, segment by segment. Manipulator control reads it at start-up and uses it for every Cartesian motion: it turns joint angles into a tool pose, and its solver turns a tool pose back into joint angles.

└── mech
    └── mech-parameters.xml

The application reads the file named in config.json:

"Path": {
  "Mechanism": "mech/mech-parameters.xml"
}

The extension picks the format: an .xml file describes a serial arm, a .json file a parallel mechanism such as a delta robot. This page covers the .xml format. To describe your own robot step by step, follow Kinematics and mass.

How the chain is built

The tool pose is built from four parts in a row, from where the robot stands to the tool point. The segments and the tool come from this file. The base and the tool offset are parameters only. Click a part to go to its section.

Joint angles to tool point along this chain; the ik_type solver works back from tool point to joint angles parameter only from the file from the file parameter only Go to Frames and tool offset frames/base where it stands Go to Segments 1 2 3 4 5 6 <segment>: a joint and a tip pose Go to Tool <tool> flange to tool Go to Frames and tool offset frames/toolOffset changeable live tool point Go to Elements that are not used <basepose> in the file: not used Go to Elements that are not used <tool-offset> in the file: not used

All elements at a glance

Element or attribute What it sets Default
<robot name="…"> The robot’s name, shown in root/ManipulatorControl/mechanism/info/name empty
<robot numberDoFs="…"> The number of axes 0
<robot ik_type="…"> The solver. Older files use type, which is still read when ik_type is missing anthropomorphic
<robot fk_type="…"> The forward kinematics position_recursive
<robot id_type="…"> The inverse dynamics, which calculates joint torques from the masses newton_euler_recursive
<segment number="N"> One segment per axis, numbered from the base. Required
<tool name="…"> The tool, from the flange to the tool point all 0

An unknown ik_type, fk_type or id_type stops the application at start-up, with the name of the type in the log.

Solvers

The solver turns a tool pose into joint angles. An analytical solver is exact and fast, so use one when your robot fits it; an iterative solver works for any arm but is much slower.

ik_type For Joint axes, from the base
anthropomorphic Six axes with a spherical wrist: axes 4, 5 and 6 meet in one point rot_z, rot_y, rot_y, rot_z, rot_y, rot_z
anthropomorphic2 Six axes with axes 2, 3 and 4 parallel, like most cobots rot_z, rot_y, rot_y, rot_y, rot_z, rot_y
planar SCARA robots, with at least four axes
anthropomorphic_7dof, iterative_7dof, weighted_7dof Seven-axis arms
kdl_nrjl Any serial arm. Iterative, so much slower than the analytical solvers Any
passthrough No solving: the joints keep their reference positions, whatever tool pose you command

Segments

Picture the robot with all joint angles at 0. Each segment is one step up the arm, from its own joint to the next one.

<segment number="1">
    <tippose>
        <position x="0.08" y="0" z="0.15"/>
    </tippose>
    <jointaxis>rot_z</jointaxis>
</segment>
Element What it sets Default
number The segment’s place in the chain, from 1 at the base. Give each segment its own number: a duplicate is logged as an error 0
<tippose> › <position> Where the next joint sits, as x, y and z in m, seen from this segment’s joint. For the last segment that is the flange 0
<tippose> › <orientation> A rotation of the next joint’s frame, as a, b and c in rad. Leave it at 0 with an analytical solver 0
<jointaxis> The axis the joint turns around or slides along: rot_x, rot_y, rot_z, tran_x, tran_y or tran_z. Any other text makes a fixed joint fixed
<mass>, <cog>, <inertia> The segment’s mass, centre of gravity and inertia, for the joint torques. See Kinematics and mass 0

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

Segment anthropomorphic anthropomorphic2 planar
1 x, y, z z x
2 x, z z x
3 x, z z x
4 z y z
5 z z
6 z y

Tool

The <tool> element is a fixed last segment, from the flange to the tool point. Unlike with a segment, the solvers use its <orientation> too: a, b and c in rad.

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

It takes <mass>, <cog> and <inertia> too, for a tool that carries weight.

Elements that are not used

Older files have a <basepose> and a <tool-offset>. The application reads them, then overwrites them at start-up with the parameters under root/ManipulatorControl/mechanism/frames/. Set where the robot stands, and an extra tool offset, as in Frames and tool offset.

Where the values end up

Each segment appears in the parameter tree under root/ManipulatorControl/mechanism/segmentN/, the tool under mechanism/tool/, and the solver and number of axes under mechanism/info/. The segment and tool values are parameters: once you save them, control.xml holds them, and it is loaded after this file. A later change in the file then has no effect until you remove those lines from control.xml. Kinematics and mass shows how to apply each kind of change.

Examples

Two example files, one for each six-axis solver, each filled in from the picture of its robot.


Six axes with a spherical wrist

Axes 4, 5 and 6 meet in one point, the wrist. With all joints at 0 the arm stands straight up, and the joint axes from the base are rot_z, rot_y, rot_y, rot_z, rot_y, rot_z.

A six-axis arm with a spherical wrist in its zero pose, with its segment lengths marked: 0.15 and 0.08 for segment 1, then 0.385, 0.255, 0.09, 0.12 and 0.08 up to the tool

Each length in the picture is one tip-pose value in the file:

Segment Joint axis Tip pose (m)
1 rot_z x = 0.08, z = 0.15
2 rot_y z = 0.385
3 rot_y z = 0.255
4 rot_z z = 0.09
5 rot_y z = 0.12
6 rot_z 0
tool z = 0.08

Download: mcx-anthropomorphic-simple.xml

mcx-anthropomorphic-simple.xml 
<?xml version="1.0"?>
<robot name="MCX-6DOF" numberDoFs="6" ik_type="anthropomorphic">
    <segment number="1">
        <tippose>
            <position x="0.08" y="0.0" z="0.15"></position>
        </tippose>
        <jointaxis> rot_z </jointaxis>
    </segment>
    <segment number="2">
        <tippose>
            <position x="0.0" y="0.0" z="0.385"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <segment number="3">
        <tippose>
            <position x="0.0" y="0.0" z="0.255"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <segment number="4">
        <tippose>
            <position x="0.0" y="0.0" z="0.09"></position>
        </tippose>
        <jointaxis> rot_z </jointaxis>
    </segment>
    <segment number="5">
        <tippose>
            <position x="0.0" y="0.0" z="0.12"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <segment number="6">
        <tippose>
            <position x="0.0" y="0.0" z="0.0"></position>
        </tippose>
        <jointaxis> rot_z </jointaxis>
    </segment>
    <tool name="tool">
        <tippose>
            <position x="0.0" y="0.0" z="0.08"></position>
        </tippose>
    </tool>
</robot>

Six axes with three parallel axes

Axes 2, 3 and 4 are parallel, and the wrist is offset sideways, as on most cobots. With all joints at 0 the arm stands straight up, and the joint axes from the base are rot_z, rot_y, rot_y, rot_y, rot_z, rot_y.

A six-axis cobot with axes 2, 3 and 4 parallel in its zero pose, with its segment lengths marked: 0.147, 0.427, 0.357 and 0.116 up, and the sideways offsets 0.141 and 0.076

Each length in the picture is one tip-pose value in the file:

Segment Joint axis Tip pose (m)
1 rot_z z = 0.147
2 rot_y z = 0.427
3 rot_y z = 0.357
4 rot_y y = 0.141
5 rot_z z = 0.116
6 rot_y y = 0.076
tool 0

Download: mcx-anthropomorphic2-simple.xml

mcx-anthropomorphic2-simple.xml 
<?xml version="1.0"?>
<robot name="MCX-6DOF" numberDoFs="6" ik_type="anthropomorphic2">
    <segment number="1">
        <tippose>
            <position x="0.0" y="0.0" z="0.147"></position>
        </tippose>
        <jointaxis> rot_z </jointaxis>
    </segment>
    <segment number="2">
        <tippose>
            <position x="0.0" y="0.0" z="0.427"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <segment number="3">
        <tippose>
            <position x="0.0" y="0.0" z="0.357"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <segment number="4">
        <tippose>
            <position x="0.0" y="0.141" z="0.0"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <segment number="5">
        <tippose>
            <position x="0.0" y="0.0" z="0.116"></position>
        </tippose>
        <jointaxis> rot_z </jointaxis>
    </segment>
    <segment number="6">
        <tippose>
            <position x="0.0" y="0.076" z="0.0"></position>
        </tippose>
        <jointaxis> rot_y </jointaxis>
    </segment>
    <tool name="tool">
        <tippose>
            <position x="0.0" y="0.0" z="0.0"></position>
        </tippose>
    </tool>
</robot>