Documentation Center

  • Trials
  • Product Updates

signalbuilder

Create and access Signal Builder blocks

Syntax

[time, data] = signalbuilder(block)
[time, data, signames] = signalbuilder(block)
[time, data, signames, groupnames] = signalbuilder(block)
block = signalbuilder([], 'create', time, data, signames, groupnames)
block = signalbuilder(path, 'create', time, data, signames, groupnames)
block = signalbuilder(path,'create', time, data, signames, groupnames, vis)
block = signalbuilder(path,'create', time, data, signames, groupnames, vis, pos)
block = signalbuilder(block, 'append', time, data, signames, groupnames)
block = signalbuilder(block, 'appendgroup', time, data, signames, groupnames)
signalbuilder(block,'appendsignal', time, data, signames)
signalbuilder(block, 'showsignal', signal, group)
signalbuilder(block, 'hidesignal', signal, group)
[time, data] = signalbuilder(block, 'get', signal, group)
signalbuilder(block, 'set', signal, group, time, data)
index = signalbuilder(block, 'activegroup')
[index, activeGroupLabel]= signalbuilder(block, 'activegroup')
signalbuilder(block, 'activegroup', index)
signalbuilder(block, 'annotategroup', onoff)
signalbuilder(block, 'print', [])
signalbuilder(block, 'print', config, printArgs)
figh = signalbuilder(block, 'print', config, 'figure')

Description

Use the signalbuilder command to interact programmatically with Signal Builder blocks.

    Note:   When you use the signalbuilder command to interact with a Signal Builder block, the Undo last edit and Redo last edit buttons on the block dialog box are grayed out. You cannot undo the results of using the signalbuilder command.

Creating and Accessing Signal Builder Blocks

[time, data] = signalbuilder(block) returns the time (x-coordinate) and amplitude (y-coordinate) data of the Signal Builder block, block.

The output arguments, time and data, take different formats depending on the block configuration:

Configuration

Time/Data Format

1 signal, 1 group

Row vector of break points.

>1 signal, 1 group

Column cell vector where each element corresponds to a separate signal and contains a row vector of points.

1 signal, >1 group

Row cell vector where each element corresponds to a separate group and contains a row vector of points.

>1 signal, >1 group

Cell matrix where each element (i, j) corresponds to signal i and group j.

[time, data, signames] = signalbuilder(block) returns the signal names, signames, in a string or a cell array of strings.

[time, data, signames, groupnames] = signalbuilder(block) returns the group names, groupnames, in a string or a cell array of strings.

block = signalbuilder([], 'create', time, data, signames, groupnames) creates a Signal Builder block in a new Simulink® model using the specified values. The preceding table describes the allowable formats of time and data. If data is a cell array and time is a vector, the time values are duplicated for each element of data. Each vector in time and data must be the same length and have at least two elements. If time is a cell array, all elements in a column must have the same initial and final value. Signal names, signames, and group names, groupnames, can be omitted to use default values. The function returns the path to the new block, block. Always provide time and data when using the create command. These two parameters are always required.

block = signalbuilder(path, 'create', time, data, signames, groupnames) creates a new Signal Builder block at path using the specified values. If path is empty, the function creates a block in a new model, which has a default name. If data is a cell array and time is a vector, the time values are duplicated for each element of data. Each vector within time and data must be the same length and have at least two elements. If time is a cell array, all elements in a column must have the same initial and final value. Signal names, signames, and group names, groupnames, can be omitted to use default values. The function returns the path to the new block, block. Always provide time and data when using the create command. These two parameters are always required.

block = signalbuilder(path,'create', time, data, signames, groupnames, vis) creates a new Signal Builder block and sets the visible signals in each group based on the values of the matrix vis. This matrix must be the same size as the cell array, data. Always provide time and data when using the create command. These two parameters are always required. You cannot create Signal Builder blocks in which all signals are invisible. For example, if you set the vis parameter for all signals to 0, the first signal is still visible.

block = signalbuilder(path,'create', time, data, signames, groupnames, vis, pos) creates a new Signal Builder block and sets the block position to pos. Always provide time and data when using the create command. These two parameters are always required. You cannot create Signal Builder blocks in which all signals are invisible. For example, if you set the vis parameter for all signals to 0, the first signal is still visible.

If you create signals that are smaller than the display range or do not start from 0, the Signal Builder block extrapolates the undefined signal data. It does so by holding the final value.

Adding New Groups

