Serial-link robot class

A concrete class that represents a serial-link arm-type robot. The mechanism is described using Denavit-Hartenberg parameters, one set per joint.

plot | display graphical representation of robot |

teach | drive the graphical robot |

isspherical | test if robot has spherical wrist |

islimit | test if robot at joint limit |

isconfig | test robot joint configuration |

fkine | forward kinematics |

ikine6s | inverse kinematics for 6-axis spherical wrist revolute robot |

ikine | inverse kinematics using iterative numerical method |

ikine_sym | analytic inverse kinematics obtained symbolically |

jacob0 | Jacobian matrix in world frame |

jacobn | Jacobian matrix in tool frame |

maniplty | manipulability |

A | link transforms |

jtraj | a joint space trajectory |

accel | joint acceleration |

coriolis | Coriolis joint force |

dyn | show dynamic properties of links |

fdyn | joint motion |

friction | friction force |

gravload | gravity joint force |

inertia | joint inertia matrix |

nofriction | set friction parameters to zero |

rne | joint torque/force |

payload | add a payload in end-effector frame |

perturb | randomly perturb link dynamic parameters |

links | vector of Link objects (1xN) |

gravity | direction of gravity [gx gy gz] |

base | pose of robot's base (4x4 homog xform) |

tool | robot's tool transform, T6 to tool tip (4x4 homog xform) |

qlim | joint limits, [qmin qmax] (Nx2) |

offset | kinematic joint coordinate offsets (Nx1) |

name | name of robot, used for graphical display |

manuf | annotation, manufacturer's name |

comment | annotation, general comment |

plotopt | options for plot() method (cell array) |

fast | use mex version of RNE. Can only be set true if the mex file exists. Default is true. |

n | number of joints |

config | joint configuration string, eg. 'RRRRRR' |

mdh | kinematic convention boolean (0=DH, 1=MDH) |

theta | kinematic: joint angles (1xN) |

d | kinematic: link offsets (1xN) |

a | kinematic: link lengths (1xN) |

alpha | kinematic: link twists (1xN) |

- SerialLink is a reference object.
- SerialLink objects can be used in vectors and arrays

- Robotics, Vision & Control, Chaps 7-9, P. Corke, Springer 2011.
- Robot, Modeling & Control, M.Spong, S. Hutchinson & M. Vidyasagar, Wiley 2006.

Create a SerialLink robot object

**R** = SerialLink(**links**, **options**) is a robot object defined by a vector
of Link objects.

**R** = SerialLink(**dh**, **options**) is a robot object with kinematics defined
by the matrix **dh** which has one row per joint and each row is
[theta d a alpha] and joints are assumed revolute. An optional
fifth column sigma indicate revolute (sigma=0, default) or
prismatic (sigma=1).

**R** = SerialLink(**options**) is a null robot object with no links.

**R** = SerialLink([R1 R2 ...], **options**) concatenate robots, the base of
R2 is attached to the tip of R1.

**R** = SerialLink(**R1**, **options**) is a deep copy of the robot object **R1**,
with all the same properties.

'name', NAME | set robot name property to NAME |

'comment', COMMENT | set robot comment property to COMMENT |

'manufacturer', MANUF | set robot manufacturer property to MANUF |

'base', T | set base transformation matrix property to T |

'tool', T | set tool transformation matrix property to T |

'gravity', G | set gravity vector property to G |

'plotopt', P | set default options for .plot() to P |

'plotopt3d', P | set default options for .plot3d() to P |

'nofast' | don't use RNE MEX file |

Create a 2-link robot

L(1) = Link([ 0 0 a1 0], 'standard'); L(2) = Link([ 0 0 a2 0], 'standard'); twolink = SerialLink(L, 'name', 'two link');

Robot objects can be concatenated in two ways

R = R1 * R2; R = SerialLink([R1 R2]);

- SerialLink is a reference object, a subclass of Handle object.
- SerialLink objects can be used in vectors and arrays
- When robots are concatenated (either syntax) the intermediate base and tool transforms are removed since general constant transforms cannot be represented in Denavit-Hartenberg notation.

Link, Revolute, Prismatic, SerialLink.plot

Evaluate link transform matrices

**s** = R.A(**jlist**, **q**) is a homogeneous transform (4x4) that results
from chaining the link transform matrices given in the list JLIST,
and the joint variables are taken from the corresponding elements
of Q.

For example, the link transform for joint 4 is

robot.A(4, q)

and for joints 3 through 6 is

robot.A([3 4 5 6], q)

- base and tool transforms are not applied.
- JLIST and Q must be the same length.

Manipulator forward dynamics

**qdd** = R.accel(**q**, **qd**, **torque**) is a vector (Nx1) of joint accelerations that result
from applying the actuator force/torque to the manipulator robot in state **q** and **qd**.
If **q**, **qd**, **torque** are matrices (KxN) then **qdd** is a matrix (KxN) where each row
is the acceleration corresponding to the equivalent rows of **q**, **qd**, **torque**.

