Main Content

annotations

Control appearance of Simscape block based on the component

Syntax

annotations
   [Id1, Id2] : ExternalAccess=value;
   UILayout = [UIGroup("Title 1",p1,p2) UIGroup("Title 2",p3)] 
   Icon = 'filename';
   [port1, port2] : Side=value;
   [param1, param2] : UnitDropdown = common
end

Description

annotations begins the annotations section, which is terminated by an end keyword. The annotations section in a component file lets you provide annotations that control various cosmetic aspects of a Simscape™ block generated from this component.

Use the annotations section to:

  • Define conditional visibility of component members, such as parameters, variables, nodes, inputs, and outputs, in block icons and dialog boxes. Possible values are: modify, observe, and none.

  • Specify block interface layout by defining titled groups of component parameters, the order of these groups, and the order of parameters in each group. When you deploy the component as a custom Simscape block, these groups translate into dialog box tabs (and into Property Inspector tree nodes). UILayout is a class-level annotation, meaning that it can appear only once per component file. For more information, see Group and Reorder Block Parameters Using Annotation.

  • Specify a custom block icon and change it based on the block variant.

  • Control port location by placing it on a specific side of the block icon. Ports on a block icon correspond to nodes, inputs, and outputs declared in the underlying component file. Possible values are: left, right, top, and bottom.

  • Prepopulate a unit drop-down list for a parameter in the block dialog box with commonly used units.

Examples

The following example hides inapplicable parameters from the block dialog box based on the control parameter value.

component MyPipe
  parameters
    circular  = true;             % Circular pipe?
    d_in      = { 0.01, 'm' };    % Pipe internal diameter
    area      = { 1e-4, 'm^2' };  % Noncircular pipe cross-sectional area
    D_h       = { 1.12e-2, 'm' }; % Noncircular pipe hydraulic diameter
  end
  if circular 
  % Hide inapplicable parameters
    annotations
       [area, D_h] : ExternalAccess=none;
    end
    equations
       % First set of equations, for circular pipe 
    end
  else
  % Hide inapplicable parameter
    annotations
       d_in : ExternalAccess=none;
    end
    equations
       % Second set of equations, for noncircular pipe 
    end
  end
  [...] % Other parameters, variables, branches, equations
end

The next example exposes a thermal port H and changes the customized block icon based on the control parameter value.

parameters
    thermal_effects = false; % Model thermal effects?
end
nodes (ExternalAccess=none)
   H = foundation.thermal.thermal; 
end
if thermal_effects 
  % Use icon with additional thermal port
    annotations
       H : ExternalAccess=modify;
       Icon = 'pipe_thermal.jpg';
    end
end

The following example customizes the names and locations of block ports. The block contains two electrical ports, labeled + and -, located on the left and right sides of the block icon, respectively, and a thermal port H, located on the top side.

nodes
    H = foundation.thermal.thermal; 
    p = foundation.electrical.electrical; % +
    n = foundation.electrical.electrical; % -
end
annotations
    H : Side = top;
    p : Side = left;
    n : Side = right;
end

Note

You cannot conditionally switch port sides, that is, include Side annotations in branches of a conditional statement. For more information, see Control Port Locations Using Annotations.

The next example specifies that the drop-down list for the Gain parameter includes a list of common units, such as those available in the Simulink-PS Converter and the PS-Simulink Converter block dialog boxes.

annotations
    Gain : UnitDropdown = common
end
 
Introduced in R2019a