AVEVA PI

Referenz zum Treiber AVEVA PI: PI Web API über HTTPS, Anmeldung über Bearer-Token oder Basic, Adressierung über AF- und PI-Punkte, Lesen und Schreiben.

Der Treiber AVEVA PI liest und schreibt ein AVEVA PI System über die PI Web API, die REST-Schnittstelle dieses Systems (JSON über HTTP). Er ist ein Treiber im Client-Betrieb, Ganter Lab verbindet sich mit dem Dienst PI Web API, und der Übertragungsweg ist standardmäßig HTTPS: Der Treiber legt die Anmeldedaten des Geräts jeder Anfrage bei, eine unverschlüsselte Verbindung würde sie also veröffentlichen. Einfaches HTTP gibt es nur als ausdrückliche Wahl je Gerät.

Ein Tag adressiert ein AF-Attribut, einen PI-Punkt oder einen rohen Datenstrom der PI Web API und liest dessen Momentanwert (snapshot).

Verbindungsfelder

Beim Verbinden prüft der Treiber die Wurzel des Dienstes (HEAD, mit Ausweichen auf GET). Über HTTPS wird das TLS-Zertifikat des Dienstes angenommen, wenn Windows ihm vertraut oder wenn Sie genau dieses Zertifikat unter Anlagenzugriff auf der Seite dieses Treibers freigegeben haben. Das Abfrageintervall ist einstellbar: Der Standard des Geräts (1000 ms) gilt für jedes Tag, das keinen eigenen nennt.

PI Web API vorbereiten

Der Treiber meldet sich mit Benutzername und Passwort über HTTP Basic an oder mit einem Bearer-Token. Die PI Web API kommt mit Kerberos als einziger Authentifizierungsmethode, und der Treiber spricht kein Kerberos. Ein frisch installierter Dienst weist die Station deshalb meist ab, bis auf dem Server der PI Web API einer dieser Wege eingerichtet ist:

Antwortet der Dienst mit 401, ohne Basic anzubieten, sagt die Seite des Geräts das mit diesen Schritten, anstelle des englischen Fehlers des Treibers; bietet er Basic an und weist das Konto ab, das das Gerät gesendet hat, sagt die Seite, dass Benutzername oder Passwort abgelehnt wurden, und verweist auf die Karte Verbindung. Jeder dieser Hinweise verschwindet von selbst, sobald der Dienst antwortet. Das Protokoll und der Agent lesen dieselben Schritte. Ein Bearer-Token, das der Dienst ablehnt, wird mit den eigenen Worten des Treibers gesagt.

Adressierung der Tags

Das Feld PI-Pfad des Tags nimmt vier Formen an:

Nachschlagevorgänge für Pfade werden 12 Stunden zwischengespeichert, das zyklische Lesen im eingeschwungenen Zustand wiederholt sie also nicht. Bei den ersten drei Formen holt der Lesevorgang per GET den Momentanwert des Datenstroms (streams/{webId}/value) und entnimmt das JSON-Feld Value; eine relative URL wird wortgetreu gelesen, richten Sie sie also auf einen Endpunkt, der mit einem Wertdokument antwortet. Das Ergebnis wird in den erklärten Datentyp des Tags gewandelt.

Das eigene Urteil des Archivs über den Abtastwert wird mitgelesen. Ein Wert, den das Archiv als nicht gut, als fraglich oder als ersetzt kennzeichnet (eine von Hand eingetragene statt gemessene Zahl), ist kein Messwert der Anlage und wird deshalb auch nicht als solcher veröffentlicht: Das Tag geht auf schlechte Qualität, und der Grund sagt, welcher der drei Fälle es war. Dasselbe geschieht, wenn die Antwort keinen Wert trägt oder mit einem digitalen Zustand statt eines einzelnen Werts antwortet, wobei dann der Name des Zustands Teil des Grundes ist. An ihrer Stelle wird nichts erfunden, und kein Dokument kommt an, als wäre es die Messung.

