python-mobius 0.7.0__tar.gz → 0.7.1__tar.gz

{python_mobius-0.7.0 → python_mobius-0.7.1}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.7.1
+
+- Added scene support: get_configured_scenes(), get_current_scene(),
+  start_scene(). Fixed get_current_scene() crashing on a custom
+  (non-preset) scene, and start_scene()'s duration being in seconds,
+  not minutes as previously labeled.
+
 ## 0.7.0
 
 - Added get_full_poll_batch() -- one round-trip for device identity +

{python_mobius-0.7.0 → python_mobius-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.7.0
+Version: 0.7.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.7.0 → python_mobius-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.7.0"
+version = "0.7.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.7.0 → python_mobius-0.7.1}/src/mobius/__init__.py

@@ -35,6 +35,7 @@ from .schedule import (
     LightPrimitive, SchedulePoint, interpolate_light_schedule,
     PumpPrimitiveValue, PumpSchedulePoint, get_active_pump_block,
 )
+from .scenes import Scene, ActiveScene, decode_configured_scenes, decode_active_scene
 from .manufacturer import MOBIUS_COMPANY_ID_ECOTECH, MOBIUS_COMPANY_ID_AQUAILLUMINATION, MOBIUS_COMPANY_IDS, MobiusAdvertisement, parse_manufacturer_data
 from .modifiers import (
     AcclimationInfo, is_night_segment,
@@ -71,7 +72,7 @@ from .dump import (
     enrich_attribute_dump,
 )
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 __all__ = [
     "__version__",
@@ -98,6 +99,8 @@ __all__ = [
     # schedule
     "LightPrimitive", "SchedulePoint", "interpolate_light_schedule",
     "PumpPrimitiveValue", "PumpSchedulePoint", "get_active_pump_block",
+    # scenes
+    "Scene", "ActiveScene", "decode_configured_scenes", "decode_active_scene",
     # manufacturer
     "MOBIUS_COMPANY_ID_ECOTECH", "MOBIUS_COMPANY_ID_AQUAILLUMINATION", "MOBIUS_COMPANY_IDS", "MobiusAdvertisement", "parse_manufacturer_data",
     # modifiers

{python_mobius-0.7.0 → python_mobius-0.7.1}/src/mobius/cli.py

@@ -18,6 +18,7 @@ from .device import MobiusDevice
 from .relay import RelayedMobiusDevice
 from .device_status import MeshPeer
 from .mesh_address import extract_short_address
+from .constants import PrimitiveType, SceneID
 from .discovery import (
     scan_for_mobius_devices_with_info, group_by_pan_id, dedupe_by_serial,
     find_device_by_serial, discover_mesh_peers_via_direct_connect, discover_tank,
@@ -99,6 +100,37 @@ async def _dump_schedule(device: MobiusDevice, support: str) -> None:
         print(f"    (schedule dumping not supported for support={support!r})")
 
 
+async def _dump_scenes(device: MobiusDevice, primitive: PrimitiveType | None) -> None:
+    """Prints every configured scene, at whatever slot it lives in,
+    including empty/unused slots. The currently active scene is
+    already shown by the summary above (info["current_scene"])."""
+    print("  --- configured scenes ---")
+    scenes = await device.get_configured_scenes(primitive=primitive)
+    if not scenes:
+        print("    (none)")
+        return
+    for scene in scenes:
+        if scene.scene_type == SceneID.EmptyScene and not scene.name:
+            print(f"    [{scene.index}] (empty)")
+            continue
+        type_label = scene.scene_type.name if scene.scene_type else "custom"
+        if scene.light is not None:
+            payload = ", ".join(
+                f"{vid.name}={val}"
+                for vid, val in sorted(scene.light.channels.items(), key=lambda x: x[0].name)
+            )
+        elif scene.pump is not None:
+            params = ", ".join(
+                f"{p.name}={v.hex() if isinstance(v, bytes) else (v.name if hasattr(v, 'name') else v)}"
+                for p, v in scene.pump.params.items()
+            )
+            payload = f"mode={scene.pump.mode.name} {params}"
+        else:
+            payload = "(no primitive data decoded)"
+        print(f"    [{scene.index}] id={scene.id} ({type_label}) name={scene.name!r} "
+              f"timeout={scene.timeout}s: {payload}")
+
+
 async def _debug_mesh_discovery(device) -> list:
     """
     Verbose, step-by-step version of discover_mesh_peers_auto() for CLI
@@ -273,6 +305,10 @@ async def _run(args) -> None:
                     print(f"  {k}: {v}")
                 if args.dump_schedule:
                     await _dump_schedule(mdevice, summary.get("support", ""))
+                if args.dump_scenes:
+                    primitive_name = summary.get("primitive_type")
+                    primitive = PrimitiveType[primitive_name] if primitive_name else None
+                    await _dump_scenes(mdevice, primitive)
 
                 relayed = None  # set below only if --relay-target resolves successfully
                 if args.dump_mesh_peers or args.relay_target:
@@ -620,6 +656,10 @@ async def _run(args) -> None:
                     print(f"  {k}: {v}")
                 if args.dump_schedule:
                     await _dump_schedule(mdevice, summary.get("support", ""))
+                if args.dump_scenes:
+                    primitive_name = summary.get("primitive_type")
+                    primitive = PrimitiveType[primitive_name] if primitive_name else None
+                    await _dump_scenes(mdevice, primitive)
         except Exception as e:
             print("  failed to connect/read:", e)
 
@@ -667,6 +707,12 @@ def main() -> None:
                               "hardware -- see LunarPhaseInfo's own docstring) -- compare against "
                               "\"current_intensities\"/\"light_diagnostics\" in the summary output "
                               "above for this library's own calculated value.")
+    parser.add_argument("--dump-scenes", action="store_true",
+                         help="Also print every configured scene on each connected device -- "
+                              "id, name, timeout, and its own light/pump payload -- at whatever "
+                              "slot it lives in, including empty/unused slots. The currently "
+                              "active scene is already shown by the summary above "
+                              "(\"current_scene\").")
     parser.add_argument("--dump-mesh-peers", action="store_true",
                          help="Only usable with --by-serial. After connecting, calls "
                               "discover_mesh_peers_auto() on it and prints every other device "

{python_mobius-0.7.0 → python_mobius-0.7.1}/src/mobius/constants.py

@@ -436,6 +436,7 @@ class C2Attribute(IntEnum):
     SceneTimeout = 402
     SceneTimer = 403
     # Scene diagnostics -- named, not yet exposed by a get_*() method.
+    LiveDemoSceneNero = 404
     LiveDemoTimeout = 405
     LiveDemoTimer = 406
     LiveDemoScene = 407

{python_mobius-0.7.0 → python_mobius-0.7.1}/src/mobius/device.py

@@ -43,6 +43,7 @@ from .schedule import (
     SchedulePoint, interpolate_light_schedule,
     PumpSchedulePoint, get_active_pump_block,
 )
+from .scenes import Scene, ActiveScene, decode_configured_scenes, decode_active_scene
 from .modifiers import (
     AcclimationInfo, is_night_segment, lunar_percent_reduction,
 )
@@ -1276,22 +1277,40 @@ class MobiusDevice:
 
     # ---- scenes -----------------------------------------------------------
 
-    async def start_scene(self, scene_id: SceneID, duration_minutes: int = 0) -> None:
-        """duration_minutes=0 lets the device use the scene's own configured duration."""
-        value = struct.pack("<HH", int(scene_id), duration_minutes)
+    async def start_scene(self, scene_id: int, duration_seconds: int = 0) -> None:
+        """
+        Activates a scene by id -- one of the ten SceneID presets, or a
+        user-created scene's own device-assigned id (see get_configured_scenes()).
+        duration_seconds=0 lets the device use the scene's own configured
+        timeout instead.
+        """
+        value = struct.pack("<HH", int(scene_id), duration_seconds)
         await self.set_attribute(C2Attribute.CurrentScene, value)
 
-    async def start_feed_mode(self, duration_minutes: int = 0) -> None:
-        await self.start_scene(SceneID.FeedMode, duration_minutes)
+    async def start_feed_mode(self, duration_seconds: int = 0) -> None:
+        await self.start_scene(SceneID.FeedMode, duration_seconds)
 
     async def resume_schedule(self) -> None:
         """Cancel whatever scene is running and go back to the normal schedule."""
         await self.set_attribute(C2Attribute.OperationState, bytes([OperationState.Schedule]))
 
-    async def get_current_scene(self) -> tuple[SceneID, int]:
-        raw = await self.get_attribute(C2Attribute.CurrentScene)
-        scene_id, duration = struct.unpack("<HH", raw[0])
-        return SceneID(scene_id), duration
+    async def get_current_scene(self) -> Optional[ActiveScene]:
+        try:
+            raw = await self.get_attribute(C2Attribute.CurrentScene)
+        except Exception:
+            return None
+        return decode_active_scene(raw[0]) if raw else None
+
+    async def get_configured_scenes(self, primitive: Optional[PrimitiveType] = None) -> list[Scene]:
+        """
+        Every configured scene, at whatever slots this device actually
+        has one in -- including slots holding a genuinely empty/unused
+        scene. Pass primitive so each scene's own light/pump payload
+        can be decoded; omit it (or leave as None) to get every other
+        field with light/pump both left None.
+        """
+        raw = await self.get_attribute(C2Attribute.ConfiguredScenes, index=0, count=0xFFFF)
+        return decode_configured_scenes(raw, primitive)
 
     async def get_operation_state(self) -> OperationState:
         raw = await self.get_attribute(C2Attribute.OperationState)
@@ -2931,6 +2950,8 @@ class MobiusDevice:
         info["firmware_versions"] = await self.get_firmware_versions(model)
         info["hardware_info"] = await self.get_hardware_info()
         info["device_time"] = await self.get_device_time_info()
+        current_scene = await self.get_current_scene()
+        info["current_scene"] = current_scene
 
         return info
 

python_mobius-0.7.1/src/mobius/scenes.py

@@ -0,0 +1,97 @@
+"""
+Scenes: a device-side preset that can be activated on demand, separate
+from the normal time-based schedule (Schedule1/Schedule2). Each
+configured scene stores exactly the same kind of payload a schedule
+point would (channel intensities for a light, mode+parameters for a
+pump), plus a name and a timeout, at a fixed slot within
+ConfiguredScenes (400). Activating one writes CurrentScene (401).
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+from .constants import SceneID, PrimitiveType, LIGHT_PRIMITIVES, PUMP_PRIMITIVES_VERIFIED, PUMP_PRIMITIVES_EXPERIMENTAL
+from .schedule import LightPrimitive, PumpPrimitiveValue
+
+SCENE_HEADER_SIZE = 20  # id(2) + timeout(2) + name(16), before primitiveData
+SCENE_NAME_SIZE = 16
+
+
+@dataclass
+class Scene:
+    """One configured scene, at a fixed slot (`index`) within
+    ConfiguredScenes. `scene_type` is one of the ten built-in presets
+    if `id` matches one, or None for a user-created scene (whose own
+    `id` is a device-assigned value outside that range). Exactly one
+    of `light`/`pump` is populated, matching the device's own
+    PrimitiveType -- the other stays None."""
+    index: int
+    id: int
+    scene_type: Optional[SceneID]
+    name: str
+    timeout: int
+    light: Optional[LightPrimitive]
+    pump: Optional[PumpPrimitiveValue]
+
+
+@dataclass
+class ActiveScene:
+    """The currently active scene (CurrentScene, 401) and how many
+    seconds it has left. `scene_type` is None if `id` doesn't match
+    one of the ten built-in presets (i.e. a user-created scene is
+    active) -- id itself is always present either way."""
+    id: int
+    scene_type: Optional[SceneID]
+    duration_seconds: int
+
+
+def decode_configured_scenes(values: list[bytes], primitive: Optional[PrimitiveType]) -> list[Scene]:
+    """
+    Pure decode for ConfiguredScenes (400) -- one call's worth of
+    values from a "get all elements" read (index=0, count=0xFFFF),
+    one element per slot, in index order. A slot with fewer than
+    SCENE_HEADER_SIZE bytes is skipped rather than raising.
+    """
+    scenes = []
+    for index, raw in enumerate(values):
+        if len(raw) < SCENE_HEADER_SIZE:
+            continue
+        scene_id = struct.unpack_from("<H", raw, 0)[0]
+        timeout = struct.unpack_from("<H", raw, 2)[0]
+        name_bytes = raw[4:4 + SCENE_NAME_SIZE]
+        name = name_bytes.split(b"\x00", 1)[0].decode("utf-8", errors="replace")
+        primitive_data = raw[SCENE_HEADER_SIZE:]
+
+        try:
+            scene_type = SceneID(scene_id)
+        except ValueError:
+            scene_type = None
+
+        light = None
+        pump = None
+        if primitive in LIGHT_PRIMITIVES:
+            light = LightPrimitive.parse(primitive_data)
+        elif primitive in PUMP_PRIMITIVES_VERIFIED or primitive in PUMP_PRIMITIVES_EXPERIMENTAL:
+            pump = PumpPrimitiveValue.parse(primitive_data)
+
+        scenes.append(Scene(
+            index=index, id=scene_id, scene_type=scene_type, name=name,
+            timeout=timeout, light=light, pump=pump,
+        ))
+    return scenes
+
+
+def decode_active_scene(raw: bytes) -> Optional[ActiveScene]:
+    """Pure decode for CurrentScene (401): id(u16 LE) + duration
+    seconds(u16 LE). None if raw is too short to contain both fields."""
+    if len(raw) < 4:
+        return None
+    scene_id, duration = struct.unpack_from("<HH", raw, 0)
+    try:
+        scene_type = SceneID(scene_id)
+    except ValueError:
+        scene_type = None
+    return ActiveScene(id=scene_id, scene_type=scene_type, duration_seconds=duration)

python_mobius-0.7.1/tests/test_scenes.py

@@ -0,0 +1,203 @@
+"""Tests for scenes.py's decode_configured_scenes()/decode_active_scene(),
+and the device.py methods built on top of them."""
+
+import struct
+from unittest.mock import AsyncMock
+
+import pytest
+from bleak.backends.device import BLEDevice
+
+from mobius import (
+    Scene, ActiveScene, SceneID, PrimitiveType, VisualID, PumpMode, PumpParam,
+    decode_configured_scenes, decode_active_scene,
+)
+from mobius.device import MobiusDevice
+
+
+def _scene_bytes(scene_id: int, timeout: int, name: str, primitive_data: bytes) -> bytes:
+    name_bytes = name.encode("utf-8")[:16].ljust(16, b"\x00")
+    return struct.pack("<HH", scene_id, timeout) + name_bytes + primitive_data
+
+
+def _light_primitive_bytes(channel: VisualID, intensity: int) -> bytes:
+    return struct.pack("<BH", int(channel), intensity)
+
+
+def _pump_primitive_bytes(mode: PumpMode, max_speed: int) -> bytes:
+    return bytes([int(mode)]) + struct.pack("<h", max_speed)
+
+
+# --------------------------------------------------------------------------
+# decode_configured_scenes
+# --------------------------------------------------------------------------
+
+def test_decode_light_scene():
+    raw = _scene_bytes(int(SceneID.AllOn), 60, "Bright", _light_primitive_bytes(VisualID.RoyalBlue, 1000))
+    scenes = decode_configured_scenes([raw], PrimitiveType.VisualV1)
+
+    assert len(scenes) == 1
+    scene = scenes[0]
+    assert scene.index == 0
+    assert scene.id == int(SceneID.AllOn)
+    assert scene.scene_type == SceneID.AllOn
+    assert scene.name == "Bright"
+    assert scene.timeout == 60
+    assert scene.pump is None
+    assert scene.light.get(VisualID.RoyalBlue) == 1000
+
+
+def test_decode_pump_scene():
+    raw = _scene_bytes(int(SceneID.FeedMode), 30, "Feed", _pump_primitive_bytes(PumpMode.Feed, 0))
+    scenes = decode_configured_scenes([raw], PrimitiveType.VorTechV1)
+
+    assert len(scenes) == 1
+    scene = scenes[0]
+    assert scene.scene_type == SceneID.FeedMode
+    assert scene.name == "Feed"
+    assert scene.light is None
+    assert scene.pump.mode == PumpMode.Feed
+    assert scene.pump.params[PumpParam.MaxSpeed] == 0
+
+
+def test_decode_custom_scene_has_no_scene_type():
+    """A user-created scene's own id is a device-assigned value outside
+    the ten built-in presets -- confirms this doesn't raise, and
+    scene_type comes back None rather than a wrong/guessed preset."""
+    raw = _scene_bytes(65000, 60, "Sushi", _light_primitive_bytes(VisualID.RoyalBlue, 500))
+    scenes = decode_configured_scenes([raw], PrimitiveType.VisualV1)
+
+    assert scenes[0].id == 65000
+    assert scenes[0].scene_type is None
+    assert scenes[0].name == "Sushi"
+
+
+def test_decode_multiple_slots_preserves_index_order():
+    raw1 = _scene_bytes(int(SceneID.EmptyScene), 0, "", bytes(3))
+    raw2 = _scene_bytes(int(SceneID.AllOn), 60, "Bright", _light_primitive_bytes(VisualID.RoyalBlue, 1000))
+    scenes = decode_configured_scenes([raw1, raw2], PrimitiveType.VisualV1)
+
+    assert len(scenes) == 2
+    assert scenes[0].index == 0 and scenes[0].name == ""
+    assert scenes[1].index == 1 and scenes[1].name == "Bright"
+
+
+def test_decode_skips_elements_shorter_than_the_header():
+    raw_short = bytes(10)  # shorter than the 20-byte header
+    raw_ok = _scene_bytes(int(SceneID.AllOn), 60, "Bright", _light_primitive_bytes(VisualID.RoyalBlue, 1000))
+    scenes = decode_configured_scenes([raw_short, raw_ok], PrimitiveType.VisualV1)
+
+    assert len(scenes) == 1
+    assert scenes[0].name == "Bright"
+
+
+def test_decode_with_no_primitive_type_leaves_light_and_pump_none():
+    raw = _scene_bytes(int(SceneID.AllOn), 60, "Bright", _light_primitive_bytes(VisualID.RoyalBlue, 1000))
+    scenes = decode_configured_scenes([raw], None)
+
+    assert scenes[0].light is None
+    assert scenes[0].pump is None
+    assert scenes[0].name == "Bright"
+
+
+# --------------------------------------------------------------------------
+# decode_active_scene -- the actual bug fix (used to raise on a custom id)
+# --------------------------------------------------------------------------
+
+def test_decode_active_scene_known_preset():
+    raw = struct.pack("<HH", int(SceneID.FeedMode), 45)
+    active = decode_active_scene(raw)
+
+    assert active.id == int(SceneID.FeedMode)
+    assert active.scene_type == SceneID.FeedMode
+    assert active.duration_seconds == 45
+
+
+def test_decode_active_scene_custom_id_does_not_raise():
+    """The actual bug this fixes: SceneID(scene_id) used to raise
+    ValueError outright whenever a custom (non-preset) scene was the
+    one currently active."""
+    raw = struct.pack("<HH", 65000, 12)
+    active = decode_active_scene(raw)
+
+    assert active.id == 65000
+    assert active.scene_type is None
+    assert active.duration_seconds == 12
+
+
+def test_decode_active_scene_too_short_returns_none():
+    assert decode_active_scene(bytes(2)) is None
+
+
+# --------------------------------------------------------------------------
+# Device methods
+# --------------------------------------------------------------------------
+
+def _fake_ble_device():
+    return BLEDevice("AA:BB:CC:DD:EE:FF", "MOBIUS", {})
+
+
+@pytest.mark.asyncio
+async def test_get_configured_scenes_reads_all_elements():
+    device = MobiusDevice(_fake_ble_device())
+    raw = _scene_bytes(int(SceneID.AllOn), 60, "Bright", _light_primitive_bytes(VisualID.RoyalBlue, 1000))
+    device.get_attribute = AsyncMock(return_value=[raw])
+
+    scenes = await device.get_configured_scenes(primitive=PrimitiveType.VisualV1)
+
+    device.get_attribute.assert_awaited_once()
+    call_args = device.get_attribute.call_args
+    assert call_args.kwargs.get("index") == 0
+    assert call_args.kwargs.get("count") == 0xFFFF
+    assert scenes[0].name == "Bright"
+
+
+@pytest.mark.asyncio
+async def test_get_current_scene_decodes_the_response():
+    device = MobiusDevice(_fake_ble_device())
+    raw = struct.pack("<HH", int(SceneID.FeedMode), 45)
+    device.get_attribute = AsyncMock(return_value=[raw])
+
+    active = await device.get_current_scene()
+
+    assert active.scene_type == SceneID.FeedMode
+    assert active.duration_seconds == 45
+
+
+@pytest.mark.asyncio
+async def test_get_current_scene_fails_soft_when_unsupported():
+    device = MobiusDevice(_fake_ble_device())
+    device.get_attribute = AsyncMock(side_effect=IOError("not supported"))
+
+    assert await device.get_current_scene() is None
+
+
+@pytest.mark.asyncio
+async def test_start_scene_writes_id_and_seconds():
+    """Confirms the actual unit is seconds, not minutes -- the
+    parameter used to be misleadingly named duration_minutes even
+    though the device treats it as seconds."""
+    device = MobiusDevice(_fake_ble_device())
+    device.set_attribute = AsyncMock()
+
+    await device.start_scene(int(SceneID.FeedMode), duration_seconds=90)
+
+    device.set_attribute.assert_awaited_once()
+    call_args = device.set_attribute.call_args
+    written = call_args.args[1] if len(call_args.args) > 1 else call_args.kwargs.get("value")
+    scene_id, seconds = struct.unpack("<HH", written)
+    assert scene_id == int(SceneID.FeedMode)
+    assert seconds == 90
+
+
+@pytest.mark.asyncio
+async def test_start_scene_accepts_a_custom_scene_id():
+    """A user-created scene's own id isn't a SceneID enum member at
+    all -- confirms start_scene() accepts a plain int, not just SceneID."""
+    device = MobiusDevice(_fake_ble_device())
+    device.set_attribute = AsyncMock()
+
+    await device.start_scene(65000, duration_seconds=0)
+
+    written = device.set_attribute.call_args.args[1]
+    scene_id, _ = struct.unpack("<HH", written)
+    assert scene_id == 65000