**qdd** = R.accel(**x**) as above but **x**=[**q**,**qd**,**torque**].

- Uses the method 1 of Walker and Orin to compute the forward dynamics.
- This form is useful for simulation of manipulator dynamics, in conjunction with a numerical integration function.

- Efficient dynamic computer simulation of robotic mechanisms, M. W. Walker and D. E. Orin, ASME Journa of Dynamic Systems, Measurement and Control, vol. 104, no. 3, pp. 205-211, 1982.

SerialLink.rne, SerialLink, ode45

Update a robot animation

R.animate(**q**) updates an existing animation for the robot R. This will have
been created using R.plot().

Updates graphical instances of this robot in all figures.

- Called by plot() and plot3d() to actually move the arm models
- Used for Simulink robot animation.

Convert to string

**s** = R.char() is a string representation of the robot's kinematic parameters,
showing DH parameters, joint structure, comments, gravity vector, base and
tool transform.

Cartesian inertia matrix

**m** = R.cinertia(**q**) is the NxN Cartesian (operational space) inertia matrix which relates
Cartesian force/torque to Cartesian acceleration at the joint configuration **q**, and N
is the number of robot joints.

SerialLink.inertia, SerialLink.rne

Coriolis matrix

**C** = R.coriolis(**q**, **qd**) is the Coriolis/centripetal matrix (NxN) for
the robot in configuration **q** and velocity **qd**, where N is the number of
joints. The product **C*****qd** is the vector of joint force/torque due to velocity
coupling. The diagonal elements are due to centripetal effects and the
off-diagonal elements are due to Coriolis effects. This matrix is also
known as the velocity coupling matrix, since gives the disturbance forces
on all joints due to velocity of any joint.

If **q** and **qd** are matrices (KxN), each row is interpretted as a joint state
vector, and the result (NxNxK) is a 3d-matrix where each plane corresponds
to a row of **q** and **qd**.

**C** = R.coriolis( **qqd**) as above but the matrix **qqd** (1x2N) is [**q** **qd**].

- Joint friction is also a joint force proportional to velocity but it is eliminated in the computation of this value.
- Computationally slow, involves N^2/2 invocations of RNE.

Display parameters

R.display() displays the robot parameters in human-readable form.

- This method is invoked implicitly at the command line when the result of an expression is a SerialLink object and the command has no trailing semicolon.

SerialLink.char, SerialLink.dyn

Display inertial properties

R.dyn() displays the inertial properties of the SerialLink object in a multi-line format. The properties shown are mass, centre of mass, inertia, gear ratio, motor inertia and motor friction.

R.dyn(**J**) as above but display parameters for joint **J** only.

Integrate forward dynamics

[**T**,**q**,**qd**] = R.fdyn(**T1**, **torqfun**) integrates the dynamics of the robot over
the time interval 0 to **T** and returns vectors of time TI, joint position **q**
and joint velocity **qd**. The initial joint position and velocity are zero.
The torque applied to the joints is computed by the user function **torqfun**:

[**ti**,**q**,**qd**] = R.fdyn(**T**, **torqfun**, **q0**, **qd0**) as above but allows the initial
joint position and velocity to be specified.

The control torque is computed by a user defined function

TAU = TORQFUN(T, Q, QD, ARG1, ARG2, ...)

where **q** and **qd** are the manipulator joint coordinate and velocity state
respectively, and **T** is the current time.

[**T**,**q**,**qd**] = R.fdyn(**T1**, **torqfun**, **q0**, **qd0**, ARG1, ARG2, ...) allows optional
arguments to be passed through to the user function.

- This function performs poorly with non-linear joint friction, such as Coulomb friction. The R.nofriction() method can be used to set this friction to zero.
- If TORQFUN is not specified, or is given as 0 or [], then zero torque is applied to the manipulator joints.
- The builtin integration function ode45() is used.

SerialLink.accel, SerialLink.nofriction, SerialLink.rne, ode45

Forward kinematics

**T** = R.fkine(**q**) is the pose (4x4) of the robot end-effector as a homogeneous
transformation for the joint configuration **q** (1xN).

If **q** is a matrix (KxN) the rows are interpretted as the generalized
joint coordinates for a sequence of points along a trajectory. **q**(i,j) is
the j'th joint parameter for the i'th trajectory point. In this case
**T** is a 3d matrix (4x4xK) where the last subscript is the index along the path.

[**T**,**all**] = R.fkine(**q**) as above but **all** (4x4xN) is the pose of the link
frames 1 to N, such that **all**(:,:,k) is the pose of link frame k.

- The robot's base or tool transform, if present, are incorporated into the result.
- Joint offsets, if defined, are added to Q before the forward kinematics are computed.

SerialLink.ikine, SerialLink.ikine6s

Friction force

**tau** = R.friction(**qd**) is the vector of joint friction forces/torques for the
robot moving with joint velocities **qd**.

The friction model includes:

- viscous friction which is linear with velocity;
- Coulomb friction which is proportional to sign(QD).

