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
| Campo | O que é | Formato | Padrão |
|---|---|---|---|
| Host | O nome de host ou endereço IP do servidor PI Web API. | Nome de host ou IP | vazio |
| Porta | A porta TCP do serviço. Zero significa o padrão do driver, 443. | número de porta | 0 (= 443) |
| Caminho do recurso | O caminho da raiz de serviço anexado à autoridade. Em branco, ou uma / sozinha, significa a raiz padrão do PI Web API, piwebapi. Qualquer outro caminho é o caminho que o driver abre, exatamente como digitado: um serviço publicado atrás de um proxy reverso em /pi é alcançado em /pi, e nada é anexado a ele. Escreva o caminho inteiro de que um navegador precisaria, piwebapi incluído onde o serviço ainda responde ali. |
texto de caminho | em branco (= piwebapi) |
| Enviar por HTTP simples | Rebaixa este dispositivo de HTTPS para HTTP em claro. Desmarcado significa HTTPS, o transporte normal do PI Web API. O painel declara a consequência: em HTTP simples, o token bearer ou a senha é enviado sem criptografia em toda requisição. Use isso só num PI Web API que não responde em nenhum outro transporte. | ligado / desligado | desligado |
| Usuário | Conta para autenticação HTTP Basic, usada só quando nenhum token bearer está definido. Vazio (e sem token) deixa as requisições anônimas. | Texto livre | vazio |
| Senha | A senha que acompanha o usuário. Protegida em repouso por usuário do Windows; um segredo digitado sob outra conta do Windows aparece como ilegível e precisa ser digitado de novo. | Texto livre | vazio |
| Token bearer | Um token enviado como Authorization: Bearer … em toda requisição. Quando definido, ele prevalece sobre o par usuário e senha. Protegido em repouso do mesmo jeito. |
Texto do token | vazio |
Ao conectar, o driver verifica a raiz de serviço (HEAD, recorrendo a GET). Em HTTPS, o certificado TLS do serviço precisa passar pela validação normal de certificados do Windows. O intervalo de leitura é configurável: o padrão do dispositivo (1000 ms) vale para toda tag que não declare o próprio.
Endereçamento da tag
O campo Caminho PI da tag aceita quatro formas:
| Forma | Se parece com | Como é resolvida |
|---|---|---|
| Caminho de atributo AF | \\AFServer\Database\Element\SubElement\|Attribute |
Consultado uma vez por attributes?path=… para obter o WebId do atributo |
| Caminho de PI point | \\PIServer\TagName |
Consultado uma vez por points?path=… para obter o WebId do ponto |
| WebId | A própria cadeia opaca do WebId | Usado diretamente (reconhecido como um símbolo longo sem \, \| nem /) |
| URL relativa | streams/{webId}/value, streamsets/…, attributes?…, points?… |
Enviada como está, sob a raiz de serviço |
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 veredicto 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.
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.
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.
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.