Проектирование и создание пользовательского блока

Как спроектировать пользовательский блок

В целом, используйте следующий процесс для разработки пользовательского блока:

Предположим, что вы хотите создать настраиваемый блок насыщения, который ограничивает верхнюю и нижнюю границы сигнала на основе параметров блоков или значения входного сигнала. Во второй версии блока необходимо, чтобы опция строила график пределов насыщения после завершения симуляции. В следующих шагах примера разработки этих блоков. Библиотечный ex_customsat_lib содержит две версии настраиваемого блока насыщения.

Пример модели sldemo_customsat использует базовую версию блока.

Определение поведения пользовательских блоков

Начните с определения функций и ограничений пользовательского блока. В этом примере блок поддерживает следующие функции:

  • Включение и выключение верхнего или нижнего предела насыщения.

  • Установка верхних и/или нижних пределов через параметры блоков.

  • Установка верхнего и/или нижнего пределов с помощью входного сигнала.

Он также имеет следующие ограничения:

  • Входной сигнал под насыщением должен быть скаляром.

  • Входной сигнал и пределы насыщения должны иметь тип данных double.

  • Генерация кода не требуется.

Принятие решения о типе Пользовательского блока

На основе пользовательских функций блоков реализация должна поддерживать следующее:

  • Несколько входных портов

  • Относительно простой алгоритм

  • Нет непрерывных или дискретных состояний системы

Поэтому в этом руководстве реализуется пользовательский блок с помощью Level-2 MATLAB® S-функция. MATLAB S-функции поддерживают несколько входов и, поскольку алгоритм прост, не имеют значительных накладных расходов при обновлении схемы или симуляции модели. Описание различных функциональных возможностей MATLAB S-функций по сравнению с другими типами пользовательских блоков см. в разделе Сравнение функциональности пользовательских блоков.

Параметризация S-функции MATLAB

Начните с определения параметров S-функции. Этот пример требует четырех параметров:

  • Первый параметр указывает, как установлен верхний предел насыщения. Предел может быть выключен, установлен через параметры блоков или установлен через входной сигнал.

  • Второй параметр является значением верхнего предела насыщения. Это значение используется, только если верхний предел насыщения установлен через параметры блоков. В случае использования этого параметра, вы должны иметь возможность изменить значение параметров во время симуляции, т.е., параметр настраивается.

  • Третий параметр указывает, как установлен нижний предел насыщения. Предел может быть выключен, установлен через параметры блоков или установлен через входной сигнал.

  • Четвертый параметр является значением нижнего предела насыщения. Это значение используется, только если нижний предел насыщения установлен через параметры блоков. Как и с верхним пределом насыщения, этот параметр настраивается при использовании.

Первый и третий параметры S-функции представляют режимы, которые должны быть переведены в значения, которые S-функция может распознать. Поэтому задайте следующие значения для верхнего и нижнего режимов предела насыщения:

  • 1 указывает, что предел насыщения отключен.

  • 2 указывает, что предел насыщения устанавливается через параметры блоков.

  • 3 указывает, что предел насыщения устанавливается через входной сигнал.

Запись S-функции MATLAB

После того, как вы задаете параметры и функциональность S-функции, запишите S-функцию. Шаблон msfuntmpl.m предоставляет начальную точку для записи Level-2 S-функции MATLAB. В файле можно найти завершенную версию пользовательского блока насыщения custom_sat.m. Сохраните этот файл в рабочей папке перед продолжением этого руководства.

