Add additional helpers

README.md

@@ -10,9 +10,9 @@
   <img alt="Oasis Mini logo" src="https://brands.home-assistant.io/oasis_mini/logo.png">
 </picture>
 
-# Oasis Mini for Home Assistant
+# Oasis Control for Home Assistant
 
-Home Assistant integration for Oasis Mini kinetic sand art devices.
+Home Assistant integration for Oasis kinetic sand art devices.
 
 # Installation
 
@@ -43,13 +43,13 @@ While the manual installation above seems like less steps, it's important to not
 
 [![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=oasis_mini)
 
-There is a config flow for this Oasis Mini integration. After installing the custom component, use the convenient My Home Assistant link above.
+There is a config flow for this Oasis Control integration. After installing the custom component, use the convenient My Home Assistant link above.
 
 Alternatively:
 
 1. Go to **Configuration**->**Integrations**
 2. Click **+ ADD INTEGRATION** to setup a new integration
-3. Search for **Oasis Mini** and click on it
+3. Search for **Oasis Control** and click on it
 4. You will be guided through the rest of the setup process via the config flow
 
 # Options
@@ -76,6 +76,6 @@ data:
 
 I'm not employed by Kinetic Oasis, and provide this custom component purely for your own enjoyment and home automation needs.
 
-If you already own an Oasis Mini, found this integration useful and want to donate, consider [sponsoring me on GitHub](https://github.com/sponsors/natekspencer) or buying me a coffee ☕ (or beer 🍺) instead by using the link below:
+If you already own an Oasis device, found this integration useful and want to donate, consider [sponsoring me on GitHub](https://github.com/sponsors/natekspencer) or buying me a coffee ☕ (or beer 🍺) instead by using the link below:
 
 <a href='https://ko-fi.com/Y8Y57F59S' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi1.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>

custom_components/oasis_mini/__init__.py

@@ -10,6 +10,7 @@ from homeassistant.const import CONF_EMAIL, Platform
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.exceptions import ConfigEntryAuthFailed
 import homeassistant.helpers.entity_registry as er
+import homeassistant.util.dt as dt_util
 
 from .coordinator import OasisDeviceCoordinator
 from .helpers import create_client
@@ -59,6 +60,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry)
     entry.runtime_data = coordinator
 
     def _on_oasis_update() -> None:
+        coordinator.last_updated = dt_util.now()
         coordinator.async_update_listeners()
 
     for device in coordinator.data:

custom_components/oasis_mini/coordinator.py

@@ -9,6 +9,7 @@ import async_timeout
 
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+import homeassistant.util.dt as dt_util
 
 from .const import DOMAIN
 from .pyoasiscontrol import OasisCloudClient, OasisDevice, OasisMqttClient
@@ -52,6 +53,7 @@ class OasisDeviceCoordinator(DataUpdateCoordinator[list[OasisDevice]]):
                         OasisDevice(
                             model=raw_device.get("model", {}).get("name"),
                             serial_number=raw_device.get("serial_number"),
+                            cloud=self.cloud_client,
                         )
                         for raw_device in raw_devices
                     ]
@@ -60,16 +62,12 @@ class OasisDeviceCoordinator(DataUpdateCoordinator[list[OasisDevice]]):
                 for device in devices:
                     self.mqtt_client.register_device(device)
                     await self.mqtt_client.wait_until_ready(device, request_status=True)
-                    if not device.mac_address:
+                    if not await device.async_get_mac_address():
-                        await device.async_get_mac_address()
+                        raise Exception(
-                    # if not device.software_version:
+                            "Could not get mac address for %s", device.serial_number
-                    #     await device.async_get_software_version()
+                        )
-                # data = await self.device.async_get_status()
+                await self.cloud_client.async_get_playlists()
-                # devices = self.cloud_client.mac_address
                 self.attempt = 0
-                # await self.device.async_get_current_track_details()
-                # await self.device.async_get_playlist_details()
-                # await self.device.async_cloud_get_playlists()
         except Exception as ex:  # pylint:disable=broad-except
             if self.attempt > 2 or not (devices or self.data):
                 raise UpdateFailed(
@@ -77,5 +75,5 @@ class OasisDeviceCoordinator(DataUpdateCoordinator[list[OasisDevice]]):
                 ) from ex
 
         if devices != self.data:
-            self.last_updated = datetime.now()
+            self.last_updated = dt_util.now()
         return devices

custom_components/oasis_mini/entity.py

@@ -30,8 +30,12 @@ class OasisDeviceEntity(CoordinatorEntity[OasisDeviceCoordinator]):
         serial_number = device.serial_number
         self._attr_unique_id = f"{serial_number}-{description.key}"
 
+        connections = set()
+        if mac_address := device.mac_address:
+            connections.add((CONNECTION_NETWORK_MAC, format_mac(mac_address)))
+
         self._attr_device_info = DeviceInfo(
-            connections={(CONNECTION_NETWORK_MAC, format_mac(device.mac_address))},
+            connections=connections,
             identifiers={(DOMAIN, serial_number)},
             name=f"{device.model} {serial_number}",
             manufacturer=device.manufacturer,

custom_components/oasis_mini/helpers.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import Any
 
+import async_timeout
+
 from homeassistant.const import CONF_ACCESS_TOKEN
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.aiohttp_client import async_get_clientsession
@@ -23,12 +26,18 @@ def create_client(hass: HomeAssistant, data: dict[str, Any]) -> OasisCloudClient
 
 async def add_and_play_track(device: OasisDevice, track: int) -> None:
     """Add and play a track."""
+    async with async_timeout.timeout(10):
         if track not in device.playlist:
             await device.async_add_track_to_playlist(track)
 
+        while track not in device.playlist:
+            await asyncio.sleep(0.1)
+
         # Move track to next item in the playlist and then select it
         if (index := device.playlist.index(track)) != device.playlist_index:
-        if index != (_next := min(device.playlist_index + 1, len(device.playlist) - 1)):
+            if index != (
+                _next := min(device.playlist_index + 1, len(device.playlist) - 1)
+            ):
                 await device.async_move_track(index, _next)
             await device.async_change_track(_next)
 

custom_components/oasis_mini/image.py

@@ -11,8 +11,6 @@ from . import OasisDeviceConfigEntry
 from .coordinator import OasisDeviceCoordinator
 from .entity import OasisDeviceEntity
 from .pyoasiscontrol import OasisDevice
-from .pyoasiscontrol.const import TRACKS
-from .pyoasiscontrol.utils import draw_svg
 
 
 async def async_setup_entry(
@@ -52,33 +50,24 @@ class OasisDeviceImageEntity(OasisDeviceEntity, ImageEntity):
     def image(self) -> bytes | None:
         """Return bytes of image."""
         if not self._cached_image:
-            self._cached_image = Image(
+            self._cached_image = Image(self.content_type, self.device.create_svg())
-                self.content_type, draw_svg(self.device.track, self._progress, "1")
-            )
         return self._cached_image.content
 
     @callback
     def _handle_coordinator_update(self) -> None:
         """Handle updated data from the coordinator."""
+        device = self.device
         if (
-            self._track_id != self.device.track_id
+            self._track_id != device.track_id or self._progress != device.progress
-            or self._progress != self.device.progress
+        ) and (device.status == "playing" or self._cached_image is None):
-        ) and (self.device.status == "playing" or self._cached_image is None):
             self._attr_image_last_updated = self.coordinator.last_updated
-            self._track_id = self.device.track_id
+            self._track_id = device.track_id
-            self._progress = self.device.progress
+            self._progress = device.progress
             self._cached_image = None
-            if self.device.track and self.device.track.get("svg_content"):
+            if device.track and device.track.get("svg_content"):
                 self._attr_image_url = UNDEFINED
             else:
-                self._attr_image_url = (
+                self._attr_image_url = device.track_image_url
-                    f"https://app.grounded.so/uploads/{track['image']}"
-                    if (
-                        track := (self.device.track or TRACKS.get(self.device.track_id))
-                    )
-                    and "image" in track
-                    else None
-                )
 
         if self.hass:
             super()._handle_coordinator_update()

custom_components/oasis_mini/media_player.py

@@ -23,7 +23,6 @@ from .const import DOMAIN
 from .coordinator import OasisDeviceCoordinator
 from .entity import OasisDeviceEntity
 from .helpers import get_track_id
-from .pyoasiscontrol.const import TRACKS
 
 
 async def async_setup_entry(
@@ -73,11 +72,7 @@ class OasisDeviceMediaPlayerEntity(OasisDeviceEntity, MediaPlayerEntity):
     @property
     def media_image_url(self) -> str | None:
         """Image url of current playing media."""
-        if not (track := self.device.track):
+        return self.device.track_image_url
-            track = TRACKS.get(self.device.track_id)
-        if track and "image" in track:
-            return f"https://app.grounded.so/uploads/{track['image']}"
-        return None
 
     @property
     def media_position(self) -> int:
@@ -92,11 +87,7 @@ class OasisDeviceMediaPlayerEntity(OasisDeviceEntity, MediaPlayerEntity):
     @property
     def media_title(self) -> str | None:
         """Title of current playing media."""
-        if not self.device.track_id:
+        return self.device.track_name
-            return None
-        if not (track := self.device.track):
-            track = TRACKS.get(self.device.track_id, {})
-        return track.get("name", f"Unknown Title (#{self.device.track_id})")
 
     @property
     def repeat(self) -> RepeatMode:

custom_components/oasis_mini/pyoasiscontrol/clients/cloud_client.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from datetime import timedelta
+from datetime import datetime, timedelta
 import logging
 from typing import Any
 from urllib.parse import urljoin
@@ -37,7 +37,7 @@ class OasisCloudClient:
     _access_token: str | None
 
     # these are "cache" fields for tracks/playlists
-    _playlists_next_refresh: float
+    _playlists_next_refresh: datetime
     playlists: list[dict[str, Any]]
     _playlist_details: dict[int, dict[str, str]]
 
@@ -52,7 +52,7 @@ class OasisCloudClient:
         self._access_token = access_token
 
         # simple in-memory caches
-        self._playlists_next_refresh = 0.0
+        self._playlists_next_refresh = now()
         self.playlists = []
         self._playlist_details = {}
 

custom_components/oasis_mini/pyoasiscontrol/clients/mqtt_client.py

@@ -143,8 +143,9 @@ class OasisMqttClient(OasisClientProtocol):
     async def _resubscribe_all(self) -> None:
         """Resubscribe to all known devices after (re)connect."""
         self._subscribed_serials.clear()
-        for serial in list(self._devices):
+        for serial, device in self._devices.items():
             await self._subscribe_serial(serial)
+            await self.async_get_all(device)
 
     def start(self) -> None:
         """Start MQTT connection loop."""
@@ -316,9 +317,6 @@ class OasisMqttClient(OasisClientProtocol):
         payload = f"WRIJOBLIST={track_str}"
         await self._publish_command(device, payload)
 
-        # local state optimistic update
-        device.update_from_status_dict({"playlist": playlist})
-
     async def async_send_set_repeat_playlist_command(
         self,
         device: OasisDevice,

custom_components/oasis_mini/pyoasiscontrol/device.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import TYPE_CHECKING, Any, Callable, Final, Iterable
 
@@ -12,9 +13,10 @@ from .const import (
     STATUS_CODE_SLEEPING,
     TRACKS,
 )
-from .utils import _bit_to_bool, _parse_int
+from .utils import _bit_to_bool, _parse_int, create_svg, decrypt_svg_content
 
 if TYPE_CHECKING:  # avoid runtime circular imports
+    from .clients import OasisCloudClient
     from .clients.transport import OasisClientProtocol
 
 _LOGGER = logging.getLogger(__name__)
@@ -62,10 +64,12 @@ class OasisDevice:
         serial_number: str | None = None,
         ssid: str | None = None,
         ip_address: str | None = None,
+        cloud: OasisCloudClient | None = None,
         client: OasisClientProtocol | None = None,
     ) -> None:
         # Transport
-        self._client: OasisClientProtocol | None = client
+        self._cloud = cloud
+        self._client = client
         self._listeners: list[Callable[[], None]] = []
 
         # Details
@@ -105,8 +109,9 @@ class OasisDevice:
         self.environment: str | None = None
         self.schedule: Any | None = None
 
-        # Track metadata cache (used if you hydrate from cloud)
+        # Track metadata cache
         self._track: dict | None = None
+        self._track_task: asyncio.Task | None = None
 
     @property
     def brightness(self) -> int:
@@ -157,13 +162,20 @@ class OasisDevice:
     def update_from_status_dict(self, data: dict[str, Any]) -> None:
         """Update device fields from a status payload (from any transport)."""
         changed = False
+        playlist_or_index_changed = False
+
         for key, value in data.items():
             if hasattr(self, key):
                 if self._update_field(key, value):
                     changed = True
+                    if key in ("playlist", "playlist_index"):
+                        playlist_or_index_changed = True
             else:
                 _LOGGER.warning("Unknown field: %s=%s", key, value)
 
+        if playlist_or_index_changed:
+            self._schedule_track_refresh()
+
         if changed:
             self._notify_listeners()
 
@@ -243,6 +255,13 @@ class OasisDevice:
         """Return human-readable status from status_code."""
         return STATUS_CODE_MAP.get(self.status_code, f"Unknown ({self.status_code})")
 
+    @property
+    def track(self) -> dict | None:
+        """Return cached track info if it matches the current `track_id`."""
+        if (track := self._track) and track["id"] == self.track_id:
+            return track
+        return TRACKS.get(self.track_id)
+
     @property
     def track_id(self) -> int | None:
         if not self.playlist:
@@ -251,37 +270,45 @@ class OasisDevice:
         return self.playlist[0] if i >= len(self.playlist) else self.playlist[i]
 
     @property
-    def track(self) -> dict | None:
+    def track_image_url(self) -> str | None:
-        """Return cached track info if it matches the current `track_id`."""
+        """Return the track image url, if any."""
-        if self._track and self._track.get("id") == self.track_id:
+        if (track := self.track) and (image := track.get("image")):
-            return self._track
+            return f"https://app.grounded.so/uploads/{image}"
-        if track := TRACKS.get(self.track_id):
+        return None
-            self._track = track
+
-            return self._track
+    @property
+    def track_name(self) -> str | None:
+        """Return the track name, if any."""
+        if track := self.track:
+            return track.get("name", f"Unknown Title (#{self.track_id})")
         return None
 
     @property
     def drawing_progress(self) -> float | None:
         """Return drawing progress percentage for the current track."""
-        # if not (self.track and (svg_content := self.track.get("svg_content"))):
+        if not (self.track and (svg_content := self.track.get("svg_content"))):
-        #     return None
+            return None
-        # svg_content = decrypt_svg_content(svg_content)
+        svg_content = decrypt_svg_content(svg_content)
-        # paths = svg_content.split("L")
+        paths = svg_content.split("L")
-        total = self.track.get("reduced_svg_content_new", 0)  # or len(paths)
+        total = self.track.get("reduced_svg_content_new", 0) or len(paths)
         percent = (100 * self.progress) / total
-        return percent
+        return min(percent, 100)
 
     @property
     def playlist_details(self) -> dict[int, dict[str, str]]:
         """Basic playlist details using built-in TRACKS metadata."""
         return {
-            track_id: TRACKS.get(
+            track_id: {self.track_id: self.track or {}, **TRACKS}.get(
                 track_id,
                 {"name": f"Unknown Title (#{track_id})"},
             )
             for track_id in self.playlist
         }
 
+    def create_svg(self) -> str | None:
+        """Create the current svg based on track and progress."""
+        return create_svg(self.track, self.progress)
+
     def add_update_listener(self, listener: Callable[[], None]) -> Callable[[], None]:
         """Register a callback for state changes.
 
@@ -330,7 +357,7 @@ class OasisDevice:
         led_speed: int | None = None,
         brightness: int | None = None,
     ) -> None:
-        """Set the Oasis Mini LED (shared validation & attribute updates)."""
+        """Set the Oasis device LED (shared validation & attribute updates)."""
         if led_effect is None:
             led_effect = self.led_effect
         if color is None:
@@ -410,3 +437,43 @@ class OasisDevice:
     async def async_reboot(self) -> None:
         client = self._require_client()
         await client.async_send_reboot_command(self)
+
+    def _schedule_track_refresh(self) -> None:
+        """Schedule an async refresh of current track info if track_id changed."""
+        if not self._cloud:
+            return
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            _LOGGER.debug("No running loop; cannot schedule track refresh")
+            return
+
+        if self._track_task and not self._track_task.done():
+            self._track_task.cancel()
+
+        self._track_task = loop.create_task(self._async_refresh_current_track())
+
+    async def _async_refresh_current_track(self) -> None:
+        """Refresh the current track info."""
+        if not self._cloud:
+            return
+
+        if (track_id := self.track_id) is None:
+            self._track = None
+            return
+
+        if self._track and self._track.get("id") == track_id:
+            return
+
+        try:
+            track = await self._cloud.async_get_track_info(track_id)
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception("Error fetching track info for %s", track_id)
+            return
+
+        if not track:
+            return
+
+        self._track = track
+        self._notify_listeners()

custom_components/oasis_mini/pyoasiscontrol/utils.py

@@ -1,4 +1,4 @@
-"""Oasis Mini utils."""
+"""Oasis control utils."""
 
 from __future__ import annotations
 
@@ -35,8 +35,8 @@ def _parse_int(val: str) -> int:
         return 0
 
 
-def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
+def create_svg(track: dict, progress: int) -> str | None:
-    """Draw SVG."""
+    """Create an SVG from a track based on progress."""
     if track and (svg_content := track.get("svg_content")):
         try:
             if progress is not None:

custom_components/oasis_mini/select.py

@@ -27,7 +27,7 @@ def playlists_update_handler(entity: OasisDeviceSelectEntity) -> None:
     counts = defaultdict(int)
     options = []
     current_option: str | None = None
-    for playlist in device.playlists:
+    for playlist in device._cloud.playlists:
         name = playlist["name"]
         counts[name] += 1
         if counts[name] > 1:
@@ -71,18 +71,11 @@ async def async_setup_entry(
 ) -> None:
     """Set up Oasis device select using config entry."""
     coordinator: OasisDeviceCoordinator = entry.runtime_data
-    entities = [
+    async_add_entities(
         OasisDeviceSelectEntity(coordinator, device, descriptor)
         for device in coordinator.data
         for descriptor in DESCRIPTORS
-    ]
+    )
-    # if coordinator.device.access_token:
-    #     entities.extend(
-    #         OasisDeviceSelectEntity(coordinator, device, descriptor)
-    #         for device in coordinator.data
-    #         for descriptor in CLOUD_DESCRIPTORS
-    #     )
-    async_add_entities(entities)
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -104,6 +97,15 @@ DESCRIPTORS = (
             device.async_set_autoplay(AUTOPLAY_MAP_LIST[index])
         ),
     ),
+    OasisDeviceSelectEntityDescription(
+        key="playlists",
+        translation_key="playlist",
+        current_value=lambda device: (device._cloud.playlists, device.playlist.copy()),
+        select_fn=lambda device, index: device.async_set_playlist(
+            [pattern["id"] for pattern in device._cloud.playlists[index]["patterns"]]
+        ),
+        update_handler=playlists_update_handler,
+    ),
     OasisDeviceSelectEntityDescription(
         key="queue",
         translation_key="queue",
@@ -112,17 +114,6 @@ DESCRIPTORS = (
         update_handler=queue_update_handler,
     ),
 )
-CLOUD_DESCRIPTORS = (
-    OasisDeviceSelectEntityDescription(
-        key="playlists",
-        translation_key="playlist",
-        current_value=lambda device: (device.playlists, device.playlist.copy()),
-        select_fn=lambda device, index: device.async_set_playlist(
-            [pattern["id"] for pattern in device.playlists[index]["patterns"]]
-        ),
-        update_handler=playlists_update_handler,
-    ),
-)
 
 
 class OasisDeviceSelectEntity(OasisDeviceEntity, SelectEntity):

custom_components/oasis_mini/sensor.py

@@ -23,17 +23,11 @@ async def async_setup_entry(
 ) -> None:
     """Set up Oasis device sensors using config entry."""
     coordinator: OasisDeviceCoordinator = entry.runtime_data
-    entities = [
+    async_add_entities(
         OasisDeviceSensorEntity(coordinator, device, descriptor)
         for device in coordinator.data
         for descriptor in DESCRIPTORS
-    ]
-    entities.extend(
-        OasisDeviceSensorEntity(coordinator, device, descriptor)
-        for device in coordinator.data
-        for descriptor in CLOUD_DESCRIPTORS
     )
-    async_add_entities(entities)
 
 
 DESCRIPTORS = {
@@ -45,6 +39,14 @@ DESCRIPTORS = {
         native_unit_of_measurement=PERCENTAGE,
         state_class=SensorStateClass.MEASUREMENT,
     ),
+    SensorEntityDescription(
+        key="drawing_progress",
+        translation_key="drawing_progress",
+        entity_category=EntityCategory.DIAGNOSTIC,
+        native_unit_of_measurement=PERCENTAGE,
+        state_class=SensorStateClass.MEASUREMENT,
+        suggested_display_precision=1,
+    ),
 } | {
     SensorEntityDescription(
         key=key,
@@ -56,17 +58,6 @@ DESCRIPTORS = {
     # for key in ("error_message", "led_color_id", "status")
 }
 
-CLOUD_DESCRIPTORS = (
-    SensorEntityDescription(
-        key="drawing_progress",
-        translation_key="drawing_progress",
-        entity_category=EntityCategory.DIAGNOSTIC,
-        native_unit_of_measurement=PERCENTAGE,
-        state_class=SensorStateClass.MEASUREMENT,
-        suggested_display_precision=1,
-    ),
-)
-
 
 class OasisDeviceSensorEntity(OasisDeviceEntity, SensorEntity):
     """Oasis device sensor entity."""