LinkageDesigner is an add-in package for virtual prototyping linkages. It is designed to analyze, synthesize and simulate linkages with serial chain, tree and graph structure. Using the symbolic calculation capabilities of *Mathematica* LinkageDesigner supports fully parametrized linkage definition and analysis too.

Linkages are modelled as multibody systems that build up from a set of constarined rigid bodies. Rigid bodies are often referred as *links.* Constraints between the links restricts their relative movements. These constraints are referred as *joints or kinematic pairs*.

The basic definition of multibody kinematics and dynamics is introduced in this tutorial, but by no means substitute to a standard text book of the topic.

In[1]:= |

In order to analyse mechanisms in *LinkageDesigner* they have to be *digitally modelled -* equivalently build the mathematical model of the mechanism. This mathematical model is stored in an internal database. This database is implemented as a new data type called LinkageData.

LinkageData | is a new data type that represents the database of the linkage |

LinkageData can be considered as a small relational database that stores all the relevant information of linkages. LinkageData consist of a list *records. *Every record comply to a simple template {id, data}, where id is string record identifiers and data is a List.

Beside other information LinkageData stores the kinematic graph of the linkage. The edges of this graph represents the *kinematic pair*s, while the vertexes correspond to the *links* of the linkage. From kinematic point of view the links are specified with body attached frames, called **L**ocal **L**ink **R**eference **F**rames (LLRF). The *kinematic pair*s are represented with parameterized homogeneous transformation matrices that constraints the relative motion of the two links.

Record Identifier | Description |

$LDMechanismID | defines the name of the linkage and other linkage instance specific informations (units, Workbech name, etc). |

$LDDrivingVariables | list of rules representing the driving variables of the linkage together with their substitutional values. |

$LDSimpleParameters | list of rules representing the simple parameters of the linkage together with their substitutional values. |

$LDStructure | list of records defininig the kinematic pairs of the linkage. |

$LDLowOrderJoint | list of records about the low order kinematic pairs ( type, joint marker, etc). |

$LDLinkGeometry | stores the geometric representation of the links. |

