PI Vision Scanner

Overview

The PI Vision Scanner is a component of Tycho Data Osprey that connects to your AVEVA PI Vision server to:

Discover PI Vision displays and symbols.
Scan for display data sources such as AF Element Attributes or PI tags.
Upload metadata and lineage information to Tycho Data Osprey.

This scanner enhances Osprey's ability to trace data usage across visualization layers. It complements the PI Asset Framework and Data Archive scanners to build a full picture of sensor lineage, usage, and visibility.

How It Works

Once configured, the scanner connects securely to the PI Vision SQL database and the AF Server. At scheduled intervals, it:

Authenticates to the PI Vision SQL Server using the configured credentials.
Scans PI Vision display and symbol metadata.
Scans AF Server for tag mappings and element references (to resolve any wildcards that might be defined in PI Vision displays).
Uploads results to the Tycho Data Osprey via API.

Collected Information

Data Type	Description
Display Info	PI Vision display metadata (name, owner, last modified, etc.)
Tag References	All PI tags referenced by the symbols, including data paths
AF References	Element and attribute references if symbols are linked to AF
Scan Status	Runtime details, including scanner ID, timestamps, and upload results

PI Vision collections are supported but requires authentication to PI AF Server to resolve configurations containing wildcards (*).

Preflight

Before running the PI Vision Scanner, ensure the following requirements are met:

Network

Port 1433 must be open between the scanner host and the SQL Server hosting the PI Vision database. This is the default port used by SQL Server for client connections.

Service Account

The scanner requires a user account with Read access to the SQL Server database hosting PI Vision (typically named PIVision). For initial setup or testing, an individual user account can be used. For production deployments, a dedicated Windows Service Account is recommended.

See Setting Up a Windows Service Account below for detailed steps on granting the required SQL Server permissions.

Preparing authentication user

Running in Production: Set Up a Windows Service Account

When running the scanner in a production environment, it is recommended to set up a dedicated Windows Service Account. This account can be a domain user or a member of an Active Directory (AD) group. The service account (or group) must be granted sufficient permissions to read from the SQL Server PI Vision database.

Steps to Grant SQL Server Permissions (using SQL Server Management Studio - SSMS):

Open SQL Server Management Studio (SSMS) and connect to the SQL Server instance hosting the PI Vision database.
In the Object Explorer, expand Security > Logins.
Right-click Logins and select New Login...
In the Login name field, enter the service account (e.g., DOMAIN\ServiceAccount) or AD group (e.g., DOMAIN\OspreyScannerUsers).
Under Select a page, click User Mapping.
Check the box for the PI Vision database (e.g., PIVision).
In the Database role membership section, check db_datareader to grant read access.
Click OK to save.

Note: If using Windows Authentication, ensure the service is configured to run as this account.

Enable TCP/IP for SQL Server

If the scanner cannot connect to SQL Server, you may need to enable TCP/IP:

Open SQL Server Configuration Manager.
In the left pane, expand SQL Native Client x.x Configuration and select Client Protocols.
In the right pane, right-click TCP/IP and select Enable.
Restart the SQL Server service for changes to take effect.

Setting Up the Scanner

!!! tip "Recommended: Use the Osprey Scanner Configuration Utility" The easiest way to configure the PI Data Archive scanner is with TychoScannerConfig.exe (Osprey Scanner Configuration Utility). This graphical tool lets you set all parameters, test connectivity, and save your configuration without manually editing any files. It can also generate an API token and register scanners directly with Osprey - so you don't need to log into the Osprey UI to complete those steps. Launch it from the scanner installation directory.

1. Add Scanner in Osprey UI

To set up your PI Vision scanner:

Navigate to Scanners in the Osprey left panel.
Click Add Scanner.
Select PI Vision.
Enter a scanner Name (e.g., Vision - West Plant).
Copy the generated Scanner ID. You'll need this in the configuration file.

2. Update Configuration File

