audi-app/custom_components/audi_dashboard/batterie.py

"""Langfristige Aufzeichnung der 12V-Batteriespannung (Mein Audi -> Zustand
-> Batteriespannung antippen).

Eine über die Jahre absinkende Spannung deutet auf eine alternde Batterie hin
- dafür braucht es einen Verlauf, nicht nur den aktuellen Wert.

Ein Eintrag pro Tag ({datum, min, min_ts, max, max_ts}) reicht dafür und hält
die Datei auch über viele Jahre klein, selbst wenn der Sensor mehrfach pro
Stunde meldet (aktive Fahrt: Motor an/aus, Ladezustand des Alternators
wechselt laufend). Die Prüfung läuft deshalb alle 5 Minuten und trägt jede
Messung in den Tageseintrag ein; die Ablage erweitert dabei nur min/max samt
dem genauen Zeitstempel der jeweiligen Extremmessung - robust gegen Neustarts
und schwankende Erreichbarkeit.

Der Tagesminimalwert ist die für die Entladung aussagekräftige Größe: er fällt
typischerweise auf den Moment kurz nach dem Start, bevor der Alternator die
Ladespannung hochfährt - also am nächsten an die "echte" Ruhespannung heran,
ohne 2+ Stunden Standzeit abwarten zu müssen. Deshalb verwendet auch die
Ladezustands-/Gesundheitsauswertung im Frontend (AGM_RUHE_MAX_V) den
Tagesminimalwert, nicht den Maximalwert.

Es wird bewusst NICHT gefiltert, welche Messwerte gespeichert werden - min UND
max jedes Tages werden roh aufgezeichnet, solange die Messung überhaupt
plausibel ist (siehe SPANNUNG_MIN_V unten). Die AGM-Ruhespannungs-Grenze wird
erst beim Anzeigen angewendet: Tage, an denen selbst der Minimalwert über der
Grenze liegt (Fahrzeug nie im Ruhezustand beobachtet, z. B. bei einer sehr
langen Fahrt), tauchen dort nicht in der Statistik auf.

Eine Ausnahme von "roh aufzeichnen" gibt es: Werte unter SPANNUNG_MIN_V gelten
als unplausibel für eine echte Messung an dieser 12V-Bleibatterie und deuten
eher auf einen Sensor-/Verbindungsfehler hin - sie werden gar nicht erst
aufgezeichnet, damit ein einzelner Ausreißer nicht als Tagesminimum in der
Liste und im Diagramm landet.

Ohne zugeordneten BATTERIE_SENSOR passiert hier bewusst nichts, statt
Platzhalter-Nullwerte aufzuzeichnen.

Aufgezeichnet wird nur eine NEUE Messung. zustand_oder_none() liefert den
zuletzt bekannten Zustand unabhängig von seinem Alter - ohne diese Prüfung
"misst" ein schweigender Dongle alle fünf Minuten weiter seinen letzten Wert,
gestempelt mit "jetzt". Am Bestand nachgewiesen (06.09.2026): der 16.08.2026
trug einen Tageseintrag, obwohl der Spannungssensor an diesem Tag kein einziges
Mal gemeldet hatte - die nächste echte Meldung lag 885 Minuten entfernt; sieben
von 19 Einträgen standen mehr als fünf Minuten von jeder echten Meldung
entfernt, die unstrittigen Fahrzeugtage dagegen exakt bei 0 s.

Der Zeitstempel ist deshalb auch nicht mehr "jetzt", sondern der der Messung
selbst, und der Tag wird aus ihm abgeleitet - sonst landete eine Messung von
23:58 im Folgetag. Damit verhält sich der Livepfad wie der Rückblick
(historienimport.py's _batterie_importieren), der seit jeher jede Messung mit
ihrem eigenen Zeitstempel einträgt: dieselbe Messung, gleich auf welchem Weg
erfasst, ergibt denselben Eintrag.

Optional wird bei jeder neuen Tagesminimum-Messung auch die aktuelle
Außentemperatur (AUSSENTEMP_SENSOR, CAN ambient air temperature) mit
aufgezeichnet - für die Messwertliste (Datum, Uhrzeit, Außentemperatur), nicht
für die Ladezustandsauswertung selbst. Ohne zugeordneten Temperatursensor
bleibt das Feld None, genau wie beim Batteriesensor.
"""

from __future__ import annotations

import datetime
import logging
from typing import TYPE_CHECKING

from .veroeffentlichung import zustand_oder_none
from .verlauf import NEBENWERT_MAX_ABSTAND_S, ZUORDNUNG_MAX_S, geraetezeit_plausibel

if TYPE_CHECKING:
    from .koordinator import Koordinator

_LOGGER = logging.getLogger(__name__)

# Plausible Untergrenze für eine 12V-Bleibatterie (vom Nutzer festgelegt) -
# darunter ist es ein Sensor-/Verbindungsfehler, keine echte Messung (siehe
# Moduldocstring).
SPANNUNG_MIN_V = 10.0

