GI.config

Functionality

The primary functions of GI.config include:

1. Serving as an abstraction interface between configuration files stored in the filesystem (*.gcf, ...) and the touchable XML-RPC API. To implement this API, refer to the documentation available here: API Quick Start Guide.

2. Facilitating access to a full property structure element, from the entire structure down to a single item, using the same function (e.g., accessing a full variable versus individual variables unit-factor).

3. Simplying the configuration processes through the inclusion of selection variants and limits delivered via the interface.

4. Enforcing all necessary rules and tests for a system-wide valid configuration.

The system consists of different type of objects, which have structured properties.

• Project (can own Controllers and Features)
  • Features (can own Stream Processors)
    • Stream Processor
      • Variable (can own —)
  • Controller (can own Features, Adapters and InternalModules)
    • Features (can own Stream Processors)
      • Stream Processor (can own Variables)
        • Variable (can own —)
    • InternalModule (can own Variables)
      • Variable (can own —)
    • Adapter (can own Modules)
      • Module (can own Variables)
        • Variable (can own —)

👉 Key points for understanding the object structure in GI.config:

• In GI.config based on PC, the highest level in the hierarchy is the "Project" Object, while the lowest level is the "Variable" Object.
• In GI.config based on Q.station, the highest level is the "Controller" Object, and the lowest level remains the "Variable" Object.
• Depending on the use case, the availability of each object can change (e.g., GI.config running in a controller may only have objects up to "Controller").
• Each object can and must be connected together according to coded functionality.
• An owner object can possess sub-objects of different types and organizes them using different lists.
• If an index is needed, its position within this list is considered (the index no longer holds essential meaning except for sorting or displaying purposes).
• For identification, each object has a unique ID (UUID), generated by a UUID generator from the POCO library. These IDs connect the objects together and are stored in configuration files to prevent loss.

As previously stated, GI.config contains dependencies in a tree structure among its objects. All child objects are associated with a parent object. To begin identifying object IDs within GI.config, you can use the GetIDsFromObjectType method.

To understand the structure in GI.config, you need to retrieve information about "Owned" objects. For instance, you can obtain all "Adapters" owned by a "Controller," or all "Variables" owned by a "Module." This information can be obtained as a property of these objects using the GetConfigs method. The specific property name required depends on the object type.

Some examples:

• “Controller” object:
  • get owned adapter IDs with → General/OwnedIDsAdapter
  • get owned feature IDs with → General/OwnedIDsFeature
  • get owned internal module IDs with → General/OwnedIDsInternalModule
• “Module” object
  • get owned variables IDs → General/OwnedIDsVariable

It is also possible to get the information about the “Owner” ID of an object using General/OwnerID.

The “Design Rule Check” (short: DRC) is a main functionality of GI.config, which takes care of a correct over-all configuration of a Project. At each configuration step (SetConfig, CreateObject,…), it takes care of:

• Valid configurations of each object and relations between objects.
• Defaulting parameter values “forced” (e.g. if an object is newly created) or “on error” (e.g. if one parameter is changed and therefore another one is not longer existing) but NOT creating needed or deleting not longer needed objects !!!
• Refreshing elements (e.g. selection possibilities of combo boxes, limits of values, hint generation, setting options, …)
• Doing all kind of checks
• Notification handling for clients (added, removed, changed and defaulted notifications of objects and their parameters)

All objects that are touched or modified during the setting or modification process are stored in a central list. At the end of each function call that influences these objects (based on the "DisableDRC" parameter), this list undergoes DRC handling. Subsequently, the list is cleared to enable monitoring of subsequent events.

As a result of DRC handling, the API returns lists of changes (based on the "ReturnConfigChangesReasonBitset" parameter) and states (such as Info, Warnings, Errors, etc.) related to the causing object (ID).

• DisableDRC: Disableing the DRC is not recommended in “standard” use. In special cases it could make sense for speeding up configuration (e.g. if n-variable names should be changed once, DisableDRC n-1 times and !DisableDRC with last change - this is a MUST !!!)
• ReturnConfigChangesReasonBitset: This bitset defines which information is generated once by this actual DRC within the ReturnLists in the API Base Result. See also GIns_Enum_NotifyReason

