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

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
fkine forward kinematics
ikine6s inverse kinematics for 6-axis spherical wrist revolute robot
ikine3 inverse kinematics for 3-axis revolute robot
ikine inverse kinematics using iterative method
jacob0 Jacobian matrix in world frame
jacobn Jacobian matrix in tool frame
maniplty manipulability
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

Properties (read/write)

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)

Object properties (read only)

n number of joints
config joint configuration string, eg. 'RRRRRR'
mdh kinematic convention boolean (0=DH, 1=MDH)

Note

Reference

See also

Link, DHFactor


SerialLink.SerialLink

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.

Options

'name', name set robot name property
'comment', comment set robot comment property
'manufacturer', manuf set robot manufacturer property
'base', base set base transformation matrix property
'tool', tool set tool transformation matrix property
'gravity', g set gravity vector property
'plotopt', po set plotting options property

Examples

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

Note

See also

Link, SerialLink.plot


SerialLink.accel

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

Note

References

See also

SerialLink.rne, SerialLink, ode45


SerialLink.animate

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

See also

SerialLink.plot


SerialLink.char

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.


SerialLink.cinertia

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


SerialLink.coriolis

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

Notes

See also

SerialLink.rne












SerialLink.display

Display parameters

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

Notes

See also

SerialLink.char, SerialLink.dyn


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.

See also

Link.dyn


SerialLink.fdyn

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.

Note

See also

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


SerialLink.fkine

evaluate fkine for each point on a trajectory of theta_i or q_i data


SerialLink.friction

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:

See also

Link.friction


SerialLink.gencoords

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



SerialLink.gravload

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.

See also

SerialLink.rne, SerialLink.itorque, SerialLink.coriolis


SerialLink.ikine

default parameters for solution


SerialLink.ikine3

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

Notes

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


SerialLink.ikine6s

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 (such as the Puma 560).

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)

Notes

Reference

Author

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

See also

SerialLink.FKINE, SerialLink.IKINE


SerialLink.inertia

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

See also

SerialLink.RNE, SerialLink.CINERTIA, SerialLink.ITORQUE


SerialLink.islimit

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

See also

Link.islimit


SerialLink.isspherical

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



SerialLink.itorque

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.

Note

See also

SerialLink.rne, SerialLink.inertia


SerialLink.jacob0

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.

Options

'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

Note

See also

SerialLink.jacobn, jsingu, deltatr, tr2delta, jsingu


SerialLink.jacob_dot

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

References

See also

: SerialLink.jacob0, diff2tr, tr2diff


SerialLink.jacobn

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.

Options

'trans' Return translational submatrix of Jacobian
'rot' Return rotational submatrix of Jacobian

Notes

Reference

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


SerialLink.jtraj

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.

Note

See also

jtraj, SerialLink.ikine, SerialLink.ikine6s


SerialLink.maniplty

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:

Options

'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

Notes

References

See also

SerialLink.inertia, SerialLink.jacob0


SerialLink.mtimes

Concatenate robots

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

Notes


SerialLink.nofriction

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.

Notes

See also

SerialLink.fdyn, Link.nofriction


SerialLink.payload

Add payload mass

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

See also

SerialLink.rne, SerialLink.gravload


SerialLink.perturb

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

SerialLink.plot

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

'workspace', W size of robot 3D workspace, W = [xmn, xmx ymn ymx zmn zmx]
'delay', d delay betwen frames for animation (s)
'fps', fps set number of frames per second for display
'[no]loop' loop over the trajectory forever
'mag', scale annotation scale factor
'cylinder', C color for joint cylinders, C=[r g b]
'ortho' orthogonal camera view (default)
'perspective' perspective camera view
'xyz' wrist axis label is XYZ
'noa' wrist axis label is NOA
'[no]raise' autoraise the figure (very slow).
'[no]render' controls shaded rendering after drawing
'[no]base' controls display of base 'pedestal'
'[no]wrist' controls display of wrist
'[no]shadow' controls display of shadow
'[no]name' display the robot's name
'[no]jaxes' control display of joint axes
'[no]joints' controls display of joints
'movie', M save frames as files in the folder M

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

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.

To save the effort of processing options on each call they can be preprocessed by

opts = robot.plot({'opt1', 'opt2', ... });

and the resulting object can be passed in to subsequent calls instead of text-based options, for example:

robot.plot(q, opts);

Graphical annotations and options

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

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

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

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

Notes

See also

plotbotopt, SerialLink.animate, SerialLink.fkine


SerialLink.plot_options

a cell array of options and return a struct


SerialLink.rne

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.

Notes

See also

SerialLink.accel, SerialLink.gravload, SerialLink.inertia





SerialLink.teach

Graphical teach pendant

R.teach(options) 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.

h = R.teach(options) as above but returns a handle for the teach window. Can be used to programmatically delete the teach window.

Options

'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)
'degrees' Display angles in degrees (default radians)
'q0', q Set initial joint coordinates

GUI

Notes

See also

SerialLink.plot


SerialLink.teach_callback

on changes to a slider or to the edit box showing joint coordinate

src the object that caused the event
name name of the robot
j the joint index concerned (1..N)
slider true if the

Robotics Toolbox for MATLAB © 1990-2012 Peter Corke.