General toolbox questions

RST vs RTB?

This site is concerned with the Robotics Toolbox for MATLAB (RTB) an open-source project that brought robotics capability in to MATLAB, and dates back to the mid 1990s.  The Robotics System Toolbox (RST) is a MathWorks product that was introduced in 2015.  There are some videos that explain how it all came to be.

  • RTB is free, open-source and unsupported, but there is an active support community.  You can browse and modify the code as you see fit.  The book Robotics, Vision and Control gives lots of example on how to use it.
  • RST is a product, you pay money and it has technical support, 6-monthly updates and comprehensive documentation.

I have problems with the MATLAB Robotics System Toolbox

You are in the wrong place!  That Toolbox is a MATLAB product, my Toolbox — the Robotics Toolbox for MATLAB — is a much older open-source project that has similarities and differences to the Robotics System Toolbox. See above.

Why are there two robotics toolboxes for MATLAB?

See above.

RTB versions

The major release number goes up after the code undergoes a major upgrade that will break compatibility.  The most recent change was in 2017 from RTB9 to RTB10.  A full history of the changes can be found on the developer page.

RTB9 vs RTB10

These are the two most modern and complete versions of the Toolbox

  • RTB9, released in 2011 is compatible with Robotics, Vision & Control first edition.
  • RTB10, released in 2017 is compatible with Robotics, Vision & Control second edition.  It has many bug fixes, minor changes and a few extensions.  The biggest change is the introduction of classes SO2, SE2, SO3, SE3.

Development, support and bugs

This Toolbox is not a product and development is bursty.  If you’re looking for help your best bet is the Google Support group.

Can I contribute code to the Toolbox?

Absolutely!  There is quite a bit of contributed code already in the Toolbox.  I will give credit to you and you remain the author and copyright holder.

If you contribute  large and complex pieces of code I’d be looking for some agreement that you stay involved and keep it working into the future.  Ongoing changes to MATLAB mean that realistically code will stop working after a few years.

What is MVTB contributed code?

A small number of MVTB functions depend on third party code which is included in contrib. zip or contrib2.zip. These zip files contain snapshots of these code projects that I know work with MVTB.

Since I didn’t author these files, and they have their own licence conditions, the cleanest approach is to distribute as separate zip files. In some cases I provide wrappers within MVTB to make these packages consistent in look and feel with the rest of MVTB. Please note and respect the licence conditions associated with these packages.

contrib.zip supports:

  • igraphseg
  •  imser
  •  vl_kmeans, for bag of words example, Sec 14.7
  •  EPnP, for the CentralCamera.estpose() method, Sec 11.2.3

contrib2.zip supports:

  •  isift
  •  isurf

Installation questions

I can’t unpack the zip file

If the zip archive won’t unpack and/or reports errors, it is most likely corrupt. This can occur if you have a very slow internet connection, and the transfer times out. Try to download the file again.

What is a MEX-file?

MEX-files are written in C or C++ and compiled into a binary module that is dynamically linked by MATLAB at run time. MEX-files can be much faster than the equivalent M-files but the disadvantage is that they are not portable, they must be compiled for the particular platform that you are using.

MEX-files have names that are of the form:

  • function.mexw32 for a 32-bit Windows platform
  •  function.mexglx for a GNU-Linux platform (implicitly x86 based)
  •  function.mexmaci64 for an Apple Mac with a 64-bit Intel processor

To learn more about MEX files and how to create them have a look at this online documentation. For 32-bit Windows MATLAB comes with a simple compiler called lcc but for 64-bit Windows you need to provide your own compiler.

I distribute MEX-files for 64-bit Mac, Linux and 32-bit Windows only.

How do I build the MEX files?

For either toolbox change into its mex folder, that is rvctools/robot/mex or rvctools/vision/mex and execute

make

which will invoke the appropriate compiler. If there are errors then either the mex compiler is not setup correctly, so have a look at the relevant Mathworks documentation.

If you’re a command line kind of person just cd into the mex directory and run make from the command line. This assumes that the mexcompiler is in your path, it’s located in the bin subdirectory of your MATLAB install. % mex -v shows current mex settings, % mex -helpshows various options, and % mex -setup allows configuration. On a *nix or MacOS system these settings are kept in the top-level hidden directory ~/.matlab.

