It's a Whole Different World - Using QUARC Versus WinCon

navigation bar

Table of Contents > QUARC > Getting Started with QUARC > Migrating From WinCon

QUARC is much more tightly integrated with Simulink than WinCon. Functionality that used to be part of WinCon Server can now be done directly in Simulink due to QUARC's seamless interface. This section describes the similarities and differences between QUARC and WinCon with respect to using the product. It is the "How to..." guide for those migrating from WinCon to QUARC. However, do not rely solely upon this section to "get up to speed" in QUARC. Be sure to read the Basic Procedures section of the QUARC documentation as well.

The similarities and differences between QUARC and WinCon may be broadly categorized into eight categories, listed below. Please refer to these links for details on each topic. The changes in hardware access are especially important, particularly on the Windows target, where use of a hardware timebase can improve jitter performance significantly. Take careful note of the warnings highlighted by an exclamation icon.

Building Models for Real-Time - Similar but Different

Configuring a Model for Building Code

Like WinCon, the first step in generating code for a model is to select the appropriate system target file, which configures the target for which code will be generated. The system target file is selected in the Configuration Parameters dialog or in the active Configuration in Model Explorer. The Model Explorer interface is more general because it allows multiple configurations to be defined so that a single model may be used to generate code for multiple targets.

In WinCon, there is only one choice, wincon.tlc, because WinCon only supported one target. Hence, WinCon set up this target as the default. However, QUARC supports multiple targets (contingent on your license) so there is more than one system target file from which to choose. For example, the quarc_win64.tlc target file selects the Windows soft real-time target. The quarc_linux_{target}.tlc target file is used to generate code for various Linux targets. QUARC configures the default target to be the Windows target, although this default may readily be changed via the QUARC Preferences dialog.

Configuring the sample time and solver type is the same in QUARC as it was in WinCon. However, QUARC also allows the stop time to be set. Hence, a model may be configured to run for exactly 30 seconds simply by setting the stop time to 30.

A much more powerful feature supported by QUARC is the tasking mode (single or multi-tasking). WinCon executed real-time code in a single thread. Thus, for a multi-rate model, WinCon would run the entire model at the base rate but only execute the code for subrate tasks every N samples. For example, if a model contained two sample rates, 1 kHz and 100 Hz, then WinCon would run the model at 1 kHz and execute the code for the subrate task, from the same thread, every 10 sampling instants. The disadvantage of this approach is that the base rate is limited by the total computation time for both the base rate (1 kHz) task and the subrate (100 Hz) task because the two tasks are executed in the same thread.

When multitasking or auto mode is selected, QUARC overcomes this limitation by executing the two tasks in separate threads. The base rate thread runs at 1 kHz and the subrate thread runs at 100 Hz. The faster the sample rate, the higher the priority QUARC assigns to it. Hence, if the subrate thread takes 8 milliseconds to execute, the base rate thread will interrupt it 8 times in order to run (on a single CPU), but the subrate thread will continue where it left off each time. Thus, the base rate is no longer limited by the computation time of the subrate task. Even better, on a target supporting multi-core CPUs (or multiple CPUs), such as the Windows target, the two threads can run concurrently on separate cores. Full details on the multi-threading capabilities of QUARC may be found on the Multithreading page.

Refer to Configuring a Model for a more complete description of configuring a model for generating real-time code. For information on configuring a single model for multiple targets or multiple configurations (such as a debug and release configuration), refer to Defining Multiple Configurations. Often the default settings are appropriate, so the model does not always have to be configured.

Building the Model

Once a model has been configured for a particular target, code is built much as it was in WinCon. Choose Build from the QUARC menu, click on the Build button in the model's toolbar, or press Ctrl+B to build the model. Like WinCon, C source code will be generated for the model, compiled into object files, linked into a real-time executable, and downloaded to the target system - all automatically. QUARC also supports the generation of C++ code by choosing it as the Language on the Code Generation pane of the Configuration Parameters dialog.

Warning Unlike WinCon, QUARC always builds the code in a subdirectory of the current MATLAB directory. WinCon built the code in a subdirectory of the folder containing the model. However, with recent versions of MATLAB, WinCon fails to run the code if the model is not in the current MATLAB directory. QUARC is always able to run the code if the current MATLAB directory is not changed after building the code.

When code is downloaded to the target, the QUARC Target Manager stores the code in a spool directory on the target system. Unlike WinCon, QUARC supplies MATLAB commands that allow you to manipulate the contents of this spool directory from the host PC. A list of the models available on the target are retrieved using the qc_get_downloaded_models command. The qc_remove_downloaded_model command may be employed to remove one or more models from the target system. Refer to QUARC MATLAB Functions for more information about the large number of MATLAB functions provided by QUARC!

