O sistema NKL SIV é o conjunto de plataformas que operam em conjunto com os equipamentos de medição e monitoramento de tanques (geralmente para combustívies) fabricados pela NKL. Cada modelo de equipamento pode disponibilizar uma ou mais APIs que permitem integração com outros equipamentos ou sistemas. Confira abaixo as opções de integrações para cada versão de equipamento:

V-Link USB

Funciona conectado a um computador com sistema operacional Windows em conjunto com o aplicativo NKL SIV 4.0. Essa versão permite a integração de 2 formas:

• API Local Desktop – acesso direto ao banco de dados local do computador onde está instalado o equipamento (que permite um acesso offline aos dados).
• API Web – quando o computador em que o SIV 4.0 está instalado tem acesso a internet, é possível ativar o serviço do SIV Web para acesso online dos dados.

G4-Link

Opera apenas com um chip de celular GPRS com tecnologia móvel 2g e disponibiliza os dados através plataforma SIV Web. Nesse caso as integrações estão disponíveis exclusivamente através da:

• API Web – Acesso pela API online do servidor web www.nklsiv.com.br.

V-Link Wi-Fi Tradicional

Disponibiliza os dados na plataforma SIV Web e também permite o acesso via rede local. Permite as integrações das seguintes formas:

• API Web – Quando o V-Link Wi-Fi estiver conectado a uma rede Wi-Fi com internet disponível os dados ficarão disponíveis na plataforma SIV Web para acesso online dos dados.
• API local REST –  Na rede Wi-Fi local, a API responde a requisições “REST” utilizando o método “GET”, isso permite que ERPs acessem os dados via rede local sem a necessidade de estar conectado a internet.

V-Link Wi-Fi Com conector Serial

Disponibiliza os dados na plataforma SIV Web, permite também o acesso via rede local e também conta com um conector Serial DB9 RS232. Nesse equipamento as integrações podem ser feitas de 3 formas:

• API Web – Quando o V-Link Wi-Fi estiver conectado a uma rede Wi-Fi com internet disponível os dados ficarão disponíveis na plataforma SIV Web para acesso online dos dados.
• API local REST–  Na rede Wi-Fi local, a API responde a requisições “REST” utilizando o método “GET”, isso permite que ERPs acessem os dados via rede local sem a necessidade de estar conectado a internet.
• Conector Serial DB9 – Permite a comunicação de dados via RS232, ele pode ser utilizado como interface física para conexão a dispositivos terceiros que possuam hardware compatível.

V-Link Wi-Fi PLUS

Equipamento similar a versão Wi-Fi tradicional, porém com tela LCD Touchscreen, disponibiliza os dados na plataforma SIV Web e também permite o acesso via rede local. Integrações disponíveis:

• API Web – Quando o V-Link Wi-Fi estiver conectado a uma rede Wi-Fi com internet disponível os dados ficarão disponíveis na plataforma SIV Web para acesso online dos dados.
• API local REST –  Na rede Wi-Fi local, a API responde a requisições “REST” utilizando o método “GET”, isso permite que ERPs acessem os dados via rede local sem a necessidade de estar conectado a internet.

VM06 Wi-Fi / AR06 Wi-Fi

São basicamente as versões dos medidor VM06 (para combustíveis) / AR06 (para líquidos não inflamáveis) com “V-Link Wi-Fi integrado”, disponibilizam os dados na plataforma SIV Web e também permitem o acesso via rede local. Viabilizam as integrações das seguintes formas:

• API Web– Quando o V-Link Wi-Fi estiver conectado a uma rede Wi-Fi com internet disponível os dados ficarão disponíveis na plataforma SIV Web para acesso online dos dados.
• API local REST –  Na rede Wi-Fi local, a API responde a requisições “REST” utilizando o método “GET”, isso permite que ERPs acessem os dados via rede local sem a necessidade de estar conectado a internet.

Formas de acesso as APIs:

1 – API SIV WEB

A forma mais simples de fazer a integração é através da plataforma SIVWEB, ela é a melhor opção para quem tem vários dispositivos instalados em vários locais distintos e deseja fazer a integração simultânea com todos os dispositivos em um único sistema. As requisições podem ser feitas seguindo a documentação da API conforme os dados do seguinte link:

https://sivapi.docs.apiary.io/#/introduction/introducao

2 – API Local Desktop

O software NKL SIV 4.0 funciona exclusivamente em conjunto com o equipamento V-Link USB, ele tem a função de fazer a comunicação do computador com o equipamento V-link (com os medidores e sensores) e exibir na tela do computador as informações de volumes dos tanques e status dos sensores de vazamento para monitoramento ambiental. Ele permite também a consulta de relatórios tanto de volumetria quanto dos sensores de vazamento. O aplicativo NKL SIV 4.0 para Windows gera um banco de dados local no computador onde o V-link USB está conectado.

