Notifications MQTT

Aperçu

• Source: https://mqtt.org/
• Prise en charge des images: Non
• Prise en charge des pièces jointes: Non
• Limites de caractères des messages:
  • Corps: 32768
• Créer votre URL Apprise

Configuration du compte

La prise en charge MQTT necessite paho-mqtt, dans une version inferieure a v2, pour fonctionner :

pip install "paho-mqtt<2.0"

Syntaxe

La syntaxe valide est la suivante :

• mqtt://{host}/{topic}
• mqtt://{host}:{port}/{topic}
• mqtt://{user}@{host}:{port}/{topic}
• mqtt://{user}:{password}@{host}:{port}/{topic}

Pour une connexion securisee, utilisez simplement mqtts a la place.

• mqtts://{host}/{topic}
• mqtts://{host}:{port}/{topic}
• mqtts://{user}@{host}:{port}/{topic}
• mqtts://{user}:{password}@{host}:{port}/{topic}

Les connexions securisees doivent etre referencees avec mqtts://, tandis que les connexions non securisees doivent utiliser mqtt://.

Détail des Paramètres

Variable	Obligatoire	Description
user	Non	Utilisateur associe a votre serveur MQTT.
password	Non	Mot de passe associe a votre serveur MQTT.
hostname	Oui	Serveur MQTT auquel vous envoyez votre notification.
port	Non	Port sur lequel le serveur MQTT ecoute. Par defaut, il s’agit de 1883 pour mqtt:// et de 8883 pour toutes les references mqtts://.
qos	Non	Parametre MQTT Quality of Service, QoS. Par defaut, la valeur 0, zero, est utilisee.
version	Non	Version du protocole MQTT a utiliser. Par defaut, la valeur v3.1.1 est utilisee. Les autres valeurs possibles sont v3.1 et v5.
client_id	Non	Identifiant client MQTT a utiliser lors de l’etablissement de la connexion avec le serveur. Par defaut, il n’est pas defini et un identifiant unique est genere pour chaque message.
session	Non	Session MQTT a maintenir, associee a client_id. Si aucun client_id n’est precise, cette valeur n’est pas prise en compte. Par defaut, aucune session n’est etablie et chaque connexion effectuee par Apprise est unique. Si vous souhaitez imposer une session, associee a un client_id fourni, definissez cette valeur sur True.
retain	Non	Drapeau MQTT publisher retain. Par defaut, cette option vaut no, mais vous pouvez facultativement la surcharger et la definir sur yes.

Paramètres Globaux

Variable	Description
overflow	Ce paramètre peut être défini sur split, truncate ou upstream. Il détermine la manière dont Apprise remet le message que vous lui transmettez. Par défaut, il vaut upstream. 👉 upstream : ne fait aucune modification et transmet le message exactement tel qu’il a été reçu au service. 👉 truncate : veille à ce que le message tienne dans la limite amont documentée par le service. Si plus d’informations sont fournies que la limite définie, l’excédent est tronqué. 👉 split : similaire à truncate, sauf que si le message dépasse la limite amont documentée par le service, il est découpé en plusieurs morceaux plus petits puis envoyés séquentiellement.
format	Ce paramètre peut être défini sur text, html ou markdown. Certains services prennent en charge plusieurs formats de publication du contenu. La valeur par défaut varie selon le service choisi et peut correspondre à l’un de ces trois formats. Vous pouvez facultativement forcer cette option pour vous écarter du comportement par défaut. Si le service ne prend pas en charge plusieurs formats de transmission, ce champ est ignoré.
verify	Les requêtes externes vers des emplacements sécurisés, par exemple via https, utilisent des certificats. Par défaut, Apprise vérifie la validité de ces certificats ; si ce n’est pas le cas, aucune notification n’est envoyée à la source. Dans certains cas, un utilisateur ne dispose pas d’une autorité de certification pour valider la clé ou fait simplement confiance à la source ; dans ce cas, vous pouvez définir ce drapeau sur no. Par défaut, il vaut yes.
cto	Signifie Socket Connect Timeout. Il s’agit du nombre de secondes pendant lesquelles Requests attend que votre client établisse une connexion avec une machine distante, ce qui correspond à l’appel connect() sur la socket. La valeur par défaut est de 4.0 secondes.
rto	Signifie Socket Read Timeout. Il s’agit du nombre de secondes pendant lesquelles le client attend que le serveur envoie une réponse. La valeur par défaut est de 4.0 secondes.
emojis	Active la prise en charge des emojis, par exemple :+1: qui sera traduit en 👍. Par défaut, cette option vaut no. Remarque : selon la configuration côté serveur, l’administrateur peut désactiver globalement la prise en charge des emojis ; mais par défaut, ce n’est pas le cas.
tz	Identifie le fuseau horaire de la base IANA que vous souhaitez utiliser. Par défaut, celui-ci est détecté à partir de la configuration du serveur qui exécute Apprise. Vous pouvez le définir sur des valeurs comme America/Toronto, ou sur tout autre fuseau correctement formaté correspondant à votre région.

Exemples

# Supposons que nous executons simplement un serveur MQTT localement sur notre machine
# Supposons que nous voulions publier notre message sur le topic `my/topic`
apprise -vvv -b "whatever-payload-want" "mqtt://localhost/my/topic"

Test

Voici ce qui a ete fait pour tester ce service localement, avec Docker :

# Recuperer Mosquitto, version v2.x a l'epoque, le 16 septembre 2021
docker pull eclipse-mosquitto

# Creer un emplacement pour la configuration
mkdir mosquitto
cd mosquitto
cat << _EOF > mosquitto.conf
persistence false
allow_anonymous true
connection_messages true
log_type all
listener 1883
_EOF

# Lancer ensuite une instance, que l'on pourra interrompre avec Ctrl-C :
docker run --name mosquitto -p 1883:1883 \
   --rm -v $(pwd)/mosquitto.conf:/mosquitto/config/mosquitto.conf \
   eclipse-mosquitto

# Tous les tests Apprise peuvent ensuite etre effectues contre l'IP de ce systeme, par exemple :
apprise -vvv -b "my=payload" "mqtt://localhost/a/simple/topic"

# Voici un exemple avec le drapeau `retain` active :
apprise -vvv -b "my=payload" "mqtt://localhost/a/simple/topic?retain=yes"