Switch to using mqtt

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/workflows/update-tracks.yml

@@ -1,10 +1,14 @@
 name: Update tracks
+
 on:
   schedule:
-    - cron: "0 19 * * *"
+    - cron: "0 19 * * 1"
+  workflow_dispatch: {}
+
 permissions:
   contents: write
   pull-requests: write
+
 jobs:
   tracks:
     name: Search and update new tracks
@@ -12,16 +16,20 @@ jobs:
     steps:
       - name: Checkout the repo
         uses: actions/checkout@v4
-      - name: Set up Python 3.12
+
+      - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
+
       - name: Install dependencies
         run: pip install homeassistant
+
       - name: Update tracks
         env:
           GROUNDED_TOKEN: ${{ secrets.GROUNDED_TOKEN }}
         run: python update_tracks.py
+
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v6
         with:

.pre-commit-config.yaml

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

README.md

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

config/configuration.yaml

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

custom_components/oasis_mini/__init__.py

@@ -1,24 +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 ConfigEntryError, ConfigEntryNotReady
-import homeassistant.helpers.device_registry as dr
+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 OasisMiniConfigEntry = ConfigEntry[OasisMiniCoordinator]
+type OasisDeviceConfigEntry = ConfigEntry[OasisDeviceCoordinator]
 
 _LOGGER = logging.getLogger(__name__)
 
 PLATFORMS = [
+    Platform.BINARY_SENSOR,
     Platform.BUTTON,
     Platform.IMAGE,
     Platform.LIGHT,
@@ -26,65 +28,121 @@ PLATFORMS = [
     Platform.NUMBER,
     Platform.SELECT,
     Platform.SENSOR,
-    # Platform.SWITCH,
     Platform.UPDATE,
 ]
 
 
-async def async_setup_entry(hass: HomeAssistant, entry: OasisMiniConfigEntry) -> bool:
-    """Set up Oasis Mini from a config entry."""
-    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 entry.unique_id:
-        if not (serial_number := coordinator.device.serial_number):
-            dev_reg = dr.async_get(hass)
-            devices = dr.async_entries_for_config_entry(dev_reg, entry.entry_id)
-            serial_number = next(
-                (
-                    identifier[1]
-                    for identifier in devices[0].identifiers
-                    if identifier[0] == DOMAIN
-                ),
-                None,
-            )
-        hass.config_entries.async_update_entry(entry, unique_id=serial_number)
+    if entry.unique_id != (user_id := str(user["id"])):
+        hass.config_entries.async_update_entry(entry, unique_id=user_id)
 
     if not coordinator.data:
-        await client.session.close()
-        raise ConfigEntryNotReady
-
-    if entry.unique_id != coordinator.device.serial_number:
-        await client.session.close()
-        raise ConfigEntryError("Serial number mismatch")
+        _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: OasisMiniConfigEntry) -> bool:
+async def async_unload_entry(
+    hass: HomeAssistant, entry: OasisDeviceConfigEntry
+) -> bool:
     """Unload a config entry."""
-    await entry.runtime_data.device.session.close()
+    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: OasisMiniConfigEntry) -> 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: OasisMiniConfigEntry) -> 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
 
@@ -15,59 +15,65 @@ from homeassistant.const import EntityCategory
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from . import OasisMiniConfigEntry
-from .entity import OasisMiniEntity
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
 from .helpers import add_and_play_track
-from .pyoasismini import OasisMini
-from .pyoasismini.const import TRACKS
+from .pyoasiscontrol import OasisDevice
+from .pyoasiscontrol.const import TRACKS
 
 
 async def async_setup_entry(
     hass: HomeAssistant,
-    entry: OasisMiniConfigEntry,
+    entry: OasisDeviceConfigEntry,
     async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis Mini button using config entry."""
+    """Set up Oasis device button using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
     async_add_entities(
-        [
-            OasisMiniButtonEntity(entry.runtime_data, descriptor)
-            for descriptor in DESCRIPTORS
-        ]
+        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 = 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."""

custom_components/oasis_mini/config_flow.py

@@ -1,86 +1,52 @@
-"""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.components import dhcp
 from homeassistant.config_entries import 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.const import CONF_ACCESS_TOKEN, CONF_EMAIL, CONF_PASSWORD
 
-from . import OasisMiniConfigEntry
 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.config_entry.runtime_data
-
-    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
 
-    @staticmethod
-    @callback
-    def async_get_options_flow(
-        config_entry: OasisMiniConfigEntry,
-    ) -> SchemaOptionsFlowHandler:
-        """Get the options flow for this handler."""
-        return SchemaOptionsFlowHandler(config_entry, OPTIONS_FLOW)
-
-    async def async_step_dhcp(
-        self, discovery_info: dhcp.DhcpServiceInfo
+    async def async_step_reauth(
+        self, entry_data: Mapping[str, Any]
     ) -> ConfigFlowResult:
-        """Handle DHCP discovery."""
-        host = {CONF_HOST: discovery_info.ip}
-        await self.validate_client(host)
-        self._abort_if_unique_id_configured(updates=host)
-        # This should never happen since we only listen to DHCP requests
-        # for configured devices.
-        return self.async_abort(reason="already_configured")
+        """Perform reauth upon an API authentication error."""
+        return await self.async_step_reauth_confirm()
+
+    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
+
+        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
@@ -114,20 +80,22 @@ class OasisMiniConfigFlow(ConfigFlow, domain=DOMAIN):
 
         if user_input is not None:
             if not (errors := await self.validate_client(user_input)):
-                if step_id != "reconfigure":
-                    self._abort_if_unique_id_configured(updates=user_input)
-                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=user_input
+                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.unique_id}",
-                    data=user_input,
+                    title=user_input[CONF_EMAIL], data=user_input
                 )
 
         return self.async_show_form(
@@ -141,21 +109,29 @@ class OasisMiniConfigFlow(ConfigFlow, domain=DOMAIN):
         errors = {}
         try:
             async with asyncio.timeout(10):
-                client = create_client(user_input)
-                await self.async_set_unique_id(await client.async_get_serial_number())
+                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_host"
+                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

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
 
@@ -11,18 +11,23 @@ from homeassistant.core import HomeAssistant
 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,
@@ -31,31 +36,46 @@ class OasisMiniCoordinator(DataUpdateCoordinator[str]):
             update_interval=timedelta(seconds=10),
             always_update=False,
         )
-        self.device = device
+        self.cloud_client = cloud_client
+        self.mqtt_client = mqtt_client
 
-    async def _async_update_data(self):
+    async def _async_update_data(self) -> list[OasisDevice]:
         """Update the data."""
-        data: str | None = None
+        devices: list[OasisDevice] = []
         self.attempt += 1
 
         try:
             async with async_timeout.timeout(10):
-                if not self.device.mac_address:
-                    await self.device.async_get_mac_address()
-                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()
+                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_get_current_track_details()
+                # await self.device.async_get_playlist_details()
+                # await self.device.async_cloud_get_playlists()
         except Exception as ex:  # pylint:disable=broad-except
-            if self.attempt > 2 or not (data or self.data):
+            if self.attempt > 2 or not (devices or self.data):
                 raise UpdateFailed(
-                    f"Couldn't read from the Oasis Mini after {self.attempt} attempts"
+                    f"Couldn't read from the Oasis device after {self.attempt} attempts"
                 ) from ex
 
-        if data != self.data:
+        if devices != self.data:
             self.last_updated = datetime.now()
-        return data
+        return devices

custom_components/oasis_mini/entity.py

@@ -1,4 +1,4 @@
-"""Oasis Mini entity."""
+"""Oasis device entity."""
 
 from __future__ import annotations
 
@@ -7,36 +7,35 @@ 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
+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, description: EntityDescription
+        self,
+        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
-        device = coordinator.device
+
         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=f"Oasis Mini {serial_number}",
-            manufacturer="Kinetic Oasis",
-            model="Oasis Mini",
+            name=f"{device.model} {serial_number}",
+            manufacturer=device.manufacturer,
+            model=device.model,
             serial_number=serial_number,
             sw_version=device.software_version,
         )
