This guide shows how to deploy and configure the AVEVA PI Connector v0.2.0 and verify that PI data is flowing into the Tetra Data Lake. The connector supports two deployment modes: Windows MSI (runs as a Windows service) and Hub or Cloud (runs as a container on a Tetra Hub or in the Tetra cloud).

Choose a Deployment Mode

Jump to your deployment mode:

• Hub or Cloud deployment
• Windows MSI deployment

The Configure PI Settings in Tetra step and everything after it applies to both deployment modes.

Hub or Cloud Deployment

Prerequisites

Network Requirements

The connector connects to your PI Web API server over HTTPS (port 443):

• Hub deployment: the Tetra Hub must have outbound HTTPS access to the PI Web API server.
• Cloud deployment: the PI Web API server must accept HTTPS connections from the Tetra cloud. Because most PI servers are on premises, a Hub deployment is usually the better fit.

PI Prerequisites

• PI Web API must be installed and accessible over HTTPS from the connector's host.
• The PI user account must have read access to the PI Asset Framework (AF) database you want to poll.
• SSL certificates: select Verify SSL Certificates to verify the PI Web API certificate (recommended for production). If the certificate is self-signed or issued by a private certificate authority, first upload it to Tetra, then restart the connector. Clear Verify SSL Certificates only in development and test environments.

Deploy the Connector

Create the connector by following Create a Pluggable Connector:

1. In the Tetra UI, open the Connectors page and choose Create Connector.
2. For HOST, select Hub and choose your Hub, or select Cloud.
3. For CONNECTOR TYPE, select AVEVA PI. For CONNECTOR VERSION, select v0.2.0.
4. Choose Create.
5. On the connector's details page, select Set to Running.

Once deployed, proceed to Configure PI Settings in Tetra.

📘

NOTE

The Hub or Cloud deployment supports basic authentication only. If you need Kerberos authentication to PI Web API, use the Windows MSI deployment instead.

Windows MSI Deployment

🚧

IMPORTANT

You must have local Administrator rights on the Windows host to install and configure the connector.

Step 1: Complete the Prerequisites

Hardware and Software Requirements

The following requirements are based on the connector's test environment (AWS t3.medium: 2 vCPU / 4 GB RAM). Formal sizing tests have not been performed; your requirements may vary with polling volume and AF hierarchy size.

• OS: Windows Server 2019 or 2022, 64-bit (x86-64). Windows 10 and Windows Server 2016 have not been formally tested and are not validated configurations.
• RAM: 4 GB minimum (validated on t3.medium-class hardware)
• Disk: approximately 500 MB free for the connector installation, plus additional space for log rotation (estimated; not formally measured)
• Domain membership: required for Kerberos authentication; not required for basic authentication

📘

NOTE

No additional runtime is required. The connector bundles all of its dependencies — .NET, Python, and all required libraries are included in the MSI installer.

Network Requirements

The connector requires outbound HTTPS access (port 443) to both your Tetra environment and your PI Web API server. No inbound connections are required.

Tetra Prerequisites

Before running the MSI installer, you must complete the following steps in Tetra:

1. Create a connector of type AVEVA PI in the Tetra UI (open the Connectors page and choose Create Connector).
2. Obtain the Connector ID from the connector's detail page.
3. Generate a Connector Token by navigating to the connector's detail page → Install → Generate Token. Copy the token value — it is shown only once.
4. Download the standalone installer from the connector's Install page. The downloaded archive contains a pre-filled configuration file with your AWS connection parameters (AWS_REGION, DATALAKE_BUCKET, KMS_KEY_ID, OUTBOUND_COMMAND_QUEUE).

📘

NOTE

The standalone installer download is the easiest way to obtain the AWS values. Keep the downloaded file open when you complete Step 3.

PI Prerequisites

• PI Web API must be installed and accessible over HTTPS from the Windows host.
• The PI user account must have read access to the PI Asset Framework (AF) database you want to poll.
• SSL certificates: select Verify SSL Certificates to verify the PI Web API certificate (recommended for production). If the certificate is self-signed or issued by a private certificate authority, first upload it to Tetra, then restart the connector. Clear Verify SSL Certificates only in development and test environments.

Step 2: Install the Connector

Obtain the MSI file (TetraScience.Connector.AVEVA-PI.0.2.0.msi) from TetraScience. Then install the connector using one of the following methods:

