Merge pull request #87 from natekspencer/error-translations

Add error translations

.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",
-  "postCreateCommand": "sudo apt-get update && sudo apt-get install libturbojpeg0",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.13-bookworm",
+  "postCreateCommand": "scripts/setup",
   "postAttachCommand": "scripts/setup",
   "forwardPorts": [8123],
   "customizations": {
@@ -26,7 +26,10 @@
         "editor.codeActionsOnSave": {
           "source.organizeImports": "always"
         },
-        "files.trimTrailingWhitespace": true
+        "files.trimTrailingWhitespace": true,
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff"
+        }
       }
     }
   },

.github/workflows/update-tracks.yml

@@ -1,7 +1,7 @@
 name: Update tracks
 on:
   schedule:
-    - cron: "0 19 * * *"
+    - cron: "0 19 * * 1"
 permissions:
   contents: write
   pull-requests: write
@@ -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

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.9.10
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format

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

@@ -3,12 +3,14 @@
 from __future__ import annotations
 
 import logging
+from typing import Any
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import Platform
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, callback
 from homeassistant.exceptions import ConfigEntryError, ConfigEntryNotReady
 import homeassistant.helpers.device_registry as dr
+import homeassistant.helpers.entity_registry as er
 
 from .const import DOMAIN
 from .coordinator import OasisMiniCoordinator
@@ -19,6 +21,7 @@ type OasisMiniConfigEntry = ConfigEntry[OasisMiniCoordinator]
 _LOGGER = logging.getLogger(__name__)
 
 PLATFORMS = [
+    Platform.BINARY_SENSOR,
     Platform.BUTTON,
     Platform.IMAGE,
     Platform.LIGHT,
@@ -88,3 +91,33 @@ async def async_remove_entry(hass: HomeAssistant, entry: OasisMiniConfigEntry) -
 async def update_listener(hass: HomeAssistant, entry: OasisMiniConfigEntry) -> None:
     """Handle options update."""
     await hass.config_entries.async_reload(entry.entry_id)
+
+
+async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry):
+    """Migrate old entry."""
+    _LOGGER.debug(
+        "Migrating configuration from version %s.%s", entry.version, entry.minor_version
+    )
+
+    if entry.version == 1 and entry.minor_version == 1:
+        # Need to update previous playlist select entity to queue
+        @callback
+        def migrate_unique_id(entity_entry: er.RegistryEntry) -> dict[str, Any] | None:
+            """Migrate the playlist unique ID to queue."""
+            if entity_entry.domain == "select" and entity_entry.unique_id.endswith(
+                "-playlist"
+            ):
+                unique_id = entity_entry.unique_id.replace("-playlist", "-queue")
+                return {"new_unique_id": unique_id}
+            return None
+
+        await er.async_migrate_entries(hass, entry.entry_id, migrate_unique_id)
+        hass.config_entries.async_update_entry(entry, minor_version=2, version=1)
+
+    _LOGGER.debug(
+        "Migration to configuration version %s.%s successful",
+        entry.version,
+        entry.minor_version,
+    )
+
+    return True

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,9 +58,14 @@ DESCRIPTORS = (
     ),
     OasisMiniButtonEntityDescription(
         key="random_track",
-        name="Play random track",
+        translation_key="random_track",
         press_fn=play_random_track,
     ),
+    OasisMiniButtonEntityDescription(
+        key="sleep",
+        translation_key="sleep",
+        press_fn=lambda device: device.async_sleep(),
+    ),
 )
 
 

custom_components/oasis_mini/config_flow.py

@@ -62,6 +62,7 @@ class OasisMiniConfigFlow(ConfigFlow, domain=DOMAIN):
     """Handle a config flow for Oasis Mini."""
 
     VERSION = 1
+    MINOR_VERSION = 2
 
     @staticmethod
     @callback

custom_components/oasis_mini/coordinator.py

