SerialLink

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.

Methods

Properties (read/write)

Properties (read only)

Overloaded operators

Note

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

Reference

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

See also

Link, DHFactor

Create a SerialLink robot object

R = SerialLink(links, options) is a robot object defined by a vector of Link class objects which can be instances of Link, Revolute, Prismatic, RevoluteMDH or PrismaticMDH.

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. Can also be written R1*R2 etc.

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

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).

Options

Examples

Create a 2-link robot

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

Create a 2-link robot (most descriptive)

L(1) = Revolute('d', 0, 'a', a1, 'alpha', pi/2);
L(2) = Revolute('d', 0, 'a', a2, 'alpha', 0);
twolink = SerialLink(L, 'name', 'two link');

Create a 2-link robot (least descriptive)

twolink = SerialLink([0 0 a1 0; 0 0 a2 0], 'name', 'two link');

Robot objects can be concatenated in two ways

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

Note

• SerialLink is a reference object, a subclass of Handle object.
• SerialLink objects can be used in vectors and arrays
• Link subclass elements passed in must be all standard, or all modified, DH parameters.
• 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.

See also

Link, Revolute, Prismatic, RevoluteMDH, PrismaticMDH, SerialLink.plot

Link transformation matrices

s = R.A(J, qj) is an SE(3) homogeneous transform (4x4) that transforms from link frame {J-1} to frame {J} which is a function of the J'th joint variable qj.

s = R.A(jlist, q) as above but is a composition of link transform matrices given in the list JLIST, and the joint variables are taken from the corresponding elements of Q.

Exmaples

For example, the link transform for joint 4 is

robot.A(4, q4)

The link transform for joints 3 through 6 is

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

where q is 1x6 and the elements q(3) .. q(6) are used.

Notes

• base and tool transforms are not applied.

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 R in state q and qd, and N is the number of robot joints.

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] (1x3N).

Note

• Useful for simulation of manipulator dynamics, in conjunction with a numerical integration function.
• Uses the method 1 of Walker and Orin to compute the forward dynamics.
• Featherstone's method is more efficient for robots with large numbers of joints.
• Joint friction is considered.

References

• 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.

See also

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.

Notes

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

See also

SerialLink.plot

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.

See also

SerialLink.inertia, SerialLink.rne

Perform collision checking

C = R.collisions(q, model) is true if the SerialLink object R at pose q (1xN) intersects the solid model model which belongs to the class CollisionModel. The model comprises a number of geometric primitives and associate pose.

C = R.collisions(q, model, dynmodel, tdyn) as above but also checks dynamic collision model dynmodel whose elements are at pose tdyn. tdyn is an array of transformation matrices (4x4xP), where P = length(dynmodel.primitives). The P'th plane of tdyn premultiplies the pose of the P'th primitive of dynmodel.

C = R.collisions(q, model, dynmodel) as above but assumes tdyn is the robot's tool frame.

Trajectory operation

If q is MxN it is taken as a pose sequence and C is Mx1 and the collision value applies to the pose of the corresponding row of q. tdyn is 4x4xMxP.

Notes

• Requires the pHRIWARE package which defines CollisionModel class. Available from: https://code.google.com/p/phriware/ .
• The robot is defined by a point cloud, given by its points property.
• The function does not currently check the base of the SerialLink object.
• If MODEL is [] then no static objects are assumed.

Author

Bryan Moutrie

See also

collisionmodel, SerialLink

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 it describes the disturbance forces on any joint due to velocity of all other joints.

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].

Notes

• Joint viscous 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.

See also

SerialLink.rne

Display parameters

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

Notes

• 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.

See also

SerialLink.char, SerialLink.dyn

Print 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.

See also

Link.dyn

Edit kinematic and dynamic parameters of a seriallink manipulator

R.edit displays the kinematic parameters of the robot as an editable table in a new figure.

R.edit('dyn') as above but also displays the dynamic parameters.

Notes

• The 'Save' button copies the values from the table to the SerialLink manipulator object.
• To exit the editor without updating the object just kill the figure window.

Integrate forward dynamics

[T,q,qd] = R.fdyn(T, torqfun) integrates the dynamics of the robot over the time interval 0 to T and returns vectors of time T, 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-supplied control function torqfun:

TAU = TORQFUN(T, Q, QD)

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

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

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

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

For example, if the robot was controlled by a PD controller we can define a function to compute the control

function tau = mytorqfun(t, q, qd, qstar, P, D)

