Swap out direct HTTP connection with server MQTT connection to handle firmware 2.60+ (#98)

* Switch to using mqtt

* Better mqtt handling when connection is interrupted

* Get track info from the cloud when playlist or index changes

* Add additional helpers

* Dynamically handle devices and other enhancements

* 📝 Add docstrings to `mqtt`

Docstrings generation was requested by @natekspencer.

* https://github.com/natekspencer/hacs-oasis_mini/pull/98#issuecomment-3568450288

The following files were modified:

* `custom_components/oasis_mini/__init__.py`
* `custom_components/oasis_mini/binary_sensor.py`
* `custom_components/oasis_mini/button.py`
* `custom_components/oasis_mini/config_flow.py`
* `custom_components/oasis_mini/coordinator.py`
* `custom_components/oasis_mini/entity.py`
* `custom_components/oasis_mini/helpers.py`
* `custom_components/oasis_mini/image.py`
* `custom_components/oasis_mini/light.py`
* `custom_components/oasis_mini/media_player.py`
* `custom_components/oasis_mini/number.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/cloud_client.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/http_client.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/mqtt_client.py`
* `custom_components/oasis_mini/pyoasiscontrol/clients/transport.py`
* `custom_components/oasis_mini/pyoasiscontrol/device.py`
* `custom_components/oasis_mini/pyoasiscontrol/utils.py`
* `custom_components/oasis_mini/select.py`
* `custom_components/oasis_mini/sensor.py`
* `custom_components/oasis_mini/switch.py`
* `custom_components/oasis_mini/update.py`
* `update_tracks.py`

* Fix formatting in transport.py

* Replace tabs with spaces

* Use tuples instead of sets for descriptors

* Encode svg in image entity

* Fix iot_class

* Fix tracks list url

* Ensure update_tracks closes the connection

* Fix number typing and docstring

* Fix docstring in update_tracks

* Cache playlist based on type

* Fix formatting in device.py

* Add missing async_send_auto_clean_command to http client

* Propagate UnauthenticatedError from async_get_track_info

* Adjust exceptions

* Move create_client outside of try block in config_flow

* Formatting

* Address PR comments

* Formatting

* Add noqa: ARG001 on unused hass

* Close cloud/MQTT clients if initial coordinator refresh fails.

* Address PR again

* PR fixes

* Pass config entry to coordinator

* Remove async_timeout (thanks ChatGPT... not)

* Address PR

* Replace magic numbers for status code

* Update autoplay wording/ordering

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

custom_components/oasis_mini/image.py

@@ -1,4 +1,4 @@
-"""Oasis Mini image entity."""
+"""Oasis device image entity."""
 
 from __future__ import annotations
 
@@ -6,70 +6,118 @@ from homeassistant.components.image import Image, ImageEntity, ImageEntityDescri
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.typing import UNDEFINED
+from homeassistant.util import dt as dt_util
+
+from . import OasisDeviceConfigEntry, setup_platform_from_coordinator
+from .coordinator import OasisDeviceCoordinator
+from .entity import OasisDeviceEntity
+from .pyoasiscontrol import OasisDevice
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,  # noqa: ARG001
+    entry: OasisDeviceConfigEntry,
+    async_add_entities: AddEntitiesCallback,
+) -> None:
+    """
+    Set up image entities for Oasis devices from a config entry.
+
+    Creates an OasisDeviceImageEntity for each device in the entry's runtime data and registers them with Home Assistant.
+
+    Parameters:
+        hass (HomeAssistant): Home Assistant core instance.
+        entry (OasisDeviceConfigEntry): Config entry containing runtime data and device registrations.
+        async_add_entities (AddEntitiesCallback): Callback to add created entities to Home Assistant.
+    """
+
+    def make_entities(new_devices: list[OasisDevice]):
+        """
+        Create an Image entity for each OasisDevice using the enclosing config entry's runtime data.
+
+        Parameters:
+            new_devices (list[OasisDevice]): Devices to create image entities for.
+
+        Returns:
+            list[OasisDeviceImageEntity]: A list of image entity instances, one per device.
+        """
+        return [
+            OasisDeviceImageEntity(entry.runtime_data, device, IMAGE)
+            for device in new_devices
+        ]
+
+    setup_platform_from_coordinator(entry, async_add_entities, make_entities)
 
