- SUPPORT FOR MATRIXX-AUTOCODE IN RTAI USER SPACE:

This directory contains the support for running a code generated by Matrixx
AutoCode, from a SystemBuild model, in hard real time using RTAI-Linux. 
At the moment there is no native Matrixx for Linux but only for Windows. 
So the whole process is a kind of cross development and as such it has 
influenced the making process described in the followings. In such a view
all references to native MATRIXX installation stuff in what follows will
have to be referred to Windows.

The Matrixx version used for this development is 71.1, so it is the only one 
supported right now.
RTAI support has been derived from the existing VxWorks template file and an 
utility C function, with its specific header file (sa_utils.c and 
sa_utils.h).
The latters had to be modified for a more consistent integration into RTAI-Lab.
Those interested in a comparison of the changes can find the original files
in: "MATRIXX_HOME\mx_71.1\case\ACC\templates\apps\vxworks"
Those changes were carried out following directions suggested at page 5,
chapter 2, of "Matrixx-AutoCode Reference" stating:
"Target-specific utilities (in sa_utils.c) perform hardware, application, and 
C-specific tasks that are required for simulation and testing. They can be 
modified to support the generated code on different target computers."
Also followed where suggestions found at the beginning of the file 
"vxworks.tpl":
"This template can be used as a starting point for tailoring the generated 
code to suit specific embedded targets."

As already pointed out before to use this support you need two operating 
systems: Windows, to generate the real-time code via Matrixx AutoCode, and 
RTAI-Linux, to compile and run the code using RTAI-Lab. 
RTAI-Linux could be installed also on a virtual machine, like VMware, running 
under Windows, but neither extreme performances nor hard real time can be 
asked for.

--------------------------------------------------------------------------------
WHAT YOU FIND IN THIS DIRECTORY:

-> rtai.tpl:          is the Template File you'll need to generate Real-Time 
                      code to be run under RTAI.

-> rtmain.c:          is the Real-Time main program allowing a model to be
  (rtmain.h)          correctly executed under RTAI.
              
-> mxp.c:             contains the functions required to tune simulation 
  (mxp.h)             parameters on the fly.

-> sa_utils.c:        contains some utilities required to implement the IO file
  (sa_utils.h)        (in "Matrixx style").
  
-> /devices:          contains the functions required for the communication 
                      between the Real-Time simulation and RTAI-Lab ( 
                      RTAI scopes, logs, meters and leds), and those for 
                      analogue/digital IO to/from the external environment, 
                      using RTAI real time COMEDI support from user space. 
  
-> /examples:         contains 4 SystemBuild Block diagram examples, described
                      at the end of this README.
                
-> /vxworks-wrappers: contains the files needed to make it easier adapting 
                      Matrixx AutoCode to RTAI-Lab.
                      
-> /rtaidevs:         contains the files needed to have RTAI customized blocks 
                      directly available in the SystemBuild palette browser.
--------------------------------------------------------------------------------

HOW TO INSTALL THE SUPPORT:

For RTAI and RTAI-Lab installation consult the existing specific documentation
(you might have a look at the "RTAI-Lab tutorial", available at www.rtai.org).
Installation of RTAI-Lab in Linux come by itself following what indicated in
RTAI README.INSTALL.

To compile the Real-Time code generated from Matrixx AutoCode you need to copy 
the following files:
- sa_defn.h
- sa_fuzzy.c
- sa_fuzzy.h
- sa_math.c
- sa_math.h
- sa_sys.h
- sa_types.h
to the directory "RTAI_INSTALL_DIR/share/rtai/matrixx/matrixx-files" in Linux 
taking them from the native directory "MATRIXX_HOME\mx_71.1\case\ACC\src" 
(where RTAI_INSTALL_DIR is the RTAI installation directory within Linux and
MATRIXX_HOME is the Matrixx installation directory).

Notice that those are the Matrixx files that were found to be needed during the
work carried out during the development of the RTAI-Lab support for Matrixx
so far. It is possible that your application at hand can end in requiring other 
files distributed within Matrixx. If that happens you'll have just to copy them
in the very same Linux place as those mentioned above.

In order to use RTAI customized blocks in SystemBuild environment you have to 
copy the directory "rtaidevs" from the RTAI distribution to the native MATRIXX
directory: 
"MATRIXX_HOME\mx_71.1\sysbld\palettes".

!!!!! DO NOT CHANGE THE "rtaidevs" DIRECTORY NAME. !!!!!

