1. Introdução
--------------

Guia rápido para configuração da comunicação MQTT, utilizando o software "configurador_cel_4G".

Esse guia é aplicável aos produtos:
- ABS CEL MQTT - 4G.




2. Configuração do MQTT
------------------------

Elas são realizadas nas seguintes abas do configurador: 


MQTT > Broker configs 
=====================
Aqui são configurados os parâmetros de conexão ao broker MQTT:
- Broker address
- Broker port
- Broker username
- Broker password
- Publish topic
- Subscribe topic

Os parâmetros "username" e "password" podem ficar em branco, caso o Broker admita conexão sem autenticação.

Caso não seja necessário receber nada, o parâmetro "subscribe topic" pode ficar em branco.




MQTT > Metrics > Modbus reading & Metrics definition
====================================================
Os valores das métricas a serem transmitidas são obtidos através da leitura via Modbus (inclusive do datalogger interno do ABS). 

Então, é necessário definir os comandos Modbus de leitura e as métricas associadas a cada comando.

Essas definições devem estar no arquivo "mqtt_metrics.txt", na mesma pasta do programa de configuração.  Como montar esse arquivo é explicado mais adiante no texto.



MQTT > Metrics configs > Metrics transmission settings
======================================================
São configurações relacionadas a publicação das métricas:
- Habilita a transmissão das métricas.
- Define o intervalo de transmissão.
- Habilita (desmarcado) a repetição do envio, em caso de falha na transmissão. 




3. Montagem do arquivo "mqtt_metrics.txt"
-----------------------------------------

Regras gerais:
- Sem linha em branco
- Texto da última linha: #
- Cada linha define OU um comando Modbus OU a definição de uma métrica
- A primeira linha é obrigatoriamente um comando Modbus
- As métricas são definidas nas linhas seguintes ao comando Modbus ao qual elas estão associadas


Formato da linha do comando Modbus:

	MB:slave;fun;regi;num

	- "MB:" é o header que identifica que a linha é um comando Modbus
	- slave: endereço do dispositivo na rede Modbus
	- fun: função Modbus de leitura.  Valores válidos: 1, 2, 3 e 4
	- regi: registro inicial
	- num: quantidade de pontos a ler, a partir do registro inicial


Formato da linha de definição da métrica:

	name;type;reg

	- name: nome da métrica (até 24 caracteres)
	- type: tipo de dado lido
	- reg: registro Modbus que define o valor da métrica ("reg" deve estar entre os registros lidos pelo comando Modbus)

	Os tipos válidos são:
	    U08, U16, U32: número inteiro sem sinal, de 8, 16 e 32 bits
	    S08, S16, S32: número inteiro com sinal, de 8, 16 e 32 bits
	    F32: número em ponto flutuante de 32 bits
	    BIT: booleano, onde 1 = true e 0 = false 

	Os tipos 32 bits ocupam dois registros, onde a parte mais significativa do valor está no primeiro registro.

	O tipo BIT pode ser obtido de duas formas, conforme o comando Modbus usado para realizar a leitura:
	    fun = 01 ou 02: é o próprio valor do ponto lido
	    fun = 03 ou 04: acesso ao bit desejado do valor lido (ver exemplo abaixo).

Exemplo:

MB:200;4;64100;12
Timer;U16;64100
DI1;BIT;64101.0  
DI2;BIT;64101.1
DI3;BIT;64101.2
DI4;BIT;64101.3
DI5;BIT;64101.4
DI6;BIT;64101.5
DI7;BIT;64101.6
DI8;BIT;64101.7
AI1;U16;64103
AI2;U16;64104
AI3;U16;64105
AI4;U16;64106
MB:200;4;64115;8
Total1;U32;64115
Total2;U32;64117
Total3;U32;64119
Total4;U32;64121
MB:50;1;10;3
input1;BIT;10
input2;BIT;11
input3;BIT;12
#

No exemplo acima, existem três comandos Modbus.  São as linha iniciadas por "MB:". As demais definem as métricas (exceto a última).

Os dois primeiros comandos referem-se ao slave 200 (datalogger interno do produto ABS) e o terceiro refere-se ao slave 50 (um outro slave qualquer).  

Cada comando tem várias métricas associadas:
- primeiro: 13 métricas, referentes as entradas digitais e analógicas do ABS e também um registro auxiliar chamado Timer (64100).
- segundo: 4 métricas.  Repare que são lidos 8 registros, pois os totalizadores do ABS são valores de 32 bits
- terceiro: 3 métricas.

No primeiro comando, os BITs são obtidos acessando o bit do registros 64101.  Já no terceiro, os BITs são lidos diretamente, utilizando a função 01.



4. Transmissão das métricas
----------------------------

As métricas são transmitidas no formato JSON.

O formato padrão é:

{
    "ts": valor_timestamp,
    "metrics":{
        "nome_metrica_1": valor_metrica_1,
        "nome_metrica_2": valor_metrica_2,
        ...
        "nome_metrica_N": valor_metrica_N
    }
}

Existe a possibilidade de customizar o json enviado. 



5. Informações finais
---------------------

A varredura dos slaves Modbus ocorre a cada 15 segundos, independente do tempo de transmissão selecionado.

O timeout da comunicação típico é 300 ms.

Podem ser lidos até 64 pontos em cada comando Modbus.

IMPORTANTE: para otimizar o processo, procure ler em bloco (cada comando Modbus ler vários registros).
