About the Configuration File

The ptopc_config.xml file provides the Advanced Viewer with the configurations using which it can collect data from an assigned OPC Server and OPC UA Server. Along with the configuration file, there is a ptopc_config_samples.xml file that consists of examples with different levels of security, user authentication types, address formatting, and more. You can copy the configurations from the sample files as needed and use them in the ptopc_config.xml file. Both files are available at [Install location]\Proficy\Proficy CIMPLICITY\data.

In the ptopc_config.xml file, you must enter the OPC Classic server configurations under the <projects> node and the OPC UA server configurations under the <uaprojects> node. There is also a <ua_pki> node used for managing the OPC UA application instance certificate. For more information on managing OPC UA application instance certificates, see Manage OPC UA application instance certificates.

To understand the configuration structure and how the XML files are organized, it is recommended to have both the ptopc_config.xml and ptopc_config_samples.xml files open while reading this topic.

An example structure of the ptopc_config.xml file

<config>

  <projects>                           <!-- Node to enter OPC Classic projects related configurations -->
        <MYOPCCLASSICPROJECT>          <!-- OPC Classic Project name -->
                                       <!-- Enter configurations related to OPC Classic projects and other common configurations here -->
        </MYOPCCLASSICPROJECT>
  </projects>

  <uaprojects>                         <!-- Node to enter OPC UA projects related configurations -->
        <MYOPCUAPROJECT>               <!-- OPC UA Project name -->
                                       <!-- Enter configurations related to OPC UA projects and other common configurations here -->
        </MYOPCUAPROJECT>
  </uaprojects>

  <client_name>CimView</client_name>
  <trace_flags>00</trace_flags>
  <log_to_file>false</log_to_file>
  <archive_log_files>false</archive_log_files>

  <ua_pki>                              <!-- Node to enter OPC UA application certificate details -->
  </ua_pki>

</config>

To understand the different configurations that can be used in the ptopc_config.xml file, refer to the tables below:

Configurations specific to OPC Classic Projects

Configurations Optional/ Mandatory Description
<projects> Mandatory Identifies the section for defining your OPC Classic project specific configurations.
<projectname> Mandatory This identifies the CIMPLICITY project name. For example, <MYCIMPLICITYPROJECT>
<opc_prog_id> Mandatory Program ID in the registry that identifies the OPC server to be used. This is the same Program ID used by the OPC client communications device in the Network Address field of an OPC device. For example, NDI.OPCATLSimSvr.1.
<dcom_timeout> Optional The amount of time the client must wait for a valid connection to the OPC server. When any action is performed that involves the OPC server, those actions happen on a separate thread. The main thread will wait for the DCOM timeout for the other thread to complete the call to the OPC server. If the separate (worker or pool) thread does not return in that amount of time, the main thread is allowed to continue (with an error noted).
<dcom_threshold> Optional How long the OPC Client waits to abort the connection to the OPC server after detecting that the server has not responded to a ping. Enter the DCOM timeout threshold in milliseconds (ms). The default value is 20000 milliseconds.
<item_property_subscriptions> Optional Available with OPC Servers that implement the IOPCBrowse interface as part of the OPC DA 3.0 Specifications. The default value is TRUE.
<RemoveInvalidItems> Optional Determines whether to remove invalid items. The default value is TRUE.
<RemoveItemsOnRemoveGroup> Optional Determines whether to remove the items that are in the remove group. The default value is FALSE.
Configurations Specific to OPC UA Projects
Configurations Optional/ Mandatory Description
<uaprojects> Mandatory Identifies the section for defining your OPC UA project specific configurations.
<endpoint_url> Mandatory
Endpoint URL of the OPC UA Server.
Note: Only opc.tcp type transport is supported.

If the value has a special placeholder [NodeName], it will be substituted by the host name of the machine where Advanced Viewer is running.

