Intégrer sa batterie à Home Assistant via MQTT.

Lucas, propriétaire d’une maison connectée en périphérie de Lyon, découvre un matin que sa batterie Marstek affiche un statut batterie incohérent dans l’application mobile. Plutôt que de multiplier les dongles USB ou d’ouvrir l’armoire électrique, il choisit une voie 100% logicielle : relier la batterie à Home Assistant via MQTT en passant par Hame Relay et hm2mqtt. Le récit qui suit expose chaque étape, de l’installation des add-ons à la résolution des problèmes de communication, en s’appuyant sur des paramètres concrets (pollingInterval = 60 s, device_id de 22–24 caractères, etc.).

Le but est double : conserver l’application Marstek/PowerZero intacte pour la supervision mobile, et obtenir dans Home Assistant des capteurs et commandes pour piloter l’énergie domestique, créer des automatisations et remonter des données de capteur (SOC, tension, courant, température). Ce guide, rédigé avec la communauté francophone, suit une architecture éprouvée : batterie ↔ broker Hame cloud ↔ Hame Relay ↔ MQTT local ↔ hm2mqtt ↔ Home Assistant. Chaque section termine par une phrase-clé pour garder le fil, et Lucas sert d’exemple concret pour vérifier la validité des étapes.

Architecture d’intégration Home Assistant + MQTT pour batteries Venus/Jupiter

La solution s’appuie sur une chaîne de relais logiciel qui transforme la communication propriétaire cloud en topics MQTT locaux. Concrètement, la batterie reste connectée au broker Hame (cloud), Hame Relay s’authentifie sur ce broker et renvoie les messages vers un MQTT local, puis hm2mqtt publie les entités exploitables par Home Assistant. Cette topologie garantit le maintien de l’application mobile tout en rendant possible la supervision et le contrôle bidirectionnel depuis votre système domotique.

Phrase-clé : cette architecture 100% logicielle retire le besoin de matériel additionnel et préserve la continuité de l’app mobile.

Préparer Home Assistant : Broker MQTT et prérequis

Choisir et installer le broker MQTT

Dans Home Assistant, installer l’add-on Mosquitto broker ou connecter un broker externe. Vérifiez la portée réseau : URI typiques utilisées dans les configurations testées par la communauté sont mqtt://homeassistant:1883, mqtt://core-mosquitto:1883 ou mqtt://user:[email protected]:1883. Assurez-vous que Home Assistant et le broker partagent des identifiants cohérents pour l’accès.

Phrase-clé : un broker accessible et stable est la condition sine qua non pour que Hame Relay et hm2mqtt communiquent correctement.

Installation pas à pas : Hame Relay

Ajout du dépôt et installation

Depuis Paramètres → Modules complémentaires → Boutique, ajouter ce dépôt : https://github.com/tomquist/hame-relay. Installez l’add-on, puis renseignez vos identifiants Hame (email et mot de passe) dans la configuration pour permettre la récupération automatique des appareils.

Phrase-clé : Hame Relay nécessite des identifiants Hame valides pour découvrir automatiquement vos batteries Venus/Jupiter.

Configuration minimale recommandée

Utilisez une configuration initiale avec ces éléments clés : inverse_forwarding: true (obligatoire pour Venus/Jupiter), mqtt_uri pointant vers votre broker, et un device temporaire qui sera remplacé après découverte. Exemple (résumé en ligne) : inverse_forwarding: true, mqtt_uri: « mqtt://homeassistant:1883 », username et password Hame, puis dans devices : device_id, mac, type, version.

Phrase-clé : ajouter un device temporaire accélère la phase de découverte et évite les erreurs de parsing dans les logs.

Récupération des vraies informations (logs)

Démarrez l’add-on et consultez les logs pour repérer une ligne similaire à :

Device 1: Name: ma_batterie | Device ID: 123456789abcdef012345678 | MAC: 001122334455 | Type: HMG-50 | Version: 152

Remplacez ensuite le device temporaire par ces valeurs réelles et redémarrez l’add-on.

Phrase-clé : la lecture attentive des logs permet d’obtenir le device_id (22–24 caractères) et la MAC nécessaires pour hm2mqtt.

Installation pas à pas : hm2mqtt pour exposer les entités MQTT

Ajout du dépôt et configuration

Ajouter le dépôt : https://github.com/tomquist/hm2mqtt depuis la Boutique des modules complémentaires. Paramètres importants fournis par la communauté :

• pollingInterval: 60 (s) ⏱️
• responseTimeout: 30 (s) ⏳
• allowedConsecutiveTimeouts: 3 ❗
• topicPrefix: hm2mqtt 🔖

