Connecter les contrôleurs PLCnext à Home Assistant pour la domotique

Ce projet de démonstration montre comment utiliser facilement un contrôleur PLCnext comme dispositif domotique dans le logiciel open-source Home Assistant via l'API REST et Modbus TCP. Avec le contrôleur PLCnext, vous pouvez utiliser les composants Axioline dans votre automatisation pour ajouter des sorties plus puissantes que les broches GPIO du Raspberry Pi, des capteurs de température comme les Pt100 et des systèmes de bus comme DALI. Tout ce dont vous avez besoin : une installation Home Assistant fonctionnelle et un contrôleur PLCnext avec un petit projet PLCnext exécutable.

Prérequis

• Home Assistant Core 2021.1.5
• Balena
• PLCnext Engineer 2020.6
• AXC F 2152FW 2020.0 LTS
• Image Raspberry Pi 2 (le démarrage peut prendre une heure)

Bibliothèques

• Modbus_TCP (Build 8) pour PLCnext Engineer

Services Home Assistant

• Telegram
• SMTP

Description des fonctionnalités

Pour présenter les possibilités d'utiliser un contrôleur PLCnext comme dispositif domotique, un projet PLCnext permet de réinitialiser physiquement d'autres appareils en contrôlant leur alimentation via des relais. Les redémarrages sont déclenchés par des commandes envoyées à un bot Telegram, avant qu'un email ne soit envoyé pour confirmer le redémarrage. Cet exemple montre deux façons différentes de connecter le contrôleur PLCnext à l'environnement Home Assistant.

Architecture

Connexion via Modbus TCP

En commençant par la connexion Modbus TCP, un serveur Modbus est ajouté au projet PLCnext en utilisant la bibliothèque Modbus TCP. La configuration est identique à l'exemple de la bibliothèque. Le choix du bon registre Modbus dépend du type de données et de leur utilisation. Dans ce cas, les variables sont mappées sur le registre de coils.

Attention : le serveur Modbus ne supporte pas plus d'une connexion à la fois. Si une connexion n'est pas terminée correctement (ce qui arrive parfois pendant les tests), le serveur passe en état d'erreur et doit être redémarré manuellement. Pour éviter cela, il est recommandé de programmer un redémarrage automatique du serveur Modbus dans le projet PLCnext.

