goodwe-addon/goodwe_controller/app/mqtt.py

"""Optional MQTT discovery, so the controller's state appears as real HA entities.

Optional on purpose: the add-on runs headless without a broker and simply
publishes nothing. Nothing in the control path depends on this - if MQTT breaks,
the battery keeps being controlled correctly and only the dashboard goes stale.
That separation is deliberate; observability must never be able to take down
control.
"""

import json
import logging

try:
    import paho.mqtt.client as mqtt
except ImportError:  # pragma: no cover - container always has it
    mqtt = None

_LOG = logging.getLogger("goodwe.mqtt")

# ⚠️ The DEVICE name is half of every entity_id. Home Assistant composes
# entity_id from device name + entity name, so "GoodWe RS485 Controller" plus
# "GoodWe battery power" yields
# sensor.goodwe_rs485_controller_goodwe_battery_power. object_id in the
# discovery payload did NOT override it (tested on HA 2026.8). So the device is
# named "GoodWe" and the entities are named without repeating it - that is what
# makes the ids short, predictable, and identical on every install.
DEVICE = {
    "identifiers": ["goodwe_rs485_controller"],
    "name": "GoodWe",
    "manufacturer": "GoodWe (via RS485 meter emulation)",
    "model": "ES/BP series",
}

# (key, object_id, name, unit, device_class, state_class, icon)
#
# ⚠️ object_id is what pins the entity_id. Without it Home Assistant derives the
# id from the DEVICE name plus the entity name and produces
# `sensor.goodwe_rs485_controller_goodwe_battery_power` - unpredictable, ugly,
# and different if anyone renames the device. Dashboards and documentation need
# these ids to be stable across every install, so they are declared, not derived.
SENSORS = [
    ("setpoint", "goodwe_setpoint", "Setpoint", "W", "power", "measurement", None),
    ("grid", "goodwe_grid_power", "Grid power", "W", "power", "measurement", None),
    ("battery", "goodwe_battery_power", "Battery power", "W", "power", "measurement", None),
    ("soc", "goodwe_battery_soc", "Battery SoC", "%", "battery", "measurement", None),
    # SAFETY-31. `sum(|Bi|) - |sum(Bi)|` over MEASURED per-inverter power: the
    # power going round between the inverters, which the grid sensor above
    # CANNOT SHOW because it nets to zero there. The two are published side by
    # side on purpose - "grid 0 W, circulating 6000 W" is the whole phenomenon
    # in two rows of a dashboard, and no arithmetic on the grid figure alone can
    # ever produce the second one.
    #
    # ⚠️ Published as 0 at the shipped one-inverter roster, not omitted, and
    # that is a deliberate difference from `p1_age` below. An absent entity is
    # right for a watchdog input nothing is feeding; this is a quantity whose
    # value is KNOWN at N=1 - identically zero, for every reading - and a
    # dashboard row reading 0 W is the honest report of it.
    ("circulation", "goodwe_circulating_power", "Circulating power", "W", "power", "measurement", "mdi:sync-alert"),
    ("phase", "goodwe_maintenance_phase", "Maintenance phase", None, None, None, "mdi:battery-sync"),
    ("status", "goodwe_controller_status", "Controller status", None, None, None, "mdi:heart-pulse"),
    # ⚠️ THE LIVE ENTITY IS `sensor.goodwe_p1_sample_age`, NOT what this
    # object_id spells. An earlier version of this comment said the id "must be
    # exactly sensor.p1_sample_age_s" - that name has never existed on any HA,
    # and believing it is how a safety layer gets disarmed by someone tidying up.
    #
    # On HA 2026.8 `object_id` in a discovery payload does NOT determine the
    # entity_id. HA composes it from the device name plus the entity name:
    # "GoodWe RS485 Controller" + "P1 sample age" -> sensor.goodwe_p1_sample_age.
    # Verified against the live system 2026-08-26; the firmware subscribes to
    # that composed name (goodwe-master-stage4-failsafe.yaml, homeassistant
    # sensor p1_age_s), and its own comment records that sensor.p1_sample_age_s
    # never existed.
    #
    # So: do NOT "fix" the firmware to match the object_id below, and do not
    # rename the device or this entity's friendly name - either changes the
    # composed id and silently disarms the ingest guard, because has_state()
    # simply stays false forever and nothing reports it. The firmware calls this
    # out as the failure that "FAILS SILENTLY AND LOOKS CORRECT".
    #
    # The value: seconds since the newest accepted P1 telegram, republished
    # every second so a meter frozen at a constant value still shows a climbing
    # age - the false-trip this entity exists to remove.
    #
    # ⚠️ Separately, and not fixed here: the firmware's ingest guard tests this
    # sensor's VALUE rather than its arrival, so a dead publisher freezes the
    # number and reads permanently fresh. Filed as TEL-06.
    ("p1_age", "p1_sample_age_s", "P1 sample age", "s", "duration", "measurement", None),
]

