FB_MqttSubscribe

Descripción general

Tipo:	Bloque de funciones
Disponible desde:	V1.0.0.0

Descripción de funciones

El bloque de funciones FB_MqttSubscribe permite gestionar la suscripción a un tema específico en el Servidor MQTT.

Se admiten las funciones siguientes:

Suscripción al tema especificado
Cancelación de la suscripción al tema especificado
Lectura de los datos en función del tema suscrito

El bloque de funciones utiliza la conexión con el Servidor MQTT establecida anteriormente mediante el FB_MqttClient.

Una vez activado el bloque de funciones, se enviará la suscripción al tema especificado al conectado Servidor MQTT. El estado de la suscripción y, con ello, la posibilidad de recibir datos, se indican mediante la salida q_xReady. Los nuevos datos recibidos se indican mediante la salida q_xNewMessage.

Al deshabilitar el bloque de funciones, se envía la cancelación de la suscripción al tema anteriormente suscrito. El estado de la cancelación de la suscripción se indica mediante la salida q_xActive. Solo se permitirá una nueva suscripción si se ajusta la salida q_xActive en FALSE.

Una vez suscrito correctamente al tema especificado, ya podrán leerse los datos recibidos sobre dicho tema; para ello, deberá ajustarse el comando i_xExecute en TRUE.

Calidad de servicio

Nivel de suscripción	Descripción
QoS 0	Pueden leerse los últimos datos relacionados con el tema suscrito.
QoS 1	Pueden leerse los mensajes publicados con QoS 1. La secuencia de los mensajes no sufrirá cambios (primero en entrar, primero en salir). El primer mensaje recibido se guardará en el bloque de funciones FB_MqttSubscribe. Puede leerse inmediatamente activando la ejecución del bloque de funciones. Una vez recibido el primer mensaje, el bloque de funciones ya está listo para recibir el siguiente. Si el mensaje ya se ha enviado desde el Servidor MQTT, el bloque de funciones esperará la llegada del duplicado. El tiempo que transcurrirá hasta que el bloque de funciones entregue el mensaje siguiente dependerá del tiempo que transcurra hasta que el servidor envíe el duplicado. Si utiliza Mosquitto como Servidor MQTT, el tiempo podría extenderse hasta los 30 segundos. El último mensaje con QoS 0 podrá leerse siempre que los mensajes con QoS 1 enviados anteriormente por el Servidor MQTT ya se hayan recibido y leído. El mensaje recibido con QoS 0 puede sobrescribirse en cualquier momento con un nuevo mensaje.

Nivel de suscripción

Descripción

QoS 0

Pueden leerse los últimos datos relacionados con el tema suscrito.

QoS 1

Pueden leerse los mensajes publicados con QoS 1. La secuencia de los mensajes no sufrirá cambios (primero en entrar, primero en salir).

El primer mensaje recibido se guardará en el bloque de funciones FB_MqttSubscribe. Puede leerse inmediatamente activando la ejecución del bloque de funciones. Una vez recibido el primer mensaje, el bloque de funciones ya está listo para recibir el siguiente. Si el mensaje ya se ha enviado desde el Servidor MQTT, el bloque de funciones esperará la llegada del duplicado. El tiempo que transcurrirá hasta que el bloque de funciones entregue el mensaje siguiente dependerá del tiempo que transcurra hasta que el servidor envíe el duplicado.

Si utiliza Mosquitto como Servidor MQTT, el tiempo podría extenderse hasta los 30 segundos.
El último mensaje con QoS 0 podrá leerse siempre que los mensajes con QoS 1 enviados anteriormente por el Servidor MQTT ya se hayan recibido y leído.

El mensaje recibido con QoS 0 puede sobrescribirse en cualquier momento con un nuevo mensaje.

Interfaz

