How To Create Data Dictionary In Matlab

Once again I wish to welcome guest blogger Donn Shull. Donn has previously written a series of articles on Matlab's previous-generation class-object system (UDD). Today Donn explores a little-known yet quite useful aspect of Simulink.

Introduction

In 2014, MathWorks introduced the Simulink Data Dictionary. This new feature provides the ability to store Data Types, Parameters, and Signals in database files. This is great news for embedded systems developers who want the flexibility of using data objects and want to avoid using the base workspace with its potential for data corruption.
In its initial implementation, the data dictionary interface is provided by the Simulink Model Explorer. The GUI interface is clean, intuitive, and easy to use. This interface supports importing and exporting dictionaries to m files and mat files.
Unfortunately, in production code generation environments there is frequently a need to interface this data with external tools such as software specification systems, documentation generators, and calibration tools. MathWorks have not published an API for accessing dictionaries from code, indicating that it may possibly be available in a future release. Today, we will look at some portions of the undocumented API for Simulink Data Dictionaries.

Simulink F14 model using data dictionary

Some background information

Simulink Data Dictionaries exist as files having a standard file extension of .sldd. Dictionary files can be opened with the open function, which in turn calls opensldd . This opens the file and launches the Simulink Model Explorer with the selected dictionary node. When a dictionary is opened, a cached copy is created. While working with a dictionary, changes are made to the cached copy. The dictionary file is only changed when the changes are saved by issuing the relevant command. Until the cached copy is saved, it is possible to view differences between the file and the cached copy, and revert any unwanted changes. The file maintains the date, time, and author of the last saved change, but no information about previous revisions.
From the Model Explorer it is possible to add items to a dictionary from a model, the base workspace, or by creating new items. We can associate a Simulink model with a dictionary by using the model properties dropdown in the Simulink editor.
Using data dictionaries it is possible to tailor a model's code generation for different targets, simply by changing the dictionary that is being used.

The Simulink Data Dictionary API

Programmatic access to Simulink Data Dictionaries is provided by the undocumented MCOS package Simulink.dd. We will look at two package functions and a few methods of the Simulink.dd.Connection class. These provide the basic ability to work with dictionaries from within our m code.

Creating and Opening Dictionary Files

Dictionary files are created with the package function create:

hDict = Simulink.dd.create              (dictionaryFileName);

hDict = Simulink.dd.create(dictionaryFileName);

Existing dictionary files are opened using the package function open:

hDict = Simulink.dd.open              (dictionaryFileName);

hDict = Simulink.dd.open(dictionaryFileName);

In both cases the functions return a handle of type Simulink.dd.Connection to the named dictionary file.

Modifying a Dictionary

We can use methods of the Simulink.dd.Connection instance to modify an open dictionary. Dictionaries are organized into two sections: The Configurations section contains Simulink.ConfigSet entries, while Parameter, Signal, and DataType items are placed in the Global section. We can get a list of the items in a section using the getChildNames method:

childNamesList = hDict.getChildNames              (sectionName);

childNamesList = hDict.getChildNames(sectionName);

Adding and removing items from a section are done using the insertEntry and deleteEntry methods, respectively:

hDict.insertEntry              (sectionName, entryName, object)              hDict.deleteEntry              (sectionName, entryName)

hDict.insertEntry(sectionName, entryName, object) hDict.deleteEntry(sectionName, entryName)

Modifying an existing entry is done using the getEntry, and setEntry methods:

workingCopy = hDict.getEntry              (sectionName.entryName              )              % modify workingCopy              hDict.setEntry              (sectionName.entryName, workingCopy)

workingCopy = hDict.getEntry(sectionName.entryName) % modify workingCopy hDict.setEntry(sectionName.entryName, workingCopy)

A collection of objects from the base workspace can be added to a dictionary using the importFromBaseWorkspace method:

hDict.importFromBaseWorkspace              (sectionName, overwriteExisitngObjectsFlag, deleteFromBaseWorkspaceFlag, cellArrayOfNames)

hDict.importFromBaseWorkspace(sectionName, overwriteExisitngObjectsFlag, deleteFromBaseWorkspaceFlag, cellArrayOfNames)

Additional dictionary manipulations are possible using the evalin and assignin methods:

hDict.evalin              (commandString)              hDict.assignin              (variableName, variable)

hDict.evalin(commandString) hDict.assignin(variableName, variable)

Closing a Dictionary

Finalizing a dictionary session is done with the saveChanges, close, and delete methods:

hDict.saveChanges              hDict.close              hDict.delete

hDict.saveChanges hDict.close hDict.delete

Example: Migrate Single Model to Use Dictionary

This example is an adaptation of MathWorks' interactive example of the same title, using programmatic Matlab commands rather than GUI interactions.

Start by using load_system to open the f14 model. This opens the model and executes the PreLoadFcn callback, which loads design data into the base workspace, without opening the Simulink block diagram editor:

Use the Simulink package function findVars to find the variables used by the model:

usedVariables = Simulink.findVars                  (                  'f14'                  );

usedVariables = Simulink.findVars('f14');

Next, use the create package function to create and open a new Simulink Data Dictionary:

hDict = Simulink.dd.create                  (                  'f14_data_dictionary.sldd'                  );

hDict = Simulink.dd.create('f14_data_dictionary.sldd');

Attach the newly created dictionary to the model:

set_param(                  'f14',                  'DataDictionary',                  'f14_data_dictionary.sldd'                  );

set_param('f14', 'DataDictionary', 'f14_data_dictionary.sldd');

Use one of the API methods to add these variables to the Data Dictionary:

overWrite = true; deleteFromWorkspace = false;                  for                  n =                  1:numel(usedVariables)                  if                  strcmp                  (usedVariables(n).Source,                  'base workspace'                  )                  hDict.importFromBaseWorkspace                  (overWrite, deleteFromWorkspace,                  {usedVariables(n).Name                  }                  );                  end                  end

overWrite = true; deleteFromWorkspace = false; for n = 1:numel(usedVariables) if strcmp(usedVariables(n).Source, 'base workspace') hDict.importFromBaseWorkspace(overWrite, deleteFromWorkspace, {usedVariables(n).Name}); end end

Save the changes made to the dictionary:

Clean up and we are done:

hDict.close; hDict.delete;                  clear                  hDict;

hDict.close; hDict.delete; clear hDict;

Final notes

MathWorks have recognized the value of data dictionaries for a long time. In 2006, MathWorker Tom Erkkinen published a paper about multitarget modeling using data dictionaries. The Simulink.dd package was added to Matlab in R2011b, and the DataDictionary parameter was added to Simulink models in R2012a. MathWorks have also indicated that a user API for Simulink Data Dictionaries may be in the works. Until it is released we can make do with the undocumented API.
Update March 7, 2015 : Matlab release R2015a now includes a fully documented Simulink.data.Dictionary class, which works in a very similar manner. Users of R2015a or newer should use this new Simulink.data.Dictionary class, while users of previous Matlab releases can use the Simulink.dd class presented in this article.
Have you made some good use of this data-dictionary functionality in your project? If so, please share your experience in a comment below.