Then you have to move the file "rtai.pal" from the directory:
"MATRIXX_HOME\mx_71.1\sysbld\palettes\rtaidevs"
to the native MATRIXX directory:
"MATRIXX_HOME\mx_71.1\sysbld\palettes".

By default RTAI-blocks are not available in SystemBuild palette browser, so you 
have to load the file "MATRIXX_HOME\mx_71.1\sysbld\palettes\rtai.pal" in the
palette browser ( by means of "File -> Load" or "Ctrl+O" ). If the RTAI-blocks' 
icons aren't visible in the block diagram editor (as it is possible when you 
load a saved model from your working directory) you just have to reload the 
file "rtai.pal".

--------------------------------------------------------------------------------

HOW TO USE THE SUPPORT:

1. SystemBuild Block diagram to use RTAI-Lab support.
   
   In order to use RTAI-Lab with a Real-Time model you have to add to your 
   SystemBuild Block diagram those device blocks needed for the communication 
   between the Real-Time simulation, the external environment and RTAI-Lab.
   At the moment four output displaying devices are available:

   - rtai_scope:  monitor signals during real-time simulation;
   - rtai_log:    save signals to a file;
   - rtai_meter:  monitor with meter a signal during real-time simulation; 
   - rtai_led:    monitor with a led a signal during real-time simulation; 
  
   and four external anologue/digital IO devices, to support the related data
   acquisitions using COMEDI drivers (www.comedi.org):
   
   - rtai_comedi_datain:  to read analogue signals;
   - rtai_comedi_dataout: to write analogue signals;
   - rtai_comedi_dioin:   to read a digital signals;
   - rtai_comedi_dioout:  to write a digital signals;
          
   To include RTAI customized blocks to SystemBuild there are two different 
   ways, the first is to "drag and drop" the RTAI-blocks from the palette 
   browser (see HOW TO INSTALL THE SUPPORT part of this README to see how load 
   RTAI-blocks in the SystemBuild palette browser); otherwise you can 
   use the "UserCode" block (under Palette Browser -> User Programmed) and 
   adapt this block to perform a specific devices.
    
   1.1 rtai_scope block.
       With the rtai_scope you can monitor a signal during the Real-Time 
       simulation through RTAI-Lab.
       To include a rtai_scope in your SystemBuild model you can use the
       "UserCode" block ( under Palette Browser -> User Programmed ). You can 
       monitor N signals together within a single rtai_scope selecting for 
       the block N inputs and connecting the block with N signals.
       In the "UserCode" block paramenters you must set: 
       - "File Name" -> "rtai_log.c";
       - "Function Name" -> "rtai_log";
       - "Number od Integer Parameters" -> 1;
       - "Integer Parameters" -> ID.
       ID is the scope identification number and it must be unique for each
       scope. In RTAI-Lab a label is associated to each scope: SCOPE-ID, 
       where ID is the integer parameter defined in the SystemBuild block.
       Otherwise, using the customized block from palette browser ( 
       Palette Browser -> rtai -> RTAI-Scope ), you have only to set the 
       identification number and the inputs' number.
       
   1.2 rtai_log block.
       With the rtai_log you can save to a file a signal during the Real-Time 
       simulation through RTAI-Lab. 
       To include a rtai_log in your SystemBuild model you can use the 
       "UserCode" block (under Palette Browser -> User Programmed). You can
       save N signals files together to the same file with the same rtai_log
       selecting for the block N inputs and connecting the block with N signals.
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_log.c";
       - "Function Name" -> "rtai_log";
       - "Number od Integer Parameters" -> 1;
       - "Integer Parameters" -> ID.
       ID is the log identification number and it must be unique for each log.
       In RTAI-Lab a label is associated to each log: LOG-ID, where ID is the
       integer parameter defined in the SystemBuild block.
       Otherwise, using the customized block from palette browser ( 
       Palette Browser -> rtai -> RTAI-Log ), you have only to set the 
       identification number and the inputs' number.
       
   1.3 rtai_meter block.
       To include a rtai_meter in your SystemBuild model you can use the
       "UserCode" block (under Palette Browser -> User Programmed). You can 
       monitor only one signal with a rtai_meter, to monitor N signals
       you have to use N rtai_meters.
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_meter.c";
       - "Function Name" -> "rtai_meter";
       - "Number od Integer Parameters" -> 1;
       - "Integer Parameters" -> ID.
       ID is the meter identification number and it must be unique for each meter.
       In RTAI-Lab a label is associated to each meter: METER-ID, 
       where ID is the integer parameter defined in the SystemBuild block.
       Otherwise, using the customized block from palette browser ( 
       Palette Browser -> rtai -> RTAI-Meter ), you have only to set the 
       identification number.
       
   1.4 rtai_led block.
       To include a rtai_led in your SystemBuild model you can use the
       "UserCode" block (under Palette Browser -> User Programmed). You can 
       monitor N signals together iwhitin a single rtai_led selecting for the 
       block N inputs and connecting the block with N signals.
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_led.c;
       - "Function Name" -> "rtai_led";
       - "Number od Integer Parameters" -> 1;
       - "Integer Parameters" -> ID.
       ID is the led identification number and it must be unique for each led.
       In RTAI-Lab a label is associated to each log: LED-ID, where ID is the
       integer parameter defined in the SystemBuild block.
       Otherwise, using the customized block from palette browser ( 
       Palette Browser -> rtai -> RTAI-Led ), you have to set only the 
       identification number and the input number.
       
   1.5 rtai_analogIn block.
       To include in your model a block to carry out the reading analogue
       signals from the external environment you can use the "UserCode" block 
       (under Palette Browser -> User Programmed). You need a block for each
       different analogue acquisition channel.   
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_comedi_datain.c;
       - "Function Name" -> "rtai_comedi_datain";
       - "Number od Integer Parameters" -> 4;
       - "Integer Parameters" -> [ channel , range , aref , comedi ].
       Where "channel" is the channel number of the acquisition card from
       which the signal is read, "range" and "aref" are setting parameters 
       of the channel and comedi is the identification number of the 
       device (acquisition card). 
       Otherwise, using the customized block from palette browser
       (Palette Browser -> rtai -> RTAI-AnalogInput), you have to set just
       just the four integer parameters described above.
   
   1.6 rtai_analogOut block.
       To include in your model a block to carry out the writing of analogue
       signals to output channels of the acquisition card you can use the 
       "UserCode" block (under Palette Browser -> User Programmed). You need
       a block for each different output signal.   
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_comedi_dataout.c;
       - "Function Name" -> "rtai_comedi_dataout";
       - "Number od Integer Parameters" -> 4;
       - "Integer Parameters" -> [ channel , range , aref , comedi ].
       Where "channel" is the channel number of the acquisition card to
       which the signal is written, "range" and "aref" are setting parameters 
       of the channel and comedi is the identification number of the 
       device (acquisition card). 
       Otherwise, using the customized block from palette browser 
       (Palette Browser -> rtai -> RTAI-AnalogOutput), you have to set just 
       the four integer parameters described above.
       
   1.7 rtai_digitalIn block.
       To include in your model a block that performs the reading of digital
       signals from the external environment you can use the "UserCode" block 
       (under Palette Browser -> User Programmed). You need a block for each
       different digital acquisition channel.   
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_comedi_dioin.c;
       - "Function Name" -> "rtai_comedi_dioin";
       - "Number od Integer Parameters" -> 2;
       - "Integer Parameters" -> [ channel , comedi ].    
       Where "channel" is the channel number of the acquisition card from
       which the signal is read and comedi is the identification number of the 
       device (acquisition card). 
       Otherwise, using the customized block from palette browser 
       (Palette Browser -> rtai -> RTAI-DigitalInput ), you have only to set 
       just the parameters (channel, comedi) described above.        
       
   1.8 rtai_digitalOut block.
       To include in your model a block that performs the writing of digital
       signals to a digital channel of the acquisition card you can use
       the "UserCode" block (under Palette Browser -> User Programmed). You 
       need a block for each different output signal.   
       In the "UserCode" block parameters you must set: 
       - "File Name" -> "rtai_comedi_dioout.c;
       - "Function Name" -> "rtai_comedi_dioout";
       - "Number od Integer Parameters" -> 2;
       - "Integer Parameters" -> [ channel , comedi ];
       - "Number od Real Parameters" -> 2;
       - "Real Parameters" -> threshold.
       Where "channel" is the channel number of the acquisition card to which 
       the signal is written and comedi is the identification number of the 
       device (acquisition card). The output signal is set to 1 if the 
       signal value is greater than the threshold value and set to 0 otherwise.
       Otherwise, using the customized block from palette browser 
       (Palette Browser -> rtai -> RTAI-DigitalOutput), you have to set just 
       the parameters (channel, comedi and threshold) described above.
           
   Via RTAI-Lab you can modify on the fly the very same parameters that you 
   can modify during an Interactive Simulation within SystemBuild environment,
   through the Run-Time Variable Editor (RVE). For a list of blocks and 
   parameters supported in RVE see chapter 9 of "Matrixx-SystemBuild User Guide"
   pages 18-19.
   The parameters names in RTAI-Lab are the same as those defined in 
   SystemBuild for the corresponding Xmath variable (to obtain a tunable 
   parameter, you must define the parameter value in Xmath environment 
   before code generation).

