Intégration BLUETTI en Modbus TCP local — S Meter et Balco 260, et une PR vers HA Core

Bonjour à tous,

Suite de mon précédent sujet sur le dashboard Énergie avec un Balco 260 :

J'y expliquais notamment que l'intégration officielle ne remonte que des watts, jamais
des kWh, et que la puissance batterie du Balco 260 n'existe tout simplement pas côté
cloud — d'où une estimation par bilan de puissance, avec les approximations que ça
implique.

Le Modbus local règle ces deux problèmes.

Où on en est

L'intégration Modbus locale que je maintiens reconnaît maintenant deux appareils :
le S Meter et le Balco 260. Aucune dépendance au cloud, aucune latence, ça
tourne même sans internet.

Concrètement, par rapport au cloud :

  • Compteurs d'énergie cumulée natifs (production PV, import et export réseau,
    sortie AC). Plus besoin de helpers Riemann, les kWh sortent directement de
    l'appareil
  • Données batterie réelles : énergie chargée et déchargée en Wh, SoC, SoH,
    nombre de cycles. L'estimation dont je parlais dans le tuto précédent devient
    inutile en local
  • Par string PV : puissance, tension et courant de chacune des quatre entrées
    séparément — ce qui permet de vérifier qu'un panneau débite réellement, panneau par
    panneau
  • Statuts, avertissements et défauts onduleur, en valeurs énumérées

:information_source: À ne pas confondre avec l'intégration officielle BLUETTI, qui existe déjà, passe
par le cloud avec un compte BLUETTI et couvre un large catalogue d'appareils. Ce
projet en est indépendant : c'est une démarche communautaire centrée sur le local.
Les deux sont complémentaires et peuvent cohabiter.

La suite : Home Assistant Core

Une PR est ouverte dans Core, construite sur la nouvelle architecture Modbus arrivée
en 2026.9 :

Si elle est acceptée, BLUETTI apparaît dans la liste des intégrations natives — plus
de dépôt tiers, plus de HACS. Elle ne porte que sur le Balco 260 pour l'instant : les
mainteneurs de Core demandent des PR courtes et ciblées, ce qui est parfaitement
compréhensible vu le volume qu'ils traitent. Le S Meter suivra dans une PR séparée,
puis les autres modèles un par un.

Une trouvaille qui peut servir à d'autres

En testant les connexions persistantes, on a changé le backend de notre bibliothèque
client : pymodbus remonte les réponses tronquées comme de simples timeouts, là où
tmodbus les identifie correctement comme ModbusProtocolError. On a passé un bon
moment à déboguer des « timeouts » qui étaient en réalité des trames malformées.
À retenir si vous chassez des appareils Modbus instables.

Où j'en suis honnêtement

Le projet est jeune et il reste des bugs. Le firmware Modbus des appareils a par
ailleurs ses propres instabilités — trames tronquées intermittentes, épuisement du
pool de sockets — que j'ai remontées au constructeur et qu'on contourne côté client
en attendant. C'est utilisable au quotidien, pas encore d'une robustesse
irréprochable.

Si vous avez du matériel BLUETTI

C'est là que j'ai besoin de vous. Étendre la compatibilité ne dépend pas du temps de
développement mais de l'accès au matériel : je possède un Balco 260 et S Meter, et c'est tout.

