# 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 `mex`

compiler is in your path, it’s located in the `bin`

subdirectory of your MATLAB install. `% mex -v `

shows current `mex`

settings, `% mex -help`

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

## Toolbox is using degrees not radians

If the Toolbox results appear to be using units of degrees not radians try this simple test case.

The correct answer is

`>> rotx(pi/2)`

ans =

1.0000 0 0

0 0.0000 -1.0000

0 1.0000 0.0000

If instead you get

`>> rotx(pi/2)`

ans =

1.0000 0 0

0 0.9996 -0.0274

0 0.0274 0.9996

then you have an installation problem. You are using functions with the same name as Robotics Toolbox for MATLAB functions but which are not from the Robotics Toolbox for MATLAB. The usual culprit is the MATLAB Phased Array System Toolbox. To test this

`>> which rotx`

which shows you the filesystem path to rotx.m. If the path contains something about “Phase Array” then you have a clash. There are two solutions:

- Since most people interested in robotics are not interested in phased array systems you could uninstall that toolbox. Go to the add-on manager and uninstall it.
- Use the pathtool command and move the phase array systems toolbox to the bottom of the list. Then the Robotics Toolbox for MATLAB functions will have priority. This is fine for using the Robotics Toolbox for MATLAB, not so good for running the Phased Array System Toolbox.

## I can’t replicate the results of rotx() or rpy2tr() from the book

See answer above.

# 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

Error using SerialLink/ikine (line 164) Number of robot DOF must be >= the same number of 1s in the mask matrix

The syntax changed between RTB9 (RVC first edition), for example

qcycle = leg.ikine( transl(p), [], [1 1 1 0 0 0] );

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:

- use the ‘nofast’ option when you create the SerialLink object
- 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:

- You are not using the MEX version of RNE, see above.
- 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()`

and`coriolis()`

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.