m/hacs-oasis_mini
1
0
Fork 0
mirror of https://github.com/natekspencer/hacs-oasis_mini.git synced 2025-12-06 18:44:14 -05:00
Code Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Nathan Spencer
2025-11-24 01:09:23 -07:00
committed by GitHub
parent 171a608314
commit 379b6f67f2
40 changed files with 4262 additions and 1263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
custom_components/oasis_mini/pyoasiscontrol/clients/transport.py Normal file
View File

@@ -0,0 +1,222 @@
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:
"""
Retrieve the MAC address of the specified Oasis device.
Parameters:
device (OasisDevice): The target device to query.
Returns:
str | None: The device's MAC address as a string, or `None` if the MAC address is unavailable.
"""
async def async_send_auto_clean_command(
self, device: OasisDevice, auto_clean: bool
) -> None:
"""
Enable or disable the device's auto-clean mode.
Parameters:
device (OasisDevice): The target Oasis device to send the command to.
auto_clean (bool): `True` to enable auto-clean mode, `False` to disable it.
"""
async def async_send_ball_speed_command(
self,
device: OasisDevice,
speed: int,
) -> None:
"""
Set the device's ball speed to the specified value.
Parameters:
device (OasisDevice): Target Oasis device to send the command to.
speed (int): Desired ball speed value for the device.
"""
async def async_send_led_command(
self,
device: OasisDevice,
led_effect: str,
color: str,
led_speed: int,
brightness: int,
) -> None:
"""
Configure the device's LED effect, color, speed, and brightness.
Parameters:
device (OasisDevice): Target Oasis device to receive the LED command.
led_effect (str): Name or identifier of the LED effect to apply.
color (str): Color for the LED effect (format depends on implementation, e.g., hex code or color name).
led_speed (int): Effect speed; larger values increase the animation speed.
brightness (int): Brightness level as a percentage from 0 to 100.
"""
async def async_send_sleep_command(self, device: OasisDevice) -> None:
"""
Put the specified Oasis device into sleep mode.
Parameters:
device (OasisDevice): The target Oasis device to send the sleep command to.
"""
async def async_send_move_job_command(
self,
device: OasisDevice,
from_index: int,
to_index: int,
) -> None:
"""
Move a job within the device's job list from one index to another.
Parameters:
device (OasisDevice): Target Oasis device.
from_index (int): Source index of the job in the device's job list.
to_index (int): Destination index to move the job to.
"""
async def async_send_change_track_command(
self,
device: OasisDevice,
index: int,
) -> None:
"""
Change the device's current track to the specified track index.
Parameters:
device (OasisDevice): The target Oasis device to receive the command.
index (int): The index of the track to select on the device.
"""
async def async_send_add_joblist_command(
self,
device: OasisDevice,
tracks: list[int],
) -> None:
"""
Add the given sequence of track indices to the device's job list.
Parameters:
device (OasisDevice): Target Oasis device to receive the new jobs.
tracks (list[int]): Ordered list of track indices to append to the device's job list.
"""
async def async_send_set_playlist_command(
self,
device: OasisDevice,
playlist: list[int],
) -> None:
"""
Set the device's current playlist to the provided sequence of track indices.
Parameters:
device (OasisDevice): The target Oasis device to receive the playlist.
playlist (list[int]): Sequence of track indices in the desired playback order.
"""
async def async_send_set_repeat_playlist_command(
self,
device: OasisDevice,
repeat: bool,
) -> None:
"""
Set whether the device should repeat the current playlist.
Parameters:
repeat (bool): True to enable repeating the current playlist, False to disable it.
"""
async def async_send_set_autoplay_command(
self,
device: OasisDevice,
option: str,
) -> None:
"""
Send a command to configure the device's autoplay behavior.
Parameters:
device (OasisDevice): Target Oasis device to receive the command.
option (str): Autoplay option to set (e.g., "on", "off", "shuffle", or other device-supported mode).
"""
async def async_send_upgrade_command(
self,
device: OasisDevice,
beta: bool,
) -> None:
"""
Initiates a firmware upgrade on the given Oasis device.
If `beta` is True, requests the device to use the beta upgrade channel; otherwise requests the stable channel.
Parameters:
device (OasisDevice): Target device to upgrade.
beta (bool): Whether to use the beta upgrade channel (`True`) or the stable channel (`False`).
"""
async def async_send_play_command(self, device: OasisDevice) -> None:
"""
Send a play command to the specified Oasis device.
Parameters:
device (OasisDevice): The target device to instruct to start playback.
"""
async def async_send_pause_command(self, device: OasisDevice) -> None:
"""
Pause playback on the specified Oasis device.
This sends a pause command to the device so it stops current playback.
"""
async def async_send_stop_command(self, device: OasisDevice) -> None:
"""
Send a stop command to the specified Oasis device to halt playback.
Parameters:
device (OasisDevice): The target Oasis device to receive the stop command.
"""
async def async_send_reboot_command(self, device: OasisDevice) -> None:
"""
Send a reboot command to the specified Oasis device.
Parameters:
device (OasisDevice): The target Oasis device to reboot.
"""
async def async_get_all(self, device: OasisDevice) -> None:
"""
Fetch comprehensive device data for the specified Oasis device.
This method triggers retrieval of all relevant information (configuration, status, and runtime data) for the given device so the client's representation of that device can be refreshed.
Parameters:
device (OasisDevice): Target device whose data should be fetched and refreshed.
"""
async def async_get_status(self, device: OasisDevice) -> None:
"""
Retrieve the current runtime status for the specified Oasis device.
Implementations should query the device for its current state (for example: playback, LED settings, job/track lists, and connectivity) and update any client-side representation or caches as needed.
Parameters:
device (OasisDevice): The target device to query.
"""