Activer le Modbus TCP prend deux minutes (serveur web local de l'appareil, login
admin avec le mot de passe de l'app BLUETTI, Settings → Modbus TCP, port 502, puis
bien cliquer sur le bouton d'enregistrement). Une lecture, et vous m'envoyez la
sortie.

Le mieux est d'ouvrir une issue ou une discussion sur le dépôt plutôt que de répondre
ici : c'est suivi, c'est traçable, et ça profite aux suivants.

Et bien sûr, questions et retours bienvenus dans ce fil.

Deux appareils de plus — AC500 et AC200L — et les packs d'extension du Balco 260

Depuis le premier message, l'intégration Modbus locale (hassio-bluetti-modbus, version 0.0.73) lit deux modèles BLUETTI supplémentaires, tous deux confirmés sur du matériel réel par leurs propriétaires :

  • AC500 — 30 champs (puissances, énergies, PV par string, totaux batterie, versions firmware), interrupteurs de sortie AC et DC, seuils de SoC. Confirmé par des membres de la communauté sur leurs propres unités. À savoir : la page web locale de l'AC500 — et donc le Modbus TCP — n'apparaît qu'avec le firmware du module IoT v9041.17, proposé en mise à jour dans l'app BLUETTI ; si votre AC500 répond au ping mais n'a pas de page web, c'est la raison.
  • AC200L — nouveau cette semaine. 30 champs, interrupteurs de sortie AC et DC, seuils de SoC (en lecture seule pour l'instant). Le profil a été construit par un propriétaire d'AC200L (@awrede) en recoupant chaque registre avec les lectures Bluetooth du même appareil, puis reconfirmé sur la version générée. Les champs d'énergie et de PV n'ont pas encore été vus autrement qu'à zéro (pas de panneaux sur cette unité) — si vous avez un AC200L2 avec des panneaux, un export de diagnostics réglerait la question. L'appareil se nomme lui-même « AC200L » ; rien ne dit encore qu'un AC200L d'origine expose le Modbus TCP.

Mise en route identique pour les deux : activer le Modbus TCP sur la page web locale de l'appareil (http://<ip-de-l'appareil>/, utilisateur admin, mot de passe = celui de votre compte app BLUETTI ; Réglages → Modbus TCP → Activer, port 502), puis ajouter l'intégration à la main — aucun des deux modèles ne s'annonce sur le réseau, donc pas de découverte automatique pour eux. Le détail est dans le README.

Propriétaires de Balco 260 avec des packs d'extension BC260 : chaque pack a maintenant son propre sous-appareil (« Pack 2 », « Pack 3 », …) avec les mêmes capteurs que la batterie intégrée — tension, courant, SoC, SoH, cycles, firmware, énergies. Ça a pris du temps : les packs répondent à leurs propres adresses Modbus, 41 et suivantes, pas là où tout le monde (nous compris) avait d'abord cherché, et les unités de deux propriétaires ont tranché cette semaine. Un pack que l'onduleur connaît mais qui ne remonte rien (en veille, éteint, débranché depuis) apparaît indisponible plutôt qu'à 0 % — c'est l'appareil qui ne dit rien, pas une panne. Toujours côté Balco 260 : une douzaine de registres de la liste officielle BLUETTI qui ne portent jamais de valeur sur cet appareil ont été retirés (confirmés non supportés par BLUETTI — les totaux les couvrent), et les écritures sont correctement gérées malgré une particularité du firmware dans la façon dont l'appareil les confirme (remontée à BLUETTI, corrigée de leur côté dans une prochaine version).

Un autre modèle ? Les données de registres sont bienvenues — le guide de test matériel déroule la procédure sans coder. La PR Core est inchangée pour l'instant : le Balco 260 d'abord, le reste suivra une fois qu'elle sera fusionnée.

Ah c'est toi qui contribue autant sur le projet community de bluetti ! :grinning_face:
Malheureusement de mon côté je n'ai pas de support modbus donc j'attends beaucoup du ble qui ne marche toujours pas avec ma EL400, mais c'est chouette de voir tout cela se mettre en place !

Des nouvelles de l'intégration BLUETTI locale (Modbus TCP)

Depuis le dernier message, elle reconnaît sept appareils, tous vérifiés sur du vrai matériel par leurs propriétaires :

Appareil Entités Pilotable depuis HA
Balco 260 107, plus un sous-appareil par pack de batterie sortie AC, charge réseau, injection, seuils de batterie
S Meter 31, réparties par phase —
AC500 32 sorties AC et DC
AC200L 30 sorties AC et DC
EP500Pro 32 sorties AC et DC
FridgePower 120, plus un sous-appareil batterie sortie DC, charge réseau
Balco Transfer Hub 27 —

Trois sont nouveaux : l'EP500Pro, le FridgePower et le Balco Transfer Hub. Ce dernier est passé de « personne ne l'a jamais essayé » à un appareil supporté en trois jours, grâce à un propriétaire qui en possède trois et qui a testé chaque étape. Il n'a pas de batterie à lui : la charge, la tension et le solaire qu'il affiche sont ceux de la station qui lui est raccordée.

Pour démarrer

  • Le Modbus TCP est désactivé d'usine. Il s'active sur la page web de l'appareil : son adresse IP dans un navigateur, identifiant admin, mot de passe = celui du Bluetooth défini dans l'application (vide si vous n'en avez jamais mis).
  • Le Balco 260 et le S Meter sont détectés tout seuls. Les autres s'ajoutent avec leur adresse IP, et ça ne changera pas : BLUETTI nous a confirmé que leurs modules réseau n'ont pas la place pour l'annonce automatique en plus du Modbus.
  • Installation via HACS : GitHub - bluetti-community/hassio-bluetti-modbus: BLUETTI Modbus Integration for Home Assistant · GitHub

Ce qui manque, et où vous pouvez aider

Le Balco 500 et l'EP2000 ont un profil écrit à partir de la documentation officielle de BLUETTI, mais aucune machine réelle ne les a jamais confirmés. Si vous en avez un, dites-le : il y a une commande de vérification qui prend deux minutes et qui ne fait que lire. Même chose pour un modèle absent de la liste.

La PR vers Home Assistant Core est toujours ouverte (#180602).

Enfin, pour ceux qui préfèrent rester sur le cloud : le fork communautaire de l'intégration officielle détecte maintenant tout seul le centre de données qui gère votre compte — les comptes européens se faisaient déconnecter en boucle — et supporte les coupures passagères du cloud BLUETTI sans faire clignoter les entités.

Suite du message précédent, et il se trouve que la section « ce qui manque » a bougé.

L'EP2000 est confirmé, l'Apex 300 aussi

Les deux tournent maintenant sur du vrai matériel, et la version 2.0.1 sortie le 5 octobre les propose en stable. On passe à neuf appareils.

Appareil Entités Pilotable depuis HA
Balco 260 107, plus un sous-appareil par pack de batterie sortie AC, charge réseau, injection, seuils de batterie
S Meter 31, réparties par phase —
AC500 32 sorties AC et DC
AC200L 30 sorties AC et DC
EP500Pro 32 sorties AC et DC
FridgePower 120, plus un sous-appareil batterie sortie DC, charge réseau
Balco Transfer Hub 27 —
EP2000 plus d'une vingtaine —
Apex 300 plus d'une vingtaine sorties AC et DC

Ce que « confirmé sur du vrai matériel » veut dire

L'EP2000 est un bon exemple de l'écart entre un profil écrit depuis la documentation et un profil vérifié. Trois corrections, toutes trouvées sur des machines réelles :

  • Le courant de pack était lu en non signé. Un pack en décharge affichait 6551,8 A au lieu de -1,8 A. Et sur ce modèle c'est une valeur en 0,1 A toute simple, pas l'offset de la famille Balco.
  • La température du pack n'est ni en Fahrenheit ni en Celsius direct, mais en degrés C + 40 — l'encodage que l'application BLUETTI utilise pour toutes les températures de l'EP2000. Un brut de 59-63 donne 19-23 °C.
  • Les entrées PV sont nommées d'après les MPPT et non les terminaux, chacun en portant deux. PV3 et PV4 lisaient des valeurs impossibles : ils ont disparu.

Et 57 champs que l'EP2000 ajoute n'avaient aucun nom — Home Assistant affichait le nom de l'appareil pour chacun d'eux. Ils sont nommés d'après la liste de registres de BLUETTI.

La batterie affiche maintenant la pile complète dont elle est constituée, par exemple HV800 + 3 × B700, comptée depuis les cellules que le contrôleur déclare.

Sur l'Apex 300, la sortie AC et la sortie DC sont devenues de vrais interrupteurs, commutés et relus sur une unité réelle. Les totaux d'énergie PV et de charge réseau sont arrivés avec.

Les entités fantômes disparaissent

Point qui concerne tout le monde. L'intégration créait une entité par champ de la table de registres, donc une unité monophasée avec une seule entrée PV affichait des phases 2-3, des onduleurs 2-3, des entrées PV 2-4 et des emplacements de firmware 2-4 qui ne portaient jamais rien.

Chaque groupe suit désormais le nombre que l'unité déclare elle-même, et tout ce qui dépasse démarre désactivé.

Sur une installation existante, ces entités sont désactivées une fois, même si vous les aviez activées. Rien n'est supprimé et l'historique est conservé. Pour en récupérer une : Paramètres → Appareils et services → BLUETTI Modbus → Entités, afficher les désactivées, ouvrir et activer. Et si vous ajoutez du matériel plus tard — une entrée PV, une phase, une batterie — il faudra activer les entités correspondantes à la main.

Prérequis

La 2.x demande Home Assistant 2026.9.0 ou plus récent. Les sous-appareils batterie, pack et phase reposent sur une fonction du registre d'appareils que HA n'a qu'à partir de la 2026.8 : sur une version antérieure, l'appareil n'affichait aucune entité du tout. HACS refuse maintenant l'installation plutôt que de vous laisser avec ça.

Ce qui manque toujours

Le Balco 500 a son profil écrit depuis la documentation officielle, et aucune machine réelle ne l'a encore confirmé. Si vous en avez un, la commande de vérification prend deux minutes et ne fait que lire.

Même chose pour tout modèle absent du tableau. Le parcours est rodé : profil construit depuis votre lecture, publié en beta, vous confirmez, et le modèle passe en stable. L'Apex 300 et le FridgePower ont fait exactement ce chemin, en quelques jours à chaque fois.

La PR vers Home Assistant Core est toujours ouverte (#180602).