$LDDerivedParametersA | list of explicitly derived parameters. (p is explicitly derived if it can be expressed as p = f[q1, q2, ...]. |

$LDDerivedParametersB | list of implicitly derived parameters. (p is implicitly derived if it can be expressed as the solution of f[p, q1, q2, ...]= 0). |

Most important record identifiers of LinkageData.

Every linkage has one separate and independent LinkageData object, which can be assigned to variables, merged with other LinkageData objects, renamed etc. Building a linkage in LinkageDesigner is equivalent with creating and populating the LinkageData object of the linkage.

In this quick tour a simple planar linkage called four-bar mechanism is built. The schematic figure of this mechanism is shown below.

The first step in defining the four-bar mechanism is to create a new LinkageData object with the help of the CreateLinkage function.

CreateLinkage[str] | creates an empty LinkageData object with str as the name of the linkage. |

ViewLDTree[linkage] | displays the LinkageData of linkage in a tree form that permits the user to browse interactively the database. |

Create a new LinkageData object.

Create a new LinkageData

In[5]:= |

Out[5]= |

In[6]:= |

Out[6]= |

CreateLinkage by default inserts two rigid bodies, the Ground and the Workbench links and a placement transformation between them. The LLRF of Ground link represent the global reference of the linkage. The Workbench link is the base link, or the local ground of the linkage. By default the LLRF of these links are super-positioned. One can imagine that the linkage is built on a workbench, which can be placed anywhere in the "world" by changing the placement transformation between the Workbench and the Ground links.

The string identifiers are stored in a so called full name form. A full name is made up of the name of the linkage (like the surname) and the entity name (as the given name). For example the name of the linkage is "fourBar" and the entity name of the link is "link0" then the full name of this link will be "fourBar@link0".

CreateLinkage defines automatically a name of the two base links. To change the default name of the Ground and Workbench links the GroundName and WorkbenchName options of CreateLinkage function should be used.

The string identifiers are stored in a so called full name form. A full name is made up of the name of the linkage (like the surname) and the entity name (as the given name). For example the name of the linkage is "fourBar" and the entity name of the link is "link0" then the full name of this link will be "fourBar@link0".

CreateLinkage defines automatically a name of the two base links. To change the default name of the Ground and Workbench links the GroundName and WorkbenchName options of CreateLinkage function should be used.

option name | default value | |

GroundName | Ground | GroundName defines the name of the ground link. |

WorkbenchName | Workbench | WorkbenchName specifies the name of the workbench link. |

SimpleParameters | {} | SimpleParameters specifies the intial set of simple parameters that can be used in the linkage defintion. |

Selected options fro CreateLinkage.

LinkageData can be populated as the kinematic pairs (or joints) of the mechanism are defined. One kinematic pair inserts two links and the constraints, which restricts the movements of this two links. The basic tool for creating kinematic pairs is the DefineKinematicPair function.

DefineKinematicPair[linkage,type,{vars},{link1,mx1},{link2,mx2}] | inserts a kinematic pair between link1 and link2 into linkage. The joint markers are placed with mx1 and mx2 homogeneous matrix w.r.t LLRF of link1 and link2 . |

DefineKinematicPair[linkage,type,{vars},{link1,LLRF1},{link2,LLRF2},mx] | inserts a kinematic pair between link1 and link2 into linkage. The local reference frames of the links LLRF1, LLRF2 and the placement of the joint marker mx are specified w.r.t global reference frame. |

DefineKinematicPair[linkage,type,{vars},{link1,link2},{a,d,,}] | inserts a kinematic pair definition to linkage between link1 and link2 links using the {a, d, , } Denavit-Hartenberg parameters. |

Insert a kinematic pair definition into LinkageData.

DefineKinematicPair function might look complicated to use, therefore a number of joint macro function are defined. These joint macro functions ( R2, R3, T2, T3, S3, U3 etc ) are calculating the input arguments of the DefineKinematicPair function based on a much simpler input.

1. The Local Reference Frames of every links are defined with their z-axis perpendicular to the plane. This z-axis also coincides with the z -axis of the World Reference Frame.

R2[i->j,p_{1},p_{2}] | function defines the input arguments of a planar rotational joint definition between i and j links as the DefineKinematicPair function expects. |

T2[i->j,p_{1},p_{2}] | function defines a list of input arguments of a planar translational joint definition between i and j links as the DefineKinematicPair function expects. |

F2[i->j,p_{1},p_{2}] | function defines a list of input arguments of a planar fixed joint definition between i and j links as the DefineKinematicPair function expects |

Planar joint macros of DefineKinematicPair function.

Based on these assumption the planar rotational joint definition simplifies to specifying the center points of joints on the two links. The center point definition can be made with 0, 1 or 2 coordinates.

In[7]:= |

Out[7]= |

In[8]:= |

Out[8]= |

In[9]:= |

Out[9]= |

Using the joint macro functions the kinematic pairs can be defined and inserted into the LinkageData object using the DefineLinkage function. This function maps the output of the joint macro function to DefineKinematicPair function. Also it executes some other useful function such as DefLinkGeometryTo function that assigns simplified geometries to every links of the linkage.

Since the link geometries are defined by connecting the center points of the joint markers, therefore it is a good practice to add fixed joints to the significant points of the links, which is not used in other joint definitions.

DefineLinkage[str, ls] | creates a new linkage with str name and adds a list of kinematic pair definitions (ls). |

DefineLinkage[linkage, ls] | appends kinematic pair definitions (ls) to linkage. |

DefLinkGeometryTo[linkage,type] | assigns simplified geometries to every links of linkage. The geometries of the links are determined by the center points of the joint markers. |

In[10]:= |

Out[10]= |

The generated linkage is not yet a mechanism with closed kinematic graph, but a 3 degree of freedom planar manipulator. Linkages can be iteratively defined in LinkageDesigner, if the user prefer that way. It is possible to add a couple of kinematic pair to the LinkageData, than move the mechanism to another pose, visualize how it is look like and return to define additional kinematic pairs.

Rotational joint definition above specifies the joint variables with the JointVariable option. Joint variables are the so called generalized coordinates of the mechanism, whose functionality is determined by the type of the kinematic pair. In case of rotational joint, the joint variable represent the angle of the connected links.

If a linkage has open kinematic chain, than the joint variables of the kinematic pairs become the so called driving variables of the linkage. The driving variables are the independent kinematic variables that determines the mobility of the mechanism. By changing the value of any driving variable the mechanism moves into a new posture.

SetDrivingVariables[linkage,{var_{i}→x_{i}..}] | sets var_{i} driving variable of linkage to x_{i} and returns the resulted LinkageData |

SetDrivingVariablesTo[linkage,{var_{i}→x_{i}..}] | sett the var_{i} driving variable to x_{i} value and resets the resulted LinkageData to linkage. |

In[11]:= |

Out[11]= |

LinkageDesigner models every mechanism (planar or non-planar) as spatial mechanism. This implies that geometries that represent the links, must be defined as Graphics3D objects. Hoverer there are functions that can display planar mechanism in a plane as Graphics object. Linkage2D is one of these functions that can project the 3D geometries of the linkage onto the x-y plane and displays the linkage as a Graphics object.

Linkage3D[linkage,opts] | renders the geometries of the links in the current posture of the linkage. Returns a Graphics3D object. |

Linkage2D[linkage,opts] | project the Graphics3D representation of the linkage, rendered by Linkage3D function, into the x-y plane and returns a Graphics object. |

In[12]:= |

Out[12]= |

In[13]:= |

Out[13]= |

Beside rendering the mechanism, there are some other functions to visualize the LinkageData object of the mechanism. The two most important parsing functions of the LinkageData are ViewLDTree and ShowLinkageGraph. The first browses the LinkageData object in an interactive tree view, while the second displays the kinematic graph of the linkage.

ShowLinkageGraph[linkage] | displays the kinematic graph of the linkage. |

Display the kinematic graph of the linkage

In[14]:= |

Out[14]= |

In[15]:= |

Out[15]= |

To close the four-bar mechanism definition, the link3 link should be pinned down to link0. This will close the kinematic graph, because it will create a loop in the graph. The simplest way to define this rotational joint is to join D3 and D0 links that are rigidly connected to link3 and link0. If the DefineKinematicPairTo function is used the resulted kinematic pair will be automatically inserted into the input LinkageData.

In[16]:= |

Out[16]= |

The number of records in the LinkageData has increased from 7 to 8 after this kinematic pair definition. This follows form the fact the kinematic pair between D3 and D0 links create a loop in the kinematic graph, therefore it will decrease the mobility of the linkage.

DefineKinematicPair function will automatically calculate the non-redundant constraint equations imposed by the loop closing kinematic pair, and remove as many driving variables from $LDDrivingVariables record as the number of non-redundant constraint equations. The removed driving variables are expressed from the generated constraint equations, since they are not independent variables of the linkage any more. The constraint equations are inserted into the new $LDDerivedParametersB record of the LinkageData.

In[17]:= |

Out[17]= |

In[18]:= |

Out[18]= |

As a final step the four-bar linkage should be placed in a posture where the link0 inclined with angle with respect to the x-axis of the World Reference Coordinate system. Linkages can be placed into an arbitrary position and orientation if the transformation matrix between the Ground and Workbench links is changed.

PlaceLinkage function replaces this transformation matrix with the one specified in its argument. The placement transformation can contain parameters, provided that you have added these parameters to the LinkageData object. Since the symbol has already been added to the simple parameters of the linkage, it can be used to define the placement matrix.

PlaceLinkage[linkage,mx] | sets the transformation matrix between Ground and Workbench link to mx homogeneous matrix. |

MakeHomogenousMatrix[m,v] | creates a homogeneous transformation matrix from a 3 x 3 rotation matrix m and a 3 x 1 translation vector v. |

MakeHomogenousMatrix[m] | creates a homogeneous transformation matrix from a 3 x 3 rotation matrix m with a {0,0,0} translation vector. |

MakeHomogenousMatrix[ax,ang] | creates a homogeneous transformation matrix from a 3 x 3 rotation matrix that rotates with ang around ax vector with a {0,0,0} translation vector. |

In[19]:= |

Out[19]//MatrixForm= | |

In[20]:= |

Out[20]= |

In[21]:= |

Out[21]= |

Since the symbol has a substituted value of 15°, therefore the placed linkage should be rotated in such a way that link0 and x-axis of the reference coordinate frame has 15° angle.

In[22]:= |

Out[22]= |

This concludes the definition of the four-bar mechanism. The LinkageData contains all information that is required to analyze the four-bar mechanism digitally.

Linkages defined in LinkageDesigner can be saved for further usage. By saving a linkage the LinkageData is serialized and saved into a text file. Loading the linkages from text file build a new LinkageData object from the serialized data. This way linkages can be shared with other user without redefining them.

SaveLinkage | saves the linkage definition in a text file. |

LoadLinkage | loads the linkage definition from text file |

Save and load linkage definition.

In[23]:= |

Out[23]= |

In[25]:= |

Out[25]= |

In[26]:= |

Out[26]= |

Before we continue with the linkage analysis, the linkage definition, which was created in the previous chapter, can repeated using only one command. The new definition will be assigned to fourBar2 variable. The only difference of the two linkages is the generated link's geometry, because for the fourBar2 linkage Line type geometry primitives will be used.

In[27]:= |

Out[27]= |

In[28]:= |

Out[29]= |

In[30]:= |

In[31]:= |

Out[31]= |

It could also happen that the two linkages are displayed in a different pose. The difference is caused by the so called solution branch of the loop closing equation. The loop closing equation is a trigonometrical polynomial that implicitly determines the values of the so called loop variables. In the case of four-bar mechanism the 2 and 3 joint variables are selected as loop variables, when the 4th rotational joint is defined.

The values of these dependent variables are re-calculated every time the independent variables ($LDDrivingVariables, $LDSimpleParameters) are changed. The re-calculation is completed by calling the FindRoot function for the generated constraint equation (stored in the $LDDerivedParametersB record). The result of the FindRoot funtion call depends on the initial values, which is always set to the current value of the loop variables, so the result of the root finding might belongs to different solution branch.

To control the branch switching the user can use the ParameterInitialGuess option of SetDrivingVariables and SetSimpleParameters function, or use the ShakeLinkage function that explicitly switch solution branches without changing the values of the independent variables

option name | default value | |

ParameterInitialGuess | Automatic | specifies the intial values used in root finding. |

JointLimitCheck | False | switches on/off the limit check of driving variables |

AccuracyGoal | Automatic | specifies how many effective digits of accuracy should be sought in the final results during root finding |

MaxIterations | 100 | specifies the maximum number of iterations that should be tried during root finding. |

PrecisionGoal | Automatic | specifies how many effective digits of precision should be sought in the final resul during root findingt |

Selected options SetDrivingVariables and SetSimpleParameters.

ShakeLinkage[linkage] | shakes linkage to jump to another solution branch of the loop closing equations. The function returns the linkage in a new posture if it is found. |

Jump linkage to other solution branch using ParameterInitialGuess option

In[32]:= |

Out[32]= |

In[33]:= |

Out[33]= |

The explicit values of the loop variables could be listed using the GetLinkageRules function, or directly list the $LDDerivedParametersB record.

GetLinkageRules[linkage,opts] | returns a list of parameter rules of the linkage. |

GetLinkageRules[linkage,{recID1,recID2,...}] | returns a list of parameter rules that are filtered with (recIDi). |

GetLinkageRules[linkage,!{recID1,recID2,...}] | returns all parameter rules, that are complementer with (recIDi). |

Get actual values of the parameters and variables.

In[34]:= |

Out[34]= |

The most often used analysis tool is the linkage animation that helps the designer to check the motion of the mechanism. Animation can be used as a simple quantitative check for such problems like reach-ability, workspace analysis or other tests. LinkageDesigner provide a number of tool to support the linkage animation in either 2D, 3D or even in VRML97/X3D worlds.

AnimateLinkage2D[linkage,drvls] | function projects the frames of AnimateLinkage3D onto the X-Y plane. The resulted projections are rendered as Graphics primitives. The function takes the same options as AnimateLinkage3D. |

AnimateLinkage3D[linkage,ls] | generates a list animation of linkage while the linkage interpolates through the poses corresponding to the driving variable list ls |

WriteVRMLAnimation[linkage, filename,ls] | generates a list animation of linkage while the linkage interpolates through the poses corresponding to the driving variable list ls, and exports it to the filename WRL file. |

option name | default value | |

JointMarkers | None | JointMarkers is an option for Linkage3D and AnimateLinkage3D function, that specifies the joint markers tob shown. |

Resolution | 10 | Resolution is an option for GetLinkageRules function,that specifies the number of interpolation points between two base point. |

LinkGeometry | All | LinkGeometry is an option for Linkage3D and AnimateLinkage3D function, that defines whose geometry should be displayed. |

LinkMarkers | None | LinkMarkers is an option for Linkage3D and AnimateLinkage3D function, that defines the name of the links,whose LLRFs should be displayed. |

TracePoints | None | TracePoints is an option for AnimateLinkage3D function, that specifies the points of the linkage, of that trace should be displayed. |

TraceStyle | Automatic | TraceStyle is an option for AnimateLinkage3D function, that defines the specifies style of the trace graphics. |

Animations are generated as a list of postures of the linkage. The postures - or frames of the animations- are calculated by incrementing the values of the driving variables from the start to finishing value. The number of frames generated between two driving variable's base point of the linkage is determined by the Resolution option. The Resolution is equal to 10 by default.

- Internal point generation for Resolution →10

In[35]:= |

Out[35]= |

In[36]:= |

Out[36]= |

Since the linkage is defined parametrically, the length of the links can be easily changed by simply changing the substitution value of the simple parameters. The trace point or the movement of the resulted linkage can be investigated with the help of the animation.

In the following example some of the dimensional parameter of the linkage is changed and the resulted linkage is animated.

SetSimpleParameters[linkage,{var_{i}→x_{i}..}] | sets var_{i} simple parameter to x_{i} and returns the resulted LinkageData object. |

SetSimpleParameters[linkage,{x_{1},x_{2},..}] | sets the ith simple parameters' value to x_{i} and returns the resulted LinkageData. |

Change the dimensional parameters.

In[37]:= |

Out[37]= |

In[38]:= |

Out[38]= |

In[39]:= |

Out[39]= |

Trace points of the linkages define planar curves. The parametric definition of the curve could be obtained from the mechanism by simply measure the selected points with respect to the reference frame. Measurements can be made on any linkages using the MeasureDistance function.

MeasureDistance[linkage,p_{1},p_{2}] | calculates the vector from p1 to p2, where p1 and p2 are points defined on the linkage. p1 and p2 points are specified on a link in form as {linkName,coord}. coord is a vector relative to the LLRF of linkName. The reference coordinate system of the measurement is specified with the ReferenceFrame option. |

MeasureDistance[linkage,p_{2}] | calculates the position vector of p2 point from the origin of the LLRF of the Ground's link. |

option name | default value | |

ReferenceFrame | Automatic | ReferenceFrame is an option for GetLLRFMatrix function, that specifies the name of the refrence link. The LLRF of this link is the reference coordinate system. |

SubstituteParameters | False | SubstituteParameters is an option for GetLLRFMatrix and GetLinkageRules functions, that specifies, whether the numerical values of the linkage parameters should be substitued into the result or not. |

SubstitutionList | None | SubstitutionList is an option for GetLLRFMatrix function that defines the substitution list for the calculation |

Measurements are common analysis tool, because it is capable of not only measuring numerical distances, but parameterical distances too. Parametric distance measurement might contain the independent variables - $LDDrivingVariables, $LDSimpleParameters - or dependent variables - $LDDerivedParametersA, $LDDerivedParametersB - records. The parametric expressions resulted from the measurement could be further processed to set up constraint equations or other kind of design equations.

In[40]:= |

Out[40]= |

In[41]:= |

Out[41]= |

The resulted expression looks simple, but keep in mind that 2 variable is not independent, but an implicitly derived variable. In order to calculate the 2 value, the loop closing equation should be solved. Linear interpolation of derived variables can be obtained using the GetLinkageRules function.

GetLinkageRules[linkage,drvls] | returns a two dimensional list of interpolated parameters. The interpolation is specified with the drvls list of driving variable. |

Get interpolated values of linkage parameters.

In[42]:= |

Out[42]= |

The calculated interpolated parameters is a two dimensional list. The list is defined by changing the value of the independent driving variable (1) and calculating the values of all other independent and dependent variables. This way the list stored in sub contains all relevant information to display the trace point of one body fixed point such as the point defined in dist.

Display the trace curve for X= 3 point

In[43]:= |

Out[43]= |

Display the trace curve with higher resolution and changing the position of trace point from {-10, 10}

In[44]:= |

Out[44]= |

Angle measurements are also often needed for the analysis of linkages. Angel measurements could be easily obtained using MeasureDistance function. In case the two measured points belong to the same link, the norm of the measured vector will not change if the value of the driving variables are changing. This follows from the fact that links are assumed to be rigid bodies. The angle of the measured vector and a reference vector could be calculated with ArcTan function.

In[45]:= |

Out[45]= |

It is easy to see that the angle between the measured vector and the x-axis ( {1, 0, 0} vector) of the reference frame is +1+2+3. This angle is often called the output angle of the four-bar mechanism.

In[46]:= |

Out[46]= |