PI System AF SDK Connector

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.

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

The Intelligence Hub communicates with the agent over a secure websocket (wss) connection that requires a TLS certificate. To use a self-signed certificate and private key run the following command to install it into the LocalMachine\Personal certificate store. Certificate installation must be performed with an account that has Administrator permissions. The installation process grants the Current User, Local System account, and Administrators read access to the certificate and private key. Non-admin users that need to run the agent interactively will need to be granted read permission to the certificate’s private key. This can be managed using the Windows Certificate Store by right-clicking the certificate, choosing All Tasks > Manage Private Keys.

intelligencehub-osisoft.exe -installcert

By default the agent will use the self-signed certificate and private key. The self-signed certificate will expire after 5 years. The tool outputs information about the certificate as well as the user that was granted access to the certificate private key. Access to the private key is required in interactive and service mode.

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

installutil intelligencehub-osisoft.exe

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

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.

{
	"port": 45290,
	"token": "randomtoken",
	"subjectName": "HighByte PI Agent",
    "settings": {
        "piServer": "optionalNonDefaultPiArchiveName",
        "piSystem": "optionalNonDefaultPiAFSystemName"
    }
}

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, unless the settings.piServer or settings.piSystem override this.

To use a custom certificate/private key, import the key pair into LocalMachine\Personal certificate store and grant read permission to the imported private key. Permissions for the private key can be managed through the certificate store by right-clicking the certificate, choosing All Tasks > Manage Private Keys.

Next, set subjectName in settings.json to match the certificate Subject Common Name. This information can be reviewed by opening the Certificate, choosing the Details tab, and scrolling to the Subject entry.

For example, a certificate with Subject of CN = MyOrgAgentCertificate, update the settings.json to:

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

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 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>