FB_MqttSubscribe

Panoramica

Tipo:	Blocco funzione
Disponibile a partire da:	V1.0.0.0

Descrizione funzionale

Il blocco funzione FB_MqttSubscribe viene utilizzato per gestire una sottoscrizione a un argomento specifico sul Server MQTT.

Sono supportate le seguenti funzioni:

Sottoscrizione all'argomento specifico
Annullamento della sottoscrizione all'argomento specifico
Lettura dei dati in base all'argomento sottoscritto

Il blocco funzione utilizza la connessione al Server MQTT stabilita precedentemente con il FB_MqttClient.

Una volta che il blocco funzione è attivato, la sottoscrizione per l'argomento specificato viene inviata al collegato Server MQTT. Lo stato della sottoscrizione e quindi la possibilità di ricevere dati è indicata dall'uscita q_xReady. I nuovi dati ricevuti sono indicati dall'uscita q_xNewMessage.

Disattivando il blocco funzione si invia l'annullamento della sottoscrizione all'argomento sottoscritto in precedenza. Lo stato della sottoscrizione è indicato dall'uscita q_xActive. Una nuova sottoscrizione è consentita solo se l'uscita q_xActive è impostata a FALSE.

Una volta che l'argomento specificato è sottoscritto correttamente, i dati ricevuti da questo argomento possono essere letti impostando il comando i_xExecute a TRUE.

Quality of Service

Livello di sottoscrizione	Descrizione
QoS0	Gli ultimi dati relativi all'argomento sottoscritto possono essere letti.
QoS1	I messaggi pubblicati con QoS 1 possono essere letti. La sequenza dei messaggi resta invariata (First In First Out). Il primo messaggio ricevuto viene memorizzato nel blocco funzione FB_MqttSubscribe. Può essere letto immediatamente attivando l'esecuzione del blocco funzione. Dopo avere ricevuto il primo messaggio, il blocco funzione è pronto per ricevere il messaggio successivo. Se il messaggio è già stato inviato dal Server MQTT, il blocco funzione attende il duplicato. Il tempo necessario per la consegna del messaggio successivo da parte del blocco funzione dipende dal tempo che il server impiega per inviare il duplicato. Se si utilizza Mosquitto come Server MQTT, possono essere necessari fino a 30 secondi. L'ultimo messaggio con QoS 0 può essere letto se i messaggi QoS 1 inviati in precedenza dal Server MQTT sono stati ricevuti e già letti. Il messaggio QoS 0 ricevuto può essere sovrascritto da un nuovo messaggio in qualsiasi momento.

Livello di sottoscrizione

Descrizione

QoS0

Gli ultimi dati relativi all'argomento sottoscritto possono essere letti.

QoS1

I messaggi pubblicati con QoS 1 possono essere letti. La sequenza dei messaggi resta invariata (First In First Out).

Il primo messaggio ricevuto viene memorizzato nel blocco funzione FB_MqttSubscribe. Può essere letto immediatamente attivando l'esecuzione del blocco funzione. Dopo avere ricevuto il primo messaggio, il blocco funzione è pronto per ricevere il messaggio successivo. Se il messaggio è già stato inviato dal Server MQTT, il blocco funzione attende il duplicato. Il tempo necessario per la consegna del messaggio successivo da parte del blocco funzione dipende dal tempo che il server impiega per inviare il duplicato.

Se si utilizza Mosquitto come Server MQTT, possono essere necessari fino a 30 secondi.
L'ultimo messaggio con QoS 0 può essere letto se i messaggi QoS 1 inviati in precedenza dal Server MQTT sono stati ricevuti e già letti.

Il messaggio QoS 0 ricevuto può essere sovrascritto da un nuovo messaggio in qualsiasi momento.

Interfaccia