Refer to External Mode Operation for a more complete description of building the real-time code for a model. For information on model referencing, which may be used for incremental compiling and linking in QUARC, refer to

in the Simulink documentation.

Running Models - Similar but Different

Starting Models

To start running the model on the target, the procedure is again similar to WinCon, but with some subtle differences. The simulation mode should be changed to External before attempting to run the real-time code. Otherwise, a normal simulation will be run. Like WinCon, a model may be started by clicking on the Connect to target button or choosing the Connect to Target item from the Simulation menu, and then clicking on the Run button or choosing Run from the Simulation menu. The QUARC Target Manager loads the real-time application when Connect to Target is selected. The model is initialized and the startup (mdlStart) code is executed. However, the model does not start running the base rate task (and subrate tasks, if any) until Run is selected. (It is possible to have the model start immediately without waiting for Run from Simulink by removing the -w option in the MEX file arguments).

Warning Due to restrictions in the latest versions of MATLAB, QUARC requires that the model be started from the same MATLAB directory as the one in which real-time code was built. Changing the current MATLAB directory after building code and then attempting to connect will result in the error "Could not execute target data map file '...' or it does not exist. Stop the target, delete the ... executable, rebuild the code, and try again. Note that execution of external mode requires the build directory to be present". Despite the cryptic error from Simulink, all you really need to do is change the current MATLAB directory back to what it was when you built the code!

Stopping Models

To stop a model, simply click on the Stop button or choose Stop from the Simulation menu. Unlike WinCon, however, the model cannot be stopped by simply disconnecting from the target.

Warning QUARC is fundamentally different from WinCon when it comes to disconnecting from a model. In WinCon, disconnecting from a model also stops the model. In QUARC, disconnecting from a model leaves the model running in the background! If you connect to a model that is already running, then QUARC reconnects to the same model and all plots and displays begin plotting the most recent data from the model. This feature is good for production systems where it is necessary to periodically monitor the real-time code.

There is also a subtle difference in the way QUARC handles models. In WinCon, when a model is started and stopped repeatedly, WinCon does not unload the model from memory. Hence, static and global variables defined in the code may not get re-initialized. Even though static and global variables are supposed to be avoided in S-functions, this persistence has affected some users. Likewise, user-written S-functions that never free allocated resources in the mdlTerminate function cause resources to be gradually consumed in this situation.

QUARC, on the other hand, always unloads the model from memory when it is stopped. Hence, static and global variables are always initialized when the model is started and resources are always freed when the model is terminated, resulting in more robust operation.

Changing Parameters - Why Change a Good Thing?

When the real-time code is running and the Simulink model is connected in external mode, block parameters may be changed online, just like in WinCon. However, in WinCon, many of the block parameters are not tunable and the model has to be rebuilt every time those parameters are changed. In QUARC, blocks have been carefully designed to allow as many parameters as possible to be tuned online, resulting in fewer builds. QUARC also supports batch downloading of parameters so that the parameters of multiple blocks may all be changed at the same time.

Please refer to Parameter Tuning for more information.

Plotting Signals - Tighter Integration Than Ever Before

One of the biggest differences between QUARC and WinCon concerns the way signals are plotted. WinCon does not allow the Scopes, Displays and other Sink blocks in Simulink to be used. All plotting in WinCon has to be done through WinCon Server. Unfortunately, WinCon Server does not support signal triggering, or Triggered or Enabled Subsystems, when collecting data. Nor does it support streaming of data to disk.

In contrast, QUARC supports all of these features. QUARC allows Simulink Scopes, Floating Scopes, Displays, To Workspace blocks and other sinks to be used for online visualization. It supports signal triggering and Triggered and Enabled Subsystems when collecting data. It even supports plotting to MATLAB Figure windows and MATLAB GUIs from real-time code through the QUARC Figure blocks. A whole new suite of online visualization tools are available in QUARC!

All of the plotting options in QUARC require external mode and are affected by the signal triggering and arming options available in the External Mode Control Panel. While full support for the External Mode Control Panel means that signal triggering is provided in QUARC, the triggering features of QUARC should be reviewed so that problems due to incorrect settings, such as Scope traces that do not complete a sweep of the axes, may be understood and remedied. Please refer to the Signal Triggering page for more information on the triggering options available in QUARC.