Эта S-функция изменяет шаблон S-функции следующим образом:

  • The setup функция инициализирует количество портов входа на основе значений, введенных для верхнего и нижнего режимов предела насыщения. Если пределы установлены через входные сигналы, метод добавляет входные порты к блоку. The setup затем метод указывает, что существует четыре параметра S-функции и устанавливает настраиваемость параметра. Наконец, метод регистрирует методы S-функции, используемые во время симуляции.

    function setup(block)
    
    % The Simulink engine passes an instance of the Simulink.MSFcnRunTimeBlock
    % class to the setup method in the input argument "block". This is known as
    % the S-function block's run-time object.
    
    % Register original number of input ports based on the S-function
    % parameter values
    
    try % Wrap in a try/catch, in case no S-function parameters are entered
        lowMode    = block.DialogPrm(1).Data;
        upMode     = block.DialogPrm(3).Data;
        numInPorts = 1 + isequal(lowMode,3) + isequal(upMode,3);
    catch
        numInPorts=1;
    end % try/catch
    block.NumInputPorts = numInPorts;
    block.NumOutputPorts = 1;
    
    % Setup port properties to be inherited or dynamic
    block.SetPreCompInpPortInfoToDynamic;
    block.SetPreCompOutPortInfoToDynamic;
    
    % Override input port properties
    block.InputPort(1).DatatypeID  = 0;  % double
    block.InputPort(1).Complexity  = 'Real';
    
    % Override output port properties
    block.OutputPort(1).DatatypeID  = 0; % double
    block.OutputPort(1).Complexity  = 'Real';
    
    % Register parameters. In order:
    % -- If the upper bound is off (1) or on and set via a block parameter (2)
    %    or input signal (3)
    % -- The upper limit value. Should be empty if the upper limit is off or
    %    set via an input signal
    % -- If the lower bound is off (1) or on and set via a block parameter (2)
    %    or input signal (3)
    % -- The lower limit value. Should be empty if the lower limit is off or
    %    set via an input signal
    block.NumDialogPrms     = 4;
    block.DialogPrmsTunable = {'Nontunable','Tunable','Nontunable', ...
        'Tunable'};
    
    % Register continuous sample times [0 offset]
    block.SampleTimes = [0 0];
    
    %% -----------------------------------------------------------------
    %% Options
    %% -----------------------------------------------------------------
    % Specify if Accelerator should use TLC or call back into
    % MATLAB script
    block.SetAccelRunOnTLC(false);
    
    %% -----------------------------------------------------------------
    %% Register methods called during update diagram/compilation
    %% -----------------------------------------------------------------
    
    block.RegBlockMethod('CheckParameters',      @CheckPrms);
    block.RegBlockMethod('ProcessParameters',    @ProcessPrms);
    block.RegBlockMethod('PostPropagationSetup', @DoPostPropSetup);
    block.RegBlockMethod('Outputs',              @Outputs);
    block.RegBlockMethod('Terminate',            @Terminate);
    %end setup function
    

  • The CheckParameters метод проверяет значения, введенные в Блок Level-2 MATLAB S-function.

    function CheckPrms(block)
    
    lowMode = block.DialogPrm(1).Data;
    lowVal  = block.DialogPrm(2).Data;
    upMode  = block.DialogPrm(3).Data;
    upVal   = block.DialogPrm(4).Data;
    
    % The first and third dialog parameters must have values of 1-3
    if ~any(upMode == [1 2 3]);
        error('The first dialog parameter must be a value of 1, 2, or 3');
    end
    
    if ~any(lowMode == [1 2 3]);
        error('The first dialog parameter must be a value of 1, 2, or 3');
    end
    
    % If the upper or lower bound is specified via a dialog, make sure there
    % is a specified bound. Also, check that the value is of type double
    if isequal(upMode,2),
        if isempty(upVal),
            error('Enter a value for the upper saturation limit.');
        end
        if ~strcmp(class(upVal), 'double')
            error('The upper saturation limit must be of type double.');
        end
    end
    
    if isequal(lowMode,2),
        if isempty(lowVal),
            error('Enter a value for the lower saturation limit.');
        end
        if ~strcmp(class(lowVal), 'double')
            error('The lower saturation limit must be of type double.');
        end
    end
    
    % If a lower and upper limit are specified, make sure the specified
    % limits are compatible.
    if isequal(upMode,2) && isequal(lowMode,2),
        if lowVal >= upVal,
            error('The lower bound must be less than the upper bound.');
        end
    end
    
    %end CheckPrms function
    

  • The ProcessParameters и PostPropagationSetup методы обрабатывают настройку параметра S-функции.

    function ProcessPrms(block)
    
    %% Update run time parameters
    block.AutoUpdateRuntimePrms;
    
    %end ProcessPrms function
    
    
    function DoPostPropSetup(block)
    
    %% Register all tunable parameters as runtime parameters.
    block.AutoRegRuntimePrms;
    
    %end DoPostPropSetup function

  • The Outputs метод вычисляет выход блока на основе настроек параметра S-функции и любых входных сигналов.

    function Outputs(block)
    
    lowMode    = block.DialogPrm(1).Data;
    upMode     = block.DialogPrm(3).Data;
    sigVal     = block.InputPort(1).Data;
    lowPortNum = 2; % Initialize potential input number for lower saturation limit
    
    % Check upper saturation limit
    if isequal(upMode,2), % Set via a block parameter
        upVal = block.RuntimePrm(2).Data;
    elseif isequal(upMode,3), % Set via an input port
        upVal = block.InputPort(2).Data;
        lowPortNum = 3; % Move lower boundary down one port number
    else
        upVal = inf;
    end
    
    % Check lower saturation limit
    if isequal(lowMode,2), % Set via a block parameter
        lowVal = block.RuntimePrm(1).Data;
    elseif isequal(lowMode,3), % Set via an input port
        lowVal = block.InputPort(lowPortNum).Data;
    else
        lowVal = -inf;
    end
    
    % Assign new value to signal
    if sigVal > upVal,
        sigVal = upVal;
    elseif sigVal < lowVal,
        sigVal=lowVal;
    end
    
    block.OutputPort(1).Data = sigVal;
    
    %end Outputs function

