¿Qué es un reason code y un reason string de MQTT?
Los reason codes son la característica de MQTT 5 que convierte una falla muda y desconcertante en una diagnosticable. En 3.1.1, un broker que rechazaba su suscripción a menudo no le daba nada útil; en MQTT 5 le dice por qué. Para un ingeniero de control poniendo en marcha un gateway que no conecta, esta es la diferencia entre adivinar y saber. Esta página explica qué son los reason codes y los reason strings y cómo leerlos durante el diagnóstico.
Reason code y reason string de MQTT en una línea: Un reason code de MQTT es un byte único, presente en la mayoría de los paquetes de reconocimiento y desconexión de MQTT 5, que declara el resultado de una operación, como éxito, no autorizado o filtro de tópico inválido. Un reason string opcional es un texto legible que el servidor puede adjuntar a su lado. Juntos explican por qué un connect, publish, subscribe o disconnect tuvo éxito o falló, en lugar de dejar al cliente adivinando.
Dónde aparecen los reason codes y qué le dicen
Los reason codes viajan en los paquetes de reconocimiento de todo el protocolo: CONNACK para un intento de conexión, PUBACK y PUBREC para una publicación QoS 1 o 2, SUBACK para una suscripción, UNSUBACK y DISCONNECT. Cada uno lleva un byte cuyo valor cae en un rango definido, donde los valores por debajo de 128 significan en general éxito o un desenlace normal y los valores de 128 en adelante significan error. Así, un reason code de SUBACK le dice no solo que su subscribe fue contestado sino si cada filtro de tópico fue concedido, y con qué QoS, o rechazado.
Esto es una ganancia genuina de capacidad sobre MQTT 3.1.1. Bajo 3.1.1 el CONNACK llevaba un conjunto pequeño de códigos de retorno de conexión, pero un SUBACK solo podía señalar una falla con un único valor genérico y no había una forma limpia y estandarizada de que el broker explicara una publicación rechazada o enviara una razón rica al desconectar. MQTT 5 llena esos huecos, que es una de las razones prácticas para preferirlo en cualquier cosa que usted tendrá que poner en marcha y sostener en campo. La comparación más amplia vive en MQTT 3.1.1 versus MQTT 5 para SCADA.
Un caso particularmente útil es el DISCONNECT iniciado por el servidor. En MQTT 5 un broker puede enviar un DISCONNECT a un cliente, con un reason code, antes de cerrar la conexión, así que en lugar de que el socket simplemente desaparezca, el cliente aprende que fue desconectado por, por ejemplo, una acción administrativa, una toma de sesión por otro cliente usando el mismo identificador, o un timeout de keepalive. Esa razón es exactamente lo que usted quiere al diagnosticar un cliente que se cae una y otra vez, porque distingue una falla de red de una decisión deliberada del broker.
Leer los reason strings durante la puesta en marcha
El reason string es el acompañante opcional legible del código. Donde el código es un byte fijo pensado para manejo programático, el reason string es texto libre que el servidor puede aportar para explicar lo específico, por ejemplo nombrando qué filtro de tópico fue rechazado o por qué falló la autorización. Está pensado para bitácoras y diagnóstico, no para que el cliente lo interprete y ramifique sobre él. Un broker bien administrado lo llena con algo sobre lo que un ingeniero leyendo una bitácora pueda actuar.
En la puesta en marcha, lo primero que hay que hacer cuando un gateway no conecta es capturar el reason code del CONNACK. Un código de no autorizado lo apunta a credenciales o a una lista de control de acceso, no a la red; un código que indica que el identificador de cliente no es válido o fue tomado apunta a un identificador duplicado, causa clásica de dos dispositivos peleándose una sesión. Es el mismo hilo diagnóstico que corre por el diagnóstico de un nodo Sparkplug que se pone fuera de línea, donde una toma de sesión o una falla de autenticación puede disfrazarse de enlace inestable.
La disciplina es registrar el reason code y el string en cada nivel, connect, subscribe y disconnect, en lugar de solo anotar que una operación falló. Un gateway que registra apenas desconectado no le dice nada; uno que registra desconectado, reason code timeout de keepalive le dice que mire el keepalive y el timeout de inactividad del celular. Los reason strings no arreglan nada por sí mismos, pero convierten una falla de caja negra en un punto de partida, que es la mayor parte de la batalla cuando el sitio queda a horas de camino.
Preguntas frecuentes
¿Los reason codes están disponibles en MQTT 3.1.1?
Solo en forma limitada. MQTT 3.1.1 tiene códigos de retorno de conexión en el CONNACK y una indicación genérica única de falla en el SUBACK, pero carece de los reason codes amplios y consistentes y de los reason strings opcionales que MQTT 5 adjunta a los reconocimientos de publicación, al unsubscribe y al disconnect. Los diagnósticos más ricos de los reason codes de MQTT 5 son una de las razones concretas para correr la versión 5 en cualquier cosa que deba ponerse en marcha y sostenerse remotamente.
¿Mi cliente debería ramificar su lógica sobre el reason string?
No. Ramifique sobre el reason code, que es un byte definido con significado estable entre brokers, y trate el reason string puramente como texto diagnóstico legible para las bitácoras. El reason string es texto libre que un servidor puede o no aportar y puede redactar distinto que otro broker, así que interpretarlo para dirigir la lógica vuelve frágil a su cliente. Regístrelo textual para que un ingeniero pueda leerlo, y tome las decisiones programáticas a partir del reason code numérico.
Fuentes y lecturas
Referencias primarias de los organismos de normas y reguladores que definen este tema:
- MQTT Version 5.0 Specification - OASIS
Servicios de automatización
¿Necesita convertir esta información en un sistema que funcione?
Merobix integra SCADA, programa PLC Allen-Bradley y Siemens, y diseña y fabrica tableros de control industrial.
Las solicitudes de reunión se revisan antes de confirmarse.