-
-    @property
-    def device(self) -> OasisMini:
-        """Return the device."""
-        return self.coordinator.device

custom_components/oasis_mini/helpers.py

@@ -1,20 +1,27 @@
-"""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: OasisMini, track: int) -> None:
+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)
@@ -27,3 +34,21 @@ async def add_and_play_track(device: OasisMini, track: int) -> None:
 
     if device.status_code != 4:
         await device.async_play()
+
+
+def get_track_id(track: str) -> int | None:
+    """Get a track id.
+
+    `track` can be either an id or title
+    """
+    track = track.lower().strip()
+    if track not in map(str, TRACKS):
+        track = next(
+            (id for id, info in TRACKS.items() if info["name"].lower() == track), track
+        )
+
+    try:
+        return int(track)
+    except ValueError:
+        _LOGGER.warning("Invalid track: %s", track)
+        return None

custom_components/oasis_mini/icons.json

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

custom_components/oasis_mini/image.py

@@ -1,4 +1,4 @@
-"""Oasis Mini image entity."""
+"""Oasis device image entity."""
 
 from __future__ import annotations
 
@@ -7,27 +7,45 @@ from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.typing import UNDEFINED
 
-from . import OasisMiniConfigEntry
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini.const import TRACKS
-from .pyoasismini.utils import draw_svg
+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
+    )
+
 
 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, description: ImageEntityDescription
+        self,
+        coordinator: OasisDeviceCoordinator,
+        device: OasisDevice,
+        description: ImageEntityDescription,
     ) -> None:
         """Initialize the entity."""
-        super().__init__(coordinator, description)
+        super().__init__(coordinator, device, description)
         ImageEntity.__init__(self, coordinator.hass)
         self._handle_coordinator_update()
 
@@ -42,9 +60,10 @@ class OasisMiniImageEntity(OasisMiniEntity, ImageEntity):
     @callback
     def _handle_coordinator_update(self) -> None:
         """Handle updated data from the coordinator."""
-        if self._track_id != self.device.track_id or (
-            self._progress != self.device.progress and self.device.access_token
-        ):
+        if (
+            self._track_id != self.device.track_id
+            or self._progress != self.device.progress
+        ) and (self.device.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
@@ -63,12 +82,3 @@ class OasisMiniImageEntity(OasisMiniEntity, ImageEntity):
 
         if self.hass:
             super()._handle_coordinator_update()
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: OasisMiniConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up Oasis Mini camera using config entry."""
-    async_add_entities([OasisMiniImageEntity(entry.runtime_data, IMAGE)])

custom_components/oasis_mini/light.py

@@ -1,4 +1,4 @@
-"""Oasis Mini light entity."""
+"""Oasis device light entity."""
 
 from __future__ import annotations
 
@@ -23,13 +23,30 @@ from homeassistant.util.color import (
     value_to_brightness,
 )
 
-from . import OasisMiniConfigEntry
-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
 
