Real-Time Workshop

Tutorial 5: Getting Started with External Mode Using GRT

This section provides step-by-step instructions for getting started with external mode, a very useful environment for rapid prototyping. The tutorial consists of four parts, each of which depends on completion of the preceding ones, in order. The four parts correspond to the steps that you would follow in simulating, building, and tuning an actual real-time application:

• Part 1: Setting Up the Model
• Part 2: Building the Target Executable
• Part 3: Running the External Mode Target Program
• Part 4: Tuning Parameters

The example presented uses the generic real-time target, and does not require any hardware other than the computer on which you run Simulink and Real-Time Workshop. The generated executable in this example runs on the host computer under a separate process from MATLAB and Simulink.

The procedures for building, running, and testing your programs are almost identical in UNIX and PC environments. The discussion notes differences where applicable.

For a more thorough description of external mode, including a discussion of all the options available, see Using the External Mode User Interface" in Chapter 6 of the Real-Time Workshop documentation.

Part 1: Setting Up the Model

In this part of the tutorial, you create a simple model, ext_example, and a directory called ext_mode_example to store the model and the generated executable:

1. Create the directory from the MATLAB command line by typing

• mkdir ext_mode_example
  

2. Make ext_mode_example your working directory:

• cd ext_mode_example
  

3. Create a model in Simulink with a Sine Wave block for the input signal, two Gain blocks in parallel, and two Scope blocks. The model is shown below. Label the Gain and Scope blocks as shown.
   
   
4. Define and assign two variables A and B in the MATLAB workspace as follows:

• A = 2; B = 3;
  

5. Open Gain block A and set its Gain parameter to the variable A as shown below.

6. Similarly, open Gain block B and set its Gain parameter to the variable B.

1. When the target program is built and connected to Simulink in external mode, new gain values can be downloaded to the executing target program by assigning new values to workspace variables A and B, or by editing the values in the block parameter dialog boxes.

7. Verify correct operation of the model. Open the Scope blocks and run the model. Given that A=2 and B=3, the output should look like this.
   
   
8. From the File menu, choose Save As. Save the model as ext_example.mdl.

Part 2: Building the Target Executable

In this section, you set up the model and code generation parameters required for an external mode compatible target program. Then you generate code and build the target executable.

1. Open the Simulation Parameters dialog box. On the Solver pane, set the Solver options Type to Fixed-step, select the discrete (no continuous states) solver algorithm. Set Fixed step size to 0.01. Leave the other parameters at their default values.
2. On the Workspace I/O pane, clear the Time and Output check boxes. In this exercise, data will not be logged to the workspace or to a MAT-file.
3. On the Real-Time Workshop pane, select Target configuration from the Category menu.

1. By default, the GRT target should be selected, as shown in this figure.
   
   

   If the GRT target is not selected, click the Browse button and select the GRT target from the System Target File Browser. Then click OK to close the browser. Return to the Real-Time Workshop pane and click Apply.

4. Select GRT code generation options from the Category menu and select the External mode option.This enables generation of external mode support code.
   
   
5. Click Apply.
6. On the Advanced pane, make sure that the Inline parameters option is not selected. External mode supports inlined parameters, but we will not be using inlined parameters in this tutorial.

1. The Advanced pane looks like the figure below.

7. From the Tools menu, select External Mode Control Panel. The External Mode Control Panel lets you configure host and target communications, signal monitoring, and data archiving. It also lets you connect to the target program and start and stop execution of the model code.
   
   

The top four buttons are for use after the target program has started. The three lower buttons open three separate dialog boxes:

• The Target interface button opens the External Target Interface dialog box, which configures the external mode communications channel.
• The Signal & triggering button opens the External Signal & Triggering dialog box, which configures which signals are viewed and how signals are acquired.
• The Data archiving button opens the External Data Archiving dialog box. Data archiving lets you save data sets generated by the target program for future analysis. This example does not use data archiving. See Data Archiving Dialog Box of the Real-Time Workshop documentation for more information.

8. Click the Target interface button to open the External Target Interface dialog box. This dialog box configures the external mode interface options.

1. The MEX-file for external interface field specifies the name of a MEX-file that supports host and target communications on the host side. The default is ext_comm, a MEX-file provided by Real-Time Workshop. ext_comm supports communication via the TCP/IP communications protocol.

   The MEX-file arguments field lets you specify arguments, such as a TCP/IP server port number, to be passed to the external interface program. Note that these arguments are specific to the external interface file you are using.

   For information on these arguments, see The External Interface MEX-File of the Real-Time Workshop documentation.

   This exercise uses the default arguments. Leave the MEX-file arguments field blank.

   The External Target Interface dialog box should appear as shown below.

