Command Line Tools

This section explains how the QUARC command line tools may be used to manage models. These tools give you the ability to perform tasks such as downloading, running or stopping a model on a QUARC target right from a Windows Command Prompt, or a Linux Shell. The command line tools may be used on a host computer or the target machine. In fact, once a model has been built and it is no longer necessary to modify the model, the associated QUARC executable file may be used exclusively - MATLAB does not even have to be installed. All you need to download, run, stop or otherwise manage the model is QUARC and its command line tools. Of course, if modifications are required to the model then MATLAB and Simulink are required, in addition to the QUARC Simulink Development Environment. For information on how to use QUARC executable files to manage models on the target, please refer to the Using Windows Explorer to Manage Models reference page.

The following is the general syntax for using the QUARC command line tools. The square brackets indicate optional arguments. The vertical bar separates mutually exclusive options and the angle brackets delimit parameters and should not be included. The order of the hyphenated options is not important. However, the model name and model arguments must appear in the order shown.

quarc_run [-d|-i] [-c|-D|-l|-r|-q|-b|-B|-n|-k|-u] [-Q] [-t <URI> ] <model> [<arguments>]

Please keep in mind that regardless of your choice of action, the command always starts with quarc_run. The actual action to be taken (running, stopping, etc.) is specified by including the appropriate option letter from the above list. A detailed description of each option is given below. The model parameter specifies the model to which the command applies and should be replaced by the name of the executable file generated upon building that model. Note that a different model executable is generated for each target type for which you build code. Executables generated for QUARC Windows targets have the .rt-win64 extension while executables for other targets would have the .rt-{target_type} extension. You should include these suffixes when specifying your model's name.

The arguments parameter specifies the arguments you wish to pass to the model. For a complete list of the recognized model arguments and their functionality, please refer to the MEX-File Arguments section in QUARC documentation. In general, the -w argument should not be specified for a model, because it will cause the model to wait for Simulink to connect and start the model before running the real-time code.

The model arguments do support some format specifiers. See the Model Arguments Format Specifiers section below for the complete list.

In Windows, the Command Prompt window may be opened by selecting Start/All Programs/Accessories/Command Prompt. When using Linux targets, the Secure SHell (SSH) network protocol can be used, for example, from a Windows-based ssh client program to connect to the remote Linux target. Typing the following command displays a succinct usage help message:

quarc_run -?

The options available to the quarc_run command are described in more details below:

-d

Including the -d option causes a dialog box to open in which you can specify the model arguments as well as the target URI to be used to communicate with the target. In this case, you do not need to include the target URI or model arguments on the command-line. They may be specified in the Target URI and Model arguments fields of the dialog respectively. The -d option can only be used when quarc_run is executed from a Windows machine. Assuming that a QUARC executable file named Sample_QUARC_Executable.rt-win64 resides in the current directory of the Windows Command Prompt, the following command causes the dialog box depicted in the figure to open.

quarc_run -d -r Sample_QUARC_Executable.rt-win64

This dialog varies slightly depending on the other options specified on the command-line. In this case, the -r option was specified, which downloads the executable to the target and runs the code on that target. The target URI identifying the target and the model arguments may be entered in their respective fields. Notice that the QUARC command-line tools can interface with a remote target. The command does not have to be run on the target itself, although it is possible to do so. Once you are done, clicking on Run causes the model you have specified to be downloaded to and loaded on the target because the -r option was also specified. The important issue to remember when using this option is that if the box next to "Use these parameters as defaults for this target type" is checked, the target URI you enter will become the default. As a result, this target URI will be employed on subsequent uses of the command line tools unless it is changed via the -d option and this dialog or the target URI is explicitly specified using the -t <URI> option, which will be discussed later in this page. If the box next to "Use these parameters as defaults for this target type" is not checked, the target URI you enter will only be used this once.

-i