Interactive installation

1. Right-click the MSI file and select Properties. On the General tab, click Unblock if the button is present, then click OK.
2. Double-click the MSI file.
3. Accept the UAC elevation prompt when prompted.
4. Follow the guided installation wizard and click Finish when complete.

Silent installation

Open an elevated command prompt (Run as Administrator) and run:

msiexec /i "TetraScience.Connector.AVEVA-PI.0.2.0.msi" /qn

Default installation location

C:\Program Files\TetraScience\AVEVA PI Connector\

After installation, the Windows service TetraScience AVEVA PI Connector is registered and configured to start automatically, but it is not started immediately. Complete the configuration steps before starting the service.

Step 3: Configure the Tetra Connection

The connector reads its Tetra connection settings from a .env file in the installation directory. You must create this file before starting the service.

1. Open an elevated PowerShell window (Run as Administrator).
2. Copy the example file and open it for editing:

cd "C:\Program Files\TetraScience\AVEVA PI Connector"
Copy-Item .env.example .env
notepad .env

3. Fill in the required values using the table below:

📘

NOTE

The AWS values (AWS_REGION, DATALAKE_BUCKET, KMS_KEY_ID, OUTBOUND_COMMAND_QUEUE) are pre-filled in the configuration file included with the standalone installer download from the Tetra UI. If you downloaded that file, you can copy the values from it directly.

4. Save and close the file.

Configure PI Settings in Tetra

📘

NOTE

This step applies to both Windows MSI and Hub or Cloud deployments.

PI configuration is managed through the Tetra UI. Complete this step before starting the connector for the first time.

1. In the Tetra UI, navigate to Connectors and select your AVEVA PI connector.
2. Select Configuration.
3. Set the required fields:

4. Enable at least one data source:

🚧

IMPORTANT

You must enable at least one of the following data sources. Tetra won't save the configuration if none of them is set.

📘

NOTE

Tag Query and AF Element Paths can be used together. If they both resolve to the same underlying PI Point, that tag's data may appear twice in the output under different identifiers. To avoid duplicates, ensure the two modes cover non-overlapping tag sets.

5. Optionally, configure additional fields:

📘

NOTE

If you are using Kerberos authentication, also complete Configure Kerberos Authentication before starting the service.

Configure Kerberos Authentication (Windows MSI Only)

Skip this step if you are using basic authentication or a Hub or Cloud deployment.

The connector uses Windows SSPI for Kerberos — it authenticates to PI Web API as a Windows domain account, using the standard Windows Kerberos ticket infrastructure. No additional Kerberos libraries or keytab files are required.

There are two ways to supply the Kerberos identity:

Option A (recommended): Run the service as a domain service account

The Windows service itself runs under a domain account that has PI Web API read access. This is the most secure option because credentials are managed by Windows and never stored in the Tetra configuration.

1. Work with your PI administrator to create a domain service account (for example, DOMAIN\svc_pi_reader) and grant it read access to PI Web API.
2. Grant the account the Log on as a service right on the Windows host:
   • Open Local Security Policy → Local Policies → User Rights Assignment.
   • Double-click Log on as a service and add the service account.
3. Grant the account write access to the connector's log directory:

# Run as Administrator
icacls "C:\Program Files\TetraScience\AVEVA PI Connector\logs" /grant "DOMAIN\svc_pi_reader:(OI)(CI)M"

4. Configure the Windows service to run as that account. The nssm.exe executable is in the installation directory — use the full path:

# Run as Administrator
& "C:\Program Files\TetraScience\AVEVA PI Connector\nssm.exe" set "TetraScience AVEVA PI Connector" ObjectName "DOMAIN\svc_pi_reader" "password"

Replace DOMAIN\svc_pi_reader and password with your actual service account name and password.

5. Leave PI Web API Username, PI Web API Password, and Windows AD Domain blank in the Tetra configuration UI (the service account identity is used automatically).

📘

NOTE

Service account password rotation: If the service account password expires or is rotated, the connector service will fail to start after the next restart. When you change the password, re-run the nssm.exe set command above with the new password and then restart the service.

Option B: Explicit credentials in Tetra configuration

The service runs as LocalSystem, but explicit domain credentials are passed to PI Web API for Kerberos authentication. Use this option when you cannot change the service account (for example, in tightly managed environments).

