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.
To use it you have to download the full source Scilab release from 
"www.scilab.org" and install it. It contains Scicos already. You'll have to 
download its CodeGen toolbox also; it can be found within the contributions 
addressed at Scilab site. 

Then:
- install Scilab;
- untar the CodeGen tarball in the Scilab directory "contrib";
- duplicate CodeGen with another name, if you want to keep the original with 
  the one to be used for RTAI only;
- edit "gen_make.sci", in the "macros" directory found here, to modify the 
  line: "RTAIDIR = <RTAI home dir>" so that your RTAI home directory is known 
  to the code generation.
- edit the DEST macro, in "macros/copyto" found here, to point to the Scilab 
  code generation directory that will be used to support RTAI;
- do ./copyto

At this point you are ready to generate code for RTAI, in the very same way 
used for the original Scilab/Scicos CodeGen. Scicos generated code is structured
with names in the form "modelname_......", "modelname" being the identifier of 
the model. 
With RTAI you must make and use what generated as "modelname_standalone". 
As said the overall RTAI specific procedure is not different than the standard 
Scicos CodeGen way. So refer to Scicos and CodeGen docs for more informations.

It must be noticed however that the code generator knows nothing about the IOs 
that will be used in the actual execution. So it generates just a related void
template function that must be completed according to what it has to be done. 
Such a function, "modelname_void_io.c", will remain unchanged till any 
input/output is changed in the model. Thus "modelname_standalone.c" does not 
use it but expects to find a function modelename_io.c that carries out the real 
working code. Then, at the very first code generation or whenever any 
input/output is changed, the user must care of coping modelname_void_io.c 
into modelname_io.c, adding whatever code needed for the application at hand. 
If nothing, but the mere coping, is done the code will run without any 
"visible" effect. So there is no doubt that you'll have to do something if 
the code has to be used with some external hardware, but even simple tests 
require something be done, to produce anything "visible".

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

By way of example an execution and parameter supervisor, param.c, and data
monitor, scope.c, are included.

Param.c allows you to start the execution of the generated code by assigning:
- new parameters before start up;
- its period of execution;
- the pacing clock start/stop request;
- soft/hard mode execution;
- stack expansion, if needed.
The clause related to starting/stopping the timer is included to allow running
multiple applications. Each of them can use param to control its execution,
but only the first one must start the clock. To avoid identifier clashes each 
application must be given a minor id number, a single alpha-numeric character, 
small and capital letters being the same. So you can run and monitor up to 35 
applications, where and from wherever you want. The minor id number must be 
given to the model code startup by running it as:
./modelname_standalone <any alpha-numeric character>,
e.g. "./modelname_standalone q", "./modelname_standalone 5", 
"./modelname_standalone A".
If no minor id number is given it will default to (character) 0. 

Both param.c and scope.c will ask for it at the very beginning of their
execution.

Scope.c depends from your specific application. What implemented here gets model
output data data as received from a mail box installed in the model specific 
actuator code hinted above. So the implementation found here is just a sketch 
specific to the examples available in the directories:
- Controller, which generate a simple sine function and a constant value in its 
sensor part of Controller_io.c; it is a modified version of the demo 
controller.cosf, distributed with CodeGen.
- pid, which implement a summing PID controller; it includes also the 
discretized systems it controls to allow a simple verification.

As said it is possible to change model parameters during execution.  
Unfortunately it cannot be done in a too friendly way as no (human) parameter 
id is generated by CodeGen. So you must know some Scicos internals to guess the 
position each parameter occupies in the vector RPAR1, found in your model, and 
be sure it can be changed at each sampling time. At the moment it is possible 
to change just RPAR1 contents. As an helper to an easier understanding of where 
your parameters are placed within RPAR1 there is a parameter preview and 
initialization loop in param. By setting up fancy numbers in the Scicos model 
before code generation you can see them at the beginning of param execution, 
know where they are, set back their correct values before execution and then 
change them during the controller execution also. It is a bit silly operation
but can help in guiding you to do what you want almast without knowing Scicos
internals.
A rough understanding of the Scilab/Scicos internals is nonetheless clearly 
a good asset. The essential fact to be recalled is that any dynamic block will 
end into RPAR1 as a standard discrete quadruple [A, B; C, D] other single 
parameter blocks, e.g. constants and gains remaining standalone. A look at 
modelname.cosf might be of help also.

The same problem exists for model input/output, as it is up to you to take care 
of the way Scicos numbers your input/output, so that you can code appropriately 
the sensor/actuator code in modelname_io.c.

The examples available here contain some clues that might result useful for 
more realistic applications also.

This work is just the beginning of a project aiming at making it possible to
use a unified distributed execution/supervision/monitoring program working 
with both Scilab and Matlab. In that view what found here is just a rough 
preliminary proof of concept of what has to be done with Scicos. Nonetheless 
it affords a usable framework already, that should be easily expandable 
according to any specific immediate need.

A typical example of multiple runs is given below, using multiple instances of 
any example found here. It must be remarked that each of the lines below must 
be run from different shells. So:
-./run a, initial loading of all the RTAI supporting stuff and of the very first
  real time task; answer to what param asks you, this is the first instance so 
  the clock must be started;
-./runmore b, another instance, without loading RTAI stuff, then as above;
-./runmore c, another instance, without loading RTAI stuff, then as above;
.
.
.
-./runmore 1, another instance, without loading RTAI stuff, then as above; 

At this point you'll have a lot of controllers running. To monitor any of them:
- ./runscope, then answer with the minor id of the controllers when asked for.
It all can be done also in a distributed way, just care of setting the 
appropriate "SysNode" when you execute "modelname_standalone", see run and
runmore for the command syntax to be used.

You can run any number of scope instances. Scope will simply type a time 
history on the screen. If you want to plot it redirect the related output to
a file and then plot it. A really poor man plotting capability is available,
i.e mbplot. To use it have a look at "plot", each example has its own plot
command for a file "foo", just edit it according to the command explained
in "plot" for your own needs. 

Tru on line "real time" scopes will become available in the general unified 
interface hinted above. To stop a scope instance simple type "enter"

Take care of ending the controller that started the clock after it has remained
the only one executing.
