You are on page 1of 20

OPC TUNNELLER

USER'S MANUAL
VERSION 1.01.0
FEBRUARY 21, 2003
Matrikon OPC Tunneller User's Manual

DOCUMENT HISTORY
Document
Date Author Comments
Version

Dec 10, 2002 M.I. 1.0 First draft.

February 10, S.M.L 1.1 Product upgrades


2003

ii
Matrikon OPC Tunneller User's Manual

TABLE OF CONTENTS
1. INTRODUCTION................................................................................................................ 1
1.1 OVERVIEW .................................................................................................................. 1
1.2 HARDWARE REQUIREMENTS ....................................................................................... 2
1.3 SOFTWARE REQUIREMENTS ........................................................................................ 3
2. INSTALLATION AND OPERATION ....................................................................................... 4
2.1 TUNNELLER SERVER SIDE GATEWAY............................................................................. 4
2.1.1 INSTALLING THE TUNNELLER SERVER-SIDE GATEWAY ........................................... 4
2.1.2 STARTING THE TUNNELLER SERVER-SIDE GATEWAY .............................................. 5
2.1.3 STOPPING THE TUNNELLER SERVER-SIDE GATEWAY ............................................. 5
2.2 TUNNELLER CLIENT-SIDE GATEWAY ............................................................................ 6
2.2.1 INSTALLING THE TUNNELLER CLIENT-SIDE GATEWAY ........................................... 6
2.2.2 STARTING UP (CLIENT-SIDE GATEWAY)................................................................. 6
2.2.3 STARTING THE TUNNELLER CLIENT-SIDE GATEWAY CONFIGURATION UTILITY ..... 7
2.2.4 STARTING THE TUNNELLER CLIENT-SIDE GATEWAY .............................................. 7
2.3 SHUTTING DOWN...................................................................................................... 7
2.3.1 STOPPING THE TUNNELLER CLIENT-SIDE GATEWAY CONFIGURATION UTILITY..... 8
2.3.2 STOPPING THE TUNNELLER CLIENT-SIDE GATEWAY ............................................. 8
3. CONFIGURATION ............................................................................................................. 9
3.1 OPC TUNNELLER SERVER-SIDE GATEWAY CONFIGURATION ....................................... 9
3.1.1 EXAMPLE CONFIGURATION FILE .......................................................................... 9
3.1.2 [LOG] SECTION................................................................................................. 10
3.1.2.1 FILE SIZE OPTION ....................................................................................... 10
3.1.2.2 LEVEL OPTION ............................................................................................ 10
3.1.2.3 LOG TO SCREEN OPTION .......................................................................... 10
3.1.3 [COMMUNICATION] SECTION .......................................................................... 10
3.1.3.1 TRANSPORT OPTION .................................................................................. 10
3.1.3.2 TIMEOUT OPTION ...................................................................................... 10
3.1.3.3 RETRIES OPTION......................................................................................... 11
3.1.3.4 PORT OPTION ............................................................................................ 11
3.2 OPC TUNNELLER CLIENT-SIDE GATEWAY CONFIGURATION ..................................... 11
3.2.1 CLIENT CONFIGURATION UTILITY...................................................................... 11
3.2.1.1 ADDING A REMOTE SERVER ........................................................................ 12
3.2.1.2 DOWNLOADING AND REGISTERING TUNNELLED SERVERS.......................... 14
3.2.1.3 VIEWING AND UPDATING A REMOTE COMPUTER CONNECTION............... 14
3.2.1.4 VIEWING AND UPDATING A TUNNELLED SERVER CONFIGURATION............ 15
3.2.1.5 UNREGISTERING TUNNELLED SERVERS ........................................................ 16
4. UNINSTALLATION ............................................................................................................ 17

iii
Matrikon OPC Tunneller User's Manual

1. INTRODUCTION
This document describes the use and operation of the Matrikon OPC Tunneller software.

1.1 OVERVIEW
Companies wishing to use OPC technology to link operators and engineers with plant devices
often encounter communications problems. The majority of these problems occur not during
normal operation but at the time of installation. Quite often plant engineers face difficulties
configuring cross-network communication, windows authentication, and start up and run-time
permissions.

OPC Tunneller aims to alleviate many of these problems by providing a mechanism for OPC
data communication without the use of distributed COM (DCOM). The primary issues that
Tunneller addresses are:

