CSV File for Third-party OPC Devices

Before you can import OPC items data, you must manually edit the configuration data in a CSV file (a textual file containing comma separated values).

OPC Devices CSV File Template

A CSV file template (OPC_ConfigurationData_Ver1_1.csv) is available at the following path: GmsMainProject\profiles\OPCDataTemplate. This template can be used to create your OPC configuration file.

 

OPC CSV File Sections

Section

Description

[HEADER]

Includes the following separators:

  • List Separator “,”: Used as a delimiter for parsing row data in the CSV file.
  • Decimal Separator “.”: Used for parsing fields that contain values like floating-point numbers, such as Min, Max, Scaling Factor (MinRaw, MaxRaw, MinEng, MaxEng), and Alarms.

In the file, for easy identification, separators are within double quotes (“ ”) on subsequent lines.

[FILEVERSION]

Indicates the version of the CSV file. It corresponds to Desigo CC software version.

[LIBRARY]

Indicates the name of the object model library to be used to create the OPC items included in this configuration file.

NOTE: This tag is mandatory. If this tag is left empty or the library does not exist, an error displays.

[STATE_TEXTS]

Includes the following data:

  • Table Name: Name of the text groups.
  • Index: Number that represents the different states of a text groups.
  • Text: Description associated with the different text groups states.

NOTE: State texts are applicable only for Multistate and Binary points (floating point values do not have integral states). However, if a CSV file contains StateText for points with float/double data type, the state text for that point is skipped during the import.

[SERVERS]

Includes servers data (see OPC Servers Data, below).

[GROUPS]

Includes groups data (see OPC Groups Data, below).

[ITEMS]

Includes items data (see OPC Items Data, below).

OPC Servers Data

This [SERVERS] section is composed as follows:

# Servers Data: [Name] [Description] [ProgId] [Alias] [Function Name] [Discipline ID] [Subdiscipline ID] [Type ID] [Subtype ID]

For example:

Server_Matrikon; Server OPC;Matrikon.OPC.Simulation.1;0;1;200;201

Data

Use

Description

[Name]

Mandatory

Name of the third-party OPC server node as it will appear in System Browser.
NOTE: Do not use the dollar sign ($) in the name of the server. This is a special character already in use in the definition of the peripheral address.

[Description]

Mandatory

Description of the third-party OPC server node as it will appear in System Browser (in brackets next to the name).

[ProgId]

Mandatory

Program identification for the registry of the OPC server.

[Alias]

Optional

Alias assigned to the OPC server.

[Function Name]

Optional

Name of the function associated with the OPC server.

[Discipline ID]

Optional

Identifier of the discipline associated with the OPC server.

[Subdiscipline ID]

Optional

Identifier of the subdiscipline associated with the OPC server.

[Type ID]

Optional

Identifier of the type associated with the OPC server.

[Subtype ID]

Optional

Identifier of the sub type associated with the OPC server.

OPC Groups Data

The [GROUPS] section is composed as follows:

# Groups Data: [Parent Server Name] [Name] [Description] [Alias] [Function Name] [Discipline ID] [Subdiscipline ID] [Type ID] [Subtype ID]

For example:

Server_Matrikon;Group_1;Group_1;0;1;200;201

Data

Use

Description

[Parent Server Name]

Mandatory

Name of the parent OPC server for the OPC group.

[Name]

Mandatory

Name of the OPC group node as it will appear in System Browser.

NOTE: Do not use the dollar sign ($) in the name of the group. This is a special character already in use in the definition of the peripheral address.

[Description]

Mandatory

Description of the OPC group node as it will appear in System Browser (in brackets next to the name).

[Alias]

Optional

Alias assigned to the OPC group.

[Function Name]

Optional

Name of the function associated with the OPC group.

[Discipline ID]

Optional

Identifier of the discipline associated with the OPC group.

[Subdiscipline ID]

Optional

Identifier of the subdiscipline associated with the OPC group.

[Type ID]

Optional

Identifier of the type associated with the OPC group.

[Subtype ID]

Optional

Identifier of the sub type associated with the OPC group.

OPC Items Data

The [ITEMS] section is composed as follows:

