python-mobius 0.3.0__tar.gz → 0.3.1__tar.gz

{python_mobius-0.3.0 → python_mobius-0.3.1}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.3.1
+
+- **Fixed a real, high-impact bug: `Brightness` (the master dimmer
+  channel) was never being applied to any other channel at all.**
+  Confirmed directly from raw smali (`LightPrimitive.flatten()`, called
+  on both bracketing schedule points in `getIntensitiesAtTime()` before
+  interpolating between them -- JADX's decompiled Java for this class
+  carried its own "Code duplicated" warning, the same signal that led to
+  finding the `is_night_segment()` bug, so this was re-verified against
+  bytecode rather than trusted from the decompile a second time). Every
+  channel -- moonlight included -- was being interpolated and returned
+  without ever being scaled by `Brightness`, found via real hardware
+  testing: a light showing ~1% in the app's own display came back as
+  ~25% from this library at the same moment, with `Brightness` itself
+  reading ~3.3% at that point in its own ramp -- fully consistent with
+  the missing multiplication, not a lunar or scheduling bug.
+  `interpolate_light_schedule()` now flattens each bracketing point
+  SEPARATELY (by that point's own `Brightness` value) BEFORE
+  interpolating between the two already-flattened points -- confirmed
+  via a dedicated test that this is NOT mathematically equivalent to
+  interpolating raw values first and multiplying by a single
+  interpolated `Brightness` at the end, whenever `Brightness` itself
+  changes across the segment (which it usually does, e.g. ramping
+  during dusk/dawn). `Brightness` itself is still returned as the plain
+  raw interpolated value, not flattened to a constant 100% the way the
+  real `flatten()` does to the primitive it's applied to -- callers
+  (e.g. a dedicated `Brightness` sensor) want the actual current
+  master-dimmer level. 4 new tests.
+
 ## 0.3.0
 
 - **Fixed a real, high-impact bug in `is_night_segment()`: the condition

{python_mobius-0.3.0 → python_mobius-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.3.0
+Version: 0.3.1
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation

{python_mobius-0.3.0 → python_mobius-0.3.1}/documentation/06-light-schedule.md

@@ -81,12 +81,51 @@ Ported from `PointSchedule.getIntensitiesAtTime()`:
 2. Find the two points that bracket the target minute-of-day, wrapping
    around midnight (the point after the last one is treated as being on
    "the next day," i.e. its time + 1440).
-3. For each channel present in either bracketing point, linearly
-   interpolate: `value(t) = v1 + (v2 - v1) * (t - t1) / (t2 - t1)`.
-4. Channels absent from a point default to `0` (off).
+3. **`Brightness` (`VisualID.Brightness`) is a master dimmer, applied to
+   EACH bracketing point separately, before interpolating between them**
+   -- confirmed from raw smali (`LightPrimitive.flatten()`, called on
+   both point copies in `getIntensitiesAtTime()` before the
+   interpolation loop -- JADX's decompiled Java for this class carried
+   its own "Code duplicated" warning, the same signal that led to
+   finding the `is_night_segment()` bug, so this was verified against
+   bytecode directly rather than trusted from the decompile). For each
+   point independently: every channel except `Brightness` itself is
+   multiplied by that same point's own `Brightness` value / 1000. This
+   was a real, confirmed-missing step for a while -- every channel
+   (moonlight included) was being interpolated and returned without
+   ever being scaled by `Brightness` at all, found via real hardware
+   testing (a light showing ~1% in the app's own display came back as
+   ~25% from this library at the same moment, with `Brightness` itself
+   reading ~3.3% at that point in its own ramp).
+4. For each channel present in either bracketing point, linearly
+   interpolate between the (already `Brightness`-scaled, for
+   non-`Brightness` channels) endpoint values:
+   `value(t) = v1 + (v2 - v1) * (t - t1) / (t2 - t1)`.
+   **Flattening happens per-endpoint before this step, not
+   interpolate-raw-then-multiply-by-a-single-`Brightness`-value after
+   it** -- these are NOT mathematically equivalent whenever `Brightness`
+   itself changes across the segment (which it usually does, e.g.
+   ramping during a dusk/dawn transition).
+5. Channels absent from a point default to `0` (off), except
+   `Brightness` itself: a point missing that channel entirely is treated
+   as a no-op 1000 (100%) multiplier for that point, matching
+   `flatten()`'s own `visuals().contains(Brightness)` guard (skips
+   scaling entirely rather than treating an absent value as 0, which
+   would zero out every other channel).
+6. `Brightness` itself is returned as the plain raw interpolated value
+   between the two points' own `Brightness` levels -- NOT flattened to
+   1000 the way the real `flatten()` call does internally to the
+   primitive it's applied to. Unlike the app's own dashboard (which
+   doesn't display `Brightness` as its own value at all, only as the
+   multiplier baked into every other channel), this library's callers
+   (e.g. a dedicated `Brightness` sensor) want the actual current
+   master-dimmer level itself.
 
 Verified against a synthetic two-point schedule (exact endpoint values,
-midpoint blending, and midnight-wraparound blending -- see
+midpoint blending, midnight-wraparound blending, and the `Brightness`
+master-dimmer behavior above, specifically including a case designed to
+mathematically distinguish flatten-then-interpolate from the wrong
+interpolate-then-multiply alternative -- see
 `tests/test_light_schedule.py`) and against a real 9-point schedule
 fetched live, which produces a coherent daily light-intensity curve (dim
 moonlight overnight → ramp to full blues/UV midday → wind back down).

{python_mobius-0.3.0 → python_mobius-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.3.0"
+version = "0.3.1"
 description = "Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)"
 readme = "README.md"
 license = { text = "GPL-2.0-only" }

{python_mobius-0.3.0 → python_mobius-0.3.1}/src/mobius/__init__.py

@@ -63,7 +63,7 @@ from .discovery import (
     dedupe_by_serial, find_device_by_serial, discover_mesh_peers_via_direct_connect,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "__version__",

{python_mobius-0.3.0 → python_mobius-0.3.1}/src/mobius/schedule.py

@@ -88,6 +88,41 @@ def interpolate_light_schedule(points: list[SchedulePoint], minute_of_day: int)
     schedule points and a target time (0-1439, minutes since midnight),
     returns {VisualID: intensity_permille} by linearly interpolating between
     the two points that bracket that time, wrapping around midnight.
+
+    Applies LightPrimitive.flatten()'s confirmed semantics (see that
+    method and its two call sites in getIntensitiesAtTime() in the real
+    smali -- JADX's decompiled Java for this class carried its own "Code
+    duplicated" warning, the same signal that led to finding the
+    is_night_segment() bug, so this was re-verified against raw bytecode
+    rather than trusted from the decompile alone): the "Brightness"
+    channel (VisualID.Brightness) is a master dimmer that multiplies
+    every OTHER channel -- confirmed via real hardware testing that this
+    was missing entirely: MoonlightBlue/White (and every other color
+    channel) were computed without ever being scaled by Brightness,
+    which the real app clearly does (a light showing ~1% in the app's
+    own "Current Intensities" display came back as ~25% from this
+    library at the same moment, with Brightness itself reading ~3.3% at
+    that point in its own ramp -- consistent with the missing
+    multiplication, not a lunar or scheduling bug).
+
+    Critically, this flattening happens to EACH bracketing point
+    SEPARATELY (each point's own non-Brightness channels multiplied by
+    that SAME point's own Brightness value) BEFORE interpolating between
+    the two already-flattened points -- not interpolate raw values first
+    and apply a single Brightness value at the end. These are NOT
+    mathematically equivalent whenever Brightness itself changes across
+    the segment (which it usually does, e.g. ramping 0->1000 during a
+    dusk/dawn transition) -- confirmed by the smali calling flatten() on
+    both point copies before the interpolation loop, not after it.
+
+    "Brightness" itself is deliberately NOT flattened to 1000 in the
+    returned dict the way the real flatten() call does internally --
+    unlike the app's own dashboard (which doesn't display Brightness as
+    its own value at all, only as the multiplier baked into every other
+    channel), this library's callers (e.g. a dedicated Brightness
+    sensor) want the actual current master-dimmer level itself, not a
+    constant 100%. Returned as the plain raw interpolation between the
+    two points' own Brightness values, same as before this fix.
     """
     if not points:
         return {}
@@ -109,12 +144,26 @@ def interpolate_light_schedule(points: list[SchedulePoint], minute_of_day: int)
         if t1 <= m <= t2:
             span = (t2 - t1) or 1
             frac = (m - t1) / span
+
+            # Each point's own Brightness value, defaulting to 1000 (a
+            # no-op multiplier) if that point doesn't have a Brightness
+            # channel at all -- matches flatten()'s own
+            # visuals().contains(Brightness) guard, which skips scaling
+            # entirely rather than treating an absent channel as 0.
+            b1 = p1.light.get(VisualID.Brightness) if VisualID.Brightness in p1.light.channels else 1000
+            b2 = p2.light.get(VisualID.Brightness) if VisualID.Brightness in p2.light.channels else 1000
+
             result = {}
             all_channels = set(p1.light.channels) | set(p2.light.channels)
             for ch in all_channels:
                 v1 = p1.light.get(ch)
                 v2 = p2.light.get(ch)
-                result[ch] = v1 + (v2 - v1) * frac
+                if ch == VisualID.Brightness:
+                    result[ch] = v1 + (v2 - v1) * frac
+                else:
+                    flattened1 = v1 * b1 / 1000.0
+                    flattened2 = v2 * b2 / 1000.0
+                    result[ch] = flattened1 + (flattened2 - flattened1) * frac
             return result
     return {}
 

python_mobius-0.3.1/tests/test_light_schedule.py

@@ -0,0 +1,135 @@
+"""
+Light schedule parsing/interpolation tests. The interpolation algorithm and
+9-point schedule shape here mirror what was captured live from two real
+Radion XR15 lights -- see documentation/06-light-schedule.md.
+"""
+from mobius import (
+    LightPrimitive, SchedulePoint, interpolate_light_schedule, VisualID,
+)
+
+
+def test_light_primitive_parses_channel_triplets():
+    # RoyalBlue(18) = 500
+    data = bytes([18]) + (500).to_bytes(2, "little")
+    lp = LightPrimitive.parse(data)
+    assert lp.get(VisualID.RoyalBlue) == 500
+    assert lp.get(VisualID.Blue) == 0  # unset channel defaults to 0
+
+
+def test_schedule_point_parses_time_flags_and_primitive():
+    raw_channel = bytes([18]) + (500).to_bytes(2, "little")
+    raw_point = (600).to_bytes(2, "little") + bytes([1]) + raw_channel
+    sp = SchedulePoint.parse(raw_point)
+    assert sp.time_minutes == 600
+    assert sp.flags == 1
+    assert sp.light.get(VisualID.RoyalBlue) == 500
+
+
+def test_inactive_point_returns_none():
+    raw_channel = bytes([18]) + (500).to_bytes(2, "little")
+    raw_point = (600).to_bytes(2, "little") + bytes([0]) + raw_channel  # flags=0, not ACTIVE
+    assert SchedulePoint.parse(raw_point) is None
+
+
+def _make_point(minute, royal_blue):
+    return SchedulePoint(minute, 1, LightPrimitive({VisualID.RoyalBlue: royal_blue}))
+
+
+def test_interpolation_at_exact_points():
+    points = [_make_point(480, 0), _make_point(720, 1000)]
+    assert interpolate_light_schedule(points, 480)[VisualID.RoyalBlue] == 0.0
+    assert interpolate_light_schedule(points, 720)[VisualID.RoyalBlue] == 1000.0
+
+
+def test_interpolation_halfway_between_points():
+    points = [_make_point(480, 0), _make_point(720, 1000)]
+    result = interpolate_light_schedule(points, 600)
+    assert result[VisualID.RoyalBlue] == 500.0
+
+
+def test_interpolation_wraps_across_midnight():
+    points = [_make_point(480, 0), _make_point(720, 1000)]
+    # 20:00 (1200) is 40% of the way from the 720 point to the wrapped 480+1440 point
+    result = interpolate_light_schedule(points, 1200)
+    assert result[VisualID.RoyalBlue] == 600.0
+
+
+def test_empty_schedule_returns_empty_dict():
+    assert interpolate_light_schedule([], 600) == {}
+
+
+# --------------------------------------------------------------------------
+# Brightness as a master dimmer (LightPrimitive.flatten()) -- confirmed
+# from real smali (not just the decompiled Java, which carried JADX's own
+# "Code duplicated" warning on this exact method, the same signal that
+# led to finding the is_night_segment() bug): "Brightness" multiplies
+# EVERY other channel, applied to EACH bracketing schedule point
+# SEPARATELY (by that same point's own Brightness value) BEFORE
+# interpolating between the two already-scaled points -- not interpolate
+# raw values first and multiply by a single Brightness value at the end.
+# Found via real hardware testing: MoonlightBlue/White (and every other
+# channel) were being computed without ever being scaled by Brightness,
+# which the real app's dashboard clearly does.
+# --------------------------------------------------------------------------
+
+def _make_point_with_brightness(minute, royal_blue, brightness):
+    return SchedulePoint(minute, 1, LightPrimitive({
+        VisualID.RoyalBlue: royal_blue, VisualID.Brightness: brightness,
+    }))
+
+
+def test_brightness_scales_other_channels_at_a_constant_level():
+    # Brightness=500 (50%) at both points -> RoyalBlue halved throughout,
+    # not left at its raw 1000.
+    points = [
+        _make_point_with_brightness(480, 1000, 500),
+        _make_point_with_brightness(720, 1000, 500),
+    ]
+    result = interpolate_light_schedule(points, 600)
+    assert result[VisualID.RoyalBlue] == 500.0
+
+
+def test_flatten_before_interpolate_not_interpolate_before_flatten():
+    """The actual point of this fix, made mathematically unambiguous:
+    Brightness and RoyalBlue both ramp 0->1000 across the same segment.
+    Flattening each endpoint by its OWN Brightness first, then
+    interpolating between the two flattened endpoints, gives 500 at the
+    midpoint. Interpolating the raw values first and multiplying by a
+    single interpolated Brightness at the end gives 250 instead -- these
+    are NOT the same, and only the former matches the confirmed real
+    smali (flatten() called on both point copies before the
+    interpolation loop, not after it)."""
+    points = [
+        _make_point_with_brightness(480, 0, 0),
+        _make_point_with_brightness(720, 1000, 1000),
+    ]
+    result = interpolate_light_schedule(points, 600)  # exact midpoint
+    assert result[VisualID.RoyalBlue] == 500.0  # NOT 250.0
+
+
+def test_brightness_itself_is_not_flattened_to_1000():
+    """Unlike the real flatten() (which resets Brightness to 1000 on the
+    primitive it's called on, having "absorbed" it into every other
+    channel), this library's returned dict keeps Brightness as the
+    actual raw interpolated master-dimmer level -- callers like a
+    dedicated Brightness sensor want that real value, not a constant
+    100% that would carry no information."""
+    points = [
+        _make_point_with_brightness(480, 1000, 0),
+        _make_point_with_brightness(720, 1000, 1000),
+    ]
+    result = interpolate_light_schedule(points, 600)  # midpoint
+    assert result[VisualID.Brightness] == 500.0  # raw interpolation, not 1000
+
+
+def test_missing_brightness_channel_is_a_no_op():
+    """Matches flatten()'s own visuals().contains(Brightness) guard --
+    if a point has no Brightness channel at all, other channels aren't
+    scaled by anything (equivalent to a no-op 1000/100% multiplier), not
+    zeroed out or otherwise affected. Confirms none of the existing
+    tests above this one (all written before this fix, none setting
+    Brightness at all) needed to change."""
+    points = [_make_point(480, 0), _make_point(720, 1000)]
+    result = interpolate_light_schedule(points, 600)
+    assert result[VisualID.RoyalBlue] == 500.0
+    assert VisualID.Brightness not in result

python_mobius-0.3.0/tests/test_light_schedule.py

@@ -1,58 +0,0 @@
-"""
-Light schedule parsing/interpolation tests. The interpolation algorithm and
-9-point schedule shape here mirror what was captured live from two real
-Radion XR15 lights -- see documentation/06-light-schedule.md.
-"""
-from mobius import (
-    LightPrimitive, SchedulePoint, interpolate_light_schedule, VisualID,
-)
-
-
-def test_light_primitive_parses_channel_triplets():
-    # RoyalBlue(18) = 500
-    data = bytes([18]) + (500).to_bytes(2, "little")
-    lp = LightPrimitive.parse(data)
-    assert lp.get(VisualID.RoyalBlue) == 500
-    assert lp.get(VisualID.Blue) == 0  # unset channel defaults to 0
-
-
-def test_schedule_point_parses_time_flags_and_primitive():
-    raw_channel = bytes([18]) + (500).to_bytes(2, "little")
-    raw_point = (600).to_bytes(2, "little") + bytes([1]) + raw_channel
-    sp = SchedulePoint.parse(raw_point)
-    assert sp.time_minutes == 600
-    assert sp.flags == 1
-    assert sp.light.get(VisualID.RoyalBlue) == 500
-
-
-def test_inactive_point_returns_none():
-    raw_channel = bytes([18]) + (500).to_bytes(2, "little")
-    raw_point = (600).to_bytes(2, "little") + bytes([0]) + raw_channel  # flags=0, not ACTIVE
-    assert SchedulePoint.parse(raw_point) is None
-
-
-def _make_point(minute, royal_blue):
-    return SchedulePoint(minute, 1, LightPrimitive({VisualID.RoyalBlue: royal_blue}))
-
-
-def test_interpolation_at_exact_points():
-    points = [_make_point(480, 0), _make_point(720, 1000)]
-    assert interpolate_light_schedule(points, 480)[VisualID.RoyalBlue] == 0.0
-    assert interpolate_light_schedule(points, 720)[VisualID.RoyalBlue] == 1000.0
-
-
-def test_interpolation_halfway_between_points():
-    points = [_make_point(480, 0), _make_point(720, 1000)]
-    result = interpolate_light_schedule(points, 600)
-    assert result[VisualID.RoyalBlue] == 500.0
-
-
-def test_interpolation_wraps_across_midnight():
-    points = [_make_point(480, 0), _make_point(720, 1000)]
-    # 20:00 (1200) is 40% of the way from the 720 point to the wrapped 480+1440 point
-    result = interpolate_light_schedule(points, 1200)
-    assert result[VisualID.RoyalBlue] == 600.0
-
-
-def test_empty_schedule_returns_empty_dict():
-    assert interpolate_light_schedule([], 600) == {}