Vector of symbolic generalized coordinates

**q** = R.gencoords() is a vector (1xN) of symbols [q1 q2 ... qN].

[**q**,**qd**] = R.gencoords() as above but **qd** is a vector (1xN) of
symbols [qd1 qd2 ... qdN].

[**q**,**qd**,**qdd**] = R.gencoords() as above but **qdd** is a vector (1xN) of
symbols [qdd1 qdd2 ... qddN].

Vector of symbolic generalized forces

**q** = R.genforces() is a vector (1xN) of symbols [Q1 Q2 ... QN].

Gravity loading

**taug** = R.gravload(**q**) is the joint gravity loading for the robot in the
joint configuration **q**. Gravitational acceleration is a property of the
robot object.

If **q** is a row vector, the result is a row vector of joint torques. If
**q** is a matrix, each row is interpreted as a joint configuration vector,
and the result is a matrix each row being the corresponding joint torques.

**taug** = R.gravload(**q**, **grav**) is as above but the gravitational
acceleration vector **grav** is given explicitly.

SerialLink.rne, SerialLink.itorque, SerialLink.coriolis

Inverse manipulator kinematics

**q** = R.ikine(**T**) are the joint coordinates corresponding to the robot
end-effector pose **T** which is a homogenenous transform.

**q** = R.ikine(**T**, **q0**, **options**) specifies the initial estimate of the joint
coordinates.

This method can be used for robots with 6 or more degrees of freedom.

For the case where the manipulator has fewer than 6 DOF the solution space has more dimensions than can be spanned by the manipulator joint coordinates.

**q** = R.ikine(**T**, **q0**, **m**, **options**) similar to above but where **m** is a mask
vector (1x6) which specifies the Cartesian DOF (in the wrist coordinate
frame) that will be ignored in reaching a solution. The mask vector
has six elements that correspond to translation in X, Y and Z, and rotation
about X, Y and Z respectively. The value should be 0 (for ignore) or 1.
The number of non-zero elements should equal the number of manipulator DOF.

For example when using a 3 DOF manipulator rotation orientation might be
unimportant in which case **m** = [1 1 1 0 0 0].

For robots with 4 or 5 DOF this method is very difficult to use since
orientation is specified by **T** in world coordinates and the achievable
orientations are a function of the tool position.

In all cases if **T** is 4x4xM it is taken as a homogeneous transform sequence
and R.ikine() returns the joint coordinates corresponding to each of the
transforms in the sequence. **q** is MxN where N is the number of robot joints.
The initial estimate of **q** for each time step is taken as the solution
from the previous time step.

'pinv' | use pseudo-inverse instead of Jacobian transpose (default) |

'ilimit', L | set the maximum iteration count (default 1000) |

'tol', T | set the tolerance on error norm (default 1e-6) |

'alpha', A | set step size gain (default 1) |

'varstep' | enable variable step size if pinv is false |

'verbose' | show number of iterations for each point |

'verbose=2' | show state at each iteration |

'plot' | plot iteration state versus time |

- Solution is computed iteratively.
- Solution is sensitive to choice of initial gain. The variable step size logic (enabled by default) does its best to find a balance between speed of convergence and divergence.
- Some experimentation might be required to find the right values of tol, ilimit and alpha.
- The pinv option leads to much faster convergence (default)
- The tolerance is computed on the norm of the error between current and desired tool pose. This norm is computed from distances and angles without any kind of weighting.
- The inverse kinematic solution is generally not unique, and depends on the initial guess Q0 (defaults to 0).
- The default value of Q0 is zero which is a poor choice for most manipulators (eg. puma560, twolink) since it corresponds to a kinematic singularity.
- Such a solution is completely general, though much less efficient than specific inverse kinematic solutions derived symbolically, like ikine6s or ikine3.
- This approach allows a solution to be obtained at a singularity, but the joint angles within the null space are arbitrarily assigned.
- Joint offsets, if defined, are added to the inverse kinematics to generate Q.
- Joint limits are not considered in this solution.

SerialLink.fkine, SerialLink.ikinem, tr22angvec, SerialLink.jacob0, SerialLink.ikine6s

Inverse kinematics for 3-axis robot with no wrist

**q** = R.ikine3(**T**) is the joint coordinates corresponding to the robot
end-effector pose **T** represented by the homogenenous transform. This
is a analytic solution for a 3-axis robot (such as the first three joints
of a robot like the Puma 560).

**q** = R.ikine3(**T**, **config**) as above but specifies the configuration of the arm in
the form of a string containing one or more of the configuration codes:

'l' | arm to the left (default) |

'r' | arm to the right |

'u' | elbow up (default) |

'd' | elbow down |

- The same as IKINE6S without the wrist.
- The inverse kinematic solution is generally not unique, and depends on the configuration string.
- Joint offsets, if defined, are added to the inverse kinematics to generate Q.

Inverse kinematics for a PUMA 560 based on the equations by Paul and Zhang From The International Journal of Robotics Research Vol. 5, No. 2, Summer 1986, p. 32-44