@@ -104,15 +121,3 @@ class OasisMiniLightEntity(OasisMiniEntity, LightEntity):
             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: OasisMiniConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up Oasis Mini lights using config entry."""
-    async_add_entities([OasisMiniLightEntity(entry.runtime_data, DESCRIPTOR)])

custom_components/oasis_mini/manifest.json

@@ -1,13 +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,4 +1,4 @@
-"""Oasis Mini media player entity."""
+"""Oasis device media player entity."""
 
 from __future__ import annotations
 
@@ -18,13 +18,32 @@ from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ServiceValidationError
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from . import OasisMiniConfigEntry
-from .entity import OasisMiniEntity
-from .pyoasismini.const import TRACKS
+from . import OasisDeviceConfigEntry
+from .const import DOMAIN
+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 = (
@@ -47,8 +66,8 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
     @property
     def media_duration(self) -> int | None:
         """Duration of current playing media in seconds."""
-        if (track := self.device.track) and "reduced_svg_content" in track:
-            return track["reduced_svg_content"].get("1")
+        if (track := self.device.track) and "reduced_svg_content_new" in track:
+            return track["reduced_svg_content_new"]
         return None
 
     @property
@@ -102,18 +121,30 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
             return MediaPlayerState.ON
         return MediaPlayerState.IDLE
 
+    def abort_if_busy(self) -> None:
+        """Abort if the device is currently busy."""
+        if self.device.busy:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="device_busy",
+                translation_placeholders={"name": self._friendly_name_internal()},
+            )
+
     async def async_media_pause(self) -> None:
         """Send pause command."""
+        self.abort_if_busy()
         await self.device.async_pause()
         await self.coordinator.async_request_refresh()
 
     async def async_media_play(self) -> None:
         """Send play command."""
+        self.abort_if_busy()
         await self.device.async_play()
         await self.coordinator.async_request_refresh()
 
     async def async_media_stop(self) -> None:
         """Send stop command."""
+        self.abort_if_busy()
         await self.device.async_stop()
         await self.coordinator.async_request_refresh()
 
@@ -127,6 +158,7 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
 
     async def async_media_previous_track(self) -> None:
         """Send previous track command."""
+        self.abort_if_busy()
         if (index := self.device.playlist_index - 1) < 0:
             index = len(self.device.playlist) - 1
         await self.device.async_change_track(index)
@@ -134,6 +166,7 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
 
     async def async_media_next_track(self) -> None:
         """Send next track command."""
+        self.abort_if_busy()
         if (index := self.device.playlist_index + 1) >= len(self.device.playlist):
             index = 0
         await self.device.async_change_track(index)
@@ -147,32 +180,35 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
         **kwargs: Any,
     ) -> None:
         """Play a piece of media."""
-        if media_id not in map(str, TRACKS):
-            media_id = next(
-                (
-                    id
-                    for id, info in TRACKS.items()
-                    if info["name"].lower() == media_id.lower()
-                ),
-                media_id,
+        self.abort_if_busy()
+        if media_type == MediaType.PLAYLIST:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN, translation_key="playlists_unsupported"
             )
-        try:
-            track = int(media_id)
-        except ValueError as err:
-            raise ServiceValidationError(f"Invalid media: {media_id}") from err
+        else:
+            track = list(filter(None, map(get_track_id, media_id.split(","))))
+            if not track:
+                raise ServiceValidationError(
+                    translation_domain=DOMAIN,
+                    translation_key="invalid_media",
+                    translation_placeholders={"media": media_id},
+                )
 
         device = self.device
         enqueue = MediaPlayerEnqueue.NEXT if not enqueue else enqueue
         if enqueue == MediaPlayerEnqueue.REPLACE:
-            await device.async_set_playlist([track])
+            await device.async_set_playlist(track)
         else:
             await device.async_add_track_to_playlist(track)
 
         if enqueue in (MediaPlayerEnqueue.NEXT, MediaPlayerEnqueue.PLAY):
             # Move track to next item in the playlist
-            if (index := (len(device.playlist) - 1)) != device.playlist_index:
+            new_tracks = 1 if isinstance(track, int) else len(track)
+            if (index := (len(device.playlist) - new_tracks)) != device.playlist_index:
                 if index != (
-                    _next := min(device.playlist_index + 1, len(device.playlist) - 1)
+                    _next := min(
+                        device.playlist_index + 1, len(device.playlist) - new_tracks
+                    )
                 ):
                     await device.async_move_track(index, _next)
                 if enqueue == MediaPlayerEnqueue.PLAY:
@@ -188,17 +224,6 @@ class OasisMiniMediaPlayerEntity(OasisMiniEntity, MediaPlayerEntity):
 
     async def async_clear_playlist(self) -> None:
         """Clear players playlist."""
+        self.abort_if_busy()
         await self.device.async_clear_playlist()
         await self.coordinator.async_request_refresh()
-
-
-DESCRIPTOR = MediaPlayerEntityDescription(key="oasis_mini", name=None)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: OasisMiniConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up Oasis Mini media_players using config entry."""
-    async_add_entities([OasisMiniMediaPlayerEntity(entry.runtime_data, DESCRIPTOR)])

custom_components/oasis_mini/number.py

@@ -1,4 +1,4 @@
-"""Oasis Mini number entity."""
+"""Oasis device number entity."""
 
 from __future__ import annotations
 
@@ -10,13 +10,51 @@ from homeassistant.components.number import (
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from . import OasisMiniConfigEntry
-from .entity import OasisMiniEntity
-from .pyoasismini import BALL_SPEED_MAX, BALL_SPEED_MIN, LED_SPEED_MAX, LED_SPEED_MIN
+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:
@@ -30,35 +68,3 @@ class OasisMiniNumberEntity(OasisMiniEntity, NumberEntity):
         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",
-        mode=NumberMode.SLIDER,
-        native_max_value=BALL_SPEED_MAX,
-        native_min_value=BALL_SPEED_MIN,
-    ),
-    NumberEntityDescription(
-        key="led_speed",
-        name="LED speed",
-        mode=NumberMode.SLIDER,
-        native_max_value=LED_SPEED_MAX,
-        native_min_value=LED_SPEED_MIN,
-    ),
-}
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: OasisMiniConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up Oasis Mini numbers using config entry."""
-    async_add_entities(
-        [
-            OasisMiniNumberEntity(entry.runtime_data, 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,215 @@
+"""Oasis HTTP client (per-device)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiohttp import ClientSession
+
+from ..const import AUTOPLAY_MAP
+from ..device import OasisDevice
+from ..utils import _bit_to_bool, _parse_int
+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)
+
+        values = raw_status.split(";")
+        if len(values) < 7:
+            _LOGGER.warning(
+                "Unexpected status format for %s: %s", device.serial_number, values
+            )
+            return
+
+        playlist = [_parse_int(track) for track in values[3].split(",") if track]
+        shift = len(values) - 18 if len(values) > 17 else 0
+
+        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_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 + shift]),
+                "download_progress": _parse_int(values[12 + shift]),
+                "max_brightness": _parse_int(values[13 + shift]),
+                "repeat_playlist": _bit_to_bool(values[15 + shift]),
+                "autoplay": AUTOPLAY_MAP.get(value := values[16 + shift], value),
+            }
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception("Error parsing HTTP status for %s", device.serial_number)
+            return
+
+        device.update_from_status_dict(status)

custom_components/oasis_mini/pyoasiscontrol/clients/mqtt_client.py

