harbor-python 1.0.0__tar.gz → 1.2.0__tar.gz

{harbor_python-1.0.0 → harbor_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: harbor-python
-Version: 1.0.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.0.0 → harbor_python-1.2.0}/harbor/__init__.py

@@ -1,6 +1,7 @@
 from .config import HarborCameraConfig
 from .core import Harbor
 from .data.mqtt_models import (
+    GetCameraSettingsRequest,
     HeartbeatEvent,
     LocalLivekitHeartbeatEvent,
     MotionDetectedEvent,
@@ -9,7 +10,7 @@ from .data.mqtt_models import (
     ViewerLeftEvent,
 )
 from .device import HarborDevice
-from .devices.camera import HarborCamera
+from .devices.camera import SPEAKER_STATES, STREAM_QUALITIES, HarborCamera
 from .devices.monitor import HarborMonitor
 from .events import (
     CameraEventUpdate,
@@ -49,6 +50,7 @@ __all__ = [
     "MotionDetectedUpdate",
     "ViewerInfo",
     "parse_message",
+    "GetCameraSettingsRequest",
     "HeartbeatEvent",
     "LocalLivekitHeartbeatEvent",
     "SettingsEvent",
@@ -59,4 +61,6 @@ __all__ = [
     "HarborViewer",
     "HarborEventState",
     "HarborDeviceState",
+    "SPEAKER_STATES",
+    "STREAM_QUALITIES",
 ]

harbor_python-1.2.0/harbor/config.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class HarborCameraConfig:
+    """Connection configuration for a Harbor camera.
+
+    Client certificate material can be provided either as in-memory PEM
+    strings (``cert_pem``/``key_pem``) or as file paths
+    (``cert_path``/``key_path``). PEM strings are preferred for consumers
+    that should not manage certificate files themselves: while building the
+    SSL context the library briefly stages the PEM data in a private
+    temporary directory (0600 files) that is deleted before the build
+    returns, so the caller never handles files. When both are provided, the
+    PEM strings win.
+    """
+
+    serial: str
+    cert_path: str | None = None
+    key_path: str | None = None
+    cert_dir: str | None = None
+
+    ip_address: str | None = None
+
+    cert_pem: str | None = None
+    key_pem: str | None = None
+
+    def __post_init__(self) -> None:
+        if (self.cert_pem is None) != (self.key_pem is None):
+            raise ValueError("cert_pem and key_pem must be provided together")
+        if (self.cert_path is None) != (self.key_path is None):
+            raise ValueError("cert_path and key_path must be provided together")
+        if self.cert_pem is None and self.cert_path is None:
+            raise ValueError("Certificate material is required: provide cert_pem/key_pem or cert_path/key_path")

{harbor_python-1.0.0 → harbor_python-1.2.0}/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_python-1.0.0 → harbor_python-1.2.0}/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_python-1.0.0 → harbor_python-1.2.0}/harbor/devices/camera.py

@@ -20,6 +20,16 @@ _LOGGER = logging.getLogger(__name__)
 DEFAULT_CAMERA_EVENT_KEYS = ("motion_detection", "cry_detection", "noise_detection")
 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 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"})
+
 
 class HarborCamera(HarborDevice):
     """Represents a Harbor camera device."""
@@ -29,6 +39,7 @@ class HarborCamera(HarborDevice):
         super().__init__(config.serial, "camera")
         self.config = config
         self._event_reset_handles: dict[str, asyncio.TimerHandle] = {}
+        self._unexpected_enum_values: set[tuple[str, str]] = set()
 
         for event_key in DEFAULT_CAMERA_EVENT_KEYS:
             self._ensure_camera_event(event_key)
@@ -36,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."""
@@ -60,8 +74,14 @@ class HarborCamera(HarborDevice):
         self._set_state_value("bitrate", payload.bitrate)
         self._set_state_value("wifi_strength", payload.network_bars)
         self._set_state_value("camera_present", payload.camera_present)
-        self._set_state_value("speaker_state", payload.speaker_state)
-        self._set_state_value("stream_quality", payload.stream_quality)
+        self._set_state_value(
+            "speaker_state",
+            self._normalize_enum_value("speaker_state", payload.speaker_state, SPEAKER_STATES),
+        )
+        self._set_state_value(
+            "stream_quality",
+            self._normalize_enum_value("stream_quality", payload.stream_quality, STREAM_QUALITIES),
+        )
         self._set_state_value("app_start_time", payload.app_start_time)
         self._set_state_value("stream_start_time", payload.stream_start_time)
 
@@ -77,6 +97,36 @@ class HarborCamera(HarborDevice):
         }
         self.state.values["num_viewers"] = len(self.state.viewers)
 
+    def _normalize_enum_value(
+        self,
+        field_name: str,
+        value: str | None,
+        known_values: frozenset[str],
+    ) -> str | None:
+        """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:
+            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:
         """Apply a viewer joined update."""
         if viewer is None:

{harbor_python-1.0.0 → harbor_python-1.2.0}/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_python-1.2.0/harbor/mqtt.py

@@ -0,0 +1,415 @@
+import asyncio
+import json
+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:
+    def __init__(
+        self,
+        config: HarborCameraConfig,
+        topics: list[str],
+        message_handler: Callable[[str, Any], Awaitable[None]],
+        client_id: str | None = None,
+        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.
+
+        ``on_connection_change`` fires only on stable connection-state
+        transitions: a disconnect is reported only if the client stays
+        disconnected for ``connection_grace_period`` seconds, so routine
+        TCP flapping never reaches the listener. Set the grace period to 0
+        to report every raw transition. ``connected`` always reflects the
+        raw transport state.
+        """
+        self.config = config
+        self.topics = topics
+        self.message_handler = message_handler
+        self.client_id = client_id
+        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
+
+    async def _handle_message(self, topic: str, payload_raw: str) -> None:
+        try:
+            payload = json.loads(payload_raw)
+        except Exception:
+            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."""
+        if self.connected == connected:
+            return
+        self.connected = connected
+
+        if connected:
+            self._cancel_disconnect_grace()
+            if self._reported_connected is not True:
+                await self._notify_connection_change(True)
+            return
+
+        if self._reported_connected is not True:
+            return
+        if self.connection_grace_period <= 0:
+            await self._notify_connection_change(False)
+            return
+        if self._disconnect_grace_task is None or self._disconnect_grace_task.done():
+            self._disconnect_grace_task = asyncio.create_task(self._disconnect_after_grace())
+
+    async def _disconnect_after_grace(self) -> None:
+        """Report a disconnect only if it survives the grace period."""
+        await asyncio.sleep(self.connection_grace_period)
+        self._disconnect_grace_task = None
+        if not self.connected:
+            _LOGGER.info(
+                "Harbor: camera %s still disconnected after %s second grace period",
+                self.config.serial,
+                self.connection_grace_period,
+            )
+            await self._notify_connection_change(False)
+
+    def _cancel_disconnect_grace(self) -> None:
+        if self._disconnect_grace_task is not None:
+            self._disconnect_grace_task.cancel()
+            self._disconnect_grace_task = None
+
+    async def _notify_connection_change(self, connected: bool) -> None:
+        self._reported_connected = connected
+        if self.on_connection_change is None:
+            return
+        try:
+            await self.on_connection_change(connected)
+        except Exception:
+            _LOGGER.exception(
+                "Harbor: connection-change listener raised for camera %s",
+                self.config.serial,
+            )
+
+    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
+
+        _LOGGER.info("Harbor: MQTT client starting for camera %s", self.config.serial)
+
+        try:
+            while not self._stop_event.is_set():
+                # Fetch the SSL context each attempt so invalidations in the
+                # error handlers below take effect on the next reconnect;
+                # unchanged material is a cheap cache hit.
+                try:
+                    loop = asyncio.get_running_loop()
+                    ssl_ctx = await loop.run_in_executor(None, get_ssl_context, self.config, self.ssl_context_cache)
+                except Exception as e:
+                    _LOGGER.error("Harbor: Failed to create SSL context for camera %s: %s", self.config.serial, e)
+                    # Ensure we clear any partial state
+                    self._invalidate_ssl_cache()
+                    return
+
+                try:
+                    host = get_camera_host(self.config)
+                    _LOGGER.info(
+                        "Harbor: MQTT attempting connection to %s:%s for camera %s",
+                        host,
+                        8884,
+                        self.config.serial,
+                    )
+
+                    async with Client(
+                        hostname=host,
+                        port=8884,
+                        tls_context=ssl_ctx,
+                        timeout=10,
+                        identifier=self.client_id,
+                    ) as client:
+                        self._client = client
+                        _LOGGER.info(
+                            "Harbor: MQTT connected to %s:%s for camera %s",
+                            host,
+                            8884,
+                            self.config.serial,
+                        )
+                        await self._set_connected(True)
+                        try:
+                            if self.topics:
+                                await client.subscribe([(t, 0) for t in self.topics])
+                                _LOGGER.info(
+                                    "Harbor: MQTT subscribed to topics: %s for camera %s",
+                                    self.topics,
+                                    self.config.serial,
+                                )
+
+                            await self._publish_initial_commands()
+
+                            async for message in client.messages:
+                                if self._stop_event.is_set():
+                                    break
+
+                                payload_raw = message.payload.decode("utf-8", errors="replace")
+                                topic = str(message.topic)
+
+                                _LOGGER.debug(
+                                    "Harbor: MQTT message received on topic '%s' from camera %s: %s",
+                                    topic,
+                                    self.config.serial,
+                                    payload_raw,
+                                )
+
+                                await self._handle_message(topic, payload_raw)
+
+                            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:
+                    _LOGGER.warning("Harbor: MQTT connection timeout for %s: %s (reconnecting)", self.config.serial, e)
+                    # Clear SSL context on timeout as it might be a stale session
+                    self._invalidate_ssl_cache()
+
+                except MqttError as e:
+                    _LOGGER.warning("Harbor: MQTT error for %s: %s (reconnecting)", self.config.serial, e)
+                    _LOGGER.info("Harbor: MQTT disconnected from camera %s", self.config.serial)
+                    # Clear SSL context on MQTT error
+                    self._invalidate_ssl_cache()
+
+                except OSError as e:
+                    _LOGGER.warning("Harbor: MQTT OS error for %s: %s (reconnecting)", self.config.serial, e)
+                    # Critical to clear context here for WinError 10065 cleanup
+                    self._invalidate_ssl_cache()
+                except asyncio.CancelledError:
+                    raise
+                except Exception as e:
+                    _LOGGER.error("Harbor: MQTT unexpected error for %s: %s (reconnecting)", self.config.serial, e)
+                    # Clear context on unexpected errors too
+                    self._invalidate_ssl_cache()
+                    import traceback
+
+                    _LOGGER.error(traceback.format_exc())
+
+                try:
+                    _LOGGER.info(
+                        "Harbor: MQTT waiting %s seconds before reconnecting to camera %s",
+                        reconnect_delay,
+                        self.config.serial,
+                    )
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=reconnect_delay)
+                except TimeoutError:
+                    pass
+                reconnect_delay = min(reconnect_delay * 2, 30)
+
+        except asyncio.CancelledError:
+            _LOGGER.info("Harbor: MQTT task cancelled for camera %s", self.config.serial)
+            raise
+
+    async def start(self) -> None:
+        if sys.platform == "win32" and isinstance(asyncio.get_running_loop(), asyncio.ProactorEventLoop):
+            _LOGGER.warning(
+                "Harbor: You are running on Windows with the default ProactorEventLoop. "
+                "This is known to cause issues with aiomqtt. "
+                "Please use WindowsSelectorEventLoopPolicy instead: "
+                "asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())"
+            )
+
+        if self._task and not self._task.done():
+            _LOGGER.info("Harbor: MQTT client already running for camera %s", self.config.serial)
+            return
+        _LOGGER.info("Harbor: MQTT client starting for camera %s", self.config.serial)
+        self._stop_event.clear()
+        self._task = asyncio.create_task(self.run())
+
+    async def stop(self) -> None:
+        _LOGGER.info("Harbor: MQTT client stopping for camera %s", self.config.serial)
+        self._stop_event.set()
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            _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.2.0/harbor/utils.py

@@ -0,0 +1,82 @@
+import hashlib
+import logging
+import os
+import ssl
+import tempfile
+
+from .config import HarborCameraConfig
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def get_camera_host(camera_config: HarborCameraConfig) -> str:
+    if camera_config.ip_address:
+        return camera_config.ip_address
+    return f"harborc-{camera_config.serial}.local"
+
+
+def get_ssl_cache_key(camera_config: HarborCameraConfig) -> str:
+    """Return the cache key for the SSL context built from this config.
+
+    Keyed off the certificate material itself so a config carrying new
+    credentials never reuses a stale context.
+    """
+    if camera_config.cert_pem is not None and camera_config.key_pem is not None:
+        digest = hashlib.sha256()
+        digest.update(camera_config.cert_pem.encode())
+        digest.update(b"\x00")
+        digest.update(camera_config.key_pem.encode())
+        return f"pem:{digest.hexdigest()}"
+    return f"path:{camera_config.cert_path}:{camera_config.key_path}"
+
+
+def _write_private_file(path: str, data: str) -> None:
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    # PEM must stay byte-exact: no platform newline translation or locale encoding.
+    with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(data)
+
+
+def build_ssl_context(camera_config: HarborCameraConfig) -> ssl.SSLContext:
+    ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
+
+    if camera_config.cert_pem is not None and camera_config.key_pem is not None:
+        _LOGGER.info("Harbor: Building SSL context from in-memory PEM data for camera %s", camera_config.serial)
+        # ssl.SSLContext.load_cert_chain only accepts file paths, so stage the
+        # PEM data in a short-lived private temp dir that is removed before
+        # this function returns.
+        with tempfile.TemporaryDirectory(prefix="harbor-tls-") as tmp_dir:
+            cert_file = os.path.join(tmp_dir, "cert.pem")
+            key_file = os.path.join(tmp_dir, "key.pem")
+            _write_private_file(cert_file, camera_config.cert_pem)
+            _write_private_file(key_file, camera_config.key_pem)
+            ctx.load_cert_chain(certfile=cert_file, keyfile=key_file)
+    else:
+        _LOGGER.info(
+            "Harbor: Building SSL context with cert_path=%s, key_path=%s",
+            camera_config.cert_path,
+            camera_config.key_path,
+        )
+        if camera_config.cert_path is None or camera_config.key_path is None:
+            raise ValueError("HarborCameraConfig has no certificate material")
+        ctx.load_cert_chain(certfile=camera_config.cert_path, keyfile=camera_config.key_path)
+
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
+def get_ssl_context(camera_config: HarborCameraConfig, cache: dict | None = None) -> ssl.SSLContext:
+    if cache is None:
+        _LOGGER.info("Harbor: Creating new SSL context (no cache)")
+        return build_ssl_context(camera_config)
+
+    key = get_ssl_cache_key(camera_config)
+    if key in cache:
+        _LOGGER.debug("Harbor: Returning cached SSL context for camera %s", camera_config.serial)
+        return cache[key]
+
+    _LOGGER.info("Harbor: Creating new SSL context for camera %s", camera_config.serial)
+    ctx = build_ssl_context(camera_config)
+    cache[key] = ctx
+    return ctx

{harbor_python-1.0.0 → harbor_python-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "harbor-python"
-version = "1.0.0"
+version = "1.2.0"
 description = "A package to locally connect to a Harbor Sleep Camera"
 authors = [{name="Andres Garcia"},{name = "Lash-L"}]
 readme = "README.md"

harbor_python-1.0.0/harbor/config.py

@@ -1,11 +0,0 @@
-from dataclasses import dataclass
-
-
-@dataclass(frozen=True)
-class HarborCameraConfig:
-    serial: str
-    cert_path: str
-    key_path: str
-    cert_dir: str
-
-    ip_address: str | None = None

harbor_python-1.0.0/harbor/mqtt.py

@@ -1,201 +0,0 @@
-import asyncio
-import json
-import logging
-import sys
-from collections.abc import Awaitable, Callable
-from typing import Any
-
-from aiomqtt import Client, MqttError
-
-from .config import HarborCameraConfig
-from .utils import get_camera_host, get_ssl_context
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class HarborMQTTClient:
-    def __init__(
-        self,
-        config: HarborCameraConfig,
-        topics: list[str],
-        message_handler: Callable[[str, Any], Awaitable[None]],
-        client_id: str | None = None,
-        ssl_context_cache: dict | None = None,
-        on_connection_change: Callable[[bool], Awaitable[None]] | None = None,
-    ) -> None:
-        self.config = config
-        self.topics = topics
-        self.message_handler = message_handler
-        self.client_id = client_id
-        self.ssl_context_cache = ssl_context_cache or {}
-        self.on_connection_change = on_connection_change
-        self.connected: bool = False
-        self._stop_event = asyncio.Event()
-        self._task: asyncio.Task | None = None
-
-    async def _handle_message(self, topic: str, payload_raw: str) -> None:
-        try:
-            payload = json.loads(payload_raw)
-        except Exception:
-            payload = payload_raw
-
-        await self.message_handler(topic, payload)
-
-    async def _set_connected(self, connected: bool) -> None:
-        """Update the connection flag and notify the listener if it changed."""
-        if self.connected == connected:
-            return
-        self.connected = connected
-        if self.on_connection_change is None:
-            return
-        try:
-            await self.on_connection_change(connected)
-        except Exception:
-            _LOGGER.exception(
-                "Harbor: connection-change listener raised for camera %s",
-                self.config.serial,
-            )
-
-    async def run(self) -> None:
-        try:
-            loop = asyncio.get_running_loop()
-            ssl_ctx = await loop.run_in_executor(None, get_ssl_context, self.config, self.ssl_context_cache)
-        except Exception as e:
-            _LOGGER.error("Harbor: Failed to create SSL context for camera %s: %s", self.config.serial, e)
-            # Ensure we clear any partial state
-            if self.config.serial in self.ssl_context_cache:
-                del self.ssl_context_cache[self.config.serial]
-            return
-
-        reconnect_delay = 2
-
-        _LOGGER.info("Harbor: MQTT client starting for camera %s", self.config.serial)
-
-        try:
-            while not self._stop_event.is_set():
-                try:
-                    host = get_camera_host(self.config)
-                    _LOGGER.info(
-                        "Harbor: MQTT attempting connection to %s:%s for camera %s",
-                        host,
-                        8884,
-                        self.config.serial,
-                    )
-
-                    async with Client(
-                        hostname=host,
-                        port=8884,
-                        tls_context=ssl_ctx,
-                        timeout=10,
-                        identifier=self.client_id,
-                    ) as client:
-                        _LOGGER.info(
-                            "Harbor: MQTT connected to %s:%s for camera %s",
-                            host,
-                            8884,
-                            self.config.serial,
-                        )
-                        await self._set_connected(True)
-                        try:
-                            if self.topics:
-                                await client.subscribe([(t, 0) for t in self.topics])
-                                _LOGGER.info(
-                                    "Harbor: MQTT subscribed to topics: %s for camera %s",
-                                    self.topics,
-                                    self.config.serial,
-                                )
-
-                            async for message in client.messages:
-                                if self._stop_event.is_set():
-                                    break
-
-                                payload_raw = message.payload.decode("utf-8", errors="replace")
-                                topic = str(message.topic)
-
-                                _LOGGER.debug(
-                                    "Harbor: MQTT message received on topic '%s' from camera %s: %s",
-                                    topic,
-                                    self.config.serial,
-                                    payload_raw,
-                                )
-
-                                await self._handle_message(topic, payload_raw)
-
-                            reconnect_delay = 2
-                        finally:
-                            await self._set_connected(False)
-
-                except TimeoutError as e:
-                    _LOGGER.warning("Harbor: MQTT connection timeout for %s: %s (reconnecting)", self.config.serial, e)
-                    # Clear SSL context on timeout as it might be a stale session
-                    if self.config.serial in self.ssl_context_cache:
-                        del self.ssl_context_cache[self.config.serial]
-
-                except MqttError as e:
-                    _LOGGER.warning("Harbor: MQTT error for %s: %s (reconnecting)", self.config.serial, e)
-                    _LOGGER.info("Harbor: MQTT disconnected from camera %s", self.config.serial)
-                    # Clear SSL context on MQTT error
-                    if self.config.serial in self.ssl_context_cache:
-                        del self.ssl_context_cache[self.config.serial]
-
-                except OSError as e:
-                    _LOGGER.warning("Harbor: MQTT OS error for %s: %s (reconnecting)", self.config.serial, e)
-                    # Critical to clear context here for WinError 10065 cleanup
-                    if self.config.serial in self.ssl_context_cache:
-                        del self.ssl_context_cache[self.config.serial]
-                except asyncio.CancelledError:
-                    raise
-                except Exception as e:
-                    _LOGGER.error("Harbor: MQTT unexpected error for %s: %s (reconnecting)", self.config.serial, e)
-                    # Clear context on unexpected errors too
-                    if self.config.serial in self.ssl_context_cache:
-                        del self.ssl_context_cache[self.config.serial]
-                    import traceback
-
-                    _LOGGER.error(traceback.format_exc())
-
-                try:
-                    _LOGGER.info(
-                        "Harbor: MQTT waiting %s seconds before reconnecting to camera %s",
-                        reconnect_delay,
-                        self.config.serial,
-                    )
-                    await asyncio.wait_for(self._stop_event.wait(), timeout=reconnect_delay)
-                except TimeoutError:
-                    pass
-                reconnect_delay = min(reconnect_delay * 2, 30)
-
-        except asyncio.CancelledError:
-            _LOGGER.info("Harbor: MQTT task cancelled for camera %s", self.config.serial)
-            raise
-
-    async def start(self) -> None:
-        if sys.platform == "win32" and isinstance(asyncio.get_running_loop(), asyncio.ProactorEventLoop):
-            _LOGGER.warning(
-                "Harbor: You are running on Windows with the default ProactorEventLoop. "
-                "This is known to cause issues with aiomqtt. "
-                "Please use WindowsSelectorEventLoopPolicy instead: "
-                "asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())"
-            )
-
-        if self._task and not self._task.done():
-            _LOGGER.info("Harbor: MQTT client already running for camera %s", self.config.serial)
-            return
-        _LOGGER.info("Harbor: MQTT client starting for camera %s", self.config.serial)
-        self._stop_event.clear()
-        self._task = asyncio.create_task(self.run())
-
-    async def stop(self) -> None:
-        _LOGGER.info("Harbor: MQTT client stopping for camera %s", self.config.serial)
-        self._stop_event.set()
-        if self._task:
-            self._task.cancel()
-            try:
-                await self._task
-            except asyncio.CancelledError:
-                pass
-            _LOGGER.info("Harbor: MQTT client stopped for camera %s", self.config.serial)
-
-    def __del__(self) -> None:
-        if self._stop_event and not self._stop_event.is_set():
-            self._stop_event.set()

harbor_python-1.0.0/harbor/utils.py

@@ -1,39 +0,0 @@
-import logging
-import ssl
-
-from .config import HarborCameraConfig
-
-_LOGGER = logging.getLogger(__name__)
-
-
-def get_camera_host(camera_config: HarborCameraConfig) -> str:
-    if camera_config.ip_address:
-        return camera_config.ip_address
-    return f"harborc-{camera_config.serial}.local"
-
-
-def build_ssl_context(camera_config: HarborCameraConfig) -> ssl.SSLContext:
-    _LOGGER.info(
-        "Harbor: Building SSL context with cert_path=%s, key_path=%s", camera_config.cert_path, camera_config.key_path
-    )
-    ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
-    ctx.load_cert_chain(certfile=camera_config.cert_path, keyfile=camera_config.key_path)
-    ctx.check_hostname = False
-    ctx.verify_mode = ssl.CERT_NONE
-    return ctx
-
-
-def get_ssl_context(camera_config: HarborCameraConfig, cache: dict | None = None) -> ssl.SSLContext:
-    if cache is None:
-        _LOGGER.info("Harbor: Creating new SSL context (no cache)")
-        return build_ssl_context(camera_config)
-
-    key = camera_config.serial
-    if key in cache:
-        _LOGGER.debug("Harbor: Returning cached SSL context for camera %s", camera_config.serial)
-        return cache[key]
-
-    _LOGGER.info("Harbor: Creating new SSL context for camera %s", camera_config.serial)
-    ctx = build_ssl_context(camera_config)
-    cache[key] = ctx
-    return ctx