BASE = "goodwe_ctl"
AVAILABILITY = f"{BASE}/availability"


class MqttPublisher:
    def __init__(self, host, port, username=None, password=None, omit=()):
        # `omit` drops sensor keys from discovery entirely. ⚠️ Announcing a
        # sensor that nothing will ever publish to is not harmless here:
        # p1_sample_age_s is a watchdog input, and an entity that exists but is
        # never fed is a worse signal than one that does not exist at all.
        self.omit = set(omit)
        self.enabled = mqtt is not None and bool(host)
        self.client = None
        if not self.enabled:
            _LOG.info("MQTT not configured - status entities will not be published")
            return
        # paho-mqtt 2.x requires a callback API version; 1.x has no such
        # argument and Alpine ships 1.x. Support both rather than pinning, so
        # the container can use the distro package instead of compiling.
        try:
            self.client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                                      client_id="goodwe_rs485_controller")
        except AttributeError:
            self.client = mqtt.Client(client_id="goodwe_rs485_controller")
        if username:
            self.client.username_pw_set(username, password or "")
        self.client.will_set(AVAILABILITY, "offline", retain=True)
        # ⚠️ Announce from on_connect, never straight after connect(). paho
        # processes the CONNACK on its network thread, so a publish issued
        # immediately after connect() is made while still disconnected - and
        # paho DROPS QoS-0 publishes when disconnected, silently. The result is
        # an add-on that logs "MQTT connected" and creates no entities at all.
        # As a bonus, this also re-announces after every reconnect.
        self.client.on_connect = lambda *_args, **_kw: self._announce()
        try:
            self.client.connect(host, int(port), keepalive=60)
            self.client.loop_start()
            _LOG.info("MQTT connected to %s:%s", host, port)
        except OSError as err:
            _LOG.warning("MQTT connect failed (%s) - continuing without it", err)
            self.enabled = False

    def _announce(self) -> None:
        for key, object_id, name, unit, dev_class, state_class, icon in SENSORS:
            if key in self.omit:
                continue
            cfg = {
                "name": name,
                "object_id": object_id,
                "unique_id": f"{BASE}_{key}",
                "state_topic": f"{BASE}/{key}",
                "availability_topic": AVAILABILITY,
                "device": DEVICE,
            }
            if unit:
                cfg["unit_of_measurement"] = unit
            if dev_class:
                cfg["device_class"] = dev_class
            if state_class:
                cfg["state_class"] = state_class
            if icon:
                cfg["icon"] = icon
            self.client.publish(
                f"homeassistant/sensor/{BASE}_{key}/config",
                json.dumps(cfg), retain=True,
            )
        self.client.publish(AVAILABILITY, "online", retain=True)

    def publish(self, values: dict) -> None:
        if not self.enabled or self.client is None:
            return
        try:
            for key, value in values.items():
                if value is None:
                    continue
                self.client.publish(f"{BASE}/{key}", str(value))
        except OSError as err:  # pragma: no cover
            _LOG.debug("MQTT publish failed: %s", err)

    def close(self) -> None:
        if not self.enabled or self.client is None:
            return
        try:
            self.client.publish(AVAILABILITY, "offline", retain=True)
            self.client.loop_stop()
            self.client.disconnect()
        except OSError:  # pragma: no cover
            pass