Data Dictionary Rules

Note

These rules apply to text-based data dictionaries. Text based data dictionaries are generally used with C-API applications. If you are using the Simulink API, then consider using Simulink data dictionary file (.sldd) instead.

File and Directory Structure 

Each data dictionary must be located in a 3-letter folder name under the root model location.
The file name must match the folder name, with _dd appended, e.g., XYZ_dd.txt
Each data dictionary file is a tab-delimited text file.
A data dictionary contains the following columns for each entry: Name, Value, Units, Description, Type, Accuracy, Min, Max, Enums (optional), Scale, Offset.

Naming Rules 

OpenECU uses a naming convention for data dictionary entries.

Rules for DD Names 

Must be > 3 characters
Must be < max length (31)
Must not start with a digit or an _ character
Must contain only the characters ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’, or ‘_’
Must end in _x, _y or _z if it’s a map
Must not end in _x, _y or _z if it’s not a map
Must not use mpl for the prefix (mpl_, mplc_, mplk_, mplm_, mpls_ or mplv; these are reserved for internal OpenECU variables).

Prefix 

The Naming Rules section of the user guide describe some recommended conventions. Most of these are optional; the only required convention is that the 4th character of the name indicates the data type.

Character	Data Type	Description
blank	Displayable signal (exported global)	Global variable that can be read with a calibration tool
k	constant scalar	Constant value, cannot be changed with a calibration tool
c	calibration scalar	Can be changed with a calibration tool
m	calibration map	1D or 2D map that can be changed with a calibration tool
v	array	Can be read with a calibration tool

Suffix 

For maps or lookup tables, the last character indicates which axis the data belongs to.

1D Tables must have _x and _z entries.
Each z must have a corresponding x.
z must be formed as a matrix of size 1 by x.
2D Tables must have _x, _y, and _z entries.
Each z must have a corresponding x and y.
z must be a matrix of size x by y.

DD Entry Properties 

Values 

Must be non-empty if a calibration or string
Must contain valid numbers or characters (depending on type)
Must be bracketed if the calibration is a map
Must have rows of equal length if the calibration is a map
Must have rows at least 2 entries long if the calibration is a map
Must have only 1 row of data if the calibration is for the x-axis or y-axis if the calibration is a map
Must have only 1 row of data if the calibration is a vector (array)

Note

Value will be set to zero if not specified, so MATLAB workspace will have a value.

Description 

Must be less than 256 characters long
Must not use “ or ‘ characters

Type 

This is a required field; it must always be specified.
Must be one of: int8_T, uint8_T, int16_T, uint16_T, int32_T, uint32_T, real_T or bool.
Must be real_T if the calibration is x-axis, y-axis or z-axis data.

Type	Min	Max
bool	0	1
int8_T	-128	127
uint8_T	0	255
int16_T	-32768	32767
uint16_T	0	65535
int32_T	-2147483648	2147483647
uint32_T	0	4294967295

Min / Max 

Must both be present or both missing (cannot specify only one)
Must be a valid number
If Type is boolean, Min must be 0 and Max must be 1.
Min must be < Max

Enums (Enumerations)

Must be a list of names, separated by ‘,’
Each entry must be > 3 characters
Each entry must be < max length
Each entry must not start with a digit or an ‘_’ character
Each entry must contain only the characters ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’ or ‘_’
Each entry must not end in ‘_x’, ‘_y’ or ‘_z’ if it’s not a map
Each entry must not start with mpl (mpl_, mplc_, mplk_, mplm_, mpls_, mplv; these are reserved for internal OpenECU variables).

Example 

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