Allows cross domain and cross workgroup communication with minimal network
configuration

Bypasses normal Windows authentication used by DCOM

Provide fine control over communication timeouts


By eliminating these common DCOM hurdles, the Matrikon OPC Tunneller will enable the smoothest
possible installation and operation of OPC technology in any environment.

OPC Client Node OPC Server Node


OPC Server 1

OPC Client1
Tunneller Tunneller OPC Server 2
Client-Side Server-Side
OPC Client 2 Gateway Gateway
OPC Server 3

Tunnelled OPC OPC Server 4


Server List

OPC Tunneller

Figure 1: Tunneller Solution

The Tunneller solution combines two applications:

1
Matrikon OPC Tunneller User's Manual

- Tunneller Client-Side Gateway (local)

- Tunneller Server-Side Gateway (remote)

Local Tunneller application

The Tunneller Client-Side Gateway is installed on the computer where the OPC clients reside. The
Client Side Gateway provides tunnelled program ids for remote servers and manages communication with
OPC clients. By default, this application is automatically run whenever a client attempts a connection to
a tunnelled OPC server.

Figure 2: Local connections to Tunnelled OPC Servers

Remote Tunneller application

The Tunneller Server-Side Gateway resides on the remote machine and manages communication with
OPC servers. The Tunneller Server-Side Gateway application is typically run as a service on the remote
machine. The Tunneller Server-Side Gateway application must be running on the remote computer to
enable tunnelling.

1.2 HARDWARE REQUIREMENTS


OPC Tunneller is extremely lightweight and uses very few resources. If the target machine can
run the desired OPC application it should have no problems running either the Tunneller Client-
Side Gateway, or the Tunneller Server-Side Gateway.

2
Matrikon OPC Tunneller User's Manual

1.3 SOFTWARE REQUIREMENTS


The operating system required by OPC Tunneller is Microsoft Windows 2000. Additionally, the OPC
client computer must have an OPC compliant client application and the OPC server computer must have
an OPC compliant Data Access server.

OPC Tunneller will not support the Historical Data Access or Alarms and Events
specifications at this time.
Note

3
Matrikon OPC Tunneller User's Manual

2. INSTALLATION AND OPERATION


This section describes the installation and usage of the Matrikon OPC Tunneller software. It is
recommended to install and operate the Server-Side Gateway application before installing and
configuring the client-side applications.

2.1 TUNNELLER SERVER SIDE GATEWAY

2.1.1 INSTALLING THE TUNNELLER SERVER-SIDE GATEWAY

OPC Server Node


OPC Server 1

Tunneller OPC Server 2


Server Side
Gateway
OPC Server 3

OPC Server 4

Figure 3 Tunneller Server-Side Gateway

The OPC Tunneller Server-Side Gateway software receives the IP-based messages sent by the
OPC Tunneller Client-Side Gateway, converts them to OPC requests, and communicates them to
a local OPC Server. The OPC Tunneller Server-Side Gateway software must be installed on the
same computer as the ‘remote’ OPC Server(s) that are to be ‘tunnelled’.

To install the OPC Tunneller Server-Side Gateway software:

1. Run the OPC Tunneller installation package on the OPC Server computer
(MatrikonOPCTunneller.exe).

2. During the install, an option to select Tunneller Client-Side Gateway or Tunneller Server-
Side Gateway installation will appear. Select Tunneller Server-Side Gateway install
and simply follow the remaining steps specified by the installer.

If successful, a dialog box will appear indicating that OPC Tunneller has been successfully
installed.

4
Matrikon OPC Tunneller User's Manual

2.1.2 STARTING THE TUNNELLER SERVER-SIDE GATEWAY


On the remote machine, locate and click the shortcut named “OPC Tunneller Server” from the
start menu.

From the command-line, the OPC Tunneller Server has the following options:

Parameter Description

-INSTALL Registers the OPC Tunneller Server to run as an NT service. By default the
service is set to run as the System account as an interactive process.

Removes all registry entries for the OPC Tunneller Server (uninstalling the
-UNINSTALL
NT service if necessary).

Starts up a copy of the OPC Tunneller Server as a local executable. It is


(no parameters) preferable to start the server up from the start menu instead of from the
command line.

