Module MQTT « mqtt »

Description

Le module MQTT sert à la communication bidirectionnelle avec un broker MQTT.

Plusieurs canaux smartCORE peuvent être affectés à un même topic MQTT, le module permettant de sélectionner plusieurs topics.

Il est en outre possible d'instancier plusieurs modules afin de communiquer simultanément avec plusieurs brokers différents.

Pour l'interprétation et la préparation des payloads MQTT, des « payload hints » sont pris en charge ; ils servent à décrire le format.

Dans le sens de la publication, ils permettent de vérifier la syntaxe des modèles de publication dans lesquels les valeurs de canal consommées sont ensuite insérées (par exemple pour des formats courants comme JSON, XML, ...).

Inversement, dans le sens de l'abonnement (subscribe), ces payload hints permettent de fournir des mécanismes d'extraction de données adaptés aux formats précités, de sorte que les valeurs ainsi extraites puissent être produites dans les canaux smartCORE correspondants.

Interfaces et protocoles utilisés

• MQTT

Configuration JSON

La section suivante décrit l'ensemble de la configuration JSON du module et explique chacun des paramètres.

Exemple de configuration (minimale et typique)

Voici un exemple de configuration minimale :

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

          <MQTT TOPIC KONFIGURATIONEN>

        ]
      }
    }

Exemple de configuration (maximale)

    {
      "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>

        ]
      }
    }

Exemples d'objets JSON pour la configuration des topics...

Les objets JSON suivants peuvent être insérés dans le tableau topics mentionné ci-dessus.

...dans le sens de la publication

Les chaînes indiquées sous mqttName servent ici d'espaces réservés, qui sont remplacés tels quels par les valeurs des canaux smartCORE indiqués sous 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"
        }
    ]
}

...dans le sens de l'abonnement

Les chaînes indiquées sous mqttName décrivent ici comment extraire les données de canal du payload MQTT, ce qui est possible de différentes manières (voir ci-dessous).

  {
    "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"
      }
    ]
  }

Paramètres du module

Nom du paramètre	Requis	Type de données	Plage de valeurs pertinente	Défaut	Description
useLocalBroker	Non	BOOL	true, false	false	Démarre un broker MQTT sur l'appareil et communique avec celui-ci
enabled	Non	BOOL	true, false	true	Activité de la communication avec le broker
pollingIntervalMs	Non	INT	1 -	1000	Intervalle de traitement [ms] propre au module
brokerAddress	Non	STRING	URL de broker valide		"ssl://awe.some.io:8883" , "tcp://awe.some.io:1883" (non recommandé)
brokerAuthentication	Non	BOOL	true, false	true	Authentification auprès du broker
trustStore	Non	STRING		/etc/ssl/certs/ca-certificates.crt	Trust store pour l'authentification auprès du broker
brokerUserId	Non	STRING			Identifiant utilisateur du broker
brokerUserPassword	Non	STRING			Mot de passe utilisateur du broker
brokerClientId	Non	STRING			Identifiant du client/de l'appareil auprès du broker
maxBufferedMessages	Non	INT	1 -	10	Nombre maximal de messages MQTT mis en tampon dans le client MQTT
connectTimeoutS	Non	INT	1 -	10	Timeout pour l'établissement de la connexion
disconnectTimeoutS	Non	INT	1 -	10	Timeout pour la déconnexion après demande
keepaliveIntervalS	Non	INT	1 -	10	Timeout pour la détection d'une connexion interrompue
completionIntervalS	Non	INT	1 -	10	Timeout pour la réception de l'accusé de réception après l'envoi d'un message MQTT
sendingIntervalS	Non	INT	1 -	10	Timeout pour l'envoi d'un message MQTT
topics	OUI	JSON Array			voir Configuration des topics MQTT

Configuration des topics MQTT « topics »

On distingue ici les topics à publier (published) et les topics auxquels s'abonner (subscribed).

Topics à publier (published topics)

Un topic à publier, qui contient en général une sélection de canaux smartCORE, est configuré sous forme d'objet JSON contenant les paramètres suivants.

