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.
Mask Editor Icon Tab
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') 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(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(xvec, yvec) draws a solid polygon whose vertices are specified by the vectors xvec and yvec. Both vectors must have the same length.
circle(x, y, r) draws a circle at the coordinates x and y with the radius r.
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(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.
Mask Editor Parameters Tab
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.
Note In PLECS Standalone, the maximum length of variable names is 63 characters. This is due to the way, in which a mask workspace is stored in PLECS and exchanged with Octave. It is advisable to observe this limit also in the PLECS Blockset to ensure that a model can be exchanged with PLECS Standalone.
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/Octave expression, consisting of MATLAB/Octave functions, operators, and variables defined in the mask workspace. Variables defined in the base workspace cannot be accessed.
Note In PLECS Standalone, the maximum length of variable names is 63 characters. This is due to the way, in which a mask workspace is stored in PLECS and exchanged with Octave. It is advisable to observe this limit also in the PLECS Blockset to ensure that a model can be exchanged with PLECS Standalone.
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.
Mask Editor Probes Tab
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.
Mask Editor Documentation Tab
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.