@@ -0,0 +1,517 @@
+"""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 ..const import AUTOPLAY_MAP
+from ..device import OasisDevice
+from ..utils import _bit_to_bool
+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
+
+
+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()
+
+    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())
+
+        # 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
+                )
+
+        if not device.client:
+            device.attach_client(self)
+
+    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
+
+    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)
+
+    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")
+
+    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_status(self, device: OasisDevice) -> None:
+        """Ask device to publish STATUS topics."""
+        await self._publish_command(device, "GETSTATUS")
+
+    async def _publish_command(self, device: OasisDevice, payload: str) -> None:
+        if not self._client:
+            raise RuntimeError("MQTT client not connected yet")
+
+        serial = device.serial_number
+        if not serial:
+            raise RuntimeError("Device has no serial_number set")
+
+        topic = f"{serial}/COMMAND/CMD"
+        _LOGGER.debug("MQTT publish %s => %s", topic, payload)
+        await self._client.publish(topic, payload.encode(), qos=1)
+
+    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.debug(
+                    "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()
+
+                    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.debug("MQTT connection error")
+
+            finally:
+                if self._connected_event.is_set():
+                    self._connected_event.clear()
+                    if self._connected_at:
+                        _LOGGER.debug(
+                            "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.debug(
+                    "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:
+            # Ignore devices we don't know about
+            _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_effect_color"] = 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["max_brightness"] = 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"] = AUTOPLAY_MAP.get(payload, 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
+            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,85 @@
+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: ...

custom_components/oasis_mini/pyoasiscontrol/const.py

@@ -0,0 +1,106 @@
+"""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",
+    "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_MAP: Final[dict[int, str]] = {
+    0: "booting",
+    2: "stopped",
+    3: "centering",
+    4: "playing",
+    5: "paused",
+    6: "sleeping",
+    9: "error",
+    11: "updating",
+    13: "downloading",
+    14: "busy",
+    15: "live",
+}

custom_components/oasis_mini/pyoasiscontrol/device.py