1. In the Tetra configuration UI, set Authentication Mode to kerberos.
2. Set PI Web API Username to the domain account username (without the domain prefix).
3. Set PI Web API Password to the account password.
4. Set Windows AD Domain to the AD domain name (for example, CORP).

📘

NOTE

With Option B, the service continues to run as LocalSystem. The explicit credentials are used only for the PI Web API Kerberos exchange.

Start and Verify

Windows MSI: Start the Service

Open an elevated PowerShell window and run:

Start-Service "TetraScience AVEVA PI Connector"

Verify the service is running:

Get-Service "TetraScience AVEVA PI Connector"
# Expected output:
# Status   Name                          DisplayName
# ------   ----                          -----------
# Running  TetraScience AVEVA PI Co...   TetraScience AVEVA PI Connector

Tail the connector log to confirm startup and PI connection:

Get-Content "C:\Program Files\TetraScience\AVEVA PI Connector\logs\connector.stderr.log" -Wait -Tail 50

Look for log lines that confirm the connector has started, connected to Tetra, reached the PI Web API URL, and completed a first polling cycle.

In the Tetra UI, confirm the connector's status shows Running.

Windows Service States

📘

NOTE

If the service enters Paused state immediately after starting, the most common cause is a configuration error. Check connector.stderr.log for details.

Verify Data in Tetra (Both Deployments)

1. Wait for the first polling cycle to complete (default interval: 5 minutes).
2. In Tetra, navigate to Data Lake and search for files uploaded by this connector.
3. Files should appear under the connector's source path in the data lake.

Upgrade from v0.1.0

v0.1.0 is Hub or Cloud only — there is no v0.1.0 MSI. To upgrade, change the connector's version to v0.2.0 by following Edit a Pluggable Connector's Information. Then update the configuration in the Tetra UI as described in Configuration Changes.

📘

NOTE

If the version change option is not available for pre-release versions, contact TetraScience support.

Configuration Changes

🚧

IMPORTANT

In v0.1.0, the connector always polled event frames. In v0.2.0, Enable Event Frame Polling is off by default, and Tetra won't save a configuration that has no data source enabled. To keep collecting event frames after upgrading, select Enable Event Frame Polling when you update the configuration.

Authentication Mode is also new and required in v0.2.0 — there is no default. Set it to basic (or kerberos if you are moving to a Windows MSI deployment with Kerberos authentication).

Version 0.2.0 also renames the following configuration fields. After upgrading, enter your v0.1.0 values in the renamed fields in the Tetra UI:

Upgrade the Windows MSI

To upgrade an existing Windows MSI installation to a newer release:

1. Stop the service:

Stop-Service "TetraScience AVEVA PI Connector"

2. Run the new MSI installer. It installs over the existing installation. Your .env file and logs\ directory are preserved.

3. If you are using Kerberos Option A (service account): the MSI reinstall resets the service identity to LocalSystem. Re-run the nssm.exe set command to restore the domain account:

# Run as Administrator
& "C:\Program Files\TetraScience\AVEVA PI Connector\nssm.exe" set "TetraScience AVEVA PI Connector" ObjectName "DOMAIN\svc_pi_reader" "password"

4. Start the service:

Start-Service "TetraScience AVEVA PI Connector"

Troubleshooting

Next Steps

After the connector is running and data is flowing, you may want to:

• Adjust polling configuration — tune polling_interval, tag_data_lag_minutes, or element_traversal_depth through the Tetra connector configuration UI.
• Backfill historical data — use the RetrieveTagTimeWindowData or RetrieveTimeWindowData custom command to pull data for time windows the connector missed. See Custom Commands.
• Monitor the connector — set up Tetra alerts for files with ERROR status to catch authentication failures and polling errors early.

Custom Commands

Send custom commands with the Create Command endpoint. Set targetId to the connector ID shown on the connector's details page. Both commands take the same time_windows payload and upload the results as one file per window.

Example:

{
  "targetId": "your-connector-id",
  "action": "TetraScience.Connector.PI.RetrieveTagTimeWindowData.v1",
  "expiresAt": "2026-11-01T00:00:00.000Z",
  "payload": {
    "time_windows": [
      {
        "start_time": "2026-10-15T00:00:00Z",
        "end_time": "2026-10-15T23:59:59Z",
        "window_name": "2026-10-15-backfill"
      }
    ]
  }
}

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.