Update the appsettings.ini file on the scanner host at:

C:/Users/<your_user>/Documents/Tycho Data/Osprey/appsettings.ini

A sample file is provided below:

[common]
tychoDataHost = https://tychodata.int/
tychoDataDomainID = 30
tychoDataAPIToken = ${TYCHODATA_OSPREY_APITOKEN}
pathToCert = C:\cert\selfsigned.crt
updateStatus = false
schedule = "*/3 * * * *"

[scan-pivision]
scannerId = c684da15-7777-4a1f-abaf-9f836be37f11
piVisionServer = WIN-N26UUHRC4P9
sqlHost = WIN-N26UUHRC4P9\\MSSQLSERVER
sqlPort = 1433
sqlDatabase = PIVision
sqlUsername = ${PIVisionSQLUser}
sqlPassword = ${PIVisionSQLPassword}
afUser = ${AF_User}
afPassword = ${AF_Password}
performScan = false
upload = true

3. Run Scanner

Once your appsettings.ini is configured and your environment variables are set, you're ready to run the PI Vision scanner.

To run manually via PowerShell:

Open PowerShell
Navigate to the folder containing TychoScanner.exe
Run the scanner with:

.\TychoScanner.exe

The scanner will execute once using the defined configuration. To run it automatically on a schedule, see Automating the Scanner with Task Scheduler.

Configuration File Reference

[common] Section

Key	Description
tychoDataHost	The base URL of your Tycho Data instance (e.g., https://tychodata.int/)
tychoDataDomainID	The numeric ID of the domain this scanner belongs to
tychoDataAPIToken	API token used for authenticating to Tycho Data
pathToCert	Path to the SSL certificate used to verify the scanner's identity
updateStatus	If true, scanner updates run status to Tycho Data
schedule	Cron expression controlling when scans run

[scan-pivision] Section

Key	Description
scannerId	Unique ID assigned by Osprey when you add the scanner
piVisionServer	Hostname of the PI Vision web server
sqlHost	Hostname of the SQL Server used by PI Vision
sqlPort	Port for SQL Server (default is 1433)
sqlDatabase	SQL Server database name for PI Vision (commonly PIVision)
sqlUsername	SQL login username for accessing the database (use env var recommended)
sqlPassword	SQL login password (use env var recommended)
afUser / afPassword	Credentials for connecting to AF Server (use env vars, or AD if configured)
performScan	If true, the scanner will run and collect data
upload	If true, results will be uploaded to Tycho Data

Hint: To scan multiple PI Vision instances, create additional sections using the naming pattern [scan-pivision-<suffix>]. For example:

[scan-pivision-east]
...

[scan-pivision-apac]
...

Troubleshooting

If the scanner is having trouble connecting to SQL Server, you may need to adjust your SQL Server network and security settings to allow client applications to connect.

1. Enable TCP/IP in SQL Server Configuration Manager

Open SQL Server Configuration Manager on the server hosting SQL Server.
In the left pane, expand SQL Server Network Configuration and select Protocols for MSSQLSERVER (or your named instance).
In the right pane, right-click TCP/IP and select Enable.

2. Configure TCP/IP Properties

Still in SQL Server Configuration Manager, right-click TCP/IP and select Properties.
Go to the IP Addresses tab.
For each relevant IP address (e.g., IP1, IP2, IPAll):
Set Active to Yes.
Set Enabled to Yes.
For TCP Port, enter 1433 (the default SQL Server port) if not already set.
Click OK and restart the SQL Server service for changes to take effect.

3. Confirm Authentication and Permissions

Use SQL Server Management Studio (SSMS) to test your connection:
Try connecting with the same SQL credentials or Windows AD user you plan to use for the scanner.
Ensure the user has at least the db_datareader role on the PIVision database.

If you are unsure about these steps or lack the necessary permissions, contact your SQL Server administrator for assistance. Organizational policies may require admin involvement for some changes.