2. Real-Time code generation.
   
   To generate a Real-Time code to be run under RTAI you have to use the 
   Template File "rtai.tpl" (available in this directory) for code generation 
   via AutoCode. So you must copy the file "rtai.tpl" on your Windows PC where 
   Matrixx is installed. 
   To generate the code from Xmath you can type the following command:
   
       autocode "BLOCK_NAME", { fmarker, arraymin=3, initmerge, loopmin = 3, \
           ipath="MATRIXX_HOME\mx_71.1\case\ACC\templates", locvarlblkopt, \
           noerr, noinfo, propconst, vectormode=2, nouy, language="c", \
           smcallout, namelen=48, ialg=2, minsf=***, rtf="MODEL_NAME", \
           tplsrc="RTAI_TPL_DIR\rtai.tpl"}
           
   where:
   - MATRIXX_HOME is the path of the directory where you have installed
                  Matrixx;
   - RTAI_TPL_DIR is the path of the directory where you have copied the 
                  Template File "rtai.tpl";
   - BLOCK_NAME   is the name of the SystemBuild SuperBlock name which you 
                  want to generate the code;
   - MODEL_NAME   is the name of the generated files.
   
   The options "ialg" and "minsf" are intended to be used to generate code for
   continuous system. For more information on AutoCode and his options see the
   "Matrixx-Autocode User Guide" and "Matrixx-Autocode Reference". 
   After code generation you must find in your Matrixx working directory 
   (you set this directory from Xmath command: file -> Set Directory) the
   following files:
   - appl.h
   - MODEL_NAME.c
   - MODEL_NAME.cmd
   - MODEL_NAME.rtf
   - rtai.dac 