Nom du paramètre	Requis	Type de données	Plage de valeurs pertinente	Défaut	Description
name	OUI	STRING			Nom/chemin du topic sur le broker
direction	OUI	STRING	"publish"		à régler sur "publish" pour un topic à publier
payload	OUI	STRING			Modèle de payload
payloadHint	OUI	STRING	"plain", "json"	"json"	Sélection du format de payload à transmettre, pour lequel une vérification de la syntaxe du modèle de payload est effectuée si possible
channels	OUI	JSON Array			voir ci-dessous

La configuration des canaux à publier se fait sous forme d'un tableau JSON contenant des objets JSON avec les paramètres suivants.

Nom du paramètre	Requis	Type de données	Plage de valeurs pertinente	Défaut	Description
channelName	OUI	STRING			Nom du canal smartCORE à consommer
mqttName	OUI	STRING			Sous-chaîne du modèle de payload, remplacée par une représentation sous forme de chaîne de la valeur actuelle du canal.
format	NON	STRING			Instruction de formatage pour la conversion de la valeur du canal en chaîne
translateFalse	NON	STRING		"false"	Représentation sous forme de chaîne de la valeur booléenne faux
translateTrue	NON	STRING		"true"	Représentation sous forme de chaîne de la valeur booléenne vrai

Topics auxquels s'abonner (subscribed topics)

Un topic auquel s'abonner, qui fournit en général une sélection de canaux smartCORE, est configuré sous forme d'objet JSON contenant les paramètres suivants.

Nom du paramètre	Requis	Type de données	Plage de valeurs pertinente	Défaut	Description
name	OUI	STRING			Nom/chemin du topic sur le broker
direction	OUI	STRING	"subscribe"		à régler sur "subscribe" pour un topic auquel s'abonner
payloadHint	OUI	STRING	"plain", "json"	"json"	Sélection du format de payload à recevoir, selon lequel s'effectue l'extraction des données vers les canaux configurés.
channels	OUI	JSON Array			voir ci-dessous

La configuration des canaux à publier se fait sous forme d'un tableau JSON contenant des objets JSON avec les paramètres suivants.

Nom du paramètre	Requis	Type de données	Plage de valeurs pertinente	Défaut	Description
channelName	OUI	STRING			Nom du canal smartCORE à produire
dataType	OUI	STRING	type de données smartCORE valide		Type de données du canal
bufferSize	NON	INT	1 -	1024	Taille de tampon du canal
physicalUnit	NON	STRING			Unité physique du canal
mqttName	OUI	STRING			Chaîne décrivant une instruction d'extraction de valeurs de canal individuelles à partir d'un payload (par exemple un chemin pour les payloads JSON)
translateFalse	NON	STRING		"false"	Représentation sous forme de chaîne de la valeur booléenne faux
translateTrue	NON	STRING		"true"	Représentation sous forme de chaîne de la valeur booléenne vrai

Particularités liées au contenu du payload

Extraction directe 1:1 des données (payloadHint "plain")

Dans le sens de l'abonnement (subscribe), l'intégralité du contenu du payload est ici utilisée comme valeur du canal. Une conversion automatique tolérante aux erreurs vers le type de données cible est effectuée, dans la mesure du possible. Inversement, aucune vérification de la syntaxe n'est effectuée dans le sens de la publication.

JSON (payloadHint "json")

Pour extraire des données de canal d'un topic auquel on est abonné et dont le payload est au format JSON, un chemin peut être utilisé comme paramètre "mqttName".

Exemple : le payload reçu contient l'objet JSON suivant.

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

alors "mqttName":"someObject/someSubObject\/with\/slash/someKey" extrait la valeur 42, qui est ensuite produite dans le canal défini comme "channelName" (c'est-à-dire qu'il est nécessaire d'échapper le séparateur "/").

De même, "mqttName":"someArray/1" extrait la valeur 2 de l'objet JSON précité (c'est-à-dire que, dans le cas d'un tableau JSON, la composante du chemin est utilisée comme index).

Si plusieurs séparateurs "/" sont spécifiés à la suite, ils sont considérés comme un seul séparateur.

Si un chemin non valide est spécifié, aucune donnée de canal n'est produite dans tous les cas.

Informations sur le module

Information	Valeur
Auteurs	optiMEAS GmbH
depuis smartCORE	2.6
Type de module	au choix Consumer, Producer ou les deux
Dépendances	broker MQTT existant