Altia-SystemBuild and RealSim Tutorial
Connecting a Separately Developed Altia Design GUI to a SystemBuild Simulation and Then to RealSim
Altia Design graphics and user interface software can be used in conjunction with ISI’s MATRIXX SystemBuild and RealSim products. The MATRIXX interface to Altia Design allows the MATRIXX user to create new graphical panels with the state-of-the-art Altia Design editor. In addition, existing MATRIXX IA (Interactive Animation) picture (.pic) files can be converted to Altia Design (.dsn) files.
The Altia Design package includes an editor, runtime engine and numerous libraries of components for quickly creating a user interface to SystemBuild simulations. In addition to supplied components, users can modify supplied components, import images and create their own custom components in the editor without programming. With these features, a modeler can quickly create a user interface prototype for product simulations that looks and behaves like the product’s real user interface.
The goal of this tutorial is to show the basic link between the MATRIXX SystemBuild and RealSim models and an Altia Graphical User Interface (GUI). In this tutorial, we will discuss every step necessary to develop a simple system that exercises these connections.
Before you begin this hour-long tutorial, make sure you have MATRIXX SystemBuild and Altia installed on your machine. Altia is included on the MATRIXX installation CD. If Altia is not already installed on your machine, PC users may install it by running the setup.exe file in the Altia directory on your CD. Be sure to install Altia in the $ISIHOME\altia directory on your machine. Unix users should extract the Altia archive from the CD relative to their $ISIHOME directory. If you need a new codeword to unlock Altia Design, please call Altia at (719) 598-4299 or contact your ISI sales representative.
The first section, labeled Use SystemBuild to Create a Simple Model, will describe how to design a model that has a simple gain block which outputs to and is fed by an Altia Interface block.
In the next section (Use Altia Design to Create a Simple GUI), we will step through the procedures required to build a GUI that has a slider and a meter.
The process of connecting the model to the GUI we have created will be addressed in the next section, Connect Your Altia GUI to Your MATRIXX Model. We will connect the two such that the slider bar is the input to the gain and the meter will show the gain’s output.
The Test Your Altia GUI/MATRIXX Model Interaction section will show you how to verify that your GUI and your model are connected correctly.
The next three sections discuss how to connect the model we have created to RealSim for a hardware simulation. The sections Generating a Real Time File and Initializing RealSim step through the procedures for transitioning from SystemBuild to RealSim. The section labeled Connecting RealSim to Altia gives the final steps required to complete the progression to Realsim and simulate on hardware.
The last section, Translating Existing PIC Files, describes how to translate an existing Interactive Animation (.pic) file into an Altia (.dsn) file. It also details how to modify a SystemBuild model to simulate with Altia instead of IA.
Use SystemBuild to Create a Simple Model
The first thing you will need to do is decide on a name for a project directory. If the directory does not exist, create it now. For example, on the PC use the File menu in a file browser window to create a new folder. On UNIX, you can use the mkdir command to create a new directory (e.g., mkdir $HOME/tutor).
Open Xmath.
Make sure you are in the project directory you have created by typing
set directory="<full_path_to_project_directory>"; and pressing <enter> in the Xmath command line.
Next, in the Xmath Window menu, click on SystemBuild to open up the Catalog Browser and SystemBuild editor utilities.
The focus should be on the Catalog Browser, so in the Catalog Browser File menu, click on New/SuperBlock. This will open the SuperBlock Properties dialog box with the focus in the Name field.
Type in a name for our SuperBlock (for example, altiatut) and change the number of outputs (located at the far right of the SuperBlock Properties dialog box) to one (1). Then click OK (at the bottom of the dialog).
The SystemBuild editor will come up. Notice at the top of the SuperBlock editor work area that the name of our SuperBlock appears (altiatut) and it has 0 inputs and 1 output.
We are now ready to add the components of our model. To do this, click on Palette Browser in the SystemBuild editor Window menu. The Palette Browser will open to the SuperBlock selections by default.
Click on the SuperBlock icon and drag it into the left side of your SystemBuild editor work area.
Next, scroll down the Palette Browser until the Altia block is visible. Click on the Altia icon and drag it into the right side of your SystemBuild editor work area.
Next, we must give the two blocks identical names. This is done to make things easier when we export our design to RealSim (later in this tutorial). To do this, select the SuperBlock and press the <enter> key to open its property dialog. In the name field, type in tutor and click the OK button. Do the same for the Altia block.
Now, we need to add some functionality to the new SuperBlock within the SystemBuild editor. Double-click on the SuperBlock to focus into it. There should be nothing there initially. Let’s add a Gain block. Open (or switch to) the Palette Browser again.
In the left pane of the Palette Browser window, click on the Palette below the SuperBlocks called Algebraic. Scroll until you can see the Gain icon. Click on the Gain icon and drag it onto your SystemBuild editor window.
Close the Palette Browser window as these are the only components that we will use for our simple simulation.
We must now define some of the parameters of these components.
Click on the Gain component and press <enter> to view its properties. Name the Gain block altia gain. To make things a little more interesting, change the gain from 1.0 to 0.5 and click on OK.
After the properties of the Gain block have been set, it must be connected to its parental SuperBlock. To make the Gain block output connection, select the Gain block and then click on the Connect menu option and choose Outputs. To make the Gain block input connection, select the Gain block and then click on the Connect menu option and choose Inputs. The connected Gain block should resemble the following:
Press the View Parent button 
to go back to the parent system which contains the SuperBlock and the Altia
block.
Next we will have to make connections within SystemBuild between the SuperBlock which contains the gain and the Altia Interface block. When we do this, connecting lines will appear that show which blocks are connected and the direction of the connections.
Press and hold the <Ctrl> key while clicking on the SuperBlock component and then the Altia code block component. Then choose Blocks from the SystemBuild editor Connect menu. A connector from the SuperBlock to the Altia block will appear.
Next, select the Altia block first and then, while holding down <Ctrl>, click on the SuperBlock. Once again choose Blocks from the SystemBuild editor Connect menu and you will see that the output of the Altia block is now connected to the input of the SuperBlock.
There is one more thing we must do to finish out the simulation. We told SystemBuild that our top-level (altiatut) SuperBlock had one output. We must now define that output. To do so, click on the Altia block and, from the Connect menu, choose Outputs. You should notice that an external output indicator appears connected to the output of the Altia block. This indicator is typically labeled 1.
We are now finished designing our simple SystemBuild model. Save your model
by returning to the Catalog Browser window and pressing the Save button 
.
When asked what to name your model type in tutor.dat
Use Altia Design to Create a Simple GUI
In the Xmath command line, type altiainit to setup Xmath to connect to Altia. Alternatively, you can edit the startup.ms file in the MATRIXX sysbld/etc directory to load altiainit every time you start Xmath. Simply add the following two lines to the end of the file:
build
altiainit
Open the Altia Editor by double-clicking on the Altia block in the SystemBuild editor window. This should cause the SystemBuild model to connect to the Altia Editor (a message to this effect will appear in the Xmath window). Every time you double-click on the Altia block in the SystemBuild editor, the connection with Altia will be re-established and the most recent I/O information will be provided to Altia.
Altia will open with a blank design file and name it tutor.dsn because the editor was started by double-clicking on the Altia block named tutor.
In this initial design we will only have a slider bar and an analog meter. Although we could create these objects ourselves, it is easier to use objects from Altia’s included model libraries.
To create the slider bar, click on the Models button which is located beneath the menu and above the main view.
In the Altia-ModelsOpen dialogue, change to the directory $ALTIAHOME\models\ and choose the file CONTROL.DSN. Then click on the Open button.
A window will open which contains the control models. Press and hold the left mouse button on the slider image and drag it into the Main View of the Altia Editor. After you have placed the slider in the Altia Editor, close the controls Model View.
To modify the properties of the slider, double-click on it to open the Property Dialog. Change the property labeled Maximum from 100.0 to 200.0. This will make our slider’s range of values change from 0 – 100 to 0 – 200. We could also change many other slider attributes such as color scheme, title, number format, etc. For right now, we will just change its Maximum value.
The circular meter is located in the MONITOR.DSN model library. Open it in the same way that CONTROL.DSN was opened. To add the circular meter, you may need to pan up in the Models View until it is visible. To pan, click several times on the up arrow pan button located in the lower left-hand corner of the Models View window.
Once you have found the circular meter, drag it into the Altia Editor main view just below the slider. We will leave the circular meter’s properties at their default values.
Now, let’s save our GUI to a design file. In the Altia Graphics Editor, choose Save from the File menu. We have now saved this simple design to the file tutor.dsn.
Although the graphics look neat, right now they don’t do much because we have yet to connect them to anything. This is our next task.
Connect Your Altia GUI to Your MATRIXX Model
We must now connect the input/output labels of our SystemBuild model to the Altia GUI objects’ labels so that the two programs may communicate. This is easily done with Altia.
In the Altia Editor, select the slider and the circular meter by holding down the shift key and clicking on the slider and the meter. Next, from the Connections menu, choose Selected Objects…. Two connections dialogs will open (one for each object).
From the Connections menu, choose External Signals… to open the dialog which will allow us to connect to the MATRIXX signals.
Click on the signal in the slider connection dialog labeled OUTPUT Slider Value, then click on the signal in the external connection dialog labeled INPUT in1. When this is done the Connect button should become available. Press it to connect the slider to the input of the SystemBuild model. The connections dialogs should reflect the fact that the two objects are now connected.
To connect the output of the model to the circular meter, click on the signal labeled OUTPUT out1 in the external connections dialog, then click on the signal labeled INPUT Circle Meter Value. Press the Connect button to connect the output of the model to the circular meter.
The connections have now been established. Save the changes (connections) to
your Altia design by choosing Save from the File menu. You must
save whenever external connections are modified. Otherwise, the changes will not
be recognized by a MATRIXX simulation.
After saving, close all of the connections dialogs by choosing Close All
from the Exit menu in one of the dialogs.
Test Your Altia GUI/MATRIXX Model Interaction
Select the SystemBuild editor window and make sure no objects are selected. From the SystemBuild editor Tools menu, choose Simulate.
Click on the Time Vector/Variable field and enter [0:1:10000]’ (Please note the single quote). Click on the Interactive checkbox and then click on OK.
The Interactive Simulator window will open showing the contents of our altiatut SuperBlock. We are ready to simulate. Your Altia Design editor window should still be open to your GUI design from the previous section. Change your focus to this window. If the Altia editor is not already opened, an Altia runtime-only window will automatically open for your GUI design.
In the Altia Design editor, you are probably in Edit mode (the radio buttons initializing Edit/Run modes are located just below the color palette on the left side of the Main View). Unselect all of the Altia objects and then switch the Altia Design editor to the Run mode by clicking on the Run radio button.
Select the SystemBuild Interactive Simulator window. From the Simulation menu, choose Resume and the simulation will begin.
Switch back to the Altia Design editor window. Click on the handle of the slider bar and drag the mouse from side to side. You will notice that the circular meter will change to reflect the status of the Gain output (which is 50% of the slider bar value). After a short while, the simulation will time out and the Altia objects will stop responding. You can reset and resume the simulation from the Simulation menu in the Interactive Simulator window.
Now we are going to run our simulation on separate hardware using RealSim. You must have RealSim hardware and software to complete this section. We start by closing the SystemBuild Interactive Simulator and switching back to the SystemBuild Catalog Browser window. (If no contents appear in the right pane of the window, then from the View menu option, choose Update.) You should see two items in the right pane: tutor and altiatut.
Select the tutor item and from the Tools menu, choose AutoCode. In the Generate Real Time Code dialog box, confirm that the File Name is tutor and change the Language drop-down box to RTF Only. Click on the OK button to generate the RTF file (tutor.rtf).
Now that the Real Time File (.RTF) has been created, we can exit out of Xmath and SystemBuild completely. Choose to quit without saving since no changes have been made since our last save.
Start RealSim by choosing the RealSim icon from the RealSim program group. This should open up a special DOS session with the title "RealSim." Change to your project directory using the CD command (e.g., cd <project_directory>). If you list the directory contents, you should see five files: tutor.dsn, tutor.rtm, tutor.dat, tutor.mxc, tutor.rtf and altiatmp.___.
On the RealSim DOS command line, type makeproject and press <enter>. RealSim will prompt you for the name of the project (and will default to the name of the current directory). Type in tutor and press <enter>.
Once again, on the RealSim DOS command line, type retarget and press enter. RealSim will prompt you for the various parameters (which will vary depending on your particular setup). For the setup on which this tutorial was developed, the following options were set (the two of them that differed from the default values are in Italics):
Controller target name: ac104 (host name of RealSim machine)
Schedule trigger: periodic
Autocode options: optimize
Max lines in generated code files: 0
Watchdog timer: off
Overflow limit: 5
First time tick overflow limit: 5
A1 compiler options: g4_opt (RealSim machine was a 486)
A1 linker options: msvc
After you have set the final parameter, RealSim should respond with the message "Successfully updated target_config.cfg."
On the RealSim DOS command line, type realsim to start the RealSim GUI. This interface will guide us through the remaining steps required for simulating on RealSim hardware. The very top procedure, labeled Start New Xmath/SystemBuild, has already been done in the Use SystemBuild to Create a Simple Model section of this tutorial.
Click on the Animation Builder button. Since we have chosen Altia as our animation package (when we retargeted), the Altia Editor will open and load the tutor.dsn file.
At this point, you may edit the design file by changing the connections or adding new Altia objects. However, our design is just how we want it so just exit.
The RealSim GUI window should re-appear.
Click on the Hardware Connection Editor button. We don’t wish to connect any physical hardware for our demo, so just click Done on the HCE input and output windows.
We now are just three clicks away from simulating on the RealSim hardware. In the RealSim GUI window, click on the Autocode button. Then click on the Compile and Link button. If no problems are encountered, we are ready to simulate on the RealSim hardware. Click on the Download and Run button.
After a few moments, a Main Altia View window and an IA Control window will open. In the IA Control window, click on the Start Controller button to begin the simulation. Your Altia icons should come alive and behave in the manner to which you are accustomed.
Click on the Stop Controller button to stop the simulation, then click on the Hardware Reset to tell the RealSim hardware to stop running the simulation and close all the windows.
Translating Existing PIC Files
If you already have an existing PIC file that you would like to import into Altia, then you must translate the PIC file. As an illustrative example, we will translate one of the demos that is shipped with MATRIXx.
Create a new directory and name it sg_demo. Copy the sg_demo.pic and sg_demo.rtf files from the $ISIHOME\sysbld\demo\ia_demo directory to the new directory.
Exit Altia and restart Xmath. Change to the new directory by typing
set directory="<full_path_to_new_directory>"; and pressing <enter> in the Xmath command line.
To translate the PIC file to a DSN file, simply type pictodsn on the Xmath command line. First, an error dialog will appear saying that the default file pict.pic could not be found. Click OK to dismiss this dialog. Next, a dialog will appear prompting you for a PIC file to translate because our new directory has no animation.cfg file. Type sg_demo.pic and press <enter>.
When the conversion is finished, a dialog will appear that says Conversion complete! This dialog will also tell you if there were any errors in converting the file and how many objects were translated.
Click OK to dismiss the dialog. If you look in your sg_demo directory, a new sg_demo.dsn file will have been created. You will also see sg_demo.rtm (the Altia runtime configuration file for sg_demo.dsn) and sg_demo.mxc (the Altia-MATRIXX connections file for sg_demo.dsn).
Type build in the Xmath command line to open SystemBuild. Switch to the Catalog Browser window, and from the File menu, choose Load. In the File name box, type sg_demo.rtf and then press <enter>.
Double-click on the S G Demo SuperBlock in the Catalog Browser to open the SystemBuild editor. Select the User Code block by clicking on it and then press <enter>.
Change the block’s Name to sg_demo and change the Function Name from 01 (or whatever it says) to usraltia1 (the last letter of this name is a "one") and then press <enter>.
Switch back to the Catalog Browser window, from the File menu choose Save as. When prompted for the file name to save as, type sg_demo.rtf and press <enter> to overwrite the old rtf file. Now, in the Xmath command line, type altiainit and press <enter>.
In the SystemBuild Editor window, double-click on the User Code block to open the Altia editor. You should see a design that is similar to the PIC file except that the IA graphics have been replaced with Altia versions.
If you do not wish to have new versions of the IA graphics in your Altia design, you may specify that option in the pictodsn command. To do so, type the following line exactly (including double quotes) on the Xmath command line:
pictodsn "-style old"
If you open the resulting sg_demo.dsn file with Altia (by first closing the existing Altia editor session and again double-clicking on the User Code block), you will see that it is indeed the same as the PIC file.
You can simulate with either version of sg_demo.dsn by choosing Simulate from the SystemBuild Editor Tools menu.
In this tutorial, we have created an Altia GUI and a SystemBuild model from scratch. We then used the connection dialogs in Altia to connect the GUI to the model. In order to be sure that our connections were correct, we simulated the SystemBuild model and stimulated it using our Altia interface.
In the next three sections, instructions for porting our design to RealSim hardware were given. We first made a Real Time File from our existing model. Then we started RealSim, made a project in our directory, re-targeted that project and then started the RealSim GUI.
Once the RealSim GUI was started, we generated, compiled and linked code for our model. We then downloaded and ran the simulation on the RealSim hardware.
Finally, we discussed how to translate existing PIC files to Altia.