For example, to connect to the CIMPLICITY OPC UA Server running on the same host at default port number 51800, the endpoint URL can be entered as opc.tcp://[NodeName]:51800.
<security_settings> Mandatory

Determines the security mode and policy to use. The following are the two required security configurations:

Security policy:

<security_policy>

Supported policies are:

  • None
  • Basic256Sha256
  • Aes128-Sha256-RsaOaep
  • Aes256-Sha256-RsaPss

Security mode:

<security_mode>

Supported modes are:

  • None
  • Sign
  • SignAndEncrypt
<authentication_settings> Mandatory Determines the authentication credentials of the user associated with the OPC UA session created by Advanced Viewer on the OPC UA Server.
<authentication_method> Mandatory Determines the user authentication method to be used. The following methods are supported:
  • anonymous- no authentication is required.
  • user_token- CIMPLICITY will ask you for the user name and password required to log into the server.
  • certificate- User certificate authentication. Requires certificate configuration.
<certificate> Mandatory if you selected the user authentication method as certificate. Determines the user certificate settings. The following certificate files are mandatory for this authentication method.

<public_key_file_name> in the following format: [C:\HardCodedPath]\TrustMe.DER.

<private_key_file_name> in the following format: [C:\HardCodedPath]\TrustMe.PEM.

If you used a password while generating the private key, you can enter that password in the <private_key_password> node in plain text encryption format.
Note: The password field can be empty; however, the private key will not be encrypted. So, it is not recommended to leave the password field empty in a production environment.
<display_format_browse_name> Optional This parameter is a replacement for the OPC DA (Classic) global property_id_display_format. It defines an OPC UA Property browse name that would contain the display format. This is a qualified name that requires a namespace index and the name.
  • <namespace_index>- Namespace of the browse name for the display format property. The default value is 0.
  • <name>-Name of the browse name for the display format property.
<default_address> Optional

Determines how the CIMPLICITY point ID is converted to the OPC UA Node ID.

If you browse the OPC UA Server address space using Advanced Viewer, the returned full Point Ids would look like \\MyProject\ns=12;s=MyPoint, where,

MyProject- is the project name (that is, the name of the XML node under <uaprojects> node).

ns=12;s=MyPoint is the Point ID that is equal to the OPC UA Node Id represented in text format.

ns is the namespace index.

s is the node identifier in string format.

The configurations below the default_address node allow for more user-friendly, shorter point names, skipping namespace index definitions, and s= parts. This can be useful if most points have a node ID in the same namespace and have a string type.

For example, the default_address as follows in the example below could be used to allow point ID \\MyProject\ns=12;s=MyPoint to be configured in the CimView screen or Point Control Panel as \\MyProject\MyPoint:

                 <default_address>
                        <default_namespace_index>12</default_namespace_index>
                        <default_address_format></default_address_format>
                  </default_address>

The above example assumes that the default_address_format is blank, so it will be set to the default value, s= and the default_namespace_index to 12. This will be interpreted as the full OPC UA node ID as ns=12;s=MyPoint.

The below configurations are available under this node:

  • <default_namespace_index>- - The namespace index part of the OPC UA node ID to use if the Point ID does not have it defined. It must be greater or equal to 0. If the field is missing or has a negative value, that means that the field is not defined.
  • <default_namespace>- The namespace used to find the namespace index from the OPC UA Server's Namespace Array node, if this field is not defined.
  • <default_address_format>- The string format specifier to compose the string type identifier part of the OPC UA node ID. The default value is s=.
    • If the value is not empty, it will be appended to the default value. This means the value should not start with s=.
    • If the value has a format specifier {}, then this part will be replaced by the Point ID.
    • If the value does not have a format specifier {}, the identifier will be composed by appending Point ID at the end of the field's value.

      Example 1

                       <default_address>
                        <default_namespace_index>2</default_namespace_index>
                        <default_address_format></default_address_format>
                  </default_address>

      The string identifier portion will be composed by appending Point ID to the default value s=: s=MyPoint. The full OPC UA node ID will be ns=2;s=MyPoint

      Example 2

                       <default_address>
                        <default_namespace_index>2</default_namespace_index>
                        <default_address_format>{}</default_address_format>
                  </default_address>

      The string identifier formatter will be defined as s={}; after replacing the specifier {} with the point ID, it becomes s=MyPoint; full Point ID will be ns=2;s=MyPoint

      Example 3

                       <default_address> 
                        <default_namespace_index>2</default_namespace_index>
                        <default_address_format>{}.Value</default_address_format>
                  </default_address>

      This case can be useful when the CIMPLICITY OPC UA Server is the OPC UA Server, where CIMPLICITY points are represented as objects whose values are represented in their child nodes with and identifier composed as the point object's identifier with an appended postfix .Value.

      \ \DEMOPROJECT\MyPoint will be interpreted as OPC UA Node ID, ns=2;s=MyPoint.Value
