RTAI-Lab is a tool that allows to integrate the execution of any suite of
real time controllers/simulators automatically generated by
Matlab/Simulink/RTW, hereafter addressed as RTW, and/or Scilab/Scicos/CodeGen,
addressed as SCICOS:
- in a local/remote/distributed way,
- monitor their local/remote/distributed execution,
- change their parameters on the fly for performance supervision, monitoring,
tuning and optimisation.
The basic concept of RTAI-Lab is to allow any couple of two separated
systems, the host and the target, to communicate. In a remote implementation,
the host is the machine where RTAI-Lab is executing in soft real time,
the target is the machine where the generated hard real time codes run.
Using "net_rpc" APIs the host send/receives messages, requesting the target
to accept parameters changes and exchanges signals data for graphical
displaying and file logging using mailboxes. This basic scheme can be
extended by running many controllers on the same target as well as many
RTAI-Lab sessions on the same host, to monitor and interface many targets
simultaneously. The host and the target can be the same machine.
Such a scheme has the capability to generate and distribute real time codes,
by simply providing a library of I/O blocks, embedding "net_rpc" directly in
the code generators. In such a way a user can build as many Simulink/Scicos
models as he/she likes and downloads each one onto any target machine.
Each model will contain the I/O blocks required to synchronize and communicate
with other parts of the distributed real time control system thus allowing
distributed applications. The hinted IO blocks will likely be specific RTW
S-functions and SCICOS code included in users SCICOS template sensors/actuators
So the making of such distributed applications can be an easy task, but
you have to set up the related policy and support it your own way using
"net_rpc" APIs. In any case the wealth of distributed APIs made available
by "net_rpc" should pose little or no limitation to what can be done.
At the moment a simple example of a possible distributed application is
available in ./scilab/examples/pid, have a look there for something more.
It is likely a variety of such support functions will become available as
the use of RTAI-Lab expands.
As said RTAI-Lab is already structured to work for monitoring and changing
parameters for a mix of applications using multiple, possibly mixed, instances
of both RTW and SCICOS, running on a single or multiple machines.
The monitoring and parameter changes can be done either locally or remotely.
Signal can be watched by means of multitraces scopes, whose traces can be
logged to a file also. A specific support is available also to monitor and
log data not related to time histories.
User acquainted with RTW external mode will more or less find the same way of
working under RTAI-Lab, naturally with the mentioned advantage of being able
to run both distributed multiple RTW and SCICOS and RTAI-Lab applications.
For further informations refer to specific READMEs within the specific
"matlab" and "scilab" directories found here.
There are 2 versions of the monitor/supervisor program:
- a very simple alpha mode to be run on any screen, i.e. both aplhanumeric
consoles and xterminals (rtailab);
- a graphic mode to be run under xterminals only (xrtailab).
The former is made under the name "rtailab" the latter as "xrtailab". To make
"xrtailab" you need to have both FLTK and OPENGL installed on your computer,
telling the path to them in the Makefile in this directory. They should be
available in any of the Linux distribution, their installation being simple
anyhow, i.e. even if they must be recovered from their home sites.
The usage of "(x)rtailab" should come self explained by looking at the
various buttons captions in "xrtailab" and by reading the, somewhat rough
but understandable, alpha menus of "rtailab".
Production work will likely be done under "xrtailab" mostly, while "rtailab"
might be useful to start/stop and quickly change parameters from anywhere.
Another use of "rtailab" is in making it easier debugging and testing, as it
allows to properly divide problems coming from the basics of the various RTAI
tools used from specific problems related to the FLTK/OPENGL interface of
"xrtailab". That is possible because both are using the same structure and
interface to "net_rpc", to receive/send what has to be exchanged with the
control application. A further help could come from the simpler "rtailab"
when one needs to set up an interaface to tuning an monitoring that must be
embedded in a specific user application. It is then simple to cut and paste
what is needed from "rtailab" in such a case, without being encumbered by the
somewhat deceiving code used in "xrtailab" to interface to FLTK C++ APIs.
RTAI-Lab has been used already at DIAPM but it might be possible that its
commit to the RTAI CVS still needs some tuning. Its testing has been mostly
done by using LXRT under UP and NEWLXRT-NOBUDDY under MP.
To execute an RTW/SCICOS controller you have to run what generated by them
using your chosen options. Their explanation can be of help in further
understanding what you can do. Apart from the standard options:
-u, --usage: to print a quick usage help;
-v, --verbose: to ask for a more extensive output;
there are those more relevant to the controller modes of executions.
So it is possible to specify:
-s, --soft: to run the controller in soft real time, to ease initial
debugging and checking;
-w, --wait: to have the execution started by the supervisor program,
default is immediate execution;
-p, --priority: the priority of the controller real time task, default is the
highest priority of an RTAI task (0), recall that the highest
priorities have the lowest numbers under RTAI;
-r, --samptime: controller period, in microseconds. A default is nonsense but
one is provided anyhow: 10000 (us), this option is for use
with SCICOS only, RTW embeds its sampling time in its
generated code and does not allow changing it, with SCICOS
instead you can assign it when the controller is started,
without generating its code again, clearly you might have
to change some parameters before activating it, but that is
possible through the parameter tuning offered by "(x)rtailab";
-f, --finaltime: a possible time to have the controller end its execution
without any external intervention, default is never end and
you can stop the controller using "(x)rtailab", a case where
using the simpler "rtailab" might suffice;
-m, --stackinc: a preincrement of the stack before locking the controller
into memory, to avoid possible page faults, default is set
to varying values in rtmain.c for RTW/SCICOS, try changing
it to fix any page fault that might occur during preliminary
testing, it is somewhat difficult to hint to any value
without a thorough look at the generated code, on today PCs
it should not be difficult to stay on the safe side by using
a relatively large conservative value;
-n, --name: a six alphanumeric identifier of the controller, following
the short six carachters names ids rule used in (NEW)LXRT,
default is "IFTASK", this option is compulsory if you want
to run and monitor multiple controllers, in the case of a
single one it might be changed only if the used default
"tastes" bad to you, recall also that short name ids do
not distinguish between small and upper case letters, so
"IFTASK" and "iftask" are he same;
-i, --mbxid: up to three alphanumeric carachters, root identifier for the
scope mailboxes, default is "RTS", "rts" being the same, so
because of the short naming ids used by (NEW)LXRT there can
be "only" 999 scopes per controller, any further comment is
as for the controller name above;
-t, --clocktick: if non zero the hard timer will run in periodic mode, the
default is oneshot mode, it is the tick giving the resolution
to be used when using the hard timer in periodic mode, all
controller tasks executing on a machine must conform,
RTW controllers run in such a way by default so this option
is compulsory if you are mixing RTW with SCICOS as SCICOS
must comply accordingly, either if it is run first, in such
a case it must be installed with a hard periodic timer using
the ticking of RTW, or if it is added afterward, to adhere
to what RTW as imposed already;
-e, --drevent: to have a controller timed by an external source, either
local or remote, the external application in charge of it
must act in agreement with what the controller will set up,
likely in the sensors/actuators initialisation phase, the
default is a periodic execution timed by the local computer
hard timer used by RTAI schedulers, at the moment this
option is available just for SCICOS applications, see its
specific directory found here for further comments;
-c, --cpumap: the map of the CPU on which to run the controller on multi
processors machines; a single bit has to be set, so it is
a power of 2 always, for SCICOS and single tasking RTW
applications there nothing more to be said, for RTW multi
tasking this option forces just the base rate task to the
assigned CPU all other task will then be equally distributed
to all the available CPUs by RTAI.
RTAI-Lab relies, fully and only, on "net_rpc" support to allow interoperability
of local/remote/distributed usage. As such "(x)rtailab" allows you to configure
your server by setting its "name" and "mbxid" pointed out above, as well as the
remote node address, in dotted decimal notation, i.e. xxx.xxx.xxx.xxx.
Then according to "net_rpc" usage in local mode you can set your node to the
local host, 127.0.0.1 is the default in "(x)rtailab", or to zero. In the latter
case there will be no "net_rpc" usage, but it must be insmoded anyhow to
satisfy references to its, unused, entries. It is recalled that using a zero
node implies direct calls to local RTAI APIs and it is thus the optimal usage
for a host that is on the same machine as the target, the use of local host
being mostly for dubugging and checking "wonna be" distributed applications.
A further remark relates to the net support used. In relation to that you can
rely either on the "rtnet" Linux emulation ditributed with RTAI or download the
true RTNet support. The latter will likely afford improved performances and
become compulsory if you want to embed the monitoring in a custom hard real
time interface of yours, as previously suggested.
As it has been said RTAI-Lab has beed used at DIAPM already but for its release
in the RTAI CVS it is still to be intended as a beta test. For this reason
there is no change and it is not included yet in the RTAI configuration and
making. It has to be made specifically from within here. Its make file should
nonetheless be fully configured to work from within RTAI, as it is in the CVS,
and thus is expected that it can be used also by copying this directory into
any of the most recent RTAI official releases.
Lorenzo Dozio (firstname.lastname@example.org)
Paolo Mantegazza (email@example.com)
Dec. 22th, 2002.