PLECS 3.6 Online Help

Masking Subsystems

Masking a subsystem allows you to create a custom user interface for a Subsystem block that hides the underlying schematic, making it appear as an atomic component with its own icon and dialog box. Many of the components in the PLECS component library are in fact masked subsystems. To mask a subsystem, select the Subsystem block, then choose Create mask... from the Subsystem submenu of the Edit menu or the block's context menu. The mask editor appears. The mask editor consists of four tabbed panes that are described in detail below.

Mask Icon

The Icon pane enables you to create icons that show descriptive text or labels, graphics and images.

[Picture]

Mask Icon Drawing Commands

The available drawing commands are described below. If you enter more than one command, the graphic objects are drawn in the order in which the commands appear. In case an error occurs during evaluation of the commands PLECS displays three question marks (? ? ?) in the mask icon.


Note  Unlike with Simulink masks, the PLECS drawing commands do not have access to variables defined in the mask or base workspace.

Text

text('text') displays a text in the center of the icon.

text(x, y, 'text' [, fontsize]) places the text at the coordinates x and y. The optional argument fontsize allows you to specify the font size.

The displayed text does not rotate or flip together with the icon. It is always displayed from left to right and it is centered both horizontally and vertically at its position.

Line

line(xvec, yvec) plots the vector yvec against the vector xvec. Both vectors must have the same length. The vectors may contain NaN and inf values. When NaNs or infs are encountered, the line is interrupted and continued at the next point that is not NaN or inf.

Patch

patch(xvec, yvec) draws a solid polygon whose vertices are specified by the vectors xvec and yvec. Both vectors must have the same length.

Circle

circle(x, y, r) draws a circle at the coordinates x and y with the radius r.

Image

image(xvec, yvec, imread('filename') [, 'on']) reads an image from the file filename and displays it on the mask icon. The parameter filename must either be an absolute filename (e.g. C:\images\myimage.png) or a relative filename that is appended to the model's directory (e.g. images\myimage.png). The two-element vectors xvec and yvec specify the minimum and maximum coordinates of the image's extent.

Use the optional flag 'on' to indicate that the image data should rotate or flip together with the mask icon. By default, this is set to 'off', and the image data remains stationary.

Color

color(r, g, b) changes the current drawing color. The new color is given by r, g and b which specify the red, green and blue components. Each value is given as an integer in the range from 0 to 255.

Examples:
color(0, 0, 0) changes the color to black.
color(255, 0, 0) changes the color to red.
color(255, 255, 255) changes the color to white.

Mask Icon Coordinates

All coordinates used by the mask drawing commands are expressed in pixels. The origin of the coordinate system is always the center of the block icon; it is moved when the block is resized.

Use the icon frame and/or the terminal locations as reference points in order to position graphic elements. Both the frame and the terminals snap to a grid of 10 by 10 pixels.

Mask Icon Properties

Show subsystem frame
The subsystem frame is the rectangle that encloses the block. It is drawn if this property is set, otherwise it is hidden.
Hide terminal labels
This property controls whether the terminal labels underneath the icon are shown or hidden. A terminal label is only shown if this property is unset and the name of the corresponding port block is visible.
Icon rotates
If drawing commands are given this property determines whether the drawn icon rotates if the component is rotated. The drawn icon remains stationary if this property is unchecked.

Mask Parameters

The Parameters pane enables you to define the parameters that will appear in the dialog box of the masked subsystem.

[Picture]

Prompts and Associated Variables

Mask parameters are defined by a Prompt, a Variable and a Type. The prompt provides information that helps the user identify the purpose of a parameter. The variable name specifies the variable that will be assigned the parameter value.

Mask parameters appear on the dialog box in the order they appear in the prompt list. You can add or remove parameters or change their order by using the four buttons to the left of the prompt list.

Parameter Types

Parameters of type Edit are shown as a text edit field. The entered text is interpreted as a MATLAB/Octave expression and is usually expected to evaluate to a numeric value. Parameters of type String are shown as a combination of a text edit field and a switch that determines whether the entered text should be interpreted as a literal string or as a variable or expression that evaluates to a string. Parameters of type Combo Box offer a choice of predefined values. The possible values are defined in the Combo Box values field with each line representing one value. Parameters of type Check Box can be set to false or true. Parameters of type Thermal allow to specify a thermal description. See section Thermal Description Parameter for more details.

Tab Names

You can group parameters into separate tabs shown in the parameter dialog by assigning a tab name in the Tab column. All parameters that have the same tab name will appear on the same tab page in the parameter dialog.

Tunable Parameters

By default, mask parameter values cannot be modified during a simulation. However, if you check the box in the Tunable column, the corresponding parameter will be made tunable so that you can in fact modify it interactively during a simulation by entering a new value in the parameter dialog. Whenever you change the parameter, PLECS will re-evaluate the parameter variable and the mask initialization commands and propagate the new variable values to the underlying components, which in turn must have tunable parameters. If a changed variable is used in a non-tunable component parameter, the change will have no effect until the simulation is restarted.

Variable Scope

PLECS associates a local variable workspace with each masked subsystem that has one or more mask parameters defined. Components in the underlying schematics can only access variables that are defined in this mask workspace.

Initialization Commands

The mask initialization commands are evaluated in the mask workspace when a simulation is started. You can enter any valid MATLAB expression, consisting of MATLAB functions, operators, and variables defined in the mask workspace. Variables defined in the base workspace cannot be accessed.

Mask Probe Signals

The Probes pane enables you to define the probe signals that the masked subsystem will provide to the PLECS Probe. Mask probe signals appear in the probe editor in the order they appear in the mask signal list. You can add or remove signals or change their order by using the four buttons to the left of the signal list.

[Picture]

Mask probe signals are defined as vectors of probe signals from components below the subsystem mask. For this reason the controls in the lower half of the dialog are identical to those of the probe editor. In order to define a mask signal, select the signal in the list and then drag the desired components into the dialog window. The new components are added to the bottom of the list of probed components. Next, select the components one by one and enable the desired component signals in the list on the right side by using the check boxes.

Mask Documentation

The Documentation pane enables you to define the descriptive text that is displayed in the dialog box of the masked subsystem.

[Picture]

Mask Type

The mask type is a string used only for purposes of documentation. PLECS displays this string in the dialog box and appends "(mask)" in order to differentiate masked subsystems from built-in components.

Mask Description

The mask description is informative text that is displayed in the dialog box in the frame under the mask type. Long lines of text are automatically wrapped to fit into the dialog box. You can force line breaks by using the Enter or Return key.

Unprotecting Masked Subsystems

If you define a mask icon for a Subsystem block, PLECS automatically protects the block and the underlying schematic. You can no longer resize the Subsystem block or modify the sub-schematic. The purpose of this protection is to prevent the user from making unintentional changes that might render the icon useless.

If you want to change a masked Subsystem block, you can unprotect it by choosing Unprotect from the Subsystem submenu of the Edit menu or the block's context menu. You can later protect it again by choosing Protect from the same menus.