<connect_timeout> Optional Determines the amount of time the client must wait for a valid connection to the OPC UA server. The default value is 5000.
<ping_interval> Optional Determines how often the OPC client reads the value of the OPC UA server state node. The default value is 15000 milliseconds.
<max_nodes_per_read> Optional Determines the maximum number of nodes that the Advanced Viewer will attempt to read for snapshot reads. This parameter is meant to communicate with servers with limited capacity. The parameter is meant to communicate with the Server\ServerCapabilities\OperationLimits\MaxNodesPerRead node ID. The default value is 0.
<max_nodes_per_write> Optional Determines the maximum number of nodes that the Advanced Viewer will attempt to write for setpoint writes. This parameter is meant to communicate with servers with limited capacity. The parameter is meant to communicate with the Server\ServerCapabilities\OperationLimits\MaxNodesPerWrite node ID. The default value is 0.
<max_nodes_per_browse> Optional Determines the maximum number of nodes that the Advanced Viewer will attempt to browse at a time. This parameter is meant to communicate with servers with limited capacity. The parameter is meant to communicate with the Server\ServerCapabilities\OperationLimits\MaxNodesPerBrowse node ID. The default value is 0.
Note: The Advanced Viewer will set the maximum number of nodes per browse to 100 to provide a better user experience.
<max_nodes_per_subscription> Optional Determines the maximum number of nodes (monitored items) per subscription from the client side. By default, it is set to 0. This will create one subscription per OPC UA Server connection for all monitored items (or points in terms of CIMPLICITY). To avoid loss of points received from the server and not exceed the maximum limit of monitored items, it is advised that you set the <max_nodes_per_subscription>based on the monitored items per subscription settings on the server side.
Note: If the OPC UA Server feature is enabled in the CIMPLICITY project, the server-side limits are configured in the MaxMonitoredItemPerSubscriptionCount option in the file [project folder]/data/ServerConfig.xml.
<browse_start_node_id> Optional The starting node for a browse. The default start node ID is the Root Folder. To reduce the number of browse operations, you can define a different start node ID, such as the Objects Folder. It will browse all child nodes, starting from the start node recursively.

You can enter the value in the following format: [ns=<numeric value>; s=MYPROJECTNAME].
<browse_node_to_ignore> Optional Allows you to prevent browsing on a particular node to optimize the browse operations. This parameter can be used multiple times to ignore browsing on specific nodes.

A recommendation could be to ignore the Server object, the Types Folder, and the Views Folder.

For example,

<browse_node_to_ignore>i=2253</browse_node_to_ignore>

<browse_node_to_ignore>i=86</browse_node_to_ignore>

<browse_node_to_ignore>i=87</browse_node_to_ignore>
<certificate_validation_rules> Optional Determines the validation rules for the OPC UA Server instance certificate. If any of the Server instance certificates are not compliant and you are sure about the certificate, you can use the below configurations. If you do not enter a value, the default value will be used. The default value is FALSE.

<accept_any_server_certificate>

<disable_application_uri_check>

