A text file based data dictionary file is a simple tab delimited text file format and must contain at minimum: the name, default value and type for calibratables and the name and type only for displayables. When a model is loaded, the data dictionary files are read into MATLAB's workspace to support simulation or building. Optionally, these can be used to generate ASAP2 files at build time. See Section 4.3.4, “Configuration options” for details.

Note that non-ASCII characters appearing in the data dictionary may not be interpreted correctly by the calibration tool reading the resultant ASAP2 files, since different calibration tools use different extended encoding conventions. It is best therefore to stick to ASCII characters within the data dictionary.

Each data dictionary file is stored in a directory of the same name. Given the example of the model read_sensor above, then there would be two directories named min and mot:

Each data dictionary file stored in each of those directories must be named data dictionary name_dd.txt. Given the example of the model read_sensor above, then there would be two files named min_dd.txt and mot_dd.txt in the corresponding directories:

Each data dictionary follows a simple format, separated into columns and will look something like:

Name            Value  Units  Type    Accuracy  Min  Max  Description
moi_pressure           kPa    real_T  0.01      20   80   Pressure reading
moi_temperature        degC   real_T  0.01      -40  150  Temperature reading

To help readability, comment lines can be inserted into a data dictionary file. Comment lines are ignored and start with either a ** or the -- character sequence. For example:

Name            Value  Units  Type    Accuracy  Min  Max  Description
** A comment line
moi_pressure           kPa    real_T  0.01      20   80   Pressure reading

-- Another comment line
moi_temperature        degC   real_T  0.01      -40  150  Temperature reading

Each column has a heading, followed by as many data dictionary entries as necessary. Each column is separated by a TAB character and because of this, Excel is a very useful tool for editing the files (in Excel, save the file as Text (tab delimited) *.txt).

Each column has a use:

An example of how the data dictionary can be used to name model signals, model constants and map look-ups is given below. Each entry follows the naming convention laid out in (Section 8.2.5, “Naming rules”). Explore the OpenECU demos for more examples (Section 3.2, “Installed examples”).

Name           Value               Units  Type    Min Max  Description

** Example of a signal DDE
moi_pressure                       kPa    real_T  20  80   Example of a named signal

** Example of a constant look-up DDE
moic_constant  50                  kPa    real_T  20  80   Example of a calibration constant

** Example of set of a 1D table/map look-up DDEs
moim_1d_map_x  [20 40 80]          kPa    real_T  20  80   Example of a x-axis for a 1d map
moim_1d_map_z  [0  0  1]           state  bool    0   1    Example of a z-data for a 1d map

** Example of set of a 2D table/map look-up DDEs
moim_2d_map_x  [20 40]             kPa    real_T  20  80   Example of a x-axis for a 2d map
moim_2d_map_y  [1  5  10]          sec    real_T  0   25   Example of a y-axis for a 2d map
moim_2d_map_z  [0  1; 4  5; 8  9]  steps  real_T  0   100  Example of a z-data for a 2d map

** Example of set of an array DDE
moiv           [1 2 3 5 8 13]      counts real_T  0   100  Example of an array

Instead of using values to represent discrete states, enumerations can be used instead. These represent the discrete states using a textual name rather than a number. For instance, in the following example, moi_state can have two enumerations: MOI_RUNNING which represents the value 0 and MOI_STOPPED which represents the value 1. It is easier to understand and interpret the enumerations than the values.

Name         Value  Units  Type    Min  Max  Enums                     Description

moi_state           state  real_T  0    1    MOI_RUNNING, MOI_STOPPED  Example of a st ...

MOI_RUNNING  0      enum   real_T                                      Enumeration for ...
MOI_STOPPED  1      enum   real_T                                      Enumeration for ...

When a model is loaded, each data dictionary entry is checked for errors. A complete list of checks is given in Appendix 8, Data dictionary tool errors. If any errors or warnings are displayed, go back and edit the file to remove the errors.

In R2015a and later, a Simulink based data dictionary file with an extension of .sldd can be used with OpenECU. This type of data dictionary holds the same information as a text based data dictionary, only the data is stored in oe.Parameter and oe.Signal objects in the data dictionary file from within Simulink, instead of externally in text files. This file can be edited manually from within Simulink using the Model Explorer interface, or programmatically in Simulink using the Simulink.data.dictionary class and API.

The data dictionary file is specified in the Model Properties dialog box of the model File-> Model Properties-> Model Properties under the Data tab, as shown in the image below.

The data dictionary file can be viewed or edited by clicking the icon in the bottom left hand corner of the model once it has been configured to use a data dictionary, as shown below.

The data dictionary file is then edited in Model Explorer Tools-> Model Explorer, as shown below.

To add a new oe.Parameter or oe.Signal object to the data dictionary select Add-> Add Custom... from the Model Explorer menu, and in the dialog box, specify the name of the variable and the class of the variable (either oe.Parameter or oe.Signal), as shown below.

OpenECU uses the following properties for each signal object:

With a Simulink data dictionary, in order to make each variable available in a calibration tool, the variable must have certain properties set in order to control the storage of that variable. The properties must be set differently depending on the auto-coder used (see Section 4.3.2, “Auto-coders” for more details about auto-coders), and the desired type and scope of the variable.

The following table details the desired variable type in the model or calibration tool, and the data object and properties required for each auto-coder which must be set to generate that variable in the model and make available in the calibration tool:

A model configured to use a text based data dictionary can be automatically converted to use a Simulink data dictionary with all of the existing data dictionary entries imported into the .sldd file by calling the following command:

oe_config_using_sim_dd

at MATLAB's command prompt.

By default, the script will convert the currently active model, using the data dictionary file name model-name.sldd. If the data dictionary file already exists it can be overwritten with additional parameters. See details at oe_config_using_sim_dd.

In addition to the previously mentioned data dictionary variables, additional data can also be stored in a Simulink data dictionary file, such as Simulink.Bus objects, Simulink enum type definitions, Configuration Sets, and other built-in Simulink types. Please refer to the Simulink documentation for further details on the data that can be stored in a Simulink data dictionary file.