MEX file won’t compile

If you get errors like

make ** building MEX files for MVTB closest.c: En la función ‘mexFunction’: 
closest.c:98:25: error: expected expression before ‘/’ token 
closest.c:102:13: error: expected expression before ‘/’ token 
closest.c:108:21: error: expected expression before ‘/’ token 
closest.c:159:25: error: expected expression before ‘/’ token 
closest.c:163:13: error: expected expression before ‘/’ token 
closest.c:169:21: error: expected expression before ‘/’ token

it’s because your compiler isn’t recognizing the C++ style // comments. Change the line in the makefile from

CFLAGS="-std=gnu99"

to

CFLAGS=-std=c99

This tells the compiler to use C99 standard syntax which allows the C++ style comments.

Compiling MEX files for Windows

If you get errors like

No supported SDK or compiler was found on this computer. For a list of supported compilers, see http://www.mathworks.com/support/compilers/R2013a/win64.html

Error using mex (line 206) Unable to complete successfully.

then you don’t have a C compiler setup properly. Follow the instructions here.

ilabel.m is just comments

There is no mechanism for a binary MEX file to have documentation comments, these are the block of comments at the top of each MATLAB M-file that is given (without the % characters) in response to the help command.

The MATLAB convention is that a MEX-file has a corresponding M-file which contains the help documentation for that file. If you don’t have the MEX-file for your platform then MATLAB will attempt to execute the documentation file (with the .m extension) which it thinks is a script not a function, and this leads to the error message.

The specifed superclass ‘NNNNN’ is invalid or contains a parse error

where NNNNN is the name of some class. The problem is that the file defining the superclass is not in fact a class definition. Typically this occurs if you create a function with the same name as the superclass NNNNN. The easiest way to test for this is

>> which NNNNN

which should show a file within the RVC install directory. If not, you have a name clash, so remove that file or move it to some place not on your MATLAB search path.

Function not defined

Undefined function ‘vgg_XXXXX’ for input arguments of type ‘double’

Download the contributed code zip file from the MVTB download area.

Undefined function ‘Open Surf’ for input arguments of type ‘struct’

Please install contrib2. zip from the MVTB download page.

Errors using isift or isurf

Please install contrib2. zip from the MVTB download page.

Errors using igraphseg, imser, vl_kmeans, EPnP

Please install contrib. zip from the MVTB download page.

Errors using isift or isurf

Please install contrib2. zip from the MVTB download page.

Will the toolbox work with my version of MATLAB?

The Toolbox should work with all version of MATLAB from 2016b onwards.  The MATLAB language and the Toolboxes are constantly evolving, new features are added and over time old features or ways of doing things are removed.

The older version of MATLAB you use the more problems you will likely encounter, and the problem is more acute with Simulink. A list of Toolbox versions is here.

Kinematics

Inverse kinematics doesn’t work!!

Actually it does.  But maybe you need to think a bit more deeply about the problem you are trying to solve.

Inverse kinematics is probably one of the troublesome areas for those starting out with RTB. It’s really important to understand the fundamentals so check out a textbook if this topic is unfamiliar to you, for example Robotics, Vision & Control (chaps 7 and 8.4), Spong etal, or Siciliano etal.

ikine6s()

If your robot has 6 links and a spherical wrist then then the ikine6s() might be appropriate. To test whether your robot has a spherical wrist

>> p560.isspherical
 ans =
 1

which in this case is true, the Puma 560 does indeed have a spherical wrist. The solution in ikine6s() is based on the paper by Paul & Zhang and is quite specific to the Puma 560 kinematics. Other solutions for an anthropomorphic arm manipulator are included in the books by Spong etal and Siciliano etal. The Paul & Zhang solution assumes that the upper and lower arm lengths are given by the DH parameters a2 and d4, whereas Spong and Siciliano assume these are the parameters a2 and a3.

The Puma model is complicated because the shoulder and wrist are offset from the waist rotation axis (by different amounts) which means it can have the lefty and righty configurations. This complexity is not included in the Spong or Siciliano solutions.

Bottom line to use ikine6s() the kinematic model must be Puma-like, with the upper and lower arm lengths given by a2 and d4 and the elbow having a twist (alpha) of -90deg.

ikine()

