This directory contains the support for modifing the Scilab/Scicos code 
generation, so that it can be used within RTAI user space soft/hard real time
and monitered with RTAI-Lab.

First of all you have to install RTAI-Lab: please follow the instructions contained in 
the files rtai-lab/README and rtai-lab/INSTALL.

Now you have to download and install the full source Scilab-3.0 release 
from "www.scilab.org", it contains Scicos already.

Follow these steps to properly install all the Scilab/Scicos add-ons for RTAI-Lab:

1) become superuser
2) go in the "macros" directory found here
3) modify in the file "Makefile" the line 
	"SCILAB_DIR = /usr/lib/scilab"
   to fit your SCILAB installation.
 
4) run "make install"

Each user who want to work with the Scilab/Scicos RTAI add-ons has to modify his own ".scilab"
file. This operation can be done running as normal user "make user" in this "macros" directory.
This command add the following lines to the user ".scilab" file:

   load('SCI/macros/RTAI/lib')
   %scicos_menu($+1)=['RTAI','RTAI CodeGen']
   scicos_pal($+1,:)=['RTAI-Lib','SCI/macros/RTAI/RTAI-Lib.cosf']

These lines are important to add the menu "RTAI->CodeGen" to the scicos window and to add the
new RTAI-Lib.cosf library with the RTAI specific blocks to scicos.

The RTAICodeGen_.sci routines call some rtai application during the code generation. In order
to use these applications 

    YOU HAVE TO ADD THE /USR/REALTIME/BIN (or equivalent) DIRECTORY TO THE SYSTEM PATH!!!!!

At this point you are ready to generate code for RTAI, using the new menu 
"RTAI->RTAICodeGen" in the scicos window.

Start the example "test1.cos" to check if your installation is complete:

1) Copy "test1.cos" to a directory (you need write permissions!)
2) Open a shell
3) Go to this directory 
4) Open scilab running "scilab"
5) Give the command "scicos test1.cos" in the scilab window
6) Start "RTAI->Code Gen" in the scicos window and give "OK" on the first
   dialog box

If all is OK you see the "link" command as output on the scilab window

Now you can star the realtime standalone application on the shell:

1) Load the RTAI needed modules (rtai_hal, rtai_lxrt, rtai_fifos, rtai_sem,
                                 rtai_mbx, rtai_msg, rtai_netrpc.o ThisNode="127.0.0.1")
2) go to the directory "test1"
3) start the realtime application using "./test1 -v"
4) open a new shell
5) start the "xrtailab" application, click on connect, open the scopes, the meter and the led
   using the manager windows
6) Open the parameter manager and change some values


Possible known troubles
=======================

- The Code Generation crashes and on the scilab window you see a message such "gen_io not found":
  this happens normally when "/usr/realtime/bin" is not added to the PATH environment variable;
  check with "echo $PATH" if it is setted correcly.

You can allways compile the generated code directly in the "test1" directory using
   make -f test1_Makefile test1

In this case you get more informations about errors by compiling the generated code.

Sensors and actuators library
=============================

The scicos library "RTAI-Lib.cosf" contains a lot of sensors and actuators. Here you can find
different input signals (step, square, sinus, data from a file), sensors and actuators (COMEDI 
drivers) and RTAI-Lab specific blocks (scope, meter, led, mailbox for distributed control).
Users can add own specific blocks following the instructions in the "scilab-howto.pdf" document 
in the "utility" directory.

Roberto Bucher (roberto.bucher@supsi.ch)
Jun 26th, 2004.


========================================================

The RTAI specific Scicos code generation allows you to execute the generated
code in soft/hard real time, monitor its execution and change parameters on 
the fly, both locally and remotely. It shows the power and ease afforded by 
RTAI in setting up a local/distributed processing, by using the "net_rpc"
based "xrtailab".

Many controllers can then be installed, either on a single local computer or 
distributed on local/remote nodes. They all are supervised/monitored with 
RTAI-Lab, thus allowing to manage multiple instance of both Scicos and RTW 
applications. See the related README in RTAI-Lab specific directory.

As mentioned Scicos based applications can be implemented also in a distributed
way. No specific scheme is made available. It is preferred to let each user do 
what he/she wants. As said anything should be easily carried out in the 
sensors/actuators part of the code by using net_rpc support. In violation
to the previous statement a general provision has been embedded for providing
externally generated local/remote timing events. It will be explained further 
on and can be used by way of example for other types of remote coordinations.

A clearer understanding of what is possible to do can be achieved by reading
the explaination of the available execution parameters in the main README.

As it has been said above the Scicos controller driver generator has a native
way to implement the "drevent" option. To use such a feature a controller must 
use the function:
void WaitTimerEvent(unsigned long TimerEventArg). 
In fact WaitTimerEvent is a pointer to such a function and TimerEventArg a 
global variable. As hinted immediatly above they must be set up during 
controller iniatialisation. The local/remote server must provide the conjugate 
function to wake up the controller according to its timing, or any other 
protocol agreed. The function:
void SendTimerEvent(unsigned long TimerEventArg), 
must also be provided by setting the related pointer within the controller. 
Such a function is the very same function used by the local/remote server, 
albeit in local mode. It is required to awake the controller to have it 
smoothly ended asynchonously by the supervisor program.
The default periodic execution comes through the pair: 
rt_task_make_periodic - rt_task_wait_period. 
It allows to have the controller ended by the supervisor without any specific 
event, its termination coming at the next period anyhow.

Paolo Mantegazza (mantegazza@aero.polimi.it)
Roberto Bucher (roberto.bucher@supsi.ch)
Jun 26th, 2004.

