Installation of Simatic Batch Bridge

The Simatic Batch Bridge service should be installed if you wish to create an interface to a PCS7 Simatic Batch Server through the Lua API. It uses the Simatic Batch API.

SimaticBatchBridge 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 Simatic Batch Bridge:

  • Microsoft .NET Framework 4.8

  • Simatic PCS7 OS Client for Batch

  • Simatic PCS7 Batch Client

The computer running Simatic Batch Bridge needs to be created as OS-Client in the PCS7 Simatic Manager, and permissions need to be set appropriately.

The API requires a license installation for every project on the SIMATIC BATCH project server. Without an API license, writing operations to the SIMATIC BATCH system will be blocked and an error will be returned.

Installation

The easiest way to install or uninstall the Simatic Batch 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 Simatic Batch Bridge Configuration File below.
Here is an example:

{
    "TCPPortClient":7959,"ApiVersion": 820
}

Manual Installation & Uninstallation

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

Installation

To install the Simatic Batch Bridge manually, locate the SimaticBatchBridge zip archive and complete the following tasks:

Copy Files
  1. Create a folder for the files in the Program Files directory of the host machine. For example: "C:\Program Files\SimaticBatchBridge"

  2. Unzip and copy the files to the new folder

Register as a Windows Service

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

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

  2. Run the following command (including correct paths depending on your system):

C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe "C:\Program Files\SimaticBatchBridge\SimaticBatchBridge.exe"
Start Windows Service

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

Uninstallation

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

  1. Stop the "Simatic Batch Bridge" Service

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

  3. Run the following command (including correct paths depending on your system):

C:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe /u "C:\Program Files\SimaticBatchBridge\SimaticBatchBridge.exe"

The Simatic Batch Bridge Configuration File

The configuration files for the service can be found in the same directory ("SimaticBatchBridge.exe.config")

parameter description default setting

TCPPortClient

TCP port for communication with AspenTech Inmation.

7959

EndOfTransmissionSignal

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

xEOFx

MaximalBufferSizeToSend

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

2048

MaxTCPConnectionQueues

The maximum length of the pending connections queue.

128

EndOfSimaticBatchBridge

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.

EndOfSimaticBridge

ApiVersion

API version used by bridge service. To ensure backwards compatibility with older Batch-Servers, specify earlier version. Available version numbers: 613, 701, 707, 712, 800, 801, 810, 811, 820.

820

Configuring Authentication

The Simatic Batch Bridge Windows Service will install using the LocalSystem account as the Service Logon account by default. Some Simatic Batch deployments may require to use specific user credentials for function calls (SetCurrentUser). 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.

If esi-SimaticBatchBridge function calls are requested with the credentials argument, this will override the configuration file credentials. If no credentials argument is used when calling functions, the configuration file credentials are used.
key value example

UserName

PCS7 user name

Inmation

UserNameLong

Long PCS7 user name

Inmation

Password

Password encoded using Base64

MTIzNDU2

Domain

Computer domain

.

Example Configuration String property value JSON string:

{
    "UserName":"USERNAME","Domain":".", "Password_clear":"123456"
}
Upgrade of the SimaticBatchBridge Package will reinstall the Windows Service and reset the Service Logon account.