É possível fazer uma integração nesse computador acessando via requisições o banco de dados do NKL SIV local, nesse caso não é necessário o uso de internet, pois o acesso é direto no banco de dados local.
Para acessar a API faça o download do seguinte arquivo formato “.yaml” https://nkl.com.br/wa_upload/image/api-vlink-description.yaml  (clique com o botão direito do mouse e escolha “salvar link como”)

Após salvar o arquivo em seu computador, acesse pelo navegador o seguinte link: https://editor.swagger.io/
Nessa página, clique em “File” e “Import File”

Selecione o arquivo “.yaml” no seu computador:

Nessa tela você terá acesso aos comandos de leitura das informações dos equipamentos conectados ao V-link:

Obs: o acesso só pode ser feito no computador onde o equipamento V-link está conectado com o software NKL SIV 4.0 instalado e parametrizado com os equipamentos.

3 – API local REST

A linha Wi-Fi (VM06 Wi-Fi, AR06 Wi-Fi, V-Link Wi-Fi e V-Link Wi-Fi Plus) possui implementada em sua lógica embarcada uma Interface de Programação de Aplicação (API). Este recurso pode ser utilizado para permitir que as informações dos dispositivos sejam acessadas por um eventual software de gestão (ERP/BI) de terceira parte, desde que ambas as plataformas compartilhem os mesmos recursos de rede.

A API de integração responde a requisições “REST” utilizando o método “GET” destinadas a uma das URIs de cada modelo de equipamento:

3.1 – V-Link Wi-Fi e V-Link Wi-Fi Plus:

Para obter a situação atualizada dos dispositivos de campo associados ao V-Link:
http://nkl-yyXXXXX.local/api/field_status (onde yyXXXXX é o número de série do V-LINK).

Para obter os parâmetros de configuração de um indicador de volume individual conectado a um V-Link Wi-Fi:
http://nkl-yyXXXXX.local/api/device_param?ZZKKKKK (onde yyXXXXX é o número de série do V-LINK e ZZKKKKK é o número de série de um indicador de volume instalado ao V-LINK).

A inclusão de informações adicionais no cabeçalho da requisição, tais como uma chave de autorização, NÃO é necessária. Apesar de não existir um limite definido para requisições sucessivas NÃO sobrecarregue a aplicação com múltiplas chamadas à API em intervalo de tempo reduzido. Intervalos de 10 segundos entre chamadas são bastante satisfatórios considerando a natureza das atividades monitoradas pelo V-LINK.

As repostas devolvidas chegam em formato JSON (JavaScript Object Notation), de forma similar aos exemplos a seguir:

Exemplo de resposta para uma requisição hipotética feita à http://nkl-ve00001.local/api/field_status

{
“Field Status”: {
“V-LINK_WiFi”: {
“jt_sn”: “VE00001”,
“online”: 1,
“qtd_lvl”: 10,
“qtd_sen”: 19,
“bus_v”: 9.6,
“bus_i”: 85.5,
“bus_st”: 0,
“cycle”: 1887,
“rtc_fl”: 0,
“men_fl”: 0,
“id_IPV4”: “192.168.254.80”
},
“Sensores_de_Liquido”: {
“#01(Sensor do SUMP1)”: {
“id_sn”: “SI00184”,
“st_online”: 1,
“st_drywet”: 1
}
},
“Indicadores_de_Volume”: {
“#01(Gasolina Comum)”: {
“id_sn”: “BP24239 “,
“st_online”: 1,
“st_erro”: 0,
“st_lvel”: 2599,
“st_volu”: 10333,
“pr_capac”: 10337,
“st_almi”: 0,
“st_alcr”: 0,
“st_alin”: 0
}
}
}
}

Até três (3) tipos de atributo podem estar listados na resposta:

“V-LINK_WiFi” – Carrega os parâmetros do Link de Dados e informações gerais do V-LINK WiFi.

“Sensores de Liquido” – Estará presente na resposta se ao menos um (1) sensor de líquido estiver associado ao V-LINK Wi-Fi.

“#01(nonono)” Sensor #XX(identificação)

“Indicadores de Volume” – Estará presente na resposta se ao menos um (1) indicador de volume estiver associado ao V-LINK Wi-Fi

“#01(nonono)” Indicador de volume #XX(identificação)

Exemplo de resposta para uma requisição hipotética feita à
http://nkl-ve00001.local/api/device_param?BP24239

{
“Device Parameters”: {
“jt_sn”: “VE00001”,
“id_sn”: “BP24239 “,
“id_name”: “Caixa dagua NKL”,
“pr_tipo”: 2,
“pr_diam”: 2250,
“pr_altu”: 2600,
“pr_pull”: 3836,
“al_crtr”: 1000,
“al_mitr”: 2000,
“ca_relv”: 2604,
“ca_mult”: 1,
“fl_actv”: 1
}
}

