AVEVA PI

Referencia del controlador AVEVA PI: PI Web API sobre HTTPS, autenticación por token de portador o Basic, direccionamiento de AF y de puntos PI, lecturas y escrituras.

El controlador AVEVA PI lee y escribe un AVEVA PI System a través de PI Web API, la interfaz REST del sistema (JSON sobre HTTP). Es un controlador en modo cliente (Ganter Lab se conecta al servicio PI Web API) y el transporte es HTTPS de forma predeterminada: el controlador pone las credenciales del dispositivo en cada petición que hace, así que una conexión sin cifrar las publicaría. El HTTP sin cifrar existe solo como una elección explícita por dispositivo.

Un tag direcciona un atributo AF, un punto PI, o un flujo en bruto de PI Web API, y lee su valor instantáneo (el actual).

Campos de conexión

Al conectar, el controlador verifica la raíz del servicio (con HEAD, y recayendo en GET). Sobre HTTPS, el certificado TLS del servicio se acepta cuando Windows confía en él, o cuando usted aprobó ese mismo certificado en Acceso a los equipos, en la página de este controlador. El intervalo de sondeo es configurable: el valor por defecto del dispositivo (1000 ms) se aplica a todo tag que no declare el suyo.

Preparar la PI Web API

El controlador inicia sesión con usuario y contraseña mediante HTTP Basic, o con un token de portador. La PI Web API viene con Kerberos como único método de autenticación, y el controlador no habla Kerberos, así que un servicio recién instalado suele rechazar la estación hasta que se hace una de estas cosas en el servidor de la PI Web API:

Cuando el servicio responde 401 sin ofrecer Basic, la página del dispositivo lo dice, con estos pasos, en lugar del error en inglés del controlador; cuando ofrece Basic y rechaza la cuenta que envió el dispositivo, la página dice que se rechazó el usuario o la contraseña y señala la tarjeta Conexión. Cualquiera de los dos avisos desaparece solo en cuanto el servicio responde. El registro y el agente leen los mismos pasos. Un token de portador que el servicio rechaza se dice con las palabras del propio controlador.

Direccionamiento del tag

El campo Ruta PI del tag acepta cuatro formas:

Las búsquedas de ruta se guardan en caché durante 12 horas, así que el sondeo en régimen permanente no las repite. En las tres primeras formas, la lectura hace GET al valor instantáneo del flujo (streams/{webId}/value) y extrae el campo Value del JSON; una URL relativa se lee literalmente, así que apúntela a un endpoint que responda con un documento de valor. El resultado se convierte al tipo de dato declarado del tag.

El veredicto del propio archivo histórico sobre la muestra se lee con ella. Un valor que el archivo marca como no bueno, como cuestionable o como sustituido (un número introducido a mano en lugar de medido) no es una lectura del equipo, así que no se publica como tal: el tag pasa a mala calidad y el motivo dice cuál de los tres era. Lo mismo pasa cuando la respuesta no lleva ningún valor, o contesta con un estado digital en vez de con un solo valor, y en ese caso el nombre del estado forma parte del motivo. En su lugar no se inventa nada, y ningún documento llega como si fuera la medida.

Una lectura que PI Web API rechaza (un estado fuera del rango de éxito, como una cuenta sin acceso de lectura al punto) también pasa a mala calidad, y el motivo nombra el estado y lo que el servicio dijo con él (HTTP 403 Forbidden: …). Una ruta que el servicio no conoce lo dice, nombrando la ruta. Una dirección vacía, una dirección en ninguna de las cuatro formas y una respuesta que no se lee como el tipo declarado también dan el motivo. Un servicio que no contesta nada es la conexión del dispositivo fallando: el dispositivo lo informa y se reconecta, y sus tags apuntan a él.

Ejemplos:

• \\PI-SRV01\FURNACE.TEMP, un punto PI clásico.
• \\AF-SRV\Plant\Line 3\Furnace|Temperature, un atributo AF.
• streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value, una URL de flujo en bruto, útil cuando ya se tiene el WebId de otra herramienta.

Escrituras

Los tags con un modo de acceso que permite escribir escriben por el endpoint de flujo de PI Web API: un POST de {"Timestamp":"*","Value":…} (la marca de tiempo * significa ahora) a streams/{webId}/value. La escritura necesita un WebId que se pueda resolver, así que funciona con los tags direccionados por ruta AF, por ruta de punto PI, por WebId, y también por una URL relativa streams/…: el WebId se saca de esa URL y la escritura aterriza en el endpoint de valor de ese flujo, sea cual sea el subrecurso de lectura (recorded, por ejemplo) que la dirección llevara más allá. Tres formas relativas se rechazan, porque cada una responde con un documento en lugar de con el valor de un flujo y una escritura direccionaría el recurso equivocado: streamsets/…, attributes?… y points?…. La negativa nombra las formas aceptadas. Que la escritura aterrice depende además de que PI Web API esté configurado para escrituras y de que la cuenta tenga acceso de escritura al punto. Una escritura que PI Web API rechaza se contesta con el estado y lo que el servicio dijo con él (por ejemplo HTTP 403 Forbidden: …), y quien escribió el valor lee el motivo.

