# AVEVA PI

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

El driver AVEVA PI lee y escribe un **PI System de AVEVA** a través de la **PI Web API**, la
interfaz REST del sistema (JSON sobre HTTP). Es un driver en modo cliente (**Ganter Lab se
conecta al servicio de la PI Web API**) y el transporte es **HTTPS de forma predeterminada**:
el driver 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 de AF**, un **punto PI** o un flujo crudo de la PI Web API, y
lee su valor de instantánea (el actual).

## Los campos de conexión {#connection-fields}

| Campo | Qué es | Formato | Valor inicial |
|---|---|---|---|
| Host o IP | El nombre de host o la dirección IP del servidor de la PI Web API. Se puede pegar una dirección completa (`https://pi-host/piwebapi`): `https://` o `http://` adelante ajusta el transporte de más abajo y se descarta, un puerto pasa al campo del puerto y la ruta a la ruta del recurso. | Nombre de host o IP | vacío |
| Puerto | El puerto TCP del servicio. Un dispositivo nuevo lo deja vacío, y un campo vacío significa el puerto en el que contesta el transporte elegido, 443 sobre HTTPS y 80 sin cifrar: el campo muestra ese puerto en gris y sigue la elección del transporte, que es también como se lee un dispositivo guardado con 0. | de 1 a 65535, o vacío | vacío |
| Ruta del recurso | La ruta raíz del servicio que se agrega a la autoridad. En blanco, o una `/` sola, significa la raíz estándar de la PI Web API, `piwebapi`. Cualquier otra ruta es la ruta que abre el driver, exactamente como se escribió: un servicio publicado detrás de un proxy inverso en `/pi` se alcanza en `/pi`, y no se le agrega nada. Escriba la ruta completa que necesitaría un navegador, con `piwebapi` incluido donde el servicio siga contestando ahí. | texto de ruta | en blanco (= `piwebapi`) |
| Enviar por HTTP sin cifrar | Baja este dispositivo, y solo este, de HTTPS a HTTP en claro. Apagado significa HTTPS, el transporte normal de la PI Web API. El panel declara la consecuencia: en HTTP sin cifrar, el token de portador o la contraseña se envían sin cifrar en cada petición. Úselo solo con una PI Web API que no conteste por ningún otro transporte. | encendido / apagado | apagado |
| Nombre de usuario | La cuenta para la autenticación **HTTP Basic**, usada solo cuando no hay ningún token de portador puesto. Vacío (y sin token) deja las peticiones anónimas. | Texto libre | vacío |
| Contraseña | La contraseña que va con el nombre de usuario. Protegida en reposo por usuario de Windows; un secreto capturado en otra cuenta de Windows se muestra como ilegible y hay que volver a ingresarlo. | Texto libre | vacía |
| Token de portador | Un token que se envía como `Authorization: Bearer …` en cada petición. Cuando está puesto, **gana** sobre el par de nombre de usuario y contraseña. Se protege en reposo de la misma manera. | Texto del token | vacío |

