OSIsoft PI System™

Connect to OSIsoft PI System™ for industrial data collection and visualization using OIBus with the embedded PI driver in OIBus Agent.

System Requirements

• OIBus Agent must be installed on a Windows machine
• Can be installed on PI Server machine or separate machine with PI SDK configured

Connection Settings

Setting	Description	Example Value
Remote agent URL	Agent endpoint URL. Required for all connections.	http://192.168.1.100:2224
Retry interval	Time in milliseconds to wait before retrying the connection. Default: 10000.	10000

Group Settings

Items are organised into groups. Each group defines a shared schedule and the default throttling parameters for historical data retrieval.

Setting	Description	Example Value
Name	Unique label for the group within this connector.	Group A
Scan mode	Collection schedule applied to every item in the group.	Every 1 min

Throttling Settings

Throttling controls how OIBus paces historical data requests. These settings appear on each group (for connectors that support groups) or on each item (for single-item connectors). Items in a group can override the group defaults by disabling the Sync with group toggle.

Setting	Description	Example Value
Max read interval	Maximum duration of each sub-query in seconds. Larger time ranges are automatically split into chunks not exceeding this value.	3600
Read delay	Pause in milliseconds between consecutive sub-queries. Helps prevent server overload and manages rate limits.	1000
Start time offset	Milliseconds added to the start of the query window (@StartTime). A negative value moves the start earlier, to capture late-arriving data from the previous interval — this is the old "Overlap" behavior. A positive value moves the start later instead, skipping that much of the window.	-60000
End time offset	Milliseconds added to the end of the query window (@EndTime). A negative value pulls the end in earlier — useful for eventually-consistent sources where the very latest rows aren't reliable yet. A positive value extends the window later. If the resulting end is not after the effective start, the query is skipped for this run.	0
Recovery strategy	Order in which OIBus catches up on a backlog of unqueried sub-intervals — e.g. after being stopped for a while, or on first run against a wide time range. From oldest to newest (default) processes the backlog chronologically. From newest to oldest queries the most recent sub-interval first, so up-to-date values become available immediately while older gaps are backfilled afterward.	From oldest to newest

How Throttling Works

1. Interval splitting — A 24-hour range with Max read interval = 3600 (1 hour) is split into 24 separate 1-hour sub-queries.
2. Read delay — A pause is inserted between sub-queries to manage server load.
3. Start/End time offset — With Start time offset = -60000 (-1 minute), a query for [10:00–11:00] actually requests [9:59–11:00], ensuring no late-arriving data is missed. End time offset shifts the other boundary the same way.
4. Recovery strategy — Only matters when there's more than one sub-interval to catch up on. With From newest to oldest, the tracked instant only advances once every sub-interval in the backlog has been queried — this avoids skipping over not-yet-queried older intervals if OIBus restarts mid-catch-up.

Offsets apply to the full query range

Start/End time offset are applied once, to the start and end of the overall query window — not to the start of each individual sub-interval when a large range is split into chunks by Max read interval.

Recommended Configurations

Scenario	Max read interval	Read delay	Start time offset
Stable network, small datasets	3600 (1 hour)	500	0 (none)
Unstable network	1800 (30 min)	2000	0 (none)
Large historical retrievals	7200 (2 hours)	1000	0 (none)
Real-time with occasional gaps	900 (15 min)	200	-15000 (-15 sec)

Going deeper

For the reasoning behind these numbers — sizing Max read interval against real data volumes, the Read delay / Max read interval trade-off on a large backlog, and worked examples of Start vs. End time offset (including the batched multi-item case where items don't all flush at once) — see Tuning South History Call Settings.

Overriding throttling per item

Each item can override the group throttling defaults by disabling the Sync with group toggle in the item edit form.

Item Configuration

Point Access Methods

Setting	Description	Example Value
Type	Access method: PI point (single point by ID) or PI query (multiple points by query expression)	PI point or PI query
Point ID	Fully qualified point ID (without server name). Used when Type is PI point.	\\CDT158\SINUSOID
Point Query	Query selector for multiple points (see PI Point Query Syntax). Used when Type is PI query.	Name:='SINUSOID'

Reference Names

• For PI point: Item name serves as reference in JSON payloads
• For PI query: PI name is used as reference

OSIsoft PI SDK Configuration

Installation Requirements

1. Install PI SDK on agent machine
2. During installation, specify default data server
3. If installing remotely:

• PI SDK must be properly configured
• PI System Access (PSA) must be installed

User Configuration

1. Create domain user account (accessible from both machines)

• If domain doesn't exist, create identical local users with same password

2. Configure OIBus Agent service to run as this user

Trust Configuration

1. Open PI System Management Tools
2. Navigate to Mapping & Trusts → Trusts tab
3. Create new trust with:

• OIBus Agent machine IP and Net Mask
• Domain (if applicable)
• PI Identity to connect with

Mapping Configuration

1. In PI System Management Tools
2. Navigate to Mapping & Trusts → Mappings tab
3. Create new mapping with:

• OIBus Agent service user
• PI Identity from trust configuration

Log Access

View system logs in PI System Management Tools: Operation → Messages Logs

Configuration Screenshots

1. SDK Installation — Specify default data server during installation

2. Trust Configuration — Configure trust for agent machine

3. Trust List — Verified trust configuration

4. Mapping Creation — Map agent user to PI identity

5. Mapping List — Verified user mapping