🔋 Guide d'intégration Marstek Venus/Jupiter dans Home Assistant

📋 Introduction

Ce guide détaille l'intégration complète des batteries Marstek Venus et Jupiter dans Home Assistant. Contrairement aux batteries Saturn/B2500, ces modèles récents nécessitent une approche spécifique utilisant deux add-ons complémentaires.

🎯 Avantages de cette méthode

✅ Aucun matériel supplémentaire requis (pas de dongles USB, capteurs, etc.)
✅ 100% logiciel : utilise uniquement des add-ons Home Assistant
✅ Préserve l'app mobile : votre application Marstek/PowerZero continue de fonctionner
✅ Intégration native : entités créées automatiquement dans Home Assistant
✅ Contrôle bidirectionnel : lecture des données ET envoi de commandes

⚠️ Important à savoir

✅ Venus/Jupiter : Ne peuvent PAS être reconfigurées pour utiliser un MQTT local
✅ Obligation : Doivent rester connectées au broker Hame (cloud)
✅ Solution : Utiliser Hame Relay + hm2mqtt pour l'intégration HA

🏗️ Architecture de la solution

[Batterie Venus/Jupiter] ↔ [Broker Hame Cloud] ↔ [Hame Relay] ↔ [MQTT Local] ↔ [hm2mqtt] ↔ [Home Assistant]

📦 Prérequis

1. MQTT Broker dans Home Assistant

Installer l'add-on Mosquitto broker
Ou configurer un broker MQTT externe

2. Informations de votre batterie

Device ID : Identifiant de 22-24 caractères
MAC Address : Adresse physique (sans les :)
Type : HMG-50 (Venus), HMN-X (Jupiter E), HMM-X (Jupiter C), etc.

🚀 Installation Étape par Étape

Étape 1 : Installation de Hame Relay

1.1 Ajouter le repository

Paramètres → Modules complémentaires → Boutique des modules complémentaires
Cliquer sur ⋮ (menu) → Dépôts
Ajouter : https://github.com/tomquist/hame-relay

1.2 Configuration Hame Relay

# Configuration pour récupération automatique des informations
inverse_forwarding: true  # OBLIGATOIRE pour Venus/Jupiter
default_broker_id: hame-2024
log_level: info

# Vos identifiants Hame pour récupération auto
username: "[email protected]"
password: "votre_mot_de_passe_hame"

# Configuration MQTT (adaptez selon votre setup)
mqtt_uri: "mqtt://homeassistant:1883"  # MQTT interne HA
# ou
mqtt_uri: "mqtt://user:[email protected]:1883"  # MQTT externe

# Device temporaire (sera récupéré automatiquement)
devices:
  - device_id: "000000000000000000000000"
    mac: "000000000000"
    type: "HMG-50"  # HMG-50 pour Venus, HMN-X pour Jupiter E, etc.
    version: 0

1.3 Récupération des vraies informations

Démarrer l'add-on Hame Relay
Consulter les logs pour voir vos vraies informations :

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

Mettre à jour la configuration avec les vraies valeurs

1.4 Configuration finale Hame Relay

inverse_forwarding: true
mqtt_uri: "mqtt://homeassistant:1883"
username: "[email protected]"
password: "votre_mot_de_passe"

devices:
  - device_id: "123456789abcdef012345678"  # Vos vraies valeurs
    mac: "001122334455"
    type: "HMG-50"
    version: 152

Étape 2 : Installation de hm2mqtt

2.1 Ajouter le repository

Paramètres → Modules complémentaires → Boutique des modules complémentaires
Cliquer sur ⋮ (menu) → Dépôts
Ajouter : https://github.com/tomquist/hm2mqtt

2.2 Configuration hm2mqtt

pollingInterval: 60  # Intervalle de polling en secondes
responseTimeout: 30  # Timeout des réponses
allowedConsecutiveTimeouts: 3
topicPrefix: hm2mqtt

devices:
  - deviceType: "HMG-50"  # Type de votre batterie
    deviceId: "001122334455"  # MAC sans les ":"

2.3 Types de devices courants

HMG-50 : Marstek Venus
HMN-1, HMN-2... : Marstek Jupiter E
HMM-1, HMM-2... : Marstek Jupiter C
JPLS-8H : Jupiter Plus

🔧 Dépannage

Problème : Aucun topic MQTT visible

Solution 1 : Vérifier la connexion MQTT

# Dans Hame Relay, essayez différentes URI :
mqtt_uri: "mqtt://homeassistant:1883"
mqtt_uri: "mqtt://core-mosquitto:1883"  
mqtt_uri: "mqtt://addon_core_mosquitto:1883"

Solution 2 : Test MQTT dans HA

Outils de développement → MQTT
Publier sur topic test/homeassistant avec payload {"test": "ok"}
Écouter le topic test/+
Si ça ne marche pas → problème MQTT de base

Solution 3 : Logs en mode debug

log_level: debug  # Dans Hame Relay

Problème : Hame Relay connecté mais pas de données

Vérifications :

Logs Hame Relay : Chercher "Connected to remote/local broker"
App mobile : Vérifier que la batterie fonctionne toujours
Topics MQTT : Écouter hm_VOTRE_DEVICE_ID/+ et hm2mqtt/+

📊 Entités créées automatiquement

Une fois les deux add-ons configurés, vous devriez voir apparaître :

Capteurs principaux

État de charge (SOC) en %
Puissance en temps réel (W)
Tension et Courant
Température de la batterie
Mode de fonctionnement

Contrôles disponibles

Mode de fonctionnement (automatique/manuel)
Programmation horaire (time periods)
Synchronisation de l'heure
Refresh des données

📈 Topics MQTT générés

Topics de données :

hm2mqtt/HMG-50/device/VOTRE_MAC/data

Topics de contrôle :

hm2mqtt/HMG-50/control/VOTRE_MAC/working-mode
hm2mqtt/HMG-50/control/VOTRE_MAC/time-period/1/enabled
hm2mqtt/HMG-50/control/VOTRE_MAC/refresh

🎯 Exemple de configuration complète

Hame Relay (final)

inverse_forwarding: true
mqtt_uri: "mqtt://homeassistant:1883"
username: "[email protected]"
password: "mon_mot_de_passe"
devices:
  - device_id: "123456789abcdef012345678"
    mac: "001122334455"
    type: "HMG-50"
    version: 152

hm2mqtt (final)

pollingInterval: 60
topicPrefix: hm2mqtt
devices:
  - deviceType: "HMG-50"
    deviceId: "001122334455"

🤝 Contribution

Ce guide a été créé par la communauté francophone de Home Assistant. N'hésitez pas à proposer des améliorations !

Remerciements

tomquist pour le développement de Hame Relay et hm2mqtt
Communauté HA française pour les tests et retours

🔗 Liens utiles

📝 Notes de version

v1.0 - Guide initial pour Venus/Jupiter

Procédure complète d'installation
Dépannage des problèmes courants
Exemples de configuration

Guide maintenu par la communauté francophone Home Assistant

cmer81/guide-integration-marstek-venus-jupiter-homeassistant-fr.md