Al conectarse, el driver verifica la raíz del servicio (con HEAD, y cayendo 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](#equipment-access), en la página de este
driver. El intervalo de sondeo es configurable: el valor predeterminado del dispositivo
(1000 ms) vale para todo tag que no declare el suyo.

## Preparar la PI Web API {#prepare-pi-web-api}

El driver 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 driver 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:

| Vía | Dónde se ajusta | Después |
| --- | --- | --- |
| Autenticación Basic | PI Web API Admin Utility, página Authentication Options: marque Basic y aplique. O PI System Explorer, base de datos Configuration, el elemento System Configuration bajo OSIsoft > PI Web API > el nombre de la instancia: agregue Basic al atributo AuthenticationMethods y registre el cambio con check in. Reinicie el servicio de la PI Web API. | Nombre de usuario y Contraseña en la tarjeta Conexión del dispositivo llevan una cuenta de Windows que el PI System acepte; una cuenta de dominio se escribe DOMINIO\usuario |
| Token de portador | PI Web API configurada con AVEVA Identity Manager (autenticación Bearer) | El token va en la casilla Token de portador del dispositivo |

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 driver; 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 driver.

## El direccionamiento del tag {#tag-addressing}

El campo **Ruta PI** del tag acepta cuatro formas:

| Forma | Se ve así | Cómo se resuelve |
| --- | --- | --- |
| Ruta de atributo de AF | `\\AFServer\BaseDeDatos\Elemento\SubElemento\|Atributo` | Se consulta una vez por `attributes?path=…` para obtener el WebId del atributo |
| Ruta de punto PI | `\\ServidorPI\NombreDeTag` | Se consulta una vez por `points?path=…` para obtener el WebId del punto |
| WebId | La cadena opaca del WebId misma | Se usa directamente (se reconoce como un token largo sin `\`, `\|` ni `/`) |
| URL relativa | `streams/{webId}/value`, `streamsets/…`, `attributes?…`, `points?…` | Se envía tal cual bajo la raíz del servicio |

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

El veredicto propio del archivo histórico sobre la muestra se lee junto con ella. Un valor
que el archivo marca como **no bueno**, como **cuestionable** o como **sustituido** (un
número capturado 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 fue. Lo mismo
pasa cuando la respuesta no trae ningún valor, o cuando contesta con un estado digital en
lugar de un valor único, y en ese caso el nombre del estado forma parte del motivo. Nada se
inventa en su lugar, y ningún documento llega como si fuera la medición.

Una lectura que la 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 reporta 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 de AF.
- `streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value`, una URL de flujo cruda, útil cuando usted ya
  tiene el WebId de otra herramienta.

## Las escrituras {#writes}

Los tags con un modo de acceso escribible escriben por el endpoint de flujo de la PI
Web API: un POST de `{"Timestamp":"*","Value":…}` (la marca de tiempo `*` significa ahora) a
`streams/{webId}/value`. La escritura necesita un WebId resoluble, así que funciona para los
tags direccionados por ruta de 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 del lado de lectura (`recorded`,
por ejemplo) que llevara la dirección más allá. Tres formas relativas se rechazan, porque
cada una contesta con un documento en lugar de con el valor de un flujo y una escritura
direccionaría el recurso equivocado: `streamsets/…`, `attributes?…` y `points?…`. El rechazo
nombra las formas aceptadas. Que la escritura aterrice depende además de que la PI Web API
esté configurada para escrituras y de que la cuenta tenga acceso de escritura al punto. Una escritura que la 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 usted escribe en la caja 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, como se
describe en la página del [Connector](connector).

## Los tipos de dato admitidos {#supported-data-types}

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 contesta con uno se lee
con mala calidad nombrando el estado, sea cual sea el tipo que declare el tag.

## Comandos {#commands}

Más allá de leer y escribir puntos, a un endpoint de la PI Web API se le puede pedir
que haga algo, y qué peticiones acepta es asunto del propio servicio. Declare cada una en el
dispositivo, en la tarjeta **Comandos** de su página: un nombre, la URL relativa a la que se
le hace POST bajo la raíz del servicio y, opcionalmente, el nombre del único valor que toma,
que viaja como el cuerpo de la petición. El verbo Ejecutar de la fila lo envía y reporta qué
contestó el servicio; el comando se convierte además en un método del dispositivo dentro del
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.

## El descubrimiento {#discovery}

El botón **Descubrir** lee un solo servicio. Ponga su dirección y el elemento AF desde el que
empieza el recorrido en la tarjeta Alcance del escaneo de la página del driver, separados por
un `#`: `https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3`. El escaneo 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. El escaneo lee el servicio sin
credenciales, porque corre antes de que exista el dispositivo que las tendría, así que una PI
Web API que autentica cada petición no contesta nada y el dispositivo se agrega a mano en su
lugar: agregue el servicio por su host y agregue los tags por sus rutas de AF o de PI, como
describe el flujo para agregar un dispositivo de la página del [Connector](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 este escaneo o se agregan a mano (vea [Descubrir los tags de un dispositivo](connector-discovery#discovering-a-devices-tags)).

## Acceso a los equipos {#equipment-access}

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 driver AVEVA PI, la misma tarjeta que lleva la página del driver OPC UA, hasta que usted decida:

| Grupo | Qué muestra | Qué puede hacer |
|---|---|---|
| A la espera de aprobación | Cada certificado rechazado, con el nombre que declara: su huella digital SHA-256, la dirección en la que se encontró, cuándo lo intentó por última vez y cuántas veces, y sus detalles (sujeto, emisor, nombres de dominio, fechas de validez). El que abrió **Revisar el certificado** de un dispositivo aparece marcado como Seleccionado para revisión. | **Aprobar** acepta el certificado desde el siguiente intento de conexión. **Bloquear** lo sigue rechazando sin volver a listarlo aquí. **Descartar todos los certificados pendientes** vacía la lista sin aprobar ni bloquear nada. |
| Equipos aprobados | Los certificados que usted aprobó o importó, con quién decidió y cuándo, y la dirección en la que se encontró cada uno por última vez. | **Retirar la aprobación** cierra la conexión y devuelve el certificado a la lista. **Importar certificado** aprueba un archivo de certificado público que ya tenga (.der, .cer, .crt o .pem) antes de la primera conexión. |
| Equipos bloqueados | Los certificados que usted bloqueó. Un certificado bloqueado se rechaza aunque Windows confíe en él. | **Desbloquear** devuelve el certificado a la lista, sin aprobarlo. |

Verifique 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 driver 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 driver 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 driver 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. Un escaneo del servicio desde la tarjeta Alcance del escaneo se encuentra con las mismas decisiones: un certificado desconocido termina el escaneo 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.