AVEVA PI

Riferimento del driver AVEVA PI - la PI Web API in HTTPS, autenticazione con token o Basic, indirizzamento AF e per punto PI, letture e scritture.

Il driver AVEVA PI legge e scrive un AVEVA PI System attraverso la PI Web API, l'interfaccia REST del sistema (JSON su HTTP). È un driver in modo client, cioè è Ganter Lab a collegarsi al servizio PI Web API, e il trasporto è HTTPS per impostazione predefinita: il driver mette le credenziali del dispositivo su ogni richiesta che fa, quindi una connessione non cifrata le pubblicherebbe. L'HTTP in chiaro esiste solo come scelta esplicita per il singolo dispositivo.

Un tag indirizza un attributo AF, un punto PI oppure uno stream grezzo della PI Web API, e ne legge il valore istantaneo, cioè quello corrente.

Campi di connessione

Alla connessione il driver verifica la radice del servizio (HEAD, ripiegando su GET). In HTTPS il certificato TLS del servizio viene accettato quando Windows lo considera attendibile, o quando è stato approvato proprio quel certificato in Accesso delle apparecchiature, nella pagina di questo driver. L'intervallo di interrogazione è configurabile: il valore predefinito del dispositivo (1000 ms) vale per ogni tag che non dichiari il proprio.

Preparare la PI Web API

Il driver accede con nome utente e password tramite HTTP Basic, oppure con un token. La PI Web API arriva con Kerberos come unico metodo di autenticazione, e il driver non parla Kerberos, quindi un servizio appena installato di solito rifiuta la stazione finché sul server della PI Web API non si fa una di queste cose:

Quando il servizio risponde 401 senza offrire Basic, la pagina del dispositivo lo dice, con questi passi, al posto dell'errore in inglese del driver; quando offre Basic e rifiuta l'account che il dispositivo ha inviato, la pagina dice che il nome utente o la password è stato rifiutato e rimanda alla scheda Connessione. Entrambi gli avvisi scompaiono da soli non appena il servizio risponde. Il registro e l'agente leggono gli stessi passi. Un token che il servizio rifiuta è detto con le parole del driver stesso.

Indirizzamento dei tag

Il campo Percorso PI del tag accetta quattro forme:

Le ricerche di percorso vengono tenute in cache per 12 ore, così l'interrogazione a regime non le ripete. Per le prime tre forme la lettura esegue una GET sul valore istantaneo dello stream (streams/{webId}/value) ed estrae il campo JSON Value; un URL relativo viene letto alla lettera, quindi puntalo a un endpoint che risponda con un documento di valore. Il risultato viene convertito nel tipo di dato dichiarato dal tag.

Insieme al campione si legge il giudizio proprio dell'archivio. Un valore che l'archivio marca come non buono, come dubbio oppure come sostituito (un numero inserito a mano invece che misurato) non è una lettura dell'apparecchiatura, quindi non viene pubblicato come tale: il tag passa a cattiva qualità e il motivo dice quale dei tre casi fosse. Lo stesso succede quando la risposta non porta alcun valore, oppure risponde con uno stato digitale invece che con un valore singolo, e in quel caso il nome dello stato fa parte del motivo. Al loro posto non viene inventato nulla, e nessun documento arriva come se fosse la misura.

