Better mqtt handling when connection is interrupted

Update tracks

.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/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/update-tracks.yml

@@ -0,0 +1,41 @@
+name: Update tracks
+
+on:
+  schedule:
+    - cron: "0 19 * * 1"
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  tracks:
+    name: Search and update new tracks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install homeassistant
+
+      - name: Update tracks
+        env:
+          GROUNDED_TOKEN: ${{ secrets.GROUNDED_TOKEN }}
+        run: python update_tracks.py
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: Update tracks
+          title: Update tracks
+          body: Update tracks
+          base: main
+          labels: automated-pr, tracks
+          branch: 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

@@ -1,6 +1,9 @@
-![Release](https://img.shields.io/github/v/release/natekspencer/hacs-oasis_mini?style=for-the-badge)
+[![Release](https://img.shields.io/github/v/release/natekspencer/hacs-oasis_mini?style=for-the-badge)](https://github.com/natekspencer/hacs-oasis_mini/releases)
 [![Buy Me A Coffee/Beer](https://img.shields.io/badge/Buy_Me_A_☕/🍺-F16061?style=for-the-badge&logo=ko-fi&logoColor=white&labelColor=grey)](https://ko-fi.com/natekspencer)
-[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=for-the-badge)](https://github.com/hacs/integration)
+[![HACS Custom](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=for-the-badge)](https://github.com/hacs/integration)
+
+![Downloads](https://img.shields.io/github/downloads/natekspencer/hacs-oasis_mini/total?style=flat-square)
+![Latest Downloads](https://img.shields.io/github/downloads/natekspencer/hacs-oasis_mini/latest/total?style=flat-square)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://brands.home-assistant.io/oasis_mini/dark_logo.png">
@@ -53,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

@@ -1,21 +1,26 @@
-"""Support for Oasis Mini."""
+"""Support for Oasis devices."""
 
 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.exceptions import ConfigEntryNotReady
+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
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
+from .coordinator import OasisDeviceCoordinator
 from .helpers import create_client
+from .pyoasiscontrol import OasisMqttClient, UnauthenticatedError
+
+type OasisDeviceConfigEntry = ConfigEntry[OasisDeviceCoordinator]
 
 _LOGGER = logging.getLogger(__name__)
 
 PLATFORMS = [
+    Platform.BINARY_SENSOR,
     Platform.BUTTON,
     Platform.IMAGE,
     Platform.LIGHT,
@@ -23,49 +28,121 @@ PLATFORMS = [
     Platform.NUMBER,
     Platform.SELECT,
     Platform.SENSOR,
-    Platform.SWITCH,
+    Platform.UPDATE,
 ]
 
 
-async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
-    """Set up Oasis Mini from a config entry."""
-    hass.data.setdefault(DOMAIN, {})
-    client = create_client(entry.data | entry.options)
-    coordinator = OasisMiniCoordinator(hass, client)
+async def async_setup_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry) -> bool:
+    """Set up Oasis devices from a config entry."""
+    cloud_client = create_client(hass, entry.data)
+    try:
+        user = await cloud_client.async_get_user()
+    except UnauthenticatedError as err:
+        raise ConfigEntryAuthFailed(err) from err
+
+    mqtt_client = OasisMqttClient()
+    mqtt_client.start()
+
+    coordinator = OasisDeviceCoordinator(hass, cloud_client, mqtt_client)
 
     try:
         await coordinator.async_config_entry_first_refresh()
     except Exception as ex:
         _LOGGER.exception(ex)
 
-    if not coordinator.data:
-        await client.session.close()
-        raise ConfigEntryNotReady
+    if entry.unique_id != (user_id := str(user["id"])):
+        hass.config_entries.async_update_entry(entry, unique_id=user_id)
 
-    hass.data[DOMAIN][entry.entry_id] = coordinator
+    if not coordinator.data:
+        _LOGGER.warning("No devices associated with account")
+
+    entry.runtime_data = coordinator
+
+    def _on_oasis_update() -> None:
+        coordinator.async_update_listeners()
+
+    for device in coordinator.data:
+        device.add_update_listener(_on_oasis_update)
 
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
 
-    entry.async_on_unload(entry.add_update_listener(update_listener))
     return True
 
 
-async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+async def async_unload_entry(
+    hass: HomeAssistant, entry: OasisDeviceConfigEntry
+) -> bool:
     """Unload a config entry."""
-    if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
-        await hass.data[DOMAIN][entry.entry_id].device.session.close()
-        del hass.data[DOMAIN][entry.entry_id]
-    return unload_ok
+    mqtt_client = entry.runtime_data.mqtt_client
+    await mqtt_client.async_close()
+
+    cloud_client = entry.runtime_data.cloud_client
+    await cloud_client.async_close()
+
+    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
 
 
-async def async_remove_entry(hass: HomeAssistant, entry: ConfigEntry) -> None:
+async def async_remove_entry(
+    hass: HomeAssistant, entry: OasisDeviceConfigEntry
+) -> None:
     """Handle removal of an entry."""
-    if entry.options:
-        client = create_client(entry.data | entry.options)
-        await client.async_cloud_logout()
-        await client.session.close()
+    cloud_client = create_client(hass, entry.data)
+    try:
+        await cloud_client.async_logout()
+    except Exception as ex:
+        _LOGGER.exception(ex)
+    await cloud_client.async_close()
 
 
-async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
-    """Handle options update."""
-    await hass.config_entries.async_reload(entry.entry_id)
+async def async_migrate_entry(hass: HomeAssistant, entry: OasisDeviceConfigEntry):
+    """Migrate old entry."""
+    _LOGGER.debug(
+        "Migrating configuration from version %s.%s", entry.version, entry.minor_version
+    )
+
+    if entry.version > 1:
+        # This means the user has downgraded from a future version
+        return False
+
+    if entry.version == 1:
+        new_data = {**entry.data}
+        new_options = {**entry.options}
+
+        if entry.minor_version < 2:
+            # 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)
+
+        if entry.minor_version < 3:
+            # Auth is now required, host is dropped
+            new_data = {**entry.options}
+            new_options = {}
+
+        hass.config_entries.async_update_entry(
+            entry,
+            data=new_data,
+            options=new_options,
+            minor_version=3,
+            title=new_data.get(CONF_EMAIL, "Oasis Control"),
+            unique_id=None,
+            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,56 @@
+"""Oasis device 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 OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis device sensors using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    async_add_entities(
+        OasisDeviceBinarySensorEntity(coordinator, device, descriptor)
+        for device in coordinator.data
+        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 OasisDeviceBinarySensorEntity(OasisDeviceEntity, BinarySensorEntity):
+    """Oasis device 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

@@ -1,4 +1,4 @@
-"""Oasis Mini button entity."""
+"""Oasis device button entity."""
 
 from __future__ import annotations
 
@@ -11,70 +11,70 @@ from homeassistant.components.button import (
     ButtonEntity,
     ButtonEntityDescription,
 )
-from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import EntityCategory
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini import OasisMini
-from .pyoasismini.const import TRACKS
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+from .helpers import add_and_play_track
+from .pyoasiscontrol import OasisDevice
+from .pyoasiscontrol.const import TRACKS
 
 
 async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis Mini button using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
+    """Set up Oasis device button using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
     async_add_entities(
-        [
-            OasisMiniButtonEntity(coordinator, entry, descriptor)
+        OasisDeviceButtonEntity(coordinator, device, descriptor)
+        for device in coordinator.data
         for descriptor in DESCRIPTORS
-        ]
     )
 
 
-async def play_random_track(device: OasisMini) -> None:
+async def play_random_track(device: OasisDevice) -> None:
     """Play random track."""
-    track = int(random.choice(list(TRACKS)))
-    if track not in device.playlist:
-        await device.async_add_track_to_playlist(track)
-
-    # Move track to next item in the playlist and then select it
-    if (idx := device.playlist.index(track)) != (next_idx := device.playlist_index + 1):
-        await device.async_move_track(idx, next_idx)
-    await device.async_change_track(next_idx)
-    await device.async_play()
+    track = random.choice(list(TRACKS))
+    await add_and_play_track(device, track)
 
 
 @dataclass(frozen=True, kw_only=True)
-class OasisMiniButtonEntityDescription(ButtonEntityDescription):
-    """Oasis Mini button entity description."""
+class OasisDeviceButtonEntityDescription(ButtonEntityDescription):
+    """Oasis device button entity description."""
 
-    press_fn: Callable[[OasisMini], Awaitable[None]]
+    press_fn: Callable[[OasisDevice], Awaitable[None]]
 
 
 DESCRIPTORS = (
-    OasisMiniButtonEntityDescription(
+    OasisDeviceButtonEntityDescription(
         key="reboot",
         device_class=ButtonDeviceClass.RESTART,
+        entity_category=EntityCategory.CONFIG,
         press_fn=lambda device: device.async_reboot(),
     ),
-    OasisMiniButtonEntityDescription(
+    OasisDeviceButtonEntityDescription(
         key="random_track",
-        name="Play random track",
+        translation_key="random_track",
         press_fn=play_random_track,
     ),
+    OasisDeviceButtonEntityDescription(
+        key="sleep",
+        translation_key="sleep",
+        press_fn=lambda device: device.async_sleep(),
+    ),
 )
 
 
-class OasisMiniButtonEntity(OasisMiniEntity, ButtonEntity):
-    """Oasis Mini button entity."""
+class OasisDeviceButtonEntity(OasisDeviceEntity, ButtonEntity):
+    """Oasis device button entity."""
 
-    entity_description: OasisMiniButtonEntityDescription
+    entity_description: OasisDeviceButtonEntityDescription
 
     async def async_press(self) -> None:
         """Press the button."""
         await self.entity_description.press_fn(self.device)
-        await self.coordinator.async_request_refresh()

custom_components/oasis_mini/config_flow.py

@@ -1,90 +1,60 @@
-"""Config flow for Oasis Mini integration."""
+"""Config flow for Oasis device integration."""
 
 from __future__ import annotations
 
 import asyncio
 import logging
-from typing import Any
+from typing import Any, Mapping
 
 from aiohttp import ClientConnectorError
 from httpx import ConnectError, HTTPStatusError
 import voluptuous as vol
 
-from homeassistant.config_entries import ConfigEntry, ConfigFlow, ConfigFlowResult
-from homeassistant.const import CONF_ACCESS_TOKEN, CONF_EMAIL, CONF_HOST, CONF_PASSWORD
-from homeassistant.core import callback
-from homeassistant.helpers.schema_config_entry_flow import (
-    SchemaCommonFlowHandler,
-    SchemaFlowError,
-    SchemaFlowFormStep,
-    SchemaOptionsFlowHandler,
-)
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.const import CONF_ACCESS_TOKEN, CONF_EMAIL, CONF_PASSWORD
 
 from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
 from .helpers import create_client
+from .pyoasiscontrol import UnauthenticatedError
 
 _LOGGER = logging.getLogger(__name__)
 
-
-STEP_USER_DATA_SCHEMA = vol.Schema({vol.Required(CONF_HOST): str})
-OPTIONS_SCHEMA = vol.Schema(
+STEP_USER_DATA_SCHEMA = vol.Schema(
     {vol.Required(CONF_EMAIL): str, vol.Required(CONF_PASSWORD): str}
 )
 
 
-async def cloud_login(
-    handler: SchemaCommonFlowHandler, user_input: dict[str, Any]
-) -> dict[str, Any]:
-    """Cloud login."""
-    coordinator: OasisMiniCoordinator = handler.parent_handler.hass.data[DOMAIN][
-        handler.parent_handler.config_entry.entry_id
-    ]
-
-    try:
-        await coordinator.device.async_cloud_login(
-            email=user_input[CONF_EMAIL], password=user_input[CONF_PASSWORD]
-        )
-        user_input[CONF_ACCESS_TOKEN] = coordinator.device.access_token
-    except Exception as ex:
-        raise SchemaFlowError("invalid_auth") from ex
-
-    del user_input[CONF_PASSWORD]
-    return user_input
-
-
-OPTIONS_FLOW = {
-    "init": SchemaFlowFormStep(OPTIONS_SCHEMA, validate_user_input=cloud_login)
-}
-
-
-class OasisMiniConfigFlow(ConfigFlow, domain=DOMAIN):
-    """Handle a config flow for Oasis Mini."""
+class OasisDeviceConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for Oasis devices."""
 
     VERSION = 1
+    MINOR_VERSION = 3
 
-    host: str | None = None
-    serial_number: str | None = None
+    async def async_step_reauth(
+        self, entry_data: Mapping[str, Any]
+    ) -> ConfigFlowResult:
+        """Perform reauth upon an API authentication error."""
+        return await self.async_step_reauth_confirm()
 
-    @staticmethod
-    @callback
-    def async_get_options_flow(config_entry: ConfigEntry) -> SchemaOptionsFlowHandler:
-        """Get the options flow for this handler."""
-        return SchemaOptionsFlowHandler(config_entry, OPTIONS_FLOW)
+    async def async_step_reauth_confirm(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Dialog that informs the user that reauth is required."""
+        entry = self.hass.config_entries.async_get_entry(self.context["entry_id"])
+        assert entry
 
-    # async def async_step_dhcp(self, discovery_info: dhcp.DhcpServiceInfo) -> ConfigFlowResult:
-    #     """Handle dhcp discovery."""
-    #     self.host = discovery_info.ip
-    #     self.name = discovery_info.hostname
-    #     await self.async_set_unique_id(discovery_info.macaddress)
-    #     self._abort_if_unique_id_configured(updates={CONF_HOST: self.host})
-    #     return await self.async_step_api_key()
+        suggested_values = user_input or entry.data
+        return await self._async_step(
+            "reauth_confirm", STEP_USER_DATA_SCHEMA, user_input, suggested_values
+        )
 
     async def async_step_user(
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
         """Handle the initial step."""
-        return await self._async_step("user", STEP_USER_DATA_SCHEMA, user_input)
+        return await self._async_step(
+            "user", STEP_USER_DATA_SCHEMA, user_input, user_input
+        )
 
     async def async_step_reconfigure(
         self, user_input: dict[str, Any] | None = None
@@ -106,26 +76,26 @@ class OasisMiniConfigFlow(ConfigFlow, domain=DOMAIN):
         suggested_values: dict[str, Any] | None = None,
     ) -> ConfigFlowResult:
         """Handle step setup."""
-        if abort := self._abort_if_configured(user_input):
-            return abort
-
         errors = {}
 
         if user_input is not None:
             if not (errors := await self.validate_client(user_input)):
-                data = {CONF_HOST: user_input.get(CONF_HOST, self.host)}
-                if existing_entry := self.hass.config_entries.async_get_entry(
-                    self.context.get("entry_id")
-                ):
-                    self.hass.config_entries.async_update_entry(
-                        existing_entry, data=data
+                entry_id = self.context.get("entry_id")
+                existing_entry = self.hass.config_entries.async_get_entry(entry_id)
+                if existing_entry and existing_entry.unique_id:
+                    self._abort_if_unique_id_mismatch(reason="wrong_account")
+                if existing_entry:
+                    return self.async_update_reload_and_abort(
+                        existing_entry,
+                        unique_id=self.unique_id,
+                        title=user_input[CONF_EMAIL],
+                        data=user_input,
+                        reload_even_if_entry_is_unchanged=False,
                     )
-                    await self.hass.config_entries.async_reload(existing_entry.entry_id)
-                    return self.async_abort(reason="reconfigure_successful")
 
+                self._abort_if_unique_id_configured(updates=user_input)
                 return self.async_create_entry(
-                    title=f"Oasis Mini {self.serial_number}",
-                    data=data,
+                    title=user_input[CONF_EMAIL], data=user_input
                 )
 
         return self.async_show_form(
@@ -139,33 +109,29 @@ class OasisMiniConfigFlow(ConfigFlow, domain=DOMAIN):
         errors = {}
         try:
             async with asyncio.timeout(10):
-                client = create_client({"host": self.host} | user_input)
-                self.serial_number = await client.async_get_serial_number()
-            if not self.serial_number:
-                errors["base"] = "invalid_host"
+                client = create_client(self.hass, user_input)
+                await client.async_login(
+                    email=user_input[CONF_EMAIL], password=user_input[CONF_PASSWORD]
+                )
+                user_input[CONF_ACCESS_TOKEN] = client.access_token
+                user = await client.async_get_user()
+                await self.async_set_unique_id(str(user["id"]))
+                del user_input[CONF_PASSWORD]
+            if not self.unique_id:
+                errors["base"] = "invalid_auth"
+        except UnauthenticatedError:
+            errors["base"] = "invalid_auth"
         except asyncio.TimeoutError:
             errors["base"] = "timeout_connect"
         except ConnectError:
-            errors["base"] = "invalid_host"
+            errors["base"] = "invalid_auth"
         except ClientConnectorError:
-            errors["base"] = "invalid_host"
+            errors["base"] = "invalid_auth"
         except HTTPStatusError as err:
             errors["base"] = str(err)
         except Exception as ex:  # pylint: disable=broad-except
             _LOGGER.error(ex)
             errors["base"] = "unknown"
         finally:
-            await client.session.close()
+            await client.async_close()
         return errors
-
-    @callback
-    def _abort_if_configured(
-        self, user_input: dict[str, Any] | None
-    ) -> ConfigFlowResult | None:
-        """Abort if configured."""
-        if self.host or user_input:
-            data = {CONF_HOST: self.host, **(user_input or {})}
-            for entry in self._async_current_entries():
-                if entry.data[CONF_HOST] == data[CONF_HOST]:
-                    return self.async_abort(reason="already_configured")
-        return None

custom_components/oasis_mini/const.py

@@ -1,4 +1,4 @@
-"""Constants for the Oasis Mini integration."""
+"""Constants for the Oasis devices integration."""
 
 from typing import Final
 

custom_components/oasis_mini/coordinator.py

@@ -1,4 +1,4 @@
-"""Oasis Mini coordinator."""
+"""Oasis devices coordinator."""
 
 from __future__ import annotations
 
@@ -8,40 +8,74 @@ import logging
 import async_timeout
 
 from homeassistant.core import HomeAssistant
-from homeassistant.exceptions import ConfigEntryAuthFailed
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
 
 from .const import DOMAIN
-from .pyoasismini import OasisMini
+from .pyoasiscontrol import OasisCloudClient, OasisDevice, OasisMqttClient
 
 _LOGGER = logging.getLogger(__name__)
 
 
-class OasisMiniCoordinator(DataUpdateCoordinator[str]):
-    """Oasis Mini data update coordinator."""
+class OasisDeviceCoordinator(DataUpdateCoordinator[list[OasisDevice]]):
+    """Oasis device data update coordinator."""
 
+    attempt: int = 0
     last_updated: datetime | None = None
 
-    def __init__(self, hass: HomeAssistant, device: OasisMini) -> None:
+    def __init__(
+        self,
+        hass: HomeAssistant,
+        cloud_client: OasisCloudClient,
+        mqtt_client: OasisMqttClient,
+    ) -> None:
         """Initialize."""
         super().__init__(
-            hass, _LOGGER, name=DOMAIN, update_interval=timedelta(seconds=10)
+            hass,
+            _LOGGER,
+            name=DOMAIN,
+            update_interval=timedelta(minutes=10),
+            always_update=False,
         )
-        self.device = device
+        self.cloud_client = cloud_client
+        self.mqtt_client = mqtt_client
+
+    async def _async_update_data(self) -> list[OasisDevice]:
+        """Update the data."""
+        devices: list[OasisDevice] = []
+        self.attempt += 1
 
-    async def _async_update_data(self):
         try:
             async with async_timeout.timeout(10):
-                if not self.device.serial_number:
-                    await self.device.async_get_serial_number()
-                if not self.device.software_version:
-                    await self.device.async_get_software_version()
-                data = await self.device.async_get_status()
-                await self.device.async_get_current_track_details()
-        except Exception as ex:
-            raise UpdateFailed("Couldn't read from the Oasis Mini") from ex
-        if data is None:
-            raise ConfigEntryAuthFailed
-        if data != self.data:
+                if not self.data:
+                    raw_devices = await self.cloud_client.async_get_devices()
+                    devices = [
+                        OasisDevice(
+                            model=raw_device.get("model", {}).get("name"),
+                            serial_number=raw_device.get("serial_number"),
+                        )
+                        for raw_device in raw_devices
+                    ]
+                else:
+                    devices = self.data
+                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:
+                        await device.async_get_mac_address()
+                    # if not device.software_version:
+                    #     await device.async_get_software_version()
+                # data = await self.device.async_get_status()
+                # 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(
+                    f"Couldn't read from the Oasis device after {self.attempt} attempts"
+                ) from ex
+
+        if devices != self.data:
             self.last_updated = datetime.now()
-        return data
+        return devices

custom_components/oasis_mini/entity.py

@@ -1,47 +1,41 @@
-"""Oasis Mini entity."""
+"""Oasis device entity."""
 
 from __future__ import annotations
 
-import logging
-
-from homeassistant.config_entries import ConfigEntry
+from homeassistant.helpers.device_registry import CONNECTION_NETWORK_MAC, format_mac
 from homeassistant.helpers.entity import DeviceInfo, EntityDescription
 from homeassistant.helpers.update_coordinator import CoordinatorEntity
 
 from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .pyoasismini import OasisMini
-
-_LOGGER = logging.getLogger(__name__)
+from .coordinator import OasisDeviceCoordinator
+from .pyoasiscontrol import OasisDevice
 
 
-class OasisMiniEntity(CoordinatorEntity[OasisMiniCoordinator]):
-    """Base class for Oasis Mini entities."""
+class OasisDeviceEntity(CoordinatorEntity[OasisDeviceCoordinator]):
+    """Base class for Oasis device entities."""
 
     _attr_has_entity_name = True
 
     def __init__(
         self,
-        coordinator: OasisMiniCoordinator,
-        entry: ConfigEntry,
+        coordinator: OasisDeviceCoordinator,
+        device: OasisDevice,
         description: EntityDescription,
     ) -> None:
-        """Construct an Oasis Mini entity."""
+        """Construct an Oasis device entity."""
         super().__init__(coordinator)
+        self.device = device
         self.entity_description = description
-        serial_number = coordinator.device.serial_number
+
+        serial_number = device.serial_number
         self._attr_unique_id = f"{serial_number}-{description.key}"
 
         self._attr_device_info = DeviceInfo(
+            connections={(CONNECTION_NETWORK_MAC, format_mac(device.mac_address))},
             identifiers={(DOMAIN, serial_number)},
-            name=entry.title,
-            manufacturer="Kinetic Oasis",
-            model="Oasis Mini",
+            name=f"{device.model} {serial_number}",
+            manufacturer=device.manufacturer,
+            model=device.model,
             serial_number=serial_number,
-            sw_version=coordinator.device.software_version,
+            sw_version=device.software_version,
         )
-
-    @property
-    def device(self) -> OasisMini:
-        """Return the device."""
-        return self.coordinator.device

custom_components/oasis_mini/helpers.py

@@ -1,14 +1,54 @@
-"""Helpers for the Oasis Mini integration."""
+"""Helpers for the Oasis devices integration."""
 
 from __future__ import annotations
 
+import logging
 from typing import Any
 
-from homeassistant.const import CONF_ACCESS_TOKEN, CONF_HOST
+from homeassistant.const import CONF_ACCESS_TOKEN
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
 
-from .pyoasismini import OasisMini
+from .pyoasiscontrol import OasisCloudClient, OasisDevice
+from .pyoasiscontrol.const import TRACKS
+
+_LOGGER = logging.getLogger(__name__)
 
 
-def create_client(data: dict[str, Any]) -> OasisMini:
-    """Create a Oasis Mini local client."""
-    return OasisMini(data[CONF_HOST], data.get(CONF_ACCESS_TOKEN))
+def create_client(hass: HomeAssistant, data: dict[str, Any]) -> OasisCloudClient:
+    """Create a Oasis cloud client."""
+    session = async_get_clientsession(hass)
+    return OasisCloudClient(session=session, access_token=data.get(CONF_ACCESS_TOKEN))
+
+
+async def add_and_play_track(device: OasisDevice, track: int) -> None:
+    """Add and play a track."""
+    if track not in device.playlist:
+        await device.async_add_track_to_playlist(track)
+
+    # 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)):
+            await device.async_move_track(index, _next)
+        await device.async_change_track(_next)
+
+    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

@@ -1,55 +1,84 @@
-"""Oasis Mini image entity."""
+"""Oasis device image entity."""
 
 from __future__ import annotations
 
-from datetime import datetime
-
-from homeassistant.components.image import ImageEntity, ImageEntityDescription
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
+from homeassistant.components.image import Image, ImageEntity, ImageEntityDescription
+from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.typing import UNDEFINED
+
+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(
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis device image using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    async_add_entities(
+        OasisDeviceImageEntity(coordinator, device, IMAGE)
+        for device in coordinator.data
+    )
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini.utils import draw_svg
 
 IMAGE = ImageEntityDescription(key="image", name=None)
 
 
-class OasisMiniImageEntity(OasisMiniEntity, ImageEntity):
-    """Oasis Mini image entity."""
+class OasisDeviceImageEntity(OasisDeviceEntity, ImageEntity):
+    """Oasis device image entity."""
 
     _attr_content_type = "image/svg+xml"
+    _track_id: int | None = None
+    _progress: int = 0
 
     def __init__(
         self,
-        coordinator: OasisMiniCoordinator,
-        entry_id: str,
+        coordinator: OasisDeviceCoordinator,
+        device: OasisDevice,
         description: ImageEntityDescription,
     ) -> None:
         """Initialize the entity."""
-        super().__init__(coordinator, entry_id, description)
+        super().__init__(coordinator, device, description)
         ImageEntity.__init__(self, coordinator.hass)
-
-    @property
-    def image_last_updated(self) -> datetime | None:
-        """The time when the image was last updated."""
-        return self.coordinator.last_updated
+        self._handle_coordinator_update()
 
     def image(self) -> bytes | None:
         """Return bytes of image."""
-        return draw_svg(
-            self.device._current_track_details,
-            self.device.progress,
-            "1",
+        if not self._cached_image:
+            self._cached_image = Image(
+                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."""
+        if (
+            self._track_id != self.device.track_id
+            or self._progress != self.device.progress
+        ) 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
+            self._cached_image = None
+            if self.device.track and self.device.track.get("svg_content"):
+                self._attr_image_url = UNDEFINED
+            else:
+                self._attr_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
                 )
 
-
-async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
-) -> None:
-    """Set up Oasis Mini camera using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    if coordinator.device.access_token:
-        async_add_entities([OasisMiniImageEntity(coordinator, entry, IMAGE)])
+        if self.hass:
+            super()._handle_coordinator_update()

custom_components/oasis_mini/light.py

@@ -1,4 +1,4 @@
-"""Oasis Mini light entity."""
+"""Oasis device light entity."""
 
 from __future__ import annotations
 
@@ -14,7 +14,6 @@ from homeassistant.components.light import (
     LightEntityDescription,
     LightEntityFeature,
 )
-from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.util.color import (
@@ -24,21 +23,37 @@ from homeassistant.util.color import (
     value_to_brightness,
 )
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini import LED_EFFECTS
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+from .pyoasiscontrol.const import LED_EFFECTS
 
 
-class OasisMiniLightEntity(OasisMiniEntity, LightEntity):
-    """Oasis Mini light entity."""
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis device lights using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    async_add_entities(
+        OasisDeviceLightEntity(coordinator, device, DESCRIPTOR)
+        for device in coordinator.data
+    )
+
+
+DESCRIPTOR = LightEntityDescription(key="led", translation_key="led")
+
+
+class OasisDeviceLightEntity(OasisDeviceEntity, LightEntity):
+    """Oasis device light entity."""
 
     _attr_supported_features = LightEntityFeature.EFFECT
 
     @property
     def brightness(self) -> int:
         """Return the brightness of this light between 0..255."""
-        scale = (1, self.device.max_brightness)
+        scale = (1, self.device.brightness_max)
         return value_to_brightness(scale, self.device.brightness)
 
     @property
@@ -70,8 +85,10 @@ class OasisMiniLightEntity(OasisMiniEntity, LightEntity):
         return self.device.brightness > 0
 
     @property
-    def rgb_color(self) -> tuple[int, int, int]:
+    def rgb_color(self) -> tuple[int, int, int] | None:
         """Return the rgb color value [int, int, int]."""
+        if not self.device.color:
+            return None
         return rgb_hex_to_rgb_list(self.device.color.replace("#", ""))
 
     @property
@@ -82,15 +99,14 @@ class OasisMiniLightEntity(OasisMiniEntity, LightEntity):
     async def async_turn_off(self, **kwargs: Any) -> None:
         """Turn the entity off."""
         await self.device.async_set_led(brightness=0)
-        await self.coordinator.async_request_refresh()
 
     async def async_turn_on(self, **kwargs: Any) -> None:
         """Turn the entity on."""
         if brightness := kwargs.get(ATTR_BRIGHTNESS):
-            scale = (1, self.device.max_brightness)
+            scale = (1, self.device.brightness_max)
             brightness = math.ceil(brightness_to_value(scale, brightness))
         else:
-            brightness = self.device.brightness or 100
+            brightness = self.device.brightness or self.device.brightness_on
 
         if color := kwargs.get(ATTR_RGB_COLOR):
             color = f"#{color_rgb_to_hex(*color)}"
@@ -103,15 +119,3 @@ class OasisMiniLightEntity(OasisMiniEntity, LightEntity):
         await self.device.async_set_led(
             brightness=brightness, color=color, led_effect=led_effect
         )
-        await self.coordinator.async_request_refresh()
-
-
-DESCRIPTOR = LightEntityDescription(key="led", name="LED")
-
-
-async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
-) -> None:
-    """Set up Oasis Mini lights using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    async_add_entities([OasisMiniLightEntity(coordinator, entry, DESCRIPTOR)])

custom_components/oasis_mini/manifest.json

@@ -1,12 +1,14 @@
 {
   "domain": "oasis_mini",
-  "name": "Oasis Mini",
+  "name": "Oasis Control",
   "codeowners": ["@natekspencer"],
   "config_flow": true,
+  "dhcp": [{ "registered_devices": true }],
   "documentation": "https://github.com/natekspencer/hacs-oasis_mini",
-  "integration_type": "device",
+  "integration_type": "hub",
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/natekspencer/hacs-oasis_mini/issues",
   "loggers": ["custom_components.oasis_mini"],
+  "requirements": ["aiomqtt"],
   "version": "0.0.0"
 }

custom_components/oasis_mini/media_player.py

@@ -1,11 +1,12 @@
-"""Oasis Mini media player entity."""
+"""Oasis device media player entity."""
 
 from __future__ import annotations
 
 from datetime import datetime
-import math
+from typing import Any
 
 from homeassistant.components.media_player import (
+    MediaPlayerEnqueue,
     MediaPlayerEntity,
     MediaPlayerEntityDescription,
     MediaPlayerEntityFeature,
@@ -13,26 +14,47 @@ from homeassistant.components.media_player import (
     MediaType,
     RepeatMode,
 )
-from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
+from . import OasisDeviceConfigEntry
 from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini.const import TRACKS
-
-BRIGHTNESS_SCALE = (1, 200)
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+from .helpers import get_track_id
+from .pyoasiscontrol.const import TRACKS
 
 
-class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
-    """Oasis Mini media player entity."""
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis device media_players using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    async_add_entities(
+        OasisDeviceMediaPlayerEntity(coordinator, device, DESCRIPTOR)
+        for device in coordinator.data
+    )
+
+
+DESCRIPTOR = MediaPlayerEntityDescription(key="oasis_mini", name=None)
+
+
+class OasisDeviceMediaPlayerEntity(OasisDeviceEntity, MediaPlayerEntity):
+    """Oasis device media player entity."""
 
     _attr_media_image_remotely_accessible = True
     _attr_supported_features = (
-        MediaPlayerEntityFeature.NEXT_TRACK
-        | MediaPlayerEntityFeature.PAUSE
+        MediaPlayerEntityFeature.PAUSE
         | MediaPlayerEntityFeature.PLAY
+        | MediaPlayerEntityFeature.STOP
+        | MediaPlayerEntityFeature.PREVIOUS_TRACK
+        | MediaPlayerEntityFeature.NEXT_TRACK
+        | MediaPlayerEntityFeature.PLAY_MEDIA
+        | MediaPlayerEntityFeature.MEDIA_ENQUEUE
+        | MediaPlayerEntityFeature.CLEAR_PLAYLIST
         | MediaPlayerEntityFeature.REPEAT_SET
     )
 
@@ -42,19 +64,17 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
         return MediaType.IMAGE
 
     @property
-    def media_duration(self) -> int:
+    def media_duration(self) -> int | None:
         """Duration of current playing media in seconds."""
-        if (
-            track := self.device._current_track_details
-        ) and "reduced_svg_content" in track:
-            return track["reduced_svg_content"].get("1")
-        return math.ceil(self.media_position / 0.99)
+        if (track := self.device.track) and "reduced_svg_content_new" in track:
+            return track["reduced_svg_content_new"]
+        return None
 
     @property
     def media_image_url(self) -> str | None:
         """Image url of current playing media."""
-        if not (track := self.device._current_track_details):
-            track = TRACKS.get(str(self.device.current_track_id))
+        if not (track := self.device.track):
+            track = TRACKS.get(self.device.track_id)
         if track and "image" in track:
             return f"https://app.grounded.so/uploads/{track['image']}"
         return None
@@ -70,40 +90,60 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
         return self.coordinator.last_updated
 
     @property
-    def media_title(self) -> str:
+    def media_title(self) -> str | None:
         """Title of current playing media."""
-        if not (track := self.device._current_track_details):
-            track = TRACKS.get(str(self.device.current_track_id), {})
-        return track.get("name", f"Unknown Title (#{self.device.current_track_id})")
+        if not self.device.track_id:
+            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:
         """Return current repeat mode."""
-        if self.device.repeat_playlist:
-            return RepeatMode.ALL
-        return RepeatMode.OFF
+        return RepeatMode.ALL if self.device.repeat_playlist else RepeatMode.OFF
 
     @property
     def state(self) -> MediaPlayerState:
         """State of the player."""
         status_code = self.device.status_code
+        if self.device.error or status_code in (9, 11):
+            return MediaPlayerState.OFF
+        if status_code == 2:
+            return MediaPlayerState.IDLE
         if status_code in (3, 13):
             return MediaPlayerState.BUFFERING
-        if status_code in (2, 5):
-            return MediaPlayerState.PAUSED
         if status_code == 4:
             return MediaPlayerState.PLAYING
-        return MediaPlayerState.STANDBY
+        if status_code == 5:
+            return MediaPlayerState.PAUSED
+        if status_code == 15:
+            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()
 
     async def async_set_repeat(self, repeat: RepeatMode) -> None:
         """Set repeat mode."""
@@ -111,22 +151,70 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
             repeat != RepeatMode.OFF
             and not (repeat == RepeatMode.ONE and self.repeat == RepeatMode.ALL)
         )
-        await self.coordinator.async_request_refresh()
+
+    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)
 
     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)
-        await self.coordinator.async_request_refresh()
 
-
-DESCRIPTOR = MediaPlayerEntityDescription(key="oasis_mini", name=None)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
+    async def async_play_media(
+        self,
+        media_type: MediaType | str,
+        media_id: str,
+        enqueue: MediaPlayerEnqueue | None = None,
+        **kwargs: Any,
     ) -> None:
-    """Set up Oasis Mini media_players using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    async_add_entities([OasisMiniMediaPlayerEntity(coordinator, entry, DESCRIPTOR)])
+        """Play a piece of media."""
+        self.abort_if_busy()
+        if media_type == MediaType.PLAYLIST:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN, translation_key="playlists_unsupported"
+            )
+        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)
+        else:
+            await device.async_add_track_to_playlist(track)
+
+        if enqueue in (MediaPlayerEnqueue.NEXT, MediaPlayerEnqueue.PLAY):
+            # Move track to next item in the playlist
+            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) - new_tracks
+                    )
+                ):
+                    await device.async_move_track(index, _next)
+                if enqueue == MediaPlayerEnqueue.PLAY:
+                    await device.async_change_track(_next)
+
+        if (
+            enqueue in (MediaPlayerEnqueue.PLAY, MediaPlayerEnqueue.REPLACE)
+            and device.status_code != 4
+        ):
+            await device.async_play()
+
+    async def async_clear_playlist(self) -> None:
+        """Clear players playlist."""
+        self.abort_if_busy()
+        await self.device.async_clear_playlist()

custom_components/oasis_mini/number.py

@@ -1,19 +1,60 @@
-"""Oasis Mini number entity."""
+"""Oasis device number entity."""
 
 from __future__ import annotations
 
-from homeassistant.components.number import NumberEntity, NumberEntityDescription
-from homeassistant.config_entries import ConfigEntry
+from homeassistant.components.number import (
+    NumberEntity,
+    NumberEntityDescription,
+    NumberMode,
+)
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+from .pyoasiscontrol.device import (
+    BALL_SPEED_MAX,
+    BALL_SPEED_MIN,
+    LED_SPEED_MAX,
+    LED_SPEED_MIN,
+)
 
 
-class OasisMiniNumberEntity(OasisMiniEntity, NumberEntity):
-    """Oasis Mini number entity."""
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis device numbers using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    async_add_entities(
+        OasisDeviceNumberEntity(coordinator, device, descriptor)
+        for device in coordinator.data
+        for descriptor in DESCRIPTORS
+    )
+
+
+DESCRIPTORS = {
+    NumberEntityDescription(
+        key="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",
+        translation_key="led_speed",
+        mode=NumberMode.SLIDER,
+        native_max_value=LED_SPEED_MAX,
+        native_min_value=LED_SPEED_MIN,
+    ),
+}
+
+
+class OasisDeviceNumberEntity(OasisDeviceEntity, NumberEntity):
+    """Oasis device number entity."""
 
     @property
     def native_value(self) -> str | None:
@@ -22,37 +63,8 @@ class OasisMiniNumberEntity(OasisMiniEntity, NumberEntity):
 
     async def async_set_native_value(self, value: float) -> None:
         """Set new value."""
+        value = int(value)
         if self.entity_description.key == "ball_speed":
             await self.device.async_set_ball_speed(value)
         elif self.entity_description.key == "led_speed":
             await self.device.async_set_led(led_speed=value)
-        await self.coordinator.async_request_refresh()
-
-
-DESCRIPTORS = {
-    NumberEntityDescription(
-        key="ball_speed",
-        name="Ball speed",
-        native_max_value=800,
-        native_min_value=200,
-    ),
-    NumberEntityDescription(
-        key="led_speed",
-        name="LED speed",
-        native_max_value=90,
-        native_min_value=-90,
-    ),
-}
-
-
-async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
-) -> None:
-    """Set up Oasis Mini numbers using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    async_add_entities(
-        [
-            OasisMiniNumberEntity(coordinator, entry, descriptor)
-            for descriptor in DESCRIPTORS
-        ]
-    )

custom_components/oasis_mini/pyoasiscontrol/__init__.py

@@ -0,0 +1,7 @@
+"""Oasis control."""
+
+from .clients import OasisCloudClient, OasisMqttClient
+from .device import OasisDevice
+from .exceptions import UnauthenticatedError
+
+__all__ = ["OasisDevice", "OasisCloudClient", "OasisMqttClient", "UnauthenticatedError"]

custom_components/oasis_mini/pyoasiscontrol/clients/__init__.py

@@ -0,0 +1,7 @@
+"""Oasis control clients."""
+
+from .cloud_client import OasisCloudClient
+from .http_client import OasisHttpClient
+from .mqtt_client import OasisMqttClient
+
+__all__ = ["OasisCloudClient", "OasisHttpClient", "OasisMqttClient"]

custom_components/oasis_mini/pyoasiscontrol/clients/cloud_client.py

@@ -0,0 +1,191 @@
+"""Oasis cloud client."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+import logging
+from typing import Any
+from urllib.parse import urljoin
+
+from aiohttp import ClientResponseError, ClientSession
+
+from ..exceptions import UnauthenticatedError
+from ..utils import now
+
+_LOGGER = logging.getLogger(__name__)
+
+BASE_URL = "https://app.grounded.so"
+PLAYLISTS_REFRESH_LIMITER = timedelta(minutes=5)
+
+
+class OasisCloudClient:
+    """Cloud client for Oasis.
+
+    Responsibilities:
+    - Manage aiohttp session (optionally owned)
+    - Manage access token
+    - Provide async_* helpers for:
+        * login/logout
+        * user info
+        * devices
+        * tracks/playlists
+        * latest software metadata
+    """
+
+    _session: ClientSession | None
+    _owns_session: bool
+    _access_token: str | None
+
+    # these are "cache" fields for tracks/playlists
+    _playlists_next_refresh: float
+    playlists: list[dict[str, Any]]
+    _playlist_details: dict[int, dict[str, str]]
+
+    def __init__(
+        self,
+        *,
+        session: ClientSession | None = None,
+        access_token: str | None = None,
+    ) -> None:
+        self._session = session
+        self._owns_session = session is None
+        self._access_token = access_token
+
+        # simple in-memory caches
+        self._playlists_next_refresh = 0.0
+        self.playlists = []
+        self._playlist_details = {}
+
+    @property
+    def session(self) -> ClientSession:
+        """Return (or lazily create) the aiohttp ClientSession."""
+        if self._session is None or self._session.closed:
+            self._session = ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def async_close(self) -> None:
+        """Close owned session (call from HA unload / cleanup)."""
+        if self._session and not self._session.closed and self._owns_session:
+            await self._session.close()
+
+    @property
+    def access_token(self) -> str | None:
+        return self._access_token
+
+    @access_token.setter
+    def access_token(self, value: str | None) -> None:
+        self._access_token = value
+
+    async def async_login(self, email: str, password: str) -> None:
+        """Login via the cloud and store the access token."""
+        response = await self._async_request(
+            "POST",
+            urljoin(BASE_URL, "api/auth/login"),
+            json={"email": email, "password": password},
+        )
+        token = response.get("access_token") if isinstance(response, dict) else None
+        self.access_token = token
+        _LOGGER.debug("Cloud login succeeded, token set: %s", bool(token))
+
+    async def async_logout(self) -> None:
+        """Logout from the cloud."""
+        await self._async_auth_request("GET", "api/auth/logout")
+        self.access_token = None
+
+    async def async_get_user(self) -> dict:
+        """Get current user info."""
+        return await self._async_auth_request("GET", "api/auth/user")
+
+    async def async_get_devices(self) -> list[dict[str, Any]]:
+        """Get user devices (raw JSON from API)."""
+        return await self._async_auth_request("GET", "api/user/devices")
+
+    async def async_get_playlists(
+        self, personal_only: bool = False
+    ) -> list[dict[str, Any]]:
+        """Get playlists from the cloud (cached by PLAYLISTS_REFRESH_LIMITER)."""
+        if self._playlists_next_refresh <= now():
+            params = {"my_playlists": str(personal_only).lower()}
+            playlists = await self._async_auth_request(
+                "GET", "api/playlist", params=params
+            )
+            if playlists:
+                self.playlists = playlists
+            self._playlists_next_refresh = now() + PLAYLISTS_REFRESH_LIMITER
+        return self.playlists
+
+    async def async_get_track_info(self, track_id: int) -> dict[str, Any] | None:
+        """Get single track info from the cloud."""
+        try:
+            return await self._async_auth_request("GET", f"api/track/{track_id}")
+        except ClientResponseError as err:
+            if err.status == 404:
+                return {"id": track_id, "name": f"Unknown Title (#{track_id})"}
+        except Exception as ex:  # noqa: BLE001
+            _LOGGER.exception("Error fetching track %s: %s", track_id, ex)
+        return None
+
+    async def async_get_tracks(
+        self, tracks: list[int] | None = None
+    ) -> list[dict[str, Any]]:
+        """Get multiple tracks info from the cloud (handles pagination)."""
+        response = await self._async_auth_request(
+            "GET",
+            "api/track",
+            params={"ids[]": tracks or []},
+        )
+        if not response:
+            return []
+        track_details = response.get("data", [])
+        while next_page_url := response.get("next_page_url"):
+            response = await self._async_auth_request("GET", next_page_url)
+            track_details += response.get("data", [])
+        return track_details
+
+    async def async_get_latest_software_details(self) -> dict[str, int | str]:
+        """Get latest software metadata from cloud."""
+        return await self._async_auth_request("GET", "api/software/last-version")
+
+    async def _async_auth_request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Perform an authenticated cloud request."""
+        if not self.access_token:
+            raise UnauthenticatedError("Unauthenticated")
+
+        headers = kwargs.pop("headers", {}) or {}
+        headers["Authorization"] = f"Bearer {self.access_token}"
+
+        return await self._async_request(
+            method,
+            url if url.startswith("http") else urljoin(BASE_URL, url),
+            headers=headers,
+            **kwargs,
+        )
+
+    async def _async_request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Low-level HTTP helper for both cloud and (if desired) device HTTP."""
+        session = self.session
+        _LOGGER.debug(
+            "%s %s",
+            method,
+            session._build_url(url).update_query(  # pylint: disable=protected-access
+                kwargs.get("params"),
+            ),
+        )
+        response = await session.request(method, url, **kwargs)
+
+        if response.status == 200:
+            if response.content_type == "application/json":
+                return await response.json()
+            if response.content_type == "text/plain":
+                return await response.text()
+            if response.content_type == "text/html" and BASE_URL in url:
+                text = await response.text()
+                if "login-page" in text:
+                    raise UnauthenticatedError("Unauthenticated")
+            return None
+
+        if response.status == 401:
+            raise UnauthenticatedError("Unauthenticated")
+
+        response.raise_for_status()

custom_components/oasis_mini/pyoasiscontrol/clients/http_client.py

@@ -0,0 +1,180 @@
+"""Oasis HTTP client (per-device)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import ClientSession
+
+from ..device import OasisDevice
+from .transport import OasisClientProtocol
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class OasisHttpClient(OasisClientProtocol):
+    """HTTP-based Oasis transport.
+
+    This client is typically used per-device (per host/IP).
+    It implements the OasisClientProtocol so OasisDevice can delegate
+    all commands through it.
+    """
+
+    def __init__(self, host: str, session: ClientSession | None = None) -> None:
+        self._host = host
+        self._session: ClientSession | None = session
+        self._owns_session: bool = session is None
+
+    @property
+    def session(self) -> ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def async_close(self) -> None:
+        """Close owned session."""
+        if self._session and not self._session.closed and self._owns_session:
+            await self._session.close()
+
+    @property
+    def url(self) -> str:
+        # These devices are plain HTTP, no TLS
+        return f"http://{self._host}/"
+
+    async def _async_request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Low-level HTTP helper."""
+        session = self.session
+        _LOGGER.debug(
+            "%s %s",
+            method,
+            session._build_url(url).update_query(  # pylint: disable=protected-access
+                kwargs.get("params"),
+            ),
+        )
+        resp = await session.request(method, url, **kwargs)
+
+        if resp.status == 200:
+            if resp.content_type == "text/plain":
+                return await resp.text()
+            if resp.content_type == "application/json":
+                return await resp.json()
+            return None
+
+        resp.raise_for_status()
+
+    async def _async_get(self, **kwargs: Any) -> str | None:
+        return await self._async_request("GET", self.url, **kwargs)
+
+    async def _async_command(self, **kwargs: Any) -> str | None:
+        result = await self._async_get(**kwargs)
+        _LOGGER.debug("Result: %s", result)
+        return result
+
+    async def async_get_mac_address(self, device: OasisDevice) -> str | None:
+        """Fetch MAC address via HTTP GETMAC."""
+        try:
+            mac = await self._async_get(params={"GETMAC": ""})
+            if isinstance(mac, str):
+                return mac.strip()
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception(
+                "Failed to get MAC address via HTTP for %s", device.serial_number
+            )
+        return None
+
+    async def async_send_ball_speed_command(
+        self,
+        device: OasisDevice,
+        speed: int,
+    ) -> None:
+        await self._async_command(params={"WRIOASISSPEED": speed})
+
+    async def async_send_led_command(
+        self,
+        device: OasisDevice,
+        led_effect: str,
+        color: str,
+        led_speed: int,
+        brightness: int,
+    ) -> None:
+        payload = f"{led_effect};0;{color};{led_speed};{brightness}"
+        await self._async_command(params={"WRILED": payload})
+
+    async def async_send_sleep_command(self, device: OasisDevice) -> None:
+        await self._async_command(params={"CMDSLEEP": ""})
+
+    async def async_send_move_job_command(
+        self,
+        device: OasisDevice,
+        from_index: int,
+        to_index: int,
+    ) -> None:
+        await self._async_command(params={"MOVEJOB": f"{from_index};{to_index}"})
+
+    async def async_send_change_track_command(
+        self,
+        device: OasisDevice,
+        index: int,
+    ) -> None:
+        await self._async_command(params={"CMDCHANGETRACK": index})
+
+    async def async_send_add_joblist_command(
+        self,
+        device: OasisDevice,
+        tracks: list[int],
+    ) -> None:
+        # The old code passed the list directly; if the device expects CSV:
+        await self._async_command(params={"ADDJOBLIST": ",".join(map(str, tracks))})
+
+    async def async_send_set_playlist_command(
+        self,
+        device: OasisDevice,
+        playlist: list[int],
+    ) -> None:
+        await self._async_command(params={"WRIJOBLIST": ",".join(map(str, playlist))})
+        # optional: optimistic state update
+        device.update_from_status_dict({"playlist": playlist})
+
+    async def async_send_set_repeat_playlist_command(
+        self,
+        device: OasisDevice,
+        repeat: bool,
+    ) -> None:
+        await self._async_command(params={"WRIREPEATJOB": 1 if repeat else 0})
+
+    async def async_send_set_autoplay_command(
+        self,
+        device: OasisDevice,
+        option: str,
+    ) -> None:
+        await self._async_command(params={"WRIWAITAFTER": option})
+
+    async def async_send_upgrade_command(
+        self,
+        device: OasisDevice,
+        beta: bool,
+    ) -> None:
+        await self._async_command(params={"CMDUPGRADE": 1 if beta else 0})
+
+    async def async_send_play_command(self, device: OasisDevice) -> None:
+        await self._async_command(params={"CMDPLAY": ""})
+
+    async def async_send_pause_command(self, device: OasisDevice) -> None:
+        await self._async_command(params={"CMDPAUSE": ""})
+
+    async def async_send_stop_command(self, device: OasisDevice) -> None:
+        await self._async_command(params={"CMDSTOP": ""})
+
+    async def async_send_reboot_command(self, device: OasisDevice) -> None:
+        await self._async_command(params={"CMDBOOT": ""})
+
+    async def async_get_status(self, device: OasisDevice) -> None:
+        """Fetch status via GETSTATUS and update the device."""
+        raw_status = await self._async_get(params={"GETSTATUS": ""})
+        if raw_status is None:
+            return
+
+        _LOGGER.debug("Status for %s: %s", device.serial_number, raw_status)
+        device.update_from_status_string(raw_status)

custom_components/oasis_mini/pyoasiscontrol/clients/mqtt_client.py

@@ -0,0 +1,607 @@
+"""Oasis MQTT client (multi-device)."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from datetime import UTC, datetime
+import logging
+import ssl
+from typing import Any, Final
+
+import aiomqtt
+
+from ..device import OasisDevice
+from ..utils import _bit_to_bool, _parse_int
+from .transport import OasisClientProtocol
+
+_LOGGER = logging.getLogger(__name__)
+
+# mqtt connection parameters
+HOST: Final = "mqtt.grounded.so"
+PORT: Final = 8084
+PATH: Final = "mqtt"
+USERNAME: Final = "YXBw"
+PASSWORD: Final = "RWdETFlKMDczfi4t"
+RECONNECT_INTERVAL: Final = 4
+
+# Command queue behaviour
+MAX_PENDING_COMMANDS: Final = 10
+
+
+class OasisMqttClient(OasisClientProtocol):
+    """MQTT-based Oasis transport using WSS.
+
+    Responsibilities:
+    - Maintain a single MQTT connection to:
+        wss://mqtt.grounded.so:8084/mqtt
+    - Subscribe only to <serial>/STATUS/# for devices it knows about.
+    - Publish commands to <serial>/COMMAND/CMD
+    - Map MQTT payloads to OasisDevice.update_from_status_dict()
+    """
+
+    def __init__(self) -> None:
+        # MQTT connection state
+        self._client: aiomqtt.Client | None = None
+        self._loop_task: asyncio.Task | None = None
+        self._connected_at: datetime | None = None
+
+        self._connected_event: asyncio.Event = asyncio.Event()
+        self._stop_event: asyncio.Event = asyncio.Event()
+
+        # Known devices by serial
+        self._devices: dict[str, OasisDevice] = {}
+
+        # Per-device events
+        self._first_status_events: dict[str, asyncio.Event] = {}
+        self._mac_events: dict[str, asyncio.Event] = {}
+
+        # Subscription bookkeeping
+        self._subscribed_serials: set[str] = set()
+        self._subscription_lock = asyncio.Lock()
+
+        # Pending command queue: (serial, payload)
+        self._command_queue: asyncio.Queue[tuple[str, str]] = asyncio.Queue(
+            maxsize=MAX_PENDING_COMMANDS
+        )
+
+    def register_device(self, device: OasisDevice) -> None:
+        """Register a device so MQTT messages can be routed to it."""
+        if not device.serial_number:
+            raise ValueError("Device must have serial_number set before registration")
+
+        serial = device.serial_number
+        self._devices[serial] = device
+
+        # Ensure we have per-device events
+        self._first_status_events.setdefault(serial, asyncio.Event())
+        self._mac_events.setdefault(serial, asyncio.Event())
+
+        # Attach ourselves as the client if the device doesn't already have one
+        if not device.client:
+            device.attach_client(self)
+
+        # If we're already connected, subscribe to this device's topics
+        if self._client is not None:
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._subscribe_serial(serial))
+            except RuntimeError:
+                # No running loop (unlikely in HA), so just log
+                _LOGGER.debug(
+                    "Could not schedule subscription for %s (no running loop)", serial
+                )
+
+    def unregister_device(self, device: OasisDevice) -> None:
+        serial = device.serial_number
+        if not serial:
+            return
+
+        self._devices.pop(serial, None)
+        self._first_status_events.pop(serial, None)
+        self._mac_events.pop(serial, None)
+
+        # If connected and we were subscribed, unsubscribe
+        if self._client is not None and serial in self._subscribed_serials:
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(self._unsubscribe_serial(serial))
+            except RuntimeError:
+                _LOGGER.debug(
+                    "Could not schedule unsubscription for %s (no running loop)",
+                    serial,
+                )
+
+    async def _subscribe_serial(self, serial: str) -> None:
+        """Subscribe to STATUS topics for a single device."""
+        if not self._client:
+            return
+
+        async with self._subscription_lock:
+            if not self._client or serial in self._subscribed_serials:
+                return
+
+            topic = f"{serial}/STATUS/#"
+            await self._client.subscribe([(topic, 1)])
+            self._subscribed_serials.add(serial)
+            _LOGGER.info("Subscribed to %s", topic)
+
+    async def _unsubscribe_serial(self, serial: str) -> None:
+        """Unsubscribe from STATUS topics for a single device."""
+        if not self._client:
+            return
+
+        async with self._subscription_lock:
+            if not self._client or serial not in self._subscribed_serials:
+                return
+
+            topic = f"{serial}/STATUS/#"
+            await self._client.unsubscribe(topic)
+            self._subscribed_serials.discard(serial)
+            _LOGGER.info("Unsubscribed from %s", topic)
+
+    async def _resubscribe_all(self) -> None:
+        """Resubscribe to all known devices after (re)connect."""
+        self._subscribed_serials.clear()
+        for serial in list(self._devices):
+            await self._subscribe_serial(serial)
+
+    def start(self) -> None:
+        """Start MQTT connection loop."""
+        if self._loop_task is None or self._loop_task.done():
+            self._stop_event.clear()
+            loop = asyncio.get_running_loop()
+            self._loop_task = loop.create_task(self._mqtt_loop())
+
+    async def async_close(self) -> None:
+        """Close connection loop and MQTT client."""
+        await self.stop()
+
+    async def stop(self) -> None:
+        """Stop MQTT connection loop."""
+        self._stop_event.set()
+
+        if self._loop_task:
+            self._loop_task.cancel()
+            try:
+                await self._loop_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._client:
+            try:
+                await self._client.disconnect()
+            except Exception:
+                _LOGGER.exception("Error disconnecting MQTT client")
+            finally:
+                self._client = None
+
+        # Drop pending commands on stop
+        while not self._command_queue.empty():
+            try:
+                self._command_queue.get_nowait()
+                self._command_queue.task_done()
+            except asyncio.QueueEmpty:
+                break
+
+    async def wait_until_ready(
+        self, device: OasisDevice, timeout: float = 10.0, request_status: bool = True
+    ) -> bool:
+        """
+        Wait until:
+        1. MQTT client is connected
+        2. Device sends at least one STATUS message
+
+        If request_status=True, a request status command is sent *after* connection.
+        """
+        serial = device.serial_number
+        if not serial:
+            raise RuntimeError("Device has no serial_number set")
+
+        first_status_event = self._first_status_events.setdefault(
+            serial, asyncio.Event()
+        )
+
+        # Wait for MQTT connection
+        try:
+            await asyncio.wait_for(self._connected_event.wait(), timeout=timeout)
+        except asyncio.TimeoutError:
+            _LOGGER.debug(
+                "Timeout (%.1fs) waiting for MQTT connection (device %s)",
+                timeout,
+                serial,
+            )
+            return False
+
+        # Optionally request a status refresh
+        if request_status:
+            try:
+                first_status_event.clear()
+                await self.async_get_status(device)
+            except Exception:
+                _LOGGER.debug(
+                    "Could not request status for %s (not fully connected yet?)",
+                    serial,
+                )
+
+        # Wait for first status
+        try:
+            await asyncio.wait_for(first_status_event.wait(), timeout=timeout)
+            return True
+        except asyncio.TimeoutError:
+            _LOGGER.debug(
+                "Timeout (%.1fs) waiting for first STATUS message from %s",
+                timeout,
+                serial,
+            )
+            return False
+
+    async def async_get_mac_address(self, device: OasisDevice) -> str | None:
+        """For MQTT, GETSTATUS causes MAC_ADDRESS to be published."""
+        # If already known on the device, return it
+        if device.mac_address:
+            return device.mac_address
+
+        serial = device.serial_number
+        if not serial:
+            raise RuntimeError("Device has no serial_number set")
+
+        mac_event = self._mac_events.setdefault(serial, asyncio.Event())
+        mac_event.clear()
+
+        # Ask device to refresh status (including MAC_ADDRESS)
+        await self.async_get_status(device)
+
+        try:
+            await asyncio.wait_for(mac_event.wait(), timeout=3.0)
+        except asyncio.TimeoutError:
+            _LOGGER.debug("Timed out waiting for MAC_ADDRESS for %s", serial)
+
+        return device.mac_address
+
+    async def async_send_ball_speed_command(
+        self,
+        device: OasisDevice,
+        speed: int,
+    ) -> None:
+        payload = f"WRIOASISSPEED={speed}"
+        await self._publish_command(device, payload)
+
+    async def async_send_led_command(
+        self,
+        device: OasisDevice,
+        led_effect: str,
+        color: str,
+        led_speed: int,
+        brightness: int,
+    ) -> None:
+        payload = f"WRILED={led_effect};0;{color};{led_speed};{brightness}"
+        await self._publish_command(device, payload, bool(brightness))
+
+    async def async_send_sleep_command(self, device: OasisDevice) -> None:
+        await self._publish_command(device, "CMDSLEEP")
+
+    async def async_send_move_job_command(
+        self,
+        device: OasisDevice,
+        from_index: int,
+        to_index: int,
+    ) -> None:
+        payload = f"MOVEJOB={from_index};{to_index}"
+        await self._publish_command(device, payload)
+
+    async def async_send_change_track_command(
+        self,
+        device: OasisDevice,
+        index: int,
+    ) -> None:
+        payload = f"CMDCHANGETRACK={index}"
+        await self._publish_command(device, payload)
+
+    async def async_send_add_joblist_command(
+        self,
+        device: OasisDevice,
+        tracks: list[int],
+    ) -> None:
+        track_str = ",".join(map(str, tracks))
+        payload = f"ADDJOBLIST={track_str}"
+        await self._publish_command(device, payload)
+
+    async def async_send_set_playlist_command(
+        self,
+        device: OasisDevice,
+        playlist: list[int],
+    ) -> None:
+        track_str = ",".join(map(str, playlist))
+        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,
+        repeat: bool,
+    ) -> None:
+        payload = f"WRIREPEATJOB={1 if repeat else 0}"
+        await self._publish_command(device, payload)
+
+    async def async_send_set_autoplay_command(
+        self,
+        device: OasisDevice,
+        option: str,
+    ) -> None:
+        payload = f"WRIWAITAFTER={option}"
+        await self._publish_command(device, payload)
+
+    async def async_send_upgrade_command(
+        self,
+        device: OasisDevice,
+        beta: bool,
+    ) -> None:
+        payload = f"CMDUPGRADE={1 if beta else 0}"
+        await self._publish_command(device, payload)
+
+    async def async_send_play_command(self, device: OasisDevice) -> None:
+        await self._publish_command(device, "CMDPLAY", True)
+
+    async def async_send_pause_command(self, device: OasisDevice) -> None:
+        await self._publish_command(device, "CMDPAUSE")
+
+    async def async_send_stop_command(self, device: OasisDevice) -> None:
+        await self._publish_command(device, "CMDSTOP")
+
+    async def async_send_reboot_command(self, device: OasisDevice) -> None:
+        await self._publish_command(device, "CMDBOOT")
+
+    async def async_get_all(self, device: OasisDevice) -> None:
+        """Request FULLSTATUS + SCHEDULE (compact snapshot)."""
+        await self._publish_command(device, "GETALL")
+
+    async def async_get_status(self, device: OasisDevice) -> None:
+        """Ask device to publish STATUS topics."""
+        await self._publish_command(device, "GETSTATUS")
+
+    async def _enqueue_command(self, serial: str, payload: str) -> None:
+        """Queue a command to be sent when connected.
+
+        If the queue is full, drop the oldest command to make room.
+        """
+        if self._command_queue.full():
+            try:
+                dropped = self._command_queue.get_nowait()
+                self._command_queue.task_done()
+                _LOGGER.debug(
+                    "Command queue full, dropping oldest command: %s", dropped
+                )
+            except asyncio.QueueEmpty:
+                # race: became empty between full() and get_nowait()
+                pass
+
+        await self._command_queue.put((serial, payload))
+        _LOGGER.debug("Queued command for %s: %s", serial, payload)
+
+    async def _flush_pending_commands(self) -> None:
+        """Send any queued commands now that we're connected."""
+        if not self._client:
+            return
+
+        while not self._command_queue.empty():
+            try:
+                serial, payload = self._command_queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+
+            try:
+                # Skip commands for unknown devices
+                if serial not in self._devices:
+                    _LOGGER.debug(
+                        "Skipping queued command for unknown device %s: %s",
+                        serial,
+                        payload,
+                    )
+                    self._command_queue.task_done()
+                    continue
+
+                topic = f"{serial}/COMMAND/CMD"
+                _LOGGER.debug("Flushing queued MQTT command %s => %s", topic, payload)
+                await self._client.publish(topic, payload.encode(), qos=1)
+            except Exception:
+                _LOGGER.debug(
+                    "Failed to flush queued command for %s, re-queuing", serial
+                )
+                # Put it back and break; we'll try again on next reconnect
+                await self._enqueue_command(serial, payload)
+                self._command_queue.task_done()
+                break
+
+            self._command_queue.task_done()
+
+    async def _publish_command(
+        self, device: OasisDevice, payload: str, wake: bool = False
+    ) -> None:
+        serial = device.serial_number
+        if not serial:
+            raise RuntimeError("Device has no serial number set")
+
+        if wake and device.is_sleeping:
+            await self.async_get_all(device)
+
+        # If not connected, just queue the command
+        if not self._client or not self._connected_event.is_set():
+            _LOGGER.debug(
+                "MQTT not connected, queueing command for %s: %s", serial, payload
+            )
+            await self._enqueue_command(serial, payload)
+            return
+
+        topic = f"{serial}/COMMAND/CMD"
+        try:
+            _LOGGER.debug("MQTT publish %s => %s", topic, payload)
+            await self._client.publish(topic, payload.encode(), qos=1)
+        except Exception:
+            _LOGGER.debug(
+                "MQTT publish failed, queueing command for %s: %s", serial, payload
+            )
+            await self._enqueue_command(serial, payload)
+
+    async def _mqtt_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        tls_context = await loop.run_in_executor(None, ssl.create_default_context)
+
+        while not self._stop_event.is_set():
+            try:
+                _LOGGER.info("Connecting MQTT WSS to wss://%s:%s/%s", HOST, PORT, PATH)
+
+                async with aiomqtt.Client(
+                    hostname=HOST,
+                    port=PORT,
+                    transport="websockets",
+                    tls_context=tls_context,
+                    username=base64.b64decode(USERNAME).decode(),
+                    password=base64.b64decode(PASSWORD).decode(),
+                    keepalive=30,
+                    websocket_path=f"/{PATH}",
+                ) as client:
+                    self._client = client
+                    self._connected_event.set()
+                    self._connected_at = datetime.now(UTC)
+                    _LOGGER.info("Connected to MQTT broker")
+
+                    # Subscribe only to STATUS topics for known devices
+                    await self._resubscribe_all()
+
+                    # Flush any queued commands now that we're connected
+                    await self._flush_pending_commands()
+
+                    async for msg in client.messages:
+                        if self._stop_event.is_set():
+                            break
+                        await self._handle_status_message(msg)
+
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                _LOGGER.info("MQTT connection error")
+
+            finally:
+                if self._connected_event.is_set():
+                    self._connected_event.clear()
+                    if self._connected_at:
+                        _LOGGER.info(
+                            "MQTT was connected for %s",
+                            datetime.now(UTC) - self._connected_at,
+                        )
+                    self._connected_at = None
+                self._client = None
+                self._subscribed_serials.clear()
+
+            if not self._stop_event.is_set():
+                _LOGGER.info(
+                    "Disconnected from broker, retrying in %.1fs", RECONNECT_INTERVAL
+                )
+                await asyncio.sleep(RECONNECT_INTERVAL)
+
+    async def _handle_status_message(self, msg: aiomqtt.Message) -> None:
+        """Map MQTT STATUS topics → OasisDevice.update_from_status_dict payloads."""
+        topic_str = str(msg.topic) if msg.topic is not None else ""
+        payload = msg.payload.decode(errors="replace")
+
+        parts = topic_str.split("/")
+        # Expect: "<serial>/STATUS/<STATUS_NAME>"
+        if len(parts) < 3:
+            return
+
+        serial, _, status_name = parts[:3]
+
+        device = self._devices.get(serial)
+        if not device:
+            _LOGGER.debug("Received MQTT for unknown device %s: %s", serial, topic_str)
+            return
+
+        data: dict[str, Any] = {}
+
+        try:
+            if status_name == "OASIS_STATUS":
+                data["status_code"] = int(payload)
+            elif status_name == "OASIS_ERROR":
+                data["error"] = int(payload)
+            elif status_name == "OASIS_SPEEED":
+                data["ball_speed"] = int(payload)
+            elif status_name == "JOBLIST":
+                data["playlist"] = [int(x) for x in payload.split(",") if x]
+            elif status_name == "CURRENTJOB":
+                data["playlist_index"] = int(payload)
+            elif status_name == "CURRENTLINE":
+                data["progress"] = int(payload)
+            elif status_name == "LED_EFFECT":
+                data["led_effect"] = payload
+            elif status_name == "LED_EFFECT_COLOR":
+                data["led_color_id"] = payload
+            elif status_name == "LED_SPEED":
+                data["led_speed"] = int(payload)
+            elif status_name == "LED_BRIGHTNESS":
+                data["brightness"] = int(payload)
+            elif status_name == "LED_MAX":
+                data["brightness_max"] = int(payload)
+            elif status_name == "LED_EFFECT_PARAM":
+                data["color"] = payload if payload.startswith("#") else None
+            elif status_name == "SYSTEM_BUSY":
+                data["busy"] = payload in ("1", "true", "True")
+            elif status_name == "DOWNLOAD_PROGRESS":
+                data["download_progress"] = int(payload)
+            elif status_name == "REPEAT_JOB":
+                data["repeat_playlist"] = payload in ("1", "true", "True")
+            elif status_name == "WAIT_AFTER_JOB":
+                data["autoplay"] = _parse_int(payload)
+            elif status_name == "AUTO_CLEAN":
+                data["auto_clean"] = payload in ("1", "true", "True")
+            elif status_name == "SOFTWARE_VER":
+                data["software_version"] = payload
+            elif status_name == "MAC_ADDRESS":
+                data["mac_address"] = payload
+                mac_event = self._mac_events.setdefault(serial, asyncio.Event())
+                mac_event.set()
+            elif status_name == "WIFI_SSID":
+                data["wifi_ssid"] = payload
+            elif status_name == "WIFI_IP":
+                data["wifi_ip"] = payload
+            elif status_name == "WIFI_PDNS":
+                data["wifi_pdns"] = payload
+            elif status_name == "WIFI_SDNS":
+                data["wifi_sdns"] = payload
+            elif status_name == "WIFI_GATE":
+                data["wifi_gate"] = payload
+            elif status_name == "WIFI_SUB":
+                data["wifi_sub"] = payload
+            elif status_name == "WIFI_STATUS":
+                data["wifi_connected"] = _bit_to_bool(payload)
+            elif status_name == "SCHEDULE":
+                data["schedule"] = payload
+            elif status_name == "ENVIRONMENT":
+                data["environment"] = payload
+            elif status_name == "FULLSTATUS":
+                if parsed := device.parse_status_string(payload):
+                    data = parsed
+            else:
+                _LOGGER.warning(
+                    "Unknown status received for %s: %s=%s",
+                    serial,
+                    status_name,
+                    payload,
+                )
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception(
+                "Error parsing MQTT payload for %s %s: %r", serial, status_name, payload
+            )
+            return
+
+        if data:
+            device.update_from_status_dict(data)
+
+        first_status_event = self._first_status_events.setdefault(
+            serial, asyncio.Event()
+        )
+        if not first_status_event.is_set():
+            first_status_event.set()

custom_components/oasis_mini/pyoasiscontrol/clients/transport.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from ..device import OasisDevice
+
+
+@runtime_checkable
+class OasisClientProtocol(Protocol):
+    """Transport/client interface for an Oasis device.
+
+    Concrete implementations:
+    - MQTT client (remote connection)
+    - HTTP client (direct LAN)
+    """
+
+    async def async_get_mac_address(self, device: OasisDevice) -> str | None: ...
+
+    async def async_send_ball_speed_command(
+        self,
+        device: OasisDevice,
+        speed: int,
+    ) -> None: ...
+
+    async def async_send_led_command(
+        self,
+        device: OasisDevice,
+        led_effect: str,
+        color: str,
+        led_speed: int,
+        brightness: int,
+    ) -> None: ...
+
+    async def async_send_sleep_command(self, device: OasisDevice) -> None: ...
+
+    async def async_send_move_job_command(
+        self,
+        device: OasisDevice,
+        from_index: int,
+        to_index: int,
+    ) -> None: ...
+
+    async def async_send_change_track_command(
+        self,
+        device: OasisDevice,
+        index: int,
+    ) -> None: ...
+
+    async def async_send_add_joblist_command(
+        self,
+        device: OasisDevice,
+        tracks: list[int],
+    ) -> None: ...
+
+    async def async_send_set_playlist_command(
+        self,
+        device: OasisDevice,
+        playlist: list[int],
+    ) -> None: ...
+
+    async def async_send_set_repeat_playlist_command(
+        self,
+        device: OasisDevice,
+        repeat: bool,
+    ) -> None: ...
+
+    async def async_send_set_autoplay_command(
+        self,
+        device: OasisDevice,
+        option: str,
+    ) -> None: ...
+
+    async def async_send_upgrade_command(
+        self,
+        device: OasisDevice,
+        beta: bool,
+    ) -> None: ...
+
+    async def async_send_play_command(self, device: OasisDevice) -> None: ...
+
+    async def async_send_pause_command(self, device: OasisDevice) -> None: ...
+
+    async def async_send_stop_command(self, device: OasisDevice) -> None: ...
+
+    async def async_send_reboot_command(self, device: OasisDevice) -> None: ...
+
+    async def async_get_all(self, device: OasisDevice) -> None: ...
+
+    async def async_get_status(self, device: OasisDevice) -> None: ...

custom_components/oasis_mini/pyoasiscontrol/const.py

@@ -0,0 +1,110 @@
+"""Constants."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Final
+
+__TRACKS_FILE = os.path.join(os.path.dirname(__file__), "tracks.json")
+try:
+    with open(__TRACKS_FILE, "r", encoding="utf8") as file:
+        TRACKS: Final[dict[int, dict[str, Any]]] = {
+            int(k): v for k, v in json.load(file).items()
+        }
+except Exception:  # ignore: broad-except
+    TRACKS = {}
+
+AUTOPLAY_MAP: Final[dict[str, str]] = {
+    "0": "on",
+    "1": "off",
+    "2": "5 minutes",
+    "3": "10 minutes",
+    "4": "30 minutes",
+    "6": "1 hour",
+    "7": "6 hours",
+    "8": "12 hours",
+    "5": "24 hours",
+}
+
+ERROR_CODE_MAP: Final[dict[int, str]] = {
+    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_EFFECTS: Final[dict[str, str]] = {
+    "0": "Solid",
+    "1": "Rainbow",
+    "2": "Glitter",
+    "3": "Confetti",
+    "4": "Sinelon",
+    "5": "BPM",
+    "6": "Juggle",
+    "7": "Theater",
+    "8": "Color Wipe",
+    "9": "Sparkle",
+    "10": "Comet",
+    "11": "Follow Ball",
+    "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",
+}
+
+STATUS_CODE_SLEEPING: Final = 6
+STATUS_CODE_MAP: Final[dict[int, str]] = {
+    0: "booting",
+    2: "stopped",
+    3: "centering",
+    4: "playing",
+    5: "paused",
+    STATUS_CODE_SLEEPING: "sleeping",
+    9: "error",
+    11: "updating",
+    13: "downloading",
+    14: "busy",
+    15: "live",
+}

custom_components/oasis_mini/pyoasiscontrol/device.py

@@ -0,0 +1,412 @@
+"""Oasis device."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Callable, Final, Iterable
+
+from .const import (
+    ERROR_CODE_MAP,
+    LED_EFFECTS,
+    STATUS_CODE_MAP,
+    STATUS_CODE_SLEEPING,
+    TRACKS,
+)
+from .utils import _bit_to_bool, _parse_int
+
+if TYPE_CHECKING:  # avoid runtime circular imports
+    from .clients.transport import OasisClientProtocol
+
+_LOGGER = logging.getLogger(__name__)
+
+BALL_SPEED_MAX: Final = 400
+BALL_SPEED_MIN: Final = 100
+LED_SPEED_MAX: Final = 90
+LED_SPEED_MIN: Final = -90
+
+_STATE_FIELDS = (
+    "auto_clean",
+    "autoplay",
+    "ball_speed",
+    "brightness",
+    "busy",
+    "color",
+    "download_progress",
+    "error",
+    "led_effect",
+    "led_speed",
+    "mac_address",
+    "playlist",
+    "playlist_index",
+    "progress",
+    "repeat_playlist",
+    "serial_number",
+    "software_version",
+    "status_code",
+)
+
+
+class OasisDevice:
+    """Oasis device model + behavior.
+
+    Transport-agnostic; all I/O is delegated to an attached
+    OasisClientProtocol (MQTT, HTTP, etc.) via `attach_client`.
+    """
+
+    manufacturer: Final = "Kinetic Oasis"
+
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        serial_number: str | None = None,
+        ssid: str | None = None,
+        ip_address: str | None = None,
+        client: OasisClientProtocol | None = None,
+    ) -> None:
+        # Transport
+        self._client: OasisClientProtocol | None = client
+        self._listeners: list[Callable[[], None]] = []
+
+        # Details
+        self.model: str | None = model
+        self.serial_number: str | None = serial_number
+        self.ssid: str | None = ssid
+        self.ip_address: str | None = ip_address
+
+        # Status
+        self.auto_clean: bool = False
+        self.autoplay: int = 0
+        self.ball_speed: int = BALL_SPEED_MIN
+        self._brightness: int = 0
+        self.brightness_max: int = 200
+        self.brightness_on: int = 0
+        self.busy: bool = False
+        self.color: str | None = None
+        self.download_progress: int = 0
+        self.error: int = 0
+        self.led_color_id: str = "0"
+        self.led_effect: str = "0"
+        self.led_speed: int = 0
+        self.mac_address: str | None = None
+        self.playlist: list[int] = []
+        self.playlist_index: int = 0
+        self.progress: int = 0
+        self.repeat_playlist: bool = False
+        self.software_version: str | None = None
+        self.status_code: int = 0
+        self.wifi_connected: bool = False
+        self.wifi_ip: str | None = None
+        self.wifi_ssid: str | None = None
+        self.wifi_pdns: str | None = None
+        self.wifi_sdns: str | None = None
+        self.wifi_gate: str | None = None
+        self.wifi_sub: str | None = None
+        self.environment: str | None = None
+        self.schedule: Any | None = None
+
+        # Track metadata cache (used if you hydrate from cloud)
+        self._track: dict | None = None
+
+    @property
+    def brightness(self) -> int:
+        """Return the brightness."""
+        return 0 if self.is_sleeping else self._brightness
+
+    @brightness.setter
+    def brightness(self, value: int) -> None:
+        self._brightness = value
+        if value:
+            self.brightness_on = value
+
+    @property
+    def is_sleeping(self) -> bool:
+        """Return `True` if the status is set to sleeping."""
+        return self.status_code == STATUS_CODE_SLEEPING
+
+    def attach_client(self, client: OasisClientProtocol) -> None:
+        """Attach a transport client (MQTT, HTTP, etc.) to this device."""
+        self._client = client
+
+    @property
+    def client(self) -> OasisClientProtocol | None:
+        """Return the current transport client, if any."""
+        return self._client
+
+    def _require_client(self) -> OasisClientProtocol:
+        """Return the attached client or raise if missing."""
+        if self._client is None:
+            raise RuntimeError(
+                f"No client/transport attached for device {self.serial_number!r}"
+            )
+        return self._client
+
+    def _update_field(self, name: str, value: Any) -> bool:
+        old = getattr(self, name, None)
+        if old != value:
+            _LOGGER.debug(
+                "%s changed: '%s' -> '%s'",
+                name.replace("_", " ").capitalize(),
+                old,
+                value,
+            )
+            setattr(self, name, value)
+            return True
+        return False
+
+    def update_from_status_dict(self, data: dict[str, Any]) -> None:
+        """Update device fields from a status payload (from any transport)."""
+        changed = False
+        for key, value in data.items():
+            if hasattr(self, key):
+                if self._update_field(key, value):
+                    changed = True
+            else:
+                _LOGGER.warning("Unknown field: %s=%s", key, value)
+
+        if changed:
+            self._notify_listeners()
+
+    def parse_status_string(self, raw_status: str) -> dict[str, Any] | None:
+        """Parse a semicolon-separated status string into a state dict.
+
+        Used by:
+        - HTTP GETSTATUS response
+        - MQTT FULLSTATUS payload (includes software_version)
+        """
+        if not raw_status:
+            return None
+
+        values = raw_status.split(";")
+
+        # We rely on indices 0..17 existing (18 fields)
+        if (n := len(values)) < 18:
+            _LOGGER.warning(
+                "Unexpected status format for %s: %s", self.serial_number, values
+            )
+            return None
+
+        playlist = [_parse_int(track) for track in values[3].split(",") if track]
+
+        try:
+            status: dict[str, Any] = {
+                "status_code": _parse_int(values[0]),
+                "error": _parse_int(values[1]),
+                "ball_speed": _parse_int(values[2]),
+                "playlist": playlist,
+                "playlist_index": min(_parse_int(values[4]), len(playlist)),
+                "progress": _parse_int(values[5]),
+                "led_effect": values[6],
+                "led_color_id": values[7],
+                "led_speed": _parse_int(values[8]),
+                "brightness": _parse_int(values[9]),
+                "color": values[10] if "#" in values[10] else None,
+                "busy": _bit_to_bool(values[11]),
+                "download_progress": _parse_int(values[12]),
+                "brightness_max": _parse_int(values[13]),
+                "wifi_connected": _bit_to_bool(values[14]),
+                "repeat_playlist": _bit_to_bool(values[15]),
+                "autoplay": _parse_int(values[16]),
+                "auto_clean": _bit_to_bool(values[17]),
+            }
+
+            # Optional trailing field(s)
+            if n > 18:
+                status["software_version"] = values[18]
+
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception(
+                "Error parsing status string for %s: %r", self.serial_number, raw_status
+            )
+            return None
+
+        return status
+
+    def update_from_status_string(self, raw_status: str) -> None:
+        """Parse and apply a raw status string."""
+        if status := self.parse_status_string(raw_status):
+            self.update_from_status_dict(status)
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return core state as a dict."""
+        return {field: getattr(self, field) for field in _STATE_FIELDS}
+
+    @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 status(self) -> str:
+        """Return human-readable status from status_code."""
+        return STATUS_CODE_MAP.get(self.status_code, f"Unknown ({self.status_code})")
+
+    @property
+    def track_id(self) -> int | None:
+        if not self.playlist:
+            return None
+        i = self.playlist_index
+        return self.playlist[0] if i >= len(self.playlist) else self.playlist[i]
+
+    @property
+    def track(self) -> dict | None:
+        """Return cached track info if it matches the current `track_id`."""
+        if self._track and self._track.get("id") == self.track_id:
+            return self._track
+        if track := TRACKS.get(self.track_id):
+            self._track = track
+            return self._track
+        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"))):
+        #     return None
+        # svg_content = decrypt_svg_content(svg_content)
+        # paths = svg_content.split("L")
+        total = self.track.get("reduced_svg_content_new", 0)  # or len(paths)
+        percent = (100 * self.progress) / total
+        return percent
+
+    @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,
+                {"name": f"Unknown Title (#{track_id})"},
+            )
+            for track_id in self.playlist
+        }
+
+    def add_update_listener(self, listener: Callable[[], None]) -> Callable[[], None]:
+        """Register a callback for state changes.
+
+        Returns an unsubscribe function.
+        """
+        self._listeners.append(listener)
+
+        def _unsub() -> None:
+            try:
+                self._listeners.remove(listener)
+            except ValueError:
+                pass
+
+        return _unsub
+
+    def _notify_listeners(self) -> None:
+        """Call all registered listeners."""
+        for listener in list(self._listeners):
+            try:
+                listener()
+            except Exception:  # noqa: BLE001
+                _LOGGER.exception("Error in update listener")
+
+    async def async_get_mac_address(self) -> str | None:
+        """Return the device MAC address, refreshing via transport if needed."""
+        if self.mac_address:
+            return self.mac_address
+
+        client = self._require_client()
+        mac = await client.async_get_mac_address(self)
+        if mac:
+            self._update_field("mac_address", mac)
+        return mac
+
+    async def async_set_ball_speed(self, speed: int) -> None:
+        if not BALL_SPEED_MIN <= speed <= BALL_SPEED_MAX:
+            raise ValueError("Invalid speed specified")
+        client = self._require_client()
+        await client.async_send_ball_speed_command(self, speed)
+
+    async def async_set_led(
+        self,
+        *,
+        led_effect: str | None = None,
+        color: str | None = None,
+        led_speed: int | None = None,
+        brightness: int | None = None,
+    ) -> None:
+        """Set the Oasis Mini LED (shared validation & attribute updates)."""
+        if led_effect is None:
+            led_effect = self.led_effect
+        if color is None:
+            color = self.color or "#ffffff"
+        if led_speed is None:
+            led_speed = self.led_speed
+        if brightness is None:
+            brightness = self.brightness
+
+        if led_effect not in LED_EFFECTS:
+            raise ValueError("Invalid led effect specified")
+        if not LED_SPEED_MIN <= led_speed <= LED_SPEED_MAX:
+            raise ValueError("Invalid led speed specified")
+        if not 0 <= brightness <= self.brightness_max:
+            raise ValueError("Invalid brightness specified")
+
+        client = self._require_client()
+        await client.async_send_led_command(
+            self, led_effect, color, led_speed, brightness
+        )
+
+    async def async_sleep(self) -> None:
+        client = self._require_client()
+        await client.async_send_sleep_command(self)
+
+    async def async_move_track(self, from_index: int, to_index: int) -> None:
+        client = self._require_client()
+        await client.async_send_move_job_command(self, from_index, to_index)
+
+    async def async_change_track(self, index: int) -> None:
+        client = self._require_client()
+        await client.async_send_change_track_command(self, index)
+
+    async def async_add_track_to_playlist(self, track: int | Iterable[int]) -> None:
+        if isinstance(track, int):
+            tracks = [track]
+        else:
+            tracks = list(track)
+        client = self._require_client()
+        await client.async_send_add_joblist_command(self, tracks)
+
+    async def async_set_playlist(self, playlist: int | Iterable[int]) -> None:
+        if isinstance(playlist, int):
+            playlist_list = [playlist]
+        else:
+            playlist_list = list(playlist)
+        client = self._require_client()
+        await client.async_send_set_playlist_command(self, playlist_list)
+
+    async def async_set_repeat_playlist(self, repeat: bool) -> None:
+        client = self._require_client()
+        await client.async_send_set_repeat_playlist_command(self, repeat)
+
+    async def async_set_autoplay(self, option: bool | int | str) -> None:
+        """Set autoplay / wait-after behavior."""
+        if isinstance(option, bool):
+            option = 0 if option else 1
+        client = self._require_client()
+        await client.async_send_set_autoplay_command(self, str(option))
+
+    async def async_upgrade(self, beta: bool = False) -> None:
+        client = self._require_client()
+        await client.async_send_upgrade_command(self, beta)
+
+    async def async_play(self) -> None:
+        client = self._require_client()
+        await client.async_send_play_command(self)
+
+    async def async_pause(self) -> None:
+        client = self._require_client()
+        await client.async_send_pause_command(self)
+
+    async def async_stop(self) -> None:
+        client = self._require_client()
+        await client.async_send_stop_command(self)
+
+    async def async_reboot(self) -> None:
+        client = self._require_client()
+        await client.async_send_reboot_command(self)

custom_components/oasis_mini/pyoasiscontrol/exceptions.py

@@ -0,0 +1,5 @@
+"""Exceptions."""
+
+
+class UnauthenticatedError(Exception):
+    """Unauthenticated."""

custom_components/oasis_mini/pyoasiscontrol/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,15 +27,24 @@ 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))
-                percent = (100 * progress) / total
-                progress = math.floor((percent / 100) * 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))
 
                 svg = Element(
                     "svg",
@@ -56,7 +72,7 @@ def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
                         path.progress_arc_complete {{ stroke: {COLOR_DARK[1]}; }}
                         path.track {{ stroke: {COLOR_LIGHT_SHADE[1]}; }}
                         path.track_complete {{ stroke: {COLOR_MEDIUM_TINT[1]}; }}
-                    }}"""
+                    }}""".replace("\n", " ").strip()
 
                 group = SubElement(
                     svg,
@@ -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/pyoasismini/__init__.py

@@ -1,311 +0,0 @@
-"""Oasis Mini API client."""
-
-import asyncio
-import logging
-from typing import Any, Awaitable, Callable, Final
-from urllib.parse import urljoin
-
-from aiohttp import ClientSession
-
-from .utils import _bit_to_bool
-
-_LOGGER = logging.getLogger(__name__)
-
-STATUS_CODE_MAP = {
-    2: "stopped",
-    3: "centering",
-    4: "running",
-    5: "paused",
-    9: "error",
-    13: "downloading",
-}
-
-ATTRIBUTES: Final[list[tuple[str, Callable[[str], Any]]]] = [
-    ("status_code", int),  # see status code map
-    ("error", str),  # error, 0 = none, and 10 = ?, 18 = can't download?
-    ("ball_speed", int),  # 200 - 800
-    ("playlist", lambda value: [int(track) for track in value.split(",")]),  # noqa: E501 # comma separated track ids
-    ("playlist_index", int),  # index of above
-    ("progress", int),  # 0 - max svg path
-    ("led_effect", str),  # led effect (code lookup)
-    ("led_color_id", str),  # led color id?
-    ("led_speed", int),  # -90 - 90
-    ("brightness", int),  # noqa: E501 # 0 - 200 in app, but seems to be 0 (off) to 304 (max), then repeats
-    ("color", str),  # hex color code
-    ("busy", _bit_to_bool),  # noqa: E501 # device is busy (downloading track, centering, software update)?
-    ("download_progress", int),  # 0 - 100%
-    ("max_brightness", int),
-    ("wifi_connected", _bit_to_bool),
-    ("repeat_playlist", _bit_to_bool),
-    ("pause_between_tracks", _bit_to_bool),
-]
-
-LED_EFFECTS: Final[dict[str, str]] = {
-    "0": "Solid",
-    "1": "Rainbow",
-    "2": "Glitter",
-    "3": "Confetti",
-    "4": "Sinelon",
-    "5": "BPM",
-    "6": "Juggle",
-    "7": "Theater",
-    "8": "Color Wipe",
-    "9": "Sparkle",
-    "10": "Comet",
-    "11": "Follow Ball",
-    "12": "Follow Rainbow",
-    "13": "Chasing Comet",
-    "14": "Gradient Follow",
-}
-
-CLOUD_BASE_URL = "https://app.grounded.so"
-CLOUD_API_URL = f"{CLOUD_BASE_URL}/api"
-
-
-class OasisMini:
-    """Oasis Mini API client class."""
-
-    _access_token: str | None = None
-    _current_track_details: dict | None = None
-    _serial_number: str | None = None
-    _software_version: str | None = None
-
-    brightness: int
-    color: str
-    led_effect: str
-    led_speed: int
-    max_brightness: int
-    playlist: list[int]
-    playlist_index: int
-    progress: int
-    status_code: int
-
-    def __init__(
-        self,
-        host: str,
-        access_token: str | None = None,
-        session: ClientSession | None = None,
-    ) -> None:
-        """Initialize the client."""
-        self._host = host
-        self._access_token = access_token
-        self._session = session if session else ClientSession()
-
-    @property
-    def access_token(self) -> str | None:
-        """Return the access token, if any."""
-        return self._access_token
-
-    @property
-    def current_track_id(self) -> int:
-        """Return the current track."""
-        i = self.playlist_index
-        return self.playlist[0] if i >= len(self.playlist) else self.playlist[i]
-
-    @property
-    def serial_number(self) -> str | None:
-        """Return the serial number."""
-        return self._serial_number
-
-    @property
-    def session(self) -> ClientSession:
-        """Return the session."""
-        return self._session
-
-    @property
-    def software_version(self) -> str | None:
-        """Return the software version."""
-        return self._software_version
-
-    @property
-    def status(self) -> str:
-        """Return the status."""
-        return STATUS_CODE_MAP.get(self.status_code, f"Unknown ({self.status_code})")
-
-    @property
-    def url(self) -> str:
-        """Return the url."""
-        return f"http://{self._host}/"
-
-    async def async_add_track_to_playlist(self, track: int) -> None:
-        """Add track to playlist."""
-        await self._async_command(params={"ADDJOBLIST": track})
-        self.playlist.append(track)
-
-    async def async_change_track(self, index: int) -> None:
-        """Change the track."""
-        if index >= len(self.playlist):
-            raise ValueError("Invalid selection")
-        await self._async_command(params={"CMDCHANGETRACK": index})
-
-    async def async_get_serial_number(self) -> str | None:
-        """Get the serial number."""
-        self._serial_number = await self._async_get(params={"GETOASISID": ""})
-        _LOGGER.debug("Serial number: %s", self._serial_number)
-        return self._serial_number
-
-    async def async_get_software_version(self) -> str | None:
-        """Get the software version."""
-        self._software_version = await self._async_get(params={"GETSOFTWAREVER": ""})
-        _LOGGER.debug("Software version: %s", self._software_version)
-        return self._software_version
-
-    async def async_get_status(self) -> None:
-        """Get the status from the device."""
-        status = await self._async_get(params={"GETSTATUS": ""})
-        _LOGGER.debug("Status: %s", status)
-        for index, value in enumerate(status.split(";")):
-            attr, func = ATTRIBUTES[index]
-            if (old_value := getattr(self, attr, None)) != (value := func(value)):
-                _LOGGER.debug("%s changed: '%s' -> '%s'", attr, old_value, value)
-                setattr(self, attr, value)
-        return status
-
-    async def async_move_track(self, _from: int, _to: int) -> None:
-        """Move a track in the playlist."""
-        await self._async_command(params={"MOVEJOB": f"{_from};{_to}"})
-
-    async def async_pause(self) -> None:
-        """Send pause command."""
-        await self._async_command(params={"CMDPAUSE": ""})
-
-    async def async_play(self) -> None:
-        """Send play command."""
-        await self._async_command(params={"CMDPLAY": ""})
-
-    async def async_reboot(self) -> None:
-        """Send reboot command."""
-
-        async def _no_response_needed(coro: Awaitable) -> None:
-            try:
-                await coro
-            except Exception as ex:
-                _LOGGER.error(ex)
-
-        reboot = self._async_command(params={"CMDBOOT": ""})
-        asyncio.create_task(_no_response_needed(reboot))
-
-    async def async_set_ball_speed(self, speed: int) -> None:
-        """Set the Oasis Mini ball speed."""
-        if not 200 <= speed <= 800:
-            raise Exception("Invalid speed specified")
-
-        await self._async_command(params={"WRIOASISSPEED": speed})
-
-    async def async_set_led(
-        self,
-        *,
-        led_effect: str | None = None,
-        color: str | None = None,
-        led_speed: int | None = None,
-        brightness: int | None = None,
-    ) -> None:
-        """Set the Oasis Mini led."""
-        if led_effect is None:
-            led_effect = self.led_effect
-        if color is None:
-            color = self.color
-        if led_speed is None:
-            led_speed = self.led_speed
-        if brightness is None:
-            brightness = self.brightness
-
-        if led_effect not in LED_EFFECTS:
-            raise Exception("Invalid led effect specified")
-        if not -90 <= led_speed <= 90:
-            raise Exception("Invalid led speed specified")
-        if not 0 <= brightness <= 200:
-            raise Exception("Invalid brightness specified")
-
-        await self._async_command(
-            params={"WRILED": f"{led_effect};0;{color};{led_speed};{brightness}"}
-        )
-
-    async def async_set_pause_between_tracks(self, pause: bool) -> None:
-        """Set the Oasis Mini pause between tracks."""
-        await self._async_command(params={"WRIWAITAFTER": 1 if pause else 0})
-
-    async def async_set_repeat_playlist(self, repeat: bool) -> None:
-        """Set the Oasis Mini repeat playlist."""
-        await self._async_command(params={"WRIREPEATJOB": 1 if repeat else 0})
-
-    async def _async_command(self, **kwargs: Any) -> str | None:
-        """Send a command request."""
-        result = await self._async_get(**kwargs)
-        _LOGGER.debug("Result: %s", result)
-
-    async def _async_get(self, **kwargs: Any) -> str | None:
-        """Perform a GET request."""
-        response = await self._session.get(self.url, **kwargs)
-        if response.status == 200 and response.content_type == "text/plain":
-            text = await response.text()
-            return text
-        return None
-
-    async def async_cloud_login(self, email: str, password: str) -> None:
-        """Login via the cloud."""
-        response = await self._async_request(
-            "POST",
-            urljoin(CLOUD_BASE_URL, "api/auth/login"),
-            json={"email": email, "password": password},
-        )
-        self._access_token = response.get("access_token")
-
-    async def async_cloud_logout(self) -> None:
-        """Login via the cloud."""
-        if not self.access_token:
-            return
-        await self._async_request(
-            "GET",
-            urljoin(CLOUD_BASE_URL, "api/auth/logout"),
-            headers={"Authorization": f"Bearer {self.access_token}"},
-        )
-
-    async def async_cloud_get_track_info(self, track_id: int) -> None:
-        """Get cloud track info."""
-        if not self.access_token:
-            return
-
-        response = await self._async_request(
-            "GET",
-            urljoin(CLOUD_BASE_URL, f"api/track/{track_id}"),
-            headers={"Authorization": f"Bearer {self.access_token}"},
-        )
-        return response
-
-    async def async_cloud_get_tracks(self, tracks: list[int]) -> None:
-        """Get cloud tracks."""
-        if not self.access_token:
-            return
-
-        response = await self._async_request(
-            "GET",
-            urljoin(CLOUD_BASE_URL, "api/track"),
-            headers={"Authorization": f"Bearer {self.access_token}"},
-            params={"ids[]": tracks},
-        )
-        return response
-
-    async def _async_request(self, method: str, url: str, **kwargs) -> Any:
-        """Login via the cloud."""
-        response = await self._session.request(method, url, **kwargs)
-        if response.status == 200:
-            if response.headers.get("Content-Type") == "application/json":
-                return await response.json()
-            return await response.text()
-        response.raise_for_status()
-
-    async def async_get_current_track_details(self) -> dict:
-        """Get current track info, refreshing if needed."""
-        if (track_details := self._current_track_details) and track_details.get(
-            "id"
-        ) == self.current_track_id:
-            return track_details
-
-        self._current_track_details = await self.async_cloud_get_track_info(
-            self.current_track_id
-        )
-
-    async def async_get_playlist_details(self) -> dict:
-        """Get playlist info."""
-        return await self.async_cloud_get_tracks(self.playlist)

custom_components/oasis_mini/pyoasismini/const.py

@@ -1,11 +0,0 @@
-"""Constants."""
-
-from __future__ import annotations
-
-import json
-import os
-from typing import Final
-
-__TRACKS_FILE = os.path.join(os.path.dirname(__file__), "tracks.json")
-with open(__TRACKS_FILE, "r", encoding="utf8") as file:
-    TRACKS: Final[dict[str, dict[str, str]]] = json.load(file)

custom_components/oasis_mini/pyoasismini/tracks.json

@@ -1,827 +0,0 @@
-{
-  "131": {
-    "name": "A Star",
-    "author": "Oasis Mini",
-    "image": "2024/02/b90cbedf5982c44e2b88096e3f35f019.svg"
-  },
-  "358": {
-    "name": "Alligator",
-    "author": "Camila Veiga",
-    "image": "2024/05/83a5cb2f63a9103d9ea506cf762dee42.svg"
-  },
-  "114": {
-    "name": "Ant",
-    "author": "Camila Veiga",
-    "image": "2024/02/2c0494bff772e525b2888c869618b624.svg"
-  },
-  "306": {
-    "name": "arc flower",
-    "author": "mike",
-    "image": "2024/05/8341f09979ab20f6512d8fd88ba68b92.svg"
-  },
-  "251": {
-    "name": "Aries Ram",
-    "author": "Camila Veiga",
-    "image": "2024/05/02fea95ff2c9e1ef4636505a78517351.svg"
-  },
-  "246": {
-    "name": "Armadillo",
-    "author": "Oasis Mini",
-    "image": "2024/05/9715de0b402cd6ee7fbd3a8f44fb7404.svg"
-  },
-  "174": {
-    "name": "Baby Hummingbird",
-    "author": "Camila Veiga",
-    "image": "2024/02/5d982c39ad7d7613a6f43a2862fc4202.svg"
-  },
-  "359": {
-    "name": "BaldEagle",
-    "author": "Camila Veiga",
-    "image": "2024/05/db7781a68eaf312d15d773ed926f4719.svg"
-  },
-  "196": {
-    "name": "Bambi",
-    "author": "Camila Veiga",
-    "image": "2024/03/77c49931602941ff050c672257d2a4c4.svg"
-  },
-  "194": {
-    "name": "Bass",
-    "author": "Camila Veiga",
-    "image": "2024/03/58e1083634becb3e2e06ae294fd4abcd.svg"
-  },
-  "48": {
-    "name": "Beatle01",
-    "author": "Camila Veiga",
-    "image": "2024/02/6cb8369a92fcd78b7dfe67639f2568c2.svg"
-  },
-  "45": {
-    "name": "Beatle2",
-    "author": "Camila Veiga",
-    "image": "2024/02/34954cfa79d491552ec5d085d18662a8.svg"
-  },
-  "59": {
-    "name": "Beatle3",
-    "author": "Camila Veiga",
-    "image": "2024/02/d3c759d4407b4bd9dce4af2aa02fb309.svg"
-  },
-  "168": {
-    "name": "Betta Fish",
-    "author": "Oasis Mini",
-    "image": "2024/02/eda69bb71c0a146f59e3d7aa5af5d033.svg"
-  },
-  "102": {
-    "name": "Big Fish",
-    "author": "Camila Veiga",
-    "image": "2024/02/223d81730511500d47dc9ce386b54e76.svg"
-  },
-  "56": {
-    "name": "Branch",
-    "author": "Camila Veiga",
-    "image": "2024/02/93da7a9a8901a7ee2cbaf687c1d4f6bd.svg"
-  },
-  "133": {
-    "name": "Bubbles",
-    "author": "Oasis Mini",
-    "image": "2024/03/0c68af1243b823a829a83c2bced9462d.svg"
-  },
-  "349": {
-    "name": "Buddah",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/0e22fae64a02d4e7fe1f4ada6b1f707f.svg"
-  },
-  "257": {
-    "name": "Buddhist Tree",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/71c59b439b4a4f66527b045e22beacf3.svg"
-  },
-  "621": {
-    "name": "Bufallo",
-    "author": "Otávio Bittencourt",
-    "image": "2024/07/5fac3aff67796b4365593d38bb83dc1f.svg"
-  },
-  "157": {
-    "name": "Butterfly",
-    "author": "Oasis Mini",
-    "image": "2024/03/060b7c7aee2db3cc7bbf41d6f260c347.svg"
-  },
-  "58": {
-    "name": "Camalion",
-    "author": "Camila Veiga",
-    "image": "2024/02/f8b7ec53c2ca63f30baeacdda30659bd.svg"
-  },
-  "178": {
-    "name": "Cardinal Bird",
-    "author": "Camila Veiga",
-    "image": "2024/02/ba057fd71a816dd15565583cf63ee2ab.svg"
-  },
-  "215": {
-    "name": "Cardiod",
-    "author": null,
-    "image": "2024/03/a24da534ded92bfff8b604a630b76edd.svg"
-  },
-  "113": {
-    "name": "Cat Face",
-    "author": "Camila Veiga",
-    "image": "2024/02/d45a368206f87e077739e48ca73a89c6.svg"
-  },
-  "49": {
-    "name": "Clam",
-    "author": "Camila Veiga",
-    "image": "2024/02/25355aa8111a77ec41d1396df9123fcb.svg"
-  },
-  "505": {
-    "name": "Coarse Hilbert Wiper",
-    "author": "Xilufer",
-    "image": "2024/06/cb2ad632c8d1c2ca69fa9a8f544bc0c7.svg"
-  },
-  "118": {
-    "name": "Coarse Spiral In to Out",
-    "author": "Oasis Mini",
-    "image": "2024/02/64a1c80bbb9b5b690ee08ae11e9c0e89.svg"
-  },
-  "501": {
-    "name": "Coarse Spiral Out to In",
-    "author": "Xilufer",
-    "image": "2024/06/a46ab9145f30d81856ceec69ca4b8378.svg"
-  },
-  "503": {
-    "name": "Coarse Wipe Bottom to Top",
-    "author": "Xilufer",
-    "image": "2024/06/798a562ecda1f6ae80143ce3e69e97e2.svg"
-  },
-  "499": {
-    "name": "Coarse Wipe Left to Right",
-    "author": "Xilufer",
-    "image": "2024/06/335f1704e84153fa4e8334fc6e3ede6f.svg"
-  },
-  "504": {
-    "name": "Coarse Wipe Right to Left",
-    "author": "Xilufer",
-    "image": "2024/06/ed92b6cc7935a4c9f8a691e3308f9b49.svg"
-  },
-  "497": {
-    "name": "Coarse Wipe Top to Bottom",
-    "author": "Xilufer",
-    "image": "2024/06/053798917cd862f58adfc8b52310d377.svg"
-  },
-  "264": {
-    "name": "Crab",
-    "author": "Camila Veiga",
-    "image": "2024/05/e11995a5855afbfa05f89ce39ba65740.svg"
-  },
-  "220": {
-    "name": "Crane Mini",
-    "author": null,
-    "image": "2024/03/e2b3f344d6a1407d8dd5d06a2dd4d10f.svg"
-  },
-  "104": {
-    "name": "Cricket",
-    "author": "Camila Veiga",
-    "image": "2024/02/de8399defab8eed0f2e5de564e423c78.svg"
-  },
-  "98": {
-    "name": "Crocodile",
-    "author": "Camila Veiga",
-    "image": "2024/02/71b8b959f6f5320b0778f4c25a74f105.svg"
-  },
-  "68": {
-    "name": "Cupid",
-    "author": "Camila Veiga",
-    "image": "2024/02/8db157d5e68d132eb3766e5325936b3a.svg"
-  },
-  "261": {
-    "name": "Cute Cat",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/caf48ea93bc21a7391cf8aa16388f500.svg"
-  },
-  "393": {
-    "name": "dither_tri4",
-    "author": "B Perry",
-    "image": "2024/06/b15f38d3a4ae4f8418c769ca024bc646.svg"
-  },
-  "146": {
-    "name": "Dithermaster Gears",
-    "author": "Oasis Mini",
-    "image": "2024/02/92ed5ddc81f3152558a62b90f9ab99bd.svg"
-  },
-  "145": {
-    "name": "Dithermaster Nautilus",
-    "author": "Oasis Mini",
-    "image": "2024/02/d3e546f47a5e328320f95471e6d06e8e.svg"
-  },
-  "144": {
-    "name": "Dithermaster Sierpinski",
-    "author": "Oasis Mini",
-    "image": "2024/02/b873df4b7f29d81f9577b7f3d9adb649.svg"
-  },
-  "142": {
-    "name": "Dithermaster Sunburst",
-    "author": "Oasis Mini",
-    "image": "2024/02/560135854581fcf00007644641f317c0.svg"
-  },
-  "140": {
-    "name": "Dithermaster Wormhole",
-    "author": "Oasis Mini",
-    "image": "2024/02/011ba7387ca10787302da62a9ab39ce7.svg"
-  },
-  "41": {
-    "name": "Dog Beatle",
-    "author": "Camila Veiga",
-    "image": "2024/02/420d5b52f9c39fbec5d0301c8d1917b4.svg"
-  },
-  "36": {
-    "name": "Dog Golden Retriever",
-    "author": "Camila Veiga",
-    "image": "2024/02/a7419fb8058506cfc4b97a1ad44b08a1.svg"
-  },
-  "40": {
-    "name": "Dog Pug",
-    "author": "Oasis Mini",
-    "image": "2024/02/c2e232717568ca7fba7c835d94ff14f3.svg"
-  },
-  "162": {
-    "name": "Dolphin",
-    "author": "Oasis Mini",
-    "image": "2024/03/10a84a5fd019316a24e90535894db3fe.svg"
-  },
-  "244": {
-    "name": "Doodle Dog",
-    "author": "Camila Veiga",
-    "image": "2024/05/430de6550a4affc068160c9a4c88e226.svg"
-  },
-  "195": {
-    "name": "Dragon",
-    "author": "Camila Veiga",
-    "image": "2024/03/077c020cce5abf70d49fe040ddd5b209.svg"
-  },
-  "193": {
-    "name": "Duck",
-    "author": "Camila Veiga",
-    "image": "2024/03/22ca351799853f1452a6905a94942d4b.svg"
-  },
-  "159": {
-    "name": "Elephant",
-    "author": "Oasis Mini",
-    "image": "2024/03/48a449db2bbb530e5d54b54cb711ce9f.svg"
-  },
-  "129": {
-    "name": "Engine Turn",
-    "author": "Oasis Mini",
-    "image": "2024/02/7cb25ab3fbea0fc33a013e05bfc7b393.svg"
-  },
-  "219": {
-    "name": "Face",
-    "author": null,
-    "image": "2024/03/20039d6b829edcf6db73d19f9e923f2f.svg"
-  },
-  "33": {
-    "name": "Fibonacci Shell",
-    "author": "Camila Veiga",
-    "image": "2024/02/aaac5e59aab118064638e273ee2da27a.svg"
-  },
-  "262": {
-    "name": "Fish Koi",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/ce8f6c7d5e89dac56cb4296d86cd7261.svg"
-  },
-  "38": {
-    "name": "Flamingo",
-    "author": "Camila Veiga",
-    "image": "2024/02/cc1b007041fa87e28601c757887631fa.svg"
-  },
-  "249": {
-    "name": "Flower Voyage",
-    "author": "Camila Veiga",
-    "image": "2024/05/85f7a4290e6b45f76ff7653d77db3322.svg"
-  },
-  "87": {
-    "name": "Flowers",
-    "author": "Camila Veiga",
-    "image": "2024/02/f27ab7850ca572a4e83d9606a3528fb5.svg"
-  },
-  "241": {
-    "name": "French Bulldog",
-    "author": "Camila Veiga",
-    "image": "2024/05/0992b12affcc14cf541baff6b1368fd9.svg"
-  },
-  "60": {
-    "name": "Frog",
-    "author": "Camila Veiga",
-    "image": "2024/02/1d37a8cd59f9222670949681f607f454.svg"
-  },
-  "252": {
-    "name": "Furry Moth",
-    "author": "Camila Veiga",
-    "image": "2024/05/fec69cc408643e629247c56648df6dee.svg"
-  },
-  "88": {
-    "name": "Geometric Hummingbird",
-    "author": "Camila Veiga",
-    "image": "2024/02/f2ddf3bd2d74b7674832d7ace5e54992.svg"
-  },
-  "81": {
-    "name": "Geometric Wolf",
-    "author": "Camila Veiga",
-    "image": "2024/02/a8cc546c3d9dfd1ade921817299a626a.svg"
-  },
-  "332": {
-    "name": "Giant Octopus",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/862ce4ee7aaba8b3832d136a9909c15d.svg"
-  },
-  "224": {
-    "name": "Happy Easter",
-    "author": "Oasis Mini",
-    "image": "2024/03/c0dfc0175a06768d06ef4a8863ddb5c6.svg"
-  },
-  "581": {
-    "name": "Happy4th",
-    "author": "zach8644",
-    "image": "2024/07/21574747a7892b04931bdd5135175d04.svg"
-  },
-  "356": {
-    "name": "Hedgehog",
-    "author": "Camila Veiga",
-    "image": "2024/05/cabfd2aa2b691af8db0d95bdfe0fd32e.svg"
-  },
-  "147": {
-    "name": "Hilbert",
-    "author": "Oasis Mini",
-    "image": "2024/03/18d8fab24afbacae8743b154ede27ac0.svg"
-  },
-  "496": {
-    "name": "Hilbert Wiper",
-    "author": "Xilufer",
-    "image": "2024/06/3ed2bf50e3aabdbc4f5de7d81c46fdeb.svg"
-  },
-  "192": {
-    "name": "Hippo",
-    "author": "Camila Veiga",
-    "image": "2024/03/cef030f36e1d9ee172603ca2ebf52045.svg"
-  },
-  "213": {
-    "name": "Honeybee",
-    "author": null,
-    "image": "2024/03/916fa92c31245f887bf6842dc0abf087.svg"
-  },
-  "100": {
-    "name": "Hummingbird",
-    "author": "Camila Veiga",
-    "image": "2024/02/6df68af94360e823a2888925fc935da4.svg"
-  },
-  "304": {
-    "name": "Iguana",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/24a538188acf7ae153746aff00e35743.svg"
-  },
-  "72": {
-    "name": "Iguana",
-    "author": "Camila Veiga",
-    "image": "2024/02/6a9c6db932fc00eacdde436bfad6affd.svg"
-  },
-  "139": {
-    "name": "Intersection",
-    "author": "Oasis Mini",
-    "image": "2024/02/a8e3c5d676faa430c0d6818ebff8044c.svg"
-  },
-  "238": {
-    "name": "Jack Russell Terrier",
-    "author": "Camila Veiga",
-    "image": "2024/05/d000c4bb896280d455dd6ac53ed8aa48.svg"
-  },
-  "170": {
-    "name": "Jellyfish",
-    "author": "Oasis Mini",
-    "image": "2024/03/2be69280b76eef7323d8f107afb6d142.svg"
-  },
-  "189": {
-    "name": "Kakapo Parrot Bird",
-    "author": "Camila Veiga",
-    "image": "2024/02/3482a2aafe5facaafff2b83531910512.svg"
-  },
-  "239": {
-    "name": "Kobra",
-    "author": "Camila Veiga",
-    "image": "2024/05/af42684b3f1ad0cc1926d28f6add3dec.svg"
-  },
-  "240": {
-    "name": "Labrador Retriever",
-    "author": "Camila Veiga",
-    "image": "2024/05/9241d0be1d61fa2b37681cb5d90d15be.svg"
-  },
-  "173": {
-    "name": "Light Bulb",
-    "author": "Oasis Mini",
-    "image": "2024/03/431d42927eca6b93a33c520a495d621d.svg"
-  },
-  "121": {
-    "name": "Line Wiper",
-    "author": "Zach",
-    "image": "2024/02/b406f9245e23ded2e3a781ccc5e5ca1f.svg"
-  },
-  "385": {
-    "name": "Lion",
-    "author": "Otávio Bittencourt",
-    "image": "2024/06/56ace3527391978ce17b65fc14f69ed3.svg"
-  },
-  "300": {
-    "name": "Little Heart",
-    "author": "Evan",
-    "image": "2024/05/8c68933d4b7e07ad9dc3496f7b82f106.svg"
-  },
-  "177": {
-    "name": "Lone Blue Jay Bird",
-    "author": "Camila Veiga",
-    "image": "2024/02/4c5b69c5fe436c8cbb5df697202dcaa5.svg"
-  },
-  "250": {
-    "name": "Long Tail Moth",
-    "author": "Camila Veiga",
-    "image": "2024/05/23c032dfc886d10c43b60fee7d1a5c92.svg"
-  },
-  "128": {
-    "name": "Loops",
-    "author": "Oasis Mini",
-    "image": "2024/02/5527235b74c3f9327728caddf73eda5b.svg"
-  },
-  "188": {
-    "name": "Macaw",
-    "author": "Camila Veiga",
-    "image": "2024/02/f36f92f355cbfc0bd1cfc779ec64d8fb.svg"
-  },
-  "64": {
-    "name": "Mandala",
-    "author": "Camila Veiga",
-    "image": "2024/02/21eb184da4fe1eeefdd7c220f209d3f1.svg"
-  },
-  "339": {
-    "name": "Marmoset Monkey",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/344128d7d7e468db26af2f04b2d7d088.svg"
-  },
-  "212": {
-    "name": "Medusa",
-    "author": null,
-    "image": "2024/03/5b8954e0d62998cdfd9fccbc8b63173e.svg"
-  },
-  "78": {
-    "name": "Mini Bouquet",
-    "author": "Camila Veiga",
-    "image": "2024/02/42a10229d228504945cde2dcab34e145.svg"
-  },
-  "179": {
-    "name": "Monkey",
-    "author": "Camila Veiga",
-    "image": "2024/02/8f3b78fecee6f47ea568c6a580a9a2fc.svg"
-  },
-  "155": {
-    "name": "Monstera",
-    "author": "Oasis Mini",
-    "image": "2024/02/c2b76034445415a1327cafe24781a2a8.svg"
-  },
-  "202": {
-    "name": "Moth",
-    "author": "Camila Veiga",
-    "image": "2024/03/374e12126f1618ee960b44a23c3229ca.svg"
-  },
-  "63": {
-    "name": "Mushroom",
-    "author": "Camila Veiga",
-    "image": "2024/02/63f18a5f611c9b798178110c885b7b7b.svg"
-  },
-  "101": {
-    "name": "Mushroom Forest",
-    "author": "Camila Veiga",
-    "image": "2024/02/df973d6848a4173b54ac6666847798d1.svg"
-  },
-  "138": {
-    "name": "Noise Curves",
-    "author": "Oasis Mini",
-    "image": "2024/03/24583f60b82a4198db5ba5c922aaa9da.svg"
-  },
-  "150": {
-    "name": "Noise Waves",
-    "author": "Oasis Mini",
-    "image": "2024/03/ef39021e727be220dab8962ff9077aca.svg"
-  },
-  "171": {
-    "name": "Octopus",
-    "author": "Camila Veiga",
-    "image": "2024/03/761741f1eabae8b3183e48e3a367fcfe.svg"
-  },
-  "431": {
-    "name": "Otter",
-    "author": "Otávio Bittencourt",
-    "image": "2024/06/af229556334619038aa62f913e36d455.svg"
-  },
-  "37": {
-    "name": "Owl",
-    "author": "Camila Veiga",
-    "image": "2024/02/eb45cee22c24225da3a79abf6f907765.svg"
-  },
-  "221": {
-    "name": "Pattern 3",
-    "author": null,
-    "image": "2024/03/419f74b031a6ea0cfd794985bb983960.svg"
-  },
-  "350": {
-    "name": "Pelican",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/678ca8eed19618dade7d4ed00e3ebdd9.svg"
-  },
-  "24": {
-    "name": "Penguin",
-    "author": "Camila Veiga",
-    "image": "2024/03/f3a718de2ff3fd37148fd16967113f87.svg"
-  },
-  "137": {
-    "name": "Pinwheel",
-    "author": "Oasis Mini",
-    "image": "2024/02/554b6e96961ce9c9459eaf9826c09c9a.svg"
-  },
-  "243": {
-    "name": "Pitbull",
-    "author": "Camila Veiga",
-    "image": "2024/05/6aa2e109b8f3eb068288bdbf652297a3.svg"
-  },
-  "103": {
-    "name": "Rabbit",
-    "author": "Camila Veiga",
-    "image": "2024/02/409d178f619d5b1dad43f34c380a8768.svg"
-  },
-  "211": {
-    "name": "Rabbit",
-    "author": null,
-    "image": "2024/03/7501a028530482e89bb726e425a6a8cb.svg"
-  },
-  "210": {
-    "name": "Rocket",
-    "author": null,
-    "image": "2024/03/7a60d9b004f546948fde90489e19f22a.svg"
-  },
-  "105": {
-    "name": "Rooster",
-    "author": "Camila Veiga",
-    "image": "2024/02/458f026c21efdaf85dd9483515c793ff.svg"
-  },
-  "156": {
-    "name": "Rose",
-    "author": "Oasis Mini",
-    "image": "2024/03/8a5ff9792afe8da301350dee4a8e4278.svg"
-  },
-  "123": {
-    "name": "Sawtooth",
-    "author": "Oasis Mini",
-    "image": "2024/02/4fe77ed20684244e6c83784f199c752e.svg"
-  },
-  "197": {
-    "name": "Scorpion",
-    "author": "Camila Veiga",
-    "image": "2024/03/d3e71b4963a7d61d55be2760482890aa.svg"
-  },
-  "345": {
-    "name": "Sea Horse",
-    "author": "Otávio Bittencourt",
-    "image": "2024/05/6de639607e4bbdca8f8ecb57c402cd6e.svg"
-  },
-  "172": {
-    "name": "Seahorse",
-    "author": "Oasis Mini",
-    "image": "2024/03/2283d765860cddd72025a150921dd6ce.svg"
-  },
-  "190": {
-    "name": "Seahorse",
-    "author": "Camila Veiga",
-    "image": "2024/03/c3ec7121261a3f75ff56630b672136fe.svg"
-  },
-  "357": {
-    "name": "Seal",
-    "author": "Camila Veiga",
-    "image": "2024/05/4833cf1cfbfc79ef6195bd2e1c006059.svg"
-  },
-  "390": {
-    "name": "Sheep",
-    "author": "Otávio Bittencourt",
-    "image": "2024/06/31e46f5f5997e742394892849eda505a.svg"
-  },
-  "136": {
-    "name": "Shield",
-    "author": "Oasis Mini",
-    "image": "2024/02/6f0952def38040c7a48bc56c7c44bf67.svg"
-  },
-  "203": {
-    "name": "Shimeji",
-    "author": "Camila Veiga",
-    "image": "2024/03/9873bcedd0b8f0560d8619fdddf42090.svg"
-  },
-  "149": {
-    "name": "Sierpenski",
-    "author": "Oasis Mini",
-    "image": "2024/03/27205730092d3b5c866bd53b9d26be97.svg"
-  },
-  "209": {
-    "name": "Skull",
-    "author": null,
-    "image": "2024/03/374f2efbfed6e4ab91137dbc6068e446.svg"
-  },
-  "158": {
-    "name": "Slightly Frightening Panda",
-    "author": "Oasis Mini",
-    "image": "2024/03/6877ff4d26904605066f246f31ed3cea.svg"
-  },
-  "180": {
-    "name": "Slot",
-    "author": "Camila Veiga",
-    "image": "2024/02/d4999457ab2769ddaef2c75736adab3a.svg"
-  },
-  "266": {
-    "name": "Snail",
-    "author": "Camila Veiga",
-    "image": "2024/05/6dd0ce7a83776d0a275d4bfcdc37d53f.svg"
-  },
-  "160": {
-    "name": "Spaceman",
-    "author": "Oasis Mini",
-    "image": "2024/03/b3d10e661d26c0bd7f8cc3ecee3b0ace.svg"
-  },
-  "125": {
-    "name": "Spiral Gyrations",
-    "author": "Oasis Mini",
-    "image": "2024/02/bfe3669fb18b99ba153bb07c2ea1d223.svg"
-  },
-  "119": {
-    "name": "Spiral In to Out",
-    "author": "Oasis Mini",
-    "image": "2024/02/f52427297697620a11131d037078fa2e.svg"
-  },
-  "117": {
-    "name": "Spiral Out to In",
-    "author": "Oasis Mini",
-    "image": "2024/03/4402aad108bb2a5c100b9f150ea3d97b.svg"
-  },
-  "20": {
-    "name": "SpiralizedWeb",
-    "author": "Zach",
-    "image": "2024/02/99e4863256d8ffb5f3b5239f19e2270b.svg"
-  },
-  "126": {
-    "name": "Spun Web",
-    "author": "Zach",
-    "image": "2024/02/99e4863256d8ffb5f3b5239f19e2270b.svg"
-  },
-  "267": {
-    "name": "Squid",
-    "author": "Camila Veiga",
-    "image": "2024/05/948f8d6eb814ce3a21e5a76ed90b3ea4.svg"
-  },
-  "175": {
-    "name": "Squirrel",
-    "author": "Camila Veiga",
-    "image": "2024/05/57981d2262e861b1b36ee842cff8b0d8.svg"
-  },
-  "265": {
-    "name": "Starfish",
-    "author": "Camila Veiga",
-    "image": "2024/05/a05aa52a44f34da15ddb1f5a3009fc1d.svg"
-  },
-  "115": {
-    "name": "String ray",
-    "author": "Camila Veiga",
-    "image": "2024/02/ca0d18b5213d4a18e0fabe76d4170247.svg"
-  },
-  "245": {
-    "name": "Sunflower",
-    "author": "Camila Veiga",
-    "image": "2024/05/bf6e4b6d739226139ced981ba9e38f60.svg"
-  },
-  "208": {
-    "name": "Swallow",
-    "author": null,
-    "image": "2024/03/026f52b5e539f1dd14215c751923024e.svg"
-  },
-  "370": {
-    "name": "Swirl",
-    "author": "Matt",
-    "image": "2024/05/156a6da37221c44878cd3c155f1d6918.svg"
-  },
-  "161": {
-    "name": "T-Rex",
-    "author": "Oasis Mini",
-    "image": "2024/03/3829ea91a3af828e7046f473707b0627.svg"
-  },
-  "455": {
-    "name": "Teste",
-    "author": "Otávio Bittencourt",
-    "image": "2024/06/ecd77e23fe859ba8e7e8c6a6ecfc9b8e.svg"
-  },
-  "223": {
-    "name": "The Knot",
-    "author": null,
-    "image": "2024/03/63013ee4146acb3af028949f98944bd9.svg"
-  },
-  "308": {
-    "name": "The Noise",
-    "author": "Matt",
-    "image": "2024/05/765c11e5dda140b236075b912731f69f.svg"
-  },
-  "483": {
-    "name": "Tiger",
-    "author": "Otávio Bittencourt",
-    "image": "2024/06/1bfb7dcda755b2d98ee85b83748d095b.svg"
-  },
-  "237": {
-    "name": "Toy Poodle",
-    "author": "Camila Veiga",
-    "image": "2024/05/9f559796eac7691049af8dadda742ad8.svg"
-  },
-  "130": {
-    "name": "Tri-Circle",
-    "author": "Oasis Mini",
-    "image": "2024/02/0a41c8694c1cd6559baafd82963286f6.svg"
-  },
-  "135": {
-    "name": "Triforce",
-    "author": "Oasis Mini",
-    "image": "2024/02/fefeea07184b4597243ba7b2dd2711fa.svg"
-  },
-  "247": {
-    "name": "Tropical Frog",
-    "author": "Oasis Mini",
-    "image": "2024/05/24f51e96925b83d64c8f63bd6c1b36b4.svg"
-  },
-  "242": {
-    "name": "Tropical Monkey texture",
-    "author": "Camila Veiga",
-    "image": "2024/05/6358af0a11dfa985f61bd9a7dec90fd3.svg"
-  },
-  "248": {
-    "name": "Tropical Snake",
-    "author": "Camila Veiga",
-    "image": "2024/05/d5bf2ba5d6417196d106b4da756035a1.svg"
-  },
-  "54": {
-    "name": "Tucan",
-    "author": "Camila Veiga",
-    "image": "2024/02/699dd2fff292f1104f8dbdf60f187043.svg"
-  },
-  "176": {
-    "name": "Tulips",
-    "author": "Camila Veiga",
-    "image": "2024/02/876563c5bafafee7e31c7ed96a846e00.svg"
-  },
-  "120": {
-    "name": "Turtle",
-    "author": "Junior Veloso",
-    "image": "2024/02/0dde4cf30929697c9d9145145771db31.svg"
-  },
-  "218": {
-    "name": "Unicorn",
-    "author": null,
-    "image": "2024/03/ed353a6e18917d9c2df0e4278e59b01d.svg"
-  },
-  "124": {
-    "name": "Warped Reuleaux",
-    "author": "Oasis Mini",
-    "image": "2024/02/a2aa2e71910c96680f78b65b81201b61.svg"
-  },
-  "127": {
-    "name": "Warped Squares",
-    "author": "Oasis Mini",
-    "image": "2024/02/8042b0f37b0cb37c739ac64e754ab774.svg"
-  },
-  "169": {
-    "name": "Whale",
-    "author": "Oasis Mini",
-    "image": "2024/03/283e1c9b6ee397a7822c58af01fcbbc3.svg"
-  },
-  "287": {
-    "name": "Windmill",
-    "author": "Matt",
-    "image": "2024/05/bcad3d06339ec7a345420191b7201ce1.svg"
-  },
-  "500": {
-    "name": "Wipe Left to Right",
-    "author": "Xilufer",
-    "image": "2024/06/3bdc415360a6466cf6245527bf85bd29.svg"
-  },
-  "498": {
-    "name": "Wipe Top to Bottom",
-    "author": "Xilufer",
-    "image": "2024/06/56b0cb09f15b44bac418ee2d1ed1940e.svg"
-  },
-  "77": {
-    "name": "Wolf head",
-    "author": "Camila Veiga",
-    "image": "2024/02/0c35befdb13ab7702f4c3b71371bf75c.svg"
-  },
-  "360": {
-    "name": "Woodpecker",
-    "author": "Camila Veiga",
-    "image": "2024/05/95ea026589751d7fca381f2c3df9380d.svg"
-  },
-  "437": {
-    "name": "Yorkshire",
-    "author": "Otávio Bittencourt",
-    "image": "2024/06/be59f584c87cfff3aa13e5887a69e183.svg"
-  }
-}

custom_components/oasis_mini/select.py

@@ -1,62 +1,162 @@
-"""Oasis Mini select entity."""
+"""Oasis device select entity."""
 
 from __future__ import annotations
 
-from typing import Any
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
 
 from homeassistant.components.select import SelectEntity, SelectEntityDescription
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.entity import EntityDescription
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini.const import TRACKS
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+from .pyoasiscontrol import OasisDevice
+from .pyoasiscontrol.const import AUTOPLAY_MAP, TRACKS
+
+AUTOPLAY_MAP_LIST = list(AUTOPLAY_MAP)
 
 
-class OasisMiniSelectEntity(OasisMiniEntity, SelectEntity):
-    """Oasis Mini select entity."""
-
-    def __init__(
-        self,
-        coordinator: OasisMiniCoordinator,
-        entry: ConfigEntry[Any],
-        description: EntityDescription,
-    ) -> None:
-        """Construct an Oasis Mini select entity."""
-        super().__init__(coordinator, entry, description)
-        self._attr_options = [
-            TRACKS.get(str(track), {}).get("name", str(track))
-            for track in self.device.playlist
-        ]
-
-    @property
-    def current_option(self) -> str:
-        """Return the selected entity option to represent the entity state."""
-        return self.options[self.device.playlist_index]
-
-    async def async_select_option(self, option: str) -> None:
-        """Change the selected option."""
-        await self.device.async_change_track(self.options.index(option))
-        await self.coordinator.async_request_refresh()
-
-    def _handle_coordinator_update(self) -> None:
-        """Handle updated data from the coordinator."""
-        self._attr_options = [
-            TRACKS.get(str(track), {}).get("name", str(track))
-            for track in self.device.playlist
-        ]
-        return super()._handle_coordinator_update()
+def playlists_update_handler(entity: OasisDeviceSelectEntity) -> None:
+    """Handle playlists updates."""
+    # pylint: disable=protected-access
+    device = entity.device
+    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
 
 
-DESCRIPTOR = SelectEntityDescription(key="playlist", name="Playlist")
+def queue_update_handler(entity: OasisDeviceSelectEntity) -> None:
+    """Handle queue updates."""
+    # pylint: disable=protected-access
+    device = entity.device
+    counts = defaultdict(int)
+    options = []
+    for track in device.playlist:
+        name = device.playlist_details.get(track, {}).get(
+            "name",
+            TRACKS.get(track, {"id": track, "name": f"Unknown Title (#{track})"}).get(
+                "name",
+                device.track["name"]
+                if device.track and device.track["id"] == track
+                else str(track),
+            ),
+        )
+        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
 
 
 async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis Mini select using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    async_add_entities([OasisMiniSelectEntity(coordinator, entry, DESCRIPTOR)])
+    """Set up Oasis device select using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    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)
+class OasisDeviceSelectEntityDescription(SelectEntityDescription):
+    """Oasis device select entity description."""
+
+    current_value: Callable[[OasisDevice], Any]
+    select_fn: Callable[[OasisDevice, int], Awaitable[None]]
+    update_handler: Callable[[OasisDeviceSelectEntity], None] | None = None
+
+
+DESCRIPTORS = (
+    OasisDeviceSelectEntityDescription(
+        key="autoplay",
+        translation_key="autoplay",
+        options=AUTOPLAY_MAP_LIST,
+        current_value=lambda device: str(device.autoplay),
+        select_fn=lambda device, index: (
+            device.async_set_autoplay(AUTOPLAY_MAP_LIST[index])
+        ),
+    ),
+    OasisDeviceSelectEntityDescription(
+        key="queue",
+        translation_key="queue",
+        current_value=lambda device: (device.playlist.copy(), device.playlist_index),
+        select_fn=lambda device, index: device.async_change_track(index),
+        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):
+    """Oasis device select entity."""
+
+    entity_description: OasisDeviceSelectEntityDescription
+    _current_value: Any | None = None
+
+    def __init__(
+        self,
+        coordinator: OasisDeviceCoordinator,
+        device: OasisDevice,
+        description: EntityDescription,
+    ) -> None:
+        """Construct an Oasis device select entity."""
+        super().__init__(coordinator, device, description)
+        self._handle_coordinator_update()
+
+    async def async_select_option(self, option: str) -> None:
+        """Change the selected option."""
+        await self.entity_description.select_fn(self.device, self.options.index(option))
+
+    @callback
+    def _handle_coordinator_update(self) -> None:
+        """Handle updated data from the coordinator."""
+        new_value = self.entity_description.current_value(self.device)
+        if self._current_value == new_value:
+            return
+        self._current_value = new_value
+        if update_handler := self.entity_description.update_handler:
+            update_handler(self)
+        else:
+            self._attr_current_option = str(
+                getattr(self.device, self.entity_description.key)
+            )
+        if self.hass:
+            return super()._handle_coordinator_update()

custom_components/oasis_mini/sensor.py

@@ -1,4 +1,4 @@
-"""Oasis Mini sensor entity."""
+"""Oasis device sensor entity."""
 
 from __future__ import annotations
 
@@ -7,56 +7,69 @@ from homeassistant.components.sensor import (
     SensorEntityDescription,
     SensorStateClass,
 )
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import EntityCategory
+from homeassistant.const import PERCENTAGE, EntityCategory
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
 
 
 async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis Mini sensors using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    async_add_entities(
-        [
-            OasisMiniSensorEntity(coordinator, entry, descriptor)
+    """Set up Oasis device sensors using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    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 = {
     SensorEntityDescription(
         key="download_progress",
+        translation_key="download_progress",
         entity_category=EntityCategory.DIAGNOSTIC,
         entity_registry_enabled_default=False,
-        name="Download progress",
-        state_class=SensorStateClass.TOTAL_INCREASING,
+        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")
+    # 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 OasisMiniSensorEntity(OasisMiniEntity, SensorEntity):
-    """Oasis Mini sensor entity."""
+
+class OasisDeviceSensorEntity(OasisDeviceEntity, SensorEntity):
+    """Oasis device sensor entity."""
 
     @property
     def native_value(self) -> str | None:

custom_components/oasis_mini/strings.json

@@ -3,33 +3,35 @@
     "step": {
       "user": {
         "data": {
-          "host": "[%key:common::config_flow::data::host%]"
+          "email": "[%key:common::config_flow::data::email%]",
+          "password": "[%key:common::config_flow::data::password%]"
         }
       },
       "reconfigure": {
         "data": {
-          "host": "[%key:common::config_flow::data::host%]"
+          "email": "[%key:common::config_flow::data::email%]",
+          "password": "[%key:common::config_flow::data::password%]"
         }
-      },
-      "reauth_confirm": {
-        "data": {}
       }
     },
     "error": {
       "cannot_connect": "[%key:common::config_flow::error::cannot_connect%]",
+      "invalid_auth": "[%key:common::config_flow::error::invalid_auth%]",
       "invalid_host": "[%key:common::config_flow::error::invalid_host%]",
       "timeout_connect": "[%key:common::config_flow::error::timeout_connect%]",
       "unknown": "[%key:common::config_flow::error::unknown%]"
     },
     "abort": {
-      "already_configured": "[%key:common::config_flow::abort::already_configured_device%]",
+      "already_configured": "[%key:common::config_flow::abort::already_configured_account%]",
       "reauth_successful": "[%key:common::config_flow::abort::reauth_successful%]",
-      "reconfigure_successful": "[%key:common::config_flow::abort::reconfigure_successful%]"
+      "reconfigure_successful": "[%key:common::config_flow::abort::reconfigure_successful%]",
+      "wrong_account": "Account used for the integration should not change"
     }
   },
   "options": {
     "step": {
       "init": {
+        "description": "Add your cloud credentials to get additional information about your device",
         "data": {
           "email": "[%key:common::config_flow::data::email%]",
           "password": "[%key:common::config_flow::data::password%]"
@@ -39,5 +41,120 @@
     "error": {
       "invalid_auth": "[%key:common::config_flow::error::invalid_auth%]"
     }
+  },
+  "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",
+        "state": {
+          "0": "on",
+          "1": "off",
+          "2": "5 minutes",
+          "3": "10 minutes",
+          "4": "30 minutes",
+          "6": "1 hour",
+          "7": "6 hours",
+          "8": "12 hours",
+          "5": "24 hours"
+        }
+      },
+      "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": {
+          "booting": "Booting",
+          "stopped": "Stopped",
+          "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/switch.py

@@ -1,64 +1,53 @@
-"""Oasis Mini switch entity."""
+# """Oasis Mini switch entity."""
 
-from __future__ import annotations
+# from __future__ import annotations
 
-from typing import Any
+# from typing import Any
 
-from homeassistant.components.switch import SwitchEntity, SwitchEntityDescription
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
+# from homeassistant.components.switch import SwitchEntity, SwitchEntityDescription
+# from homeassistant.core import HomeAssistant
+# from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from .const import DOMAIN
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
+# from . import OasisMiniConfigEntry
+# from .entity import OasisMiniEntity
 
 
-class OasisMiniSwitchEntity(OasisMiniEntity, SwitchEntity):
-    """Oasis Mini switch entity."""
-
-    @property
-    def is_on(self) -> bool:
-        """Return True if entity is on."""
-        return int(getattr(self.device, self.entity_description.key))
-
-    async def async_turn_off(self, **kwargs: Any) -> None:
-        """Turn the entity off."""
-        if self.entity_description.key == "pause_between_tracks":
-            await self.device.async_set_pause_between_tracks(False)
-        elif self.entity_description.key == "repeat_playlist":
-            await self.device.async_set_repeat_playlist(False)
-        await self.coordinator.async_request_refresh()
-
-    async def async_turn_on(self, **kwargs: Any) -> None:
-        """Turn the entity on."""
-        if self.entity_description.key == "pause_between_tracks":
-            await self.device.async_set_pause_between_tracks(True)
-        elif self.entity_description.key == "repeat_playlist":
-            await self.device.async_set_repeat_playlist(True)
-        await self.coordinator.async_request_refresh()
+# async def async_setup_entry(
+#     hass: HomeAssistant,
+#     entry: OasisMiniConfigEntry,
+#     async_add_entities: AddEntitiesCallback,
+# ) -> None:
+#     """Set up Oasis Mini switchs using config entry."""
+#     async_add_entities(
+#         [
+#             OasisMiniSwitchEntity(entry.runtime_data, descriptor)
+#             for descriptor in DESCRIPTORS
+#         ]
+#     )
 
 
-DESCRIPTORS = {
-    SwitchEntityDescription(
-        key="pause_between_tracks",
-        name="Pause between tracks",
-    ),
+# class OasisMiniSwitchEntity(OasisMiniEntity, SwitchEntity):
+#     """Oasis Mini switch entity."""
+
+#     @property
+#     def is_on(self) -> bool:
+#         """Return True if entity is on."""
+#         return int(getattr(self.device, self.entity_description.key))
+
+#     async def async_turn_off(self, **kwargs: Any) -> None:
+#         """Turn the entity off."""
+#         await self.device.async_set_repeat_playlist(False)
+#         await self.coordinator.async_request_refresh()
+
+#     async def async_turn_on(self, **kwargs: Any) -> None:
+#         """Turn the entity on."""
+#         await self.device.async_set_repeat_playlist(True)
+#         await self.coordinator.async_request_refresh()
+
+
+# DESCRIPTORS = {
 #     SwitchEntityDescription(
 #         key="repeat_playlist",
 #         name="Repeat playlist",
 #     ),
-}
-
-
-async def async_setup_entry(
-    hass: HomeAssistant, entry: ConfigEntry, async_add_entities: AddEntitiesCallback
-) -> None:
-    """Set up Oasis Mini switchs using config entry."""
-    coordinator: OasisMiniCoordinator = hass.data[DOMAIN][entry.entry_id]
-    async_add_entities(
-        [
-            OasisMiniSwitchEntity(coordinator, entry, descriptor)
-            for descriptor in DESCRIPTORS
-        ]
-    )
+# }

custom_components/oasis_mini/translations/en.json

@@ -3,33 +3,35 @@
     "step": {
       "user": {
         "data": {
-          "host": "Host"
+          "email": "Email",
+          "password": "Password"
         }
       },
       "reconfigure": {
         "data": {
-          "host": "Host"
+          "email": "Email",
+          "password": "Password"
         }
-      },
-      "reauth_confirm": {
-        "data": {}
       }
     },
     "error": {
       "cannot_connect": "Failed to connect",
+      "invalid_auth": "Invalid authentication",
       "invalid_host": "Invalid hostname or IP address",
       "timeout_connect": "Timeout establishing connection",
       "unknown": "Unexpected error"
     },
     "abort": {
-      "already_configured": "Device is already configured",
+      "already_configured": "Account is already configured",
       "reauth_successful": "Re-authentication was successful",
-      "reconfigure_successful": "Re-configuration was successful"
+      "reconfigure_successful": "Re-configuration was successful",
+      "wrong_account": "Account used for the integration should not change"
     }
   },
   "options": {
     "step": {
       "init": {
+        "description": "Add your cloud credentials to get additional information about your device",
         "data": {
           "email": "Email",
           "password": "Password"
@@ -39,5 +41,120 @@
     "error": {
       "invalid_auth": "Invalid authentication"
     }
+  },
+  "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",
+        "state": {
+          "0": "on",
+          "1": "off",
+          "2": "5 minutes",
+          "3": "10 minutes",
+          "4": "30 minutes",
+          "6": "1 hour",
+          "7": "6 hours",
+          "8": "12 hours",
+          "5": "24 hours"
+        }
+      },
+      "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": {
+          "booting": "Booting",
+          "stopped": "Stopped",
+          "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/update.py

@@ -0,0 +1,86 @@
+"""Oasis device update entity."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+import logging
+from typing import Any
+
+from homeassistant.components.update import (
+    UpdateDeviceClass,
+    UpdateEntity,
+    UpdateEntityDescription,
+    UpdateEntityFeature,
+)
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+
+_LOGGER = logging.getLogger(__name__)
+
+SCAN_INTERVAL = timedelta(hours=6)
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """Set up Oasis device updates using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
+    entities = (
+        OasisDeviceUpdateEntity(coordinator, device, DESCRIPTOR)
+        for device in coordinator.data
+    )
+    async_add_entities(entities, True)
+
+
+DESCRIPTOR = UpdateEntityDescription(
+    key="software", device_class=UpdateDeviceClass.FIRMWARE
+)
+
+
+class OasisDeviceUpdateEntity(OasisDeviceEntity, UpdateEntity):
+    """Oasis device update entity."""
+
+    _attr_supported_features = (
+        UpdateEntityFeature.INSTALL | UpdateEntityFeature.PROGRESS
+    )
+
+    @property
+    def in_progress(self) -> bool | int:
+        """Update installation progress."""
+        if self.device.status_code == 11:
+            return self.device.download_progress
+        return False
+
+    @property
+    def installed_version(self) -> str:
+        """Version installed and in use."""
+        return self.device.software_version
+
+    @property
+    def should_poll(self) -> bool:
+        """Set polling to True."""
+        return True
+
+    async def async_install(
+        self, version: str | None, backup: bool, **kwargs: Any
+    ) -> None:
+        """Install an update."""
+        if self.latest_version == self.device.software_version:
+            return
+        await self.device.async_upgrade()
+
+    async def async_update(self) -> None:
+        """Update the entity."""
+        client = self.coordinator.cloud_client
+        if not (software := await client.async_get_latest_software_details()):
+            _LOGGER.warning("Unable to get latest software details")
+            return
+        self._attr_latest_version = software["version"]
+        self._attr_release_summary = software["description"]
+        self._attr_release_url = f"https://app.grounded.so/software/{software['id']}"

hacs.json

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

requirements.txt

@@ -1,13 +1,15 @@
 # Home Assistant
-homeassistant>=2024.4
-home-assistant-frontend
+homeassistant>=2025.1
 numpy
 PyTurboJPEG
 
 # Integration
-aiohttp
+aiohttp # should already be installed with Home Assistant
+aiomqtt # asyncio MQTT client
+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

@@ -0,0 +1,74 @@
+"""Script to update track details from Grounded Labs."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from typing import Any
+
+from custom_components.oasis_mini.pyoasiscontrol import OasisCloudClient
+from custom_components.oasis_mini.pyoasiscontrol.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 "Kinetic Oasis"
+
+
+async def update_tracks() -> None:
+    """Update tracks."""
+    client = OasisCloudClient(access_token=ACCESS_TOKEN)
+
+    try:
+        data = await client.async_get_tracks()
+    except Exception as ex:
+        print(type(ex).__name__, ex)
+        await client.session.close()
+        return
+
+    if not isinstance(data, list):
+        print("Unexpected result:", data)
+        return
+
+    updated_tracks: dict[int, dict[str, Any]] = {}
+    for result in filter(lambda d: d["public"], data):
+        if (
+            (track_id := result["id"]) not in TRACKS
+            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']}")
+            track_info = await client.async_get_track_info(int(track_id))
+            if not track_info:
+                print("No track info")
+                break
+            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:
+        print("No updated tracks")
+        return
+
+    tracks = {k: v for k, v in TRACKS.items() if k in map(lambda d: d["id"], data)}
+    tracks.update(updated_tracks)
+    tracks = dict(sorted(tracks.items(), key=lambda t: t[1]["name"].lower()))
+
+    with open(
+        "custom_components/oasis_mini/pyoasiscontrol/tracks.json", "w", encoding="utf8"
+    ) as file:
+        json.dump(tracks, file, indent=2, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    asyncio.run(update_tracks())