Pour le client Modbus, il y a deux possibilités principales dans Home Assistant : utiliser l'add-on Node-RED avec l'une des bibliothèques Modbus disponibles, ou configurer une entité dans le configuration.yaml de votre environnement Home Assistant (plus d'informations). Comme montré ci-dessous, le service switch standard est utilisé, une méthode courante pour travailler avec des variables booléennes car il implémente les fonctionnalités turn_on/turn_off pour définir ou réinitialiser les variables.

modbus:
  type: tcp
  host: VOTRE_IP_SERVEUR
  port: 502
  name: hub1
switch:
  - platform: modbus
    coils:
      - name: restartMB
        hub: hub1
        slave: 1
        coil: 13

Si vous choisissez Node-RED, sachez qu'il démarre généralement des connexions distinctes pour la lecture et l'écriture avec Modbus TCP, ce qui fait passer le serveur Modbus en état d'erreur. Pour éviter cela, vous pouvez utiliser Modbus UDP ou deux serveurs Modbus dans votre projet PLCnext, un pour la lecture et un pour l'écriture.

Connexion via API REST

La seconde possibilité est l'interface de données REST PLCnext. Cette interface est liée au HMI PLCnext, il est donc nécessaire d'avoir au moins une page HMI dans votre projet PLCnext, même vide, pour rendre l'API REST disponible. De plus, les variables doivent être marquées avec le drapeau HMI. Pour plus de détails, consultez le PLCnext Info Center.

Dans ce cas, l'add-on Node-RED est utilisé côté Home Assistant pour générer des requêtes HTTP. L'installation se fait en suivant ces instructions. Assurez-vous d'avoir effectué les deux étapes avant de continuer.

Si l'authentification utilisateur HMI dans le projet PLCnext est activée, l'authentification dans Node-RED peut ressembler à ceci :

Le flux exécute l'authentification et stocke le token d'accès pour l'utiliser dans les requêtes ultérieures. Pour la structure exacte des requêtes HTTP, consultez également la documentation du PLCnext Info Center.

Pour accéder aux données de votre environnement Home Assistant dans Node-RED, plusieurs nœuds sont fournis avec l'add-on Node-RED. Le flux court en bas de la figure suivante crée une nouvelle entité dans Home Assistant et le flux au-dessus surveille les changements de cette entité. Si l'entité est définie sur true, une variable dans le contrôleur PLCnext est également mise à true et déclenche un redémarrage. Comme la variable de redémarrage dans le projet PLCnext est automatiquement remise à false après le redémarrage, l'entité dans Home Assistant est également remise à false après un délai de 5 secondes.

Bot Telegram

Pour communiquer avec Home Assistant, l'API Telegram Bot est utilisée. Pour l'utiliser, un nouveau bot doit être enregistré en suivant cette instruction.

telegram_bot:
  - platform: polling
    api_key: VOTRE_TOKEN_API
    allowed_chat_ids:
      - VOTRE_CHAT_ID_1
      - VOTRE_CHAT_ID_2

Le moyen le plus simple de trouver votre chat ID : écrivez un message à votre bot, puis lancez la requête HTTP :

https://api.telegram.org/botVOTRE_TOKEN_API/getUpdates

Un exemple utile : le bot vous informe chaque matin des conditions météo pour savoir comment vous habiller. Dans ce projet, il a une autre tâche : redémarrer physiquement un PLC (appuyer sur le bouton dans les registres Modbus) via une commande Telegram. La commande "/MBrestartPLC" envoyée au bot lance un script d'automatisation dans Home Assistant, qui modifie finalement la valeur du registre coil Modbus. "/RESTrestartPLC" fait la même chose via l'API REST.

SMTP

Dans Home Assistant, le protocole SMTP (Simple Mail Transfer Protocol) permet d'envoyer des emails avec une sélection des données disponibles dans votre domotique. Le service s'implémente en ajoutant ce code au configuration.yaml :

notify:
  - name: SMTP_MESSENGER
    platform: smtp
    server: SMTP_SERVER
    port: 587
    timeout: 15
    sender: VOTRE_EMAIL
    encryption: starttls
    username: VOTRE_USERNAME
    password: VOTRE_PASSWORD
    recipient:
      - EMAIL_DESTINATAIRE
    sender_name: My Home Assistant

Automatisations

Une fois tous les services et bibliothèques implémentés et préparés, ils doivent être combinés via les automatisations programmées dans le automations.yaml de l'environnement Home Assistant. La structure d'une automatisation est simple : l'alias est le nom dans Home Assistant, le trigger est la condition qui doit être vraie pour exécuter l'automatisation (comme une commande Telegram), et l'action est la tâche (définir une variable à true et envoyer un email).

- id: '1'
alias: 'Déclencher un redémarrage de contrôleur via modbus'
trigger:
  platform: event
  event_type: telegram_command
  event_data:
    command: '/MBrestartPLC'
action:
  - service: switch.turn_on
    entity_id: switch.restartMB
  - service: notify.SMTP_MESSENGER
    data:
      title: 'Message PLC'
      message: 'Redémarrage PLC initié via modbus!'

- id: '2'
alias: 'Déclencher un redémarrage de contrôleur via rest api'
trigger:
  platform: event
  event_type: telegram_command
  event_data:
    command: '/RESTrestartPLC'
action:
  - service: switch.turn_on
    entity_id: switch.restartREST
  - service: notify.SMTP_MESSENGER
    data:
      title: 'Message PLC'
      message: 'Redémarrage PLC initié via rest!'

Conclusion

Ce projet de démonstration prouve qu'il est assez simple d'intégrer un contrôleur PLCnext dans une installation domotique. La disponibilité de toutes les données PLC dans Home Assistant ouvre la voie à des applications bien plus puissantes que cet exemple. Imaginez des programmes PLC plus complexes pouvant être contrôlés et surveillés en fonction de la météo ou d'autres données disponibles dans Home Assistant.