<disable_certificate_usage_check>

<disable_error_certificate_host_name_invalid>

<disable_error_certificate_issuer_time_invalid>

<disable_error_certificate_revocation_unknown>

<disable_error_certificate_time_invalid>

OPC UA Application Instance Certificate Configurations

The below configurations are specific to OPC UA Application instance Certificates used in communication with the OPC UA Server. These configurations will be automatically generated when the Advanced viewer is started.

The Advanced Viewer will create a certificate store in the [Install folder]\admin_data\CIMPLICITY Advanced ViewerPKI directory. This directory requires administrator privileges to be modified for additional security.

If you decide to use different values, you can modify some of the automatically generated parameters, then delete the [Install folder]\admin_data\CIMPLICITY Advanced ViewerPKI directory, and the Advanced Viewer can then recreate the certificate storage with the new parameters. You can also add your own certificates and configure the locations of the private and public keys and password accordingly. For more information, see Manage OPC UA application instance certificate.

See the below descriptions of the configurations available below <ua_pki> section of the configuration and sample files.

Configurations Optional/ Mandatory Description
<ua_pki> Mandatory Defines the certificate parameters required for secure communications.
<max_rejected_certificates> Optional

Determines the maximum number of certificate files that can be stored in the rejected certificates folder.

When the Advanced Viewer is configured to connect to the OPC UA server in secured mode and if the server certificate is not trusted or valid,the certificate is saved in the rejected certificates folder located at [Install folder]\admin_data\CIMPLICITY Advanced ViewerPKI\rejected. If you trust the certificate, you must move the certificate to the trusted folder. For more information, see Establish Trust between Server and Advanced Viewer OPC UA Client.

Once the number of files in this folder reaches its maximum limit, the oldest file is automatically deleted.
<certificate> Mandatory for OPC UA projects

Defines the OPC UA Application Instance Certificate's public and private key file locations and field values for the default auto-generated self-signed certificate.

If you are using your own certificate generated by a third-party tool or GE Global Discovery Server (GDS), you can configure locations of certificate files under this section. For more information on managing certificates, see Manage OPC UA application instance certificate.
<file> Mandatory Node to enter the certificate options. If either the public key or the private key file is not found, both files are auto-generated when the OPC UA project starts. When the files are auto-generated, the configurations under this node are used.
The following are the types of files that you can configure:
  • <public_key> - The Public key certificate file. “der” files are expected. The default location is [Install folder]\admin_data\CIMPLICITY Advanced ViewerPKI\own\cert. You can also use other fully qualified paths.
  • <private_key> - The private key certificate file. “pem” files are expected. The default location is [Install folder]\admin_data\CIMPLICITY Advanced ViewerPKI\own\private. You can also use other fully qualified paths.
  • <private_key_password> -

    The password used to encrypt the application instance certificate’s private key. If this configuration is empty, then the private key is not encrypted. In a production environment, it is not recommended to store the private key without encryption.

    If the certificate is going to be auto-generated, then there is no predefined value, in that case if you want to use some unique strong random value, you can use special placeholder value as an encryption password: [GenerateRandomPassword]. It will be replaced with a randomly generated password by the Advanced Viewer while it starts.

    Note: The password value should be entered as a plain text. It will be stored by Advanced Viewer in an encrypted format at startup.
    Note: The private key encryption password stored in this field should match the password that was actually used to encrypt the private key file; otherwise, at the next start, that private key cannot be read anymore.
<fields> Optional The parameters used for the automatic generation of application certificates.
<common_name> Optional

The common name of the certificate. The auto-generated value is [ProductName]@[NodeName].

The Advanced viewer will interpret the bracketed values as follows:

  • ProductName will be CIMPLICITY Advanced Viewer.
  • NodeName will be interpreted as the name of the current machine in use.
<domain_component> Optional The certificate domain component name. The auto-generated value is [NodeName].