Including the -i option causes an interactive menu to be displayed in which you can specify the model arguments as well as the target URI to be used to communicate with the target. In this case, you do not need to include the target URI or model arguments on the command-line. They may be specified in the Target URI and Model arguments fields of the menu respectively. The -i option can only be used when quarc_run is executed from a Linux target. Assuming that a QUARC executable file named Sample_QUARC_Executable has already been compiled on (and downloaded to) the target, the following command causes the interactive menu to be displayed as shown below.

quarc_run -i -r Sample_QUARC_Executable.rt-{target}

                    
*** Model parameters ***
Target URI [tcpip://localhost:17000]:
Model arguments [-d /tmp -uri tcpip://localhost:17001]:
Do you want to use these parameters as the defaults for this target type {'y'|'yes'|'n'|'no'} [y]?

Select operation to perform:
1 - Run the model with the defined parameters
2 - Cancel
Enter your selection {1|2} [1]:
                

This menu varies slightly depending on the other options specified on the command-line. In this case, the -r option was specified, which downloads the executable to the target and runs the code on that target. The target URI identifying the target and the model arguments may be entered in their respective fields. Notice that the QUARC command-line tools can interface with another remote target. Once you are done, selecting option 1 (i.e., default) to "Run the model with the defined parameters" causes the model you have specified to be downloaded to and loaded on the target because the -r option was also specified. The important issue to remember when using this option is that if 'y' or 'yes' is entered in response to "Do you want to use these parameters as the defaults for this target type?", the target URI you enter will become the default. As a result, this target URI will be employed on subsequent uses of the command line tools unless it is changed via the -i option and this menu or the target URI is explicitly specified using the -t <URI> option, which will be discussed later in this page. If 'y' or 'yes' is not entered in response to "Do you want to use these parameters as the defaults for this target type?", the target URI you enter will only be used this once.

-c

Including this option in Windows causes a QUARC Console window to be opened in which you can monitor the standard I/O of the model specified as part of the command. When executing this option on a Linux target, the QUARC Console uses the shell window itself (where the quarc_run command was originally launched) for the standard I/O with the model. In this situation, you can press Ctrl-C to quit the QUARC Console mode and come back to the original Linux shell. It is possible to specify the target URI by including either the -t <URI> option, which will be discussed below, or the -d option, which, as mentioned above, opens a dialog where the target URI can be entered. If the target URI is not specified, the default target URI will be used to communicate with the target. Assuming that a QUARC executable file named Sample_QUARC_Executable.rt-win64 resides in the current directory of the Windows Command Prompt and that a default target URI of shmem://quarc-target:1 is being used, the following command causes a console window to be opened for this model on the aforementioned URI.

quarc_run -c Sample_QUARC_Executable.rt-win64

If multiple models are run on the target, it is possible to open a QUARC Console in which you can monitor the standard I/O of all the models at once. Simply replace the <model> argument of the command by an asterisk, followed by an extension appropriate to the target, such as .rt-win64 for QUARC Windows targets. Again, please note that if you do not specify the target URI, the default will be used, meaning the QUARC Console will monitor models running on the target specified by the default target URI.

-D

Including this option causes the real-time code generated for the model specified to be downloaded to the target. Please keep in mind that you can specify the target URI by including either the -t <URI> option or the -d or -i option. If you choose to include the -d or -i option, a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target. Assuming that a QUARC executable file named Sample_QUARC_Executable.rt-win64 resides in the current directory of the Windows Command Prompt, the following command causes the real-time code generated for this model to be downloaded to the target identified by the default target URI.

quarc_run -D Sample_QUARC_Executable.rt-win64

-l

Including this option causes the real-time code generated for the model you specify to be loaded or run on the target. This option only executes the real-time code. It assumes that the code has been already downloaded to the target. If this option is used without having downloaded the code already then an error is generated stating that the specified file can not be found. Please keep in mind that you can specify the target URI by either including the -t <URI> option or using the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target.

-r

Including this option will cause the real-time code generated for the specified model to be downloaded to the target and then executed on the target. Therefore, one may think of this option as being a combination of the -D and -l options. You can specify the target URI by either including the -t <URI> option or using the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target. Assuming that a QUARC executable file named Sample_QUARC_Executable.rt-win64 resides in the current directory of the Windows Command Prompt, the following command causes the real-time code generated for this model to be downloaded to the target identified by the default target URI and to be executed on that target.

quarc_run -r Sample_QUARC_Executable.rt-win64

-q

Including this option causes the real-time code running on a target to be stopped or to "quit". You can specify the target URI by either including the -t <URI> option or the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target.

If you are running multiple models on a target at once and would like to stop them all, you can simply replace the <model> parameter of the command by an asterisk followed by the extension appropriate to the target type, such as .rt-win64 for QUARC Windows targets. Once again, the target URI may be specified explicitly by including the -t <URI> option in your command or the -d or -i option.

-b

Including this option causes the real-time code generated for the specified model to be downloaded to the target and configured to load the next time the target boots. You can specify the target URI by either including the -t <URI> option or the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target.

-B

Including this option will cause the specified model to be configured to load the next time the target boots. This option assumes that the real-time code has been downloaded to the target already. You can specify the target URI by either including the -t <URI> option or the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target.

-n

If you have previously configured a model to load at boot, you can use this option to remove this setting and configure the model not to load at boot. You can specify the target URI by either including the -t <URI> option or the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target.

-k

Including this option will forcefully terminate the specified model on the target.

WARNING: USING THIS OPTION IS NOT RECOMMENDED UNLESS ABSOLUTELY NECESSARY. SYSTEM RESOURCES MAY BE LOST ON THE TARGET AS A RESULT OF USING THIS OPTION.

You can specify the target URI by either including the -t <URI> option or the -d or -i option. If you choose to include the -d or -i option then a dialog or menu, respectively, will be displayed in which you can specify the target URI, as explained above. If you do not specify the target URI using either one of these options then the default target URI will be used to communicate with the target.

-u

When using MAT-file logging, the log file is generated on the target. If the target is a remote machine then this MAT-file must be uploaded from the target to the host in order to load the results into MATLAB. This option uses the name of the executable and the current directory for the model specified in the -d option of the Model arguments parameter to locate the MAT-file and upload it to the current MATLAB directory on the host for analysis. The model does not need to be compiled with external mode for this option to work so it provides a convenient method of getting the MAT-file for any model and avoids the need to use ftp or another file transfer tool to get the MAT-file from the target. Assuming that a QUARC executable file named Sample_QUARC_Executable.rt-{target} resides in the current directory of the Windows Command Prompt, the following command causes the MAT-file logging file saved for this model under /tmp on the target machine to be uploaded from the target identified by the default target URI to the current directory of the Windows machine where the command is being executed.

quarc_run -u Sample_QUARC_Executable.rt-{target} -d /tmp

-Q

The -Q option causes the quarc_run command to operate quietly. It suppresses errors that it would otherwise generate. For example, the command to stop all models on 64-bit Windows:

quarc_run -q *.rt-win64

will produce an error dialog if no models are currently running. To prevent this dialog from appearing, add the -Q option:

quarc_run -q -Q *.rt-win64

-t <URI>

This option can be used to explicitly specify the target URI in cases where you do not want the default target URI to be used. Assuming that a QUARC executable file resides in the current working directory of the Windows Command Prompt, the following command causes the real-time code generated for the model to be downloaded to the target specified by the target URI (in this case local shared memory) regardless of the default settings.

quarc_run -D -t shmem://quarc-target:1 Sample_QUARC_Executable.rt-win64

Model Argument Format Specifiers

The model arguments specified on the quarc_run command line may contain certain format specifiers that simplify the use of model arguments across models. The full list of format specifiers are listed below:

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.

Link to this page.