Robert Biro with Gary Von McMurray, GTRI/ATRP/IIMB, Georgia Institute of Technology 2/13/95

SerialLink.FKINE, SerialLink.IKINE

Inverse kinematics for 6-axis robot with spherical wrist

**q** = R.ikine6s(**T**) is the joint coordinates corresponding to the robot
end-effector pose **T** represented by the homogenenous transform. This
is a analytic solution for a 6-axis robot with a spherical wrist (the most
common form for industrial robot arms).

**q** = R.IKINE6S(**T**, **config**) as above but specifies the configuration of the arm in
the form of a string containing one or more of the configuration codes:

'l' | arm to the left (default) |

'r' | arm to the right |

'u' | elbow up (default) |

'd' | elbow down |

'n' | wrist not flipped (default) |

'f' | wrist flipped (rotated by 180 deg) |

- Treats a number of specific cases:
- Robot with no shoulder offset
- Robot with a shoulder offset (has lefty/righty configuration)
- Robot with a shoulder offset and a prismatic third joint (like Stanford arm)
- The Puma 560 arms with should and elbow offsets
- The inverse kinematic solution is generally not unique, and depends on the configuration string.
- Joint offsets, if defined, are added to the inverse kinematics to generate Q.
- Only applicable for standard Denavit-Hartenberg parameters

- Inverse kinematics for a PUMA 560, Paul and Zhang, The International Journal of Robotics Research, Vol. 5, No. 2, Summer 1986, p. 32-44

The Puma560 specific case by Robert Biro with Gary Von McMurray, GTRI/ATRP/IIMB, Georgia Institute of Technology 2/13/95

SerialLink.FKINE, SerialLink.IKINE

Symbolic inverse kinematics

**q** = R.IKINE_SYM(**n**, **options**) is a vector (Nx1) of symbolic expressions
for the inverse kinematic solution of the SerialLink object ROBOT. The
solution is in terms of the desired end-point pose of the robot which is
represented by the symbolic matrix and elements

nx ox ax px ny oy ay py nz oz az pz

Elements of **q** may be cell arrays that contain multiple expressions,
representing different possible joint configurations.

**n** can have only specific values:

- 2 solve for translation px and py
- 3 solve for translation px, py and pz
- 6 solve for translation and orientation

'file', F | Write the solution to an m-file named F |

- This code is experimental and has a lot of diagnostic prints
- Based on the classical approach using Pieper's method

Inverse manipulator kinematics by minimization

**q** = R.ikinem(**T**) is the joint coordinates corresponding to the robot
end-effector pose **T** which is a homogenenous transform.

**q** = R.ikinem(**T**, **q0**, **options**) specifies the initial estimate of the joint
coordinates.

In all cases if **T** is 4x4xM it is taken as a homogeneous transform sequence
and R.ikinem() returns the joint coordinates corresponding to each of the
transforms in the sequence. **q** is MxN where N is the number of robot joints.
The initial estimate of **q** for each time step is taken as the solution
from the previous time step.

'pweight', P | weighting on position error norm compared to rotation error (default 1) |

'stiffness', S | Stiffness used to impose a smoothness contraint on joint angles, useful when N is large (default 0) |

'qlimits' | Enforce joint limits |

'ilimit', L | Iteration limit (default 1000) |

'nolm' | Disable Levenberg-Marquadt |

- PROTOTYPE CODE UNDER DEVELOPMENT, intended to do numerical inverse kinematics with joint limits
- The inverse kinematic solution is generally not unique, and depends on the initial guess Q0 (defaults to 0).
- The function to be minimized is highly nonlinear and the solution is often trapped in a local minimum, adjust Q0 if this happens.
- The default value of Q0 is zero which is a poor choice for most manipulators (eg. puma560, twolink) since it corresponds to a kinematic singularity.
- Such a solution is completely general, though much less efficient than specific inverse kinematic solutions derived symbolically, like ikine6s or ikine3.% - Uses Levenberg-Marquadt minimizer LMFsolve if it can be found, if 'nolm' is not given, and 'qlimits' false
- The error function to be minimized is computed on the norm of the error between current and desired tool pose. This norm is computed from distances and angles and 'pweight' can be used to scale the position error norm to be congruent with rotation error norm.
- This approach allows a solution to obtained at a singularity, but the joint angles within the null space are arbitrarily assigned.
- Joint offsets, if defined, are added to the inverse kinematics to generate Q.
- Joint limits become explicit contraints if 'qlimits' is set.

fminsearch, fmincon, SerialLink.fkine, SerialLink.ikine, tr2angvec

Manipulator inertia matrix

**i** = R.inertia(**q**) is the symmetric joint inertia matrix (NxN) which relates
joint torque to joint acceleration for the robot at joint configuration **q**.

If **q** is a matrix (KxN), each row is interpretted as a joint state
vector, and the result is a 3d-matrix (NxNxK) where each plane corresponds
to the inertia for the corresponding row of **q**.