The Advanced viewer will interpret the bracketed values as follows:

  • NodeName will be interpreted as the name of the current machine in use.
<organization> Optional Certificate's organization name. The auto-generated value is Organization.
<organization_unit> Optional Certificate organization's unit name. The auto-generated value is Unit.
<locality> Optional Certificate organization's locality name. The auto-generated value is Locality.
<state> Optional Certificate organization's State name. The auto-generated value is NY.
<country> Optional Certificate organization's two-letter ISO country code. The auto-generated value is US.
<years_valid_for> Optional The generated certificate's validity. The auto-generated value is 10 years.
<key_length> Optional The certificate's key length. The auto-generated value is 4096.

Common Configurations for both OPC Classic and OPC UA Projects

Configurations Optional/ Mandatory Description
<reconnect_interval> Optional Time between reconnection attempts. This time does not include the time it takes Microsoft's COM (DCOM) engine to determine if it is able to launch the OPC server application. The default value is 15000 milliseconds.
<hang_protection_timeout> Optional Determines the time before the Advanced Viewer times out. An error is written to the core log, reporting that the OPC Server appears to be hanging. The default value is 120000 milliseconds.
<item_property_subscriptions> Optional Determines whether the Advanced Viewer should create monitored items for properties and attributes for each node ID that is added. The default value is TRUE.
<RemoveInvalidItems> Optional Determines whether to remove any invalid items. The default value is TRUE.
<RemoveItemsOnRemoveGroup> Optional Determines whether to remove the items that are added to the remove group. The default value is FALSE.
<client_name> Optional This line allows the Advanced Viewer to identify itself to the OPC Server through the IOPCCommon::SetClientName function. Because the Advanced Viewer is designed to work with external OPC servers (not the OPC Server that comes with CIMPLICITY) you might have to make use of IOPCCommon::SetClientName so the OPC Server can perform special logic based on what type of client is connecting to it. You enter the Advanced Viewer name as a string between the XML tags. Example In the following string: <client_name>AdvancedViewer</client_name> AdvancedViewer will be passed as a parameter to the SetClientName function. This allows the Advanced Viewer (which is an OPC client) to identify itself as a particular type of client to the external OPC Server.
Note: The OPC Foundation Web site provides more information about the IOPCCommon::SetClientName function in its OPC DA 3.0 Specification.
<default_update_rate> Optional How often the OPC server updates the items in this group with fresh device data. It also determines how often to send the default value of1000 milliseconds.
Note: CPU usage increases when updates are set to occur more frequently.
<update_rates> Optional Starts update rates for selected groups that are different from the default update rate. The available configurations are:

<subsecond>- The default value is 200.

<two>- The default value is 2000.

<five>- The default value is 5000.

<ten>- The default value is 10000.
<trace_flags> Optional A trace flag utility is required for the <trace_flags> setting. The following are the values:

TRACE_SERVICE 0x01

TRACE_CONNOBJ 0x02

TRACE_CONNMGR 0x04

TRACE_CONFIG 0x08

TRACE_POINTS 0x10

TRACE_POINTSMGR 0x20

TRACE_POINT 0x40

TRACE_EVENTS 0x80

TRACE_PING 0x100

TRACE_METHODS 0x200

TRACE_POOL 0x400

TRACE_DATASRC 0x800

TRACE_POINTS2 0x1000

TRACE_POINTSMGR2 0x2000

Setting the above values will create several log files and occupy more disk space. It is recommended to set the value to 0 and use the above values only to troubleshoot any issues.
<log_to_file> Optional Determines the logging location. The default value is FALSE. If it is set to TRUE, the log file is stored at [CIMPLICITY Install folder]/log/FullPTOPCLogging.log.
<archive_log_files> Optional Determines the location for the log archives. The default value is FALSE. If it is set to TRUE, the log files are stored at [CIMPLICITY Install folder]/log/ with a unique filename, for example, FullPTOPCLogging_001.log, FullPTOPCLogging_002.log, and more.