MQTT
La communication entre les modules et le serveur ainsi qu'entre les modules est effectuée par des message MQTT.
Il existe xxx type de messages :
1) Message de commande à destination d'un module
2) Message d'event à destination d'un module
3) Message de statut (Etat) d'un module vers le serveur
NOTE :
A partir de la version 2.x04 il est possible de définir un domaine MQTT, ceci afin de partager un serveur MQTT.
Tous les topics effectivement émis sont alors précédés du domaine, mais il n'est pas nécessaire de le spécifier, la concaténation est transparente pour les messages envoyés et reçus.
Le domaine pour chaque module, est défini dans le config.ini (.........)
Note de syntaxe : La séparation entre attributs peut être effectué soit par le symbole & soit par le symbole +
exemple :
mosquitto_pub -h hostName -t MQTT_Topic_NameOfModule -m "CALL?file=pub&fct=maFct1"
ou
mosquitto_pub -h hostName -t $ MQTT_Topic_NameOfModule -m CALL?file=pub+fct=maFct1
1. Message de commande à destination d'un module
Il existe différentes commandes implémentées :
- CALL
- PUB
- VAR
- BACKUP
La syntaxe du message est
CMD?attribut1=value1&attribut2=value2...
ou
CMD?attribut1=value1+attribut2=value2...
Rem : une réponse est transmise de l'appelé vers l'appelant uniquement si l'attribut from est renseigné
Dans le cas de l'utilisation de Domain, l'attribut domain doit être renseigné
CALL
Un appel MQTT peut lancer l'appel d'un processus dans le module. Le comportement est identique à l'URL /CALL
La syntaxe du message est
CALL?file=testA&fct=test1
ou
CALL?file=testA+fct=test1
Cette technique est intéressante si le serveur MQTT n'a pas accès sur l'IP du module (par exemple un serveur MQTT externe sans accès au LAN des modules)
exemple (Pour une cible nommée Dgl_ESP_07):
mosquitto_pub -h 192.168.0.52 -t Dgl_ESP_07 -m "CALL?file=pub&fct=maFct1"
ou
mosquitto_pub -h 192.168.0.52 -t Dgl_ESP_07 -m CALL?file=pub+fct=maFct1
Remarque : Dans le cas de l'usage du signe "&" les "" sont nécessaire pour délimiter le message
PUB
Un appel MQTT peut demander la liste des fonctions publiques (identique à l'URL /PUB). Ces fonctions sont définies dans pub.xml du module
La syntaxe du message est
PUB?from=callerName
le module alors répondra
!PUB<CRLF>
variable=value
...
exemple :
!PUB
Info=Terrasse Est / Bureau
maFct1=Appliques
maFct2=Tunnel
maFct3=Gare
VAR
Un appel MQTT avec la commande VAR permet de demander / partager le contenu d'une variable d'un module.
L'usage du message VAR est de deux ordres :
- Le serveur central demande le contenu d'une variable à un module
- Un module publie une (ou plusieurs) variables
1) Demande de variable
Dans ce cas, la demande a la forme :
VAR?from=source+global=var1,var2,var3....+local=var1,var2,var2+sys=var1,var2,...
- from pour définir le demandeur
- global pour énumérer les variables globales demandées
- local pour les variables locales
- sys pour les variables système
La réponse aura la forme :
!VAR?fromDevice+var1=xxxx+var2=xxx...
exemple :
VAR?from=MirTOS+sys=FreeHeap,MAC
1) publication d'une variable
Dans ce cas, le module publiera sous la forme
VAR?fromDevice+var1=xxxx+var2=xxx...
- from pour définir le demandeur
- global pour énumérer les variables globales demandées
- local pour les variables locales
- sys pour les variables système
Seules les variables globales définies dans le config.ini du device sous la reubrique [Export] sont publiées automatiquement
BACKUP
Un appel MQTT avec la commande BACKUP permet de demande au module d'envoyer un TAR de ses fichiers (config.ini, main.xml,...)
L'appel se fait ainsi :
BACKUP?from=source
La réponse a la forme :
!BACKUP?from=device+size=xxx<CRLF>
<DATA>
RESTORE
Un appel MQTT avec la commande RESTORE permet d'envoyer au module un TAR de ses fichiers (config.ini, main.xml,...)
L'appel se fait ainsi :
RESTORE?from=source+file=xxx+size=xxx
EXEC
Un appel MQTT avec la fonction EXEC permet de demander l'exécution d'une commande :
EXEC?from=callerName+fct=fct
exemple :
EXEC?from=MirTOS+fct=RT();
STATE
Un appel MQTT avec la fonction STATE permet de demander ou d'envoyer l'état du module :
cf le point (3) plus bas
2. Message d'event à destination d'un module (MQTT xxx-Slave message)
Le Topic utilisé pour transmettre un message à un slave est le nom du slave cible.
Ainsi le message envoyé au module 'myDevice1' devra être envoyé avec un topic 'myDevice1'
Le message, quant à lui, fera référence à l'action demandé.
Ainsi si dans le device 'myDevice1' on a (dans le main.xml) le sous arbre :
<M>
<tgl......1.>IDP(0,4,tgl_1 );</tgl......1.>
<tgl......0.>IDP(0,4,tgl_0 );</tgl......0.>
<toto>IDP(0,4,toto!);</toto>
</M>
alors l'envoi du message
MQ(myDevice1,toto);
déclenchera l'affichage (IDP) du message 'toto!' sur l'écran
Remarque :
Les événements sont traités avec un Regex, ainsi l'envoi du message
MQ(myDevice1,tgl00000000);
déclenchera l'action IDP(0,4,tgl_0 );
puisque les '.' peuvent être remplacés par n'importe quel symbole
Un exemple sur les cartes sans contact ou l'arrivée de jeton est donné dans le chapitre RS232
3. MQTT Message d'état - Topic MirTOS
Le Topic de ces messages sont définis dans le config de chaque module sous la variable General/MQTT_Topic. Habituellement, le topic utilisé est MirTOS
Chaque module envoie des messages MQTT vers le serveur afin de l'informer de son statut. Les messages ont la forme suivante :
Syntaxe :
DeviceID/Key1=value1{&KeyN=valueN}
DeviceID should be unique
NOTE : A partir de la version 2.x04, la syntaxe devient :
STATE?FROM=deviceID&Key1=value1{&KeyN=valueN}
exemple :
STATE?FROM=Dgl_ESP_07&E=RSTAT&R=000X&P=0076&B=100&TS=20230111151600
STATE?FROM=TerrSud&E=RSTAT&R=000X&P=0080&B=000&TS=20230111151601
Key :
MAC : MAC Address - Mandatory on startup (first msg) / exemple : MAC=AC:67:B2:24:25:D8
IP : IP Address - Mandatory on startup (first msg) / exemple : IP=192.168.0.82
DN : Device Name - should be the same as DeviceID
N : Depreciated - Device Nam. New design should use DN / exemple E=T_Sud
HT : Hardware type / exemple :
T : Depreciated - Harware type. New design should use HT
AP : Access Point used
E : Event message / enum of {START,STATE,FCTRY,RSTAT}, exemple E=START
START : module is starting
STATE : Message has been sent using MQTTSentState
RSTAT : Automatic recurent state message (setted by MQTT_Time in config)
FM : Specific (free) Message FM=Anything
E : Depreciated : get specific info exemple E=B000L+0015S0000U0000 should be rempaced by FM=xxx
R : Relay state (4 digits), X Relay not available. Exemple : R=001x
P : Analogic level (0..1023). exemple P=0001
TS : Timestamp (en LT) - exemple : TS=20210201040028
RC : Reconnect count (MQTT reconnect count). exemple RC=0
4. Autres messages
Un module peut envoyer un message 'libre' à un autre module / serveur.
C'est par exemple le cas pour la remontée d'une carte à puce à destination d'un serveur de contrôle
Dans ce cas, le module enverra le message en utilisant un Topic spécifique.
exemple :
<RS>
<M.........>MQ(CardServer,CC(DR1_,SLF(GS(lastRSMsg),10)));</M.........>
</RS>
Enverra un message MQTT avec le topic CardServer et le message DR1_xxxxxxxxx où xxxxxxxx sont les 10 caract du code de la carte.
Ce type de message est spécifique et n'est pas traité par cette documentation. L'implémentation d'un CardServer devrait fournir le service de traitement de cette demande, et l'envoi en réponse, à une porte, l'autorisation d'ouverture, ou pas....soit par un message d'Event (le plus efficace) soit avec une commande CALL.
Remarque : Le serveur de test utilise une table d'action en DB (table MirTOS_MQTT_Actions). Selon le topic du message reçu, un traitement de 'register' ou de 'card check' sera effectué :
SELECT Topic,QOS,MsgFrom,Filter,Action FROM MirTOS_MQTT_Actions;
MirTOS|0|*||register:%Payload%
CardServer|0|*|DR1_|checkCard:%Payload%
CardServer|0|*|DR2_|checkCard:%Payload%
Résumé :
Communication Any to any
COMMAND
xxx ---> AnyCommand?from=source ---> Module
|
[xxx <--- !AnyCommand CRLF responds <---- ] responds IF "from" is specified
Commands : CALL and PUB :
xxx ---> CALL?file=pub&fct=maFct3 ---> Module
exec call
|
xxx <--- !CALL <----- réponse uniquement si from=xxx est spécifié à l'appel
xxx ---> PUB?from=source ---> Module
|
xxx <--- !PUB CRLF Message <-----
FIXME : BACKUP / RESTORE
OTHER
xxx ---> Other (not a command) ---> Module
=> main.xml event : <M><Other>...</Other></M>
Communication Device to Server (State)
OLD (should not be used):
Server <--- module/state_message <--- Module Comment : cannot start with !
New syntaxe :
Server <--- STATE?from=src&key=val... <--- Module
Créé avec HelpNDoc Personal Edition: Produire des livres Kindle gratuitement