@@ -0,0 +1,327 @@
+"""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, TRACKS
+
+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 = (
+    "autoplay",
+    "ball_speed",
+    "brightness",
+    "busy",
+    "color",
+    "download_progress",
+    "error",
+    "led_effect",
+    "led_speed",
+    "mac_address",
+    "max_brightness",
+    "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: str = "off"
+        self.ball_speed: int = BALL_SPEED_MIN
+        self.brightness: int = 0
+        self.busy: bool = False
+        self.color: str | None = None
+        self.download_progress: int = 0
+        self.error: int = 0
+        self.led_effect: str = "0"
+        self.led_speed: int = 0
+        self.mac_address: str | None = None
+        self.max_brightness: int = 200
+        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
+
+    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 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.max_brightness:
+            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,13 +27,22 @@ def _bit_to_bool(val: str) -> bool:
     return val == "1"
 
 
+def _parse_int(val: str) -> int:
+    """Convert an int string to int."""
+    try:
+        return int(val)
+    except Exception:
+        return 0
+
+
 def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
     """Draw SVG."""
     if track and (svg_content := track.get("svg_content")):
         try:
             if progress is not None:
+                svg_content = decrypt_svg_content(svg_content)
                 paths = svg_content.split("L")
-                total = track.get("reduced_svg_content", {}).get(model_id, len(paths))
+                total = track.get("reduced_svg_content_new", 0) or len(paths)
                 percent = min((100 * progress) / total, 100)
                 progress = math.floor((percent / 100) * (len(paths) - 1))
 
@@ -137,3 +153,32 @@ def draw_svg(track: dict, progress: int, model_id: str) -> str | None:
         except Exception as e:
             _LOGGER.exception(e)
     return None
+
+
+def decrypt_svg_content(svg_content: dict[str, str]):
+    """Decrypt SVG content using AES CBC mode."""
+    if decrypted := svg_content.get("decrypted"):
+        return decrypted
+
+    # decode base64-encoded data
+    key = base64.b64decode(APP_KEY)
+    iv = base64.b64decode(svg_content["iv"])
+    ciphertext = base64.b64decode(svg_content["content"])
+
+    # create the cipher and decrypt the ciphertext
+    cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+    decrypted = decryptor.update(ciphertext) + decryptor.finalize()
+
+    # remove PKCS7 padding
+    pad_len = decrypted[-1]
+    decrypted = decrypted[:-pad_len].decode("utf-8")
+
+    # save decrypted data so we don't have to do this each time
+    svg_content["decrypted"] = decrypted
+
+    return decrypted
+
+
+def now() -> datetime:
+    return datetime.now(UTC)

custom_components/oasis_mini/pyoasismini/__init__.py

@@ -1,447 +0,0 @@
-"""Oasis Mini API client."""
-
-import asyncio
-import logging
-from typing import Any, Awaitable, Final
-from urllib.parse import urljoin
-
-from aiohttp import ClientResponseError, ClientSession
-import async_timeout
-
-from .const import TRACKS
-from .utils import _bit_to_bool
-
-_LOGGER = logging.getLogger(__name__)
-
-STATUS_CODE_MAP = {
-    0: "booting",  # maybe?
-    2: "stopped",
-    3: "centering",
-    4: "playing",
-    5: "paused",
-    9: "error",
-    11: "updating",
-    13: "downloading",
-    15: "live",
-}
-
-AUTOPLAY_MAP = {
-    "0": "on",
-    "1": "off",
-    "2": "5 minutes",
-    "3": "10 minutes",
-    "4": "30 minutes",
-}
-
-
-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"
-
-BALL_SPEED_MAX: Final = 1000
-BALL_SPEED_MIN: Final = 200
-LED_SPEED_MAX: Final = 90
-LED_SPEED_MIN: Final = -90
-
-
-class OasisMini:
-    """Oasis Mini API client class."""
-
-    _access_token: str | None = None
-    _mac_address: str | None = None
-    _ip_address: str | None = None
-    _playlist: dict[int, dict[str, str]] = {}
-    _serial_number: str | None = None
-    _software_version: str | None = None
-    _track: dict | None = None
-
-    autoplay: str
-    brightness: int
-    busy: bool
-    color: str | None = None
-    download_progress: int
-    error: int
-    led_effect: str
-    led_speed: int
-    max_brightness: int
-    playlist: list[int]
-    playlist_index: int
-    progress: int
-    repeat_playlist: bool
-    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 mac_address(self) -> str | None:
-        """Return the mac address."""
-        return self._mac_address
-
-    @property
-    def drawing_progress(self) -> float | None:
-        """Return the drawing progress percent."""
-        if not (self.track and (svg_content := self.track.get("svg_content"))):
-            return None
-        paths = svg_content.split("L")
-        total = self.track.get("reduced_svg_content", {}).get("1", len(paths))
-        percent = (100 * self.progress) / total
-        return percent
-
-    @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 track(self) -> dict | None:
-        """Return the current track info."""
-        if self._track and self._track.get("id") == self.track_id:
-            return self._track
-        return None
-
-    @property
-    def track_id(self) -> int | None:
-        """Return the current track id."""
-        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 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."""
-        if not track:
-            return
-
-        if 0 in self.playlist:
-            playlist = [t for t in self.playlist if t] + [track]
-            return await self.async_set_playlist(playlist)
-
-        await self._async_command(params={"ADDJOBLIST": track})
-        self.playlist.append(track)
-
-    async def async_change_track(self, index: int) -> None:
-        """Change the track."""
-        if index >= len(self.playlist):
-            raise ValueError("Invalid index specified")
-        await self._async_command(params={"CMDCHANGETRACK": index})
-
-    async def async_clear_playlist(self) -> None:
-        """Clear the playlist."""
-        await self.async_set_playlist([])
-
-    async def async_get_ip_address(self) -> str | None:
-        """Get the ip address."""
-        self._ip_address = await self._async_get(params={"GETIP": ""})
-        _LOGGER.debug("IP address: %s", self._ip_address)
-        return self._ip_address
-
-    async def async_get_mac_address(self) -> str | None:
-        """Get the mac address."""
-        self._mac_address = await self._async_get(params={"GETMAC": ""})
-        _LOGGER.debug("MAC address: %s", self._mac_address)
-        return self._mac_address
-
-    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) -> str:
-        """Get the status from the device."""
-        raw_status = await self._async_get(params={"GETSTATUS": ""})
-        _LOGGER.debug("Status: %s", raw_status)
-        values = raw_status.split(";")
-        playlist = [int(track) for track in values[3].split(",") if track]
-        status = {
-            "status_code": int(values[0]),  # see status code map
-            "error": int(values[1]),  # noqa: E501; error, 0 = none, and 10 = ?, 18 = can't download?
-            "ball_speed": int(values[2]),  # 200 - 1000
-            "playlist": playlist,
-            "playlist_index": min(int(values[4]), len(playlist)),  # index of above
-            "progress": int(values[5]),  # 0 - max svg path
-            "led_effect": values[6],  # led effect (code lookup)
-            "led_color_id": values[7],  # led color id?
-            "led_speed": int(values[8]),  # -90 - 90
-            "brightness": int(values[9]) if values[10] else 0,  # noqa: E501; 0 - 200 in app, but seems to be 0 (off) to 304 (max), then repeats
-            "color": values[10] or None,  # hex color code
-            "busy": _bit_to_bool(values[11]),  # noqa: E501; device is busy (downloading track, centering, software update)?
-            "download_progress": int(values[12]),
-            "max_brightness": int(values[13]),
-            "wifi_connected": _bit_to_bool(values[14]),
-            "repeat_playlist": _bit_to_bool(values[15]),
-            "autoplay": AUTOPLAY_MAP.get(values[16]),
-        }
-        for key, value in status.items():
-            if (old_value := getattr(self, key, None)) != value:
-                _LOGGER.debug(
-                    "%s changed: '%s' -> '%s'",
-                    key.replace("_", " ").capitalize(),
-                    old_value,
-                    value,
-                )
-                setattr(self, key, value)
-        return raw_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."""
-        if self.status_code == 15:
-            await self.async_stop()
-        if self.track_id:
-            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 BALL_SPEED_MIN <= speed <= BALL_SPEED_MAX:
-            raise ValueError("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 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.max_brightness:
-            raise ValueError("Invalid brightness specified")
-
-        await self._async_command(
-            params={"WRILED": f"{led_effect};0;{color};{led_speed};{brightness}"}
-        )
-
-    async def async_set_autoplay(self, option: bool | int | str) -> None:
-        """Set autoplay."""
-        if isinstance(option, bool):
-            option = 0 if option else 1
-        if str(option) not in AUTOPLAY_MAP:
-            raise ValueError("Invalid pause option specified")
-        await self._async_command(params={"WRIWAITAFTER": option})
-
-    async def async_set_playlist(self, playlist: list[int]) -> None:
-        """Set the playlist."""
-        if is_playing := (self.status_code == 4):
-            await self.async_stop()
-        await self._async_command(params={"WRIJOBLIST": ",".join(map(str, playlist))})
-        self.playlist = playlist
-        if is_playing:
-            await self.async_play()
-
-    async def async_set_repeat_playlist(self, repeat: bool) -> None:
-        """Set repeat playlist."""
-        await self._async_command(params={"WRIREPEATJOB": 1 if repeat else 0})
-
-    async def async_stop(self) -> None:
-        """Send stop command."""
-        await self._async_command(params={"CMDSTOP": ""})
-
-    async def async_upgrade(self, beta: bool = False) -> None:
-        """Trigger a software upgrade."""
-        await self._async_command(params={"CMDUPGRADE": 1 if beta else 0})
-
-    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."""
-        await self._async_cloud_request("GET", "api/auth/logout")
-
-    async def async_cloud_get_track_info(self, track_id: int) -> dict[str, Any] | None:
-        """Get cloud track info."""
-        try:
-            return await self._async_cloud_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:
-            _LOGGER.exception(ex)
-        return None
-
-    async def async_cloud_get_tracks(
-        self, tracks: list[int] | None = None
-    ) -> list[dict[str, Any]]:
-        """Get tracks info from the cloud"""
-        response = await self._async_cloud_request(
-            "GET", "api/track", params={"ids[]": tracks or []}
-        )
-        if not response:
-            return None
-        track_details = response.get("data", [])
-        while next_page_url := response.get("next_page_url"):
-            response = await self._async_cloud_request("GET", next_page_url)
-            track_details += response.get("data", [])
-        return track_details
-
-    async def async_cloud_get_latest_software_details(self) -> dict[str, int | str]:
-        """Get the latest software details from the cloud."""
-        return await self._async_cloud_request("GET", "api/software/last-version")
-
-    async def async_get_current_track_details(self) -> dict | None:
-        """Get current track info, refreshing if needed."""
-        track_id = self.track_id
-        if (track := self._track) and track.get("id") == track_id:
-            return track
-        if track_id:
-            self._track = await self.async_cloud_get_track_info(track_id)
-            if not self._track:
-                self._track = TRACKS.get(
-                    track_id, {"id": track_id, "name": f"Unknown Title (#{track_id})"}
-                )
-        return self._track
-
-    async def async_get_playlist_details(self) -> dict[int, dict[str, str]]:
-        """Get playlist info."""
-        if set(self.playlist).difference(self._playlist.keys()):
-            tracks = await self.async_cloud_get_tracks(self.playlist)
-            all_tracks = TRACKS | {
-                track["id"]: {
-                    "name": track["name"],
-                    "author": ((track.get("author") or {}).get("person") or {}).get(
-                        "name", "Oasis Mini"
-                    ),
-                    "image": track["image"],
-                }
-                for track in tracks
-            }
-            for track in self.playlist:
-                self._playlist[track] = all_tracks.get(
-                    track, {"name": f"Unknown Title (#{track})"}
-                )
-        return self._playlist
-
-    async def _async_cloud_request(self, method: str, url: str, **kwargs: Any) -> Any:
-        """Perform a cloud request."""
-        if not self.access_token:
-            return
-
-        return await self._async_request(
-            method,
-            urljoin(CLOUD_BASE_URL, url),
-            headers={"Authorization": f"Bearer {self.access_token}"},
-            **kwargs,
-        )
-
-    async def _async_command(self, **kwargs: Any) -> str | None:
-        """Send a command to the device."""
-        result = await self._async_get(**kwargs)
-        _LOGGER.debug("Result: %s", result)
-
-    async def _async_get(self, **kwargs: Any) -> str | None:
-        """Perform a GET request."""
-        return await self._async_request("GET", self.url, **kwargs)
-
-    async def _async_request(self, method: str, url: str, **kwargs) -> Any:
-        """Perform a request."""
-        _LOGGER.debug(
-            "%s %s",
-            method,
-            self._session._build_url(url).update_query(  # pylint: disable=protected-access
-                kwargs.get("params")
-            ),
-        )
-        response = await self._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()
-            return None
-        response.raise_for_status()