# Items Data: [Parent Group Name] [Name] [Description] [Item Address] [Data Type] [Direction (Access Level)] [Object Model] [Object Model Property] [Alias] [Function Name] [Discipline ID] [Subdiscipline ID] [Type ID] [Subtype ID] [Min] [Max] [MinRaw] [MaxRaw] [MinEng] [MaxEng] [Resolution] [Eng Unit] [StateText] [Alarm Class] [Alarm Type] [Alarm Value] [Event Text] [Normal Text] [Upper Hysteresis] [Lower Hysteresis] [NoAlarmOn] [Logical Hierarchy] [User Hierarchy]

For example:

Group1;IntInput1;Int Input1;Group1.Int1 VT_I4;IO;IntegerInput1;0;1;200;201;0;100;5;60;10;100;Alarm;EQ;50;Event Text;NormalText; \Bldg1\Flr1\R1\;\MyUser1\Room1\

Data

Use

Description

[Parent Group Name]

Mandatory

Name of the parent OPC group for the OPC item.

[Name]

Mandatory

Name of the OPC item point as it will appear in System Browser.

[Description]

Mandatory

Description of the OPC item point as it will appear in System Browser (in brackets next to the name).

[Item Address]

Mandatory

Name of the tag that is used in the peripheral address.

NOTE: The peripheral address consists in the following entries and "$" is used as a separator among servers name, groups name, and items name.
The individual entries of the address can be only 100 characters in length each.

[Data Type]

Mandatory

See OPC Items Data Types.

[Direction (Access Level)]

Mandatory

Whether an OPC item is Input, Output, or Input/Output (see OPC Items Direction).

[Object Model]

Optional

Name of the object model of the OPC item point to create.

NOTE: This field can be used only after an object model is imported. The entry is rejected if it is invalid; anyway the field can be left empty.

[Object ModelProperty]

Optional

If the [Object Model] field is specified in the file, it specifies the name of the object model property associated with the OPC item.

[Alias]

Optional

Alias assigned to the OPC item.

[Function Name]

Optional

Name of the function associated with the OPC item.

[Discipline ID]

Optional

Identifier of the discipline associated with the OPC item.

[Subdiscipline ID]

Optional

Identifier of the subdiscipline associated with the OPC item.

[Type ID]

Optional

Identifier of the type associated with the OPC item.

[Subtype ID]

Optional

Identifier of the sub type associated with the OPC item.

[Min]

Optional

Minimum value of a point (if applicable).

[Max]

Optional

Maximum value of a point (if applicable).

[MinRaw]

Optional

Lower end of the raw value scale.

[MaxRaw]

Optional

Upper end of the raw value scale.

[MinEng]

Optional

Lower end of an engineering value scale.

[MaxEng]

Optional

Upper end of an engineering value scale.

[Resolution]

Optional

For real numbers (float), number of digits to display after the decimal separator (comma).

[EngUnit]

Optional

Text that indicates the Engineering unit.

[StateText]

Optional

Name of the text group to use to represent the value of an OPC item.

NOTE: State texts can be associated only with GmsEnum and GmsBool properties.

[Alarm Class]

Optional

Alarm class to be enabled for an event (for example, Alarm, Anomaly, Blocked$Fault, …).
Use the dollar sign ($) to separate multiple alarms or alarm classes.
Syntax:
<AlarmClass1>$<AlarmClass2>$ <AlarmClass3>…

Example: Alarm$Fault$Anomaly

[Alarm Type]

Optional

Condition for issuing an alarm (see Alarms Configuration for OPC).

Syntax:
<AlarmType1>$<AlarmType2>$ <AlarmType3>…

NOTE: If this is not present, the point will be imported with no alarms configuration.

[Alarm Value]

Optional

Value or (range of values) for which an alarm will be issued. The range is indicated by the dollar sign ($).

For example, if the Alarm Value is 40$50, this means an alarm value range between 40-50.

Syntax:
<AlarmValue1>$<AlarmValue2>$ <AlarmValue3>…

The syntax of Between (BET) and Not Between (NBET) operators is: [Value1$Value2].
For multiple alarms that contain both Equals and Range alarms, the syntax should be: “10$[40$50]”.

NOTE: If the [StateText] field is defined, the [AlarmValue] field will use it. If this field is not present, the point will be imported without alarming.

[Event Text]