Размещение пользовательских блоков в библиотеке

Библиотеки позволяют вам делиться своими пользовательскими блоками с другими пользователями, легко обновлять функциональность копий пользовательского блока и собирать блоки для конкретного проекта в одно место. Если для пользовательского блока требуется шина в качестве интерфейса, можно совместно использовать объект шины с пользователями библиотеки, создав объект шины в словаре данных и прикрепив словарь к библиотеке (См. Ссылку словаря данных к пользовательским библиотекам).

Этот пример помещает пользовательский блок насыщения в библиотеку.

  1. В Simulink® Редактор, на вкладке Simulation, выберите New > Library.

  2. Из библиотеки User-Defined Functions перетащите Блок Level-2 MATLAB S-function в новую библиотеку.

  3. Сохраните библиотеку с именем файла saturation_lib.

  4. Дважды кликните блок, чтобы открыть диалоговое окно Function Block Parameters.

  5. В S-function name поле введите имя S-функции. Для примера введите custom_sat. В Parameters поле введите 2,-1,2,1.

  6. Нажмите OK.

    Вы создали пользовательский блок насыщения, который можно использовать совместно с другими пользователями.

Можно упростить использование блока, добавив настраиваемый пользовательский интерфейс.

Добавление пользовательского интерфейса к пользовательскому блоку

Можно создать диалоговое окно блока для пользовательского блока с помощью функций маскировки Simulink. Маскирование блока также позволяет вам добавить метки портов, чтобы указать, какие порты соответствуют входному сигналу и пределам насыщения.

  1. Откройте библиотеку saturation_lib который содержит созданный пользовательский блок,

  2. Щелкните правой кнопкой мыши Блок Level-2 MATLAB S-function и выберите Mask > Create Mask.

  3. На панели Icon & Ports в поле Icons drawing commands введите port_label('input',1,'uSig'), а затем нажмите Apply.

    Эта команда помечает порт по умолчанию как входной сигнал в состоянии насыщения.

  4. На панели Parameters & Dialog добавьте четыре параметра, соответствующих четырем параметрам S-Function. Для каждого нового параметра перетащите всплывающее окно или элемент управления в Dialog box раздел, как показано в таблице. Перетащите каждый параметр в группу Parameters.

    НапечататьБыстрыйИмяОценитьНастраиваемыйОпции всплывающих оконКоллбэк
    popupВерхний контур:upMode 

    Нет пределов

    Введите предел как параметр

    Ограничьте использование входного сигнала

    customsat_callback('upperbound_callback', gcb)
    editВерхний предел:upValН/Дcustomsat_callback('upperparam_callback', gcb)

    НапечататьБыстрыйИмяОценитьНастраиваемыйОпции всплывающих оконКоллбэк
    popupНижний контур:lowMode 

    Нет пределов

    Введите предел как параметр

    Ограничьте использование входного сигнала

    customsat_callback('lowerbound_callback', gcb)
    editНижний предел:lowValН/Дcustomsat_callback('lowerparam_callback', gcb)

    Скрипт MATLAB S-Function custom_sat_final.m содержит коллбэки параметров маски. Сохраните custom_sat_final.m в рабочую папку для определения коллбэков в этом примере. Этот скрипт MATLAB имеет два входных параметров. Первый входной параметр является вектором символов, указывающим, какой параметр маски вызвал коллбэк. Второй входной параметр является указателем на связанный Блок Level-2 MATLAB S-function.

    Рисунок показывает заполненную панель Parameters & Dialog в редакторе масок.

  5. На панели Initialization установите флажок Allow library block to modify its contents. Эта настройка позволяет S-функции изменять количество портов в блоке.

  6. На панели Documentation:

    • В поле Mask type введите

      Customized Saturation
    • В поле Mask description введите

      Limit the input signal to an upper and lower saturation value
      set either through a block parameter or input signal.

  7. Нажмите OK.

  8. Чтобы сопоставить параметры S-функции с параметрами маски, щелкните правой кнопкой мыши Блок Level-2 MATLAB S-function и выберите Mask > Look Under Mask.

  9. Измените поле S-function name на custom_sat_final и поле Parameters для lowMode,lowVal,upMode,upVal.

    Рисунок показывает диалоговое окно Function Параметры Блоков после изменений.

  10. Нажмите OK. Сохраните и закройте библиотеку, чтобы выйти из режима редактирования.

  11. Снова откройте библиотеку и дважды щелкните настраиваемый блок насыщения, чтобы открыть диалоговое окно маскированного параметра.