The easiest way to plot signals using QUARC is to place a Scope or Floating Scope in the model. Scopes are attached to the signal(s) of interest. Multiple signals may be plotted on the same Scope by muxing the signals of interest to the input of the Scope. Alternatively, more than one set of axes may be displayed on the same Scope by changing the Number of axes field in the Scope parameters dialog. Open the Scope parameters dialog by clicking the Parameters button on the Scope toolbar. Setting the Number of axes field to 2 causes the Scope to display two sets of axes. A second input also becomes available for driving the second set of axes. For more information on Scopes, refer to the Simulink documentation for the

block.

The

block is much like the Scope except that it has no inputs. Instead, the signals plotted on the Floating Scope may be changed on the fly. Thus, the Floating Scope provides similar flexibility to WinCon Server - it allows any signal in the diagram to be plotted at any time. Using the Floating Scope is easy. Simply place a Floating Scope in the model and double-click on it to open the axes. Select the axes by clicking on the axes so that a blue border is shown around the axes. Then click the line in the model representing the signal you wish to plot. Use the Shift key to select more than one signal in the model to be plotted at the same time. Click in a blank area of the model to deselect all the lines currently being plotted. The Floating Scope makes it easy to observe the behaviour of the real-time code! Refer to the Using the Floating Scope page for more information on Floating Scopes.

If you wish to see the numeric value of a signal, use a Display block. Display blocks are capable of displaying the values of vectors - expand the block to show the instantaneous value of each element in the vector.

To plot X-Y graphs, use the XY Figure block provided by QUARC. The XY Figure is capable of plotting multiple curves and has much better performance than the XY Graph block supplied with Simulink. Two-dimensional images may be displayed using the Display Image block.

The XY Figure and Display Image blocks are part of a set of blocks called QUARC Figures. The QUARC Figure blocks may be used for regular visualization but also provide an added bonus. They may be used to drive a set of axes within a MATLAB GUI. These blocks make it possible to develop full blown GUIs using MATLAB GUIDE. This powerful feature is described in detail in Creating MATLAB GUI's.

Streaming Data to Disk - More Flexibility At Last!

WinCon has always been weak when it comes to streaming data to disk. WinCon basically supports only three limited options: MAT-file logging, the To File block and saving data from a WinCon Scope.

QUARC offers a great deal more flexibility. QUARC is capable of streaming data to disk on the target or on the host. It can even stream data directly to the MATLAB workspace using the To Workspace block and other mechanisms. Data may be stored on the target system using the To File block or MAT-file logging. Data may be stored on the host using QUARC's data archiving features or the To Host File block. The data archiving features are particularly powerful because data may be streamed to multiple files automatically on the host or even multiple directories. Signal triggering is supported when streaming data to the host. These features are worth investigating and are fully described in Streaming to the MATLAB Workspace and Streaming to Disk.

Accessing Hardware - A Whole New Paradigm

WinCon uses a separate set of blocks for each type of data acquisition card. This scheme results in a growing number of blocks as more data acquisition cards are supported, making it cumbersome. Furthermore, in order to change data acquisition cards, all the hardware blocks in the model must be changed. This shortcoming is particularly vexing when sharing models with other users, who may not have the same hardware.

QUARC overcomes these limitations by supplying a common set of blocks for accessing hardware. The same set of blocks are used for all data acquisition cards. These blocks are prefixed with the name "HIL", which stands for "hardware-in-the-loop". The HIL blocks are found under

. There is also a corresponding HIL MATLAB API, HIL C API and HIL .NET API.

Configuring Hardware

To use hardware in QUARC, first place a HIL Initialize block in the diagram. The HIL Initialize block configures the data acquisition card that will be used, as well as its optional features. For example, the ranges of the analog inputs and outputs may be set, as well as which digital I/O lines will be inputs and which lines will be outputs. The HIL Initialize block is a sophisticated block and it is important to be well-versed in its features.

Each HIL Initialize block has a Board name field that gives a unique name to the board. The board name is arbitrary but it must be unique. All the other HIL blocks use this name to refer to the board. The type of board, such as a Quanser Q8 card, is identified in the Board type parameter and is only specified in the HIL Initialize block. To change the data acquisition card, simply select a new board from the Board type combobox of the HIL Initialize block. The rest of the HIL blocks will automatically use the new board. To make things even easier, the HIL Initialize block remembers the settings for each board type so you can switch back and forth between board types without losing settings specific to each board.

