LORA_CONTROLLER

Implementa a interface com o módulo de comunicação LoRa RAK811 da BreakBoard, estabelecendo e mantendo a conexão com o servidor LoRa e gerenciando a troca de mensagens. É um bloco de função (mantém estado entre scans; requer instância).

Biblioteca: HI_STD · Namespace: HILS · Tipo: bloco de função

Bloco de função

               LORA_CONTROLLER
           +---------------------+
  BOOL ----|EN                ENO|---- BOOL
           |                     |
  BOOL ----|START       CONNECTED|---- BOOL
           |                     |
 USINT ----|COMM_SRC         R_EV|---- BOOL
           |                     |
 USINT ----|SEND           R_PORT|---- USINT
           |                     |
 USINT ----|LORA_MODE      R_CODE|---- INT
           |                     |
 USINT ----|S_PORT           S_EV|---- BOOL
           |                     |
           |                 S_ID|---- USINT
           |                     |
           |               S_CODE|---- INT
           |                     |
STRING ----|DEV_EUI ------------ |----
           |                     |
STRING ----|APP_EUI ------------ |----
           |                     |
STRING ----|APP_KEY ------------ |----
           |                     |
STRING ----|LORA_IMSG ---------- |----
           |                     |
STRING ----|LORA_OMSG ---------- |----
           +---------------------+

O bloco possui as seguintes funções principais:

Estabelece conexão com o servidor LoRa;
Gerencia eventuais quedas de conexão, reconectando automaticamente;
Notifica a conexão bem-sucedida, permitindo ao usuário iniciar a troca de dados;
Sinaliza a recepção de mensagens do servidor LoRa, disponibilizando a porta e a mensagem associada.

O processo é iniciado pela ativação da entrada START, que deve permanecer ativa durante todo o tempo de execução. Ao ser ativado, o bloco inicia a conexão pelo socket Ethernet indicado em COMM_SRC. Concluído o processo com sucesso, a saída CONNECTED se torna ativa, indicando que o servidor LoRa está conectado e funcional.

Quando o servidor envia uma mensagem ao cliente, a saída R_EV gera um pulso; nesse instante as saídas R_PORT e LORA_IMSG contêm, respectivamente, o número da porta e a mensagem associada.

Importante

LORA_IMSG deve ser processada durante o evento de R_EV, pois pode ser alterada nos ciclos seguintes.

Atenção

Após ativar o bloco (por START), se EN for desativada durante um processo pendente, o comportamento do bloco é indefinido. Desative EN apenas quando não houver processo pendente no bloco.

Parâmetros

Nome	Direção	Tipo	Dimensão	Padrão	Faixa / Unidade	Descrição
EN	IN	BOOL	—	TRUE	—	Habilitação de entrada (uso típico em LADDER/FB para encadear blocos).
START	IN	BOOL	—	FALSE	—	Inicia a gerência da conexão (ativa na transição de subida); mantenha ativa.
COMM_SRC	IN	USINT	—	0	`8 .. 15` (socket Ethernet)	Canal de comunicação (socket) usado para acesso ao servidor LoRa.
SEND	IN	USINT	—	0	—	Quando ? 0, envia a variável do ID indicado e o conteúdo de `LORA_OMSG`.
LORA_MODE	IN	USINT	—	0	`1` = OTAA · `2` = ABP	Modo de operação do LoRa.
S_PORT	IN	USINT	—	1	—	Porta associada à mensagem a ser enviada ao servidor LoRa.
DEV_EUI	IN_OUT	STRING	:16	—	—	Device EUI gerado pela aplicação no LoRa Network Server.
APP_EUI	IN_OUT	STRING	:32	—	—	Application EUI gerado pela aplicação no LoRa Network Server.
APP_KEY	IN_OUT	STRING	:32	—	—	App Key gerado pela aplicação no LoRa Network Server.
LORA_IMSG	IN_OUT	STRING	—	—	—	Mensagem recebida do servidor LoRa.
LORA_OMSG	IN_OUT	STRING	—	—	—	Mensagem a ser enviada ao servidor LoRa.
ENO	OUT	BOOL	—	FALSE	—	Saída de habilitação.
CONNECTED	OUT	BOOL	—	FALSE	—	Conexão com o servidor estabelecida com sucesso.
R_EV	OUT	BOOL	—	FALSE	—	Gera um pulso ao receber uma mensagem do servidor LoRa.
R_PORT	OUT	USINT	—	0	—	Porta associada ao pacote recebido.
R_CODE	OUT	INT	—	0	RET_CODE	Último código de erro na conexão ou recepção (ver Códigos de retorno).
S_EV	OUT	BOOL	—	FALSE	—	Gera um pulso ao completar qualquer processo com erro.
S_ID	OUT	USINT	—	0	—	ID do item que foi transmitido.
S_CODE	OUT	INT	—	0	RET_CODE	Último código de erro no envio de uma mensagem (ver Códigos de retorno).

