Definition of a parameter in source code

A parameter allows access to a global variable. It can be read or written on a per parameter defined Access restrictions. A parameter needs to be defined globally in a c-file.

Example of a simple parameter of the datatype float. It gives access to the global variable "g_fRatedSpeed". Allow reading by the users VIEWER, USER, and read/write by PROFESSIONAL and DEVELOPER. It can be changed between 0 and 5000.

ParameterF32(
    &g_fRatedSpeed,                        // Pointer to the parameter variable
    PARA_ID_IDM_RatedSpeed,                // ParaID
    GROUP_ID_Drive,                        // GroupID
    // ----------------------------- 
    "n_N",                                 // Name
    "Rated Speed",                         // Description
    // ---- English Help: ---------- 
    "Nominal speed.<br />"
    "The nominal speed of the induction machine given by the machine type plate.",
    // ---- German Help: ----------- 
    "Nenndrehzahl<br />"
    "Dieser Wert entspricht der Nenndrehzahl laut Typenschild der Asynchronmaschine.",
    "{0}rpm",                              // Unit
    // ---- Substitution Texts: ---- 
    "",
    // ----------------------------- 
    1,                                     // Count
    0,                                     // MinValue
    5000,                                  // MaxValue
    0.0,                                   // DefaultValue
    // ----------------------------- 
    ReadFunction_STD_F32,                  // OnReadFunction
    WriteFunction_STD_F32,                 // OnWriteFunction
    SetToDefaultFunction_STD_F32,          // RestoreDefaultFunction
    // ---- Access ----------------- 
    VIEWER_READ | USER_READ | PROFESSIONAL_READ | DEVELOPER_READ | PROFESSIONAL_WRITE | DEVELOPER_WRITE,
    DEFAULT_BACKUP_LOCATION,               // Store Location
    FLAG_NONE                              // Flags
)
 
const ParaData_F32 ParaData_fRatedSpeed = 
{
&g_fRatedSpeed, // Pointer to Parametervariable
0, // Backup
0, // MinValue
5000, // MaxValue
0.0 // DefaultValue
};
 
//-----------------------------
const Parameter PARA_fRatedSpeed __attribute__((section("para_descriptor"))) = 
{
GROUP_ID_Drive, // GroupID
PARA_ID_IDM_RatedSpeed, // ParaID
//-----------------------------
VIEWER_READ | USER_READ | PROFESSIONAL_READ | DEVELOPER_READ | PROFESSIONAL_WRITE | DEVELOPER_WRITE,    // Access
TYPE_float, // DataType
//-----------------------------
"n_N",  // Name
"Rated Speed\
DOC_D Nenndrehzahl<br />\
Dieser Wert entspricht der Nenndrehzahl laut Typenschild der Asynchronmaschine.\
DOC_E Nominal speed.<br />\
The nominal speed of the induction machine given by the machine type plate.",   // Description
"{0}rpm",      // Unit
//-----------------------------
1,  // Count
(void*)&ParaData_fRatedSpeed,   // Data*
//-----------------------------
(ReadFunction*)ReadFunction_STD_F32,    // OnReadFunction
(WriteFunction*)WriteFunction_STD_F32,  // OnWriteFunction
(RestoreDefaultFunction*)SetToDefaultFunction_STD_F32,  // SetToDefaultFunction
//-----------------------------
DEFAULT_BACKUP_LOCATION,    // Store Location
FLAG_NONE, //Flags
"", //Substitution Texts
};

Every parameter consists of two structs:

1. The ParaData structure is type-specific and holds all datatype related fields. For every usable datatype one structure is defined in the library:

   • signed char: ParaData_I8
   • unsigned char: ParaData_U8
   • signed word: ParaData_I16
   • unsigned word: ParaData_U16
   • signed int: ParaData_I32
   • unsigned int: ParaData_U32
   • signed long: ParaData_I64
   • unsigned long: ParaData_U64
   • float: ParaData_F32
   • double: ParaData_F64
   • string: ParaData_STR

   All datastructures contains of the following fields:
   

   • The type of the pointer to the data value must match the datastructure type.
   • The Backup-value is only neccessary for some storage drivers, normally it can be set to 0. See details on page Storage of parameter-values in a non volatile memory.
   • Minimum and maximum values are used by the pc-tool to check the limits of the parameter before writing.
   • The default-value is used to
     1. Reset the value manually if SetToDefault is selected in pc-tool
     2. initialize in case the readout of the non volatile parameter storage fails (see page Storage of parameter-values in a non volatile memory).

2. The Parameter structure contains all metadata describing the parameter.

   • The GroupID refers the parametergroup which has to be defined somewhere in the project. See page Grouping of parameters for details.
   • The Identifier ParaID is defined in the file "PARA_ID_Device.h" to ensure the uniqueness. If two or more parameters with the same identifier exists, the PC-tool will give an error message during connection. Identifier < 1000 are reserved for system-parameters
   • Access restrictions are described on page Access restrictions.
   • DataType must match the type of the data structure described above.
   • Name is shown in the pc-tool in the parameterlist.
   • Description field contains the detailed description and the helptext of the parameter. See page Help-page for a parameter for details.
   • Format is described on page Customized format of parameter values.
   • In case the parameter is an array, the value SubIdCount holds the number of elements of the field. In this case the pointer to the parameter value points to the first element of the array. Parameter Array Name
   • The datastructure described above is referenced with the pointer Data.
   • The three function pointers are described on page User defined onRead and onWrite functions.
   • The StoreLocation is described on page Storage of parameter-values in a non volatile memory.
   • The Flags are described on page Special flags for parameters.
   • SubstitutionalTexts are described on page Substitution of parameter values with texts.

   The Parameter variable must be defined globally with a special attribute to direct this variable to a separated area by the linker. See details on page Neccessary Linker settings and initialization to get the parameter-interface working.

The header-file of the parameter interface library and the definition-file of the identifier have to be included:

#include "lib/PARA_Lib.h"
#include "PARA_ID_Device.h"