OSIsoft PI Adapter

Connect Conduit to OSIsoft PI Data Archive and PI AF using PI Web API for historical and real-time data access.

OSIsoft PI Adapter

The OSIsoft PI adapter connects Conduit to PI Data Archive and PI Asset Framework (AF) using the PI Web API.

Overview

The PI adapter provides:

  • PI Web API Integration: REST-based access to PI data
  • AF Hierarchy Support: Navigate and query PI AF element structures
  • Historical Queries: Recorded, interpolated, and summary data
  • WebId Caching: Performance optimization for repeated queries

Prerequisites

  1. PI Data Archive: Version 2016 or later
  2. PI Web API: Version 2017 or later, configured and accessible
  3. PI AF Server: (Optional) For asset framework queries
  4. Authentication: Kerberos, Basic, or Bearer token configured

Configuration

Basic Configuration

adapter:
  type: osisoft-pi
  name: pi-corporate

  webapi:
    baseUrl: https://pi-webapi.company.com/piwebapi
    authentication:
      type: basic
      username: ${PI_USER}
      password: ${PI_PASS}

  dataArchive:
    name: PI-DA-01
    defaultQueryMode: recorded

  assetFramework:
    enabled: true
    database: Production
    rootElement: Plant/Area1

Authentication Options

Basic Authentication

authentication:
  type: basic
  username: pi_user
  password: ${PI_PASSWORD}

Kerberos (Windows Integrated)

authentication:
  type: kerberos
  spn: HTTP/pi-webapi.company.com

Bearer Token

authentication:
  type: bearer
  token: ${PI_BEARER_TOKEN}

PI Web API Endpoints

The adapter uses these PI Web API endpoints:

| Endpoint | Purpose | |----------|---------| | /points | Tag discovery and metadata | | /streams/{webId}/recorded | Historical recorded values | | /streams/{webId}/interpolated | Interpolated time-series | | /streams/{webId}/summary | Statistical summaries | | /streams/{webId}/value | Current value | | /elements | AF element hierarchy | | /attributes | AF attribute values |

Query Modes

Recorded Values

Returns actual stored values:

queryDefaults:
  mode: recorded
  maxCount: 10000

NQE: "Show temperature for Reactor1 over the last hour"

Interpolated Values

Returns evenly-spaced interpolated values:

queryDefaults:
  mode: interpolated
  interval: 1m

NQE: "Trend temperature for Reactor1 every 5 minutes over the last day"

Summary Values

Returns statistical summaries:

queryDefaults:
  mode: summary
  summaryTypes:
    - Average
    - Minimum
    - Maximum
    - StdDev

NQE: "Show average, min, max temperature for Reactor1 last week"

AF Hierarchy Navigation

Element Path Mapping

Map AF element paths to friendly names:

assetFramework:
  elementMappings:
    "Plant|Area1|Line1": "Production Line 1"
    "Plant|Area1|Line2": "Production Line 2"
    "Plant|Utilities|Cooling": "Cooling System"

Attribute Discovery

assetFramework:
  discovery:
    enabled: true
    startElement: "Plant"
    depth: 5
    attributeCategories:
      - "Process Data"
      - "Equipment Status"

WebId Caching

WebIds are unique identifiers for PI objects. Caching improves performance:

cache:
  webIds:
    enabled: true
    ttl: 86400  # 24 hours
    maxSize: 50000
  metadata:
    enabled: true
    ttl: 3600

Cache Warming

Pre-populate cache on startup:

cache:
  warmup:
    enabled: true
    patterns:
      - "sinusoid*"
      - "Tank*"
      - "Reactor*"

Query Translation

NQE to PI Web API

NQE Query:

Show average temperature for Reactor1 over the last 24 hours by hour

Generated NQE:

Show average temperature by hour during last 24 hours, where tag is Reactor1_Temperature

Translated to PI Web API Request:

GET /streams/{webId}/summary?
  startTime=*-24h&
  endTime=*&
  summaryType=Average&
  summaryDuration=1h

Batch Queries

Optimize performance with batch requests:

batch:
  enabled: true
  maxSize: 100
  parallelRequests: 4

The adapter batches multiple tag queries into single PI Web API batch requests.

Performance Tuning

Connection Settings

webapi:
  timeout: 30000  # ms
  retries: 3
  retryDelay: 1000
  connectionPool:
    maxConnections: 20
    keepAlive: true

Query Optimization

optimizer:
  preferSummary: true        # Use summary endpoint when possible
  interpolateThreshold: 1000 # Switch to interpolated above this
  parallelStreams: 10        # Concurrent stream queries

SSL/TLS Configuration

webapi:
  ssl:
    verify: true
    caCert: /etc/conduit/certs/pi-ca.pem
    clientCert: /etc/conduit/certs/client.pem
    clientKey: /etc/conduit/certs/client.key

Troubleshooting

Authentication Failures

401 Unauthorized

  • Verify credentials are correct
  • Check user has access to PI Web API
  • For Kerberos: verify SPN and ticket validity

403 Forbidden

  • User lacks permissions to specific points/elements
  • Check PI AF security settings

Performance Issues

Slow Queries

  1. Enable WebId caching
  2. Use summary mode for large time ranges
  3. Increase batch size for multi-tag queries
  4. Check PI Archive subsystem load

Timeout Errors

  1. Reduce query time range
  2. Increase timeout setting
  3. Check PI Web API server resources

Data Quality

PI data includes quality flags. Configure quality filtering:

quality:
  filter:
    enabled: true
    minimumQuality: good
    excludeAnnotated: false

Example Deployment

version: '3.8'
services:
  conduit-pi-adapter:
    image: conduit/adapter-osisoft-pi:latest
    environment:
      - CONDUIT_CONTROL_PLANE=mqtt://control-plane:1883
      - PI_WEBAPI_URL=https://pi-webapi:443/piwebapi
      - PI_USER=conduit_service
      - PI_PASS=${PI_PASSWORD}
    volumes:
      - ./config/pi-adapter.yaml:/etc/conduit/adapter.yaml
      - ./certs:/etc/conduit/certs:ro

Next Steps