- The diagonal elements I(J,J) are the inertia seen by joint actuator J.
- The off-diagonal elements I(J,K) are coupling inertias that relate acceleration on joint J to force/torque on joint K.
- The diagonal terms include the motor inertia reflected through the gear ratio.

SerialLink.RNE, SerialLink.CINERTIA, SerialLink.ITORQUE

Test for particular joint configuration

R.isconfig(**s**) is true if the robot has the joint configuration string
given by the string **s**.

Example:

robot.isconfig('RRRRRR');

Joint limit test

**v** = R.islimit(**q**) is a vector of boolean values, one per joint,
false (0) if **q**(i) is within the joint limits, else true (1).

- Joint limits are purely advisory and are not used in any other function. Just seemed like a useful thing to include...

Test for spherical wrist

R.isspherical() is true if the robot has a spherical wrist, that is, the last 3 axes are revolute and their axes intersect at a point.

Check if Link or SerialLink object is a symbolic model

**res** = L.issym() is true if the Link L has symbolic parameters.

**res** = R.issym() is true if the SerialLink manipulator R has symbolic parameters

Jörn Malzahn 2012 RST, Technische Universität Dortmund, Germany http://www.rst.e-technik.tu-dortmund.de

Inertia torque

**taui** = R.itorque(**q**, **qdd**) is the inertia force/torque vector (1xN) at the
specified joint configuration **q** (1xN) and acceleration **qdd** (1xN), that is,
**taui** = INERTIA(**q**)***qdd**.

If **q** and **qdd** are matrices (KxN), each row is interpretted as a joint state
vector, and the result is a matrix (KxN) where each row is the corresponding
joint torques.

- If the robot model contains non-zero motor inertia then this will included in the result.

SerialLink.rne, SerialLink.inertia

Jacobian in world coordinates

**j0** = R.jacob0(**q**, **options**) is the Jacobian matrix (6xN) for the robot in
pose **q** (1xN). The manipulator Jacobian matrix maps joint velocity to
end-effector spatial velocity V = **j0***QD expressed in the world-coordinate
frame.

'rpy' | Compute analytical Jacobian with rotation rate in terms of roll-pitch-yaw angles |

'eul' | Compute analytical Jacobian with rotation rates in terms of Euler angles |

'trans' | Return translational submatrix of Jacobian |

'rot' | Return rotational submatrix of Jacobian |

- The Jacobian is computed in the world frame and transformed to the end-effector frame.
- The default Jacobian returned is often referred to as the geometric Jacobian, as opposed to the analytical Jacobian.

SerialLink.jacobn, jsingu, deltatr, tr2delta, jsingu

Derivative of Jacobian

**jdq** = R.jacob_dot(**q**, **qd**) is the product (6x1) of the derivative of the
Jacobian (in the world frame) and the joint rates.

- Useful for operational space control XDD = J(Q)QDD + JDOT(Q)QD
- Written as per the text and not very efficient.

- Fundamentals of Robotics Mechanical Systems (2nd ed) J. Angleles, Springer 2003.

SerialLink.jacob0, diff2tr, tr2diff

Jacobian in end-effector frame

**jn** = R.jacobn(**q**, **options**) is the Jacobian matrix (6xN) for the robot in
pose **q**. The manipulator Jacobian matrix maps joint velocity to
end-effector spatial velocity V = **jn***QD in the end-effector frame.

'trans' | Return translational submatrix of Jacobian |

'rot' | Return rotational submatrix of Jacobian |

- This Jacobian is often referred to as the geometric Jacobian.

Differential Kinematic Control Equations for Simple Manipulators, Paul, Shimano, Mayer, IEEE SMC 11(6) 1981, pp. 456-460

SerialLink.jacob0, jsingu, delta2tr, tr2delta

Joint space trajectory

**q** = R.jtraj(**T1**, **t2**, **k**) is a joint space trajectory (KxN) where the joint
coordinates reflect motion from end-effector pose **T1** to **t2** in **k** steps with
default zero boundary conditions for velocity and acceleration.
The trajectory **q** has one row per time step, and one column per joint,
where N is the number of robot joints.

- Requires solution of inverse kinematics. R.ikine6s() is used if appropriate, else R.ikine(). Additional trailing arguments to R.jtraj() are passed as trailing arugments to these functions.

jtraj, SerialLink.ikine, SerialLink.ikine6s

Manipulability measure

**m** = R.maniplty(**q**, **options**) is the manipulability index measure for the robot
at the joint configuration **q**. It indicates dexterity, that is, how isotropic
the robot's motion is with respect to the 6 degrees of Cartesian motion.
The measure is high when the manipulator is capable of equal motion in all
directions and low when the manipulator is close to a singularity.

If **q** is a matrix (MxN) then **m** (Mx1) is a vector of manipulability
indices for each pose specified by a row of **q**.

[**m**,**ci**] = R.maniplty(**q**, **options**) as above, but for the case of the Asada
measure returns the Cartesian inertia matrix **ci**.

