AVEVA PI

Reference for the AVEVA PI driver: PI Web API over HTTPS, bearer or Basic authentication, AF and PI point addressing, reads and writes.

The AVEVA PI driver reads and writes an AVEVA PI System through PI Web API, the system's REST interface (JSON over HTTP). It is a client-mode driver (Ganter Lab connects to the PI Web API service), and the transport is HTTPS by default: the driver puts the device's credentials on every request it makes, so an unencrypted connection would publish them. Plain HTTP exists only as an explicit per-device choice.

A tag addresses one AF attribute, one PI point, or a raw PI Web API stream, and reads its snapshot (current) value.

Connection fields

On connect the driver verifies the service root (HEAD, falling back to GET). Over HTTPS, the service's TLS certificate is accepted when Windows trusts it, or when you approved that very certificate under Equipment access on this driver's page. The poll interval is configurable: the device default (1000 ms) applies to every tag that does not state its own.

Prepare PI Web API

The driver signs in with a user name and password over HTTP Basic, or with a bearer token. PI Web API comes with Kerberos as its only authentication method, and the driver does not speak Kerberos, so a newly installed service usually refuses the station until one of these is done on the PI Web API server:

When the service answers 401 without offering Basic, the device's page says so, with these steps, in place of the driver's English error; when it offers Basic and refuses the account the device sent, the page says the user name or the password was refused and points to the Connection card. Either notice goes away by itself once the service answers. The journal and the agent read the same steps. A bearer token the service refuses is said in the driver's own words.

Tag addressing

The tag's PI path field accepts four forms:

Path lookups are cached for 12 hours, so steady-state polling does not repeat them. For the first three forms the read GETs the stream's snapshot value (streams/{webId}/value) and extracts the JSON Value field; a relative URL is read literally, so point it at an endpoint that answers with a value document. The result is converted to the tag's declared data type.

The archive's own verdict on the sample is read with it. A value the archive marks as not good, as questionable, or as substituted (a number entered by hand rather than measured) is not a reading of the equipment, so it is not published as one: the tag goes to bad quality and the reason says which of the three it was. The same happens when the response carries no value, or answers with a digital state rather than a single value, in which case the state's name is part of the reason. Nothing is invented in their place, and no document arrives as if it were the measurement.

A read PI Web API refuses (a status outside the success range, such as an account without read access to the point) reads as bad quality too, and the reason names the status and what the service said with it (HTTP 403 Forbidden: …). A path the service does not know says so, naming the path. An empty address, an address in none of the four forms, and an answer that does not read as the declared type give the reason as well. A service that does not answer at all is the device's connection failing: the device reports it and reconnects, and its tags point to it.

Examples:

• \\PI-SRV01\FURNACE.TEMP: a classic PI point.
• \\AF-SRV\Plant\Line 3\Furnace|Temperature: an AF attribute.
• streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value: a raw stream URL, useful when you already hold the WebId from another tool.

Writes

Tags with a writable access mode write through PI Web API's stream endpoint: a POST of {"Timestamp":"*","Value":…} (timestamp * means now) to streams/{webId}/value. The write needs a resolvable WebId, so it works for tags addressed by AF path, PI point path, WebId, and by a relative streams/… URL as well: the WebId is read out of that URL and the write lands on that stream's value endpoint, whatever read-side sub-resource (recorded, say) the address carried past it. Three relative forms are refused, because each answers with a document rather than with one stream's value and a write would address the wrong resource: streamsets/…, attributes?… and points?…. The refusal names the accepted forms. Whether the write lands also depends on the PI Web API being configured for writes and the account having write access to the point. A write PI Web API refuses is answered with the status and what the service said with it (for instance HTTP 403 Forbidden: …), so whoever wrote the value reads why.

The value you type in the tag's write box is the engineering value; the tag's conversion stages are reversed before the raw value goes on the wire, as described on the Connector page.

Supported data types

Boolean, Int32, Int64, Float, Double and String. Numeric PI points are typically Float or Double. A digital state is not a single value, so a point that answers with one reads as bad quality naming the state, whatever type the tag declares.

Commands

Beyond reading and writing points, a PI Web API endpoint can be asked to do something, and which requests it accepts is the service's own business. Declare each one on the device, in the Commands card of its page: a name, the relative URL it is POSTed to under the service root, and optionally the name of the one value it takes, which travels as the request body. The row's Run verb sends it and reports what the service answered; the command also becomes a method on the device in this station's own OPC UA address space. A request the service refuses is answered with the status and what the service said with it, in the same words as a refused write.

Discovery

The Discover button reads one service. Put its address and the AF element the walk starts from in the driver page's Scan scope card, separated by a #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. The scan resolves that element, walks every element under it, and offers the device with one point per attribute, each addressed by its own stream. The scan reads the service without credentials, because it runs before the device that would hold them exists, so a PI Web API that authenticates every request answers nothing and the device is added by hand instead: add the service by host and add tags by their AF or PI paths, as the add-a-device flow on the Connector page describes.

A PI device's page shows no Discover tags: the walk starts from an AF element, which the device does not hold, so a device's points come from this scan or are added by hand (see Discovering a device's tags).

Equipment access

A PI Web API whose port has no certificate assigned creates and uses a self-signed certificate of its own, which no root installed in Windows vouches for. That root does not need to be installed on this computer. The first connection is refused, the device reads Waiting for certificate approval in the tree and on its page, whose Review certificate button opens this card on the certificate, and the certificate waits under Equipment access at the end of the AVEVA PI driver's page, the same card the OPC UA driver's page carries, until you decide:

Check the fingerprint with whoever manages the PI server before you approve it. An approval accepts that certificate and no other, and only within its validity dates; it stands in for the root Windows lacks and for the name the certificate carries, so a PI Web API dialed by its IP address connects although its certificate names the server, and nothing else about the certificate is relaxed. When the service answers an address whose certificate you approved with another one (a renewed certificate, another certificate bound to the port), reading stops, the new one waits here, and the station raises "Certificate changed: <name>" with a Review button. A certificate Windows already trusts is accepted as before and never appears here; nothing is approved automatically.

The driver's own failure says the reason instead of a nameless TLS error: "This equipment's certificate (the first 16 characters of the fingerprint) is waiting for your approval under Equipment access on the AVEVA PI driver's page. Reading starts once you approve it." A blocked one reads "…is blocked at this station. Review it under Equipment access on the AVEVA PI driver's page." A certificate outside its validity dates, revoked or with a broken signature is refused with that reason and is never listed, since no approval makes it sound. A scan of the service from the Scan scope card meets the same decisions: an unknown certificate ends the scan with that sentence and waits here.

The decisions are kept in the station's data folder, under ua\pki\aveva-pi, and survive a restart. Only a role that may configure the Connector is drawn the verbs, and they act only in the station's own window: a browser on another device reads the card without changing it, and no agent tool approves a certificate (connector_browse reports the waiting device with awaitingCertificate). The list holds up to 100 certificates waiting for approval; once it is full, a new one is still refused but not listed, and the card says so.