custom_components/oasis_mini/pyoasismini/const.py

@@ -1,16 +0,0 @@
-"""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 = {}

custom_components/oasis_mini/select.py

@@ -1,7 +1,8 @@
-"""Oasis Mini select entity."""
+"""Oasis device select entity."""
 
 from __future__ import annotations
 
+from collections import defaultdict
 from dataclasses import dataclass
 from typing import Any, Awaitable, Callable
 
@@ -10,35 +11,130 @@ from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.entity import EntityDescription
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from . import OasisMiniConfigEntry
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini import AUTOPLAY_MAP, OasisMini
-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
+
+
+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
+
+
+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: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """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 OasisMiniSelectEntityDescription(SelectEntityDescription):
-    """Oasis Mini select entity description."""
+class OasisDeviceSelectEntityDescription(SelectEntityDescription):
+    """Oasis device select entity description."""
 
-    current_value: Callable[[OasisMini], Any]
-    select_fn: Callable[[OasisMini, int], Awaitable[None]]
-    update_handler: Callable[[OasisMiniSelectEntity], None] | None = None
+    current_value: Callable[[OasisDevice], Any]
+    select_fn: Callable[[OasisDevice, int], Awaitable[None]]
+    update_handler: Callable[[OasisDeviceSelectEntity], None] | None = None
 
 
-class OasisMiniSelectEntity(OasisMiniEntity, SelectEntity):
-    """Oasis Mini select entity."""
+DESCRIPTORS = (
+    OasisDeviceSelectEntityDescription(
+        key="autoplay",
+        translation_key="autoplay",
+        options=list(AUTOPLAY_MAP.values()),
+        current_value=lambda device: device.autoplay,
+        select_fn=lambda device, option: device.async_set_autoplay(option),
+    ),
+    OasisDeviceSelectEntityDescription(
+        key="queue",
+        translation_key="queue",
+        current_value=lambda device: (device.playlist.copy(), device.playlist_index),
+        select_fn=lambda device, option: device.async_change_track(option),
+        update_handler=queue_update_handler,
+    ),
+)
+CLOUD_DESCRIPTORS = (
+    OasisDeviceSelectEntityDescription(
+        key="playlists",
+        translation_key="playlist",
+        current_value=lambda device: (device.playlists, device.playlist.copy()),
+        select_fn=lambda device, option: device.async_set_playlist(
+            [pattern["id"] for pattern in device.playlists[option]["patterns"]]
+        ),
+        update_handler=playlists_update_handler,
+    ),
+)
 
-    entity_description: OasisMiniSelectEntityDescription
+
+class OasisDeviceSelectEntity(OasisDeviceEntity, SelectEntity):
+    """Oasis device select entity."""
+
+    entity_description: OasisDeviceSelectEntityDescription
     _current_value: Any | None = None
 
     def __init__(
         self,
-        coordinator: OasisMiniCoordinator,
+        coordinator: OasisDeviceCoordinator,
+        device: OasisDevice,
         description: EntityDescription,
     ) -> None:
-        """Construct an Oasis Mini select entity."""
-        super().__init__(coordinator, description)
+        """Construct an Oasis device select entity."""
+        super().__init__(coordinator, device, description)
         self._handle_coordinator_update()
 
     async def async_select_option(self, option: str) -> None:
@@ -61,56 +157,3 @@ class OasisMiniSelectEntity(OasisMiniEntity, SelectEntity):
             )
         if self.hass:
             return super()._handle_coordinator_update()
-
-
-def playlist_update_handler(entity: OasisMiniSelectEntity) -> None:
-    """Handle playlist updates."""
-    # pylint: disable=protected-access
-    device = entity.device
-    options = [
-        device._playlist.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),
-            ),
-        )
-        for track in device.playlist
-    ]
-    entity._attr_options = options
-    index = min(device.playlist_index, len(options) - 1)
-    entity._attr_current_option = options[index] if options else None
-
-
-DESCRIPTORS = (
-    OasisMiniSelectEntityDescription(
-        key="playlist",
-        name="Playlist",
-        current_value=lambda device: (device.playlist.copy(), device.playlist_index),
-        select_fn=lambda device, option: device.async_change_track(option),
-        update_handler=playlist_update_handler,
-    ),
-    OasisMiniSelectEntityDescription(
-        key="autoplay",
-        name="Autoplay",
-        options=list(AUTOPLAY_MAP.values()),
-        current_value=lambda device: device.autoplay,
-        select_fn=lambda device, option: device.async_set_autoplay(option),
-    ),
-)
-
-
-async def async_setup_entry(
-    hass: HomeAssistant,
-    entry: OasisMiniConfigEntry,
-    async_add_entities: AddEntitiesCallback,
-) -> None:
-    """Set up Oasis Mini select using config entry."""
-    async_add_entities(
-        [
-            OasisMiniSelectEntity(entry.runtime_data, descriptor)
-            for descriptor in DESCRIPTORS
-        ]
-    )