Entrada	Tipo de datos	Descripción
i_xEnable	BOOL	El bloque de funciones envía una suscripción al tema especificado al Servidor MQTT conectado en un flanco ascendente de esta entrada. Consulte Comportamiento de los bloques de funciones con las entradas i_xEnable, i_xExecute y i_xErrorQuit.
i_stSubscribeTopic	ST_SubscribeTopic	Estructura en la que se especifica el tema al que desea suscribirse.
i_xExecute	BOOL	El bloque de funciones lee el último mensaje de aplicación recibido sobre el tema suscrito en un flanco ascendente de la entrada. Consulte Comportamiento de los bloques de funciones con las entradas i_xEnable, i_xExecute y i_xErrorQuit.
i_xErrorQuit	BOOL	El bloque de funciones confirma el error detectado indicado por q_xError en un flanco ascendente de esta entrada. Consulte Comportamiento de los bloques de funciones con las entradas i_xEnable, i_xExecute y i_xErrorQuit.
i_pbyBuffer	POINTER TO BYTE	Puntero del búfer en el que se copia el mensaje recibido.
i_udiBufferSize	UDINT	Tamaño del búfer en bytes. NOTA: La longitud no deberá superar el tamaño de la variable a la que apunta i_pbyBuffer.
i_stTimeout	ST_Timeout	Estructura en la que se especifican los tiempos de espera.

Entrada/salida	Tipo de datos	Descripción
iq_fbMqttClient	FB_MqttClient	Referencia al FB_MqttClient asociado empleado para el intercambio de datos con el Servidor MQTT.

Salida	Tipo de datos	Descripción
q_xActive	BOOL	Indica que la ejecución del bloque de funciones permanece activa. Mientras la salida muestre TRUE, el bloque de funciones deberá ejecutarse de manera cíclica.
q_xReady	BOOL	Indica que la suscripción al tema especificado se ha enviado correctamente al Servidor MQTT.
q_xDone	BOOL	Indica que el último mensaje recibido de la aplicación se ha copiado correctamente en el búfer especificado con la entrada i_pbyBuffer.
q_xBusy	BOOL	Indica que la suscripción está en curso.
q_xError	BOOL	Indica que se ha detectado un error durante la ejecución del bloque de funciones.
q_etResult	ET_Result	Proporciona información de diagnóstico y estado en forma de valor numérico.
q_sResultMsg	STRING [80]	Proporciona información adicional de diagnóstico y estado en forma de mensaje de texto.
q_xNewMessageAvailable	BOOL	Indica que hay disponible un nuevo mensaje de aplicación sobre el tema suscrito.
q_udiMessageLength	UDINT	Indica el número de bytes copiados en el búfer que se ha especificado mediante la entrada . i_pbyBuffer.
q_xTruncated	BOOL	Si esta salida se establece en TRUE, significa que se ha truncado el mensaje de aplicación copiado.

Uso de variables de tipo POINTER TO … o REFERENCE TO …

Este bloque de funciones proporciona entradas o entradas y salidas de tipo POINTER TO… o REFENCE TO…. Al utilizar un puntero o una referencia de este tipo, el bloque de funciones accede al área de memoria dirigida. En el caso de un evento de cambio online, es posible que las áreas de memoria se desplacen hacia nuevas direcciones y que, en consecuencia, un puntero o una referencia pasen a ser no válidos. Para evitar la presencia de errores relacionados con punteros no válidos, las variables de tipo POINTER TO… o REFERENCE TO… deberán actualizarse de manera cíclica o, al menos, al principio del ciclo en el que se utilicen.

ATENCIÓN
	PUNTERO NO VÁLIDO Verifique la validez de los punteros al utilizarlos en direcciones y ejecutar el comando Cambio en línea. Si no se siguen estas instrucciones, pueden producirse lesiones o daños en el equipo.

Diagrama de secuencia de lenguaje unificado de modelado (UML)

En el siguiente diagrama de secuencia de UML se ilustra la interacción con el bloque de funciones FB_MqttClient, el cual necesita ejecutarse de manera cíclica para procesar los mensajes recibidos y detectar una posible interrupción de la comunicación con el servidor.

NOTA: En el diagrama se ilustra un proceso de suscripción correctamente realizado, por lo que no se muestra ningún tratamiento de errores.