Чтобы создать более сложный пользовательский интерфейс, поместите графический пользовательский интерфейс MATLAB поверх маскированного блока. Блок OpenFcn вызывает графический пользовательский интерфейс MATLAB, который использует вызовы для set_param для изменения параметров Блока s-function на основе настроек в пользовательском интерфейсе.

Запись обратного коллбэка маски

Функция customsat_callback.m содержит код коллбэка маски для пользовательского диалогового окна параметра маски блока насыщения. Эта функция вызывает локальные функции, соответствующие каждому параметру маски, посредством вызова feval.

Следующая локальная функция управляет видимостью поля верхнего предела насыщения на основе выбора режима верхнего предела насыщения. Коллбэк начинается с получения значений для всех параметров маски с помощью вызова get_param с именем свойства MaskValues. Если коллбэк нуждался в значении только одного параметра маски, он мог вызвать get_param с определенным именем параметра маски, например get_param(block,'upMode'). Поскольку этому примеру нужно два значения параметров маски, он использует MaskValues свойство для сокращения числа вызовов до get_param.

Затем коллбэк получает видимости параметров маски с помощью вызова get_param с именем свойства MaskVisbilities. Этот вызов возвращает массив ячеек из векторов символов, указывающих на видимость каждого параметра маски. Коллбэк изменяет значения видимости маски на основе выбора режима верхнего предела насыщения, а затем обновляет текст метки порта.

Коллбэк наконец использует set_param команда для обновления MaskDisplay блока свойство для маркировки входных портов блока.

function customsat_callback(action,block)
% CUSTOMSAT_CALLBACK contains callbacks for custom saturation block

%   Copyright 2003-2007 The MathWorks, Inc.

%% Use function handle to call appropriate callback
feval(action,block)

%% Upper bound callback
function upperbound_callback(block)

vals = get_param(block,'MaskValues');
vis = get_param(block,'MaskVisibilities');
portStr = {'port_label(''input'',1,''uSig'')'};
switch vals{1}
    case 'No limit'
        set_param(block,'MaskVisibilities',[vis(1);{'off'};vis(3:4)]);
    case 'Enter limit as parameter'
        set_param(block,'MaskVisibilities',[vis(1);{'on'};vis(3:4)]);
    case 'Limit using input signal'
        set_param(block,'MaskVisibilities',[vis(1);{'off'};vis(3:4)]);
        portStr = [portStr;{'port_label(''input'',2,''up'')'}];
end
if strcmp(vals{3},'Limit using input signal'),
    portStr = [portStr;{['port_label(''input'',',num2str(length(portStr)+1), ...
        ',''low'')']}];
end
set_param(block,'MaskDisplay',char(portStr));

Окончательный вызов set_param вызывает setup функция в MATLAB S-функции custom_sat.m. Поэтому setup можно изменить функцию, чтобы задать количество портов входа на основе значений параметров маски вместо значений параметров S-функции. Это изменение на setup функция поддерживает соответствие количества портов в Блок Level-2 MATLAB S-function значениям, показанным в диалоговом окне параметра маски.

