PI System AF SDK Connector

Jump to Section

The PI System AF SDK Connector uses the PI System AF SDK to communicate with the PI and AF Server. The agent is a .NET application and is delivered separately from the core HighByte Intelligence Hub installation. The requirements for the agent are as follows.

Windows Operating System
The PI System AF SDK/AF Client installed on the system running the agent
Microsoft .NET 4.8 or greater

The agent runs as a standalone application, by running the intelligencehub-osisoft.exe OR as a Windows service. When running standalone, it’s recommended to run the executable with admin level permissions. To install as a service, run the following command. InstallUtil is found in the .NET installation directory: %windir%\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe

bat

installutil intelligencehub-osisoft.exe

To optionally control the service name, using the following syntax.

bat

installutil /serviceName="myServiceName" /displayName="myDisplayName" intelligencehub-osisoft.exe

The agent connects to the AF SDK/AF Client and opens a port to receive requests from the HighByte Intelligence Hub instance. By default, this communication occurs using secure websockets. On the first run the agent creates a self-signed certificate called intelligencehub.pfx as well as a settings.json file. The file contains the following.

json

{
	"port":45290,
	"token": "randomtoken"
}

The port controls the port that the agent listens on. This port must be open and available to the Intelligence Hub connecting to the agent. The token is a random security token created by the agent. This token must be applied to the Intelligence Hub PI System connection settings to authenticate the hub. Any changes to these settings require restarting the agent.

In the Intelligence Hub PI System connection settings, enter the IP/port of the agent, as well as the token. The agent also has a local intelligencehub.log file for debug information. See below on how to enable detailed diagnostics logging.

Note the agent connects to the default PI Archive and Asset Framework system configured by the AF Client using the PI System Explorer.

Diagnostics Logging

The PI Agent includes detailed diagnostics to analyze read and write performance. The agent uses NLog for to control log retention policy and verbosity. To control diagnostics change the intelligencehub-osisoft.exe.config file in the same directory as the intelligencehub-osisoft.exe file.

Add the following configuration to the file, save the file, and restart the agent. Diagnostics logs will be included in the console output and in the log file.

If the agent is running as a Windows Service under a Windows account with access to PI, it must also have local file system access to write the diagnostics file locally. Otherwise, the local log file will not be written.

The default logging configuration is shown below.

xml

<?xml version="1.0" encoding="utf-8"?>
<configuration>
	<configSections>
		<!-- Register NLog as a configuration section -->
		<section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" requirePermission="false" />
	</configSections>
	<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
		  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<!-- Define targets (where logs are written) -->
		<targets>
			<!-- File target 3 files up to 100MB each -->
			<target xsi:type="File"
					name="logfile"
					fileName="intelligencehub.log"
					archiveFileName="intelligencehub.{#}.log"
					archiveNumbering="Rolling"
					archiveAboveSize="104857600"
				maxArchiveFiles="3"
				layout="${date:format=dd-MM-yyyy hh\:mm\:ss} | ${level} | Agent | ${message}" />
			<target xsi:type="Console" name="console" layout="${date:format=dd-MM-yyyy hh\:mm\:ss} | ${level} | Agent | ${message}" />
		</targets>

		<!-- Define rules (what gets logged and where) -->
		<rules>
			<!-- Log all levels to the file -->
			<logger name="*" minlevel="Trace" writeTo="logfile" />
			<logger name="*" minlevel="Trace" writeTo="console" />
		</rules>
	</nlog>
	<startup>
		<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8"/>
	</startup>
</configuration>

Expand Collapse

PostgreSQL