tau = P*(qstar-q) + D*qd;

and then integrate the robot dynamics with the control

[t,q] = robot.fdyn(10, @mytorqfun, qstar, P, D);

Note

• 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.

See also

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

Forward kinematics

T = R.fkine(q, options) is the pose of the robot end-effector as an SE(3) homogeneous transformation (4x4) for the joint configuration q (1xN).

If q is a matrix (KxN) the rows are interpreted 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.

Options

Note

• 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.

See also

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 a linear function of velocity.
• Coulomb friction which is proportional to sign(QD).

See also

Link.friction

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].

Get joint coordinates from graphical display

q = R.getpos() returns the joint coordinates set by the last plot or teach operation on the graphical robot.

See also

SerialLink.plot, SerialLink.teach

Fast gravity load and Jacobian

[tau,jac0] = R.gravjac(q) is the generalised joint force/torques due to gravity (1xN) and the manipulator Jacobian in the base frame (6xN) for robot pose q (1xN), where N is the number of robot joints.

[tau,jac0] = R.gravjac(q,grav) as above but gravity is given explicitly by grav (3x1).

Trajectory operation

If q is MxN where N is the number of robot joints then a trajectory is assumed where each row of q corresponds to a pose. tau (MxN) is the generalised joint torque, each row corresponding to an input pose, and jac0 (6xNxM) where each plane is a Jacobian corresponding to an input pose.

Notes

• The gravity vector is defined by the SerialLink property if not explicitly given.
• Does not use inverse dynamics function RNE.
• Faster than computing gravity and Jacobian separately.

Author

Bryan Moutrie

See also

SerialLink.pay, SerialLink, SerialLink.gravload, SerialLink.jacob0

Gravity load on joints

taug = R.gravload(q) is the joint gravity loading (1xN) for the robot R in the joint configuration q (1xN), where N is the number of robot joints. Gravitational acceleration is a property of the robot object.

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

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

See also

SerialLink.rne, SerialLink.itorque, SerialLink.coriolis

Numerical inverse kinematics with joint limits

q = R.ikcon(T) are the joint coordinates (1xN) corresponding to the robot end-effector pose T (4x4) which is a homogenenous transform.

[q,err] = robot.ikcon(T) as above but also returns err which is the scalar final value of the objective function.

[q,err,exitflag] = robot.ikcon(T) as above but also returns the status exitflag from fmincon.

[q,err,exitflag] = robot.ikcon(T, q0) as above but specify the initial joint coordinates q0 used for the minimisation.

[q,err,exitflag] = robot.ikcon(T, q0, options) as above but specify the options for fmincon to use.

Trajectory operation

In all cases if T is 4x4xM it is taken as a homogeneous transform sequence and R.ikcon() 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.

err and exitflag are also Mx1 and indicate the results of optimisation for the corresponding trajectory step.

Notes

• Requires fmincon from the Optimization Toolbox.
• Joint limits are considered in this solution.
• Can be used for robots with arbitrary degrees of freedom.
• In the case of multiple feasible solutions, the solution returned depends on the initial choice of Q0.
• Works by minimizing the error between the forward kinematics of the joint angle solution and the end-effector frame as an optimisation. The objective function (error) is described as:

sumsqr( (inv(T)*robot.fkine(q) - eye(4)) * omega )

Where omega is some gain matrix, currently not modifiable.

Author

Bryan Moutrie

See also

SerialLink.ikunc, fmincon, SerialLink.ikine, SerialLink.fkine

Numerical inverse kinematics

q = R.ikine(T) are the joint coordinates (1xN) corresponding to the robot end-effector pose T (4x4) 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.

Underactuated robots

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.

Trajectory operation

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.

Options

References

• Robotics, Vision & Control, Section 8.4, P. Corke, Springer 2011.

Notes

• 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.

See also

SerialLink.ikcon, SerialLink.ikunc, SerialLink.fkine, 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:

Notes

• 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.

Reference

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

Author

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

See also

SerialLink.FKINE, SerialLink.IKINE

Analytical inverse kinematics

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

If T represents a trajectory (4x4xM) then the inverse kinematics is computed for all M poses resulting in q (MxN) with each row representing the joint angles at the corresponding pose.

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:

Notes

• 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 shoulder and elbow offsets (4 lengths parameters)
• The Kuka KR5 with many offsets (7 length parameters)
• 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

Reference

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

Author