9. Click OK to close the External Target Interface dialog box.
10. Close the External Mode Control Panel.
11. Save the model.
12. Return to the Real-Time Workshop pane. Click Build to generate code and create the target program. The content of subsequent messages depends on your compiler and operating system.The final message is

• ### Successful completion of Real-Time Workshop build procedure 
  for model: ext_example
  

In the next section, you will run the ext_example executable and use Simulink as an interactive front end to the running target program.

Part 3: Running the External Mode Target Program

The target executable, ext_example, is now in your working directory. In this section, you run the target program and establish communication between Simulink and the target.

The External Signal & Triggering dialog box displays a list of all the blocks in your model that support external mode signal monitoring and logging. The External Signal & Triggering dialog box also lets you configure which signals are viewed and how they are acquired and displayed. You can reconfigure the External Signal & Triggering dialog box while the target program runs.

In this exercise you will observe and use the default settings of the External Signal & Triggering dialog box.

1. From the Tools menu, select External Mode Control Panel.
2. In the External Mode Control Panel, click the Signal & triggering button.
3. The External Signal & Triggering dialog box opens. The default configuration of the External Signal & Triggering dialog box is designed to ensure that all signals are selected for monitoring. The default configuration also ensures that signal monitoring will begin as soon as the host and target programs have connected. The figure below shows the default configuration for ext_example.

4. Make sure that the External Signal & Triggering dialog box is set to the defaults as shown:
• Select all check box is selected. All signals in the Signal selection list are marked with an X in the Block column.)
• Trigger Source: manual
• Trigger Mode: normal
• Duration: 1000
• Delay: 0
• Arm when connect to target: selected

1. Click Close, and then close the External Mode Control Panel.

5. To run the target program, you must open a command prompt window (on UNIX systems, an Xterm window). At the command prompt, change to the ext_mode_example directory that you created in step 1. The target program is in this directory:

• cd ext_mode_example
  

1. Next, type the following command

   • ext_example -tf inf -w
     

   and press Return. The target program begins execution. Note that the target program is in a wait state, so there is no activity in the command prompt window.

   The -tf switch overrides the stop time set for the model in Simulink. The inf value directs the model to run indefinitely. The model code will run until the target program receives a stop message from Simulink.

   The -w switch instructs the target program to enter a wait state until it receives a Start real-time code message from the host. This switch is required if you want to view data from time step 0 of the target program execution, or if you want to modify parameters before the target program begins execution of model code.

6. Open Scope blocks A and B. At this point, no signals are visible on the scopes. When you connect Simulink to the target program and begin model execution, the signals generated by the target program will be visible on the scope displays.
7. The model must be in external mode before communication between the model and the target program can begin. To enable external mode, select External from the simulation mode pull-down menu located on the right side of the toolbar of the Simulink window. Alternatively, you can select External from the Simulation menu.
8. Reopen the External Mode Control Panel and click Connect. This initiates a handshake between Simulink and the target program. When Simulink and the target are connected, the Start real-time code button becomes enabled, and the caption of the Connect button changes to Disconnect.
9. Click the Start real-time code button.You should see the outputs of Gain blocks A and B on the two scopes in your model. With A=2 and B=3, the output looks like this.
   
   

Having established communication between Simulink and the running target program, you can tune block parameters in Simulink and observe the effects the parameter changes have on the target program. You will do this in the next section.

Part 4: Tuning Parameters

You can change the gain factor of either Gain block by assigning new values to the variables A or B in the MATLAB workspace. When you change block parameter values in the workspace during a simulation, you must explicitly update the block diagram with these changes. When the block diagram is updated, the new values are downloaded to the target program. To tune the variables A and B:

1. In the MATLAB command window, assign new values to both variables, for example:

• A = 0.5;B = 3.5;
  

2. Activate the ext_example model window. Select Update Diagram from the Edit menu, or press the Ctrl+D keys. As soon as Simulink has updated the block parameters, the new gain values are downloaded to the target program, and the effect of the gain change becomes visible on the scopes.

1. You can also enter gain values directly into the Gain blocks. To do this:

3. Open the dialog box for Gain block A or B in the model.
4. Enter a new numerical value for the gain and click Apply. As soon as you click Apply, the new value is downloaded to the target program and the effect of the gain change becomes visible on the scope.

1. Similarly, you can change the frequency, amplitude, or phase of the sine wave signal by opening the dialog box for the Sine Wave block and entering a new numerical value in the appropriate field.

   Note, however, that you cannot change the sample time of the Sine Wave block. Block sample times are part of the structural definition of the model and are part of the generated code. Therefore, if you want to change a block sample time, you must stop the external mode simulation and rebuild the executable.

5. To simultaneously disconnect host/target communication and end execution of the target program, pull down the Simulation menu and select Stop real-time code.

Tutorial 4: A First Look at Generated Code

Using Real-Time Workshop