El valor que se escribe en la casilla de escritura del tag es el valor de ingeniería; las etapas de conversión del tag se deshacen antes de que el valor bruto salga al bus, tal como se describe en la página Connector.

Tipos de dato admitidos

Boolean, Int32, Int64, Float, Double y String. Los puntos PI numéricos suelen ser Float o Double. Un estado digital no es un valor único, así que un punto que responde con uno se lee con mala calidad nombrando el estado, sea cual sea el tipo que declare el tag.

Comandos

Más allá de leer y escribir puntos, a un endpoint de PI Web API se le puede pedir que haga algo, y qué peticiones acepta es asunto del propio servicio. Cada una se declara en el dispositivo, en la tarjeta Comandos de su página: un nombre, la URL relativa a la que se envía por POST bajo la raíz del servicio y, si procede, el nombre del único valor que toma, que viaja como cuerpo de la petición. El verbo Ejecutar de la fila lo envía e informa de lo que contestó el servicio; el comando pasa a ser además un método sobre el dispositivo en el espacio de direcciones OPC UA propio de esta estación. Una petición que el servicio rechaza se contesta con el estado y lo que el servicio dijo con él, con las mismas palabras que las de una escritura rechazada.

Descubrimiento

El botón Descubrir lee un servicio. Ponga su dirección y el elemento AF donde empieza el recorrido en la tarjeta Alcance de la exploración de la página del controlador, separados por una #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. La exploración resuelve ese elemento, recorre todos los elementos que hay debajo, y ofrece el dispositivo con un punto por atributo, cada uno direccionado por su propio flujo. La exploración lee el servicio sin credenciales, porque corre antes de que exista el dispositivo que las guardaría, así que un PI Web API que autentica cada petición no responde nada y el dispositivo se añade a mano: añada el servicio por su host y añada los tags por sus rutas AF o PI, tal como describe el recorrido para añadir un dispositivo de la página Connector.

La página de un dispositivo PI no muestra Descubrir tags: el recorrido empieza en un elemento AF, que el dispositivo no guarda, así que los puntos de un dispositivo vienen de esta exploración o se añaden a mano (vea Descubrir los tags de un dispositivo).

Acceso a los equipos

Una PI Web API cuyo puerto no tiene ningún certificado asignado crea y usa un certificado autofirmado propio, que ninguna raíz instalada en Windows avala. No hace falta instalar esa raíz en este ordenador. La primera conexión se rechaza, el dispositivo dice Esperando la aprobación del certificado en el árbol y en su página, cuyo botón Revisar el certificado abre esta tarjeta sobre el certificado, y el certificado espera en Acceso a los equipos, al final de la página del controlador AVEVA PI, la misma tarjeta que lleva la página del controlador OPC UA, hasta que usted decida:

Compruebe la huella digital con quien administra el servidor PI antes de aprobar el certificado. Una aprobación acepta ese certificado y ningún otro, y solo dentro de sus fechas de validez; sustituye a la raíz que falta en Windows y al nombre que lleva el certificado, así que una PI Web API a la que se llama por su dirección IP se conecta aunque su certificado lleve otro nombre, y nada más del certificado se relaja. Cuando el equipo responde en una dirección cuyo certificado usted aprobó con otro distinto (un certificado renovado, otro certificado vinculado al puerto), la lectura se detiene, el nuevo espera aquí y la estación avisa "Certificado cambiado: <nombre>" con un botón Revisar. Un certificado en el que Windows ya confía se acepta como antes y nunca aparece aquí; nada se aprueba automáticamente.

El propio fallo del controlador dice el motivo en lugar de un error de TLS sin nombre: "El certificado de este equipo (los primeros 16 caracteres de la huella digital) espera su aprobación en Acceso a los equipos, en la página del controlador AVEVA PI. La lectura empieza en cuanto lo apruebe." Uno bloqueado dice "…está bloqueado en esta estación. Revíselo en Acceso a los equipos, en la página del controlador AVEVA PI." Un certificado fuera de sus fechas de validez, revocado o con la firma rota se rechaza con ese motivo y nunca se lista, porque ninguna aprobación lo vuelve válido. Una exploración del servicio desde la tarjeta Alcance de la exploración se encuentra con las mismas decisiones: un certificado desconocido termina la exploración con esa frase y espera aquí.

Las decisiones se guardan en la carpeta de datos de la estación, en ua\pki\aveva-pi, y sobreviven a un reinicio. Los verbos solo se dibujan para un rol que puede configurar el Connector, y solo actúan en la ventana de la propia estación: un navegador en otro dispositivo lee la tarjeta sin cambiarla, y ninguna herramienta de agente aprueba un certificado (connector_browse indica el dispositivo en espera con awaitingCertificate). La lista guarda hasta 100 certificados a la espera de aprobación; cuando está llena, uno nuevo se sigue rechazando pero no se lista, y la tarjeta lo dice.