AVEVA PI

Referência do driver AVEVA PI: PI Web API sobre HTTPS, autenticação por token bearer ou Basic, endereçamento de AF e de PI point, leituras e escritas.

O driver AVEVA PI lê e escreve um AVEVA PI System pelo PI Web API, a interface REST do sistema (JSON sobre HTTP). É um driver em modo cliente (o Ganter Lab conecta ao serviço PI Web API) e o transporte é HTTPS por padrão: o driver põe as credenciais do dispositivo em toda requisição que faz, então uma conexão sem criptografia as publicaria. O HTTP simples existe apenas como escolha explícita por dispositivo.

Uma tag endereça um atributo AF, um PI point ou um stream cru do PI Web API, e lê o valor de snapshot (atual) dele.

Campos de conexão

Ao conectar, o driver verifica a raiz de serviço (HEAD, recorrendo a GET). Em HTTPS, o certificado TLS do serviço é aceito quando o Windows confia nele, ou quando você aprovou exatamente esse certificado em Acesso a equipamentos, na página deste driver. O intervalo de leitura é configurável: o padrão do dispositivo (1000 ms) vale para toda tag que não declare o próprio.

Preparar o PI Web API

O driver entra com usuário e senha pelo HTTP Basic, ou com um token bearer. O PI Web API vem com o Kerberos como único método de autenticação, e o driver não fala Kerberos, então um serviço recém-instalado costuma recusar a estação até que uma destas coisas seja feita no servidor do PI Web API:

Quando o serviço responde 401 sem oferecer o Basic, a página do dispositivo diz isso, com estes passos, no lugar do erro em inglês do driver; quando ele oferece o Basic e recusa a conta que o dispositivo enviou, a página diz que o usuário ou a senha foi recusado e aponta o cartão Conexão. Qualquer um dos avisos some sozinho quando o serviço responde. O registro e o agente leem os mesmos passos. Um token bearer que o serviço recusa é dito nas palavras do próprio driver.

Endereçamento da tag

O campo Caminho PI da tag aceita quatro formas:

As consultas de caminho ficam em cache por 12 horas, então a leitura cíclica em regime não as repete. Nas três primeiras formas, a leitura busca com GET o valor de snapshot do stream (streams/{webId}/value) e extrai o campo Value do JSON; uma URL relativa é lida literalmente, então aponte-a para um endpoint que responda com um documento de valor. O resultado é convertido para o tipo de dado declarado da tag.

O veredito do próprio arquivo sobre a amostra é lido junto. Um valor que o arquivo marca como não bom, como questionável ou como substituído (um número digitado à mão, e não medido) não é uma leitura do equipamento, então não é publicado como tal: a tag vai a qualidade ruim e o motivo diz qual dos três casos era. O mesmo acontece quando a resposta não carrega valor, ou responde com um estado digital em vez de um valor único, caso em que o nome do estado faz parte do motivo. Nada é inventado no lugar deles, e nenhum documento chega como se fosse a medição.

Uma leitura que o PI Web API recusa (um status fora da faixa de sucesso, como uma conta sem acesso de leitura ao ponto) também vai a qualidade ruim, e o motivo nomeia o status e o que o serviço disse junto (HTTP 403 Forbidden: …). Um caminho que o serviço não conhece diz isso, nomeando o caminho. Um endereço vazio, um endereço em nenhuma das quatro formas e uma resposta que não se lê como o tipo declarado também dão o motivo. Um serviço que não responde nada é a conexão do dispositivo falhando: o dispositivo relata isso e reconecta, e as tags dele apontam para ele.

Exemplos:

• \\PI-SRV01\FURNACE.TEMP, um PI point clássico.
• \\AF-SRV\Plant\Line 3\Furnace|Temperature, um atributo AF.
• streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value, uma URL de stream crua, útil quando você já tem o WebId de outra ferramenta.

Escritas

Tags com modo de acesso gravável escrevem pelo endpoint de stream do PI Web API: um POST de {"Timestamp":"*","Value":…} (o carimbo de tempo * significa agora) para streams/{webId}/value. A escrita precisa de um WebId resolvível, então ela funciona em tags endereçadas por caminho AF, por caminho de PI point, por WebId e também por uma URL relativa streams/…: o WebId é lido dessa URL e a escrita cai no endpoint de valor daquele stream, seja qual for o sub-recurso do lado da leitura (recorded, por exemplo) que o endereço carregava depois dele. Três formas relativas são recusadas, porque cada uma responde com um documento em vez de responder com o valor de um stream, e uma escrita endereçaria o recurso errado: streamsets/…, attributes?… e points?…. A recusa nomeia as formas aceitas. Se a escrita chega ou não também depende de o PI Web API estar configurado para escritas e de a conta ter acesso de escrita ao ponto. Uma escrita que o PI Web API recusa recebe como resposta o status e o que o serviço disse junto (por exemplo HTTP 403 Forbidden: …), e quem escreveu o valor lê o motivo.

