Pylontech in Home Assistant

Cosa ti serve

Scegli la tua integrazione

Entrambe le opzioni si configurano dalla pagina Settings del dispositivo (http://pylon-monitor.local/settings o http://<IP-DISPOSITIVO>/settings). Scegline una: sono indipendenti.

Opzione 1 — Auto-discovery MQTT

Consigliata se usi il componente aggiuntivo Mosquitto broker in Home Assistant. Appena il dispositivo è collegato al broker, pubblica i messaggi di discovery standard su homeassistant/sensor/… e i sensori compaiono in Impostazioni → Dispositivi e servizi → MQTT in pochi secondi, raggruppati sotto un unico dispositivo chiamato Pylon-Monitor.

1. Compila 4 campi sul dispositivo

Nella pagina Settings del dispositivo, trova la scheda Home Assistant — MQTT e compila questi campi (etichette esattamente come le mostra il dispositivo):

Clicca su Save changes. Pochi secondi dopo la riga Home Assistant (MQTT) della dashboard del dispositivo mostra Connected e i sensori qui sotto vengono creati, senza configurare a mano nessuna entità. Per disattivare MQTT, svuota Broker IP e salva.

2. I sensori creati in Home Assistant

Il nome del dispositivo (predefinito pylon-monitor, modificabile in Settings) fa da prefisso dei topic. Se lo hai cambiato, sostituisci pylon-monitor qui sotto con il tuo.

Tutti leggono il proprio valore da un unico topic di stato conservato (retained), aggiornato dopo ogni lettura della batteria:

pylon-monitor/state

Il messaggio combinato ha questo aspetto:

{
  "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. Più batterie? Sensori per ciascuna

Appena il tuo pack ha più di una batteria Pylontech, il dispositivo crea anche 5 sensori per batteria — Battery 1 SOC, Battery 1 SOH, Battery 1 cycles, Battery 1 voltage, Battery 1 state, poi Battery 2, 3… — ciascuno sul proprio topic (pylon-monitor/battery1/state, pylon-monitor/battery2/state…). Ideale per individuare la batteria che invecchia più in fretta delle altre.

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 }

Questi sensori hanno anche degli attributi, visibili nella scheda di ogni sensore: modello della batteria, versione del BMS, numero di serie e — una volta lette le celle — tensione di cella minima, massima e differenza tra le due. È così che distingui «Battery 3» da «Battery 4» senza entità aggiuntive.

Il dispositivo mantiene anche un topic di disponibilità con «Last Will»: se perde l'alimentazione o il WiFi, ogni sensore diventa «non disponibile» in Home Assistant invece di restare bloccato in silenzio sull'ultimo valore.

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

Opzione 2 — API REST

Nessun broker MQTT necessario. L'integrazione rest inclusa in Home Assistant legge il dispositivo ogni 30 secondi. Il modo più semplice: copia il blocco dalla scheda Home Assistant — REST della pagina Settings: contiene già il tuo IP e una coppia SOH + cicli per ogni batteria effettivamente rilevata. La versione qui sotto è lo stesso modello per un pack da 2 batterie. Dal firmware 3.4.0 (Lite 1.1.0, generazione 1: 3.1), /api.json richiede la vostra chiave di accesso — il blocco copiato dal dispositivo contiene già ?key=…. Se avete configurato REST prima dell'aggiornamento, aggiungete ?key=<la vostra Access key> (Settings → Public JSON access) alla riga resource:. MQTT non cambia.

Il JSON restituito dal dispositivo

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", "...": "..." }
  ]
}

Accorciato per leggibilità: la risposta completa contiene anche temps, cells, alarms e net, e unitsDetail fornisce tensione, corrente, SOC, SOH, cicli, modello e numero di serie di ogni batteria (presente quando il pack ne ha più di una). Attenzione: il SOH è sotto health, non sotto summary, un classico errore di copia-incolla.

Incolla questo in 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

Riavvia Home Assistant (Strumenti per sviluppatori → Riavvia). I sensori compaiono in Impostazioni → Dispositivi e servizi → Entità: cerca pylontech.

Dashboard Energia

Per una batteria, la dashboard Energia di Home Assistant vuole due contatori in kWh: energia caricata ed energia scaricata. Il Pylon-Monitor fornisce la potenza della batteria in W (positiva = carica, negativa = scarica), quindi li crei una volta per tutte con degli aiutanti:

1. Dividi la potenza in due con due sensori template: potenza di carica = la parte positiva, potenza di scarica = la parte negativa resa positiva.
2. Trasforma ciascuna in kWh con un aiutante Integrale (somma di Riemann), prefisso «k», metodo «Sinistra».
3. In Impostazioni → Plance → Energia, sezione Accumulo a batteria, aggiungi i due contatori: energia in entrata, energia in uscita.

Lo stesso in YAML (nomi delle entità MQTT; con l'opzione 2 usa 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

Controlla il nome esatto del tuo sensore di potenza in Impostazioni → Entità (cerca «power»): cambia se hai rinominato il dispositivo o se hai più Pylon-Monitor.

Avviso batteria scarica

Una notifica sul telefono appena la batteria scende sotto il 20 %:

alias: "Pylontech batteria scarica"
triggers:
  - trigger: numeric_state
    entity_id: sensor.pylon_monitor_battery_soc
    below: 20
actions:
  - action: notify.notify
    data:
      message: "Batteria Pylontech al {{ states('sensor.pylon_monitor_battery_soc') }} %"

Stessa idea con Battery state, Cell imbalance (ad esempio sopra i 50 mV) o con sensori non disponibili da più di 10 minuti, segno che il dispositivo è offline.

Node-RED, Jeedom e altri

Node-RED — un nodo http request, metodo GET, URL http://<IP-DISPOSITIVO>/api.json?key=<ACCESS-KEY>, ritorno «a parsed JSON object», poi leggi msg.payload.summary.soc (o qualsiasi altro campo). Con MQTT configurato, un nodo mqtt in su pylon-monitor/state è ancora più semplice: nessun polling.

Jeedom — installa il plugin JSON, punta un'apparecchiatura a http://<IP-DISPOSITIVO>/api.json?key=<ACCESS-KEY> e associa i percorsi ai comandi (es. summary>soc, summary>voltage, summary>state).

Tutto il resto — openHAB, ioBroker, Domoticz, EVCC o i tuoi script: tutto ciò che legge MQTT o un endpoint JSON via HTTP funziona, con gli stessi topic e lo stesso /api.json.

Domande