To use more than one board, put one HIL Initialize block in the diagram for each board. Use the Board identifier field, if necessary, to differentiate between two boards of the same type. For example, to use two Quanser Q8 cards, set the Board identifier of the first board to 0 and the identifier of the second board to 1. Board identifiers are typically integers, with the first board being board 0. However, some data acquisition cards, such as the National Instruments cards, allow boards to be assigned alphanumeric identifiers. See the board-specific documentation for details.

Two very important settings are the Digital input channels and Digital output channels. These fields are found on the Digital Inputs and Digital Outputs tabs respectively. Set the Digital input channels field to the channels that will be used as digital inputs. Set the Digital output channels field to the channels that will be used as digital outputs.

Warning Neglecting to set the Digital input channels and Digital output channels fields will result in the digital I/O failing to work on cards which support programmable digital I/O lines. These fields are used to configure the direction of each digital I/O line. If they are not set properly then digital lines intended as inputs may actually be programmed as outputs and vice versa.

Performing I/O

Once the HIL Initialize has been configured, add other HIL blocks to perform the desired I/O. The HIL blocks are designed to support four types of input channels: analog, encoder, digital and other. Other input channels are available for inputs that don't fit the other categories. Likewise, four types of output channels are provided: analog, PWM, digital and other. The HIL blocks are organized into three categories: immediate I/O, buffered I/O and timebases. The type of channel read or written by a block is clear from the block name. For example, the HIL Read Analog block reads analog inputs. Blocks without a particular type of channel as part of the name, such as the HIL Read block, are capable of reading more than one type of channel at the same time and are more efficient when more than one kind of I/O is required.

The immediate I/O blocks read or write to the hardware immediately. When the block is executed in the model, the I/O is performed. The immediate I/O blocks are useful in control applications for writing to the motors after performing the control calculations.

The buffered I/O blocks read or write a number of samples at a fixed sample rate. The blocks do not finish executing until all the samples have been collected. For example, a HIL Read Encoder Buffer block may be configured to read 100 samples at 10 kHz. The block will take 10 milliseconds to execute because it does not return until all 100 samples have been collected. The buffered I/O blocks are useful for system identification or oversampling applications where samples are processed in frames.

The timebase blocks acts as a hardware timebase for the model while reading or writing to the indicated channels. Thus, the base sampling rate of the model is established using a timer on the data acquisition card itself rather than the QUARC system timebase available on the target operating system. Use of a hardware timebase allows faster sampling rates when the system timer is limited. It can also provide better jitter performance on some platforms.

Warning Use of one of the HIL Timebase blocks is highly recommended for the QUARC Windows target. The QUARC system timebase on the Windows target is limited to 1 kHz. While its performance is good at 500 Hz, the jitter at 1 millisecond can be significant on some platforms. There is an experimental "fast system timer" that can be enabled on multiprocessor or multicore platforms that is not limited to 1 kHz and may yield less jitter, but it is much less efficient than a hardware timebase. The hardware timebases, on the other hand, provide better overall system performance.

Please refer to the Accessing Hardware page, or the help pages for the individual HIL blocks, for more details.

Communications - It's Completely Different!

Like hardware, different communications protocols are supported using different sets of blocks in WinCon. This approach makes it difficult to change communications protocols, because all the communications blocks in the model must be replaced.

QUARC takes a completely different approach and supplies a single set of blocks for all commmunications protocols. In this sense, the QUARC communications paradigm is similar to its generic hardware access. These blocks are prefixed with the name "Stream", since a communication channel is referred to as a "stream" in QUARC. The Stream blocks are found under

. There is also a corresponding Stream MATLAB API, Stream C API and Stream .NET API.

Just like the HIL blocks, the communications protocol in QUARC may be changed by editing a single parameter of just one of the communications blocks in the diagram. The rest of the diagram does not have to be modified. Thus, QUARC makes it easy to switch between pipes and TCP/IP, or between TCP/IP and UDP or any other communications protocol supported by QUARC. Quanser engineers have used this facility to transition seamlessly between a wired serial connection to an embedded board and a wireless TCP/IP connection - without replacing a single block in the diagram!

QUARC identifies a communications protocol using a Universal Resource Identifier or URI. A URI is similar to the Universal Resource Locators or URLs familiar to anyone who has used the World Wide Web, such as https://www.quanser.com. QUARC employs URIs for communications because they offer a generic mechanism for identifying the protocol and associated options. For example, the URI tcpip://quanser-dev:18000 indicates that the TCP/IP protocol should be used, with a hostname of "quanser-dev" and port 18000. The URI serial://quanser-uav:2?baud=57600,word=8,parity=none,stop=1 denotes the serial communications protocol on COM2, with a baud rate of 57600, 8 bits in a word, no parity and one stop bit. The hostname in this case is simply for informational purposes and is ignored by the serial protocol driver. Refer to the Universal Resource Identifiers page for more details on URIs. The help pages for the individual protocols outline the options available with each protocol.

