RTSS - The Robotics Toolbox for Scilab/Scicos
=============================================
version 0.1.0
=============
Matteo Morelli, May 2007.
$LastChangedDate: 2007-10-04 12:23:28 +0200 (Thu, 04 Oct 2007) $.
********************************************************************************
0 - COPYRIGHT NOTICE
====================
RTSS, the Robotics Toolbox for Scilab/Scicos, is free software released under
the terms of the GNU General Public License.
See the included license: "license.txt" in English.
********************************************************************************
I - INSTALL THE ROBOTICS TOOLBOX FOR SCILAB/SCICOS
==================================================
A - INSTALL THE SOURCE VERSION
------------------------------
The requirements for installing RTSS from source code are the following:
a - Scilab.
RTSS runs with the Scilab 4.x family. Your Scilab can be whether a
stable version (source, binary file) or a development version (SVN).
b - C Compiler.
The source version of RTSS contains several .c files that must be
compiled (see the section: "V - TOOLBOX COMPOSITION", below) as a shared
library.
A typically adopted compiler is Microsoft Visual C++ 2005 Express
Edition, which is downloadable for free -- for non-commercial use -- at
this web page:
<http://msdn2.microsoft.com/en-us/express/aa700735.aspx>
However, note that it must be integrated with Microsoft Windows Server
2003 R2 Platform SDK in order to get a workable compilation environment.
The Platform SDK can be downloaded at this web address:
<http://msdn2.microsoft.com/en-us/express/aa700755.aspx>
Others widely adopted compilers are Microsoft Visual C++ .NET 2003,
Microsoft Visual C++ 6.0 and lcc-win32.
The 3 steps that follow must be performed when you only have to install the
toolbox (i.e. one time only). If you already have installed the toolbox,
skip to the next section:"II - LOAD THE ROBOTICS TOOLBOX FOR SCILAB/SCICOS".
1 - Unpack file rtss-0.1.0-src.zip in your SCI directory.
SCI denotes the location where your Scilab is installed. If you don't
know where your Scilab is installed, just type SCI at Scilab prompt. For
example, in my Windows Xp PC, SCI is C:\Program Files\scilab-4.1\.
You will get a folder called robot, but you can give the folder any name
provided that it does not contain any spaces. Indeed, from now on the
path SCI\robot\ will be referred to as <PATH>.
2 - Change the options that will be used to compile RTSS.
Open files <PATH>\src\buildsrc.sce and
<PATH>\sci_gateway\buildsci_gateway.sce and change the value of their
cflags variable to use platform-specific compilation options.
3 - Build RTSS.
Open the Scilab prompt and type the following command:
exec <PATH>\builder.sce;
This will build RTSS and will create html help pages for its Scilab
functions and Scicos Blocks.
B - INSTALL THE PREBUILT VERSION
--------------------------------
The prebuilt distribution is for 32-bit systems only. The DLL files were
compiled with Microsoft Visual C++ 2005 Express Edition.
The only requirement for installing the prebuilt version of RTSS is to have
Scilab installed. RTSS runs with the Scilab 4.x family. Your Scilab can be
whether a stable version (source, binary file) or a development version
(SVN).
The 2 steps that follow must be performed when you only have to install the
toolbox (i.e. one time only). If you already have installed the toolbox,
skip to the next section:"II - LOAD THE ROBOTICS TOOLBOX FOR SCILAB/SCICOS".
1 - Unpack file rtss-0.1.0-win32.zip in your SCI directory.
SCI denotes the location where your Scilab is installed. If you don't
know where your Scilab is installed, just type SCI at Scilab prompt. For
example, in my Windows Xp PC, SCI is C:\Program Files\scilab-4.1\.
You will get a folder called robot, but you can give the folder any name
provided that it does not contain any spaces. Indeed, from now on the
path SCI\robot\ will be referred to as <PATH>.
2 - Build the Scilab macros in RTSS.
Open the Scilab prompt and type the following command:
exec <PATH>\builder.sce;
This will build the Scilab macros in RTSS (i.e. the functions written in
Scilab code with the extension .sci) and will create html help pages for
its Scilab functions and Scicos Blocks.
********************************************************************************
II - LOAD THE ROBOTICS TOOLBOX FOR SCILAB/SCICOS
================================================
Open the Scilab prompt and type the following command:
exec <PATH>\loader.sce;
This will load the toolbox into Scilab. You must type this command in every
Scilab session that you want to use the toolbox.
Note that, as the final user, you may want RTSS to be loaded automatically. To
do this just put the above command in your SCI\scilab.star startup file for
automatic loading.
An additional caveat: if somewhere in your scilab session you run the clear
command, you will have to reload the toolbox. To avoid that, you can add the
command predef('all') in your SCI\scilab.star file after your
exec <PATH>\loader.sce command.
As an example, below is the sequence you could do on your own machine for
automatic loading:
1 - open SCI\scilab.star file with your favorite text editor.
2 - Add the following line at the end of SCI\scilab.star:
exec <PATH>\loader.sce;
3 - Add the following line after your exec command:
predef('all');
4 - save the SCI\scilab.star file.
That's it! Every time you enter scilab it already loads RTSS and even if you
run the clear command you won't have to reload the toolbox anymore.
********************************************************************************
III - REMARKS
=============
The purpose of this first release of the Robotics Toolbox for Scilab/Scicos
was to make a port to Scilab/Scicos of the original Robotics Toolbox for
MATLAB written by Professor Peter I. Corke. Though I've tried to maintain the
compatibility between the two toolboxes (in terms of functions Calling
Sequences and in terms of functions behaviour) as more as possible, some
differences have arisen anyway and you will have to keep them in mind when you
will use this toolbox (particular attention should be paid to the item 5 in
the list of differences, below).
1 - Names of functions.
All functions in the MATLAB toolbox which have an *overloadable* Scilab
counterpart (i.e. display, double, inv and norm) have maintained their
name. This means that, with RTSS, if q is a quaternion object it can be
displayed by
-->disp(q),
and its norm and its inverse can be computed by
-->norm(q),
-->inv(q),
respectively. On the contrary, *all the other function names* are preceded
by "rt_" (where rt stands for Robotics Toolbox). This means that
MATLAB-name Scilab-name
link has become rt_link
robot has become rt_robot
fkine has become rt_fkine
plot has become rt_plot
fdyn has become rt_fdyn
and so on.
This is due to the fact that functions such as link and plot do already
exist in Scilab and are unoverloadable functions. Thus, rather than rename
these two functions only (for istance with exotic names such as createlink
and plotobject), I've choose to rename all in this simple way: just add
the "rt_" prefix to the name of the function you would use in MATLAB.
2 - Names of variables.
When you create a Puma robot (either based on SDH and MDH notation) with
the MATLAB toolbox you also define the joint coordinate vectors qz, qr and
qstretch corresponding to the zero-angle, ready and fully extended poses.
With RTSS qr becomes qready.
3 - The link parameter of a robot object.
With the MATLAB toolbox you can reference the link field of a robot
object, r, either by command
>>r.link,
and by
>>r.links,
With RTSS you can only use the latter form, that is
-->r.links,
4 - The handle parameter of a robot object.
With the MATLAB toolbox you can reference the handle field of a robot
object, r, either by command
>>r.handle,
and by
>>r.handles,
With RTSS you can only use the latter form, that is
-->r.handles,
5 - The variable assignment operator (=).
With the MATLAB toolbox you can quickly clone a quaternion, a link and a
robot object, respectively q, l and r, by the following commands
>>q2 = q;
>>l2 = l;
>>r2 = r;
With RTSS you can not.
This is because constructors call C coded functions to create quaternion
link and robot objects. These functions (m)allocate memory for Quaternion,
Link and Robot structures and return *pointers* in the Scilab workspace.
This means that, for istance, after you give the following command
-->r2 = r;
r2 points *the same* portion of memory referred by r.
To correctly use Scilab objects such as quaternions, links and robots, you
have to take them just like pointers. For a better understanding of this
aspect, you may consider the following diagram:
Scilab Prompt | Memory
|
| /
| Scilab \ Heap Memory
| Workspace /
| \ #ROBOT # #LINKS #
| / #DATA # ---> #DATA #
-->r=rt_robot(<PARAMS>); | r _____ \___#STRUCT# #STRUCT#
| / | ||...|
-->r2 = r; | r2 ______\______| ||...|
| / ||...|
-->L = r2.links; | L(1)______\__________________||...|
| L(2)______/___________________|...|
| \ . |
| / . |
| \ . |
| L(n)______/_______________________|
| \
Taking a look at the diagram above, it's easy to understand that
-->r2.base = <VALUE>; //will change also the value in r.base!
-->r2.name = <VALUE>; //will change also the value in r.name!
-->r.gravity = <VALUE>; //will change also the value in r2.gravity!
-->L(1).A = <VALUE>; //will change length of 1st link in r and r2!
So, if you want to know, among the other things, how to clone a robot
object with RTSS, please read the following list of RTSS how-tos.
a - How to clone a robot object.
MATLAB Scilab
>>r2 = r; -->r2 = rt_robot(r);
or
>>r2 = robot(r);
b - How to create a robot clone with modified constituent links.
MATLAB Scilab
>>L = r.links; -->r2 = rt_robot(r);
>>L{1}.A = <VALUE>; -->L = r2.links;
>>r2 = robot(r, L); -->L(1).A = <VALUE>;
c - How to modify link parameters without create a new robot.
MATLAB Scilab
you can't do it. -->L = r.links;
-->L(1).A = <VALUE>;
********************************************************************************
IV - DOCUMENTATION
==================
Detailed XML help documentation, written in English language and in compliance
with the Scilab Toolbox Guide, is provided for each Scilab function and Scicos
block in the toolbox. Every help page is enriched with many examples which
illustrate the usage of the corresponding Scilab function or Scicos block.
During the RTSS installation process, XML pages are translated to HTML so that
the user can consult them by using the Scilab Help Browser.
RTSS comes with several demonstration scripts which show how the toolbox can
be productively used in studying robotics. Demos on subjects like
a - Homogeneous Transformations
b - Cartesian and joint-space Trajectories
c - Forward and Inverse Kinematics
d - Differential Motions and Manipulator Jacobians
e - Forward and Inverse Dynamics
f - Graphical Animations of Robot Motions,
can be run individually by choosing "Robotics" in the Scilab demo menu.
Other demos are provided with RTSS.
g.1 - Dynamic simulation of Puma 560 robot collapsing under gravity;
g.2 - Computed torque control of a Puma 560 robot;
g.3 - Open-loop inverse Jacobian algorithm for a three-DOF (RRR) planar arm;
g.4 - Closed-loop inverse Jacobian algorithm for a three-DOF (RRR) planar
arm;
g.5 - Jacobian pseudo-inverse algorithm for a kinematically redundant RRR
planar arm;
g.6 - Jacobian pseudo-inverse algorithm for a kinematically redundant RRR
planar arm, with mechanical joint limit constraints.
They give the user an insight into the use of RTSS for constructing robot
kinematic and dynamic models with Scicos, but currently there is no detailed
documentation about them available. At the moment, the only documentation I
can provide is a short pdf file in the <PATH>\etc\ directory. However, a
detailed RTSS User's Guide is in progress and it will be included in the next
(major?) release.
Lastly, the user can run test scripts which permit to compare performances
between the Scilab and C version of algorithm that computes inverse dynamics
via recursive Newton-Euler formulation (RNE), for the following robot models:
a - Puma 560
b - Stanford Arm
Again, there is no detailed documentation about them available yet. At the
moment, the only information provided comes from comments that the scripts
display on screen.
Test script for the Puma 560 can be executed by typing the following command
at Scilab prompt:
exec <PATH>\unit-tests\rt_pumacheck.tst;
Test script for the Stanford Robot Arm can be run with the following command,
instead:
exec <PATH>\unit-tests\rt_stanfcheck.tst;
********************************************************************************
V - TOOLBOX COMPOSITION
=======================
The root directory contains 10 sub-directories:
1 - includes
Headers (all .h files).
2 - src
Source code (all .c files), shared libraries (prebuilt distribution only),
buildsrc script.
3 - sci_gateway
Interfaces programs (all .c files), shared libraries (prebuilt
distribution only), buildsci_gateway script.
4 - macros
Scilab macros (all .sci files), buildmacros and loadmacros scripts.
5 - models
Scilab scripts (all .sce files) which create models of well known robots.
6 - scicos_palette
The Robotics Palette (.cosf file), loadpalette script.
7 - help
English help sub-directory named eng which contains all the .xml help
files, buildhelp and loadhelp scripts.
8 - unit-tests
Scilab scripts to test the toolbox (.tst files).
9 - demos
Different examples to illustrate the toolbox.
10 - etc
Short explanation of the Scicos demos that are provided with the toolbox
(.pdf file).
and 4 files:
1 - builder.sce
The main builder script.
2 - loader.sce
The main loader script.
3 - README_Win.txt
This file. Notes about toolbox description and installation.
4 - license.txt
Text of the GNU General Public License Version 2, under which the toolbox
is distributed.
********************************************************************************
VI - AKNOWLEDGEMENTS
====================
I, the author, wish to thanks Professor Peter I. Corke, who kindly allowed me
to modify part of his work and redistribute it under the terms of the GNU
General Public License.
I want also to thanks my supervisor, Professor Antonio Bicchi, for his endless
patience, support and guidance.
Finally, I would like to thanks all the people in the Scilab Newsgroup, who
generously helped me in all my efforts with helpful suggestions and comments,
especially Dr. Ramine Nikoukhah, Dr. Serge Steer, Dr. Francois Vogel,
Dr. Enrico Segre and Dr. Allan Cornet.
********************************************************************************
THAT'S ALL FOLKS
********************************************************************************
Download Latest Version
rtss-1.0.0b1-win32.zip (2.4 MB)