This method provides a numerical solution and has several advantages:

  • the robot can have an arbitrary number of axes, including under- and over-actuated
  • the robot can be at a singularity

The disadvantages are that it is an iterative algorithm which means that it can be slow and may not converge, and you cannot control which configuration.

Some tips to make it work well:

  • try to choose a good initial set of joint angles, that is, as close as possible to the desired solution
  • if the initial joint angles result in a singularity the search will not converge quickly. This is not catastrophic but something to be aware of.

If your robot is Puma-like you are much better off using the ikine6s() method.

For robots with 4 joints have a look at this article.

Number of robot DOF must be >= the same number of 1s in the mask matrix

If you get this message
Error using SerialLink/ikine (line 164)
Number of robot DOF must be >= the same number of 1s in the mask matrix
then you are using ikine() incorrectly.  Most likely you are using the Robotics, Vision & Control first edition with RTB10.
The syntax changed between RTB9 (RVC first edition), for example
    qcycle = leg.ikine( transl(p), [], [1 1 1 0 0 0] );
and RTB10 (RVC second edition).
    qcycle = leg.ikine( transl(p), 'mask', [1 1 1 0 0 0] );

Can the Toolbox handle parallel manipulators?

No, it cannot.

maniplty() gives a different answer to the book

The value returned for the example on page 180 of the RVC book first edition, is different to what RTB returns. This is a change to the default argument for the function maniplty().

Manipulability has two components: rotational and translational. Rotation has units of radians, ie. numbers in the range 0-3, whereas translation has numbers in the range that depends on the size of the robot and the units you use, they might be very big numbers in the range 0-1000 (in mm) or small 0-0.5 (in m). So it makes no sense to add them which is what maniplty() used to do. Now the default is to return manipulability for just the translational motion

>> p560.maniplty(qn, 'yoshikawa')
ans = 0.1112

not 0.0786 as per the book.

You can also specify explicitly the translational manipulability

>> p560.maniplty(qn, 'yoshikawa', 'T') 
ans = 0.1112

or you can ask for the rotational manipulability, how easily the tool orientation can change

>> p560.maniplty(qn, 'yoshikawa', 'R') 
ans = 2.4495

or the old behaviour

>> p560.maniplty(qn, 'yoshikawa', 'all') 
ans = 0.0786

Dynamics questions

rne() is really slow

The recursive Newton-Euler algorithm is computationally intense. By default RTB looks for a MEX file (see above) and if it’s found it will be indicated when the SerialLink object is displayed, in parentheses above the DH parameter table

mdl_puma560 p560

p560 =

Puma 560 (6 axis, RRRRRR, stdDH, fastRNE)
 viscous friction; params of 8/95;
 +---+-----------+-----------+-----------+-----------+ | j | theta | d | a | alpha | +---+-----------+-----------+-----------+-----------+ | 1| q1| 0| 0| 1.571| | 2| q2| 0| 0.4318| 0| | 3| q3| 0.15| 0.0203| -1.571| | 4| q4| 0.4318| 0| 1.571| | 5| q5| 0| 0| -1.571| | 6| q6| 0| 0| 0| +---+-----------+-----------+-----------+-----------+

grav = 0 base = 1 0 0 0 tool = 1 0 0 0
 0 0 1 0 0 0 1 0 0
 9.81 0 0 1 0 0 0 1 0
 0 0 0 1 0 0 0 1

Note fastRNE in this example.  This means the algorithm will use the optimised RNE code which is as fast as you can get on your computer.

If this flag is not set, then RTB couldn’t find the MEX file, use the instructions above to build it.

If you really don’t want to use the MEX file you have a few options:

  1. use the ‘nofast’ option when you create the SerialLink object
  2. change the flag in the SerialLink object
>> p560.fast=false
p560 =
Puma 560 (6 axis, RRRRRR, stdDH, slowRNE)
 viscous friction; params of 8/95;
 +---+-----------+-----------+-----------+-----------+ | j | theta | d | a | alpha | +---+-----------+-----------+-----------+-----------+ | 1| q1| 0| 0| 1.571| | 2| q2| 0| 0.4318| 0| | 3| q3| 0.15| 0.0203| -1.571| | 4| q4| 0.4318| 0| 1.571| | 5| q5| 0| 0| -1.571| | 6| q6| 0| 0| 0| +---+-----------+-----------+-----------+-----------+