Optional

Text to display for off normal conditions (incoming events).

For multiple alarms, multiple off normal condition texts can be defined.

Syntax:
<EventText1>$<EventText2>$ <EventText3>…

Examples: "Error", "Error$Warning", "Error$Warning$DangerLevel” …

[Normal Text]

Optional

Text to display for normal conditions (outgoing events).

For multiple alarms, multiple normal condition texts can be defined.

Syntax: [NormalText]=<NormalText1>$<NormalText2>$ <NormalText3>…

Examples: “Normal”, “OK$Normal”, “Normal$OK$Normal” …

[Upper Hysteresis]

Optional

Upper range for the alarm value beyond which an alarm will be generated.

For example, if the alarm value is greater than 50 and the Upper Hysteresis is 2, then the alarm will be generated only when the alarm value reaches 52.

[Lower Hysteresis]

Optional

Lower range for the alarm value below which alarms will be generated.

This value is always specified in negative.
For example, if the alarm value is less than 50 and the Lower Hysteresis is -2, then the alarm will be generated only when the alarm value is less than 48.

NoAlarmOn

Optional

To prevent that an alarm is raised on the default value when the connection to the device is lost, this field must be set to DriverFail.

NOTE: The default value for the OPC discovery is empty.

[Logical Hierarchy]

Optional

Path of the logical view where the point that corresponds to the OPC item will be created, provided that a node of the logical view was set as root for the logical hierarchy.

Syntax: \<Level0>\<Level1>\…\<Level-n>\

Example: \BuildingA\Floor3\room403\

NOTE: A backslash (\) is used as level separator, and also at the beginning and at the end of the path.
The importer automatically adds the data point to the logical hierarchy path after the last separator. Then, it adds the resulting hierarchy to the logical view root node in System Browser.
For example, if the data point “Light403_11” is associated with the hierarchy path “\BuildingA\Floor3\Room403\”, the following logical hierarchy will be presented in System Browser:
“<Logical Hierarchy Root Node>\Building A\Floor3\Room403\Light403_11”.

[User Hierarchy]

Optional

Path of the user-defined view where the point that corresponds to the OPC item will be created, provided that a node of the user-defined view was set as root for the user hierarchy.

Syntax: \<Level0>\<Level1>\…\<Level-n>\

Example: \BuildingA\Floor3\room403\

NOTE: A backslash (\) is used as level separator, and also at the beginning and at the end of the path.
The importer automatically adds the data point to the user-defined hierarchy path after the last separator. Then, it adds the resulting hierarchy to the user-defined view root node in System Browser.
For example, if the data point “Light403_11” is associated with the hierarchy path “\BuildingA\Floor3\Room403\”, the following user-defined hierarchy will be presented in System Browser:
“<User Hierarchy Root Node>\Building A\Floor3\Room403\Light403_11”.

Notes About Editing the CSV File

  • If you edit a file in Microsoft Excel, separate fields with semicolons.
  • Each comment line starts with a number sign (#). These lines are ignored during the import process.
  • The elements of an OPC configuration file must be added in the following order: servers, groups, and items. Changing this order may result in data rejected during the import.
  • If you do not enter a Function name in the CSV file, default values are taken from the object model configuration.
  • If any of the alarm fields contains an error, the point is imported, but no alarm is configured.
  • If multiple alarm configurations are listed in one of the fields, the dollar sign ($) must be used as separator.

 

Special Characters

  • A semicolon (;) is used as field separator. Do not use a semicolon (;) in the strings.
  • Do not use the dollar sign ($) in the server name and group name. This special character is already in use in the definition of the peripheral address (see OPC Items Data).
  • In the [Name] field of the elements (servers, groups, and items) the characters in the following table are replaced with underscores:

 

Glyph

Description

 

Whitespace

/

Slash

\\

Double backslash

-

Hyphen-minus

?

Question mark

.

Full stop

!

Exclamation mark

@

At sign

#

Number sign

%

Percent sign

^

Circumflex accent

$

Dollar sign

,

Comma

;

Semicolon

[

Left square bracket

]

Right square bracket

{

Left curly bracket

}

Right curly bracket

(

Left parenthesis

)

Right parenthesis

\t

Tab space

*

Asterisk

§

Section sign