grossanzeige/brightness.py

#!/usr/bin/env python3
"""Helligkeitsregelung anhand eines LDR-Werts.

Portierung von DoDimmen_V aus dem alten MSP430-Programm (GrossAnzeige/main.c):
gleitender Mittelwert, Helligkeitsstufen mit Hysterese, Prozentwerte aus
hellTafel_ub. Das alte Programm hatte 3 Stufen (bis 50 %), hier sind es 4 mit
100 % als oberster.

Der Fotowiderstand (LDR) liefert einen Rohwert (12-bit-ADC, 0..4095). Die
Schwellen rechnen in der Richtung "grosser Wert = helle Umgebung"; auf der
ESP32-Platine ist die Kennlinie umgekehrt, deshalb laeuft der Rohwert zuerst
durch raw_to_ldr(). Die Grenzen sind am realen Aufbau gemessen (siehe unten),
nicht mehr vom MSP430 uebernommen.

Reines Python, laeuft auch unter MicroPython (dort spaeter vom ADC gespeist).

    python3 brightness.py --ldr 1500        # Stufe/Prozent berechnen und senden
    python3 brightness.py --ldr 200 --dry-run
"""

# argparse und sys.stderr gibt es unter MicroPython nicht -- beides wird nur vom
# CLI-Teil ganz unten gebraucht und darum erst dort importiert. So laesst sich
# dieses Modul auf dem ESP32 einfach importieren.

# -- Stufengrenzen, am realen Aufbau gemessen (2026-07-27) ----------------
# Gemessen wurde am XIAO ESP32-C3 mit dem LDR an GPIO2 (200 Messwerte je Lage,
# Median), Werte nach raw_to_ldr, also schon in Zaehlrichtung "gross = hell":
#
#     abgedeckt      roh 4095 (ADC-Anschlag)  ->    0
#     Raumlicht      roh 1642                 -> 2453
#     angeleuchtet   roh  543                 -> 3552
#
# Die alten Grenzen (300/2500/3500) stammten vom MSP430-Aufbau und passten
# nicht: Stufe 3 begann bei 3650 und war damit unerreichbar -- selbst eine
# Taschenlampe direkt auf dem Sensor kam nur auf 3552.
#
# Aufteilung nach Nutzerwunsch "nachts laenger dunkel": der 5-%-Bereich reicht
# bis 1200, damit schwaches Licht die Anzeige noch nicht aufhellt und die
# Dunkeladaption der Beobachter geschont wird.
HELL_LOW = 1200         # Stufengrenze 0<->1  (5 % bis hierher)
HELL_HIGH = 2400        # Stufengrenze 1<->2
HELL_MAX = 3200         # Stufengrenze 2<->3  (100 % ab hier, jetzt erreichbar)

# Hysterese: Der Rohwert streut bei Raumlicht um +/-270; nach dem gleitenden
# Mittel ueber AVERAGE_WINDOW bleiben rund +/-32 (1 Sigma). 150 liegt sicher
# darueber (~4,7 Sigma) und zugleich weit unter dem Stufenabstand von 800.
# Frueher standen hier 30 fuer den untersten Uebergang (und 5*30 fuer die
# oberen) -- 30 lag unter dem Rauschen, die unterste Stufe haette geflattert.
HELL_HYST = 150
AVERAGE_WINDOW = 8      # MAXHELLARRAY: gleitender Mittelwert ueber 8 Werte

# Helligkeits-Prozente je Stufe, aus hellTafel_ub (main.h): 5/15/50/100 %.
PERCENTS = (5, 15, 50, 100)

# Mittelpunkte der Stufengrenzen und deren Hysterese (Stufe i <-> i+1).
# Jetzt einheitlich: die gemessene Streuung ist an allen Grenzen dieselbe, es
# gibt keinen Grund mehr fuer die gestaffelten Breiten des alten Programms.
_CENTERS = (HELL_LOW, HELL_HIGH, HELL_MAX)
_HYSTS = (HELL_HYST, HELL_HYST, HELL_HYST)


def raw_to_ldr(raw, inverted=None, full_scale=None):
    """ADC-Rohwert in die Zaehlrichtung bringen, die die Schwellen erwarten.

    Die Schwellen oben stammen vom alten MSP430-Aufbau: hoher Wert = helle
    Umgebung. Auf der ESP32-Platine liegt der LDR gegen Masse und der 2k gegen
    3V3, dort faellt die Spannung an A0 mit steigender Helligkeit. Der Wert wird
    deshalb gespiegelt, wenn config.LDR_INVERTED gesetzt ist.
    """
    import config
    if inverted is None:
        inverted = config.LDR_INVERTED
    if full_scale is None:
        full_scale = config.LDR_MAX
    return (full_scale - raw) if inverted else raw


class BrightnessController:
    """Rechnet aus LDR-Rohwerten die Anzeigehelligkeit -- wie DoDimmen_V.

    update() gibt die neue Helligkeit in Prozent nur zurueck, wenn sich die Stufe
    geaendert hat (sonst None). So wird -- wie im alten Programm -- nur bei
    tatsaechlicher Aenderung ein Helligkeitstelegramm gesendet.
    """

    def __init__(self):
        self._buf = []
        self._level = None       # entspricht oldHellStufe_ub = 0xFF (>=2-Zweig)

    @property
    def level(self):
        return self._level

    def _next_level(self, val, old):
        """Stufe mit Hysterese bestimmen (verallgemeinert auf beliebig viele Stufen).

        Hochschalten, solange der Wert die obere Kante (Mitte + Hysterese) der
        naechsten Grenze ueberschreitet; herunterschalten, solange er die untere
        Kante (Mitte - Hysterese) unterschreitet. Beim ersten Aufruf (old=None)
        wird von Stufe 0 aus hochgeschaltet -- die Anzeige startet also gedimmt
        und hellt sich passend zum Messwert auf.
        """
        level = 0 if old is None else old
        while level < len(PERCENTS) - 1 and val >= _CENTERS[level] + _HYSTS[level]:
            level += 1
        while level > 0 and val < _CENTERS[level - 1] - _HYSTS[level - 1]:
            level -= 1
        return level

    def update(self, ldr):
        """Einen LDR-Rohwert einspeisen. Liefert (stufe, prozent, geaendert)."""
        self._buf.append(ldr)
        if len(self._buf) > AVERAGE_WINDOW:
            self._buf.pop(0)
        avg = sum(self._buf) // len(self._buf)

        level = self._next_level(avg, self._level)
        changed = level != self._level
        self._level = level
        return level, PERCENTS[level], changed


def main(argv=None):
    import argparse
    import sys

    p = argparse.ArgumentParser(description=__doc__,
                                formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--ldr", type=int, required=True, help="LDR-Rohwert (0..4095)")
    p.add_argument("--port", default=None, help="serieller Port (Vorgabe aus config.py)")
    p.add_argument("--dry-run", action="store_true", help="nur berechnen/anzeigen, nicht senden")
    args = p.parse_args(argv)

    level, percent, _ = BrightnessController().update(args.ldr)
    print("LDR %d -> Stufe %d -> %d %%" % (args.ldr, level, percent))

    import config
    import migra
    from display import open_display
    d = open_display(port=args.port or config.PORT, fake=args.dry_run)
    try:
        d.set_brightness(percent)
    except migra.MigraError as e:
        print("Fehler: %s" % e, file=sys.stderr)
        return 1
    finally:
        d.close()
    print("OK")
    return 0


if __name__ == "__main__":
    import sys
    sys.exit(main())