• The Puma560 case: Robert Biro with Gary Von McMurray, GTRI/ATRP/IIMB, Georgia Institute of Technology, 2/13/95
• Kuka KR5 case: Gautam Sinha, Autobirdz Systems Pvt. Ltd., SIDBI Office, Indian Institute of Technology Kanpur, Kanpur, Uttar Pradesh.

See also

SerialLink.FKINE, SerialLink.IKINE

Symbolic inverse kinematics

q = R.IKINE_SYM(k, options) is a cell array (Cx1) of inverse kinematic solutions of the SerialLink object ROBOT. The cells of q represent the different possible configurations. Each cell of q is a vector (Nx1), and element J is the symbolic expressions for the J'th joint angle. The solution is in terms of the desired end-point pose of the robot which is represented by the symbolic matrix (3x4) with elements

nx ox ax tx
ny oy ay ty
nz oz az tz

where the first three columns specify orientation and the last column specifies translation.

k <= N can have only specific values:

• 2 solve for translation tx and ty
• 3 solve for translation tx, ty and tz
• 6 solve for translation and orientation

Options

Example

mdl_planar2
sol = p2.ikine_sym(2);
length(sol)
ans =

2       % there are 2 solutions

s1 = sol{1}  % is one solution
q1 = s1(1);      % the expression for q1
q2 = s1(2);      % the expression for q2

Notes

• Requires the Symbolic Toolbox for MATLAB.
• This code is experimental and has a lot of diagnostic prints.
• Based on the classical approach using Pieper's method.

Numerical inverse 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.

Options

Notes

• 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.

See also

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

Numerical inverse manipulator without joint limits

q = R.ikunc(T) are the joint coordinates (1xN) corresponding to the robot end-effector pose T (4x4) which is a homogenenous transform, and N is the number of robot joints.

[q,err] = robot.ikunc(T) as above but also returns err which is the scalar final value of the objective function.

[q,err,exitflag] = robot.ikunc(T) as above but also returns the status exitflag from fminunc.

[q,err,exitflag] = robot.ikunc(T, q0) as above but specify the initial joint coordinates q0 used for the minimisation.

[q,err,exitflag] = robot.ikunc(T, q0, options) as above but specify the options for fminunc to use.

Trajectory operation

In all cases if T is 4x4xM it is taken as a homogeneous transform sequence and R.ikunc() 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.

err and exitflag are also Mx1 and indicate the results of optimisation for the corresponding trajectory step.

Notes

• Requires fminunc from the Optimization Toolbox.
• Joint limits are not considered in this solution.
• Can be used for robots with arbitrary degrees of freedom.
• In the case of multiple feasible solutions, the solution returned depends on the initial choice of Q0
• Works by minimizing the error between the forward kinematics of the joint angle solution and the end-effector frame as an optimisation. The objective function (error) is described as:

sumsqr( (inv(T)*robot.fkine(q) - eye(4)) * omega )

Where omega is some gain matrix, currently not modifiable.

Author

Bryan Moutrie

See also

SerialLink.ikcon, fmincon, SerialLink.ikine, SerialLink.fkine

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.

Notes

• 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.

See also

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');

See also

SerialLink.config

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).

Notes

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

See also

Link.islimit

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.

See also

SerialLink.ikine6s

Check if SerialLink object is a symbolic model

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

Authors

Joern Malzahn, (joern.malzahn@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), and N is the number of robot joints. 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.

Note

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

See also

SerialLink.inertia, SerialLink.rne

Jacobian in world coordinates

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

Options

Note

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

See also

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.

Notes

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

References

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

See also

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, and N is the number of robot joints. The manipulator Jacobian matrix maps joint velocity to end-effector spatial velocity V = jn*QD in the end-effector frame.

Options

Notes

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

References

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

See also

SerialLink.jacob0, jsingu, delta2tr, tr2delta

Joint space trajectory

q = R.jtraj(T1, t2, k, options) 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.

Options

Additional options are passed as trailing arguments to the inverse kinematic function.

See also

jtraj, SerialLink.ikine, SerialLink.ikine6s

Manipulability measure

m = R.maniplty(q, options) is the manipulability index (scalar) for the robot at the joint configuration q (1xN) where N is the number of robot joints. 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 joint configuration 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 computed:

• 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.

Options

Notes

• 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

References

• 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.

See also

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.

Notes

• 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 viscous and Coulomb friction coefficients set to zero.

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

Notes

• 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/'.

See also

SerialLink.fdyn, Link.nofriction

Joint forces due to payload