Canais de comunicação

O valor de COMM_SRC identifica o canal de comunicação. Como este bloco acessa o servidor LoRa por um socket Ethernet, use um identificador da faixa Ethernet 1 (8 .. 15). Identificadores no namespace HILS:

ID	Identificador	Canal
0 .. 7	`COM1_PORT_ID` .. `COM8_PORT_ID`	Portas seriais.
8 .. 15	`SOCK0_PORT_ID` .. `SOCK7_PORT_ID`	Sockets da Ethernet 1.
16 .. 23	`ETH2_SOCK0_PORT_ID` .. `ETH2_SOCK7_PORT_ID`	Sockets da Ethernet 2.

Nota

Cada equipamento possui um subconjunto dos recursos de comunicação acima. Consulte o manual do equipamento para identificar os recursos disponíveis.

Códigos de retorno

R_CODE e S_CODE reportam o último código de erro dos processos de conexão/recepção e de envio, respectivamente. Use os identificadores com o namespace HILS (ex.: HILS.CO_SOCK_ERR). Códigos mais comuns:

Código	Identificador	Significado
0	SUCCESS	Processo executado com sucesso.
10	GL_CMD_TMO	Timeout na execução do comando.
63	CO_CONEX_FAIL	Falha no processo de conexão.
67	CO_SOCK_ERR	Erro de socket (não foi possível adquirir/usar o socket).
68	CO_TRA_BUF_OVL	Overflow no buffer de transmissão.
69	CO_REC_BUF_OVR	Overrun no buffer de recepção.
70	CO_COM_ERR	Erro genérico de comunicação.

Lista completa dos códigos de retorno: RET_CODE - Códigos de retorno do firmware G5.

Pré-condições

O equipamento deve dispor de um socket Ethernet livre, indicado em COMM_SRC.
DEV_EUI, APP_EUI e APP_KEY devem estar preenchidos conforme a aplicação cadastrada no LoRa Network Server.
START deve permanecer ativa durante toda a operação.

Observações

A recepção é sinalizada por um pulso em R_EV; processe LORA_IMSG nesse ciclo, pois o valor pode mudar nos scans seguintes.
S_EV pulsa ao término de qualquer processo com erro; S_ID e S_CODE indicam o item e o código associados.

Ver também

MQTT_CONTROLLER, MQTT_PUBLISH, MQTT_SUBSCRIBE

Exemplo

Clique aqui para baixar a tabela de variáveis

Código ST

