Solutions

DH Historian Agent

13min

Note: This driver is available for Litmus Edge version 3.11.0 and later.

Review the following information for setting up and configuring the OSI Agent driver V2.3.0

Overview

Document image


Before You Begin

  • Verify that the Windows environment runs at least .Net 4.8 or higher
  • Install an OSI Server and OSI Agent on a Windows system.
  • Download the OSI Agent and required files in a ZIP file from the Litmus Central Portal.
  • Make sure the OSI Client dll is on the same system running the OSI Agent.
  • Open port 443 and 4777 between Windows and Litmus Edge. Otherwise, the OSI Agent won't work.
  • Configure Windows authentication so that the OSI Pi Server can work.

Prerequisites

Prerequisites for Device-Hub-Agent deployment:

  1. A machine with at least 16 GB memory.
  2. Windows Workstation OS version 10 or greater
  3. Or Windows Server OS version 2012 or Grater
  4. PiServer 2012 version 3.4.375 or greater Available
  5. “PI User Login Credentials” OR “Windows user login Credentials” of a user that is permitted to connect to PI System and read data.

There are 2 different options to deploy the Device-Hub-Agent.

  1. On the PI Server itself
  2. On a “PI Node” – a separate machine that is connected to PI Server.

Option1: Deployment on the PI Server:

  1. Make sure than Dot Net Framework 4.8 is installed or just install it on the server.
  2. (Download URL: https://dotnet.microsoft.com/en-us/download/dotnet-framework/thank-you/net48-web-installer.)
  3. Unzip the Deployed package into a separate folder.
  4. Run: Device-Hub-Agent.UI.Exe as Administrator.
  5. Fill in all the fields of the configuration tabs.
  6. Start Device-Hub-Agent.Controller.

Option2: Deployment on a PI Node machine.

  1. Make sure than Dot Net Framework 4.8 is installed or just install it on the machine. (Download URL: https://dotnet.microsoft.com/en-us/download/dotnet-framework/thank-you/net48-web-installer.)
  2. Open the Add/Remove Programs and Make sure that the “PI AF Client” is installed. Or else, ask the customer to install it for you.
  3. Click on “Start” -> “PI System” -> “About PI SDK”
  4. Make sure that there is an entry for the PI Server in the connections list or else, just add one with the parameters that you have.
  5. Click the “CheckBox” to test the connection.
  6. Unzip the Deployed package into a separate folder.
  7. Run: Device-Hub-Agent.UI.exe as Administrator.
  8. Fill in all the fields of the configuration tabs.
  9. Start Device-Hub-Agent.Controller.

Tested Platforms:

The Device-Hub-Agent is Tested:

  • # Using: PI AFClient 2018 SP2 Patch 2, Ver: 2.10.99.593 PI system Management Tools 2018 SP3 Patch 1, ver: 3.6.3.65
  • # Using: PI AFClient 2018 SP3 Patch 4, Ver: 2.10.10.2593 PI system Management Tools 2018 SP3 Patch 1, ver: 3.6.3.65

Step 1: Install OSI Agent

Install the ZIP file with the OSI Agent and all required files on a Windows system.

Step

Description

1

Add an OSI Agent Advanced device in Litmus Edge DeviceHub.

Network Port, User and Password, Nats Connection Name fields are required.

2

Unzip the downloaded file.

3

Go to the unzipped folder. From the root folder, open the DH-Historian-Agent folder, then right-click DH-Historian-Agent.UI and select Run as administrator. A Device-Hub Historian Agent application will open.

Step 2: Run and Configure the DH Historian Agent

Use the DH Historian Agent app to configure the DH-Historian-Agent and DeviceHubAgentController :

  1. On the first page, press Next. The page for Theme/Skin/Menus configuration will open.
    1. Document image
      
  2. Press Save, then Next. The PI Server/Operation Mode page will open.
    1. Document image
      
  3. Press Load PI Servers.
    1. Wait for the servers to load, then select the host name of the server you want to connect to. Select between PI user authentication or Windows authentication
    2. Select Polling on tags intervals or Events-Based
    3. Once you have made your selections, press Save, then Next.
    4. The DH-Historian Agent/ WebApi page will open.
    5. Here is some help regarding the terms used:
      • PI User: Open the PI System Management Tool and navigate to Security > PI Users and Groups. Enter the correct username and password.
      • Windows: The PI Server needs to be properly configured to use Windows authentication.
      • Document image
        
  4. In the Host field, enter the IP address of our Litmus Edge Instance. Enter any text in the User and Password and Conn. Name fields and they need to be the same with configuration of OSI Agent Advanced device in Litmus Edge. Sample site settings are as follows:
    • Host: Enter the IP address for the Litmus Edge instance.
    • Port: Enter 4777.
    • User: Enter the username to connect to the server in DeviceHub.
    • Password: Enter the password to connect to the server in DeviceHub.
    • Check Validate against server Certificate (optional)
    • Click ... button and select Certificate file from host Windows machine (Optional, if previous option is checked)
    • Keepalive Packet Interval: Every minute the agent and controller will send keepalive messages. When 3 consecutive messages fail, then the connection with LE will be discarded . The keepalive packet interval can be changed from the default value, which is 60 seconds. If put "0 secs" interval, then the agent/controller will not send keep alive messages. And in such a case it is up to the server side (L.E.) to decide if to keep the opened connection or to drop it.
    • Click TEST CONNECTION button to validate configuration.
    • Press Save, then Next.
    • The Logs page will open.
      1. Document image
        
  5. Check Log file folder and enter any name for the log folder, which will be generated automatically in the same directory.
    1. Press Save, then Next.
    2. The Agent Service and Agent Controller Service page will open.
      1. Document image
        
  6. Create and start both services to make them running.
  7. Press EXIT to leave DH-Historian-Agent.UI
    1. Document image
      
  8. Go to Litmus Edge DeviceHub and confirm the device is connected

OSI Agent Driver Settings in Litmus Edge

If you review or edit the settings of the OSI Agent device, refer to the following parameters.

Parameter

Value

Type

OSI

Driver

OSI Agent Advanced

Network Port

The port configured in the DH Historian Agent. The default value is 4777.

Interface

You have the option of selecting the interface for accepting client connections. The default value is 0.0.0.0, which means using all network interfaces for accepting connections from clients.

User

The username configured in the DH Historian Agent.

Password

The password configured in the DH Historian Agent.

Release Notes

V2.3.0

  • KeepAlive Feature
  • Installed services should be with automatic Start
  • Agent Starts even when TagsList is empty and finding tag name in the tags list

V2.2.0

  • New Feature added to the UI Running on PI Events (Visual Part) Bringing back Events based version Sending of initial values
  • Currently it will only send initial values when the agent is manually restarted, not on DH driver restart
    • When the Driver restarts, the Agent and Controller notice that the TCP Connection was dropped, and they will re-establish it again.
    • All the operations will work as they did before. The only thing that will not happen, is the re-sending of the initial values, and that is simply because if there was no request to do that, the agent can't tell if this disconnection happened due to a slow network or a cable disconnection or any other infrastructural issue.
  • Removed _test project from the compilation in release.
  • Fixed the issue of timestamp was less than the minimum
  • new Icons in UI
  • removing Certificate page. and loading the certificate as a file which support .pem, .crt. and .txt format



Updated 16 Apr 2024
PREVIOUS
Troubleshooting
NEXT
Litmus Access Processors for Apache Nifi
Docs powered by Archbee