block = signalbuilder(block, 'append', time, data, signames, groupnames) or block = signalbuilder(block, 'appendgroup', time, data, signames, groupnames) appends new groups to the Signal Builder block, block. The time and data arguments must have the same number of signals as the existing block.

    Note:  

    • If you specify a value of ' ' or {} for signames, the function uses existing signal names for the new groups.

    • If you do not specify a value for groupnames, the function creates the new signal groups with the default group name pattern, GROUP #n.

Working with Signals

signalbuilder(block,'appendsignal', time, data, signames) appends new signals to all signal groups in the Signal Builder block, block. You can append either the same signals to all groups, or append different signals to different groups. Regardless of which signals you append, append the same number of signals to all the groups. Append signals to all the groups in the block; you cannot append signals to a subset of the groups. Correspondingly, provide time and data arguments for either one group (append the same information to all groups) or different time and data arguments for different groups. To use default signal names, omit the signal names argument, signames.

signalbuilder(block, 'showsignal', signal, group) makes signals that are hidden from the Signal Builder block visible. By default, signals in the current active group are visible when created. You control the visibility of a signal at creation with the vis parameter. signal can be a unique signal name, a signal scalar index, or an array of signal indices. group is the list of one or more signal groups that contains the affected signals. group can be a unique group name, a scalar index, or an array of indices.

signalbuilder(block, 'hidesignal', signal, group) makes signals, signal, hidden from the Signal Builder block. By default, all signals are visible when created. signal can be a unique signal name, a signal scalar index, or an array of signal indices. group is the list of one or more signal groups that contains the affected signals. group can be a unique group name, a scalar index, or an array of indices.

    Note:   For the showsignal and hidesignal methods, if you do not specify a value for the group argument, signalbuilder applies the operation to all the signals and groups.

Using Get/Set Methods for Specific Signals and Groups

[time, data] = signalbuilder(block, 'get', signal, group) gets the time and data values for the specified signal(s) and group(s). The signal argument can be the name of a signal, a scalar index of a signal, or an array of signal indices. The group argument can be a group name, a scalar index, or an array of indices.

signalbuilder(block, 'set', signal, group, time, data) sets the time and data values for the specified signal(s) and group(s). Use empty values of time and data to remove groups and signals. To remove a signal group, you must also remove all the signals in that group in the same command.

    Note:   For the set method, if you do not specify a value for the group argument, signalbuilder applies the operation to all signals and groups.

When removing signals, you remove all signals from all groups. You cannot select a subset of groups from which to remove signals, unless you are also going to also remove that group.

    Note:   The signalbuilder function does not allow you to alter and delete data in the same invocation. It also does not allow you to delete all the signals and groups from the application.

If you set signals that are smaller than the display range or do not start from 0, the Signal Builder block extrapolates the undefined signal data by holding the final value.

Querying, Labelling, and Setting the Active Group

index = signalbuilder(block, 'activegroup') gets the index of the active group.

[index, activeGroupLabel]= signalbuilder(block, 'activegroup') gets the label value of the active group.

signalbuilder(block, 'activegroup', index) sets the active group index to index.

Enabling Current Group Display

signalbuilder(block, 'annotategroup', onoff) controls the display of the current group name on the mask of the Signal Builder block.

onoff ValueDescription
'on'Default. Displays the current group name on the block mask.
'off'Does not display the current group name on the block mask.

Printing Signal Groups

signalbuilder(block, 'print', []) prints the currently active signal group.

signalbuilder(block, 'print', config, printArgs) prints the currently active signal group or the signal group that config specifies. The argument config is a structure that allows you to customize the printed appearance of a signal group. The config structure may contain any of the following fields:

FieldDescriptionExample Value
groupIndex

Scalar specifying index of signal group to print

2
timeRange