Ein Lesevorgang, den die PI Web API ablehnt (ein Status außerhalb des Erfolgsbereichs, etwa ein Konto ohne Leserecht am Punkt), geht ebenfalls auf schlechte Qualität, und der Grund nennt den Status und das, was der Dienst dazu gesagt hat (HTTP 403 Forbidden: …). Ein Pfad, den der Dienst nicht kennt, sagt das und nennt den Pfad. Eine leere Adresse, eine Adresse in keiner der vier Formen und eine Antwort, die sich nicht als der erklärte Typ lesen lässt, geben den Grund ebenfalls an. Ein Dienst, der gar nicht antwortet, ist die Verbindung des Geräts, die ausfällt: Das Gerät meldet es und verbindet sich neu, und seine Tags verweisen auf das Gerät.

Beispiele:

• \\PI-SRV01\FURNACE.TEMP: ein klassischer PI-Punkt.
• \\AF-SRV\Plant\Line 3\Furnace|Temperature: ein AF-Attribut.
• streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value: eine rohe URL eines Datenstroms, nützlich, wenn Sie die WebId schon aus einem anderen Werkzeug haben.

Schreiben

Tags mit einer schreibbaren Zugriffsart schreiben über den Endpunkt für Datenströme der PI Web API: ein POST von {"Timestamp":"*","Value":…} (der Zeitstempel * bedeutet jetzt) an streams/{webId}/value. Der Schreibvorgang braucht eine auflösbare WebId, er funktioniert also für Tags, die über einen AF-Pfad, einen PI-Punktpfad, eine WebId und ebenso über eine relative URL streams/… adressiert sind: Die WebId wird aus dieser URL gelesen, und der Schreibvorgang landet am Wert-Endpunkt dieses Datenstroms, gleich welche Unterressource für das Lesen (etwa recorded) die Adresse dahinter trug. Drei relative Formen werden abgelehnt, weil jede mit einem Dokument statt mit dem Wert eines Datenstroms antwortet und ein Schreibvorgang die falsche Ressource adressieren würde: streamsets/…, attributes?… und points?…. Die Ablehnung nennt die angenommenen Formen. Ob der Schreibvorgang ankommt, hängt außerdem davon ab, dass die PI Web API für Schreibvorgänge eingerichtet ist und das Konto Schreibrecht am Punkt hat. Ein Schreibvorgang, den die PI Web API ablehnt, wird mit dem Status und dem beantwortet, was der Dienst dazu gesagt hat (etwa HTTP 403 Forbidden: …), und wer den Wert geschrieben hat, liest den Grund.

Der Wert, den Sie in das Schreibfeld des Tags tippen, ist der technische Wert; die Umrechnungsstufen des Tags werden rückwärts durchlaufen, bevor der Rohwert auf den Bus geht, wie auf der Seite Connector beschrieben.

Unterstützte Datentypen

Boolean, Int32, Int64, Float, Double und String. Numerische PI-Punkte sind üblicherweise Float oder Double. Ein digitaler Zustand ist kein einzelner Wert, ein Punkt, der mit einem antwortet, liest also schlechte Qualität und nennt den Zustand, gleich welchen Typ das Tag erklärt.

Befehle

Über das Lesen und Schreiben von Punkten hinaus lässt sich ein Endpunkt der PI Web API bitten, etwas zu tun, und welche Anfragen er annimmt, ist die Sache des Dienstes selbst. Erklären Sie jede am Gerät, auf der Karte Befehle seiner Seite: einen Namen, die relative URL, an die sie unter der Wurzel des Dienstes per POST gesendet wird, und wahlweise den Namen des einen Werts, den sie nimmt und der als Rumpf der Anfrage mitreist. Der Befehl Ausführen in der Zeile sendet sie und meldet, was der Dienst geantwortet hat; der Befehl wird außerdem zu einer Methode am Gerät im eigenen OPC UA-Adressraum dieser Station. Eine Anfrage, die der Dienst ablehnt, wird mit dem Status und dem beantwortet, was der Dienst dazu gesagt hat, in denselben Worten wie bei einem abgelehnten Schreibvorgang.

Gerätesuche

Die Schaltfläche Geräte suchen liest einen Dienst. Tragen Sie seine Adresse und das AF-Element, bei dem der Durchlauf beginnt, auf der Karte Suchbereich auf der Seite des Treibers ein, getrennt durch ein #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. Der Suchlauf löst dieses Element auf, durchläuft jedes Element darunter und bietet das Gerät mit einem Punkt je Attribut an, jeder über seinen eigenen Datenstrom adressiert. Der Suchlauf liest den Dienst ohne Anmeldedaten, weil er läuft, bevor es das Gerät gibt, das sie hielte, eine PI Web API, die jede Anfrage anmeldepflichtig macht, antwortet also nichts, und das Gerät wird stattdessen von Hand angelegt: Legen Sie den Dienst über seinen Host an und die Tags über ihre AF- oder PI-Pfade, wie es der Ablauf zum Hinzufügen eines Geräts auf der Seite Connector beschreibt.

