Merge pull request #51 from natekspencer/image-update

Don't update image unless playing or image hasn't been cached yet

.devcontainer/devcontainer.json

@@ -1,8 +1,8 @@
 // See https://aka.ms/vscode-remote/devcontainer.json for format details.
 {
   "name": "Home Assistant integration development",
-  "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.13-bullseye",
-  "postCreateCommand": "sudo apt-get update && sudo apt-get install libturbojpeg0",
+  "postCreateCommand": "sudo apt-get update && sudo apt-get install libturbojpeg0 libpcap0.8 -y",
   "postAttachCommand": "scripts/setup",
   "forwardPorts": [8123],
   "customizations": {

.github/workflows/update-tracks.yml

@@ -12,10 +12,10 @@ jobs:
     steps:
       - name: Checkout the repo
         uses: actions/checkout@v4
-      - name: Set up Python 3.12
+      - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
       - name: Install dependencies
         run: pip install homeassistant
       - name: Update tracks

README.md

@@ -56,6 +56,20 @@ Alternatively:
 
 After this integration is set up, you can configure the integration to connect to the Kinetic Oasis cloud API. This will allow pulling in certain details (such as track name and image) that are otherwise not available.
 
+# Actions
+
+The media player entity supports various actions, including managing the playlist queue. You can specify a track by its ID or name. If using a track name, it must match an entry in the [tracks list](custom_components/oasis_mini/pyoasismini/tracks.json). To specify multiple tracks, separate them with commas. An example is below:
+
+```yaml
+action: media_player.play_media
+target:
+  entity_id: media_player.oasis_mini
+data:
+  media_content_id: 63, Turtle
+  media_content_type: track
+  enqueue: replace
+```
+
 ---
 
 ## Support Me

config/configuration.yaml

@@ -4,6 +4,7 @@ automation:
 dhcp:
 frontend:
 history:
+isal:
 logbook:
 media_source:
 

custom_components/oasis_mini/__init__.py

@@ -19,6 +19,7 @@ type OasisMiniConfigEntry = ConfigEntry[OasisMiniCoordinator]
 _LOGGER = logging.getLogger(__name__)
 
 PLATFORMS = [
+    Platform.BINARY_SENSOR,
     Platform.BUTTON,
     Platform.IMAGE,
     Platform.LIGHT,

custom_components/oasis_mini/binary_sensor.py

@@ -0,0 +1,55 @@
+"""Oasis Mini binary sensor entity."""
+
+from __future__ import annotations
+
+from homeassistant.components.binary_sensor import (
+    BinarySensorDeviceClass,
+    BinarySensorEntity,
+    BinarySensorEntityDescription,
+)
+from homeassistant.const import EntityCategory
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+
+from . import OasisMiniConfigEntry
+from .coordinator import OasisMiniCoordinator
+from .entity import OasisMiniEntity
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: OasisMiniConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis Mini sensors using config entry."""
+    coordinator: OasisMiniCoordinator = entry.runtime_data
+    async_add_entities(
+        OasisMiniBinarySensorEntity(coordinator, descriptor)
+        for descriptor in DESCRIPTORS
+    )
+
+
+DESCRIPTORS = {
+    BinarySensorEntityDescription(
+        key="busy",
+        translation_key="busy",
+        entity_category=EntityCategory.DIAGNOSTIC,
+        entity_registry_enabled_default=False,
+    ),
+    BinarySensorEntityDescription(
+        key="wifi_connected",
+        translation_key="wifi_status",
+        device_class=BinarySensorDeviceClass.CONNECTIVITY,
+        entity_category=EntityCategory.DIAGNOSTIC,
+        entity_registry_enabled_default=False,
+    ),
+}
+
+
+class OasisMiniBinarySensorEntity(OasisMiniEntity, BinarySensorEntity):
+    """Oasis Mini binary sensor entity."""
+
+    @property
+    def is_on(self) -> bool:
+        """Return true if the binary sensor is on."""
+        return getattr(self.device, self.entity_description.key)

custom_components/oasis_mini/button.py

@@ -58,7 +58,7 @@ DESCRIPTORS = (
     ),
     OasisMiniButtonEntityDescription(
         key="random_track",
-        name="Play random track",
+        translation_key="random_track",
         press_fn=play_random_track,
     ),
 )

custom_components/oasis_mini/helpers.py

@@ -2,11 +2,14 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Any
 
 from homeassistant.const import CONF_ACCESS_TOKEN, CONF_HOST
 
-from .pyoasismini import OasisMini
+from .pyoasismini import TRACKS, OasisMini
+
+_LOGGER = logging.getLogger(__name__)
 
 
 def create_client(data: dict[str, Any]) -> OasisMini:
@@ -27,3 +30,21 @@ async def add_and_play_track(device: OasisMini, track: int) -> None:
 
     if device.status_code != 4:
         await device.async_play()
+
+
+def get_track_id(track: str) -> int | None:
+    """Get a track id.
+
+    `track` can be either an id or title
+    """
+    track = track.lower().strip()
+    if track not in map(str, TRACKS):
+        track = next(
+            (id for id, info in TRACKS.items() if info["name"].lower() == track), track
+        )
+
+    try:
+        return int(track)
+    except ValueError:
+        _LOGGER.warning("Invalid track: %s", track)
+        return None

custom_components/oasis_mini/icons.json

@@ -0,0 +1,45 @@
+{
+  "entity": {
+    "binary_sensor": {
+      "wifi_status": {
+        "default": "mdi:wifi",
+        "state": {
+          "off": "mdi:wifi-off"
+        }
+      }
+    },
+    "sensor": {
+      "download_progress": {
+        "default": "mdi:progress-download"
+      },
+      "drawing_progress": {
+        "default": "mdi:progress-pencil"
+      },
+      "error": {
+        "default": "mdi:alert-circle-outline",
+        "state": {
+          "0": "mdi:circle-outline"
+        }
+      },
+      "status": {
+        "state": {
+          "booting": "mdi:loading",
+          "centering": "mdi:record-circle-outline",
+          "downloading": "mdi:progress-download",
+          "error": "mdi:alert-circle-outline",
+          "live": "mdi:pencil-circle-outline",
+          "paused": "mdi:motion-pause-outline",
+          "playing": "mdi:motion-play-outline",
+          "stopped": "mdi:stop-circle-outline",
+          "updating": "mdi:update"
+        }
+      },
+      "wifi_connected": {
+        "default": "mdi:wifi",
+        "state": {
+          "off": "mdi:wifi-off"
+        }
+      }
+    }
+  }
+}

custom_components/oasis_mini/image.py

@@ -42,9 +42,10 @@ class OasisMiniImageEntity(OasisMiniEntity, ImageEntity):
     @callback
     def _handle_coordinator_update(self) -> None:
         """Handle updated data from the coordinator."""
-        if self._track_id != self.device.track_id or (
+        if (
-            self._progress != self.device.progress and self.device.access_token
+            self._track_id != self.device.track_id
-        ):
+            or (self._progress != self.device.progress and self.device.access_token)
+        ) 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._progress = self.device.progress

custom_components/oasis_mini/light.py

@@ -106,7 +106,7 @@ class OasisMiniLightEntity(OasisMiniEntity, LightEntity):
         await self.coordinator.async_request_refresh()
 
 
-DESCRIPTOR = LightEntityDescription(key="led", name="LED")
+DESCRIPTOR = LightEntityDescription(key="led", translation_key="led")
 
 
 async def async_setup_entry(

custom_components/oasis_mini/media_player.py

@@ -19,7 +19,9 @@ from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
 from . import OasisMiniConfigEntry
+from .const import DOMAIN
 from .entity import OasisMiniEntity
+from .helpers import get_track_id
 from .pyoasismini.const import TRACKS
 
 
@@ -102,18 +104,30 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
             return MediaPlayerState.ON
         return MediaPlayerState.IDLE
 
+    def abort_if_busy(self) -> None:
+        """Abort if the device is currently busy."""
+        if self.device.busy:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="device_busy",
+                translation_placeholders={"name": self._friendly_name_internal()},
+            )
+
     async def async_media_pause(self) -> None:
         """Send pause command."""
+        self.abort_if_busy()
         await self.device.async_pause()
         await self.coordinator.async_request_refresh()
 
     async def async_media_play(self) -> None:
         """Send play command."""
+        self.abort_if_busy()
         await self.device.async_play()
         await self.coordinator.async_request_refresh()
 
     async def async_media_stop(self) -> None:
         """Send stop command."""
+        self.abort_if_busy()
         await self.device.async_stop()
         await self.coordinator.async_request_refresh()
 
@@ -127,6 +141,7 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
 
     async def async_media_previous_track(self) -> None:
         """Send previous track command."""
+        self.abort_if_busy()
         if (index := self.device.playlist_index - 1) < 0:
             index = len(self.device.playlist) - 1
         await self.device.async_change_track(index)
@@ -134,6 +149,7 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
 
     async def async_media_next_track(self) -> None:
         """Send next track command."""
+        self.abort_if_busy()
         if (index := self.device.playlist_index + 1) >= len(self.device.playlist):
             index = 0
         await self.device.async_change_track(index)
@@ -147,32 +163,35 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
         **kwargs: Any,
     ) -> None:
         """Play a piece of media."""
-        if media_id not in map(str, TRACKS):
+        self.abort_if_busy()
-            media_id = next(
+        if media_type == MediaType.PLAYLIST:
-                (
+            raise ServiceValidationError(
-                    id
+                translation_domain=DOMAIN, translation_key="playlists_unsupported"
-                    for id, info in TRACKS.items()
-                    if info["name"].lower() == media_id.lower()
-                ),
-                media_id,
             )
-        try:
+        else:
-            track = int(media_id)
+            track = list(filter(None, map(get_track_id, media_id.split(","))))
-        except ValueError as err:
+            if not track:
-            raise ServiceValidationError(f"Invalid media: {media_id}") from err
+                raise ServiceValidationError(
+                    translation_domain=DOMAIN,
+                    translation_key="invalid_media",
+                    translation_placeholders={"media": media_id},
+                )
 
         device = self.device
         enqueue = MediaPlayerEnqueue.NEXT if not enqueue else enqueue
         if enqueue == MediaPlayerEnqueue.REPLACE:
-            await device.async_set_playlist([track])
+            await device.async_set_playlist(track)
         else:
             await device.async_add_track_to_playlist(track)
 
         if enqueue in (MediaPlayerEnqueue.NEXT, MediaPlayerEnqueue.PLAY):
             # Move track to next item in the playlist
-            if (index := (len(device.playlist) - 1)) != device.playlist_index:
+            new_tracks = 1 if isinstance(track, int) else len(track)
+            if (index := (len(device.playlist) - new_tracks)) != device.playlist_index:
                 if index != (
-                    _next := min(device.playlist_index + 1, len(device.playlist) - 1)
+                    _next := min(
+                        device.playlist_index + 1, len(device.playlist) - new_tracks
+                    )
                 ):
                     await device.async_move_track(index, _next)
                 if enqueue == MediaPlayerEnqueue.PLAY:
@@ -188,6 +207,7 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
 
     async def async_clear_playlist(self) -> None:
         """Clear players playlist."""
+        self.abort_if_busy()
         await self.device.async_clear_playlist()
         await self.coordinator.async_request_refresh()
 

custom_components/oasis_mini/number.py

@@ -35,14 +35,14 @@ class OasisMiniNumberEntity(OasisMiniEntity, NumberEntity):
 DESCRIPTORS = {
     NumberEntityDescription(
         key="ball_speed",
-        name="Ball speed",
+        translation_key="ball_speed",
         mode=NumberMode.SLIDER,
         native_max_value=BALL_SPEED_MAX,
         native_min_value=BALL_SPEED_MIN,
     ),
     NumberEntityDescription(
         key="led_speed",
-        name="LED speed",
+        translation_key="led_speed",
         mode=NumberMode.SLIDER,
         native_max_value=LED_SPEED_MAX,
         native_min_value=LED_SPEED_MIN,

custom_components/oasis_mini/pyoasismini/__init__.py

@@ -1,15 +1,16 @@
 """Oasis Mini API client."""
 
+from __future__ import annotations
+
 import asyncio
 import logging
 from typing import Any, Awaitable, Final
 from urllib.parse import urljoin
 
 from aiohttp import ClientResponseError, ClientSession
-import async_timeout
 
 from .const import TRACKS
-from .utils import _bit_to_bool
+from .utils import _bit_to_bool, decrypt_svg_content
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -33,7 +34,6 @@ AUTOPLAY_MAP = {
     "4": "30 minutes",
 }
 
-
 LED_EFFECTS: Final[dict[str, str]] = {
     "0": "Solid",
     "1": "Rainbow",
@@ -112,6 +112,7 @@ class OasisMini:
         """Return the drawing progress percent."""
         if not (self.track and (svg_content := self.track.get("svg_content"))):
             return None
+        svg_content = decrypt_svg_content(svg_content)
         paths = svg_content.split("L")
         total = self.track.get("reduced_svg_content", {}).get("1", len(paths))
         percent = (100 * self.progress) / total
@@ -157,17 +158,17 @@ class OasisMini:
         """Return the url."""
         return f"http://{self._host}/"
 
-    async def async_add_track_to_playlist(self, track: int) -> None:
+    async def async_add_track_to_playlist(self, track: int | list[int]) -> None:
         """Add track to playlist."""
         if not track:
             return
-
+        if isinstance(track, int):
+            track = [track]
         if 0 in self.playlist:
-            playlist = [t for t in self.playlist if t] + [track]
+            playlist = [t for t in self.playlist if t] + track
             return await self.async_set_playlist(playlist)
-
         await self._async_command(params={"ADDJOBLIST": track})
-        self.playlist.append(track)
+        self.playlist.extend(track)
 
     async def async_change_track(self, index: int) -> None:
         """Change the track."""
@@ -310,8 +311,10 @@ class OasisMini:
             raise ValueError("Invalid pause option specified")
         await self._async_command(params={"WRIWAITAFTER": option})
 
-    async def async_set_playlist(self, playlist: list[int]) -> None:
+    async def async_set_playlist(self, playlist: list[int] | int) -> None:
         """Set the playlist."""
+        if isinstance(playlist, int):
+            playlist = [playlist]
         if is_playing := (self.status_code == 4):
             await self.async_stop()
         await self._async_command(params={"WRIJOBLIST": ",".join(map(str, playlist))})

custom_components/oasis_mini/pyoasismini/utils.py

@@ -1,11 +1,17 @@
 """Oasis Mini utils."""
 
+from __future__ import annotations
+
+import base64
 import logging
 import math
 from xml.etree.ElementTree import Element, SubElement, tostring
 
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
 _LOGGER = logging.getLogger(__name__)
 
+APP_KEY = "5joW8W4Usk4xUXu5bIIgGiHloQmzMZUMgz6NWQnNI04="
 
 BACKGROUND_FILL = ("#CCC9C4", "#28292E")
 COLOR_DARK = ("#28292E", "#F4F5F8")
@@ -25,6 +31,7 @@ def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
     if track and (svg_content := track.get("svg_content")):
         try:
             if progress is not None:
+                svg_content = decrypt_svg_content(svg_content)
                 paths = svg_content.split("L")
                 total = track.get("reduced_svg_content", {}).get(model_id, len(paths))
                 percent = min((100 * progress) / total, 100)
@@ -137,3 +144,28 @@ def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
         except Exception as e:
             _LOGGER.exception(e)
     return None
+
+
+def decrypt_svg_content(svg_content: dict[str, str]):
+    """Decrypt SVG content using AES CBC mode."""
+    if decrypted := svg_content.get("decrypted"):
+        return decrypted
+
+    # decode base64-encoded data
+    key = base64.b64decode(APP_KEY)
+    iv = base64.b64decode(svg_content["iv"])
+    ciphertext = base64.b64decode(svg_content["content"])
+
+    # create the cipher and decrypt the ciphertext
+    cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+    decrypted = decryptor.update(ciphertext) + decryptor.finalize()
+
+    # remove PKCS7 padding
+    pad_len = decrypted[-1]
+    decrypted = decrypted[:-pad_len].decode("utf-8")
+
+    # save decrypted data so we don't have to do this each time
+    svg_content["decrypted"] = decrypted
+
+    return decrypted

custom_components/oasis_mini/select.py

@@ -85,20 +85,20 @@ def playlist_update_handler(entity: OasisMiniSelectEntity) -> None:
 
 
 DESCRIPTORS = (
-    OasisMiniSelectEntityDescription(
-        key="playlist",
-        name="Playlist",
-        current_value=lambda device: (device.playlist.copy(), device.playlist_index),
-        select_fn=lambda device, option: device.async_change_track(option),
-        update_handler=playlist_update_handler,
-    ),
     OasisMiniSelectEntityDescription(
         key="autoplay",
-        name="Autoplay",
+        translation_key="autoplay",
         options=list(AUTOPLAY_MAP.values()),
         current_value=lambda device: device.autoplay,
         select_fn=lambda device, option: device.async_set_autoplay(option),
     ),
+    OasisMiniSelectEntityDescription(
+        key="playlist",
+        translation_key="playlist",
+        current_value=lambda device: (device.playlist.copy(), device.playlist_index),
+        select_fn=lambda device, option: device.async_change_track(option),
+        update_handler=playlist_update_handler,
+    ),
 )
 
 

custom_components/oasis_mini/sensor.py

@@ -39,34 +39,27 @@ async def async_setup_entry(
 DESCRIPTORS = {
     SensorEntityDescription(
         key="download_progress",
+        translation_key="download_progress",
         entity_category=EntityCategory.DIAGNOSTIC,
         entity_registry_enabled_default=False,
-        name="Download progress",
         native_unit_of_measurement=PERCENTAGE,
         state_class=SensorStateClass.MEASUREMENT,
     ),
 } | {
     SensorEntityDescription(
         key=key,
-        name=key.replace("_", " ").capitalize(),
         translation_key=key,
         entity_category=EntityCategory.DIAGNOSTIC,
         entity_registry_enabled_default=False,
     )
-    for key in (
+    for key in ("error", "led_color_id", "status")
-        "busy",
-        "error",
-        "led_color_id",
-        "status",
-        "wifi_connected",
-    )
 }
 
 CLOUD_DESCRIPTORS = (
     SensorEntityDescription(
         key="drawing_progress",
+        translation_key="drawing_progress",
         entity_category=EntityCategory.DIAGNOSTIC,
-        name="Drawing progress",
         native_unit_of_measurement=PERCENTAGE,
         state_class=SensorStateClass.MEASUREMENT,
         suggested_display_precision=1,

custom_components/oasis_mini/strings.json

@@ -38,7 +38,53 @@
     }
   },
   "entity": {
+    "button": {
+      "random_track": {
+        "name": "Play random track"
+      }
+    },
+    "binary_sensor": {
+      "busy": {
+        "name": "Busy"
+      },
+      "wifi_status": {
+        "name": "Wi-Fi status"
+      }
+    },
+    "light": {
+      "led": {
+        "name": "LED"
+      }
+    },
+    "number": {
+      "ball_speed": {
+        "name": "Ball speed"
+      },
+      "led_speed": {
+        "name": "LED speed"
+      }
+    },
+    "select": {
+      "autoplay": {
+        "name": "Autoplay"
+      },
+      "playlist": {
+        "name": "Playlist"
+      }
+    },
     "sensor": {
+      "download_progress": {
+        "name": "Download progress"
+      },
+      "drawing_progress": {
+        "name": "Drawing progress"
+      },
+      "error": {
+        "name": "Error"
+      },
+      "led_color_id": {
+        "name": "LED color ID"
+      },
       "status": {
         "name": "Status",
         "state": {
@@ -54,5 +100,16 @@
         }
       }
     }
+  },
+  "exceptions": {
+    "device_busy": {
+      "message": "{name} is currently busy and cannot be modified"
+    },
+    "invalid_media": {
+      "message": "Invalid media: {media}"
+    },
+    "playlists_unsupported": {
+      "message": "Playlists are not currently supported"
+    }
   }
 }

custom_components/oasis_mini/translations/en.json

@@ -38,7 +38,53 @@
     }
   },
   "entity": {
+    "button": {
+      "random_track": {
+        "name": "Play random track"
+      }
+    },
+    "binary_sensor": {
+      "busy": {
+        "name": "Busy"
+      },
+      "wifi_status": {
+        "name": "Wi-Fi status"
+      }
+    },
+    "light": {
+      "led": {
+        "name": "LED"
+      }
+    },
+    "number": {
+      "ball_speed": {
+        "name": "Ball speed"
+      },
+      "led_speed": {
+        "name": "LED speed"
+      }
+    },
+    "select": {
+      "autoplay": {
+        "name": "Autoplay"
+      },
+      "playlist": {
+        "name": "Playlist"
+      }
+    },
     "sensor": {
+      "download_progress": {
+        "name": "Download progress"
+      },
+      "drawing_progress": {
+        "name": "Drawing progress"
+      },
+      "error": {
+        "name": "Error"
+      },
+      "led_color_id": {
+        "name": "LED color ID"
+      },
       "status": {
         "name": "Status",
         "state": {
@@ -54,5 +100,16 @@
         }
       }
     }
+  },
+  "exceptions": {
+    "device_busy": {
+      "message": "{name} is currently busy and cannot be modified"
+    },
+    "invalid_media": {
+      "message": "Invalid media: {media}"
+    },
+    "playlists_unsupported": {
+      "message": "Playlists are not currently supported"
+    }
   }
 }

hacs.json

@@ -1,6 +1,6 @@
 {
   "name": "Oasis Mini",
-  "homeassistant": "2024.4.0",
+  "homeassistant": "2024.5.0",
   "render_readme": true,
   "zip_release": true,
   "filename": "oasis_mini.zip"

requirements.txt

@@ -1,10 +1,11 @@
 # Home Assistant
-homeassistant>=2024.4
+homeassistant>=2025.1
 numpy
 PyTurboJPEG
 
 # Integration
-aiohttp
+aiohttp # should already be installed with Home Assistant
+cryptography # should already be installed with Home Assistant
 
 # Development
 colorlog