Pylontech dans Home Assistant

Ce qu'il vous faut

Choisissez votre intégration

Les deux options se règlent depuis la page Settings de l'appareil (http://pylon-monitor.local/settings ou http://<IP-APPAREIL>/settings). Choisissez-en une — elles sont indépendantes.

Option 1 — Auto-découverte MQTT

Recommandée si vous utilisez le module Mosquitto broker dans Home Assistant. Dès que l'appareil est connecté au broker, il publie les messages de découverte standard sur homeassistant/sensor/… et les capteurs apparaissent dans Paramètres → Appareils et services → MQTT en quelques secondes, regroupés sous un seul appareil nommé Pylon-Monitor.

1. Remplissez 4 champs sur l'appareil

Sur la page Settings de l'appareil, repérez la carte Home Assistant — MQTT et remplissez ces champs (libellés tels qu'ils apparaissent sur l'appareil) :

Cliquez sur Save changes. Quelques secondes plus tard, la ligne Home Assistant (MQTT) du tableau de bord de l'appareil affiche Connected et les capteurs ci-dessous sont créés — aucune entité à configurer à la main. Pour couper MQTT, videz Broker IP et enregistrez.

2. Les capteurs créés dans Home Assistant

Le nom de l'appareil (par défaut pylon-monitor, modifiable dans Settings) sert de préfixe aux topics. Si vous l'avez changé, remplacez pylon-monitor ci-dessous par le vôtre.

Tous lisent leur valeur dans un seul topic d'état (retenu), mis à jour après chaque lecture de la batterie :

pylon-monitor/state

Le message combiné ressemble à ceci :

{
  "soc": 94,
  "soh": 96,
  "voltage": 48.62,
  "current": -7.20,
  "power": -350.1,
  "temp": 23.4,
  "mostemp": 28.1,
  "cycles": 486,
  "celldelta": 12,
  "units": 2,
  "state": "Discharging",
  "hw": "gen2",
  "pack": "lv"
}

3. Plusieurs batteries ? Des capteurs pour chacune

Dès que votre pack compte plus d'une batterie Pylontech, l'appareil crée en plus 5 capteurs par batterie — Battery 1 SOC, Battery 1 SOH, Battery 1 cycles, Battery 1 voltage, Battery 1 state, puis Battery 2, 3… — chacun sur son propre topic (pylon-monitor/battery1/state, pylon-monitor/battery2/state…). Idéal pour repérer la batterie qui vieillit plus vite que les autres.

pylon-monitor/battery1/state
{ "voltage": 48.61, "current": -3.60, "power": -175.0, "soc": 94, "soh": 97,
  "cycles": 480, "charge_cnt": 391, "discharge_cnt": 0, "state": "Discharging",
  "model": "US3000C", "bms_sw": "…", "serial": "…",
  "cell_min_mv": 3238, "cell_max_mv": 3247, "cell_delta_mv": 9, "cell_count": 15 }

Ces capteurs portent aussi des attributs, visibles dans la fiche de chaque capteur : modèle de la batterie, version du BMS, numéro de série et — une fois les cellules lues — tension de cellule la plus basse, la plus haute et l'écart entre les deux. C'est ce qui permet de distinguer « Battery 3 » de « Battery 4 » sans entités supplémentaires.

L'appareil entretient aussi un topic de disponibilité avec un « Last Will » : s'il perd l'alimentation ou le WiFi, chaque capteur passe à « indisponible » dans Home Assistant au lieu de rester figé en silence sur sa dernière valeur.

pylon-monitor/status  →  "online" (retained)  |  "offline" (Last Will, retained)

Option 2 — API REST

Aucun broker MQTT nécessaire. L'intégration rest intégrée à Home Assistant lit l'appareil toutes les 30 secondes. Le plus simple : copiez le bloc de la carte Home Assistant — REST de la page Settings de l'appareil — il contient déjà votre IP et une paire SOH + cycles pour chaque batterie réellement détectée. La version ci-dessous est le même modèle, pour un pack de 2 batteries. Depuis le firmware 3.4.0 (Lite 1.1.0, génération 1 : 3.1), /api.json exige votre clé d'accès — le bloc copié depuis l'appareil contient déjà ?key=…. Si vous avez configuré REST avant la mise à jour, ajoutez ?key=<votre clé d'accès> (Settings → Public JSON access) à la ligne resource:. MQTT n'est pas concerné.

Le JSON renvoyé par l'appareil

GET http://<DEVICE-IP>/api.json?key=<ACCESS-KEY>

{
  "system": "pylon-monitor",
  "firmware": "3.3.2",
  "hw": "gen2",
  "battery_link": true,
  "summary": {
    "soc": 94,
    "voltage": 48.62,
    "current": -7.20,
    "power": -350.10,
    "state": "Discharging",
    "units": 2
  },
  "health": {
    "soh": 96,
    "cycles": 486,
    "charge_cnt": 782,
    "discharge_cnt": 0
  },
  "unitsDetail": [
    { "soc": 94, "soh": 97, "cycles": 480, "model": "US3000C", "...": "..." },
    { "soc": 94, "soh": 95, "cycles": 492, "model": "US3000C", "...": "..." }
  ]
}

Raccourci pour la lisibilité : la réponse complète contient aussi temps, cells, alarms et net, et unitsDetail donne tension, courant, SOC, SOH, cycles, modèle et numéro de série de chaque batterie (présent quand le pack en compte plusieurs). Attention : le SOH est sous health, pas sous summary — une erreur de copier-coller classique.

Collez ceci dans configuration.yaml