VAR
    BROKER_IP   : STRING := '192.168.0.58'; (* IP do Broker *)
    BROKER_PORT : UDINT := 1883;            (* porta de escuta do broker *)
    MQTT_CT     : HILS.MQTT_CONTROLLER;     (* bloco de controle do protocolo MQTT *)
    START       : BOOL := 1;                (* Habilita protocolo *)
    REC_TOPIC   : STRING;                   (* Nome do tópico recebido do broker *)
    REC_MSG     : STRING;                   (* Mensagem associada ao tópico recebido do broker *)
    W_TOPIC     : STRING[80];               (* Nome do tópico associado ao processo de desconexão do cliente (opcional) *)
    W_MSG       : STRING[140];              (* Mensagem associada ao processo de desconexão do cliente (opcional) *)
    USER        : STRING[20];               (* Nome do usuário (opcional) *)
    PASSW       : STRING[16];               (* Senha de acesso (opcional) *)
    MQTT_PUB    : HILS.MQTT_PUBLISH;        (* Bloco de publicação do protocolo MQTT *)
    PUB_ITEM    : BOOL := FALSE;            (* Flag para publicar um item *)
    PUB_TOPIC   : STRING := 'temp';         (* Nome do tópico a ser publicado *)
    PUB_MSG     : STRING := '123.oC';       (* Valor do tópico a ser publicado *)
    MQTT_SUB    : HILS.MQTT_SUBSCRIBE;      (* Bloco de assinatura do protocolo MQTT *)
    SUB_TOPIC   : STRING := 'temp';         (* Nome do tópico a ser assinado *)
END_VAR

(* Este código abre conexão com o broker MQTT, assina o tópico 'temp' e, a cada
   ativação da variável PUB_ITEM, publica o tópico 'temp' com valor '123.oC'.
   Como o tópico publicado tem o mesmo nome do tópico assinado, após a publicação
   o tópico é recebido do broker. *)

(* Abre uma conexão (Clean session com Keep Alive = 5 min) *)
MQTT_CT(  (* MQTT_CONTROLLER *)
  START        := START,               (* [BOOL] Inicia a gerência da conexão MQTT (transição de subida) *)
  COMM_SRC     := HILS.SOCK1_PORT_ID,  (* [USINT] Canal de comunicação a ser utilizado *)
  BROKER_IP    := BROKER_IP,           (* [STRING] IP de conexão com o broker *)
  BROKER_PORT  := BROKER_PORT,         (* [UINT] Porta de conexão com o broker *)
  WTOPIC       := W_TOPIC,             (* [STRING] Tópico da mensagem de WILL *)
  WMSG         := W_MSG,               (* [STRING] Mensagem de WILL *)
  USER         := USER,                (* [STRING] Nome do usuário *)
  PASSW        := PASSW,               (* [STRING] Senha do usuário *)
  BROKER_TOPIC := REC_TOPIC,           (* [STRING] Nome do tópico recebido *)
  BROKER_MSG   := REC_MSG              (* [STRING] Mensagem associada ao tópico recebido *)
  );

(* Assim que a conexão com o broker for realizada, assina um tópico *)
MQTT_SUB(  (* MQTT_SUBSCRIBE *)
  START    := MQTT_CT.CONNECTED,       (* [BOOL] Inicia a assinatura de um tópico (transição de subida) *)
  COMM_SRC := HILS.SOCK1_PORT_ID,      (* [USINT] Canal de comunicação a ser utilizado *)
  TOPIC    := SUB_TOPIC                (* [STRING] Nome do tópico a ser assinado *)
  );

IF MQTT_CT.TOP_EV THEN
  (* Tratar aqui o tópico recebido do broker *)
  ;
END_IF;

IF PUB_ITEM THEN
  MQTT_PUB(  (* MQTT_PUBLISH *)
    START    := PUB_ITEM,              (* [BOOL] Inicia a publicação de um tópico (transição de subida) *)
    COMM_SRC := HILS.SOCK1_PORT_ID,    (* [USINT] Canal de comunicação a ser utilizado *)
    RETAIN   := FALSE,                 (* [BOOL] Notifica o broker para manter a mensagem enviada *)
    QOS      := 0,                     (* [USINT] QOS (Quality of Service) (0, 1 ou 2) *)
    TOPIC    := PUB_TOPIC,             (* [STRING] Nome do tópico a ser publicado *)
    MESSAGE  := PUB_MSG                (* [STRING] Mensagem associada ao tópico a ser publicado *)
    );
  IF MQTT_PUB.DONE_EV THEN
    PUB_ITEM := FALSE;
  END_IF;
END_IF;