Installation of the PI Bridge

The PI Bridge service should be installed if you wish to create an interface to an AVEVA PI system historian through the History Sink objects.

This page describes the installation and configuration of the PI Bridge service. For information on data pipes and how to use them, please see the DataPipes page.

These are PI Bridge versions available, the recommended version depends on the PI-Server version being used:

  • PI Bridge used for PI-Server 2016+

  • PI Bridge.NET3.5 used for PI-Server 2010

PI Bridge is shipped as a zip archive in the \AspenTech\inmation.root\packages directory when installing AspenTech Inmation OT DataFabric with the setup wizard. The zip files can also be provided by contacting AspenTech Inmation Customer Service.

Requirements

The following software components need to be installed on any computer running PI Bridge:

  • PI Bridge

    • Microsoft .NET Framework 4.8

    • PI AF Client 2018 SP3 Install Kit - Vers. 2.10.9.593

    • PI SDK 2018 Install Kit SP1 - Vers. 1.4.7.618

  • PI Bridge.NET3.5

    • Microsoft .NET Framework 3.5

    • PI SDK Install Kit - Vers. 1.3.6.361 (32-bit)

Installation

The easiest way to install or uninstall the PI Bridge is via the Package Management.
On installation the Configuration String property can be used to specify a JSON string with non-default values for configuration parameters. For available parameters see The PI Bridge Configuration File below.
Here is an example:

{"TCPPortClient":5959,"PIServerName":"PISVR001"}

Manual Installation & Uninstallation

As an alternative to using the Package Management system, the PI Bridge may also be installed and uninstalled manually.

Installation

Locate the PI Bridge zip archive and then do the following:

Copy Files

  1. Create a folder for the files in the Program Files directory of the host machine. For example: "C:\Program Files\PI Bridge". Further in this document this will be referred to as the <PIBRIDGEFOLDER>.

  2. Unzip and copy the files to the new folder

Update Config File

Open the config file ('PI Bridge.exe.config' or 'PI Bridge.NET3.5.exe.config', depending on the version you are installing) in your preferred editor. Find the PiServerName property and enter the correct Host Name for the OSI-Pi Server. Then save the config file and close the editor.

  • There is no need to configure the AVEVA PI Server port (5450). The PI Bridge service already has this information.

  • If an AspenTech Inmation Node is installed on the same host as the AVEVA PI Server, there is no need to open the configured TCPPortClient port (default 5959) in the network policies.

Register as a Windows Service

To register PI Bridge as a Windows service, perform the following steps:

  1. Open command prompt (cmd) as "Administrator"

  2. Run the file "Install.bat" or one of the following commands, depending on the version being installed (correct paths depending on your system):

C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe "<PIBRIDGEFOLDER>\PI Bridge.exe"

or

C:\Windows\Microsoft.NET\Framework\v2.0.50727\InstallUtil.exe "<PIBRIDGEFOLDER>\PI Bridge.NET3.5.exe"

Start Windows Service

The PI Bridge can be started as a Windows service when correctly installed. It can also be started directly by calling the "PI Bridge.exe" file. In this case, the Windows service has to be stopped in advance.

Uninstallation

To deregister PI Bridge as a Windows service, perform the following steps:

  1. Stop the "PI Bridge" Service

  2. Open command prompt (cmd) as "Administrator"

  3. Run the file "Uninstall.bat" or the following command:

C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe /u "<PIBRIDGEFOLDER>\PI Bridge.exe"

or

C:\Windows\Microsoft.NET\Framework\v2.0.50727\InstallUtil.exe /u "<PIBRIDGEFOLDER>\PI Bridge.NET3.5.exe"

The PI Bridge Configuration File

The configuration files for the service can be found in the same directory (either "PI Bridge.exe.config" or "PI Bridge.NET3.5.exe.config" depending on the version being installed)

parameter description default setting

TCPPortClient

TCP port for communication with AspenTech Inmation.

5959

EndOfTransmissionSignal

String that signals the end of a TCP data transmission. ATTENTION! This Value must be the same as in the esi-pibridge.

xEOFx

MaximalBufferSizeToSend

This Value sets the buffersize of the returning json telegram ATTENTION! This Value must be the same as in the esi-pibridge.

2048

MaxTCPConnectionQueues

The maximum length of the pending connections queue.

128

PIServerReconnectTimeSec

Time span (in seconds) in which reconnections to OSIsoft PI servers take place if a connection is lost.

30

PIServerName

Defines the network name of the standard PI server.

""

PIAFServerName

Defines the network name of the PI AF server.

""

PIDataBase

Defines the name of the standard PI AF database.

""

MaxEventToReturn

Defines the maximum count of event frames as result. This is a safety parameter, because payload can be huge.

1000

GetStatistics

performance counter are returned for measuring and benchmarking purpose of PI Bridge.

true

AllowToDelete

Defines if OSIsoft PI Tags can be deleted by the system. This is a security feature, not to lose history data.

true

EndPIBridge

Exit string. If data sent to the Bridge contains this string the Bridge service exits (stops). This string may also be used to exit the program when the Bridge runs as a console: in the console input this string and press enter.

EndPIBridge

SubscriptionMaxItemsCount

Events are buffered by the PI Bridge until they are retrieved by the Node. This is maximum number of events being buffered. If events are coming in faster then being retrieved by the Node and this maximum number is reached, the buffer will overflow and data will be lost.

Default: 100.000

SubscriptionMaxReturnedItemsCount

When retrieving events from the PI Bridge buffer with one of the Lua functions provided (see below), they will be returned as an array. This setting defines the maximum number of events retrieved (=maximum array size returned) with one Lua call.

Default: 10.000

SubscriptionMaxGetEventsIntervalSeconds

Events have to be retrieved from the PI Bridge buffer regularly. Otherwise the corresponding DataPipe will automatically be removed. This setting defines the maximum time in seconds that the buffer and DataPipe will be held in memory without the Node retrieving data.

Default: 60

SubscriptionRefreshRateSeconds

Events have to be fetched by the inmation PI Bridge from the AVEVA PI Server that buffers events itself. This is done periodically in the rate specified by this setting.

Default: 1

Configuring Service Logon Account

The inmation PI Bridge Windows Service will install using the LocalSystem account as the Service Logon account by default. Some PI Historians may require the PI Bridge Service to run as a specific account. Specific account credentials may be provided during install via the Package Manager Configuration String property value or set manually on the system hosting the Bridge.

key value example

username

Windows user name

DOMAIN\\USERNAME

password_clear

password using clear text

123456

password

password encoded using Base64

MTIzNDU2

Example Configuration String property value JSON string:

{
  "username":"DOMAIN\\USERNAME","password_clear":"123456"
}
Upgrade of the PI Bridge package will reinstall the Windows Service and reset the Service Logon account.