3. Executable generation.

   To generate the executable file to be run under RTAI you have to copy in
   your working Linux directory, i.e on your RTAI-Linux PC, the files "appl.h" 
   and "MODEL_NAME.c", generated by Autocode.
   In such a working directory you must copy also the file "Makefile", from the
   directory "RTAI_INSTALL_DIR/share/rtai/matrixx/" (where RTAI_INSTALL_DIR is 
   the RTAI installation directory).
   As explained before, see: HOW TO INSTALL THE SUPPORT, any executable 
   generation expects to find the following files:
   - sa_defn.h
   - sa_fuzzy.c
   - sa_fuzzy.h
   - sa_math.c
   - sa_math.h
   - sa_sys.h
   - sa_types.h
   as found in the directory "MATRIXX_HOME\mx_71.1\case\ACC\src", in the 
   directory: "RTAI_HOME/share/rtai/matrixx/matrixx-files", of your RTAI-Linux
   PC.
   
   Typing the command "make MODEL_NAME" you can then generate the executable 
   file named "MODEL_NAME" (you can ignore the compilation warnings, they will
   be cleaned off sooner or later). During the executable generation others 
   files are created in your working directory, you can delete them typing the 
   command "make clean".
   
   3.1 Compilation options.
       During the compilation you can select two options by editing the file 
       "Makefile": 
       - commenting (with a "#") the line "DOUBLE_FLAG = -DAC100FLAG" you 
         elect to use real numbers in singular precision (C type: float), the
         default being double precision (C type: double) otherwise.
       - the flag "FILEIO_FLAG" is intended to be used when the model needs
         external input, a la Matrixx. That external input is read from a 
     file (input data file) in "Xmath {matrixx,ascii} format" (see Matrixx 
         documentation) and, with this flag active, the output is 
         automatically saved to a file (output data file) in Xmath format too. 
         You select the input/output data files at the beginning of the 
         execution of the Real-Time simulation. You can specify a directory 
         for the input/output data files using the options -P when you launch 
         the executable (see the usage options typing the command 
         "./MODEL_NAME -u"), with the default choice the files are searched in 
     the current working directory. When you use the "FILEIO_FLAG" option 
     the simulation is terminated at to the last time instant specified in 
     the input data file.
         When the model has no external input you can comment the line 
         "FILEIO_FLAG = - DFILE_IO" in "Makefile". In this way the simulation 
     can run forever and if you want save to a file the time history of 
     some signals you have to use the RTAI_LAB options (by means of LOGS 
     and SCOPES). 
         You can use the "FILEIO_FLAG" option also with model without external
         input, in this way the model output is saved to an output file 
         in Xmath format (you must also specify an input file with the time 
         vector). The simulation cannot run forever and terminate when the 
         limit storage capability is reached (specified with MAXY in the
         "sa_utils.c" file).
         