Die Seite eines PI-Geräts zeigt kein Tags suchen: Der Durchlauf beginnt an einem AF-Element, das das Gerät nicht hält, deshalb kommen die Punkte eines Geräts aus diesem Suchlauf oder werden von Hand angelegt (siehe Die Tags eines Geräts suchen).

Anlagenzugriff

Eine PI Web API, deren Port kein Zertifikat zugewiesen ist, erzeugt und verwendet ein eigenes selbstsigniertes Zertifikat, für das keine in Windows installierte Wurzel bürgt. Diese Wurzel muss auf diesem Rechner nicht installiert werden. Die erste Verbindung wird abgewiesen, das Gerät zeigt im Baum und auf seiner Seite Wartet auf Freigabe des Zertifikats, deren Schaltfläche Zertifikat prüfen diese Karte auf dem Zertifikat öffnet, und das Zertifikat wartet unter Anlagenzugriff am Ende der Seite des AVEVA PI-Treibers, derselben Karte wie auf der Seite des OPC UA-Treibers, bis Sie entscheiden:

Prüfen Sie den Fingerabdruck mit derjenigen Person, die den PI-Server betreut, bevor Sie das Zertifikat freigeben. Eine Freigabe nimmt genau dieses Zertifikat an und kein anderes, und nur innerhalb seiner Gültigkeitsdaten; sie steht für die Wurzel ein, die Windows fehlt, und für den Namen, den das Zertifikat trägt, sodass sich eine PI Web API, die über ihre IP-Adresse angewählt wird, verbindet, obwohl sein Zertifikat einen anderen Namen trägt, und sonst wird am Zertifikat nichts gelockert. Antwortet die Anlage an einer Adresse, deren Zertifikat Sie freigegeben haben, mit einem anderen (ein erneuertes Zertifikat, ein anderes an den Port gebundenes Zertifikat), hört das Lesen auf, das neue wartet hier, und die Station meldet "Zertifikat geändert: <Name>" mit einer Schaltfläche Prüfen. Ein Zertifikat, dem Windows bereits vertraut, wird wie bisher angenommen und erscheint hier nie; nichts wird automatisch freigegeben.

Der eigene Fehlschlag des Treibers nennt den Grund statt eines namenlosen TLS-Fehlers: "Das Zertifikat dieser Anlage (die ersten 16 Zeichen des Fingerabdrucks) wartet unter Anlagenzugriff auf der Seite des AVEVA PI-Treibers auf Ihre Freigabe. Das Lesen beginnt, sobald Sie es freigeben." Ein gesperrtes liest "…ist an dieser Station gesperrt. Prüfen Sie es unter Anlagenzugriff auf der Seite des AVEVA PI-Treibers." Ein Zertifikat außerhalb seiner Gültigkeitsdaten, widerrufen oder mit gebrochener Signatur wird mit diesem Grund abgewiesen und nie aufgeführt, weil keine Freigabe es einwandfrei macht. Eine Gerätesuche auf dem Dienst über die Karte Suchbereich trifft auf dieselben Entscheidungen: Ein unbekanntes Zertifikat beendet die Suche mit diesem Satz und wartet hier.

Die Entscheidungen liegen im Datenordner der Station unter ua\pki\aveva-pi und überstehen einen Neustart. Die Befehle werden nur einer Rolle gezeichnet, die den Connector konfigurieren darf, und sie wirken nur im eigenen Fenster der Station: Ein Browser auf einem anderen Gerät liest die Karte, ohne sie zu ändern, und kein Werkzeug eines Agenten gibt ein Zertifikat frei (connector_browse meldet das wartende Gerät mit awaitingCertificate). Die Liste hält bis zu 100 Zertifikate, die auf Freigabe warten; ist sie voll, wird ein neues weiter abgewiesen, aber nicht aufgeführt, und die Karte sagt das.