@@ -50,6 +50,7 @@ class OasisMiniCoordinator(DataUpdateCoordinator[str]):
                 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 (data or self.data):
                 raise UpdateFailed(

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,47 @@
+{
+  "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",
+          "busy": "mdi:progress-clock",
+          "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",
+          "sleeping": "mdi:power-sleep",
+          "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 (
-            self._progress != self.device.progress and self.device.access_token
-        ):
+        if (
+            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
 
 
@@ -47,8 +49,8 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
     @property
     def media_duration(self) -> int | None:
         """Duration of current playing media in seconds."""
-        if (track := self.device.track) and "reduced_svg_content" in track:
-            return track["reduced_svg_content"].get("1")
+        if (track := self.device.track) and "reduced_svg_content_new" in track:
+            return track["reduced_svg_content_new"]
         return None
 
     @property
@@ -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):
-            media_id = next(
-                (
-                    id
-                    for id, info in TRACKS.items()
-                    if info["name"].lower() == media_id.lower()
-                ),
-                media_id,
+        self.abort_if_busy()
+        if media_type == MediaType.PLAYLIST:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN, translation_key="playlists_unsupported"
             )
-        try:
-            track = int(media_id)
-        except ValueError as err:
-            raise ServiceValidationError(f"Invalid media: {media_id}") from err
+        else:
+            track = list(filter(None, map(get_track_id, media_id.split(","))))
+            if not track:
+                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,39 +1,65 @@
 """Oasis Mini API client."""
 
+from __future__ import annotations
+
 import asyncio
+from datetime import datetime, timedelta
 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, _parse_int, decrypt_svg_content, now
 
 _LOGGER = logging.getLogger(__name__)
 
 STATUS_CODE_MAP = {
-    0: "booting",  # maybe?
+    0: "booting",
     2: "stopped",
     3: "centering",
     4: "playing",
     5: "paused",
+    6: "sleeping",
     9: "error",
     11: "updating",
     13: "downloading",
+    14: "busy",
     15: "live",
 }
 
+ERROR_CODE_MAP = {
+    0: "None",
+    1: "Error has occurred while reading the flash memory",
+    2: "Error while starting the Wifi",
+    3: "Error when starting DNS settings for your machine",
+    4: "Failed to open the file to write",
+    5: "Not enough memory to perform the upgrade",
+    6: "Error while trying to upgrade your system",
+    7: "Error while trying to download the new version of the software",
+    8: "Error while reading the upgrading file",
+    9: "Failed to start downloading the upgrade file",
+    10: "Error while starting downloading the job file",
+    11: "Error while opening the file folder",
+    12: "Failed to delete a file",
+    13: "Error while opening the job file",
+    14: "You have wrong power adapter",
+    15: "Failed to update the device IP on Oasis Server",
+    16: "Your device failed centering itself",
+    17: "There appears to be an issue with your Oasis Device",
+    18: "Error while downloading the job file",
+}
+
 AUTOPLAY_MAP = {
     "0": "on",
     "1": "off",
     "2": "5 minutes",
     "3": "10 minutes",
     "4": "30 minutes",
+    "5": "24 hours",
 }
 
-
 LED_EFFECTS: Final[dict[str, str]] = {
     "0": "Solid",
     "1": "Rainbow",
@@ -50,15 +76,44 @@ LED_EFFECTS: Final[dict[str, str]] = {
     "12": "Follow Rainbow",
     "13": "Chasing Comet",
     "14": "Gradient Follow",
+    "15": "Cumulative Fill",
+    "16": "Multi Comets A",
+    "17": "Rainbow Chaser",
+    "18": "Twinkle Lights",
+    "19": "Tennis Game",
+    "20": "Breathing Exercise 4-7-8",
+    "21": "Cylon Scanner",
+    "22": "Palette Mode",
+    "23": "Aurora Flow",
+    "24": "Colorful Drops",
+    "25": "Color Snake",
+    "26": "Flickering Candles",
+    "27": "Digital Rain",
+    "28": "Center Explosion",
+    "29": "Rainbow Plasma",
+    "30": "Comet Race",
+    "31": "Color Waves",
+    "32": "Meteor Storm",
+    "33": "Firefly Flicker",
+    "34": "Ripple",
+    "35": "Jelly Bean",
+    "36": "Forest Rain",
+    "37": "Multi Comets",
+    "38": "Multi Comets with Background",
+    "39": "Rainbow Fill",
+    "40": "White Red Comet",
+    "41": "Color Comets",
 }
 
 CLOUD_BASE_URL = "https://app.grounded.so"
 
-BALL_SPEED_MAX: Final = 1000
-BALL_SPEED_MIN: Final = 200
+BALL_SPEED_MAX: Final = 400
+BALL_SPEED_MIN: Final = 100
 LED_SPEED_MAX: Final = 90
 LED_SPEED_MIN: Final = -90
 
+PLAYLISTS_REFRESH_LIMITER = timedelta(minutes=5)
+
 
 class OasisMini:
     """Oasis Mini API client class."""
@@ -86,6 +141,9 @@ class OasisMini:
     repeat_playlist: bool
     status_code: int
 
+    playlists: list[dict[str, Any]] = []
+    _playlists_next_refresh: datetime = now()
+
     def __init__(
         self,
         host: str,
@@ -112,11 +170,19 @@ 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))
+        total = self.track.get("reduced_svg_content_new", 0) or len(paths)
         percent = (100 * self.progress) / total
         return percent
 
+    @property
+    def error_message(self) -> str | None:
+        """Return the error message, if any."""
+        if self.status_code == 9:
+            return ERROR_CODE_MAP.get(self.error, f"Unknown ({self.error})")
+        return None
+
     @property
     def serial_number(self) -> str | None:
         """Return the serial number."""
@@ -157,17 +223,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."""
@@ -208,25 +274,29 @@ class OasisMini:
         raw_status = await self._async_get(params={"GETSTATUS": ""})
         _LOGGER.debug("Status: %s", raw_status)
         values = raw_status.split(";")
-        playlist = [int(track) for track in values[3].split(",") if track]
+        playlist = [_parse_int(track) for track in values[3].split(",") if track]
+        shift = len(values) - 18 if len(values) > 17 else 0
         status = {
-            "status_code": int(values[0]),  # see status code map
-            "error": int(values[1]),  # noqa: E501; error, 0 = none, and 10 = ?, 18 = can't download?
-            "ball_speed": int(values[2]),  # 200 - 1000
+            "status_code": _parse_int(values[0]),  # see status code map
+            "error": _parse_int(values[1]),
+            "ball_speed": _parse_int(values[2]),  # 200 - 1000
             "playlist": playlist,
-            "playlist_index": min(int(values[4]), len(playlist)),  # index of above
-            "progress": int(values[5]),  # 0 - max svg path
+            "playlist_index": min(_parse_int(values[4]), len(playlist)),  # noqa: E501; index of above
+            "progress": _parse_int(values[5]),  # 0 - max svg path
             "led_effect": values[6],  # led effect (code lookup)
             "led_color_id": values[7],  # led color id?
-            "led_speed": int(values[8]),  # -90 - 90
-            "brightness": int(values[9]) if values[10] else 0,  # noqa: E501; 0 - 200 in app, but seems to be 0 (off) to 304 (max), then repeats
-            "color": values[10] or None,  # hex color code
-            "busy": _bit_to_bool(values[11]),  # noqa: E501; device is busy (downloading track, centering, software update)?
-            "download_progress": int(values[12]),
-            "max_brightness": int(values[13]),
-            "wifi_connected": _bit_to_bool(values[14]),
-            "repeat_playlist": _bit_to_bool(values[15]),
-            "autoplay": AUTOPLAY_MAP.get(values[16]),
+            "led_speed": _parse_int(values[8]),  # -90 - 90
+            "brightness": _parse_int(values[9]),  # noqa: E501; 0 - 200 in app, but seems to be 0 (off) to 304 (max), then repeats
+            "color": values[10] if "#" in values[10] else None,  # hex color code
+            "busy": _bit_to_bool(values[11 + shift]),  # noqa: E501; device is busy (downloading track, centering, software update)?
+            "download_progress": _parse_int(values[12 + shift]),
+            "max_brightness": _parse_int(values[13 + shift]),
+            "wifi_connected": _bit_to_bool(values[14 + shift]),
+            "repeat_playlist": _bit_to_bool(values[15 + shift]),
+            "autoplay": AUTOPLAY_MAP.get(value := values[16 + shift], value),
+            "autoclean": _bit_to_bool(values[17 + shift])
+            if len(values) > 17
+            else False,
         }
         for key, value in status.items():
             if (old_value := getattr(self, key, None)) != value:
@@ -310,8 +380,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))})
@@ -323,6 +395,10 @@ class OasisMini:
         """Set repeat playlist."""
         await self._async_command(params={"WRIREPEATJOB": 1 if repeat else 0})
 
+    async def async_sleep(self) -> None:
+        """Send sleep command."""
+        await self._async_command(params={"CMDSLEEP": ""})
+
     async def async_stop(self) -> None:
         """Send stop command."""
         await self._async_command(params={"CMDSTOP": ""})
@@ -344,6 +420,18 @@ class OasisMini:
         """Login via the cloud."""
         await self._async_cloud_request("GET", "api/auth/logout")
 
+    async def async_cloud_get_playlists(
+        self, personal_only: bool = False
+    ) -> list[dict[str, Any]]:
+        """Get playlists from the cloud."""
+        if self._playlists_next_refresh <= now():
+            if playlists := await self._async_cloud_request(
+                "GET", "api/playlist", params={"my_playlists": str(personal_only)}
+            ):
+                self.playlists = playlists
+            self._playlists_next_refresh = now() + PLAYLISTS_REFRESH_LIMITER
+        return self.playlists
+
     async def async_cloud_get_track_info(self, track_id: int) -> dict[str, Any] | None:
         """Get cloud track info."""
         try:
@@ -363,7 +451,7 @@ class OasisMini:
             "GET", "api/track", params={"ids[]": tracks or []}
         )
         if not response:
-            return None
+            return []
         track_details = response.get("data", [])
         while next_page_url := response.get("next_page_url"):
             response = await self._async_cloud_request("GET", next_page_url)

custom_components/oasis_mini/pyoasismini/utils.py

@@ -1,11 +1,18 @@
 """Oasis Mini utils."""
 
+from __future__ import annotations
+
+import base64
+from datetime import UTC, datetime
 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")
@@ -20,13 +27,22 @@ def _bit_to_bool(val: str) -> bool:
     return val == "1"
 
 
+def _parse_int(val: str) -> int:
+    """Convert an int string to int."""
+    try:
+        return int(val)
+    except Exception:
+        return 0
+
+
 def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
     """Draw SVG."""
     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))
+                total = track.get("reduced_svg_content_new", 0) or len(paths)
                 percent = min((100 * progress) / total, 100)
                 progress = math.floor((percent / 100) * (len(paths) - 1))
 
@@ -137,3 +153,32 @@ 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
+
+
+def now() -> datetime:
+    return datetime.now(UTC)

custom_components/oasis_mini/select.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections import defaultdict
 from dataclasses import dataclass
 from typing import Any, Awaitable, Callable
 
@@ -63,12 +64,33 @@ class OasisMiniSelectEntity(OasisMiniEntity, SelectEntity):
             return super()._handle_coordinator_update()
 
 
-def playlist_update_handler(entity: OasisMiniSelectEntity) -> None:
-    """Handle playlist updates."""
+def playlists_update_handler(entity: OasisMiniSelectEntity) -> None:
+    """Handle playlists updates."""
     # pylint: disable=protected-access
     device = entity.device
-    options = [
-        device._playlist.get(track, {}).get(
+    counts = defaultdict(int)
+    options = []
+    current_option: str | None = None
+    for playlist in device.playlists:
+        name = playlist["name"]
+        counts[name] += 1
+        if counts[name] > 1:
+            name = f"{name} ({counts[name]})"
+        options.append(name)
+        if device.playlist == [pattern["id"] for pattern in playlist["patterns"]]:
+            current_option = name
+    entity._attr_options = options
+    entity._attr_current_option = current_option
+
+
+def queue_update_handler(entity: OasisMiniSelectEntity) -> None:
+    """Handle queue updates."""
+    # pylint: disable=protected-access
+    device = entity.device
+    counts = defaultdict(int)
+    options = []
+    for track in device.playlist:
+        name = device._playlist.get(track, {}).get(
             "name",
             TRACKS.get(track, {"id": track, "name": f"Unknown Title (#{track})"}).get(
                 "name",
@@ -77,28 +99,41 @@ def playlist_update_handler(entity: OasisMiniSelectEntity) -> None:
                 else str(track),
             ),
         )
-        for track in device.playlist
-    ]
+        counts[name] += 1
+        if counts[name] > 1:
+            name = f"{name} ({counts[name]})"
+        options.append(name)
     entity._attr_options = options
     index = min(device.playlist_index, len(options) - 1)
     entity._attr_current_option = options[index] if options else 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="queue",
+        translation_key="queue",
+        current_value=lambda device: (device.playlist.copy(), device.playlist_index),
+        select_fn=lambda device, option: device.async_change_track(option),
+        update_handler=queue_update_handler,
+    ),
+)
+CLOUD_DESCRIPTORS = (
+    OasisMiniSelectEntityDescription(
+        key="playlists",
+        translation_key="playlist",
+        current_value=lambda device: (device.playlists, device.playlist.copy()),
+        select_fn=lambda device, option: device.async_set_playlist(
+            [pattern["id"] for pattern in device.playlists[option]["patterns"]]
+        ),
+        update_handler=playlists_update_handler,
+    ),
 )
 
 
@@ -108,9 +143,13 @@ async def async_setup_entry(
     async_add_entities: AddEntitiesCallback,
 ) -> None:
     """Set up Oasis Mini select using config entry."""
-    async_add_entities(
-        [
-            OasisMiniSelectEntity(entry.runtime_data, descriptor)
-            for descriptor in DESCRIPTORS
-        ]
-    )
+    coordinator: OasisMiniCoordinator = entry.runtime_data
+    entities = [
+        OasisMiniSelectEntity(coordinator, descriptor) for descriptor in DESCRIPTORS
+    ]
+    if coordinator.device.access_token:
+        entities.extend(
+            OasisMiniSelectEntity(coordinator, descriptor)
+            for descriptor in CLOUD_DESCRIPTORS
+        )
+    async_add_entities(entities)

custom_components/oasis_mini/sensor.py

@@ -28,10 +28,8 @@ async def async_setup_entry(
     ]
     if coordinator.device.access_token:
         entities.extend(
-            [
-                OasisMiniSensorEntity(coordinator, descriptor)
-                for descriptor in CLOUD_DESCRIPTORS
-            ]
+            OasisMiniSensorEntity(coordinator, descriptor)
+            for descriptor in CLOUD_DESCRIPTORS
         )
     async_add_entities(entities)
 
@@ -39,34 +37,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 (
-        "busy",
-        "error",
-        "led_color_id",
-        "status",
-        "wifi_connected",
-    )
+    for key in ("error", "led_color_id", "status")
 }
 
 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,80 @@
     }
   },
   "entity": {
+    "button": {
+      "random_track": {
+        "name": "Play random track"
+      },
+      "sleep": {
+        "name": "Sleep"
+      }
+    },
+    "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"
+      },
+      "queue": {
+        "name": "Queue"
+      }
+    },
     "sensor": {
+      "download_progress": {
+        "name": "Download progress"
+      },
+      "drawing_progress": {
+        "name": "Drawing progress"
+      },
+      "error": {
+        "name": "Error",
+        "state": {
+          "0": "None",
+          "1": "Error has occurred while reading the flash memory",
+          "2": "Error while starting the Wifi",
+          "3": "Error when starting DNS settings for your machine",
+          "4": "Failed to open the file to write",
+          "5": "Not enough memory to perform the upgrade",
+          "6": "Error while trying to upgrade your system",
+          "7": "Error while trying to download the new version of the software",
+          "8": "Error while reading the upgrading file",
+          "9": "Failed to start downloading the upgrade file",
+          "10": "Error while starting downloading the job file",
+          "11": "Error while opening the file folder",
+          "12": "Failed to delete a file",
+          "13": "Error while opening the job file",
+          "14": "You have wrong power adapter",
+          "15": "Failed to update the device IP on Oasis Server",
+          "16": "Your device failed centering itself",
+          "17": "There appears to be an issue with your Oasis Device",
+          "18": "Error while downloading the job file"
+        }
+      },
+      "led_color_id": {
+        "name": "LED color ID"
+      },
       "status": {
         "name": "Status",
         "state": {
@@ -47,12 +120,25 @@
           "centering": "Centering",
           "playing": "Playing",
           "paused": "Paused",
+          "sleeping": "Sleeping",
           "error": "Error",
           "updating": "Updating",
           "downloading": "Downloading",
+          "busy": "Busy",
           "live": "Live drawing"
         }
       }
     }
+  },
+  "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,80 @@
     }
   },
   "entity": {
+    "button": {
+      "random_track": {
+        "name": "Play random track"
+      },
+      "sleep": {
+        "name": "Sleep"
+      }
+    },
+    "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"
+      },
+      "queue": {
+        "name": "Queue"
+      }
+    },
     "sensor": {
+      "download_progress": {
+        "name": "Download progress"
+      },
+      "drawing_progress": {
+        "name": "Drawing progress"
+      },
+      "error": {
+        "name": "Error",
+        "state": {
+          "0": "None",
+          "1": "Error has occurred while reading the flash memory",
+          "2": "Error while starting the Wifi",
+          "3": "Error when starting DNS settings for your machine",
+          "4": "Failed to open the file to write",
+          "5": "Not enough memory to perform the upgrade",
+          "6": "Error while trying to upgrade your system",
+          "7": "Error while trying to download the new version of the software",
+          "8": "Error while reading the upgrading file",
+          "9": "Failed to start downloading the upgrade file",
+          "10": "Error while starting downloading the job file",
+          "11": "Error while opening the file folder",
+          "12": "Failed to delete a file",
+          "13": "Error while opening the job file",
+          "14": "You have wrong power adapter",
+          "15": "Failed to update the device IP on Oasis Server",
+          "16": "Your device failed centering itself",
+          "17": "There appears to be an issue with your Oasis Device",
+          "18": "Error while downloading the job file"
+        }
+      },
+      "led_color_id": {
+        "name": "LED color ID"
+      },
       "status": {
         "name": "Status",
         "state": {
@@ -47,12 +120,25 @@
           "centering": "Centering",
           "playing": "Playing",
           "paused": "Paused",
+          "sleeping": "Sleeping",
           "error": "Error",
           "updating": "Updating",
           "downloading": "Downloading",
+          "busy": "Busy",
           "live": "Live drawing"
         }
       }
     }
+  },
+  "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,12 +1,14 @@
 # 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
 pip>=21.0
+pre-commit
 ruff

scripts/setup

@@ -1,9 +1,13 @@
 #!/usr/bin/env bash
 
+sudo apt-get update && sudo apt-get install libturbojpeg0 libpcap0.8 -y
+
 set -e
 
 cd "$(dirname "$0")/.."
 
 python3 -m pip install --requirement requirements.txt --upgrade
 
+pre-commit install
+
 mkdir -p config

update_tracks.py

@@ -13,6 +13,12 @@ from custom_components.oasis_mini.pyoasismini.const import TRACKS
 ACCESS_TOKEN = os.getenv("GROUNDED_TOKEN")
 
 
+def get_author_name(data: dict) -> str:
+    """Get author name from a dict."""
+    author = (data.get("author") or {}).get("user") or {}
+    return author.get("name") or author.get("nickname") or "Oasis Mini"
+
+
 async def update_tracks() -> None:
     """Update tracks."""
     client = OasisMini("", ACCESS_TOKEN)
@@ -32,23 +38,22 @@ async def update_tracks() -> None:
     for result in filter(lambda d: d["public"], data):
         if (
             (track_id := result["id"]) not in TRACKS
-            or result["name"] != TRACKS[track_id].get("name")
-            or result["image"] != TRACKS[track_id].get("image")
+            or any(
+                result[field] != TRACKS[track_id].get(field)
+                for field in ("name", "image", "png_image")
+            )
+            or TRACKS[track_id].get("author") != get_author_name(result)
         ):
-            print(f"Updating track {track_id}: {result["name"]}")
+            print(f"Updating track {track_id}: {result['name']}")
             track_info = await client.async_cloud_get_track_info(int(track_id))
             if not track_info:
                 print("No track info")
                 break
-            author = (result.get("author") or {}).get("user") or {}
-            updated_tracks[track_id] = {
-                "id": track_id,
-                "name": result["name"],
-                "author": author.get("name") or author.get("nickname") or "Oasis Mini",
-                "image": result["image"],
-                "clean_pattern": track_info.get("cleanPattern", {}).get("id"),
-                "reduced_svg_content": track_info.get("reduced_svg_content"),
-            }
+            result["author"] = get_author_name(result)
+            result["reduced_svg_content_new"] = track_info.get(
+                "reduced_svg_content_new"
+            )
+            updated_tracks[track_id] = result
     await client.session.close()
 
     if not updated_tracks: