S-Function Connector to Simulink

The MxSuite supports interconnected Simulink models, but there is a difference compared with how Simulink does it. To interconnect Simulink models, you need Z-1 Delay Transforms on all signals that pass between models.

MxTransIt advances the time in all Simulink models by one tick and then in the next time step uses the outputs from all models (calculated from the previous step) as inputs for the new current step. This makes the Simulink blocks "logically concurrent" instead of sequential (as in Simulink). This approach is preferred if you want to have all SUTs execute the same time slice "logically concurrently."

When you select the Wrap method, the S-Function connects to the inputs and outputs of an existing model. You can do this at either the top-level subsystem, or you can select a lower-level subsystem. The transform automatically connects to the following:

•Inport Blocks and Outport Blocks – These are removed, and replaced with connections back to the S-Function

•Constant Blocks – These blocks are removed and replaced with connections back to the S-Function

•Display Blocks – These are left in the model and get connected back to the S-Function.

•Subsystem Blocks – All unconnected Input Ports, Output Ports, Enable Ports, and Trigger Ports are connected to the S-Function

oWhen a subsystem block is wrapped, MxSuite makes a copy of the block and performs a unit test on it as a standalone system.

oOnly the subsystem block that is being wrapped is copied to the model that MxVDev uses. This means that if there are Data Stores or other model blocks that are not provided in the subsystem to be wrapped, they will not exist in the harnessed model. However, all initialization functions, m files, and Configuration Set references are copied to the final model.

oThe configuration of the new model (including the tick period) is obtained and copied from the original model prior to harnessing. The configuration of the subsystem that is wrapped is therefore dependent upon the original model's configuration. So, for example, if the configuration of the original model is actually to a Configuration Set reference, the wrapped model uses the Configuration Set reference. This way, if you change the Configuration Set reference (or model parameters, etc.), the changes are propagated to the wrapped model without the need to reharness.

oSimilarly, if the configuration is a Library Block reference, changes to the Library Block are propagated to the wrapped model without the need to reharness.

oThe entire original model is compiled to ensure that the port types are obtained properly during the first harness. However, once the model is harnessed, only the subsystem that was harnessed is compiled. This means that if the subsystem that is harnessed is a library reference, and the library and/or original model is changed such that the port types are changed, a reharness is necessary so that the S-Function block sets the port types correctly.

Instead of connecting to inputs and outputs, the S-Function replaces a particular sub-system block. Once replaced, the outputs of the replaced subsystem are driven by the stimulus signals of the test case. The inputs to the replaced subsystem are read and reported back to the MxVDev test cases as response signals. This is usually used to insert the S-Function Simulink Transform into a closed-loop control model.

Replacing the entire model would leave nothing to test, so is not allowed.

We will start with the simple case where we have a new model that we want to start testing, and we need to create a new MxVDev project to test it. Note the following setting is required for your model.  In Simulink, at Main Menu->Simulation->Configuration Parameters‑>Solver Options, select:

•Type: Fixed Step

For MxVDev to harness a model properly, all user-defined data-types and buses must be available to the model prior to harnessing. Use the Script File Path property of the Simulink S-Function Transform in Mx‑Transit to execute an .m script that locates and defines any of these custom types. Additionally, each port to be harnessed should have its minimum and maximum parameters explicitly set in the model via the port's Block Parameters dialog, otherwise the full range of the data type will be used. The data type, dimensions, and rate of harnessed ports are propagated automatically to the MxVDev S-Function block.

Enum Ports

Vector Ports

If you are connecting to ports that are defined via a bus object, there are a couple extra steps:

1.In Simulink, export the bus definition to an M-file (.m):

a.In the model, select Tools->Bus Editor to open the Bus Editor.

b.Select File->Export to File. Save the file as type M-file.

This file is used in the Script File Path property. See Add and Configure the Simulink S‑Function Connector Transform below. Load the bus definitions prior to attempting to harness the model.

2.For each port that is defined via a bus and needs to be harnessed, set the UseBusObject property and the correct BusObject property in the Simulink model.

Note: Port ordering in the generated Transform is visually different than the port ordering in the model.

Limitations:

•You cannot Replace a block that has bus inputs or outputs.

•You cannot harness a subsystem that has an unconnected inport or outport that is defined by a bus.

For an example, see the Bus Demo sample project.

To ensure correct harnessing of bus ports of Simulink models, these guidelines must be followed:

•Ensure that bus signals are defined for buses in the model.

•Ensure that the bus signals are loaded into the workspace prior to the model loading. This can be done through a load callback, a workspace initialization, or through the S-Function Transform Script file path setting.

•When wrapping a subsystem using the S-Function transform, all bus inputs and outputs to and from the subsystem must be nonvirtual bus signals. If this is not the case, errors will occur during harnessing.

•When harnessing a model at the top level, ensure that all ports that are input or output signals that define buses have their data types explicitly set to the bus signal type. During harness, inputs to the model from MxVDev will always be converted to nonvirtual buses, and any virtual buses that are defined will remain virtual except for at entry into the S-Function block.

Simulink bus ports are complex. For this reason, we highly recommend that you review Matlab Simulink documentation before using them.

For more information, see Harnessing Bus Ports.

Create a new MxVDev project that we will use to test the Simulink model

1.From the main menu in MxVDev, click File->New->Project.

2.Proceed through the wizard with appropriate responses.

3.When prompted, select Custom Harness for the SUT Connection.

Once the new project has been created, the project path and name are displayed in the caption bar across the top of MxVDev.

To create the Custom Harness:

1.Launch MxTransIt. (File->New->Project will create a new Harness file if needed.)

2.Click File->Save As, and save the file  in your new MxVDev project, under the Transforms folder. In most cases you can use the default name "MxV.mxform".

Note that the new Harness file has the extension .mxform

1.Double-click Mathworks Simulink (via S-Function) in the MxTransit Toolbox.

•The Simulink Connector Transform is placed in MxTransit Harness window.

•Notice that it has no inputs and no outputs.

2.Select (click) the new Transform to display its Properties box.

3.In the Properties box, under the Matlab section, select the Preferred Matlab Version and Preferred Matlab Word Size. For more details, see Simulink Versions.

4.In the Simulink section, for Model File Path, browse to, and select your Simulink model file (.mdl or .slx).

5.Choose one of the following:

•To wrap, set the Attach Method property to Wrap.

•To replace, set the Attach Method property to Replace.

6.Enter the name of the Simulink subsystem block to be wrapped or replaced in the Subsystem to Wrap/Replace property. Leave the property blank to work with the top level of the model.

7.If the model has initializations, data type aliases, or bus definitions, they must be preloaded into the workspace. This can be accomplished by authoring a Matlab script (.m file) and setting the Script File Path property to that file. Setting this path instructs MxVDev to run the specified script prior to loading the model.

8.If you are connecting to ports that are defined via a bus object, enter the bus definitions script (.m file) in the Script File Path property. If you have not already created this file, see Export Bus Definitions above.

9.Click the Re-Attach to Model verb in the Properties box.
 
There may be a delay while Matlab/Simulink loads.

•Notice that when your model is loaded with the S-Function block, some type conversion blocks and connectors are added automatically to the model diagram. See Automatic Insertion for details of what occurs.

•When a subsystem block is wrapped, MxSuite makes a copy of the block and performs a unit test on it as a standalone system. For more details, see Wrap–Subsystem.

•The modified model is saved back into the same folder as the original model, with "MxV" and a version number appended to the file name.

•When you switch back to MxTransIt, notice the Simulink Transform has inputs and outputs that correspond to the I/O of your model.

10.Set the Tick Period property of the Simulink Connector to that of your model.  In Simulink, at Main Menu‑>Simulation->Configuration Parameters->Solver Options, get the setting for 'Fixed-Step Size'.  Ensure that the Tick Period property has the same value. (Normally, it is derived automatically from the model.) For more detail, see Simulink Tick Period.

11.Select File->Save.

The connection between the Transform Harness and the Simulink model file is now established.

Notes:

•Verify that the model is attached and compiles correctly.

•MxTransIt provides default values for the port properties. Review these properties by selecting the port and looking at the SignalInfo fields on the Properties tab.

•There may be cases where you wish to modify the properties of the Ports on the Connector Transform. Click the in the SignalInfo field of the port's Properties box.

•The path for the Simulink model is stored as a relative path in the mxform files if they are on the same drive. Model paths are displayed to the user as full paths.

•There is a property on the S-Function Transform named Harness Busses as Message Signals. The property has this effect:

oTrue: Creates a message Signal that transmits the bus Signal as one message (much like how CAN messages are transmitted). This is the preferred method for new projects.

oFalse: Harnesses bus signals by breaking them out from the busses in the model itself, and creates a port for every individual Signal.

When loading Transforms from previous versions, this property defaults to False to support previous harnesses. However, when a new S-Function Transform is created this property defaults to True to support the new method of bus support.

Before you are done with the Harness, you need to choose which ports to export.  Exported ports are made available as stimulus and response signals in MxVDev.  On more complex models you may choose not to export all ports.

1.In MxTransit, select (click) the Simulink Transform.

2.From the main menu, select Transform->Export Ports.

3.Select the ports that you want to be available in MxVDev for use in your TestCases and click OK.