grav = 0 base = 1 0 0 0 tool = 1 0 0 0
 0 0 1 0 0 0 1 0 0
 9.81 0 0 1 0 0 0 1 0
 0 0 0 1 0 0 0 1

My robot arm dynamics simulation in Simulink is really slow

This is exhibited by the fdyn() function or the Robot block in Simulink.  There are two common causes of this:

  1. You are not using the MEX version of RNE, see above.
  2. You have non-linear friction, specifically Coulomb friction in your model. This is a very harsh non-linearity and the integrator in Simulink adopts very small step sizes to cope with it.

The default Puma 560 model includes Coulomb friction. You can make a friction free version of that robot model by

>> p560_ff = p560.nofriction();

The viscous (linear) friction is retained.

How does the gear ratio work?

The torque model is perhaps not ideal, it’s kind of evolved.

The basis of all dynamics code is the RNE function which gives the torque required to achieve a particular qd and qdd for a certain q. All quantities are referred to the link/load. This torque includes link dynamic effects (inertia, coriolis, gravity) as well as motor inertia, motor viscous and Coloumb friction (given in motor frame but transferred according to gear ratio).

Bottom line:

  • torques are always link/load referenced
  • q and its derivatives are link/load referernced
  • frictions and motor inertia are motor referenced.

Torque/force components

The function rne() gives the torque required to achieve a particular qdd for a certain value of q and qd, ie. if you apply that torque at that joint angle and speed you will achieve the acceleration.

The toolbox also allows you to compute torque components:

  • inertial torque is I = robot.accel(q) * qdd
  • Coriolis/centripetal torque is C = robot.coriolis(q, qd) * qd'
  • gravity torque is G = robot.gravload(q) 
  • friction torque is F = robot.friction(qd)

The total torque balance is I+C+G-F = tau and note the negative sign on friction.

Symbolic operations

Can I perform symbolic calculations?

Yes, MATLAB makes that really easy.  For example:

>> syms r p y 
>> rpy2r(r, p, y)
ans =
[ cos(p)*cos(y), -cos(p)*sin(y), sin(p)] [ cos(r)*sin(y) + cos(y)*sin(p)*sin(r), cos(r)*cos(y) - sin(p)*sin(r)*sin(y), -cos(p)*sin(r)] [ sin(r)*sin(y) - cos(r)*cos(y)*sin(p), cos(y)*sin(r) + cos(r)*sin(p)*sin(y), cos(p)*cos(r)]

For a robot manipulator

>> mdl_twolink
>> syms q1 q2 
>> twolink.fkine([q1 q2])
ans =
[ cos(q1 + q2), -sin(q1 + q2), 0, cos(q1 + q2) + cos(q1)] [ sin(q1 + q2), cos(q1 + q2), 0, sin(q1 + q2) + sin(q1)] [ 0, 0, 1, 0] [ 0, 0, 0, 1]

Other functions like rne(), inertia(), gravload() andcoriolis() work as well however if symbolic variables are used they automatically enforce use of the slower MATLAB version of rne().

How do I get started with the symbolics and code generation functionality?

An example to get started with symbolics and generation of m-code as well as real-time capable Simulink blocks is given in rtsymcgendemo.m. To run the demo type the following on the command line:

>> rtsymcgendemo

or start it from the Robotics Toolbox demos in the help browser.

What code can be generated using the code generator module?

By default the code generation module produces robot specific and ready to use m-functions as well as Simulink blocks. The Simulink blocks are real-time compatible. The automated generation of robot specific C-code and C-MEX functions is a new feature of release 9.9.

Plotting

plot doesn’t work for robot with prismatic joint(s)

The plot() method uses a simple heuristic to figure out how big to make the axes that can hold the robot for every joint angle configuration. For this to work you must provide one of two things:

  • for each prismatic joint provide the minimum and maximum extension of the joint in the link structure, for example
      L(3).qlim = [1 2];
  • provide the information about the size of the workspace, using the ‘workspace’ option to the plot() method.

How to plot 3D solid models of robots?