Two measures can be selected:

- Yoshikawa's manipulability measure is based on the shape of the velocity ellipsoid and depends only on kinematic parameters.
- Asada's manipulability measure is based on the shape of the acceleration ellipsoid which in turn is a function of the Cartesian inertia matrix and the dynamic parameters. The scalar measure computed here is the ratio of the smallest/largest ellipsoid axis. Ideally the ellipsoid would be spherical, giving a ratio of 1, but in practice will be less than 1.

'T' | manipulability for transational motion only (default) |

'R' | manipulability for rotational motion only |

'all' | manipulability for all motions |

'dof', D | D is a vector (1x6) with non-zero elements if the corresponding DOF is to be included for manipulability |

'yoshikawa' | use Yoshikawa algorithm (default) |

'asada' | use Asada algorithm |

- The 'all' option includes rotational and translational dexterity, but this involves adding different units. It can be more useful to look at the translational and rotational manipulability separately.
- Examples in the RVC book can be replicated by using the 'all' option

- Analysis and control of robot manipulators with redundancy, T. Yoshikawa, Robotics Research: The First International Symposium (M. Brady and R. Paul, eds.), pp. 735-747, The MIT press, 1984.
- A geometrical representation of manipulator dynamics and its application to arm design, H. Asada, Journal of Dynamic Systems, Measurement, and Control, vol. 105, p. 131, 1983.

SerialLink.inertia, SerialLink.jacob0

Concatenate robots

R = R1 * R2 is a robot object that is equivalent to mechanically attaching robot R2 to the end of robot R1.

- If R1 has a tool transform or R2 has a base transform these are discarded since DH convention does not allow for arbitrary intermediate transformations.

Remove friction

**rnf** = R.nofriction() is a robot object with the same parameters as R but
with non-linear (Coulomb) friction coefficients set to zero.

**rnf** = R.nofriction('all') as above but all friction coefficients set to zero.

**rnf** = R.nofriction('viscous') as above but only viscous friction coefficients
are set to zero.

- Non-linear (Coulomb) friction can cause numerical problems when integrating the equations of motion (R.fdyn).
- The resulting robot object has its name string prefixed with 'NF/'.

SerialLink.fdyn, Link.nofriction

Add payload mass

R.payload(**m**, **p**) adds a payload with point mass **m** at position **p**
in the end-effector coordinate frame.

SerialLink.rne, SerialLink.gravload

Perturb robot parameters

**rp** = R.perturb(**p**) is a new robot object in which the dynamic parameters (link
mass and inertia) have been perturbed. The perturbation is multiplicative so
that values are multiplied by random numbers in the interval (1-**p**) to (1+**p**).
The name string of the perturbed robot is prefixed by '**p**/'.

Useful for investigating the robustness of various model-based control schemes. For example to vary parameters in the range +/- 10 percent is:

r2 = p560.perturb(0.1);

Graphical display and animation

R.plot(**q**, **options**) displays a graphical animation of a robot based on
the kinematic model. A stick figure polyline joins the origins of
the link coordinate frames. The robot is displayed at the joint angle **q** (1xN), or
if a matrix (MxN) it is animated as the robot moves along the M-point trajectory.

'workspace', W | Size of robot 3D workspace, W = [xmn, xmx ymn ymx zmn zmx] |

'floorlevel', L | Z-coordinate of floor (default -1) |

'delay', D | Delay betwen frames for animation (s) |

'fps', fps | Number of frames per second for display, inverse of 'delay' option |

'[no]loop' | Loop over the trajectory forever |

'[no]raise' | Autoraise the figure |

'movie', M | Save frames as files in the folder M |

'trail', L | Draw a line recording the tip path, with line style L |

'scale', S | Annotation scale factor |

'zoom', Z | Reduce size of auto-computed workspace by Z, makes robot look bigger |

'ortho' | Orthographic view |

'perspective' | Perspective view (default) |

'view', V | Specify view V='x', 'y', 'top' or [az el] for side elevations, plan view, or general view by azimuth and elevation angle. |

'[no]shading' | Enable Gouraud shading (default true) |

'lightpos', L | Position of the light source (default [0 0 20]) |

'[no]name' | Display the robot's name |

'[no]wrist' | Enable display of wrist coordinate frame |

'xyz' | Wrist axis label is XYZ |

'noa' | Wrist axis label is NOA |

'[no]arrow' | Display wrist frame with 3D arrows |

'[no]tiles' | Enable tiled floor (default true) |

'tilesize', S | Side length of square tiles on the floor (default 0.2) |

'tile1color', C | Color of even tiles [r g b] (default [0.5 1 0.5] light green) |

'tile2color', C | Color of odd tiles [r g b] (default [1 1 1] white) |

'[no]shadow' | Enable display of shadow (default true) |

'shadowcolor', C | Colorspec of shadow, [r g b] |

'shadowwidth', W | Width of shadow line (default 6) |