4.You can review the exported ports by viewing the Exports tab at the right of the screen.

5.Click the Save button to save the Harness (.mxform) file.

6.You can close MxTransIt at this stage.

Now you are ready to use this Transform to connect MxVDev to your Simulink model.

Now configure the MxVDev project created above to use the new Harness.

1.When the reload prompt is displayed, click Yes.

2.When the Connecting Signals dialog is displayed, click OK to import the signals exported from MxTransIt.

You are now ready to create TestCases to run against the model.

MxV MATLAB Workspace Command is a message port on the S-Function. You can use it to send commands to your Simulink workspace. Sending a command to the port is the equivalent of typing the command into the Matlab Command Window. You can use this feature to run .m scripts or other workspace commands.

Simulink S-Function Transform (with ports) as seen in MxTransIt

To use this feature:

1.In MxTransIt, select the S-Function Transform, and export the MxV MATLAB Workspace Command port.

2.In MxVDev, add the signal to a TestCase.

3.Double-click on the plot area in the TestCase to add a transition.

4.Enter Matlab Workspace commands, one per line, in the Data box and click OK.

5.Run the test.

Sending Workspace Commands from a C# Snippet Transform

Edit the C# Snippet Transform to perform the following:

string myCommand = “workspaceCommands”;

OutPortName = System.Text.Encoding.ASCII.GetBytes(myCommand);

To execute multiple commands in a single time step, use code like this:

string myCommand = @”

command1;

command2;

command3;”;

OutPortName = System.Text.Encoding.ASCII.GetBytes(myCommand);

Connect the outport on the C# Snippet Transform to the MxV Matlab Workspace Command inport on the S-Function Transform.

Prior to Release 3.36.41.27477

•When a transition is transmitted to the port, the Simulink model is stopped and reset, the Workspace commands are executed, and the model is restarted.

Release 3.36.41.27477 and later: MxVDev sends workspace commands to the S-Function without resetting the model

•If workspace commands contain the single quote character, they must now be changed to two single quote characters (the character ‘ must be changed to ‘’ ). This is due to the fact that we must run the workspace command in a different manner. If the user sees an error along the lines of “Unexpected character constant” at simulation time, this is the reason.

•Workspace commands that are sent that change variables or parameters do not take effect until the next fundamental sample time that occurs in the model. This is due to the fact that the model completes its full cycle prior to the update to the workspace. For example, if the model has a fundamental sample time F (such as 0.01 ms), and there is a workspace command that sets variable X at time T (such as 1s), the change will not take effect until time T+F (1.01 ms). This is a limitation of the interaction of MATLAB and MxVDev (the update of the workspace is not completed until both the stimulus and responses have been processed). Therefore, if a workspace needs to change prior to time P, the workspace command needs to occur at least at time P-F.

•The model is no longer reset when a workspace command is sent. If MxVDev TestCases require this behavior, it requires that the user adds the Module Reset signal to the TestCase and add a reset just after the current workspace command. In addition, due to the limitation in the last paragraph, the workspace command that was previously run must be run prior to the new reset.

For an example, see the Simulink\S‑FunctionWorkspaceCommand sample project.

When using MxVDev in conjunction with Simulink, it is often useful to pause a TestCase at some point and look at the internal state of the Simulink model. You can do this using breakpoints or the Pause button in MxVDev. Set a breakpoint where you want the test to stop. When the breakpoint is hit, you can switch to Simulink. You can step into the model, set Simulink breakpoints, etc. When you are ready to resume, just click the run or step button in MxVDev. (There is no need to press Continue/Play in Simulink as MxVDev sends the continue command to the model.)

Note: When the model has a fundamental sample time F (such as 0.01 ms), it is ticked at F1, F2, F3, etc. Due to limitations described above, if a breakpoint is set at F2 or between time F1 and F2, and there is also a stimulus transition at that time, the stimulus may not be sent to MATLAB. Breakpoints must be set at least one fundamental sample time prior to any stimulus transitions to ensure that they are processed (in this example, at F1 or before). Avoid clicking the Pause button when transitions are about to be sent to Simulink as the exact cycle that the transition is applied to the model cannot be guaranteed.

This workspace variable is named MxVCurrentScenarioPath and is the full path to the Scenario that is being run. The variable is available only while the Scenario is running, and can be used by any workspace commands. Note that it is up to the user to split the path to obtain the Scenario name (e.g. by using the [pathstr, name, ext] = fileparts(MxVCurrentScenarioPath); see Matlab documentation for more information). Note, as with the VMC, if MxVDev is being used in single test case mode, the name of the Scenario will be ‘\path\to\testcase\folder\testcase.mxc.mxs’ with the Scenario file not existent.