Two-element vector specifying the time range to print (must not exceed the block's time range)

[3 6]
visibleSignals

Vector specifying index of signals to print

[1 2]
yLimits

Cell array specifying limits for each signal's y-axis

{[-1 1],
 [0 1]}

extent

Two-element vector of the form:

[width, height]

specifying the dimensions (in pixels) of the area in which to print the signals

[500 300]
showTitle

Logical value specifying whether to print a title; true (1) prints the title

false

Set up the structure with one or more of these fields before you print. For example, if you want to print just group 2 using a configuration structure, configstruct, set up the structure as follows. You do not need to specify any other fields.

configstruct.groupIndex=2

The optional argument printArgs allows you to configure print options (see print in the MATLAB® Function Reference).

figh = signalbuilder(block, 'print', config, 'figure') prints the currently active signal group or the signal group that config specifies to a new hidden figure handle, figh.

Interpolating Missing Data Values

When specifying a periodic signal such as a Sine Wave, the signalbuilder function uses linear Lagrangian interpolation to compute data values for time steps that occur between time steps for which the signalbuilder function supplies data. When specifying periodic signals, specify them as a time vector that is defined as multiples of sample time, for example:

t = 0.2*[0:50]';

Examples

Example 1

Create a Signal Builder block in a new model editor window:

block = signalbuilder([], 'create', [0 5], {[2 2];[0 2]});

Get signal builder data from this block.

[time, data, signames, groupnames] = signalbuilder('untitled/Signal Builder')
time = 

    [1x2 double]
    [1x2 double]

data = 

    [1x2 double]
    [1x2 double]

signames = 

    'Signal 1'    'Signal 2'

groupnames = 

    'Group 1'

The Signal Builder block contains two signals in one group. Alter the second signal in the group:

signalbuilder(block, 'set', 2, 1, [0 5], [2 0])

To make this same change using the signal name and group name:

signalbuilder(block, 'set', 'Signal 2', 'Group 1', [0 5], [2 0])

Delete the first signal from the group:

signalbuilder(block, 'set', 1, 1, [], [])

Append the group with a new signal:

signalbuilder(block, 'append', [0 2.5 5], [0 2 0], 'Signal 2', 'Group 2');

Append another group with a new signal using appendgroup:

signalbuilder(block, 'appendgroup', [0 2.5 5], [0 2 0], 'Signal 2', 'Group 3');

Example 2

Create a Signal Builder block in a new model editor window:

block = signalbuilder([], 'create', [0 2], {[0 1],[1 0]});

The Signal Builder block has two groups, each of which contains a signal. To delete the second group, also delete its signal:

signalbuilder(block, 'set', 1, 2, [], [])

Example 3

Create a Signal Builder block in a new model editor window:

block = signalbuilder([], 'create', [0 1], ...
         {[0 0],[1 1];[1 0],[0 1];[1 1],[0 0]});

The Signal Builder block has two groups, each of which contains three signals.

Example 4

Create a Signal Builder block in a new model editor window:

block = signalbuilder([],'create',{[0 10],[0 20]},{[6 -6],...
[2 5]});

The Signal Builder block has two groups. Each group contains one signal.

Append a new signal group to the existing block.

block = signalbuilder(block,'append',[0 30],[10 -10]);

Append a new signal, sig3, to all groups.

signalbuilder(block,'appendsignal',[0 30],[0 10],'sig3');

Example 5

Create a Signal Builder block in a new model editor window:

time = [0 1];
data = {[0 0],[1 1];[1 0],[0 1];[1 1],[0 0]};
block = signalbuilder([], 'create', time, data);

The Signal Builder block has two groups. Each group contains three signals.

Delete the second group. To delete a signal group, also delete all the signals in the group.

signalbuilder(block, 'set',[1,2,3],'Group 2',[]);

Example 6

Create a Signal Builder block in a new model editor window:

block = signalbuilder([], 'create', [0 5], {[2 2];[0 2]});

The Signal Builder block has one group that contains two signals.

Hide the signal, Signal 1.

signalbuilder(block,'hidesignal','Signal 1', 'Group 1')

Signal 1 is no longer visible in the Signal Builder block.

Make Signal 1 visible again.

signalbuilder(block,'showsignal','Signal 1', 'Group 1')

Example 7

Create a Signal Builder block in a new model editor window:

block = signalbuilder([], 'create', [0 5], {[2 2] [0 2]});

The Signal Builder block has two groups, each with one signal.

Create a structure, configstruct, to customize the Signal Builder block that you want to print.

configstruct.groupIndex = 2;
configstruct.timeRange = [0 2];
configstruct.visibleSignals = 1;
configstruct.yLimits = {[0 1]};
configstruct.extent = [500 300];
configstruct.showTitle = true;

This sequence fills all the fields of the configstruct structure.

Print a view of the Signal Builder block to the default printer. The configstruct structure defines the view to print.

signalbuilder(block,'print',configstruct)

Print with print options, for example -dps.

signalbuilder(block,'print',configstruct,'-dps')

Print a view of the Signal Builder block as defined by the configstruct structure to a new hidden figure handle, figH.

figH = signalbuilder(block,'print',configstruct,'figure')
figure(figH)
Was this topic helpful?