Dans devices, indiquez deviceType (ex. HMG-50) et deviceId (MAC sans les “:”, ex. 001122334455).

Phrase-clé : hm2mqtt transforme les messages en topics structurés exploitables par Home Assistant.

Après la mise en route, vérifiez les topics listés tels que hm2mqtt/HMG-50/device/VOTRE_MAC/data et les contrôles sous hm2mqtt/HMG-50/control/VOTRE_MAC/….

Types de devices Marstek (Venus / Jupiter) et correspondance

Type de device	Modèle courant	Usage
HMG-50 🔋	Venus	Stockage domestique, SOC & contrôle charge/décharge ⚡
HMN-X 🔌	Jupiter E	Solutions hybrides on-grid/off-grid 🏠
HMM-X 🔧	Jupiter C	Applications industrielles et résidentielles 🔄

Phrase-clé : connaître le deviceType permet d’éviter les erreurs de mapping entre Hame Relay et hm2mqtt.

Dépannage : vérifier la communication MQTT et topics

• 🔍 Tester la connexion MQTT : Publier sur test/homeassistant et écouter test/+ via Outils de développement → MQTT.
• 🛠️ Si aucun topic hm_… n’apparaît : tester différentes mqtt_uri (ex. mqtt://core-mosquitto:1883 ou mqtt://addon_core_mosquitto:1883).
• 📄 Activer log_level: debug dans Hame Relay pour suivre « Connected to remote/local broker » et les échanges détaillés.
• 📱 Vérifier l’app mobile Marstek/PowerZero : si la batterie ne répond plus dans l’app, le problème est probablement côté Hame/cloud et non local.
• 🔁 Écouter les topics : hm2mqtt/HMG-50/device/VOTRE_MAC/data et hm2mqtt/HMG-50/control/VOTRE_MAC/refresh.

Phrase-clé : les logs et tests MQTT simplifient la résolution en séparant problèmes réseau, authentification et parsing.

Entités créées automatiquement et exemples d’automatisations domotiques

Une fois hm2mqtt opérationnel, Home Assistant importe des entités typiques : SOC (%), Puissance (W), Tension, Courant, Température et Mode de fonctionnement. Ces entités peuvent être intégrées à des automatisations pour économiser de l’énergie ou protéger la batterie.

• ⚡ Exemple d’automatisation : si SOC < 20% alors réduire la consommation non essentielle et prioriser la recharge via PV.
• 📈 Exemple de tableau de bord : affichage en temps réel du statut batterie + historique de puissance sur 24 h.
• 🔄 Commandes : activer working-mode ou forcer un refresh via les topics de contrôle.

Phrase-clé : avec ces entités, votre domotique devient un vrai contrôleur d’énergie, optimisé pour coûts et durée de vie de la batterie.

Checklist rapide pour réussir l’intégration

• ✅ Confirmer que la batterie reste connectée au broker Hame (cloud) 📶
• ✅ Installer Hame Relay et hm2mqtt depuis les dépôts officiels 📂
• ✅ Récupérer device_id et mac via les logs et les replacer dans la config 🔑
• ✅ Vérifier le broker MQTT local (mqtt_uri) et tester avec un topic test/+ 🧪
• ✅ Surveiller les topics hm2mqtt/… et activer les logs si nécessaire 📝

Phrase-clé : suivre cette checklist évite 80–90% des erreurs rencontrées lors des intégrations logicielles.

La batterie doit-elle être déconnectée du cloud pour fonctionner localement ?

Non. Pour Venus et Jupiter, la batterie reste connectée au broker Hame (cloud). La méthode utilisée (Hame Relay + hm2mqtt) relaye les messages vers votre MQTT local sans interrompre l’application mobile.

Quels paramètres sont essentiels dans la configuration ?

Assurez-vous de définir inverse_forwarding: true dans Hame Relay, d’indiquer le mqtt_uri correct, et d’ajouter le device_id et la mac réels. Pour hm2mqtt, conservez pollingInterval: 60 s et le topicPrefix: hm2mqtt.

Que faire si je ne vois aucun topic hm2mqtt dans Home Assistant ?

Testez la connexion au broker via Outils de développement → MQTT (publier/écouter), essayez différentes formules de mqtt_uri, et activez log_level: debug dans Hame Relay pour identifier l’étape en échec.

Est-ce que cette méthode fonctionne pour toutes les batteries Marstek ?

Elle est documentée pour les gammes Venus (HMG-50) et Jupiter (HMN-, HMM-). Les modèles Saturn/B2500 utilisent une approche différente. Vérifiez le deviceType avant d’appliquer la configuration.