O valor que você digita na caixa de escrita da tag é o valor de engenharia; os estágios de conversão da tag são revertidos antes de o valor bruto ir para o barramento, como descrito na página Connector.

Tipos de dado suportados

Boolean, Int32, Int64, Float, Double e String. PI points numéricos são tipicamente Float ou Double. Um estado digital não é um valor único, então um ponto que responde com um lê como qualidade ruim nomeando o estado, seja qual for o tipo que a tag declara.

Comandos

Além de ler e escrever pontos, é possível pedir a um endpoint do PI Web API que faça algo, e quais requisições ele aceita é assunto do próprio serviço. Declare cada uma no dispositivo, no cartão Comandos da página dele: um nome, a URL relativa a que ela é enviada por POST sob a raiz de serviço e, opcionalmente, o nome do único valor que ela recebe, que viaja como corpo da requisição. O verbo Executar da linha a envia e relata o que o serviço respondeu; o comando também vira um método no dispositivo, dentro do espaço de endereços OPC UA desta estação. Uma requisição que o serviço recusa recebe como resposta o status e o que o serviço disse junto, com as mesmas palavras de uma escrita recusada.

Descoberta

O botão Descobrir lê um serviço. Ponha o endereço dele e o elemento AF de onde a caminhada começa no cartão Escopo da varredura da página do driver, separados por um #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. A varredura resolve aquele elemento, percorre todo elemento abaixo dele e oferece o dispositivo com um ponto por atributo, cada um endereçado pelo stream dele. A varredura lê o serviço sem credenciais, porque roda antes de existir o dispositivo que as guardaria, então um PI Web API que autentica toda requisição não responde nada e o dispositivo é adicionado à mão: adicione o serviço por host e adicione tags pelos caminhos AF ou PI delas, como o fluxo de adicionar um dispositivo na página Connector descreve.

A página de um dispositivo PI não mostra Descobrir tags: a caminhada começa num elemento AF, que o dispositivo não guarda, então os pontos de um dispositivo vêm desta varredura ou são adicionados à mão (veja Descobrir as tags de um dispositivo).

Acesso a equipamentos

Um PI Web API cuja porta não tem nenhum certificado atribuído cria e usa um certificado autoassinado próprio, que nenhuma raiz instalada no Windows garante. Essa raiz não precisa ser instalada neste computador. A primeira conexão é recusada, o dispositivo mostra Esperando a aprovação do certificado na árvore e na página dele, cujo botão Revisar o certificado abre este cartão no certificado, e o certificado espera em Acesso a equipamentos, no fim da página do driver AVEVA PI, o mesmo cartão que a página do driver OPC UA traz, até você decidir:

Confira a impressão digital com quem administra o servidor PI antes de aprovar o certificado. Uma aprovação aceita aquele certificado e nenhum outro, e só dentro das datas de validade dele; ela substitui a raiz que falta no Windows e o nome que o certificado traz, então um PI Web API chamado pelo endereço IP conecta mesmo que o certificado dele traga outro nome, e nada mais do certificado é afrouxado. Quando o equipamento responde num endereço cujo certificado você aprovou com outro (um certificado renovado, outro certificado vinculado à porta), a leitura para, o novo espera aqui e a estação avisa "Certificado mudou: <nome>" com um botão Revisar. Um certificado em que o Windows já confia é aceito como antes e nunca aparece aqui; nada é aprovado automaticamente.

A própria falha do driver diz o motivo em vez de um erro de TLS sem nome: "O certificado deste equipamento (os primeiros 16 caracteres da impressão digital) espera a sua aprovação em Acesso a equipamentos, na página do driver AVEVA PI. A leitura começa assim que você aprová-lo." Um bloqueado diz "…está bloqueado nesta estação. Revise-o em Acesso a equipamentos, na página do driver AVEVA PI." Um certificado fora das datas de validade, revogado ou com a assinatura quebrada é recusado com esse motivo e nunca é listado, porque nenhuma aprovação o torna válido. Uma varredura do serviço pelo cartão Escopo da varredura esbarra nas mesmas decisões: um certificado desconhecido encerra a varredura com essa frase e espera aqui.

As decisões ficam na pasta de dados da estação, em ua\pki\aveva-pi, e sobrevivem a um reinício. Os verbos só são desenhados para um papel que pode configurar o Connector, e só agem na janela da própria estação: um navegador em outro aparelho lê o cartão sem mudá-lo, e nenhuma ferramenta de agente aprova um certificado (connector_browse indica o dispositivo em espera com awaitingCertificate). A lista guarda até 100 certificados esperando aprovação; quando está cheia, um novo continua recusado mas não é listado, e o cartão diz isso.