'[no]jaxes' | Enable display of joint axes (default true) |

'[no]joints' | Enable display of joints |

'jointcolor', C | Colorspec for joint cylinders (default [0.7 0 0]) |

'jointdiam', D | Diameter of joint cylinder in scale units (default 5) |

'linkcolor', C | Colorspec of links (default 'b') |

'[no]base' | Enable display of base 'pedestal' |

'basecolor', C | Color of base (default 'k') |

'basewidth', W | Width of base (default 3) |

The **options** come from 3 sources and are processed in order:

- Cell array of options returned by the function PLOTBOTOPT (if it exists)
- Cell array of options given by the 'plotopt' option when creating the SerialLink object.
- List of arguments in the command line.

Many boolean **options** can be enabled or disabled with the 'no' prefix. The
various option sources can toggle an option, the last value is taken.

The robot is displayed as a basic stick figure robot with annotations such as:

- shadow on the floor
- XYZ wrist axes and labels
- joint cylinders and axes

which are controlled by **options**.

The size of the annotations is determined using a simple heuristic from the workspace dimensions. This dimension can be changed by setting the multiplicative scale factor using the 'mag' option.

- If no figure exists one will be created and the robot drawn in it.
- If no robot of this name is currently displayed then a robot will be drawn in the current figure. If hold is enabled (hold on) then the robot will be added to the current figure.
- If the robot already exists then that graphical model will be found and moved.

If one or more plots of this robot already exist then these will all
be moved according to the argument **q**. All robots in all windows with
the same name will be moved.

Create a robot in figure 1

figure(1) p560.plot(qz);

Create a robot in figure 2

figure(2) p560.plot(qz);

Now move both robots

p560.plot(qn)

Multiple robots can be displayed in the same plot, by using "hold on" before calls to robot.plot().

Create a robot in figure 1

figure(1) p560.plot(qz);

Make a clone of the robot named bob

bob = SerialLink(p560, 'name', 'bob');

Draw bob in this figure

hold on bob.plot(qn)

To animate both robots so they move together:

qtg = jtraj(qr, qz, 100); for q=qtg'

p560.plot(q'); bob.plot(q');

end

- The 'movie' options saves frames as files NNNN.png into the specified folder
- The specified folder will be created
- To convert frames to a movie use a command like:

ffmpeg -r 10 -i %04d.png out.avi

- The options are processed when the figure is first drawn, to make different options come into effect it is neccessary to clear the figure.
- The link segments do not neccessarily represent the links of the robot, they are a pipe network that joins the origins of successive link coordinate frames.
- Delay betwen frames can be eliminated by setting option 'delay', 0 or 'fps', Inf.
- By default a quite detailed plot is generated, but turning off labels, axes, shadows etc. will speed things up.
- Each graphical robot object is tagged by the robot's name and has UserData that holds graphical handles and the handle of the robot object.
- The graphical state holds the last joint configuration
- The size of the plot volume is determined by a heuristic for an all-revolute robot. If a prismatic joint is present the 'workspace' option is required. The 'zoom' option can reduce the size of this workspace.

SerialLink.plot3d, plotbotopt, SerialLink.animate, SerialLink.teach, SerialLink.fkine

Graphical display and animation of solid model robot

R.plot3d(**q**, **options**) displays and animates a solid model of the robot.
The robot is displayed at the joint angle **q** (1xN), or
if a matrix (MxN) it is animated as the robot moves along the M-point trajectory.

'color', C | A cell array of color names, one per link. These are mapped to RGB using colorname(). If not given, colors come from the axis ColorOrder property. |

'alpha', A | Set alpha for all links, 0 is transparant, 1 is opaque (default 1) |

'path', P | Overide path to folder containing STL model files |

'workspace', W | Size of robot 3D workspace, W = [xmn, xmx ymn ymx zmn zmx] |

'floorlevel', L | Z-coordinate of floor (default -1) |

'delay', D | Delay betwen frames for animation (s) |

'fps', fps | Number of frames per second for display, inverse of 'delay' option |

'[no]loop' | Loop over the trajectory forever |

'[no]raise' | Autoraise the figure |

'movie', M | Save frames as files in the folder M |

'scale', S | Annotation scale factor |

'ortho' | Orthographic view (default) |

'perspective' | Perspective view |

'[no]wrist' | Enable display of wrist coordinate frame |

'xyz' | Wrist axis label is XYZ |

'noa' | Wrist axis label is NOA |

'[no]arrow' | Display wrist frame with 3D arrows |

'[no]tiles' | Enable tiled floor (default true) |

'tilesize', S | Side length of square tiles on the floor (default 0.2) |

'tile1color', C | Color of even tiles [r g b] (default [0.5 1 0.5] light green) |

'tile2color', C | Color of odd tiles [r g b] (default [1 1 1] white) |

'[no]jaxes' | Enable display of joint axes (default true) |

'[no]joints' | Enable display of joints |

'[no]base' | Enable display of base shape |

