Módulo MQTT "mqtt"

Descripción

El módulo MQTT sirve para la comunicación bidireccional con un broker MQTT.

Pueden asignarse varios canales de smartCORE a un mismo topic MQTT, y el módulo permite seleccionar varios topics.

Además, pueden instanciarse varios módulos para comunicarse simultáneamente con varios brokers distintos.

Para la interpretación y preparación de los payloads MQTT se admiten los llamados payload hints, que sirven para describir el formato.

En el sentido de publicación, sirven para realizar una comprobación de sintaxis de las plantillas de publicación en las que se insertan después los valores de canal consumidos (p. ej. para formatos habituales como JSON, XML, ...).

A la inversa, en el sentido de suscripción (subscribe), estos payload hints sirven para proporcionar mecanismos adecuados de extracción de datos para los formatos mencionados, de modo que los valores así extraídos puedan producirse en los canales de smartCORE correspondientes.

Interfaces y protocolos utilizados

• MQTT

Configuración JSON

En la sección siguiente se describe la configuración JSON completa del módulo y se explican los distintos parámetros.

Configuración de ejemplo (mínima y típica)

A continuación se muestra una configuración de ejemplo mínima:

    {
      "module":"MQTT",
      "factory":"mqtt",
      "config":{
        "brokerAddress": "ssl://awe.some.io:8883",
        "brokerUserId": "USER_ID",
        "brokerUserPassword": "USER_PASSWORD",
        "brokerClientId": "CLIENT_ID",
        "topics":[

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Configuración de ejemplo (máxima)

    {
      "module":"MQTT",
      "factory":"mqtt",
      "config":{
        "useLocalBroker":false,
        "enabled":true,
        "pollingIntervalMs":1000,

        "brokerAddress": "ssl://awe.some.io:8883",
        "brokerAuthentication": true,
        "trustStore": "/etc/ssl/certs/ca-certificates.crt",
        "brokerUserId": "USER_ID",
        "brokerUserPassword": "USER_PASSWORD",
        "brokerClientId": "CLIENT_ID",

        "maxBufferedMessages": 10,
        "connectTimeoutS": 10,
        "disconnectTimeoutS": 10,
        "keepaliveIntervalS": 10,
        "completionIntervalS": 10,
        "sendingIntervalS": 10,
        "topics":[

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Ejemplos de objetos JSON para la configuración de topics...

Los siguientes objetos JSON pueden insertarse en la matriz topics mencionada anteriormente.

...en el sentido de publicación

Aquí, las cadenas indicadas en mqttName sirven como marcadores de posición que se sustituyen 1:1 por los valores de los canales de smartCORE indicados en channelName.

{
    "name":"sensor/state",
    "direction":"publish",
    "payload":"{\"voltage\":%BAT_VOLTAGE%,\"current\":%BAT_CURRENT%}",
    "payloadHint":"json",
    "channels":[
        {
            "mqttName":"%BAT_VOLTAGE%",
            "channelName":"PowerSupplyVoltage"
        },
        {
            "mqttName":"%BAT_CURRENT%",
            "channelName":"PowerSupplyCurrent"
        }
    ]
}

...en el sentido de suscripción

Aquí, las cadenas indicadas en mqttName describen cómo deben extraerse los datos del canal del payload MQTT, lo cual es posible de distintas maneras (véase más abajo).

  {
    "name":"sensor/status/switch:0",
    "direction":"subscribe",
    "payloadHint":"json",
    "channels":[
      {
        "mqttName":"power",
        "channelName":"Power",
        "dataType":"float"
      },
      {
        "mqttName":"current",
        "channelName":"Current",
        "dataType":"float"
      },
      {
        "mqttName":"temperature/tC",
        "channelName":"TemperatureTC",
        "dataType":"float"
      }
    ]
  }

Parámetros del módulo

Nombre del parámetro	Obligatorio	Tipo de datos	Rango de valores recomendado	Valor por defecto	Descripción
useLocalBroker	No	BOOL	true, false	false	Inicia un broker MQTT en el dispositivo y se comunica con él
enabled	No	BOOL	true, false	true	Actividad de la comunicación con el broker
pollingIntervalMs	No	INT	1 -	1000	Intervalo de procesamiento del módulo [ms]
brokerAddress	No	STRING	URL de broker válida		"ssl://awe.some.io:8883" , "tcp://awe.some.io:1883" (no recomendado)
brokerAuthentication	No	BOOL	true, false	true	Autenticación del broker
trustStore	No	STRING		/etc/ssl/certs/ca-certificates.crt	Trust store para la autenticación del broker
brokerUserId	No	STRING			Identificador de usuario del broker
brokerUserPassword	No	STRING			Contraseña de usuario del broker
brokerClientId	No	STRING			Identificador de cliente/dispositivo del broker
maxBufferedMessages	No	INT	1 -	10	Número máximo de mensajes MQTT almacenados en búfer dentro del cliente MQTT
connectTimeoutS	No	INT	1 -	10	Timeout para el establecimiento de la conexión
disconnectTimeoutS	No	INT	1 -	10	Timeout para la desconexión tras solicitarla
keepaliveIntervalS	No	INT	1 -	10	Timeout para la detección de una conexión interrumpida
completionIntervalS	No	INT	1 -	10	Timeout para la recepción de la confirmación tras el envío de un mensaje MQTT
sendingIntervalS	No	INT	1 -	10	Timeout para el envío de un mensaje MQTT
topics	SÍ	JSON Array			véase Configuración de topics MQTT

Configuración de topics MQTT "topics"

Se distingue entre topics que se van a publicar (published) y topics a los que se va a suscribir (subscribed).

Topics que se van a publicar (published topics)

Un topic que se va a publicar, que por lo general contiene una selección de canales de smartCORE, se configura como un objeto JSON que contiene los siguientes parámetros.

Nombre del parámetro	Obligatorio	Tipo de datos	Rango de valores recomendado	Valor por defecto	Descripción
name	SÍ	STRING			Nombre/ruta del topic en el broker
direction	SÍ	STRING	"publish"		debe establecerse en "publish" para un topic que se va a publicar
payload	SÍ	STRING			Plantilla de payload
payloadHint	SÍ	STRING	"plain", "json"	"json"	Selección del formato de payload que se va a transmitir, respecto al cual se realiza una comprobación de sintaxis de la plantilla de payload, si es posible
channels	SÍ	JSON Array			véase más abajo

La configuración de los canales que se van a publicar se realiza en forma de matriz JSON que contiene objetos JSON con los siguientes parámetros.

Nombre del parámetro	Obligatorio	Tipo de datos	Rango de valores recomendado	Valor por defecto	Descripción
channelName	SÍ	STRING			Nombre del canal de smartCORE que se va a consumir
mqttName	SÍ	STRING			Subcadena dentro de la plantilla de payload que se sustituye por una representación en cadena del valor actual del canal.
format	NO	STRING			Instrucción de formato para la conversión del valor del canal a cadena
translateFalse	NO	STRING		"false"	Representación en cadena del valor booleano falso
translateTrue	NO	STRING		"true"	Representación en cadena del valor booleano verdadero

Topics a los que se va a suscribir (subscribed topics)

Un topic al que se va a suscribir, que por lo general proporciona una selección de canales de smartCORE, se configura como un objeto JSON que contiene los siguientes parámetros.

Nombre del parámetro	Obligatorio	Tipo de datos	Rango de valores recomendado	Valor por defecto	Descripción
name	SÍ	STRING			Nombre/ruta del topic en el broker
direction	SÍ	STRING	"subscribe"		debe establecerse en "subscribe" para un topic al que se va a suscribir
payloadHint	SÍ	STRING	"plain", "json"	"json"	Selección del formato de payload que se va a recibir, respecto al cual se realiza una extracción de datos a los canales configurados.
channels	SÍ	JSON Array			véase más abajo

La configuración de los canales que se van a publicar se realiza en forma de matriz JSON que contiene objetos JSON con los siguientes parámetros.

Nombre del parámetro	Obligatorio	Tipo de datos	Rango de valores recomendado	Valor por defecto	Descripción
channelName	SÍ	STRING			Nombre del canal de smartCORE que se va a producir
dataType	SÍ	STRING	tipo de datos smartCORE válido		Tipo de datos del canal
bufferSize	NO	INT	1 -	1024	Tamaño del búfer del canal
physicalUnit	NO	STRING			Unidad física del canal
mqttName	SÍ	STRING			Cadena que describe una instrucción para extraer valores de canal individuales de un payload (p. ej. una ruta para payloads JSON)
translateFalse	NO	STRING		"false"	Representación en cadena del valor booleano falso
translateTrue	NO	STRING		"true"	Representación en cadena del valor booleano verdadero

Particularidades relacionadas con el contenido del payload

Extracción directa de datos 1:1 (payloadHint "plain")

En el sentido de suscripción (subscribe), se utiliza aquí todo el contenido del payload íntegramente como valor del canal. Se realiza una conversión automática y tolerante a errores al tipo de datos de destino, siempre que sea posible. A la inversa, no se realiza ninguna comprobación de sintaxis en el sentido de publicación.

JSON (payloadHint "json")

Para extraer datos de canal de un topic suscrito con payload en formato JSON, puede utilizarse una ruta como parámetro "mqttName".

Ejemplo: el payload recibido contiene el siguiente objeto JSON.

{
  "someObject":{
    "someSubObject/with/slash":{
      "someKey": 42
    }
  }
  "someArray":[
    1,
    2,
    3
  ]
}

entonces "mqttName":"someObject/someSubObject\/with\/slash/someKey" extrae el valor 42, que a continuación se produce en el canal definido como "channelName" (es decir, es necesario escapar el separador "/").

De forma análoga, "mqttName":"someArray/1" extrae el valor 2 del objeto JSON anterior (es decir, en el caso de una matriz JSON, el componente de la ruta se utiliza como índice).

Si se especifican varios separadores "/" consecutivos, se consideran como un único separador.

Si se especifica una ruta no válida, en cualquier caso no se produce ningún dato de canal.

Información del módulo

Información	Valor
Autores	optiMEAS GmbH
desde smartCORE	2.6
Tipo de módulo	opcionalmente Consumer, Producer o ambos
Dependencias	broker MQTT disponible