Main Content

Custom Link Types

Note

Requirements Management Interface (RMI) provides legacy functionality. Starting in R2022a, useslreq.refreshCustomizations. For more information, seeDefine Custom Requirement and Link Types by Using sl_customization Files.

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®模型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. 编写一个函数,实现了自定义链接type and save it on the MATLAB path.

    For this example, the file isrmicustabcinterface.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 filermicustabcinterface.mopens 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 theOutgoing Links Editordrop-down list of document types.

  4. 创建一个文本文件.abcextension containing several requirement items marked by theRequirement::string.

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

    要求::“攀爬高度控制”高度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 theaero_dap3dof模型. At the MATLAB command line, enter:

    openExample('simulink_aerospace/DevelopingTheApolloLunarModuleDigitalAutopilotExample')
    Close the Apollo Lunar Module Descent Animation.

  6. In theaero_dap3dof模型, right-click the Reaction Jet Control subsystem and selectRequirements>Open Outgoing Links dialog.

    The Outgoing Links Editor opens.

  7. ClickNewto add a new requirement link. TheDocument typedrop-down list now contains theABC file (for demonstration)option.

  8. SetDocument typetoABC file (for demonstration)and browse to thematlabroot\toolbox\slvnv\rmidemos\demo_req_1.abcfile. The browser shows only the files with the.abcextension.

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

    In this example, thermicustabcinterfacefunction 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

    Thermireference page describes other types of requirements location delimiters.

    TheLocationdrop-down list contains these two types of location delimiters whenever you setDocument typetoABC file (for demonstration).

  10. SelectLine number. Enter the number26, which corresponds with the line number for theAltitude Holdrequirement indemo_req_1.abc.

  11. In theDescriptionfield, enterAltitude Hold, to identify the requirement by name.

  12. ClickApply.

  13. Verify that theAltitude Holdrequirement links to the Reaction Jet Control subsystem. Right-click the subsystem and selectRequirements>1. “Altitude Hold”.

Create a Document Index

Adocument indexis 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使用字符串,定义了四个需求Requirement::. To generate the document index for this ABC file, theContentsFcnfunction inrmicustabcinterface.mextracts the requirements names and inserts@before each name.

For thedemo_req_1.abcfile, in theOutgoing Links: Reaction Jet Controldialog box, click theDocument Indextab. TheContentsFcnfunction generates the document index automatically.

Implement Custom Link Types

To implement a custom link type:

  1. Create a MATLAB function file based on the custom link type template, as described inCustom Link Type Functions.

  2. Customize the custom link type file to specify the link type properties and custom callback functions required for the custom link type, as described inLink Type Properties.

  3. Register the custom link type using thermicommand'register'option, as described inCustom Link Type Registration.

Why Create a Custom Link Type?

In addition to linking to built-in types of requirements documents, you can register custom requirements document types with the Requirements Management Interface (RMI). Then you can create requirement links from your model to these types of documents.

With custom link types, you can:

  • Link to requirement items in commercial requirement tracking software

  • Link to in-house database systems

  • Link to document types that the RMI does not support

The custom link type API allows you to define MATLAB functions that enable linking between your Simulink model and your custom requirements document type. These functions also enable new link creation and navigation between the model and documents.

For example, navigation involves opening a requirements document and finding the specific requirement record. When you click your custom link in the content menu of a linked object in the model, Simulink uses your custom link type navigation function to open the document and highlight the target requirement based on the implementation provided. The navigation function you implement uses the available API to communicate with your requirements storage application.

Typically, MATLAB runs an operating system shell command or uses ActiveX®communication for sending navigation requests to external applications.

Alternatively, if your requirements are stored as custom variants of text or HTML files, you can use the built-in editor or Web browser to open the requirements document.

Custom Link Type Functions

To create a MATLAB function file, start with the custom link type template, located in:

matlabroot\toolbox\slrequirements\linktype_examples\linktype_TEMPLATE.m

Your custom link type function:

  • Must exist on the MATLAB path with a unique function and file name.

  • Cannot require input arguments.

  • Must return a single output argument that is an instance of the requirements link type class.

To view similar files for the built-in link types, see the following files inmatlabroot\toolbox\slrequirements\linktype_examples\:

linktype_rmi_doors.m linktype_rmi_excel.m linktype_rmi_html.m linktype_rmi_text.m

Custom Link Type Registration

Register your custom link type by passing the name of the MATLAB function file to thermicommand as follows:

rmi registermytargetfilename

Once you register a link type, it appears in theOutgoing Links Editoras an entry in theDocument typedrop-down list. A file in your preference folder contains the list of registered link types, so the custom link type is loaded each time you run MATLAB.

When you create links using custom link types, the software saves the registration name and the other link properties specified in the function file. When you attempt to navigate to such a link, the RMI resolves the link type against the registered list. If the software cannot find the link type, you see an error message.

You can remove a link type with the following MATLAB command:

rmi unregistermytargetfilename

Custom Link Type Synchronization

After you implement custom link types for RMI that allow you to establish links from Simulink objects to requirements in your requirements management application (RM application), you can implement synchronization of the links between the RM application and Simulink usingRequirements Toolbox™functions. Links can then be reviewed and managed in your RM application environment, while changes made are propagated to Simulink.

You first create the surrogate objects in the RM application to represent Simulink objects of interest. You then automate the process of establishing traceability links between these surrogate objects and other items stored in the RM application, to match links that exist on the Simulink side. After modifying or creating new associations in the RM application, you can propagate the changes back to Simulink. You useRequirements Toolboxto implement synchronization of links for custom requirements documents. However, this functionality is dependent upon the automation and inter-process communication APIs available in your RM application. You use the followingRequirements Toolboxfunctions to implement synchronization of links between RM applications and Simulink.

To get a complete list of Simulink objects that may be considered for inclusion in the surrogate module:

[objHs, parentIdx, isSf, objSIDs] = rmi... ('getObjectsInModel', modelName);

This command returns:

  • objHs, a complete list of numeric handles

  • objSIDs, a complete list of corresponding session-independent Simulink IDs

  • isSf, a logical array that indicates which list positions correspond to which Stateflow®objects

  • parentIdx, an array of indices that provides model hierarchy information

When creating surrogate objects in your RM application, you will need to storeobjSIDsvalues – notobjHsvalues – becauseobjHsvalues are not persistent between Simulink sessions.

To get Simulink object Name and Type information that you store on the RM application side:

[objName, objType] = rmi('getObjLabel', slObjectHandle);

To query links for a Simulink object, specified by either numeric handle or SID:

linkInfo = rmi('getLinks', slObjectHandle) linkInfo = rmi('getLinks', sigBuildertHandle, m) % Signal Builder group "m" use case. linkInfo = rmi('getLinks', [modelName objSIDs{i}]);

linkInfois a MATLAB structure that contains link attributes. See thermifunction reference page for more details.

After you retrieve the updated link information from your RM application, populate the fields oflinkDatawith the updated values, and propagate the changes to Simulink:

rmi('setLinks', slObjectHandle, linkData)

For an example MATLAB script implementing synchronization with a Microsoft Excel Workbook, see the following:

edit([matlabroot '/toolbox/slrequirements/... linktype_examples/slSurrogateInExcel.m'])

You can run this MATLAB script on the example modelslvnvdemo_fuelsys_officereqto generate the Excel®workbook surrogate for the model.