Use the method plot3d() instead of plot().  This capability only exists for robots that have ASCII STL models of the links.  Each robot is described by a folder containing files named link0.stl, link1.stl and so on. A great source of such models is ARTE by Arturo Gil.

RTB ships with a subset of the ARTE models and they are located in the rvctools/robot/data/ARTE.  For example the Puma560 models are in the folder rvctools/robot/data/ARTE/UNIMATE/puma560.  The SerialLink object contains a reference to the folder holding the STL files

>> mdl_puma560
>> p560.model3d
ans =
UNIMATE/puma560

If you have a custom robot then you will need to place the STL model files into a folder in rvctools/robot/data/ARTE and ensure that the model3d property of the SerialLink object points to it.

 

Documentation about the Toolboxes

The RVC book and the online documentation are the definitive sources of information about usage. Online documentation includes:

  • help information available from inside MATLAB
     >> help tr2eul
  • documentation information from inside MATLAB, with more formatting and cross linking
     >> doc tr2eul
  • the online HTML documentation
  • the 200 something page PDF manual available as rvctools/robot/robot.pdf or rvctools/vision/vision.pdf

All of this documentation comes from the one source, the comments at the beginning of each m-file. They are written in a very simple markup language inspired by reSt and pydoc. A bunch of Python scripts turn that raw information into HTML and PDF format documentation. This means that the documentation is fairly dry and concise. More explanation with figures and examples is provided in the RVC book.

Citing the Toolbox

Please cite the RVC book if you want to acknowledge the Toolboxes in your work:

P. I. Corke. Robotics, Vision & Control: Fundamental Algorithms in MATLAB. Springer, second edition, 2017. ISBN 978-3-319-54412-0.

or in BibTeX format:

@book{Corke17a,
Author = {Peter I. Corke},
Edition = {Second},
Keywords = {own},
Note = {ISBN 978-3-319-54412-0},
Publisher = {Springer},
Title = {Robotics, Vision \& Control: Fundamental Algorithms in {MATLAB}},
Year = {2017}}

A robotics toolbox for MATLAB (1996)

This paper was published in 1996 in the IEEE Robotics & Automation magazine. It provided a tutorial approach to solving arm robot problems using v4 of the toolbox. The names and syntax have changed dramatically since then, so if you try those examples with the current toolbox you will have problems.

Please consider this article an historic artefact not a reference. The RVC book and the online documentation are the definitive sources of information about usage.

Support for other languages

Is there a Python version of the toolbox?

There is a partial Python 3 port of RTB10.  This includes:

  • the transform classes SO2, SE2, SO3, SE3
  • Link and SerialLink classes with forward kinematics, plotting and some robot models

It can be simply installed using

pip install robopy

and has dependencies on VTK, Numpy and Scipy.

If you want to contribute to this project visit adityadua24 on GitHub.

Will the toolboxes work with Octave?

Yes and no!  GNU Octave is free mathematical software that has many similarities to MATLAB and runs under Windows, MacOS and Linux. There are a lot of minor differences between MATLAB and Octave, though less than there used to be.  Simple stuff works just fine:

octave:1> rotx(0.2)
ans =
   1.00000   0.00000   0.00000
   0.00000   0.98007  -0.19867
   0.00000   0.19867   0.98007

octave:2> vex(ans)
ans =
   0.19867
   0.00000
   0.00000

octave:3> rpy2tr(1,2,3)
ans =
   0.41198  -0.83374  -0.36763   0.00000
  -0.05873  -0.42692   0.90238   0.00000
  -0.90930  -0.35018  -0.22485   0.00000
   0.00000   0.00000   0.00000   1.00000

Classes like SO2, SE2, SO3, SE3, Quaternion, UnitQuaternion, Link, SerialLink don’t work but the errors are due to relatively localised MATLAB specific code and could be worked through.  The syntax of MATLAB classes is now supported by Octave (since v4).

A subset of an old version of RTB that includes those functions that deal with arm-type robots exists. To enable this functionality go into the folder rvctools/Octave and follow the instructions in the README.txt file.

Is there a SciLab version of the toolbox?

Yes there is!  Check out Davide Cappucci’s  Robotics Toolbox for SciLab.

Can I use the Toolbox with National Instruments LabVIEW?

LabVIEW has a robotics module and the Robotic Arm capability was ported from the MATLAB Robotics Toolbox.