4. Execute
         
   To execute the Real-Time code you must load the required RTAI modules
   (you might have a look at the script "loadrtai" in the RTAI-Lab tree), 
   then you can run the code by typing "./MODEL_NAME [options]" (to see the 
   list of options type "./MODEL_NAME -u"). In another terminal run 
   RTAI-Lab (xrtailab) to communicate with the real-time code (for more
   informations read the README in the main RTAI-Lab directory and the
   "RTAI-Lab tutorial" available at www.rtai.org).
--------------------------------------------------------------------------------
         
EXAMPLES DESCRIPTIONS:

In the "examples" directory you'll find four SystemBuild Block diagram examples,
saved in rtf (Real-Time File) format; you can use those examples to test the  
support. In the following the examples are briefly described, in the first three
examples the RTAI-blocks are implemented setting "UserCode" block as described 
above, while in the fourth example the customized RTAI-blocks are used.

- multisingen.rtf:  is a simple test case where the model output is the sum of
                    two sinewaves. The model is discrete and uses different
                    time steps for each sine wave. In the model there are three
                    rtai_scope blocks to monitor the signals, via RTAI-Lab and 
                    an rtai_log to save the signals to a file. You can verify
                    the capability to modify parameters on the fly via 
                    RTAI-Lab (you have to initialize the parameters value in
                    Xmath environment before code generation) by modifying 
                    frequencies ("freq1" and "freq2") and amplitudes ("amp1" 
                    and "amp2") of the two sine waves. This model has no 
                    external input, so you will not need the "FILEIO_FLAG" 
                    option during the compilation.   

- super_cruise.rtf: is a more complex example taken from an existing Matrixx 
                    example, with a few rtai_scopes and rtai_logs added for 
                    verifying communications with RTAI-Lab. This example needs 
                    10 input, so you have to use the "FILEIO_FLAG" option during
                    the compilation. You can take the input data file in Matrixx
                    format ("super_cruise.data") from the directory: 
                    "MATRIXX_HOME\mx_71.1\case\ACC\templates\apps\vxworks".
                    You can use this example to compare the results of a 
                    simulation within SystemBuild environment to the results
                    of an RTAI-Lab real time simulation. 

- IOtest.rtf:       is a simple example, i.e. with only one subsystem task,
                    but adequate to test the communication with the external 
                    environment. In this example a random signal is summed to 
                    a sine wave, you can tune some parameters e.g.: frequency 
                    and the magnitude of the sinewave signal and the magnitude 
                    of the random signal. Remember to initialize tunable 
                    parameter values in the Xmath partition before the code 
                    generation to have them tunable on the fly. The resulting
                    signal is written to the analogue output channel 0 of the 
                    IO card 0 (comedi0) and is then read from the analogue 
                    input channel number 0. A digital signal is written to the 
                    digital channel number 0 and read from the channel 1. 
                    This digital signal is 1 when the sine wave signal plus 
                    noise is greater than 5V. 
                    Some other signals are written and read to/from the 
                    acquisition card. You should have a look at the 
                    SystemBuild block diagram to better understand this example.
                    In this way it is possible to test the data acquisition by 
                    simply connecting right channels on the acquisition card.
                    In the model there are scopes and leds useful to monitor 
                    signals during execution. See the SystemBuild block diagram 
                    once more to understand which signal are scoped. Because 
                    of there is no file IO you do not have to use the related
                    "FILEIO_FLAG" during code compilation in this model.

- DAQtest.rtf:      this is a more complex example using all RTAI blocks to 
                    communicate with the external environment using RTAI-LAB. 
                    The blocks are implemented in the RTAI customized version.
                    This example is based on up to three subsystem tasks, with
                    sampling frequency up to 5kHz. It contains the sum of two 
                    different sine waves.
                    Looking at the SystemBuild block diagram it should be easy
                    to understand the example details. Because of the absence 
                    of any file input/output there is no need to use the 
                    "FILEIO_FLAG" during code compilation of this model.

                    
Mattia Mattaboni (mattaboni@aero.polimi.it)
15 January 2007