# Access key: device Settings > Public JSON access (required since
# firmware 3.4.0 / Lite 1.1.0 / gen. 1 3.1). The block generated by the
# device's own Settings page already contains it.
rest:
  - resource: http://<DEVICE-IP>/api.json?key=<ACCESS-KEY>
    scan_interval: 30
    sensor:
      - name: "Pylontech SOC"
        unique_id: pylontech_soc
        value_template: "{{ value_json.summary.soc }}"
        unit_of_measurement: "%"
        device_class: battery
        state_class: measurement
      - name: "Pylontech SOH"
        unique_id: pylontech_soh
        value_template: "{{ value_json.health.soh }}"
        unit_of_measurement: "%"
        state_class: measurement
      - name: "Pylontech Voltage"
        unique_id: pylontech_voltage
        value_template: "{{ value_json.summary.voltage }}"
        unit_of_measurement: "V"
        device_class: voltage
        state_class: measurement
      - name: "Pylontech Current"
        unique_id: pylontech_current
        value_template: "{{ value_json.summary.current }}"
        unit_of_measurement: "A"
        device_class: current
        state_class: measurement
      - name: "Pylontech Power"
        unique_id: pylontech_power
        value_template: "{{ value_json.summary.power }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Pylontech State"
        unique_id: pylontech_state
        value_template: "{{ value_json.summary.state }}"
      # One SOH + cycles pair per battery (only on a pack of 2 or more):
      - name: "Pylontech Battery 1 SOH"
        unique_id: pylontech_battery1_soh
        value_template: "{{ value_json.unitsDetail[0].soh }}"
        unit_of_measurement: "%"
        state_class: measurement
      - name: "Pylontech Battery 1 cycles"
        unique_id: pylontech_battery1_cycles
        value_template: "{{ value_json.unitsDetail[0].cycles }}"
        state_class: measurement
      - name: "Pylontech Battery 2 SOH"
        unique_id: pylontech_battery2_soh
        value_template: "{{ value_json.unitsDetail[1].soh }}"
        unit_of_measurement: "%"
        state_class: measurement
      - name: "Pylontech Battery 2 cycles"
        unique_id: pylontech_battery2_cycles
        value_template: "{{ value_json.unitsDetail[1].cycles }}"
        state_class: measurement

Redémarrez Home Assistant (Outils de développement → Redémarrer). Les capteurs apparaissent dans Paramètres → Appareils et services → Entités — cherchez pylontech.

Tableau de bord Énergie

Pour une batterie, le tableau de bord Énergie de Home Assistant attend deux compteurs en kWh : l'énergie chargée et l'énergie déchargée. Le Pylon-Monitor fournit la puissance de la batterie en W (positive = charge, négative = décharge) : vous les créez une fois pour toutes avec des entrées (helpers) :

1. Séparez la puissance en deux avec deux capteurs « modèle » (template) : puissance de charge = la partie positive, puissance de décharge = la partie négative rendue positive.
2. Transformez chacun en kWh avec une entrée Intégrale (somme de Riemann), préfixe « k », méthode « Gauche ».
3. Dans Paramètres → Tableaux de bord → Énergie, section Stockage sur batterie, ajoutez les deux compteurs : énergie entrante, énergie sortante.

La même chose en YAML (noms des entités MQTT ; avec l'option 2, utilisez sensor.pylontech_power) :

template:
  - sensor:
      - name: "Battery charge power"
        unique_id: pylontech_charge_power
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
        state: "{{ [states('sensor.pylon_monitor_battery_power') | float(0), 0] | max }}"
      - name: "Battery discharge power"
        unique_id: pylontech_discharge_power
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
        state: "{{ [0 - (states('sensor.pylon_monitor_battery_power') | float(0)), 0] | max }}"

sensor:
  - platform: integration
    source: sensor.battery_charge_power
    name: "Battery energy in"
    unique_id: pylontech_energy_in
    unit_prefix: k
    round: 2
    method: left
  - platform: integration
    source: sensor.battery_discharge_power
    name: "Battery energy out"
    unique_id: pylontech_energy_out
    unit_prefix: k
    round: 2
    method: left

Vérifiez le nom exact de votre capteur de puissance dans Paramètres → Entités (cherchez « power ») : il diffère si vous avez renommé l'appareil ou si vous avez plusieurs Pylon-Monitor.

Alerte batterie faible

Une notification sur votre téléphone dès que la batterie passe sous 20 % :

alias: "Pylontech batterie faible"
triggers:
  - trigger: numeric_state
    entity_id: sensor.pylon_monitor_battery_soc
    below: 20
actions:
  - action: notify.notify
    data:
      message: "Batterie Pylontech à {{ states('sensor.pylon_monitor_battery_soc') }} %"

Même principe avec Battery state, Cell imbalance (par exemple au-dessus de 50 mV) ou des capteurs indisponibles depuis plus de 10 minutes — signe que l'appareil est hors ligne.

Node-RED, Jeedom et les autres

Node-RED — un nœud http request, méthode GET, URL http://<IP-APPAREIL>/api.json?key=<ACCESS-KEY>, retour « a parsed JSON object », puis lisez msg.payload.summary.soc (ou tout autre champ). Avec MQTT configuré, un nœud mqtt in sur pylon-monitor/state est encore plus simple : aucune interrogation.

Jeedom — installez le plugin JSON, pointez un équipement vers http://<IP-APPAREIL>/api.json?key=<ACCESS-KEY> et associez les chemins à des commandes (ex. summary>soc, summary>voltage, summary>state).

Tout le reste — openHAB, ioBroker, Domoticz, EVCC ou vos propres scripts : tout ce qui lit du MQTT ou un point d'accès JSON en HTTP fonctionne, avec les mêmes topics et le même /api.json.

Questions