Data Dictionary Rules
NOTE: these rules apply to text based data dictionaries. If using the Simulink data dictionary file (.sldd) with Matlab R2015a or later, see Simulink Data Dictionary.
Contents
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, eg. 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 in order to determine data types for the generated code, and for use with development tools. Only the required items are described below.
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 its a map
- Must not end in '_x', '_y' or '_z' if its 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 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. For example, the following are all valid names for a calibration scalar: xyzc_variable_name_units, XYZc_VariableName_units, XYZc_units_VariableName.
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 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.
- Fixed point data types have the following range:
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 1)
- 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 its not a map
- Each entry must not start with mpl ('mpl_', 'mplc_', 'mplk_', 'mplm_', 'mpls_' or '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