-from . import OasisMiniConfigEntry
-from .coordinator import OasisMiniCoordinator
-from .entity import OasisMiniEntity
-from .pyoasismini.const import TRACKS
-from .pyoasismini.utils import draw_svg
 
 IMAGE = ImageEntityDescription(key="image", name=None)
 
 
-class OasisMiniImageEntity(OasisMiniEntity, ImageEntity):
-    """Oasis Mini image entity."""
+class OasisDeviceImageEntity(OasisDeviceEntity, ImageEntity):
+    """Oasis device image entity."""
 
-    _attr_content_type = "image/svg+xml"
     _track_id: int | None = None
     _progress: int = 0
 
     def __init__(
-        self, coordinator: OasisMiniCoordinator, description: ImageEntityDescription
+        self,
+        coordinator: OasisDeviceCoordinator,
+        device: OasisDevice,
+        description: ImageEntityDescription,
     ) -> None:
-        """Initialize the entity."""
-        super().__init__(coordinator, description)
+        """
+        Create an Oasis device image entity tied to a coordinator and a specific device.
+
+        Initializes the entity with the provided coordinator, device, and image description and synchronizes its initial state from the coordinator.
+
+        Parameters:
+            coordinator (OasisDeviceCoordinator): Coordinator providing updates and Home Assistant context.
+            device (OasisDevice): The Oasis device this entity represents.
+            description (ImageEntityDescription): Metadata describing the image entity.
+        """
+        super().__init__(coordinator, device, description)
         ImageEntity.__init__(self, coordinator.hass)
         self._handle_coordinator_update()
 
     def image(self) -> bytes | None:
-        """Return bytes of image."""
+        """
+        Provide the entity's image bytes, generating and caching an SVG from the device when available.
+
+        If the device cannot produce an SVG, the entity's image URL and last-updated timestamp are set and no bytes are returned. When an SVG is produced, the content type is set to "image/svg+xml" and the SVG bytes are cached for future calls.
+
+        Returns:
+            bytes: The image content bytes, or `None` if no image is available yet.
+        """
         if not self._cached_image:
-            self._cached_image = Image(
-                self.content_type, draw_svg(self.device.track, self._progress, "1")
-            )
+            if (svg := self.device.create_svg()) is None:
+                self._attr_image_url = self.device.track_image_url
+                self._attr_image_last_updated = dt_util.now()
+                return None
+            self._attr_content_type = "image/svg+xml"
+            self._cached_image = Image(self.content_type, svg.encode())
         return self._cached_image.content
 
     @callback
     def _handle_coordinator_update(self) -> None:
-        """Handle updated data from the coordinator."""
-        if (
-            self._track_id != self.device.track_id
-            or (self._progress != self.device.progress and self.device.access_token)
-        ) and (self.device.status == "playing" or self._cached_image is None):
+        """
+        Update image metadata and cached image when the coordinator reports changes to the device's track or progress.
+
+        If the device's track_id or progress changed and updates are allowed (the device is playing or there is no cached image), update image last-updated timestamp, record the new track_id and progress, clear the cached image to force regeneration, and set the image URL to UNDEFINED when the track contains inline SVG content or to the device's track_image_url otherwise. When Home Assistant is available, propagate the update to the base class handler.
+        """
+        device = self.device
+
+        track_changed = self._track_id != device.track_id
+        progress_changed = self._progress != device.progress
+        allow_update = device.status == "playing" or self._cached_image is None
+
+        if (track_changed or progress_changed) and allow_update:
             self._attr_image_last_updated = self.coordinator.last_updated
-            self._track_id = self.device.track_id
-            self._progress = self.device.progress
+            self._track_id = device.track_id
+            self._progress = device.progress
             self._cached_image = None
-            if self.device.track and self.device.track.get("svg_content"):
+
+            if device.track and device.track.get("svg_content"):
                 self._attr_image_url = UNDEFINED
             else:
-                self._attr_image_url = (
-                    f"https://app.grounded.so/uploads/{track['image']}"
-                    if (
-                        track := (self.device.track or TRACKS.get(self.device.track_id))
-                    )
-                    and "image" in track
-                    else None
-                )
+                self._attr_image_url = device.track_image_url
 
         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)])