Измененная S-функция MATLAB custom_sat_final.m содержит следующие новые setup функция. Если вы переходите через это руководство, откройте файл и сохраните его в рабочей папке.

%% Function: setup ===================================================
function setup(block)

% Register original number of ports based on settings in Mask Dialog
ud = getPortVisibility(block);
numInPorts = 1 + isequal(ud(1),3) + isequal(ud(2),3);

block.NumInputPorts = numInPorts;
block.NumOutputPorts = 1;

% Setup port properties to be inherited or dynamic
block.SetPreCompInpPortInfoToDynamic;
block.SetPreCompOutPortInfoToDynamic;

% Override input port properties
block.InputPort(1).DatatypeID  = 0;  % double
block.InputPort(1).Complexity  = 'Real';

% Override output port properties
block.OutputPort(1).DatatypeID  = 0; % double
block.OutputPort(1).Complexity  = 'Real';

% Register parameters. In order:
% -- If the upper bound is off (1) or on and set via a block parameter (2)
%    or input signal (3)
% -- The upper limit value. Should be empty if the upper limit is off or
%    set via an input signal
% -- If the lower bound is off (1) or on and set via a block parameter (2)
%    or input signal (3)
% -- The lower limit value. Should be empty if the lower limit is off or
%    set via an input signal
block.NumDialogPrms     = 4;
block.DialogPrmsTunable = {'Nontunable','Tunable','Nontunable','Tunable'};

% Register continuous sample times [0 offset]
block.SampleTimes = [0 0];

%% -----------------------------------------------------------------
%% Options
%% -----------------------------------------------------------------
% Specify if Accelerator should use TLC or call back into
% MATLAB script
block.SetAccelRunOnTLC(false);

%% -----------------------------------------------------------------
%% Register methods called during update diagram/compilation
%% -----------------------------------------------------------------

block.RegBlockMethod('CheckParameters',      @CheckPrms);
block.RegBlockMethod('ProcessParameters',    @ProcessPrms);
block.RegBlockMethod('PostPropagationSetup', @DoPostPropSetup);
block.RegBlockMethod('Outputs',              @Outputs);
block.RegBlockMethod('Terminate',            @Terminate);
%endfunction
The getPortVisibility локальная функция в custom_sat_final.m использует режимы предела насыщения, чтобы создать флаг, который передается назад в setup функция. The setup функция использует этот флаг, чтобы определить необходимое количество входных портов.
%% Function: Get Port Visibilities =======================================
function ud = getPortVisibility(block)

ud = [0 0];

vals = get_param(block.BlockHandle,'MaskValues');
switch vals{1}
    case 'No limit'
        ud(2) = 1;
    case 'Enter limit as parameter'
        ud(2) = 2;
    case 'Limit using input signal'
        ud(2) = 3;
end

switch vals{3}
    case 'No limit'
        ud(1) = 1;
    case 'Enter limit as parameter'
        ud(1) = 2;
    case 'Limit using input signal'
        ud(1) = 3;
end

Добавление функциональности блоков с использованием коллбэков блоков