custom_components/oasis_mini/sensor.py

@@ -1,4 +1,4 @@
-"""Oasis Mini sensor entity."""
+"""Oasis device sensor entity."""
 
 from __future__ import annotations
 
@@ -11,62 +11,57 @@ from homeassistant.const import PERCENTAGE, EntityCategory
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from . import OasisMiniConfigEntry
-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: OasisMiniConfigEntry,
+    entry: OasisDeviceConfigEntry,
     async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis Mini sensors using config entry."""
-    coordinator: OasisMiniCoordinator = entry.runtime_data
+    """Set up Oasis device sensors using config entry."""
+    coordinator: OasisDeviceCoordinator = entry.runtime_data
     entities = [
-        OasisMiniSensorEntity(coordinator, descriptor) for descriptor in DESCRIPTORS
+        OasisDeviceSensorEntity(coordinator, device, descriptor)
+        for device in coordinator.data
+        for descriptor in DESCRIPTORS
     ]
-    if coordinator.device.access_token:
-        entities.extend(
-            [
-                OasisMiniSensorEntity(coordinator, descriptor)
-                for descriptor in CLOUD_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",
         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", "status")
+    # 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,
-        name="Drawing progress",
         native_unit_of_measurement=PERCENTAGE,
         state_class=SensorStateClass.MEASUREMENT,
         suggested_display_precision=1,
@@ -74,8 +69,8 @@ CLOUD_DESCRIPTORS = (
 )
 
 
-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,24 +3,29 @@
     "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%]"
         }
       }
     },
     "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%]",
-      "reconfigure_successful": "[%key:common::config_flow::abort::reconfigure_successful%]"
+      "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%]",
+      "wrong_account": "Account used for the integration should not change"
     }
   },
   "options": {
@@ -38,7 +43,80 @@
     }
   },
   "entity": {
+    "button": {
+      "random_track": {
+        "name": "Play random track"
+      },
+      "sleep": {
+        "name": "Sleep"
+      }
+    },
+    "binary_sensor": {
+      "busy": {
+        "name": "Busy"
+      },
+      "wifi_status": {
+        "name": "Wi-Fi status"
+      }
+    },
+    "light": {
+      "led": {
+        "name": "LED"
+      }
+    },
+    "number": {
+      "ball_speed": {
+        "name": "Ball speed"
+      },
+      "led_speed": {
+        "name": "LED speed"
+      }
+    },
+    "select": {
+      "autoplay": {
+        "name": "Autoplay"
+      },
+      "playlist": {
+        "name": "Playlist"
+      },
+      "queue": {
+        "name": "Queue"
+      }
+    },
     "sensor": {
+      "download_progress": {
+        "name": "Download progress"
+      },
+      "drawing_progress": {
+        "name": "Drawing progress"
+      },
+      "error": {
+        "name": "Error",
+        "state": {
+          "0": "None",
+          "1": "Error has occurred while reading the flash memory",
+          "2": "Error while starting the Wifi",
+          "3": "Error when starting DNS settings for your machine",
+          "4": "Failed to open the file to write",
+          "5": "Not enough memory to perform the upgrade",
+          "6": "Error while trying to upgrade your system",
+          "7": "Error while trying to download the new version of the software",
+          "8": "Error while reading the upgrading file",
+          "9": "Failed to start downloading the upgrade file",
+          "10": "Error while starting downloading the job file",
+          "11": "Error while opening the file folder",
+          "12": "Failed to delete a file",
+          "13": "Error while opening the job file",
+          "14": "You have wrong power adapter",
+          "15": "Failed to update the device IP on Oasis Server",
+          "16": "Your device failed centering itself",
+          "17": "There appears to be an issue with your Oasis Device",
+          "18": "Error while downloading the job file"
+        }
+      },
+      "led_color_id": {
+        "name": "LED color ID"
+      },
       "status": {
         "name": "Status",
         "state": {
@@ -47,12 +125,25 @@
           "centering": "Centering",
           "playing": "Playing",
           "paused": "Paused",
+          "sleeping": "Sleeping",
           "error": "Error",
           "updating": "Updating",
           "downloading": "Downloading",
+          "busy": "Busy",
           "live": "Live drawing"
         }
       }
     }
+  },
+  "exceptions": {
+    "device_busy": {
+      "message": "{name} is currently busy and cannot be modified"
+    },
+    "invalid_media": {
+      "message": "Invalid media: {media}"
+    },
+    "playlists_unsupported": {
+      "message": "Playlists are not currently supported"
+    }
   }
-}
+}

custom_components/oasis_mini/translations/en.json

@@ -3,24 +3,29 @@
     "step": {
       "user": {
         "data": {
-          "host": "Host"
+          "email": "Email",
+          "password": "Password"
         }
       },
       "reconfigure": {
         "data": {
-          "host": "Host"
+          "email": "Email",
+          "password": "Password"
         }
       }
     },
     "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",
-      "reconfigure_successful": "Re-configuration was successful"
+      "already_configured": "Account is already configured",
+      "reauth_successful": "Re-authentication was successful",
+      "reconfigure_successful": "Re-configuration was successful",
+      "wrong_account": "Account used for the integration should not change"
     }
   },
   "options": {
@@ -38,7 +43,80 @@
     }
   },
   "entity": {
+    "button": {
+      "random_track": {
+        "name": "Play random track"
+      },
+      "sleep": {
+        "name": "Sleep"
+      }
+    },
+    "binary_sensor": {
+      "busy": {
+        "name": "Busy"
+      },
+      "wifi_status": {
+        "name": "Wi-Fi status"
+      }
+    },
+    "light": {
+      "led": {
+        "name": "LED"
+      }
+    },
+    "number": {
+      "ball_speed": {
+        "name": "Ball speed"
+      },
+      "led_speed": {
+        "name": "LED speed"
+      }
+    },
+    "select": {
+      "autoplay": {
+        "name": "Autoplay"
+      },
+      "playlist": {
+        "name": "Playlist"
+      },
+      "queue": {
+        "name": "Queue"
+      }
+    },
     "sensor": {
+      "download_progress": {
+        "name": "Download progress"
+      },
+      "drawing_progress": {
+        "name": "Drawing progress"
+      },
+      "error": {
+        "name": "Error",
+        "state": {
+          "0": "None",
+          "1": "Error has occurred while reading the flash memory",
+          "2": "Error while starting the Wifi",
+          "3": "Error when starting DNS settings for your machine",
+          "4": "Failed to open the file to write",
+          "5": "Not enough memory to perform the upgrade",
+          "6": "Error while trying to upgrade your system",
+          "7": "Error while trying to download the new version of the software",
+          "8": "Error while reading the upgrading file",
+          "9": "Failed to start downloading the upgrade file",
+          "10": "Error while starting downloading the job file",
+          "11": "Error while opening the file folder",
+          "12": "Failed to delete a file",
+          "13": "Error while opening the job file",
+          "14": "You have wrong power adapter",
+          "15": "Failed to update the device IP on Oasis Server",
+          "16": "Your device failed centering itself",
+          "17": "There appears to be an issue with your Oasis Device",
+          "18": "Error while downloading the job file"
+        }
+      },
+      "led_color_id": {
+        "name": "LED color ID"
+      },
       "status": {
         "name": "Status",
         "state": {
@@ -47,12 +125,25 @@
           "centering": "Centering",
           "playing": "Playing",
           "paused": "Paused",
+          "sleeping": "Sleeping",
           "error": "Error",
           "updating": "Updating",
           "downloading": "Downloading",
+          "busy": "Busy",
           "live": "Live drawing"
         }
       }
     }
+  },
+  "exceptions": {
+    "device_busy": {
+      "message": "{name} is currently busy and cannot be modified"
+    },
+    "invalid_media": {
+      "message": "Invalid media: {media}"
+    },
+    "playlists_unsupported": {
+      "message": "Playlists are not currently supported"
+    }
   }
-}
+}

custom_components/oasis_mini/update.py

@@ -1,4 +1,4 @@
-"""Oasis Mini update entity."""
+"""Oasis device update entity."""
 
 from __future__ import annotations
 
@@ -15,9 +15,9 @@ from homeassistant.components.update import (
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 
-from . import OasisMiniConfigEntry
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
+from . import OasisDeviceConfigEntry
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -26,13 +26,16 @@ SCAN_INTERVAL = timedelta(hours=6)
 
 async def async_setup_entry(
     hass: HomeAssistant,
-    entry: OasisMiniConfigEntry,
+    entry: OasisDeviceConfigEntry,
     async_add_entities: AddEntitiesCallback,
 ) -> None:
-    """Set up Oasis Mini updates using config entry."""
-    coordinator: OasisMiniCoordinator = entry.runtime_data
-    if coordinator.device.access_token:
-        async_add_entities([OasisMiniUpdateEntity(coordinator, DESCRIPTOR)], True)
+    """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(
@@ -40,8 +43,8 @@ DESCRIPTOR = UpdateEntityDescription(
 )
 
 
-class OasisMiniUpdateEntity(OasisMiniEntity, UpdateEntity):
-    """Oasis Mini update entity."""
+class OasisDeviceUpdateEntity(OasisDeviceEntity, UpdateEntity):
+    """Oasis device update entity."""
 
     _attr_supported_features = (
         UpdateEntityFeature.INSTALL | UpdateEntityFeature.PROGRESS
@@ -68,16 +71,14 @@ class OasisMiniUpdateEntity(OasisMiniEntity, UpdateEntity):
         self, version: str | None, backup: bool, **kwargs: Any
     ) -> None:
         """Install an update."""
-        version = await self.device.async_get_software_version()
-        if version == self.latest_version:
+        if self.latest_version == self.device.software_version:
             return
         await self.device.async_upgrade()
 
     async def async_update(self) -> None:
         """Update the entity."""
-        await self.device.async_get_software_version()
-        software = await self.device.async_cloud_get_latest_software_details()
-        if not software:
+        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"]

hacs.json

@@ -1,7 +1,7 @@
 {
-  "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,12 +1,15 @@
 # Home Assistant
-homeassistant>=2024.4
+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

@@ -7,18 +7,24 @@ import json
 import os
 from typing import Any
 
-from custom_components.oasis_mini.pyoasismini import OasisMini
-from custom_components.oasis_mini.pyoasismini.const import TRACKS
+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 = OasisMini("", ACCESS_TOKEN)
+    client = OasisCloudClient(access_token=ACCESS_TOKEN)
 
     try:
-        data = await client.async_cloud_get_tracks()
+        data = await client.async_get_tracks()
     except Exception as ex:
         print(type(ex).__name__, ex)
         await client.session.close()
@@ -32,23 +38,22 @@ async def update_tracks() -> None:
     for result in filter(lambda d: d["public"], data):
         if (
             (track_id := result["id"]) not in TRACKS
-            or result["name"] != TRACKS[track_id].get("name")
-            or result["image"] != TRACKS[track_id].get("image")
+            or any(
+                result[field] != TRACKS[track_id].get(field)
+                for field in ("name", "image", "png_image")
+            )
+            or TRACKS[track_id].get("author") != get_author_name(result)
         ):
-            print(f"Updating track {track_id}: {result["name"]}")
-            track_info = await client.async_cloud_get_track_info(int(track_id))
+            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
-            author = (result.get("author") or {}).get("user") or {}
-            updated_tracks[track_id] = {
-                "id": track_id,
-                "name": result["name"],
-                "author": author.get("name") or author.get("nickname") or "Oasis Mini",
-                "image": result["image"],
-                "clean_pattern": track_info.get("cleanPattern", {}).get("id"),
-                "reduced_svg_content": track_info.get("reduced_svg_content"),
-            }
+            result["author"] = get_author_name(result)
+            result["reduced_svg_content_new"] = track_info.get(
+                "reduced_svg_content_new"
+            )
+            updated_tracks[track_id] = result
     await client.session.close()
 
     if not updated_tracks:
@@ -60,7 +65,7 @@ async def update_tracks() -> None:
     tracks = dict(sorted(tracks.items(), key=lambda t: t[1]["name"].lower()))
 
     with open(
-        "custom_components/oasis_mini/pyoasismini/tracks.json", "w", encoding="utf8"
+        "custom_components/oasis_mini/pyoasiscontrol/tracks.json", "w", encoding="utf8"
     ) as file:
         json.dump(tracks, file, indent=2, ensure_ascii=False)