[Tuto] Installer Theengs Gateway sur Debian 12

Madcow · Octobre 11, 2023, 3:59

Bonjour,

Theengs Gateway (https://gateway.theengs.io/) est une application qui sert à décoder les données transmises par des périphériques BLE, et les renvoyer vers un broker MQTT comme Mosquitto par exemple.on français

Ces informations transmises par cette passerelle (GateWay en bon français) au broker MQTT peuvent ensuite être récupéré par le plugin MQTT-Discovery qui créera les équipements et commandes correspondants automatiquement.

L’installation de Theengs Gateway (programme python) est normalement simple, mais si vous tapez la commande d’installation sous Debian12 vous verrez ce message :

root@VM-Theengs:~# pip install TheengsGateway
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Il s’agit d’une sécurité mise en place sous Debian 12 pour éviter qu’il y ait conflit entre le gestionnaire de package installé par défaut apt, et celui de python pip.
C’est gentil tout ça, mais comment installer alors Theengs Gateway sous Debian 12 quand on n’est pas comme moi une bête en python ?

Il est dit qu’il faut installer dans un environnement virtuel (venv pour les intimes), mais comment fait-on ?
Nous allons utilise un gestionnaire de paquet python évolué : pipx

Réaliser toutes les étapes sous root (pour pouvoir ensuite lancer le service sans problème).
2 options :

passer par sudo, mais qui n’est pas installé de base sous Debian
passer par su - (conseillé)

Etape 1 : installer les paquets nécessaires

apt install python3-pip

apt install pipx

Etape 2 : installer Theengs Gateway avec pipx

pipx install TheengsGateway

qui doit donner après un temps d’attente variable selon la puissance de la machine (cela peut prendre plusieurs dizaines de mintes sous Pi0!) :

  installed package theengsgateway 1.1.0, installed using Python 3.11.2
  These apps are now globally available
    - TheengsGateway
⚠️  Note: '/root/.local/bin' is not on your PATH environment variable. These apps will not be globally accessible until your PATH is updated. Run `pipx
    ensurepath` to automatically add it, or manually modify your PATH in your shell's config file (i.e. ~/.bashrc).
done! ✨ 🌟 ✨

Theengs Gateways est maintenant disponible sous le chemin suivant :

/root/.local/bin

Etape 3 : Finalisation de l’installation

pipx ensurepath

qui doit donner :

Success! Added /root/.local/bin to the PATH environment variable.

Consider adding shell completions for pipx. Run 'pipx completions' for instructions.

You will need to open a new terminal or re-login for the PATH changes to take effect.

Otherwise pipx is ready to go! ✨ 🌟 ✨

Etape 4 : Vérification que le package BlueTooth est installé

hciconfig

Si le retour est :

-bash: hciconfig: command not found

alors taper pour installer les paquets nécessaires :

apt install bluetooth

Etape 5 : Configuration de Theengs Gateway pour lui indiquer le chemin du broker MQTT

/root/.local/bin/TheengsGateway -H IP_DU_BROKER -u UTILISATEUR -p MOT_DE_PASSE

Cela démarre Theengs et le retour doit être du type :

INFO:BLEGateway:Connected to MQTT Broker!
INFO:BLEGateway:Subscribed to home/+/BTtoMQTT/undecoded
INFO:BLEGateway:Starting BLE scan

Appuyer 2 fois de suite sur la combinaison de touche CTRL+C pour arrêter l’application

Etape 6 : Création du service pour que Theengs Gateways démarre tout seul

Créer le fichier de configuration du service en tapant :

nano /etc/systemd/system/TheengsGateway.service

Puis ajouter :

[Unit]
Description=Theengs Gateway
After=network-online.target
[Service]
Restart=always
Type=simple
ExecStart=/root/.local/bin/TheengsGateway -pt "home/TGW1/BTtoMQTT" -Lt "home/TGW1/LWT"

[Install]
WantedBy=multi-user.target

Enregistrer avec la combinaison de touche CTRL+X, puis Y.

IMPORTANT
Il n’est pas nécessaire de lancer Theengs avec les paramètres -pt "home/TGW1/BTtoMQTT" -Lt "home/TGW1/LWT" mais ceux-ci sont utiles si vous avez plusieurs « antennes » afin de les différencier dans le broker MQTT.
Vous rentrez ainsi « 1 » pour l’antenne « 1 », « 2 » pour l’antenne « 2 », « 3 » pour l’antenne … Qui a dit « pour l’antenne 25 » ??? Tu sors !

Etape 7 : activer et lancer le service

A ne faire qu’à la création du service. Ensuite le système gère tout.

systemctl daemon-reload
systemctl enable --now TheengsGateway.service

Etape 8 : Vérification que le service est lancé et fonctionne

Taper :

systemctl status TheengsGateway

Vous devez obtenir quelque chose du type :

* TheengsGateway.service - Theengs Gateway
     Loaded: loaded (/etc/systemd/system/TheengsGateway.service; enabled; preset: enabled)
     Active: active (running) since Wed 2023-10-11 11:39:32 UTC; 6s ago
   Main PID: 6816 (TheengsGateway)
      Tasks: 2 (limit: 28099)
     Memory: 23.0M
        CPU: 325ms
     CGroup: /system.slice/TheengsGateway.service
             `-6816 /root/.local/pipx/venvs/theengsgateway/bin/python /root/.local/bin/TheengsGateway -pt home/TGW1/BTtoMQTT -Lt home/TGW1/LWT

Oct 11 11:39:32 Test-Theengs-Debian12 systemd[1]: Started TheengsGateway.service - Theengs Gateway.
Oct 11 11:39:33 Test-Theengs-Debian12 TheengsGateway[6816]: INFO:BLEGateway:Starting BLE scan
Oct 11 11:39:33 Test-Theengs-Debian12 TheengsGateway[6816]: INFO:BLEGateway:Connected to MQTT Broker!
Oct 11 11:39:33 Test-Theengs-Debian12 TheengsGateway[6816]: INFO:BLEGateway:Subscribed to home/+/BTtoMQTT/undecoded
Oct 11 11:39:35 Test-Theengs-Debian12 TheengsGateway[6816]: INFO:BLEGateway:publishing device `{'name': 'ClearGrass Temp & RH', 'id': '58:2D:34:10:CB:E8', 'rssi': -83, 'brand': 'ClearGrass/Qingping', 'model': 'Round TH', 'model_id': '>

Appuyer 2 fois de suite sur la combinaison de touche CTRL+C pour sortir.

Etape 9 : Ouverture d’une bière

Merci à @Mips et @piug pour ce tuto

xavax59 · Novembre 29, 2023, 9:30

Merci pour ce tuto,
Je viens d’installer une VM sur debain 12 dans proxmox, avant de me lancer dans le tuto, je voudrais savoir si je ne dois pas faire en sorte que le Blutooth soit accessible dans ma VM mais je ne sais pas comment faire.

Madcow · Novembre 29, 2023, 9:50

Il faut passer ta clé ou ton contrôleur à la VM. Passthrough c’est appelé.

Tonio16 · Décembre 2, 2023, 2:38

Bonjour

Si on veut avoir plusieurs clés, que mettre exactement pour les topics dans sa config? Sachant que je voudrais ensuite que cela soit visible par le plugin mqtt discovery.

Ici ma config docker compose:

services:
  gateway:
    image: theengs/gateway
    network_mode: host
    container_name: theengs-gateway
    environment:
       - MQTT_HOST=192.168.1.147
       - MQTT_USERNAME=<jeedom>
       - MQTT_PASSWORD=<jeedom>
       - MQTT_PUB_TOPIC=home/theengs2/BTtoMQTT #
       - MQTT_SUB_TOPIC=home/+/BTtoMQTT/undecoded #
       - MQTT_PRE_TOPIC=home/presence/TheengsGateway #
       - LWT_TOPIC=home/theengs2/LWT
       - PRESENCE=true #
       - PUBLISH_ALL=true #
       - TIME_BETWEEN=60
       - SCAN_DUR=10 #
       - SCAN_TIME=60
       - LOG_LEVEL=ERROR
       - HASS_DISCOVERY=true
       - DISCOVERY=true
       - DISCOVERY_TOPIC=homeassistant/sensor
       - DISCOVERY_DEVICE_NAME=theengs
       - DISCOVERY_FILTER=[IBEACON,GAEN,MS-CDP,APPLE_CONT,APPLE_CONTAT]  #
       - SCANNING_MODE=active
       - ADAPTER=hci0

Si j’ai MQTT_PUB_TOPIC=home/theengsIDAntenne/BTtoMQTT
Est-ce ok pour:
LWT_TOPIC=home/theengsIDAntenne/LWT
DISCOVERY_TOPIC=homeassistant/sensor
DISCOVERY_DEVICE_NAME=theengsIDAntenne

Merci

Antoine

Mips · Décembre 2, 2023, 2:47

ca c’est comme tu veux (ca ne remontera pas dans mqttdiscovery

non, juste homeassistant c’est le défaut d’ailleurs non?

Tonio16 · Décembre 2, 2023, 2:58

Dans le fichier que j’ai trouvé, c’était avec /sensor en plus. Mais dans les deux cas, je ne vois rien qui apparait sous le topic homeassitant pour Theengs. Faut-il que ce soit des appareils bluetooth supportés pour y être publiés ?

Antoine

Mips · Décembre 2, 2023, 3:05

oui, supporté par theengs

mais si c’est pour la gestion de présence alors plugin-mqttdiscovery peut gérer même si pas supporté par theengs:

Tonio16 · Décembre 2, 2023, 5:00

Ok, mais pour l’instant avec mon installation docker-compose, la partie home assistant reste vide en fait donc même avec cette option de cochée, je ne vois rien.

Antoine

Mips · Décembre 2, 2023, 5:07

c’est normal, homeassistant restera toujours vide pour les devices non reconnus