< OpenECU Support

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

  1. Data Dictionary Rules
    1. File and Directory Structure
    2. Naming Rules
    3. DD Entry Properties
    4. Example
    5. More Information

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

More Information

Copyright © 2022 OpenECU, All rights reserved