Определяемая пользователем насыщение с блоком графического изображения в customsat_lib использует коллбэки для добавления функциональности к исходному пользовательскому блоку насыщения. Этот блок предоставляет опцию для построения графика пределов насыщения, когда симуляция заканчивается. Следующие шаги показывают, как изменить исходный пользовательский блок насыщения, чтобы создать этот новый блок.

  1. Добавьте флажок в диалоговое окно параметра маски, чтобы включить и выключить опцию графического изображения.

    1. Щелкните правой кнопкой мыши по Блок Level-2 MATLAB S-function в saturation_lib и выберите Mask + Create Mask.

    2. На Parameters панели редактора масок добавьте пятый параметр маски со следующими свойствами.

      БыстрыйИмяНапечататьНастраиваемыйОпции типаКоллбэк
      Построение графика пределовplotcheckcheckboxНетНАcustomsat_callback('plotsaturation',gcb)

    3. Нажмите OK.

  2. Запишите коллбэк для нового флажка. Коллбэк инициализирует структуру, чтобы сохранить предельные значения насыщения во время симуляции в Блок Level-2 MATLAB S-function UserData. Скрипт MATLAB customsat_plotcallback.m содержит этот новый коллбэк, а также измененные версии предыдущих коллбэков для обработки нового параметра маски. Если вы следуете этому примеру, откройте customsat_plotcallback.m и скопируйте свои локальные функции над предыдущими локальными функциями в customsat_callback.m.

    %% Plotting checkbox callback
    function plotsaturation(block)
    
    % Reinitialize the block's userdata
    vals = get_param(block,'MaskValues');
    ud = struct('time',[],'upBound',[],'upVal',[],'lowBound',[],'lowVal',[]);
    
    if strcmp(vals{1},'No limit'),
        ud.upBound = 'off';
    else
        ud.upBound = 'on';
    end
    
    if strcmp(vals{3},'No limit'),
        ud.lowBound = 'off';
    else
        ud.lowBound = 'on';
    end
    
    set_param(gcb,'UserData',ud);

  3. Обновите S-функцию MATLAB Outputs метод для хранения пределов насыщения, если применимо, как это сделано в новой S-функции MATLAB custom_sat_plot.m. Если вы следуете этому примеру, скопируйте Outputs метод в custom_sat_plot.m над исходным Outputs метод в custom_sat_final.m

    %% Function: Outputs ===================================================
    function Outputs(block)
    
    lowMode    = block.DialogPrm(1).Data;
    upMode     = block.DialogPrm(3).Data;
    sigVal     = block.InputPort(1).Data;
    vals = get_param(block.BlockHandle,'MaskValues');
    plotFlag = vals{5};
    lowPortNum = 2;
    
    % Check upper saturation limit
    if isequal(upMode,2)
        upVal = block.RuntimePrm(2).Data;
    elseif isequal(upMode,3)
        upVal = block.InputPort(2).Data;
        lowPortNum = 3; % Move lower boundary down one port number
    else
        upVal = inf;
    end
    
    % Check lower saturation limit
    if isequal(lowMode,2),
        lowVal = block.RuntimePrm(1).Data;
    elseif isequal(lowMode,3)
        lowVal = block.InputPort(lowPortNum).Data;
    else
        lowVal = -inf;
    end
    
    % Use userdata to store limits, if plotFlag is on
    if strcmp(plotFlag,'on');    
        ud = get_param(block.BlockHandle,'UserData');
        ud.lowVal = [ud.lowVal;lowVal];
        ud.upVal = [ud.upVal;upVal];
        ud.time = [ud.time;block.CurrentTime];
        set_param(block.BlockHandle,'UserData',ud)
    end
    
    % Assign new value to signal
    if sigVal > upVal,
        sigVal = upVal;
    elseif sigVal < lowVal,
        sigVal=lowVal;
    end
    
    block.OutputPort(1).Data = sigVal;
    
    %endfunction

  4. Напишите функцию plotsat.m для построения графика пределов насыщения. Эта функция переносит указатель в Блок Level-2 MATLAB S-function и использует этот указатель для извлечения UserData блока. Если вы следуете этому руководству, сохраните plotsat.m в рабочую папку.

    function plotSat(block)
    
    % PLOTSAT contains the plotting routine for custom_sat_plot
    %   This routine is called by the S-function block's StopFcn.
    
    ud = get_param(block,'UserData');
    fig=[];
    if ~isempty(ud.time)
        if strcmp(ud.upBound,'on')
            fig = figure;
            plot(ud.time,ud.upVal,'r');
            hold on
        end
        if strcmp(ud.lowBound,'on')
            if isempty(fig),
                fig = figure;
            end
            plot(ud.time,ud.lowVal,'b');
        end
        if ~isempty(fig)
            title('Upper bound in red. Lower bound in blue.')
        end
        
        % Reinitialize userdata
        ud.upVal=[];
        ud.lowVal=[];
        ud.time = [];
        set_param(block,'UserData',ud);
    end
  5. Щелкните правой кнопкой мыши Блок Level-2 MATLAB S-function и выберите Properties. Откроется диалоговое окно Свойств блока». На панели Callbacks измените StopFcn чтобы вызвать графическое изображение коллбэка как показано на следующем рисунке, нажмите OK.

Похожие темы

Для просмотра документации необходимо авторизоваться на сайте