Una lettura che la PI Web API rifiuta (uno stato fuori dall'intervallo di successo, come un account senza accesso in lettura al punto) passa anch'essa a cattiva qualità, e il motivo nomina lo stato e quello che il servizio ha detto insieme a esso (HTTP 403 Forbidden: …). Un percorso che il servizio non conosce lo dice, nominando il percorso. Un indirizzo vuoto, un indirizzo in nessuna delle quattro forme e una risposta che non si legge come il tipo dichiarato danno anch'essi il motivo. Un servizio che non risponde affatto è la connessione del dispositivo che fallisce: il dispositivo lo segnala e si riconnette, e i suoi tag rimandano a esso.

Esempi:

• \\PI-SRV01\FURNACE.TEMP: un classico punto PI.
• \\AF-SRV\Plant\Line 3\Furnace|Temperature: un attributo AF.
• streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value: un URL di stream grezzo, utile quando si ha già il WebId da un altro strumento.

Scritture

I tag con una modalità di accesso scrivibile scrivono attraverso l'endpoint di stream della PI Web API: una POST di {"Timestamp":"*","Value":…} (la marca temporale * significa adesso) su streams/{webId}/value. La scrittura ha bisogno di un WebId risolvibile, quindi funziona per i tag indirizzati per percorso AF, per percorso di punto PI, per WebId e anche per un URL relativo streams/…: il WebId viene letto da quell'URL e la scrittura arriva sull'endpoint di valore di quello stream, qualunque sotto-risorsa di lettura (per esempio recorded) l'indirizzo portasse oltre. Tre forme relative vengono rifiutate, perché ciascuna risponde con un documento invece che con il valore di un solo stream e una scrittura indirizzerebbe la risorsa sbagliata: streamsets/…, attributes?… e points?…. Il rifiuto nomina le forme accettate. Che la scrittura arrivi dipende poi anche dal fatto che la PI Web API sia configurata per le scritture e che l'account abbia accesso in scrittura al punto. Una scrittura che la PI Web API rifiuta riceve come risposta lo stato e quello che il servizio ha detto insieme a esso (per esempio HTTP 403 Forbidden: …), e chi ha scritto il valore ne legge il motivo.

Il valore che scrivi nella casella di scrittura del tag è il valore ingegneristico; le fasi di conversione del tag vengono percorse all'indietro prima che il valore grezzo vada sul bus, come è descritto nella pagina Connector.

Tipi di dato supportati

Boolean, Int32, Int64, Float, Double e String. I punti PI numerici sono di solito Float o Double. Uno stato digitale non è un valore singolo, quindi un punto che risponde con uno si legge come cattiva qualità nominando lo stato, qualunque tipo il tag dichiari.

Comandi

Oltre a leggere e scrivere punti, a un endpoint della PI Web API si può chiedere di fare qualcosa, e quali richieste accetti è affare del servizio stesso. Ognuno si dichiara sul dispositivo, nella scheda Comandi della sua pagina: un nome, l'URL relativo a cui viene inviato con una POST sotto la radice del servizio e, facoltativamente, il nome dell'unico valore che accetta, che viaggia come corpo della richiesta. Il verbo Invia della riga lo manda e riferisce quello che il servizio ha risposto; il comando diventa anche un metodo sul dispositivo nello spazio degli indirizzi OPC UA proprio di questa stazione. Una richiesta che il servizio rifiuta riceve come risposta lo stato e quello che il servizio ha detto insieme a esso, con le stesse parole di una scrittura rifiutata.

Rilevamento

Il pulsante Rileva legge un solo servizio. Metti il suo indirizzo e l'elemento AF da cui parte il percorso nella scheda Ambito della scansione della pagina del driver, separati da un #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. La scansione risolve quell'elemento, percorre ogni elemento sotto di lui e offre il dispositivo con un punto per ogni attributo, ciascuno indirizzato dal proprio stream. La scansione legge il servizio senza credenziali, perché gira prima che esista il dispositivo che le porterebbe, quindi una PI Web API che autentica ogni richiesta non risponde nulla e il dispositivo va aggiunto a mano: aggiungi il servizio per host e aggiungi i tag con i loro percorsi AF o PI, come descrive il flusso per aggiungere un dispositivo nella pagina Connector.

La pagina di un dispositivo PI non mostra Rileva tag: il percorso parte da un elemento AF, che il dispositivo non tiene, quindi i punti di un dispositivo vengono da questa scansione o si aggiungono a mano (vedere Rilevare i tag di un dispositivo).

Accesso delle apparecchiature

Una PI Web API la cui porta non ha alcun certificato assegnato crea e usa un proprio certificato autofirmato, di cui nessuna radice installata in Windows si fa garante. Non serve installare quella radice su questo computer. La prima connessione viene rifiutata, il dispositivo legge In attesa dell'approvazione del certificato nell'albero e nella sua pagina, il cui pulsante Verifica il certificato apre questa scheda sul certificato, e il certificato attende in Accesso delle apparecchiature, alla fine della pagina del driver AVEVA PI, la stessa scheda che porta la pagina del driver OPC UA, finché non si decide:

Verificare l'impronta con chi gestisce il server PI prima di approvare il certificato. Un'approvazione accetta quel certificato e nessun altro, e solo entro le sue date di validità; sostituisce la radice che manca a Windows e il nome che il certificato porta, così una PI Web API chiamata con il suo indirizzo IP si collega anche se il suo certificato porta un altro nome, e nient'altro del certificato viene allentato. Quando l'apparecchiatura risponde a un indirizzo di cui era stato approvato il certificato con un altro (un certificato rinnovato, un altro certificato associato alla porta), la lettura si ferma, il nuovo attende qui e la stazione segnala « Certificato cambiato: <nome> » con un pulsante Verifica. Un certificato che Windows considera già attendibile viene accettato come prima e non compare mai qui; nulla viene approvato automaticamente.

L'errore del driver stesso dice il motivo invece di un errore TLS senza nome: « Il certificato di questa apparecchiatura (i primi 16 caratteri dell'impronta) attende la vostra approvazione in Accesso delle apparecchiature, nella pagina del driver AVEVA PI. La lettura inizia appena lo approvate. » Uno bloccato dice « …è bloccato in questa stazione. Verificarlo in Accesso delle apparecchiature, nella pagina del driver AVEVA PI. » Un certificato fuori dalle sue date di validità, revocato o con la firma non valida viene rifiutato con quel motivo e non viene mai elencato, perché nessuna approvazione lo rende valido. Una scansione del servizio dalla scheda Ambito della scansione incontra le stesse decisioni: un certificato sconosciuto termina la scansione con quella frase e attende qui.

Le decisioni sono conservate nella cartella dati della stazione, in ua\pki\aveva-pi, e sopravvivono a un riavvio. I verbi vengono disegnati solo per un ruolo che può configurare il Connector, e agiscono solo nella finestra della stazione stessa: un browser su un altro dispositivo legge la scheda senza cambiarla, e nessuno strumento di agente approva un certificato (connector_browse segnala il dispositivo in attesa con awaitingCertificate). L'elenco tiene fino a 100 certificati in attesa di approvazione; quando è pieno, uno nuovo viene ancora rifiutato ma non elencato, e la scheda lo dice.