RTAI-Lab
========

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

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    (dozio@aero.polimi.it)
Paolo Mantegazza (mantegazza@aero.polimi.it)
Dec. 22th, 2002.