# Obergrenze für eine echte Ruhespannungsmessung (vom Nutzer festgelegt: "max
# voltage for AGM Battery is 13V, everything above is the generator") -
# darüber ist es Generator-/Ladespannung, keine Batteriespannung mehr.
# Identisch mit AGM_RUHE_MAX_V im Frontend (audi-dashboard-app.js/
# Batterie.tsx), dort aber nur für die Anzeige (welche Tage ins Ladezustands-
# /Trend-Diagramm einfließen - siehe Moduldocstring oben, "erst beim Anzeigen
# angewendet"). Hier zusätzlich fürs Backend gebraucht, als oberer Rand für
# spannung_cache_vorladen() (veroeffentlichung.py): der "zuletzt gemessene
# Wert"-Fallback für die Zustand-Kachel soll ausdrücklich innerhalb von
# [SPANNUNG_MIN_V, AGM_RUHE_MAX_V] bleiben - eine Generatorspannung soll dort
# nie als "Batteriespannung" erscheinen, auch nicht als letzter bekannter
# Wert.
AGM_RUHE_MAX_V = 13.0

# Wie alt darf eine Messung sein, um noch als neu zu gelten? Der Takt liegt bei
# 5 Minuten (TAKT_BATTERIE in koordinator.py); das Fenster muss deshalb
# mindestens eine Taktlänge betragen, sonst ginge eine Messung verloren, die
# kurz nach einem Takt eintrifft. Verdoppelt, damit auch ein verspäteter Takt
# sie noch fasst - dieselbe Messung zweimal einzutragen ist folgenlos, weil sie
# ihren eigenen Zeitstempel trägt und die Ablage min/max nur erweitert.
MESSUNG_MAX_ALTER_S = 600


def messzeitpunkt(
    spannung_zustand,
    meldezeit_zustand,
    jetzt: datetime.datetime,
) -> datetime.datetime | None:
    """Wann wurde diese Spannung gemessen - und ist es überhaupt eine neue Messung?

    `None` heißt: die Messung ist älter als MESSUNG_MAX_ALTER_S, es gibt also
    nichts aufzuzeichnen. Siehe Moduldocstring, warum das nötig ist.

    Ohne zugeordnete Meldezeit bleibt nur die Ankunftszeit, und die wird von
    einem Neustart zurückgesetzt - dann kann unmittelbar danach einmalig ein
    veralteter Wert durchgehen. Mit MELDEZEIT_SENSOR passiert das nicht.

    Gestempelt wird mit der **Gerätezeit**, wenn sie sich zuordnen lässt, sonst
    mit der Ankunftszeit. Zugeordnet wird über ZUORDNUNG_MAX_S: die flespi-
    Integration setzt die Entitäten eines Datensatzes nacheinander, aber
    innerhalb weniger Millisekunden - liegt die Meldezeit weiter weg, gehört sie
    zu einem anderen Datensatz und sagt über diese Messung nichts. Der Rückblick
    stempelt Batteriewerte ebenfalls mit Gerätezeit (verlauf_lesen() bekommt in
    historienimport.py die Meldezeit-Entität mit); ohne dieselbe Wahl hier
    ergäben Livepfad und Rückblick für dieselbe Messung verschiedene Einträge.

    Gemessen wird gegen `last_updated`, nicht gegen `last_reported` - und das
    ist Absicht: `last_updated` springt nur bei einem echten Wertwechsel, und
    genau solche Wechsel schreibt auch der recorder, aus dem der Rückblick
    liest. Ein Sensor, der unverändert weitermeldet, gilt hier deshalb als
    "nichts Neues" - was richtig ist, denn ein unveränderter Wert erweitert
    weder min noch max. Auf `last_reported` umzustellen würde den Livepfad
    wieder vom Rückblick trennen.
    """
    if spannung_zustand is None:
        return None

    gemessen = spannung_zustand.last_updated
    if meldezeit_zustand is not None:
        abstand_s = abs(
            (meldezeit_zustand.last_updated - spannung_zustand.last_updated).total_seconds()
        )
        if abstand_s <= ZUORDNUNG_MAX_S:
            try:
                kandidat = datetime.datetime.fromtimestamp(
                    float(meldezeit_zustand.state), datetime.UTC
                )
            except (TypeError, ValueError, OSError, OverflowError):
                kandidat = None
            if kandidat is not None and geraetezeit_plausibel(kandidat, jetzt):
                gemessen = kandidat

    # Das Alter wird an `gemessen` gemessen, nicht an last_updated - und das ist
    # der Unterschied zwischen "funktioniert" und "funktioniert bis zum nächsten
    # Neustart". Home Assistant setzt beim Hochfahren jede Entität neu, ihr
    # last_updated steht danach auf der Neustartzeit, auch wenn der Wert Stunden
    # alt ist. Am 06.09.2026 im Testcontainer gemessen: nach dem Neustart um
    # 21:12:54 trug der Spannungssensor last_updated 21:12:54, während die
    # Meldezeit desselben Datensatzes 14:46:47 sagte - 395 Minuten alt. Die
    # Gerätezeit übersteht den Neustart, die Ankunftszeit nicht.
    if (jetzt - gemessen).total_seconds() > MESSUNG_MAX_ALTER_S:
        return None
    return gemessen