- Solid models of the robot links are required as STL ascii format files, with extensions .stl
- Suitable STL files can be found in the package ARTE: A ROBOTICS TOOLBOX FOR EDUCATION by Arturo Gil
- The root of the solid models is an installation of ARTE with an empty file called arte.m at the top level
- Each STL model is called 'linkN'.stl where N is the link number 0 to N
- The specific folder to use comes from the SerialLink.model3d property
- The path of the folder containing the STL files can be specified using the 'path' option
- The height of the floor is set in decreasing priority order by:
- 'workspace' option, the fifth element of the passed vector
- 'floorlevel' option
- the lowest z-coordinate in the link1.stl object

- Peter Corke, based on existing code for plot()
- Bryan Moutrie, demo code on the Google Group for connecting ARTE and RTB
- Don Riley, function rndread() extracted from cad2matdemo (MATLAB File Exchange)

SerialLink.plot, plotbotopt3d, SerialLink.animate, SerialLink.teach, SerialLink.fkine

CAD STL ASCII files, which most CAD programs can export.

Used to create Matlab patches of CAD 3D data. Returns a vertex list and face list, for Matlab patch command.

filename = 'hook.stl'; % Example file.

Inverse dynamics

**tau** = R.rne(**q**, **qd**, **qdd**) is the joint torque required for the robot R
to achieve the specified joint position **q**, velocity **qd** and acceleration **qdd**.

**tau** = R.rne(**q**, **qd**, **qdd**, **grav**) as above but overriding the gravitational
acceleration vector in the robot object R.

**tau** = R.rne(**q**, **qd**, **qdd**, **grav**, **fext**) as above but specifying a wrench
acting on the end of the manipulator which is a 6-vector [Fx Fy Fz Mx My Mz].

**tau** = R.rne(**x**) as above where **x**=[**q**,**qd**,**qdd**].

**tau** = R.rne(**x**, **grav**) as above but overriding the gravitational
acceleration vector in the robot object R.

**tau** = R.rne(**x**, **grav**, **fext**) as above but specifying a wrench
acting on the end of the manipulator which is a 6-vector [Fx Fy Fz Mx My Mz].

[**tau**,**wbase**] = R.rne(**x**, **grav**, **fext**) as above but the extra output is the
wrench on the base.

If **q**,**qd** and **qdd** (MxN), or **x** (Mx3N) are matrices with M rows representing a
trajectory then **tau** (MxN) is a matrix with rows corresponding to each trajectory
step.

This algorithm is relatively slow, and a MEX file can provide better performance. The MEX file is executed if:

- the robot is not symbolic, and
- the SerialLink property fast is true, and
- the MEX file exists.

- The robot base transform is ignored.
- Currently the MEX-file version does not compute WBASE.
- The torque computed contains a contribution due to armature inertia and joint friction.
- See the README file in the mex folder for details on how to configure MEX-file operation.
- The M-file is a wrapper which calls either RNE_DH or RNE_MDH depending on the kinematic conventions used by the robot object.

SerialLink.accel, SerialLink.gravload, SerialLink.inertia

Graphical teach pendant

R.teach(**q**) drive a graphical robot by means of a graphical slider panel.
If no graphical robot exists one is created in a new window. Otherwise
all current instances of the graphical robot are driven. The robots are set
to the initial joint angles **q**.

R.teach(**q**, **options**) as above but with options.

R.teach(**options**) as above but with options and the initial joint angles
are taken from the pose of an existing graphical robot, or if that doesn't
exist then zero.

'eul' | Display tool orientation in Euler angles |

'rpy' | Display tool orientation in roll/pitch/yaw angles |

'approach' | Display tool orientation as approach vector (z-axis) |

'radians' | Display angles in radians (default degrees) |

'callback', C | Set a callback function |

- The record button invokes the user specified callback function, and is passed the joint coordinate vector.
- The Quit button destroys the teach window.

- The slider limits are derived from the joint limit properties. If not set then for
- a revolute joint they are assumed to be [-pi, +pi]
- a prismatic joint they are assumed unknown and an error occurs.

Display kinematic parameters as a chain of 3D transforms

**s** = R.TRCHAIN(**options**) is a string of elementary transforms that describe the
kinematics of the seriallink robot arm. The string **s** comprises a number
of tokens of the form X(ARG) where X is one of Tx, Ty, Tz, Rx, Ry, or Rz.
ARG is a joint variable, or a constant angle or length dimension.

For example:

>> mdl_puma560 >> p560.trchain ans = Rz(q1)Rx(90)Rz(q2)Tx(0.431800)Rz(q3)Tz(0.150050)Tx(0.020300)Rx(-90) Rz(q4)Tz(0.431800)Rx(90)Rz(q5)Rx(-90)Rz(q6)

'[no]deg' | Express angles in degrees rather than radians (default deg) |

'sym' | Replace length parameters by symbolic values L1, L2 etc. |

trchain, trotx, troty, trotz, transl

Robotics Toolbox for MATLAB © 1990-2014 Peter Corke.