tau = R.PAY(w, J) returns the generalised joint force/torques due to a payload wrench w (1x6) and where the manipulator Jacobian is J (6xN), and N is the number of robot joints.

tau = R.PAY(q, w, f) as above but the Jacobian is calculated at pose q (1xN) in the frame given by f which is '0' for world frame, 'n' for end-effector frame.

Uses the formula tau = J'w, where w is a wrench vector applied at the end effector, w = [Fx Fy Fz Mx My Mz]'.

Trajectory operation

In the case q is MxN or J is 6xNxM then tau is MxN where each row is the generalised force/torque at the pose given by corresponding row of q.

Notes

• Wrench vector and Jacobian must be from the same reference frame.
• Tool transforms are taken into consideration when F = 'n'.
• Must have a constant wrench - no trajectory support for this yet.

Author

Bryan Moutrie

See also

SerialLink.paycap, SerialLink.jacob0, SerialLink.jacobn

Static payload capacity of a robot

[wmax,J] = R.paycap(q, w, f, tlim) returns the maximum permissible payload wrench wmax (1x6) applied at the end-effector, and the index of the joint J which hits its force/torque limit at that wrench. q (1xN) is the manipulator pose, w the payload wrench (1x6), f the wrench reference frame (either '0' or 'n') and tlim (2xN) is a matrix of joint forces/torques (first row is maximum, second row minimum).

Trajectory operation

In the case q is MxN then wmax is Mx6 and J is Mx1 where the rows are the results at the pose given by corresponding row of q.

Notes

• Wrench vector and Jacobian must be from the same reference frame
• Tool transforms are taken into consideration for F = 'n'.

Author

Bryan Moutrie

See also

SerialLink.pay, SerialLink.gravjac, SerialLink.gravload

Add payload mass

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

Notes

• An added payload will affect the inertia, Coriolis and gravity terms.

See also

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.

Options

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.

Graphical annotations and options

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.

Figure behaviour

• 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.

Multiple views of the same robot

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 in the same figure

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

Making an animation movie

• 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

Notes

• 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.

See also

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.

Options

Notes

• 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, https://arvc.umh.es/arte
• 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

Authors

• 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)

See also

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

Use redundancy to avoid joint limits

qs = R.qmincon(q) exploits null space motion and returns a set of joint angles qs (1xN) that result in the same end-effector pose but are away from the joint coordinate limits. N is the number of robot joints.

[q,err] = R.qmincon(q) as above but also returns err which is the scalar final value of the objective function.

[q,err,exitflag] = R.qmincon(q) as above but also returns the status exitflag from fmincon.

Trajectory operation

In all cases if q is MxN it is taken as a pose sequence and R.qmincon() returns the adjusted joint coordinates (MxN) corresponding to each of the poses in the sequence.

err and exitflag are also Mx1 and indicate the results of optimisation for the corresponding trajectory step.

Notes

• Requires fmincon from the Optimization Toolbox.
• Robot must be redundant.

Author

Bryan Moutrie

See also

SerialLink.ikcon, SerialLink.ikunc, SerialLink.jacob0

Inverse dynamics

tau = R.rne(q, qd, qdd) is the joint torque required for the robot R to achieve the specified joint position q (1xN), velocity qd (1xN) and acceleration qdd (1xN), where N is the number of robot joints.

tau = R.rne(q, qd, qdd, grav) as above but overriding the gravitational acceleration vector (3x1) 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] (1x3N).

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.

Trajectory operation

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.

MEX file operation

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 frne.mexXXX exists in the subfolder rvctools/robot/mex.

Notes

• 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, or the MEX file.

See also

SerialLink.accel, SerialLink.gravload, SerialLink.inertia

Graphical teach pendant

R.teach(q, options) allows the user to "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(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.

Options

Example

To display the velocity ellipsoid for a Puma 560

p560.teach('callback', @(r,q) r.vellipse(q));

GUI

• The specified callback function is invoked every time the joint configuration changes. the joint coordinate vector.
• The Quit (red X) button destroys the teach window.

Notes

• If the robot is displayed in several windows, only one has the teach panel added.
• 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.

See also

SerialLink.plot, SerialLink.getpos

Convert to elementary transform sequence

s = R.TRCHAIN(options) is a sequence of elementary transforms that describe the kinematics of the serial link 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)

Options

See also

trchain, trotx, troty, trotz, transl

Robotics Toolbox for MATLAB © 1990-2014 Peter Corke.