When the OPC Tunneller Server-Side Gateway is running, unless it is running as a service, the
white background Matrikon logo icon will appear on the system tray with the tool tip “server”
(see figure below).

Figure 2 – OPC Tunneller Client Tray Icon

2.1.3 STOPPING THE TUNNELLER SERVER-SIDE GATEWAY


To stop the OPC Tunneller Server, right-click on the associated tray icon and click “Exit” (see figure
below).

Figure 5 – OPC Tunneller Server-Side Gateway Tray Icon Menu

If the OPC Tunneller Server-Side Gateway is running as a service, it can be manually stopped
from the Service Control Manager.

5
Matrikon OPC Tunneller User's Manual

2.2 TUNNELLER CLIENT-SIDE GATEWAY


This section describes how to install and operate the OPC Tunneller Client-Side applications.

2.2.1 INSTALLING THE TUNNELLER CLIENT-SIDE GATEWAY

OPC Client Node

OPC Client1
Tunneller
Client Side
OPC Client 2 Gateway

Figure 4 Tunneller Client-Side Gateway

The OPC Tunneller Client-Side Gate software will capture and convert all local OPC Client
communications into fast, efficient IP-based messages and transmit them to the OPC Tunneller
Server-Side Gateway software. The OPC Tunneller Client-Side Gateway software must be
installed on the same computer as the OPC Client.

To install the OPC Tunneller Client-Side Gateway software:

1. Run the OPC Tunneller installation package on the OPC Client computer
(MatrikonOPCTunneller.exe).

2. During the install, an option to select Tunneller Client-Side Gateway or Tunneller Server-
Side Gateway installation will appear. Select Tunneller Client-Side Gateway install
and simply follow the remaining steps specified by the installer.

If successful, a dialog box will appear indicating that OPC Tunneller has been successfully
installed.

2.2.2 STARTING UP (CLIENT-SIDE GATEWAY)


This section describes how to start up the client side applications included with the OPC Tunneller
installation.

After installation, the OPC Tunneller Client-Side Gateway needs to be configured


before using (to do this please refer to Section 3 - Configuration).
Note 6
Matrikon OPC Tunneller User's Manual

2.2.3 STARTING THE TUNNELLER CLIENT-SIDE GATEWAY CONFIGURATION


UTILITY
To start the OPC Tunneller Client Configuration Utility, simply locate and click on the shortcut named
“Tunneller Client Config” from the start menu.

2.2.4 STARTING THE TUNNELLER CLIENT-SIDE GATEWAY


The OPC Tunneller Client-Side Gateway process can be started manually by locating and
clicking on the shortcut named “Matrikon OPC Tunneller” from the start menu, or
automatically by connecting an OPC Client to one of the “Tunnelled” OPC Servers.
Additionally, if the OPC Tunneller Client-Side Gateway is installed as a service, it can be started
manually through the Service Control Manager.

From the command-line, the OPC Tunneller Client-Side Gateway has the following options:

Parameter Description

/REGSERVER
Registers the OPC Tunneller Client to run as a local executable
–REGSERVER
(uninstalling the NT service if necessary).
/SERVICE Registers the OPC Tunneller Client to run as an NT service. By default the
–SERVICE service is set to run as the System account as an interactive process.

/UNREGSERVER Removes all registry entries for the OPC Tunneller Client (uninstalling the
–UNREGSERVER NT service if necessary).

Starts up a copy of the OPC Tunneller Client as a local executable. It is


(no parameters) preferable to start the server up from the start menu or an OPC client
instead of from the command line.

When the OPC Tunneller Client is running, unless it is running as a service, the Matrikon logo
icon will appear on the system tray with the tool tip “Matrikon OPC Tunneller” (see figure
below).

Figure 1 – OPC Tunneller Client Tray Icon

2.3 SHUTTING DOWN

7
Matrikon OPC Tunneller User's Manual

This section describes how to shut down all of the applications included with the OPC Tunneller
installation.

2.3.1 STOPPING THE TUNNELLER CLIENT-SIDE GATEWAY CONFIGURATION


UTILITY
To stop the OPC Tunneller Client Configuration Utility, select “exit” from the File Menu (see
figure below).

Figure 3 – Client Configuration Utility File Menu

