Documentation Center

  • Trial Software
  • Product Updates

Create a Custom Requirements Link Type

In this example, you implement a custom link type to a hypothetical document type, a text file with the extension .abc. Within this document, the requirement items are identified with a special text string, Requirement::, followed by a single space and then the requirement item inside quotation marks (").

You will create a document index listing all the requirement items. When navigating from the Simulink® model to the requirements document, the document opens in the MATLAB® Editor at the line of the requirement that you want.

To create a custom link requirement type:

  1. Write a function that implements the custom link type and save it on the MATLAB path.

    For this example, the file is rmicustabcinterface.m, containing the function, rmicustabcinterface, that implements the ABC files shipping with your installation.

  2. To view this function, at the MATLAB prompt, type:

    edit rmicustabcinterface

    The file rmicustabcinterface.m opens in the MATLAB Editor. The content of the file is:

    function linkType = rmicustabcinterface
    %RMICUSTABCINTERFACE - Example custom requirement link type
    %
    % This file implements a requirements link type that maps 
    % to "ABC" files.
    % You can use this link type to map a line or item within an ABC
    % file to a Simulink or Stateflow object.
    %
    % You must register a custom requirement link type before using it.
    % Once registered, the link type will be reloaded in subsequent
    % sessions until you unregister it.  The following commands
    % perform registration and registration removal.
    %
    % Register command:   >> rmi register rmicustabcinterface
    % Unregister command: >> rmi unregister rmicustabcinterface
    %
    % There is an example document of this link type contained in the
    % requirement demo directory to determine the path to the document
    % invoke:
    %
    % >> which demo_req_1.abc
    
    %  Copyright 1984-2010 The MathWorks, Inc.
    
        % Create a default (blank) requirement link type
        linkType = ReqMgr.LinkType;
        linkType.Registration = mfilename;
    
        % Label describing this link type
        linkType.Label = 'ABC  file (for demonstration)';
    
        % File information
        linkType.IsFile = 1;
        linkType.Extensions = {'.abc'};
    
        % Location delimiters
        linkType.LocDelimiters = '>@';
        linkType.Version = '';             % not required
    
        % Uncomment the functions that are implemented below
        linkType.NavigateFcn = @NavigateFcn;
        linkType.ContentsFcn = @ContentsFcn;
    
    
    function NavigateFcn(filename,locationStr)
        if ~isempty(locationStr)
            findId=0;
            switch(locationStr(1))
            case '>'
                lineNum = str2num(locationStr(2:end));
                openFileToLine(filename, lineNum);
            case '@'
                openFileToItem(filename,locationStr(2:end));
            otherwise
                openFileToLine(filename, 1);
            end
        end
    
    
    function openFileToLine(fileName, lineNum)
        if lineNum > 0        
            if matlab.desktop.editor.isEditorAvailable
                matlab.desktop.editor.openAndGoToLine(fileName, lineNum);
            end
        else
            edit(fileName);
        end
    
    
    function openFileToItem(fileName, itemName)
        reqStr = ['Requirement:: "' itemName '"'];
        lineNum = 0;
        fid = fopen(fileName);
        i   = 1;
        while lineNum == 0
            lineStr = fgetl(fid);
            if ~isempty(strfind(lineStr, reqStr))
                lineNum = i;
            end;
            if ~ischar(lineStr), break, end;
            i = i + 1;
        end;
        fclose(fid);
        openFileToLine(fileName, lineNum);
    
    
    function [labels, depths, locations] = ContentsFcn(filePath)
        % Read the entire file into a variable
        fid = fopen(filePath,'r');
        contents = char(fread(fid)');
        fclose(fid);
    
        % Find all the requirement items
        fList1 = regexpi(contents,'\nRequirement:: "(.*?)"','tokens');
    
        % Combine and sort the list
        items = [fList1{:}]';
        items = sort(items);
        items = strcat('@',items);
    
        if (~iscell(items) && length(items)>0)
         locations = {items};
         labels = {items};
        else
         locations = [items];
         labels = [items];
        end
    
        depths = [];
  3. To register the custom link type ABC, type the following MATLAB command:

    rmi register rmicustabcinterface

    The ABC file type appears on the Requirements Traceability Link Editor drop-down list of document types.

  4. Create a text file with the .abc extension containing several requirement items marked by the Requirement:: string.

    For your convenience, an example file ships with your installation. The example file is matlabroot\toolbox\slvnv\rmidemos\demo_req_1.abc. demo_req_1.abc contains the following content:

    Requirement:: "Altitude Climb Control"
    
    Altitude climb control is entered whenever:
    |Actual Altitude- Desired Altitude | > 1500 
    
    Units:
    Actual Altitude - feet
    Desired Altitude - feet
    
    Description:
    
    When the autopilot is in altitude climb 
    control mode, the controller maintains a 
    constant user-selectable target climb rate.  
    
    The user-selectable climb rate is always a 
    positive number if the current altitude is 
    above the target altitude.  The actual target 
    climb rate is the negative of the user 
    setting. 
    
    End of "Altitude Climb Control">
    
    
    Requirement:: "Altitude Hold"
    
    Altitude hold mode is entered whenever:
    |Actual Altitude- Desired Altitude | < 
      30*Sample Period*(Pilot Climb Rate / 60) 
    
    Units:
    Actual Altitude - feet
    Desired Altitude - feet
    Sample Period - seconds
    Pilot Climb Rate - feet/minute
    
    Description:
    
    The transition from climb mode to altitude 
    hold is based on a threshold that is 
    proportional to the Pilot Climb Rate.  
    
    At higher climb rates the transition occurs 
    sooner to prevent excessive overshoot. 
    
    End of "Altitude Hold"
    
    
    Requirement:: "Autopilot Disable"
    
    Altitude hold control and altitude climb 
    control are disabled when autopilot enable 
    is false.
    
    Description:
    
    Both control modes of the autopilot 
    can be disabled with a pilot setting.
    
    ENd of "Autopilot Disable"
    
    
    Requirement:: "Glide Slope Armed"
    
    Glide Slope Control is armed when Glide 
    Slope Enable and Glide Slope Signal 
    are both true. 
    
    Units:
    Glide Slope Enable - Logical
    Glide Slope Signal - Logical
    
    Description:
    
    ILS Glide Slope Control of altitude is only 
    enabled when the pilot has enabled this mode 
    and the Glide Slope Signal is true.  This indicates 
    the Glide Slope broadcast signal has been 
    validated by the on board receiver. 
    
    End of "Glide Slope Armed"
    
    
    Requirement:: "Glide Slope Coupled"
    
    Glide Slope control becomes coupled when the control 
    is armed and (Glide Slope Angle Error > 0) and 
     Distance < 10000 
    
    Units:
    Glide Slope Angle Error - Logical
    Distance - feet
    
    Description:
    
    When the autopilot is in altitude climb control 
    mode the controller maintains a constant user 
    selectable target climb rate.  
    
    The user-selectable climb rate is always a positive 
    number if the current altitude is above the target 
    altitude the actual target climb rate is the 
    negative of the user setting. 
    
    End of "Glide Slope Coupled"
  5. Open the following example model:

    aero_dap3dofaero_dap3dof
  6. Right-click the Reaction Jet Control subsystem and select Requirements Traceability > Open Link Editor.

    The Requirements Traceability Link Editor opens.

  7. Click New to add a new requirement link. The Document type drop-down list now contains the ABC file (for demonstration) option.

  8. Set Document type to ABC file (for demonstration) and browse to the matlabroot\toolbox\slvnv\rmidemos\demo_req_1.abc file. The browser shows only the files with the .abc extension.

  9. To define a particular location in the requirements document, use the Location field.

    In this example, the rmicustabcinterface function specifies two types of location delimiters for your requirements:

    • > — Line number in a file

    • @ — Named item, such as a bookmark, function, or HTML anchor

      Note:   The rmi reference page describes other types of requirements location delimiters.

    The Location drop-down list contains these two types of location delimiters whenever you set Document type to ABC file (for demonstration).

  10. Select Line number. Enter the number 26, which corresponds with the line number for the Altitude Hold requirement in demo_req_1.abc.

  11. In the Description field, enter Altitude Hold, to identify the requirement by name.

  12. Click Apply.

  13. Verify that the Altitude Hold requirement links to the Reaction Jet Control subsystem. Right-click the subsystem and select Requirements Traceability > 1. "Altitude Hold".

Create a Document Index

A document index is a list of all the requirements in a given document. To create a document index, MATLAB uses file I/O functions to read the contents of a requirements document into a MATLAB variable. The RMI extracts the list of requirement items.

The example requirements document, demo_req_1.abc, defines four requirements using the string Requirement::. To generate the document index for this ABC file, the ContentsFcn function in rmicustabcinterface.m extracts the requirements names and inserts @ before each name.

For the demo_req_1.abc file, in the Link Editor: Reaction Jet Control dialog box, click the Document Index tab. The ContentsFcn function generates the document index automatically.

Was this topic helpful?