Some global settings for the behaviour of GI.config can be done via the “Settings” Method of the ConfigAPI. Pay attention, that all accessing clients can change this settings (also GI.bench does so) and therefore modifying the behaviour of it. Settings are stored as long as GI.config is running or one other client changes something ….

PLEASE DON'T MODIFY ANYTHING HERE, if you are not 100% sure what the consequences are. Default values are best case for most situations.

• AutomaticDRCAtAPIFunctionsHandlesChangedMarkedObjectsOnly: (default: false)
  • true: only changed objects will be handled
  • false: all objects will be handled
• ChooseCombinedHandlingForMultipleParameteredElements: (default: false)
  • true: multiple parametered elements are handled within one combined element
  • false: multiple parametered elements are handled in as much elements as parameters count
• ClearTraceOnce: (default: false)
  • true: clear trace once, if it is enabled
  • false: don't touch trace
• DisableErrorWithEmptyStreamProcessors: (default: false)
  • true: no error is shown, if a stream processor is empty
  • false: show error
• FeatureSelector: (default: “”)
  • “SuperUser”: enable some SuperUser features
  • “Default”: reset all FeatureSelector options to default
• GenerateItemInListIfEmptyForXMLInterface: (default: false)
  • true: generate a list item, if no one is present - for better use with GI.monitor
  • false: leave it empty
• GenerateOptionChangedNotifications: (default: true)
  • true: changed notifications are also generated, if options of an element are changing
  • false: don't do
• IgnoreWritingThisValuesForTest: (default: false)
  • true: disable changing this values
  • false: enable
• MarkObjectChangedInsteadOfEachParameterChangedCountPercentage: (default: 10.0)
  • Percentage of changed parameters of an object, where not each parameter is marked as changed, but full object will be.
• TraceOutput: (default: Off)
  • Off: no trace
  • Console: trace to console (slow)
  • Console and file: trace to console and file in Log-directory (very slow)
• TryLoadAlsoLegacyFilesAtRead: (default: false)
  • true: try load legacy files
  • false: don't do

For proper configuration, it is necessary to make a call to the function CallAssistant after adding or deleting objects.

CallAssistant:

• ID: Highest object ID (usually the ID of the project object)
• Parameters: empty
• Type: TuneSubObjects

To test the GI.config XML-RPC API (using your own client or GI.monitor), you must connect to an XML-RPC server, such as Q.station or GI.bench. The first step in working with GI.config is to create some "objects" like Project, Controller, Adapter, Modules, and Variables. You can either load an existing system (Q.station + modules) into your GI.config, or if you don't have a device available, you can use GI.bench and load the example projects provided with the GI.bench setup.

For detailed instructions on common procedures, please refer to the “How To...” section, which offers step-by-step guidance.

All methods responding with at least these result elements.

ReturnState

To ensure accurate decoding and identification of structs, each XmlRpcValue struct provides a StructTypeID() method.

For instance, consider the "Config" element in the "Type_Base_ConfigWithOwner": use the StructTypeID() method of the value itself and compare it with predefined struct IDs.

For example:

giconfig_ConfigAPI::CType_Base_ConfigWithOwner result;
Results.Get_Configs(0, result);  //Results is of type giconfig_ConfigAPI::GetConfigs::CResults
 
if (result.Get_Config().getStructTypeID().compare(giconfig_ConfigAPI::CType_Config_Variable::StructTypeID()) == 0)
{
     giconfig_ConfigAPI::CType_Config_Variable Variable;
     result.Get_Config(Variable);
 
     if (value.Get_AnalogInput() != GInsXmlRpc::XmlRpcValue())  //check if valid
     {
	   std::cout << "   -----> Analog Input found! " << std::endl;
     }
}

Types

The structure of GI.config Type-Names conforms to the properties and information they contain. For example a type of

Type_Config_<ObjectType>

