.. _data_dictionary_rules:

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.

.. contents::
   :local:
   :depth: 2

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.

.. list-table::
   :header-rows: 1

   * - 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.

.. list-table::
   :header-rows: 1

   * - 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
-------

.. code-block:: none

   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