2.3.2 STOPPING THE TUNNELLER CLIENT-SIDE GATEWAY


Disconnecting all OPC Clients from the OPC Client-Side Gateway will, after approximately a minute,
cause the OPC Tunneller Client-Side Gateway to shut down. To manually stop the OPC Tunneller
Client-Side Gateway, right-click on the associated tray icon and click “shutdown” (see figure below).

Figure 4 – OPC Tunneller Client Tray Icon Menu


If the OPC Tunneller Client is running as a service, it can be manually stopped from the Service Control
Manager.

8
Matrikon OPC Tunneller User's Manual

3. CONFIGURATION
This Section details the configuration of the all the OPC Tunneller software. If this is the first
time configuring OPC Tunneller, ensure that you read this entire section before attempting
configuration.

3.1 OPC TUNNELLER SERVER-SIDE GATEWAY CONFIGURATION


The OPC Tunneller Server uses an INI file for its configuration. The INI file, named
“tunneller.ini” must be in the same directory as the Tunneller Server and cannot be renamed.
The file is loaded by the server on start up and is scanned at regular intervals for changes. The
next few sections detail the INI file parameters required to set up the Tunneller Server.

The OPC Tunneller Server should be the first component configured because all of the
client-side components require that the server be fully set up and running. The default
configuration is fine for most installations.
Note

3.1.1 EXAMPLE CONFIGURATION FILE


For your convenience, below is an example OPC Tunneller Server configuration file. A sample
one, like the one below, should be included in the installation. The description of each option is
detailed in the sections below.

[LOG]
File Size = 1
Level = 3
Log To Screen = 1

[COMMUNICATION]
Transport = TCP
Timeout = 10
Retries = 3
Port = 21378

9
Matrikon OPC Tunneller User's Manual

Figure 6 – Example OPC Tunneller Server Configuration File

3.1.2 [LOG] SECTION


The options listed under the [LOG] section control parameters that affect the OPC Tunneller
Server’s logging capabilities.

3.1.2.1 FILE SIZE OPTION


This option determines the maximum size of the log file generated by the OPC Tunneller Server.
This value must be an integer and is in bytes.

3.1.2.2 LEVEL OPTION


This option determines the detail of log messages written to the log file. The value is an integer
and has the following items:

1 Low-level logging. Only critical events are logged

2 Medium-level logging. Useful for troubleshooting.

3 High-level logging. Useful for debugging.

3.1.2.3 LOG TO SCREEN OPTION


This is a Boolean option to enable or disable on-screen logging through a command window.
The following are valid items:

0 On-screen logging disabled.

1 On-screen logging enabled.

3.1.3 [COMMUNICATION] SECTION


The options listed under the [COMMUNICATION] section control parameters that affect the
OPC Tunneller Server’s communications capabilities.

3.1.3.1 TRANSPORT OPTION


The transport option defines which IP-based transport layer to use when accepting and
transferring data. Currently, OPC Tunneller only supports the TCP (Transport Control Protocol)
so there is no need to change this option.

3.1.3.2 TIMEOUT OPTION

10
Matrikon OPC Tunneller User's Manual

This option specifies the number of seconds to wait for a response from the OPC Tunneller
Client before attempting to retry the request. This value must be an integer between 1 and
65535.

3.1.3.3 RETRIES OPTION


The retries option allows the user to define the total number of request retries to make before
giving up on a request and logging a failure. A retry is only made if a request times out.

3.1.3.4 PORT OPTION


This option determines which TCP port that the OPC Tunneller Server will listen on for remote
Tunneller client requests. It must be an integer between 1 and 65535.

Port numbers from 1-2000 are generally reserved for known protocols so it is
recommended that you use a port numbers outside of this range.
Note

3.2 OPC TUNNELLER CLIENT-SIDE GATEWAY CONFIGURATION


With the exception of logging and specific OPC parameters, the entire OPC Tunneller Client
configuration is done through the Tunneller Client Configuration Utility.

3.2.1 CLIENT CONFIGURATION UTILITY


To configure the Tunneller Client, start up the Tunneller Client Configuration Utility (see figure
below).

11
Matrikon OPC Tunneller User's Manual

Figure 7 – Client Configuration Utility (Main Screen)