can contains ALL configuration information of a certain “ObjectType”.

Because one ObjectType can encompass numerous properties and information, the types themselves may contain struct-elements to consolidate related information. For instance, in the case of a Variable-Object:

Type_Config_Variable_General
Type_Config_Variable_AnalogInput
Type_Config_Variable_AnalogOutput
Type_Config_Variable_DigitalInput
...

and again sub structs like:

Type_Config_Variable_General_Average
Type_Config_Variable_General_Oversampling
Type_Config_Variable_General_ValueHandling
...

Single properties of a GI.config Type struct are “GInsXmlRpcStdAPI Types”.

Type_Base_ObjectRef (1.0)

Type_Edit_MultipleParametersCombinedAndSplit (1.200)

Internal type:

class CType_Edit_CANConfig : public GInsXmlRpc::XmlRpcValue 

Type_Edit_CANConfigList (1.223)

Type_Config_Variable_General_ValueHandlingSG_Linearisation (1.303)

class CType_Config_Variable_General_ValueHandlingSG_Scaling_CalculatorTwoPointOneByOne : public GInsXmlRpc::XmlRpcValue 

Type_Config_Variable_General_ValueHandlingSG_Scaling (1.308)

Internal type:

class CType_Config_Variable_General_ValueHandlingSG_Source : public GInsXmlRpc::XmlRpcValue 

Type_Config_Variable_General_ValueHandlingSG_ErrorHandling (1.311)

Internal type:

• Internal type:

  class CType_Config_Variable_General_ValueHandlingSG_ThresholdSG : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_ValueHandlingSG_Threshold : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_ValueHandlingSG : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_ValueHandling : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_Oversampling : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_AdjustmentSG : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_Adjustment : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General_Formula : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_AnalogInput : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_AnalogOutput : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_DigitalInput : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_DigitalOutput : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Remote_SSI : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Remote_Modbus : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Remote_CAN : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Remote_SDI12 : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Remote_Logger : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Remote : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_SetPoint : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Alarm : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Arithmetic : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable_Reference : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Variable : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_InternalModule_General_Additional_Hardware : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_InternalModule_General_Additional : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_InternalModule_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_InternalModule : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_General_Additional_Hardware : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_General_Additional : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_General_Special : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_Adapter_RealtimeRS485 : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_Adapter_File : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module_Adapter : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Module : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer_Base : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer_Process : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer_PostProcess : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer_System : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer_Miscellaneous : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer_Merger : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataBuffer : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Base : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_Trigger : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_SendFTPClient : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_SendMailClient : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_EventBased : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_Triggered : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_Storage_FileFormatSettingsCSV : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values_Storage : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger_Values : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor_DataLogger : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_StreamProcessor : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Feature_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Feature : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Adapter_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Adapter_SlaveRS485 : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Adapter_SlaveRealtimeRS485 : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Adapter_SlaveRealtimeCAN : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Adapter_SlaveFile : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Adapter : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional_Software : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional_LifeSignalSG : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional_LifeSignal : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional_BufferPreInit : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional_Watchdog : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional_UDBFCompatibility : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_Additional : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General_LocationDetails : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Synchronization : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Dataport : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Network_Ethernet : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Network_WLAN : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Network_Client_IoT : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Network_Client : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Network : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Fieldbus : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_FTP_Client_Connection : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_FTP_Server : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_FTP_Client : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_FTP : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Mail_Client : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_Mail : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_NTP_Client : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_NTP : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_NetDrive_Drive : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_NetDrive : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_USBDevice_Device : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_USBDevice : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_SerialDevice_RSDeviceConfigbus : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_SerialDevice_RSDevice : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_SerialDevice_SDI12Device : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter_SerialDevice : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Adapter : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Function_FFT_Processor_Evaluator : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Function_FFT_Processor : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Function_FFT : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller_Function : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Controller : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Project_General : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Project_Synchronization : public GInsXmlRpc::XmlRpcValue 

• Internal type:

  class CType_Config_Project : public GInsXmlRpc::XmlRpcValue