async def pruefen(k: Koordinator) -> None:
    sensor = k.zuordnung.werte.BATTERIE_SENSOR
    if not sensor:
        return
    wert = zustand_oder_none(k.hass, sensor)
    if wert is None:
        return
    try:
        spannung = float(wert)
    except (TypeError, ValueError):
        return
    # Ist das überhaupt eine neue Messung? Ohne diese Frage zeichnet ein
    # schweigender Dongle alle fünf Minuten weiter seinen letzten Wert auf -
    # siehe Moduldocstring und messzeitpunkt().
    jetzt = datetime.datetime.now(datetime.UTC)
    spannung_zustand = k.hass.states.get(sensor)
    meldezeit_sensor = k.zuordnung.werte.MELDEZEIT_SENSOR
    meldezeit_zustand = k.hass.states.get(meldezeit_sensor) if meldezeit_sensor else None
    gemessen = messzeitpunkt(spannung_zustand, meldezeit_zustand, jetzt)
    if gemessen is None:
        _LOGGER.debug(
            "Batteriespannung %s V ist keine neue Messung (Sensor meldet seit "
            "über %s s nichts) - nicht erfasst",
            spannung, MESSUNG_MAX_ALTER_S,
        )
        return

    # Erst hier, nach der Frischeprüfung: sonst warnt ein offline gegangener
    # Dongle alle fünf Minuten über denselben Wert (im Testcontainer 77 Mal in
    # 3000 Protokollzeilen gezählt). So warnt jede echte Messung genau einmal.
    if spannung < SPANNUNG_MIN_V:
        _LOGGER.warning(
            "Batteriespannung %s V unter der Plausibilitätsgrenze (%s V) - nicht erfasst",
            spannung, SPANNUNG_MIN_V,
        )
        return

    # Nicht nur "gibt es einen Temperaturwert", sondern "ist er auch aktuell":
    # zustand_oder_none() liefert unabhängig vom Alter den zuletzt bekannten
    # Zustand - meldet der Temperatursensor seltener als die Spannung (im
    # Testbestand teils erst nach 30+ Stunden erneut), würde sonst ein
    # beliebig alter Temperaturwert einer frischen Spannungsmessung
    # zugeschlagen. Verglichen wird gegen den Zeitpunkt der Spannungsmessung
    # selbst (last_updated des Spannungssensors), nicht gegen "jetzt" - beide
    # Sensoren werden aus dem aktuellen hass.states-Stand gelesen, können aber
    # unterschiedlich alt sein. Grenze und Begründung siehe
    # NEBENWERT_MAX_ABSTAND_S (verlauf.py) - vom Nutzer festgelegt.
    aussentemp = None
    temp_sensor = k.zuordnung.werte.AUSSENTEMP_SENSOR
    temp_wert = zustand_oder_none(k.hass, temp_sensor)
    if temp_wert is not None:
        temp_zustand = k.hass.states.get(temp_sensor)
        abstand_s = abs((temp_zustand.last_updated - spannung_zustand.last_updated).total_seconds())
        if abstand_s <= NEBENWERT_MAX_ABSTAND_S:
            try:
                aussentemp = float(temp_wert)
            except (TypeError, ValueError):
                pass
        else:
            _LOGGER.debug(
                "Außentemperatur %s s von der Spannungsmessung entfernt - nicht mit erfasst",
                round(abstand_s),
            )

    # Tag und Zeitstempel kommen aus der Messung selbst, nicht aus der Uhr des
    # Servers - sonst landete eine Messung von 23:58 im Folgetag.
    tag = gemessen.date().isoformat()
    await k.ablage.batterieverlauf_tageswert_aktualisieren(
        tag, gemessen.isoformat(), spannung, aussentemp
    )
    await k.batterieverlauf_veroeffentlichen()
    _LOGGER.debug("Batteriespannung erfasst (%s: %s V)", tag, spannung)


async def eintrag_loeschen(k: Koordinator, datum: str | None) -> None:
    """Löscht einen Tageseintrag aus der Messwertliste (Wischen zum Löschen).

    Entfernt nur diesen einen Tag - min/max anderer Tage bleiben unberührt,
    das Diagramm zeichnet beim nächsten Aufruf einfach ohne diesen Punkt."""
    if not datum:
        _LOGGER.warning("batterieverlauf_loeschen ohne datum aufgerufen")
        return
    if await k.ablage.batterieverlauf_eintrag_loeschen(datum):
        await k.batterieverlauf_veroeffentlichen()
        _LOGGER.info("Batteriespannungs-Tageseintrag %s gelöscht", datum)
    else:
        _LOGGER.warning("Batteriespannungs-Tageseintrag %s nicht gefunden", datum)