== 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 [[doc_user/openecu_user_guide_simulink_chunk/creatinganewmodel.html#dd_simulink_based|Simulink Data Dictionary]]. <> ---- === 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 [[doc_user/openecu_user_guide_simulink_chunk/naming_rules_prefix_style.html|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 [[doc_user/openecu_user_guide_simulink_chunk/naming_rules_prefix_style.html|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 === * [[doc_user/openecu_user_guide_simulink_chunk/creatinganewmodel.html#datadictionary|Creating an OpenECU Model]] * [[doc_user/openecu_user_guide_simulink_chunk/put_calmap1d.html|1-D Calibration Map]] * [[doc_user/openecu_user_guide_simulink_chunk/put_calmap2d.html|2-D Calibration Map]] * [[doc_user/openecu_user_guide_simulink_chunk/naming_rules_prefix_style.html|Naming Rules]] * [[doc_user/openecu_user_guide_simulink_chunk/dde_errors.html|Data Dictionary Errors]]