The QUARC communications blocks are divided into three categories: basic, intermediate and advanced. The intermediate blocks are closest to the communications blocks used in WinCon.

The basic blocks are the easiest to use but the least flexible. Only one basic communications block is required to establish a connection with a remote application. For models that act as a client, use the Stream Client block. To behave as a server, use the Stream Server block. The basic blocks establish a "persistent" connection to the remote application. They automatically reconnect if the connection is lost so that the connection is maintained as much as possible. The persistence of the basic blocks allows for simple and robust communications with a single block!

The intermediate blocks are similar to the WinCon communications blocks. A client connection is established using a Stream Call block and then Stream Read or Stream Write blocks are used to send and receive data from the remote application. To act as a server, use the Stream Answer block. The intermediate blocks provide similar flexibility to the WinCon TCP/IP blocks.

The advanced blocks are low-level blocks that provide the greatest flexibility but are more difficult to use. The advanced blocks support both blocking and non-blocking I/O and are typically used in an asynchronous thread. Asynchronous threads are a new feature available in QUARC and are described as part of the multithreading capabilities of QUARC on the Multithreading page.

For a list of the communications protocols supported by QUARC, please refer to the QUARC Communications Protocols and Universal Resource Identifiers pages. For more information on communications in general, refer to the Communications article.

Control Panels - New Interfaces

WinCon Server provides the ability to make "control panels", which allow user interfaces to be defined that can interact with the real-time code without Simulink. However, these control panels are quite limited and not terribly appealing. In order to provide elegant, professional looking user interfaces QUARC interfaces with third-party tools that are specifically tailored for user interface design.

The QUARC communications blockset can always be used to communicate with a custom user interface. However, QUARC has built-in support for two user interface design tools: MATLAB GUIs and Altia Design.

MATLAB GUIs

MATLAB GUIs are typically created using the GUIDE tool that comes with MATLAB. Simply type guide at the MATLAB command prompt to open the GUIDE tool. GUIDE may be used to quickly design full-featured GUIs that contain sliders, buttons, edit fields, popup menus, listboxes and many other components. These components may be used to change parameters in a Simulink model by using the

function. If the model is connected to real-time code via external mode, then these parameter changes will take effect in the real-time code.

Of course, it would be useful to display plots in the MATLAB GUI that are driven by signals in the real-time code. QUARC provides a special set of blocks called Figure blocks that are capable of doing exactly that - they can drive an Axes component within a MATLAB GUI. The Figure block are found under

. There are Figure blocks for display time plots, XY graphs and images. Check out the list above for the latest set of blocks.

It is also possible to hide the Simulink model when developing a MATLAB GUI, and to start and stop the model from the GUI. All the features you need are available with QUARC! For a description of creating MATLAB GUIs for use with QUARC, please refer to the Creating MATLAB GUI's article.

Altia GUIs

Altia Design is a sophisticated third-party user interface development tool that can produce professional, elegant interfaces that operate independently of Simulink. It may be used to create standalone GUI applications that interact with the real-time code generated by QUARC. A set of blocks are provided for interfacing with an Altia GUI from the real-time code. These blocks are prefixed with the name "Altia". The Altia blocks are found under

. Note that Altia Design must be installed and configured according to the installation requirements on the help page for the Altia Initialize block before Altia Design may be used with QUARC.

An Altia GUI acts as a server. The real-time code connects to the Altia GUI via TCP/IP. This connection is established using the Altia Initialize block. Like the HIL Initialize block, the Altia Initialize allows the interface to be assigned a name. This name is then referenced by the other Altia blocks to refer to that interface. The Altia Initialize has convenient buttons to open the Altia Design editor or a runtime version of the Altia GUI. The help for the Altia Initialize block shows the command-line required to invoke the runtime version of the Altia GUI so that it can be run from a batch file. Note that the real-time code can interact with the Altia GUI right in the Altia Design Editor or with the runtime version of the GUI.

Values are retrieved from an Altia GUI using the Altia Get Value block. Likewise, values are written to the Altia GUI using the Altia Set Value block. For plotting, use the Altia Plot block and the plot components supplied with QUARC in the plots.dsn library. This library is found under the <QUARC_DIR>\altia\models folder, where <QUARC_DIR> is the directory in which QUARC was installed.

navigation bar