Ingresso	Tipo di dati	Descrizione
i_xEnable	BOOL	Il blocco funzione invia una sottoscrizione per l'argomento specificato al Server MQTT connesso su un fronte di salita di questo ingresso. Fare riferimento a Comportamento dei blocchi funzione con gli ingressi i_xEnable, i_xExecute e i_xErrorQuit.
i_stSubscribeTopic	ST_SubscribeTopic	Struttura che specifica l'argomento da sottoscrivere.
i_xExecute	BOOL	Il blocco funzione legge l'ultimo messaggio dell'applicazione ricevuto nell'argomento sottoscritto su un fronte di salita di questo ingresso. Fare riferimento a Comportamento dei blocchi funzione con gli ingressi i_xEnable, i_xExecute e i_xErrorQuit.
i_xErrorQuit	BOOL	Il blocco funzione conferma un errore rilevato indicato da q_xError su un fronte di salita di questo ingresso. Fare riferimento a Comportamento dei blocchi funzione con gli ingressi i_xEnable, i_xExecute e i_xErrorQuit.
i_pbyBuffer	POINTER TO BYTE	Puntatore per il buffer nel quale viene copiato il messaggio ricevuto.
i_udiBufferSize	UDINT	Dimensioni del buffer in byte. NOTA: La lunghezza non deve superare le dimensioni della variabile a cui punta i_pbyBuffer.
i_stTimeout	ST_Timeout	Struttura che specifica i timeout.

Ingresso/uscita	Tipo di dati	Descrizione
iq_fbMqttClient	FB_MqttClient	Riferimento al FB_MqttClient associato utilizzato per lo scambio dati con il Server MQTT.

Uscita	Tipo di dati	Descrizione
q_xActive	BOOL	Indica che è attiva l'esecuzione del blocco funzione. Finché questa uscita è TRUE, il blocco funzione deve essere eseguito ciclicamente.
q_xReady	BOOL	Indica che la sottoscrizione all'argomento specificato è stata inviata correttamente al Server MQTT.
q_xDone	BOOL	Indica che l'ultimo messaggio applicazione ricevuto è stato correttamente copiato nel buffer specificato con l'ingresso i_pbyBuffer.
q_xBusy	BOOL	Indica che la sottoscrizione è in corso.
q_xError	BOOL	Indica che è stato rilevato un errore durante l'esecuzione del blocco funzione.
q_etResult	ET_Result	Fornisce informazioni su stato e diagnostica come valore numerico.
q_sResultMsg	STRING [80]	Fornisce ulteriori informazioni su stato e diagnostica come messaggio di testo.
q_xNewMessageAvailable	BOOL	Indica che è disponibile un nuovo messaggio dell'applicazione all'argomento sottoscritto.
q_udiMessageLength	UDINT	Indica il numero di byte copiati nel buffer specificato con l'ingresso i_pbyBuffer.
q_xTruncated	BOOL	Se questa uscita è impostata a TRUE, il messaggio dell'applicazione copiato è stato troncato.

Uso delle variabili del tipo POINTER TO … o REFERENCE TO …

Il blocco funzione fornisce ingressi e/o ingressi/uscite di tipo POINTER TO… o REFENCE TO…. Utilizzando questo tipo di puntatore o riferimento, il blocco funzione accede all'area di memoria indirizzata. In caso di evento di modifica online, può accadere che le aree di memoria vengano spostate in nuovi indirizzi e che di conseguenza un puntatore o un riferimento non siano più validi. Per evitare errori associati a puntatori non validi, occorre aggiornare ciclicamente le variabili di tipo POINTER TO… o REFERENCE TO… , o almeno all'inizio del ciclo nel quale vengono usate.

ATTENZIONE
	PUNTATORE NON VALIDO Verificare la validità del puntatore quando si utilizzano i puntatori sugli indirizzi e durante l'esecuzione del comando Modifica in linea. Il mancato rispetto di queste istruzioni può provocare infortuni o danni alle apparecchiature.

Diagramma di flusso Unified Modeling Language (UML)

Il seguente diagramma di flusso UML illustra l'interazione con il blocco funzione FB_MqttClient, che deve essere richiamato ciclicamente per elaborare i messaggi ricevuti e rilevare una possibile interruzione della comunicazione con il server.

NOTA: Il diagramma mostra un processo di sottoscrizione corretto e non indica un'eventuale gestione degli errori.