“Device Parameters” – Este atributo estará presente na resposta se o indicador de volume de número de série informado após o marcador “?” estiver instalado fisicamente ao V-LINK Wi-Fi

3.2 – VM06 Wi-Fi e AR06 Wi-Fi:

Para obter a situação atualizada do tanque monitorado:
http://nkl-yyXXXXX.local/api/field_status (onde yyXXXXX é o número de série do VM/AR06 Wi-Fi).

Para obter os parâmetros de configuração do medidor VM06 Wi-Fi:
http://nkl-yyXXXXX.local/api/device_param (onde yyXXXXX é o número de série do VM06/AR06 Wi-Fi).

“VM06_WiFi” – Algumas informações gerais do VM06 WiFi

“Indicadores de Volume” – Informações da situação atual do monitoramento

4 – Conector Serial DB9

Comunicação Serial RS232 – permite a comunicação direta com equipamentos e sistemas de terceiros.

Essa funcionalidade amplia as possibilidades de integração em aplicações industriais, automação, telemetria e monitoramento remoto, possibilitando que informações dos dispositivos conectados ao sistema sejam disponibilizadas para rastreadores, CLPs, sistemas supervisórios e outras plataformas compatíveis.

Configurações:

Baud Rate: 115.200
Data Bits: 8 Bits
Parity: Não
Flow Control: Não
Stop Bits: 1

Hardware:

DB9 Fêmea

Níveis de tensão: Padrão EIA-232
Lógico baixo (0): entre 3 e 15Vdc
Lógico alto (1): entre -3 e -15V

A interface serial pode operar das sequintes formas:

4.1 – Transmissão em Modo Automático

Neste modo, o equipamento envia periodicamente as informações dos dispositivos monitorados sem necessidade de qualquer solicitação externa. O intervalo entre transmissões pode ser configurado pelo usuário, enquanto o equipamento receptor permanece em modo de escuta aguardando os dados.

Para ativar essa função, é necessário acessar a tela de configurações do dispositivo através do modo acces point, no menu de configurações clicar em “Rastreador Externo”, alterar o modelo instalado de “Nenhum” para “Genérico”. Nessa tela será definido também um intervalo de envio da comunicação de 1 a 720min.

Após configurado, deve-se clicar em Salvar em cada um dos parâmetros.

O pacote de dados transmitido, quando o hardware selecionado possui modelo “Genérico”, tem o seguinte formato:

Dado#0 é o número de série do V-LINK WiFi;
Dado#1 … Dado#N são os “status” de cada um dos dispositivos de campo individuais, transmitidos em uma mensagem limitada por um par de parênteses. “N” é igual ao número total de dispositivos de campo instalados.

Do exemplo:

O tipo de dispositivo é obtido a partir do primeiro caractere após a abertura de um parêntese. “S” indica um sensor de líquido e “B” é um indicador de volume.

4.2 – Transmissão por Solicitação

Neste modo os dados são enviados apenas quando requisitados por um equipamento externo.

O comando ASCII suportado é:

give_sta

Ao receber este comando, o V-LINK WiFi retorna exatamente o mesmo pacote utilizado no modo automático.

Embora funcional, este método não possui tratamento de erros nem mecanismos de verificação de integridade. Para aplicações industriais a NKL recomenda a utilização do protocolo MODBUS RTU.

4.3 –  MODBUS RTU Serial

Para aplicações profissionais de automação industrial, o V-LINK WiFi implementa comunicação MODBUS RTU Serial com verificação CRC16, compatível com as especificações da Modbus Organization.
Características:

• Modo RTU
• Modo ASCII não suportado
• CRC16 Modbus
• Apenas a função 03 (Read Holding Registers) está implementada.

Função suportada
03h – Read Holding Registers

Permite consultar o estado atualizado de um dispositivo de campo individual.

Dependendo do dispositivo consultado, a resposta poderá retornar:

• Volume armazenado
• Nível do tanque
• Estado do sensor (seco/molhado)
• Condições operacionais do dispositivo.

Estrutura da requisição MODBUS

A requisição possui 8 bytes:

O parâmetro Nrede corresponde ao identificador interno do dispositivo instalado logicamente no V-LINK WiFi.

Faixas de endereçamento

Indicadores de Volume: 1 até 10
Sensores de Líquido: 33 até 52

Cada dispositivo recebe automaticamente seu endereço quando é instalado logicamente no sistema.

Recomendações para integração

Para garantir estabilidade da comunicação:

• Configurar a porta serial para 115200 8N1.
• Validar todas as respostas utilizando CRC16 Modbus.
• Utilizar MODBUS RTU sempre que possível.
• Utilizar conversor de nível quando a interface do equipamento externo não for RS232 nativa.
• Monitorar situações de indisponibilidade indicadas pelos sensores ou indicadores.
• Implementar timeout de comunicação no mestre MODBUS para tratamento de ausência de resposta.