The purpose of the Tunneller Client-Side Gateway Configuration Utility is to create and
configure local, “emulated”(AKA “tunnelled”) versions of the remote OPC Servers for an OPC
Client to connect to. To accomplish this, the Client Configuration Utility must connect to the
OPC Tunneller Server-Side Gateway, running on the remote computer, and download the list of
OPC Server program Ids.

3.2.1.1 ADDING A REMOTE SERVER


To set up a remote server connection, click on the file menu and select “Add Remote Tunneller
Connection”, pressing the Remote Connection Button, or press Ctrl+N (see figure below).

Figure 8 – Client Configuration Utility File Menu

12
Matrikon OPC Tunneller User's Manual

Figure 5:Remote connection button

This should display the Remote Server Configuration panel (shown below).

Figure 9 – Remote Server Configuration Panel

To configure a connection to a remotely running OPC Tunneller Server, fill-in the remote
server’s hostname, the port number that the remote Tunneller Server is listening on, and the
connection timeout/retries. The table below describes all of the parameters in detail.

Field Purpose

Hostname/IP This is the Hostname or IP Address of the computer currently running the OPC
Address Tunneller Server. To browse the network for machines, simply click the drop
down menu and find the correct hostname. This field defaults to the current
machine’s hostname.

Port Number This is the TCP port that the remote OPC Tunneller Server was configured to
listen on (refer to section 3.1.1 for the location of this parameter in the
Tunneller Server configuration). Both the OPC Tunneller Server and Client
default to port 21379.

Timeout The timeout field specifies the number of seconds to wait for a response from
the OPC Tunneller Server before attempting to retry the request. This value
must be an integer between 1 and 65535. The default value is 10 seconds.

13
Matrikon OPC Tunneller User's Manual

Retries The retries field defines the total number of request retries to make before
giving up on a request and logging a failure. A retry is only made if a request
times out.

3.2.1.2 DOWNLOADING AND REGISTERING TUNNELLED SERVERS


Once all four parameters are correctly filled in, click on the “Connect & Download Configuration”
button. This will initiate a connection with the OPC Tunneller Server, download the entire list of remote
OPC program IDs, and register them locally as “emulated” OPC Servers. If the download was successful,
the list of “emulated” OPC Servers should then appear in the main tree view window of the Client
Configuration Utility (shown below).

Figure 10 – Locally “Tunnelled” OPC Server List

Every downloaded OPC Server program ID will have a new, locally “emulated” program ID to
use. Program Ids generated by the OPC Tunneller Configuration Client have the following
syntax:
Tunneller:<remote hostname>:<original OPC Server program ID>

3.2.1.3 VIEWING AND UPDATING A REMOTE COMPUTER CONNECTION

14
Matrikon OPC Tunneller User's Manual

Figure 6:Tunnelled remote computer connection configuration


The remote server port number can be changed by selecting the appropriate remote connection computer
node, changing the appropriate configuration parameter and pressing the apply button.

3.2.1.4 VIEWING AND UPDATING A TUNNELLED SERVER


CONFIGURATION
By default, each “emulated” program ID is saved locally with a copy of the configuration
parameters specified in the Remote Server Configuration Panel (see Figure 9). To view this
information, highlight one of the program Ids in the Client Configuration Utility (shown below).
Any of these four parameters can be changed without affecting the other locally emulated
servers.

15
Matrikon OPC Tunneller User's Manual

Figure 11 – “Tunnelled” OPC Server configuration

To change any of a Tunnelled Server’s configuration parameters, enter the new value in the
configuration panel as shown above and click the “Update” button to save it.

3.2.1.5 UNREGISTERING TUNNELLED SERVERS


A single Tunnelled OPC Server can be removed from the computer by selecting the Server from
the Client Configuration Utility screen and clicking the “Unregister” button or by selecting
“Unregister Selected Server” from Options Menu. To unregister all of the Tunnelled Servers,
select “Unregister All” from the Options Menu or press the “Unregister All” button(see below).

Figure 12 –Configuration Utility Options Menu

Figure 7: Un-register selected server button

16
Matrikon OPC Tunneller User's Manual

Figure 8: Un-register all servers button

4. UNINSTALLATION
To uninstall OPC Tunneller, run the unwise.exe program located in the OPC Tunneller install directory
on both the remote and local machines. This will ensure all installed components have been removed.

17

You might also like