harbor-python 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

harbor/__init__.py

@@ -1,6 +1,7 @@
 from .config import HarborCameraConfig
 from .core import Harbor
 from .data.mqtt_models import (
+    GetCameraSettingsRequest,
     HeartbeatEvent,
     LocalLivekitHeartbeatEvent,
     MotionDetectedEvent,
@@ -49,6 +50,7 @@ __all__ = [
     "MotionDetectedUpdate",
     "ViewerInfo",
     "parse_message",
+    "GetCameraSettingsRequest",
     "HeartbeatEvent",
     "LocalLivekitHeartbeatEvent",
     "SettingsEvent",

harbor/core.py

@@ -2,8 +2,9 @@ import logging
 from typing import Any
 
 from .config import HarborCameraConfig
+from .data.mqtt_models import SettingsEvent
 from .device import HarborDevice
-from .mqtt import HarborMQTTClient
+from .mqtt import DEFAULT_INITIAL_COMMANDS, HarborMQTTClient
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -32,12 +33,13 @@ class Harbor:
         if config.serial in self._clients:
             _LOGGER.warning("Camera connection already exists: %s", config.serial)
             return
-        topics = list(self._topics_cache)
+        topics = list({*self._topics_cache, f"cameras/{config.serial}/responses/#"})
         client = HarborMQTTClient(
             config=config,
             topics=topics,
             message_handler=self.handle_message,
             client_id=f"harbor-client-{config.serial}",
+            initial_commands=DEFAULT_INITIAL_COMMANDS,
         )
         self._clients[config.serial] = client
         _LOGGER.info("Added MQTT client for camera: %s", config.serial)
@@ -54,6 +56,35 @@ class Harbor:
         for device in self._devices.values():
             device.shutdown()
 
+    async def publish_camera_command(
+        self,
+        serial: str,
+        command: str,
+        payload: Any,
+    ) -> None:
+        """Publish a command to a camera."""
+        await self._get_client(serial).publish_command(command, payload)
+
+    async def request_camera_command(
+        self,
+        serial: str,
+        command: str,
+        payload: dict[str, Any],
+        *,
+        timeout: float = 10.0,
+    ) -> Any:
+        """Publish a command to a camera and wait for the matching response."""
+        return await self._get_client(serial).request_command(command, payload, timeout=timeout)
+
+    async def get_camera_settings(
+        self,
+        serial: str,
+        *,
+        timeout: float = 10.0,
+    ) -> SettingsEvent:
+        """Request the camera settings payload."""
+        return await self._get_client(serial).get_settings(timeout=timeout)
+
     async def handle_message(self, topic: str, payload: Any) -> None:
         """
         Central message handler.
@@ -61,3 +92,9 @@ class Harbor:
         """
         for device in self._devices.values():
             await device.handle_message(topic, payload)
+
+    def _get_client(self, serial: str) -> HarborMQTTClient:
+        try:
+            return self._clients[serial]
+        except KeyError as exc:
+            raise KeyError(f"No camera connection exists for serial {serial!r}") from exc

harbor/data/mqtt_models.py

@@ -8,7 +8,7 @@ from pydantic import BaseModel, ConfigDict, Field
 class HarborMQTTPayload(BaseModel):
     """Base model for Harbor MQTT payloads."""
 
-    model_config = ConfigDict(extra="allow")
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
 
 
 class LocalLivekitHeartbeatEvent(HarborMQTTPayload):
@@ -82,14 +82,22 @@ class SettingsEvent(HarborMQTTPayload):
     """Payload for a settings event."""
 
     client: str | None = None
-    is_updating: bool | None = None
+    is_updating: bool | None = Field(default=None, alias="isUpdating")
     seq: str | None = None
     settings: Settings | None = None
     state: SettingsState | None = None
-    triggered_by: str | None = None
+    triggered_by: str | None = Field(default=None, alias="triggeredBy")
     updated: dict[str, Any] = Field(default_factory=dict)
 
 
+class GetCameraSettingsRequest(HarborMQTTPayload):
+    """Payload for the get-settings camera command."""
+
+    seq: str
+    client: str
+    triggered_by: str = Field(alias="triggeredBy")
+
+
 class ViewerJoinedEvent(HarborMQTTPayload):
     """Payload for a viewer joined event."""
 

harbor/devices/camera.py

@@ -23,9 +23,10 @@ DEFAULT_EVENT_ACTIVE_SECONDS = 5.0
 # Known values for enumerated state fields. The device reports these in
 # mixed/upper case (e.g. "PLAYING", "GOOD"); they are normalized to the
 # lowercase values below before being stored in ``HarborDeviceState.values``.
-# A value outside these sets is still stored lowercased (and logged once),
-# so consumers that declare options up front should treat these sets as the
-# baseline, not a hard guarantee.
+# A value outside these sets is mapped to ``UNKNOWN_ENUM_VALUE`` (and logged
+# once), so a stored enum value is always a member of its set. Consumers can
+# rely on that guarantee instead of clamping the value themselves.
+UNKNOWN_ENUM_VALUE = "unknown"
 SPEAKER_STATES = frozenset({"idle", "muted", "off", "paused", "playing", "unknown"})
 STREAM_QUALITIES = frozenset({"excellent", "fair", "good", "poor", "unknown"})
 
@@ -46,7 +47,10 @@ class HarborCamera(HarborDevice):
     def get_topics(self) -> list[str]:
         """Return topics that should be subscribed for this device."""
 
-        return [f"cameras/{self.serial}/events/#"]
+        return [
+            f"cameras/{self.serial}/events/#",
+            f"cameras/{self.serial}/responses/#",
+        ]
 
     def _apply_event(self, event: HarborEvent) -> None:
         """Apply a Harbor event to camera state, including camera-only events."""
@@ -99,21 +103,28 @@ class HarborCamera(HarborDevice):
         value: str | None,
         known_values: frozenset[str],
     ) -> str | None:
-        """Normalize an enumerated device value to a stable lowercase string."""
+        """Normalize an enumerated device value to a known lowercase member.
+
+        Returns ``None`` only when the device omitted the field. A value that
+        does not match ``known_values`` is mapped to ``UNKNOWN_ENUM_VALUE`` so
+        callers can rely on the result always being a member of the set.
+        """
         if value is None:
             return None
         normalized = value.strip().lower()
         if not normalized:
             return None
-        if normalized not in known_values and (field_name, normalized) not in self._unexpected_enum_values:
-            self._unexpected_enum_values.add((field_name, normalized))
-            _LOGGER.warning(
-                "Camera %s reported unexpected %s value %r (known values: %s)",
-                self.serial,
-                field_name,
-                normalized,
-                sorted(known_values),
-            )
+        if normalized not in known_values:
+            if (field_name, normalized) not in self._unexpected_enum_values:
+                self._unexpected_enum_values.add((field_name, normalized))
+                _LOGGER.warning(
+                    "Camera %s reported unexpected %s value %r (known values: %s)",
+                    self.serial,
+                    field_name,
+                    normalized,
+                    sorted(known_values),
+                )
+            return UNKNOWN_ENUM_VALUE
         return normalized
 
     def _apply_viewer_joined(self, viewer: ViewerInfo | None) -> None:

harbor/events.py

@@ -178,7 +178,7 @@ def parse_topic(
         return None, None, None
 
     root, serial, event_root, *rest = parts
-    if event_root != "events" or not rest:
+    if event_root not in {"events", "responses"} or not rest:
         return None, None, None
 
     if root == "cameras":
@@ -336,7 +336,7 @@ def parse_message(
             )
         return RawEventUpdate(payload=raw_payload, **base_kwargs)
 
-    if event_key == "settings":
+    if event_key in {"settings", "get_settings"}:
         if typed_payload := _validate_payload(SettingsEvent, raw_payload, topic):
             return SettingsUpdate(payload=typed_payload, **base_kwargs)
         return RawEventUpdate(payload=raw_payload, **base_kwargs)

harbor/mqtt.py

@@ -4,15 +4,21 @@ import logging
 import sys
 from collections.abc import Awaitable, Callable
 from typing import Any
+from uuid import uuid4
 
 from aiomqtt import Client, MqttError
 
 from .config import HarborCameraConfig
+from .data.mqtt_models import GetCameraSettingsRequest, SettingsEvent
 from .utils import get_camera_host, get_ssl_cache_key, get_ssl_context
 
 _LOGGER = logging.getLogger(__name__)
 
 DEFAULT_CONNECTION_GRACE_PERIOD = 90.0
+DEFAULT_COMMAND_QOS = 2
+DEFAULT_REQUEST_TIMEOUT = 10.0
+GET_SETTINGS_COMMAND = "get-settings"
+DEFAULT_INITIAL_COMMANDS = (GET_SETTINGS_COMMAND,)
 
 
 class HarborMQTTClient:
@@ -25,6 +31,7 @@ class HarborMQTTClient:
         ssl_context_cache: dict | None = None,
         on_connection_change: Callable[[bool], Awaitable[None]] | None = None,
         connection_grace_period: float = DEFAULT_CONNECTION_GRACE_PERIOD,
+        initial_commands: list[str] | tuple[str, ...] | None = None,
     ) -> None:
         """Initialize the MQTT client.
 
@@ -42,9 +49,12 @@ class HarborMQTTClient:
         self.ssl_context_cache = ssl_context_cache or {}
         self.on_connection_change = on_connection_change
         self.connection_grace_period = connection_grace_period
+        self.initial_commands = tuple(initial_commands or ())
         self.connected: bool = False
         self._stop_event = asyncio.Event()
         self._task: asyncio.Task | None = None
+        self._client: Client | None = None
+        self._pending_responses: dict[str, asyncio.Future[Any]] = {}
         self._reported_connected: bool | None = None
         self._disconnect_grace_task: asyncio.Task | None = None
 
@@ -55,6 +65,23 @@ class HarborMQTTClient:
             payload = payload_raw
 
         await self.message_handler(topic, payload)
+        self._resolve_pending_response(topic, payload)
+
+    def _resolve_pending_response(self, topic: str, payload: Any) -> None:
+        """Resolve a pending request when a camera response echoes its seq."""
+        if not topic.startswith(f"cameras/{self.config.serial}/responses/"):
+            return
+        if not isinstance(payload, dict):
+            return
+
+        seq = payload.get("seq")
+        if not isinstance(seq, str):
+            return
+
+        future = self._pending_responses.pop(seq, None)
+        if future is None or future.done():
+            return
+        future.set_result(payload)
 
     async def _set_connected(self, connected: bool) -> None:
         """Update the raw connection flag and debounce listener notifications."""
@@ -108,6 +135,12 @@ class HarborMQTTClient:
     def _invalidate_ssl_cache(self) -> None:
         self.ssl_context_cache.pop(get_ssl_cache_key(self.config), None)
 
+    def _fail_pending_responses(self, exc: Exception) -> None:
+        for future in self._pending_responses.values():
+            if not future.done():
+                future.set_exception(exc)
+        self._pending_responses.clear()
+
     async def run(self) -> None:
         reconnect_delay = 2
 
@@ -143,6 +176,7 @@ class HarborMQTTClient:
                         timeout=10,
                         identifier=self.client_id,
                     ) as client:
+                        self._client = client
                         _LOGGER.info(
                             "Harbor: MQTT connected to %s:%s for camera %s",
                             host,
@@ -159,6 +193,8 @@ class HarborMQTTClient:
                                     self.config.serial,
                                 )
 
+                            await self._publish_initial_commands()
+
                             async for message in client.messages:
                                 if self._stop_event.is_set():
                                     break
@@ -177,6 +213,8 @@ class HarborMQTTClient:
 
                             reconnect_delay = 2
                         finally:
+                            self._client = None
+                            self._fail_pending_responses(ConnectionError("Harbor MQTT client disconnected"))
                             await self._set_connected(False)
 
                 except TimeoutError as e:
@@ -247,9 +285,131 @@ class HarborMQTTClient:
             _LOGGER.info("Harbor: MQTT client stopped for camera %s", self.config.serial)
         # An intentional stop is a stable disconnect: skip the grace period.
         self._cancel_disconnect_grace()
+        self._client = None
+        self._fail_pending_responses(ConnectionError("Harbor MQTT client stopped"))
         if self._reported_connected:
             await self._notify_connection_change(False)
 
+    async def publish(
+        self,
+        topic: str,
+        payload: Any,
+        *,
+        qos: int = DEFAULT_COMMAND_QOS,
+        retain: bool = False,
+    ) -> None:
+        """Publish a JSON-compatible payload to a Harbor MQTT topic."""
+        client = self._client
+        if client is None or not self.connected:
+            raise ConnectionError(f"Harbor MQTT client is not connected for camera {self.config.serial}")
+
+        if isinstance(payload, str):
+            payload_raw = payload
+        else:
+            payload_raw = json.dumps(payload, separators=(",", ":"))
+
+        _LOGGER.debug(
+            "Harbor: MQTT publishing to topic '%s' for camera %s: %s",
+            topic,
+            self.config.serial,
+            payload_raw,
+        )
+        await client.publish(topic, payload_raw, qos=qos, retain=retain)
+
+    async def publish_command(
+        self,
+        command: str,
+        payload: Any,
+        *,
+        qos: int = DEFAULT_COMMAND_QOS,
+    ) -> None:
+        """Publish a camera command using the app's command topic layout."""
+        await self.publish(f"cameras/{self.config.serial}/{command}", payload, qos=qos)
+
+    async def _publish_initial_commands(self) -> None:
+        """Publish configured one-shot state population commands after connect."""
+        for command in self.initial_commands:
+            try:
+                if command == GET_SETTINGS_COMMAND:
+                    await self.publish_command(command, self._build_get_settings_payload())
+                else:
+                    _LOGGER.warning(
+                        "Harbor: skipping unsupported initial command %s for camera %s",
+                        command,
+                        self.config.serial,
+                    )
+            except Exception:
+                _LOGGER.exception(
+                    "Harbor: failed to publish initial command %s for camera %s",
+                    command,
+                    self.config.serial,
+                )
+
+    def _build_get_settings_payload(
+        self,
+        *,
+        client: str | None = None,
+        triggered_by: str | None = None,
+        seq: str | None = None,
+    ) -> dict[str, Any]:
+        request = GetCameraSettingsRequest(
+            seq=seq or _generate_seq(),
+            client=client or self.client_id or f"harbor-client-{self.config.serial}",
+            triggered_by=triggered_by or "harbor-python",
+        )
+        return request.model_dump(by_alias=True)
+
+    async def request_command(
+        self,
+        command: str,
+        payload: dict[str, Any],
+        *,
+        seq: str | None = None,
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+        qos: int = DEFAULT_COMMAND_QOS,
+    ) -> Any:
+        """Publish a command and wait for a response carrying the same seq."""
+        request_seq = seq or _generate_seq()
+        payload = {**payload, "seq": request_seq}
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[Any] = loop.create_future()
+        self._pending_responses[request_seq] = future
+
+        try:
+            await self.publish_command(command, payload, qos=qos)
+            return await asyncio.wait_for(future, timeout=timeout)
+        except Exception:
+            pending = self._pending_responses.pop(request_seq, None)
+            if pending is not None and not pending.done():
+                pending.cancel()
+            raise
+
+    async def get_settings(
+        self,
+        *,
+        client: str | None = None,
+        triggered_by: str | None = None,
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ) -> SettingsEvent:
+        """Request camera settings via the get-settings command."""
+        seq = _generate_seq()
+        response = await self.request_command(
+            GET_SETTINGS_COMMAND,
+            self._build_get_settings_payload(
+                seq=seq,
+                client=client,
+                triggered_by=triggered_by,
+            ),
+            seq=seq,
+            timeout=timeout,
+        )
+        return SettingsEvent.model_validate(response)
+
     def __del__(self) -> None:
         if self._stop_event and not self._stop_event.is_set():
             self._stop_event.set()
+
+
+def _generate_seq() -> str:
+    """Generate a request sequence string echoed by Harbor responses."""
+    return uuid4().hex

{harbor_python-1.1.0.dist-info → harbor_python-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: harbor-python
-Version: 1.1.0
+Version: 1.2.0
 Summary: A package to locally connect to a Harbor Sleep Camera
 Author: Andres Garcia, Lash-L
 License-Expression: Apache-2.0

harbor_python-1.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+harbor/__init__.py,sha256=F2Yo9T1Hpf0lSioVAk-m8GJnEh1tLd2En4Mzz9RxczY,1606
+harbor/config.py,sha256=LXMDaTC_0Z9wF_vTXJG9C0vQ0XHXo4EuFL0-Kwa4-S4,1373
+harbor/core.py,sha256=Alm6ojRBCibsQ5xGGyaAOQimi-_kE6Q6fuS2ZAxzaNM,3468
+harbor/device.py,sha256=YvaFWieXJ-EzQJU8VQo_ZERl65CynITTAnMFto-PF_I,5933
+harbor/events.py,sha256=4Y3JT_NP1x8rUR7U6n2-LvAENt9zpqD4jVy28AAYo4Q,20400
+harbor/mqtt.py,sha256=ZhGuR90U449q4OY9WCCJVLIuYVEHrG1uT32EGjux7rU,16712
+harbor/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+harbor/state.py,sha256=jQDLV8zpkLV2f6zR4LuOtk_B5BtGdp-8dq4NyGZCa-8,1210
+harbor/utils.py,sha256=7A3Tn1aZ93SlxRKY-0b-50ntQL4Pw1j5bXwkJvnarpY,3312
+harbor/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+harbor/data/mqtt_models.py,sha256=OF36ZoUCOeoaKp4TPggM6HCbowgtkH1zLFTozVJUZYY,4314
+harbor/devices/camera.py,sha256=ciq8ynsAaZgW0CWYjKiJGAZwk04pNz4uYfnsN0GT0O4,8429
+harbor/devices/monitor.py,sha256=hzx4lu92h3i_34QyYK392gE7CihqERiOZuLhyzDtDk0,452
+harbor_python-1.2.0.dist-info/METADATA,sha256=ZEPjl-fqvicWCUsIa5dbS18zAFgm5YeYXbGUqvMFe9A,688
+harbor_python-1.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+harbor_python-1.2.0.dist-info/licenses/LICENSE,sha256=QEOXEfrOQetemKy4k1WN5XCApJdpiRtyV5jLMSToVVw,11344
+harbor_python-1.2.0.dist-info/RECORD,,

{harbor_python-1.1.0.dist-info → harbor_python-1.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

harbor_python-1.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-harbor/__init__.py,sha256=b43EC904n7dBigKTlU8600P5XxG4Zip0It4I7GVsRDc,1544
-harbor/config.py,sha256=LXMDaTC_0Z9wF_vTXJG9C0vQ0XHXo4EuFL0-Kwa4-S4,1373
-harbor/core.py,sha256=lfO1FAwYKSSW7YZ8fqDdhgpWXS6eA-vL1NgZKmN_H_g,2186
-harbor/device.py,sha256=YvaFWieXJ-EzQJU8VQo_ZERl65CynITTAnMFto-PF_I,5933
-harbor/events.py,sha256=q_WNG_yIkCczOzloe9mDwulgHhXmeQdZFDyyKpCz1Ig,20363
-harbor/mqtt.py,sha256=ZqHVjHaocXtOK6wh0FO6lLF2UJQfDX3W6DG8R9YD30c,10816
-harbor/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-harbor/state.py,sha256=jQDLV8zpkLV2f6zR4LuOtk_B5BtGdp-8dq4NyGZCa-8,1210
-harbor/utils.py,sha256=7A3Tn1aZ93SlxRKY-0b-50ntQL4Pw1j5bXwkJvnarpY,3312
-harbor/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-harbor/data/mqtt_models.py,sha256=yir1maFUxmk_9E2J_JEnTzDJwiAGDdSrbkGN1YaZd_o,4031
-harbor/devices/camera.py,sha256=jjgXFeASsSnQqyGTmhMbeLZJ3zHrdxLAKXG2UwHYWSk,7968
-harbor/devices/monitor.py,sha256=hzx4lu92h3i_34QyYK392gE7CihqERiOZuLhyzDtDk0,452
-harbor_python-1.1.0.dist-info/METADATA,sha256=FodUxQmoYkqajgqYsSxXzrLxHm9W_pdBnXkSs5eIs5s,688
-harbor_python-1.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-harbor_python-1.1.0.dist-info/licenses/LICENSE,sha256=QEOXEfrOQetemKy4k1WN5XCApJdpiRtyV5jLMSToVVw,11344
-harbor_python-1.1.0.dist-info/RECORD,,