pyezvizapi 1.0.1.6__py3-none-any.whl → 1.0.1.7__py3-none-any.whl

pyezvizapi/__init__.py

@@ -28,7 +28,7 @@ from .exceptions import (
     PyEzvizError,
 )
 from .light_bulb import EzvizLightBulb
-from .mqtt import MQTTClient
+from .mqtt import EzvizToken, MQTTClient, MqttData, ServiceUrls
 from .test_cam_rtsp import TestRTSPAuth
 
 __all__ = [
@@ -47,14 +47,17 @@ __all__ = [
     "EzvizCamera",
     "EzvizClient",
     "EzvizLightBulb",
+    "EzvizToken",
     "HTTPError",
     "IntelligentDetectionSmartApp",
     "InvalidHost",
     "InvalidURL",
     "MQTTClient",
     "MessageFilterType",
+    "MqttData",
     "NightVisionMode",
     "PyEzvizError",
+    "ServiceUrls",
     "SoundMode",
     "SupportExt",
     "TestRTSPAuth",

pyezvizapi/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from datetime import datetime
 import hashlib
 import json
@@ -79,6 +80,7 @@ from .exceptions import (
     PyEzvizError,
 )
 from .light_bulb import EzvizLightBulb
+from .mqtt import MQTTClient
 from .utils import convert_to_dict, deep_merge
 
 _LOGGER = logging.getLogger(__name__)
@@ -112,6 +114,7 @@ class EzvizClient:
         self._timeout = timeout
         self._cameras: dict[str, Any] = {}
         self._light_bulbs: dict[str, Any] = {}
+        self.mqtt_client: MQTTClient | None = None
 
     def _login(self, smscode: int | None = None) -> dict[Any, Any]:
         """Login to Ezviz API."""
@@ -2488,6 +2491,19 @@ class EzvizClient:
 
         return True
 
+    def get_mqtt_client(
+        self, on_message_callback: Callable[[dict[str, Any]], None] | None = None
+    ) -> MQTTClient:
+        """Return a configured MQTTClient using this client's session."""
+        if self.mqtt_client is None:
+            self.mqtt_client = MQTTClient(
+                token=self._token,
+                session=self._session,
+                timeout=self._timeout,
+                on_message_callback=on_message_callback,
+            )
+        return self.mqtt_client
+
     def _get_page_list(self) -> Any:
         """Get ezviz device info broken down in sections."""
         return self._api_get_pagelist(

pyezvizapi/constants.py

@@ -2,7 +2,9 @@
 
 from enum import Enum, unique
 
-FEATURE_CODE = "1fc28fa018178a1cd1c091b13b2f9f02"
+from .utils import generate_unique_code
+
+FEATURE_CODE = generate_unique_code()
 XOR_KEY = b"\x0c\x0eJ^X\x15@Rr"
 DEFAULT_TIMEOUT = 25
 MAX_RETRIES = 3

pyezvizapi/mqtt.py

@@ -1,12 +1,32 @@
-"""Ezviz cloud MQTT client for push messages."""
+"""Ezviz cloud MQTT client for push messages.
+
+Synchronous MQTT client tailored for EZVIZ push notifications as used by
+`pyezvizapi` and Home Assistant integrations. Handles the EZVIZ registration
+flow, starts/stops push, maintains a long-lived MQTT connection, and decodes
+incoming payloads into a structured form.
+
+This module is intentionally synchronous (uses `requests` and
+`paho-mqtt`'s background network thread via `loop_start()`), which keeps
+integration code simple. If you later migrate to an async HA integration,
+wrap the blocking calls with `hass.async_add_executor_job`.
+
+Example:
+    >>> client = MQTTClient(token)
+    >>> client.connect()
+    >>> # ... handle callbacks or read client.messages_by_device ...
+    >>> client.stop()
+
+"""
+
 from __future__ import annotations
 
 import base64
+from collections import OrderedDict
+from collections.abc import Callable
+from contextlib import suppress
 import json
 import logging
-import threading
-import time
-from typing import Any
+from typing import Any, Final, TypedDict
 
 import paho.mqtt.client as mqtt
 import requests
@@ -16,111 +36,314 @@ from .api_endpoints import (
     API_ENDPOINT_START_MQTT,
     API_ENDPOINT_STOP_MQTT,
 )
-from .constants import (
-    APP_SECRET,
-    DEFAULT_TIMEOUT,
-    FEATURE_CODE,
-    MQTT_APP_KEY,
-    REQUEST_HEADER,
-)
+from .constants import APP_SECRET, DEFAULT_TIMEOUT, FEATURE_CODE, MQTT_APP_KEY
 from .exceptions import HTTPError, InvalidURL, PyEzvizError
 
 _LOGGER = logging.getLogger(__name__)
 
 
-class MQTTClient(threading.Thread):
-    """Open MQTT connection to ezviz cloud."""
+# ---------------------------------------------------------------------------
+# Typed structures
+# ---------------------------------------------------------------------------
+
+
+class ServiceUrls(TypedDict):
+    """Service URLs present in the EZVIZ auth token.
+
+    Attributes:
+        pushAddr: Hostname of the EZVIZ push/MQTT entry point.
+    """
+
+    pushAddr: str
+
+
+class EzvizToken(TypedDict):
+    """Minimal shape of the EZVIZ token required for MQTT.
+
+    Attributes:
+        username: Internal EZVIZ username.
+        session_id: Current session id.
+        service_urls: Nested object containing at least ``pushAddr``.
+    """
+
+    username: str
+    session_id: str
+    service_urls: ServiceUrls
+
+
+class MqttData(TypedDict):
+    """Typed dictionary for EZVIZ MQTT connection data."""
+
+    mqtt_clientid: str | None
+    ticket: str | None
+    push_url: str
+
+
+# ---------------------------------------------------------------------------
+# Payload decoding helpers
+# ---------------------------------------------------------------------------
+
+# Field names in the comma‑separated ``ext`` payload from EZVIZ.
+EXT_FIELD_NAMES: Final[tuple[str, ...]] = (
+    "channel_type",
+    "time",
+    "device_serial",
+    "channel_no",
+    "alert_type_code",
+    "unused1",
+    "unused2",
+    "unused3",
+    "unused4",
+    "status_flag",
+    "file_id",
+    "is_encrypted",
+    "encrypted_pwd_hash",
+    "unknown_flag",
+    "unused5",
+    "alarm_log_id",
+    "image",
+    "device_name",
+    "unused6",
+    "sequence_number",
+)
+
+# Fields that should be converted to ``int`` if present.
+EXT_INT_FIELDS: Final[frozenset[str]] = frozenset(
+    {
+        "channel_type",
+        "channel_no",
+        "alert_type_code",
+        "status_flag",
+        "is_encrypted",
+        "sequence_number",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class MQTTClient:
+    """MQTT client for Ezviz push notifications.
+
+    Handles the Ezviz-specific registration and connection process,
+    maintains a persistent MQTT connection, and processes incoming messages.
+
+    Messages are stored per device_serial in `messages_by_device`, and an optional
+    callback can be provided to handle messages as they arrive.
+
+    Typical usage::
+
+        client = MQTTClient(token=auth_token)
+        client.connect(clean_session=True)
+
+        # Access last message for a device
+        last_msg = client.messages_by_device.get(device_serial)
+
+        # Stop the client when done
+        client.stop()
+    """
 
     def __init__(
         self,
-        token: dict,
+        token: EzvizToken | dict,
+        session: requests.Session,
         timeout: int = DEFAULT_TIMEOUT,
+        on_message_callback: Callable[[dict[str, Any]], None] | None = None,
+        *,
+        max_messages: int = 1000,
     ) -> None:
-        """Initialize the client object."""
-        threading.Thread.__init__(self)
-        self._session = requests.session()
-        self._session.headers.update(REQUEST_HEADER)
-        self._token = token or {
-            "session_id": None,
-            "rf_session_id": None,
-            "username": None,
-            "api_url": "apiieu.ezvizlife.com",
-        }
-        self._timeout = timeout
-        self._stop_event = threading.Event()
-        self._mqtt_data = {
+        """Initialize the Ezviz MQTT client.
+
+        This client handles registration with the Ezviz push service, maintains
+        a persistent MQTT connection, and decodes incoming push messages.
+
+        Args:
+            token (dict): Authentication token dictionary returned by EzvizClient.login().
+                Must include:
+                    - 'username': Ezviz account username (The account aliase or generated one.)
+                    - 'session_id': session token for API access
+                    - 'service_urls': dictionary containing at least 'pushAddr'
+            timeout (int, optional): HTTP request timeout in seconds. Defaults to DEFAULT_TIMEOUT.
+            session (requests.Session): Pre-configured requests session for HTTP calls.
+            on_message_callback (Callable[[dict[str, Any]], None], optional): Optional callback function
+                that will be called for each decoded MQTT message. The callback receives
+                a dictionary with the message data. Defaults to None.
+            max_messages:
+                Maximum number of device entries kept in :attr:`messages_by_device`.
+                Oldest entries are evicted when the limit is exceeded. Defaults to ``1000``.
+
+        Raises:
+            PyEzvizError: If the provided token is missing required fields.
+        """
+        if not token or not token.get("username"):
+            raise PyEzvizError(
+                "Ezviz internal username is required. Ensure EzvizClient.login() was called first."
+            )
+
+        # Requests session (synchronous)
+        self._session = session
+
+        self._token: EzvizToken | dict = token
+        self._timeout: int = timeout
+        self._topic: str = f"{MQTT_APP_KEY}/#"
+        self._on_message_callback = on_message_callback
+        self._max_messages: int = max_messages
+
+        self._mqtt_data: MqttData = {
             "mqtt_clientid": None,
             "ticket": None,
             "push_url": token["service_urls"]["pushAddr"],
         }
-        self.mqtt_client = None
-        self.rcv_message: dict[Any, Any] = {}
 
-    def on_subscribe(
-        self, client: Any, userdata: Any, mid: Any, granted_qos: Any
-    ) -> None:
-        """On MQTT message subscribe."""
-        # pylint: disable=unused-argument
-        _LOGGER.info("Subscribed: %s %s", mid, granted_qos)
+        self.mqtt_client: mqtt.Client | None = None
+        # Keep last payload per device, bounded by ``max_messages``
+        self.messages_by_device: OrderedDict[str, dict[str, Any]] = OrderedDict()
 
-    def on_connect(
-        self, client: Any, userdata: Any, flags: Any, return_code: Any
-    ) -> None:
-        """On MQTT connect."""
-        # pylint: disable=unused-argument
-        if return_code == 0:
-            _LOGGER.info("Connected OK with return code %s", return_code)
-        else:
-            _LOGGER.info("Connection Error with Return code %s", return_code)
-            client.reconnect()
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
 
-    def on_message(self, client: Any, userdata: Any, msg: Any) -> None:
-        """On MQTT message receive."""
-        # pylint: disable=unused-argument
-        try:
-            mqtt_message = json.loads(msg.payload)
-
-        except ValueError as err:
-            self.stop()
-            raise PyEzvizError(
-                "Impossible to decode mqtt message: " + str(err)
-            ) from err
+    def connect(self, *, clean_session: bool = False, keepalive: int = 60) -> None:
+        """Connect to the Ezviz MQTT broker and start receiving push messages.
 
-        mqtt_message["ext"] = mqtt_message["ext"].split(",")
+        This method performs the following steps:
+            1. Registers the client with Ezviz push service.
+            2. Starts push notifications for this client.
+            3. Configures and connects the underlying MQTT client.
+            4. Starts the MQTT network loop in a background thread.
 
-        # Format payload message and keep latest device message.
-        self.rcv_message[mqtt_message["ext"][2]] = {
-            "id": mqtt_message["id"],
-            "alert": mqtt_message["alert"],
-            "time": mqtt_message["ext"][1],
-            "alert type": mqtt_message["ext"][4],
-            "image": mqtt_message["ext"][16] if len(mqtt_message["ext"]) > 16 else None,
-        }
+        Keyword Args:
+          clean_session (bool, optional): Whether to start a clean MQTT session. Defaults to False.
+          keepalive (int, optional): Keep-alive interval in seconds for the MQTT connection. Defaults to 60.
 
-        _LOGGER.debug(self.rcv_message, exc_info=True)
+        Raises:
+          PyEzvizError: If required Ezviz credentials are missing or registration/start fails.
+        """
+        self._register_ezviz_push()
+        self._start_ezviz_push()
+        self._configure_mqtt(clean_session=clean_session)
+        assert self.mqtt_client is not None
+        self.mqtt_client.connect(self._mqtt_data["push_url"], 1882, keepalive)
+        self.mqtt_client.loop_start()
 
-    def _mqtt(self) -> mqtt.Client:
-        """Receive MQTT messages from ezviz server."""
+    def stop(self) -> None:
+        """Stop the MQTT client and push notifications.
+
+        This method stops the MQTT network loop, disconnects from the broker,
+        and signals the Ezviz API to stop push notifications.
+
+        This method is idempotent and can be called multiple times safely.
+
+        Raises:
+          PyEzvizError: If stopping the push service fails.
+        """
+        if self.mqtt_client:
+            try:
+                # Stop background thread and disconnect
+                self.mqtt_client.loop_stop()
+                self.mqtt_client.disconnect()
+            except Exception as err:  # noqa: BLE001
+                _LOGGER.debug("MQTT disconnect failed: %s", err)
+        # Always attempt to stop push on server side
+        self._stop_ezviz_push()
+
+    # ------------------------------------------------------------------
+    # MQTT callbacks
+    # ------------------------------------------------------------------
+
+    def _on_subscribe(
+        self, client: mqtt.Client, userdata: Any, mid: int, granted_qos: tuple[int, ...]
+    ) -> None:
+        """Handle subscription acknowledgement from the broker."""
+        _LOGGER.info("Subscribed: mid=%s qos=%s", mid, granted_qos)
+        _LOGGER.info("Subscribed to EZVIZ MQTT topic: %s", self._topic)
 
-        ezviz_mqtt_client = mqtt.Client(
-            client_id=self._mqtt_data["mqtt_clientid"], protocol=4, transport="tcp"
+    def _on_connect(
+        self, client: mqtt.Client, userdata: Any, flags: dict, rc: int
+    ) -> None:
+        """Handle successful or failed MQTT connection attempts.
+
+        Subscribes to the topic if this is a new session and logs connection status.
+
+        Args:
+            client (mqtt.Client): The MQTT client instance.
+            userdata (Any): The user data passed to the client (not used).
+            flags (dict): MQTT flags dictionary, includes 'session present'.
+            rc (int): MQTT connection result code. 0 indicates success.
+        """
+        session_present = (
+            flags.get("session present") if isinstance(flags, dict) else None
         )
-        ezviz_mqtt_client.on_connect = self.on_connect
-        ezviz_mqtt_client.on_subscribe = self.on_subscribe
-        ezviz_mqtt_client.on_message = self.on_message
-        ezviz_mqtt_client.username_pw_set(MQTT_APP_KEY, APP_SECRET)
-
-        ezviz_mqtt_client.connect(self._mqtt_data["push_url"], 1882, 60)
-        ezviz_mqtt_client.subscribe(
-            f"{MQTT_APP_KEY}/ticket/{self._mqtt_data['ticket']}", qos=2
+        _LOGGER.info(
+            "Connected to EZVIZ broker rc=%s session_present=%s", rc, session_present
         )
+        if rc == 0 and not session_present:
+            client.subscribe(self._topic, qos=2)
+        if rc != 0:
+            # Let paho handle reconnects (reconnect_delay_set configured)
+            _LOGGER.error("MQTT connection failed, return code: %s", rc)
+
+    def _on_disconnect(self, client: mqtt.Client, userdata: Any, rc: int) -> None:
+        """Called when the MQTT client disconnects from the broker.
+
+        Logs the disconnection. Automatic reconnects are handled by paho-mqtt.
+
+        Args:
+            client (mqtt.Client): The MQTT client instance.
+            userdata (Any): The user data passed to the client (not used).
+            rc (int): Disconnect result code. 0 indicates a clean disconnect.
+        """
+        _LOGGER.warning("Disconnected from EZVIZ MQTT broker (rc=%s)", rc)
+
+    def _on_message(
+        self, client: mqtt.Client, userdata: Any, msg: mqtt.MQTTMessage
+    ) -> None:
+        """Handle incoming MQTT messages.
+
+        Decodes the payload, updates `messages_by_device` with the latest message,
+        and calls the optional user callback.
+
+        Args:
+            client (mqtt.Client): The MQTT client instance.
+            userdata (Any): The user data passed to the client (not used).
+            msg (mqtt.MQTTMessage): The MQTT message object containing payload and topic.
+        """
+        try:
+            decoded = self.decode_mqtt_message(msg.payload)
+        except PyEzvizError as err:
+            _LOGGER.warning("Failed to decode MQTT message: %s", err)
+            return
+
+        device_serial = decoded.get("ext", {}).get("device_serial")
+        if device_serial:
+            self._cache_message(device_serial, decoded)
+            _LOGGER.debug("Stored message for device_serial %s", device_serial)
+        else:
+            _LOGGER.warning("Received message with no device_serial: %s", decoded)
+
+        if self._on_message_callback:
+            try:
+                self._on_message_callback(decoded)
+            except Exception:
+                _LOGGER.exception("The on_message_callback raised")
 
-        ezviz_mqtt_client.loop_start()
-        return ezviz_mqtt_client
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
 
     def _register_ezviz_push(self) -> None:
-        """Register for push messages."""
+        """Register the client with the Ezviz push service.
 
+        Sends the necessary information to Ezviz to obtain a unique MQTT client ID.
+
+        Raises:
+            PyEzvizError: If the registration fails or the API returns a non-200 status.
+            InvalidURL: If the push service URL is invalid or unreachable.
+            HTTPError: If the HTTP request fails for other reasons.
+        """
         auth_seq = (
             "Basic "
             + base64.b64encode(f"{MQTT_APP_KEY}:{APP_SECRET}".encode("ascii")).decode()
@@ -142,118 +365,224 @@ class MQTTClient(threading.Thread):
                 data=payload,
                 timeout=self._timeout,
             )
-
             req.raise_for_status()
-
-        except requests.ConnectionError as err:
-            raise InvalidURL("A Invalid URL or Proxy error occured") from err
-
-        except requests.HTTPError as err:
+        except requests.HTTPError as err:  # network OK, HTTP error status
             raise HTTPError from err
 
         try:
-            json_result = req.json()
-
+            json_output = req.json()
+        except requests.ConnectionError as err:
+            raise InvalidURL("Invalid URL or proxy error") from err
         except ValueError as err:
             raise PyEzvizError(
                 "Impossible to decode response: "
                 + str(err)
-                + "\nResponse was: "
+                + "Response was: "
                 + str(req.text)
             ) from err
 
-        self._mqtt_data["mqtt_clientid"] = json_result["data"]["clientId"]
-
-    def run(self) -> None:
-        """Start mqtt thread."""
-
-        if self._token.get("username") is None:
-            self._stop_event.set()
+        if json_output.get("status") != 200:
             raise PyEzvizError(
-                "Ezviz internal username is required. Call EzvizClient login without token."
+                f"Could not register to EZVIZ mqtt server: Got {json_output})"
             )
 
-        self._register_ezviz_push()
-        self._start_ezviz_push()
-        self.mqtt_client = self._mqtt()
-
-    def start(self) -> None:
-        """Start mqtt thread as application. Set logging first to see messages."""
-        self.run()
+        # Persist client id from payload
+        self._mqtt_data["mqtt_clientid"] = json_output["data"]["clientId"]
 
-        try:
-            while not self._stop_event.is_set():
-                time.sleep(1)
-        except KeyboardInterrupt:
-            self.stop()
+    def _start_ezviz_push(self) -> None:
+        """Start push notifications for this client with the Ezviz API.
 
-    def stop(self) -> None:
-        """Stop push notifications."""
+        Sends the client ID, session ID, and username to Ezviz so that the server
+        will start pushing messages to this client.
 
+        Raises:
+            PyEzvizError: If the API fails to start push notifications or returns a non-200 status.
+            InvalidURL: If the push service URL is invalid or unreachable.
+            HTTPError: If the HTTP request fails for other reasons.
+        """
         payload = {
             "appKey": MQTT_APP_KEY,
             "clientId": self._mqtt_data["mqtt_clientid"],
             "clientType": 5,
             "sessionId": self._token["session_id"],
             "username": self._token["username"],
+            "token": "123456",
         }
 
         try:
             req = self._session.post(
-                f"https://{self._mqtt_data['push_url']}{API_ENDPOINT_STOP_MQTT}",
+                f"https://{self._mqtt_data['push_url']}{API_ENDPOINT_START_MQTT}",
+                allow_redirects=False,
                 data=payload,
                 timeout=self._timeout,
             )
-
             req.raise_for_status()
+        except requests.HTTPError as err:
+            raise HTTPError from err
 
+        try:
+            json_output = req.json()
         except requests.ConnectionError as err:
-            raise InvalidURL("A Invalid URL or Proxy error occured") from err
+            raise InvalidURL("Invalid URL or proxy error") from err
+        except ValueError as err:
+            raise PyEzvizError(
+                "Impossible to decode response: "
+                + str(err)
+                + "Response was: "
+                + str(req.text)
+            ) from err
 
-        except requests.HTTPError as err:
-            raise HTTPError from err
+        if json_output.get("status") != 200:
+            raise PyEzvizError(
+                f"Could not signal EZVIZ mqtt server to start pushing messages: Got {json_output})"
+            )
 
-        finally:
-            self._stop_event.set()
-            self.mqtt_client.loop_stop()
+        self._mqtt_data["ticket"] = json_output["ticket"]
+        _LOGGER.info("EZVIZ MQTT ticket acquired")
 
-    def _start_ezviz_push(self) -> None:
-        """Send start for push messages to ezviz api."""
+    def _stop_ezviz_push(self) -> None:
+        """Stop push notifications for this client via the Ezviz API.
+
+        Sends the client ID and session information to stop further messages.
 
+        Raises:
+            PyEzvizError: If the API fails to stop push notifications or returns a non-200 status.
+            InvalidURL: If the push service URL is invalid or unreachable.
+            HTTPError: If the HTTP request fails for other reasons.
+        """
         payload = {
             "appKey": MQTT_APP_KEY,
             "clientId": self._mqtt_data["mqtt_clientid"],
             "clientType": 5,
             "sessionId": self._token["session_id"],
             "username": self._token["username"],
-            "token": "123456",
         }
 
         try:
             req = self._session.post(
-                f"https://{self._mqtt_data['push_url']}{API_ENDPOINT_START_MQTT}",
-                allow_redirects=False,
+                f"https://{self._mqtt_data['push_url']}{API_ENDPOINT_STOP_MQTT}",
                 data=payload,
                 timeout=self._timeout,
             )
-
             req.raise_for_status()
-
-        except requests.ConnectionError as err:
-            raise InvalidURL("A Invalid URL or Proxy error occured") from err
-
         except requests.HTTPError as err:
             raise HTTPError from err
 
         try:
-            json_result = req.json()
-
+            json_output = req.json()
+        except requests.ConnectionError as err:
+            raise InvalidURL("Invalid URL or proxy error") from err
         except ValueError as err:
             raise PyEzvizError(
                 "Impossible to decode response: "
                 + str(err)
-                + "\nResponse was: "
+                + "Response was: "
                 + str(req.text)
             ) from err
 
-        self._mqtt_data["ticket"] = json_result["ticket"]
+        if json_output.get("status") != 200:
+            raise PyEzvizError(
+                f"Could not signal EZVIZ mqtt server to stop pushing messages: Got {json_output})"
+            )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _configure_mqtt(self, *, clean_session: bool) -> None:
+        """Internal helper to configure and connect the paho-mqtt client.
+
+        This method sets up the MQTT client with:
+            - Callbacks for connect, disconnect, subscribe, and message
+            - Username and password authentication
+            - Reconnect delay settings
+            - Broker connection on the configured topic
+
+        Args:
+            clean_session (bool): Whether to start a clean MQTT session.
+
+        Notes:
+            This method is called automatically by `connect()`.
+
+        """
+        broker = self._mqtt_data["push_url"]
+
+        self.mqtt_client = mqtt.Client(
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION1,
+            client_id=self._mqtt_data["mqtt_clientid"],
+            clean_session=clean_session,
+            protocol=mqtt.MQTTv311,
+            transport="tcp",
+        )
+
+        # Bind callbacks
+        self.mqtt_client.on_connect = self._on_connect
+        self.mqtt_client.on_disconnect = self._on_disconnect
+        self.mqtt_client.on_subscribe = self._on_subscribe
+        self.mqtt_client.on_message = self._on_message
+
+        # Auth (do not log these!)
+        self.mqtt_client.username_pw_set(MQTT_APP_KEY, APP_SECRET)
+
+        # Backoff for reconnects handled by paho
+        self.mqtt_client.reconnect_delay_set(min_delay=5, max_delay=10)
+
+        _LOGGER.debug("Configured MQTT client for broker %s", broker)
+
+    def _cache_message(self, device_serial: str, payload: dict[str, Any]) -> None:
+        """Cache latest message per device with an LRU-like policy.
+
+        Parameters:
+            device_serial (str): Device serial extracted from the message ``ext``.
+            payload (dict[str, Any]): Decoded message dictionary to store.
+        """
+        # Move existing to the end or insert new
+        if device_serial in self.messages_by_device:
+            del self.messages_by_device[device_serial]
+        self.messages_by_device[device_serial] = payload
+        # Evict oldest if above limit
+        while len(self.messages_by_device) > self._max_messages:
+            self.messages_by_device.popitem(last=False)
+
+    # ------------------------------------------------------------------
+    # Public decoding API
+    # ------------------------------------------------------------------
+
+    def decode_mqtt_message(self, payload_bytes: bytes) -> dict[str, Any]:
+        """Decode raw MQTT message payload into a structured dictionary.
+
+        The returned dictionary will contain all top-level fields from the message,
+        and the 'ext' field is parsed into named subfields with numeric fields converted to int.
+
+        Parameters:
+            payload_bytes (bytes): Raw payload received from MQTT broker.
+
+        Returns:
+            dict: Decoded message with ``ext`` mapped to named fields; numeric fields
+            converted to ``int`` where appropriate.
+
+        Raises:
+            PyEzvizError: If the payload is not valid JSON.
+        """
+        try:
+            payload_str = payload_bytes.decode("utf-8")
+            data: dict[str, Any] = json.loads(payload_str)
+
+            if "ext" in data and isinstance(data["ext"], str):
+                ext_parts = data["ext"].split(",")
+                ext_dict: dict[str, Any] = {}
+                for i, name in enumerate(EXT_FIELD_NAMES):
+                    value: Any = ext_parts[i] if i < len(ext_parts) else None
+                    if value is not None and name in EXT_INT_FIELDS:
+                        with suppress(ValueError):
+                            value = int(value)
+                    ext_dict[name] = value
+                data["ext"] = ext_dict
+
+        except json.JSONDecodeError as err:
+            # Stop the client on malformed payloads as a defensive measure,
+            # mirroring previous behaviour.
+            self.stop()
+            raise PyEzvizError(f"Unable to decode MQTT message: {err}") from err
+
+        return data

pyezvizapi/test_mqtt.py

@@ -0,0 +1,64 @@
+"""MQTT test module."""
+
+from getpass import getpass
+import json
+import logging
+from pathlib import Path
+import time
+from typing import Any
+
+from .client import EzvizClient  # Your login client
+from .mqtt import MQTTClient  # The refactored MQTT class
+
+logging.basicConfig(level=logging.INFO)
+
+LOG_FILE = Path("mqtt_messages.jsonl")  # JSON Lines format
+
+
+def message_handler(msg: dict[str, Any]) -> None:
+    """Handle new MQTT messages by printing and saving them to a file.
+
+    Args:
+        msg (Dict[str, Any]): The decoded MQTT message.
+    """
+    print("📩 New MQTT message:", msg)
+
+    # Append to JSONL file
+    with LOG_FILE.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(msg, ensure_ascii=False) + "\n")
+
+
+def main() -> None:
+    """Entry point for testing MQTT messages.
+
+    Prompts for username and password, logs into Ezviz, starts MQTT listener,
+    and writes incoming messages to a JSONL file.
+    """
+    # Prompt for credentials
+    username = input("Ezviz username: ")
+    password = getpass("Ezviz password: ")
+
+    # Step 1: Log into Ezviz to get a token
+    client = EzvizClient(account=username, password=password)
+    client.login()
+
+    # Step 2: Start MQTT client
+    mqtt_client: MQTTClient = client.get_mqtt_client(
+        on_message_callback=message_handler
+    )
+    mqtt_client.connect()
+
+    try:
+        print("Listening for MQTT messages... (Ctrl+C to quit)")
+        while True:
+            time.sleep(1)  # Keep process alive
+    except KeyboardInterrupt:
+        print("\nStopping...")
+    finally:
+        mqtt_client.stop()
+        print("Stopped.")
+
+
+if __name__ == "__main__":
+    main()
+

pyezvizapi/utils.py

@@ -6,6 +6,7 @@ from hashlib import md5
 import json
 import logging
 from typing import Any
+import uuid
 
 from Crypto.Cipher import AES
 
@@ -61,10 +62,12 @@ def fetch_nested_value(data: Any, keys: list, default_value: Any = None) -> Any:
     try:
         for key in keys:
             data = data[key]
-        return data
+
     except (KeyError, TypeError):
         return default_value
 
+    return data
+
 
 def decrypt_image(input_data: bytes, password: str) -> bytes:
     """Decrypts image data with provided password.
@@ -162,3 +165,27 @@ def deep_merge(dict1: Any, dict2: Any) -> Any:
             merged[key] = dict2[key]
 
     return merged
+
+
+def generate_unique_code() -> str:
+    """Generate a deterministic, platform-agnostic unique code for the current host.
+
+    This function retrieves the host's MAC address using Python's standard
+    `uuid.getnode()` (works on Windows, Linux, macOS), converts it to a
+    canonical string representation, and then hashes it using MD5 to produce
+    a fixed-length hexadecimal string.
+
+    Returns:
+        str: A 32-character hexadecimal string uniquely representing
+        the host's MAC address. For example:
+        'a94e6756hghjgfghg49e0f310d9e44a'.
+
+    Notes:
+        - The output is deterministic: the same machine returns the same code.
+        - If the MAC address changes (e.g., different network adapter),
+          the output will change.
+        - MD5 is used here only for ID generation, not for security.
+    """
+    mac_int = uuid.getnode()
+    mac_str = ":".join(f"{(mac_int >> i) & 0xFF:02x}" for i in range(40, -1, -8))
+    return md5(mac_str.encode("utf-8")).hexdigest()

{pyezvizapi-1.0.1.6.dist-info → pyezvizapi-1.0.1.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyezvizapi
-Version: 1.0.1.6
+Version: 1.0.1.7
 Summary: Pilot your Ezviz cameras
 Home-page: https://github.com/RenierM26/pyEzvizApi/
 Author: Renier Moorcroft

pyezvizapi-1.0.1.7.dist-info/RECORD

@@ -0,0 +1,20 @@
+pyezvizapi/__init__.py,sha256=ByMIDi_hdJa7Sc7GoJmviTOBe4DILx2E4UzhEpEzQis,1422
+pyezvizapi/__main__.py,sha256=OsawbYa-eoLUTOMr4xWeryq4sDzs09WL9GELKQTbda8,16396
+pyezvizapi/api_endpoints.py,sha256=rk6VinLVCn-B6DxnhfV79liplNpgUsipNbTEa_MRVwU,2755
+pyezvizapi/camera.py,sha256=BpmLySbnWWEKimSwgjx_cB60Q-6dbgdY-NA--NzUvps,11486
+pyezvizapi/cas.py,sha256=d31ZflYSD9P40MnsNRNZbT0HVLvlnHokKpLbdAjWQ74,5631
+pyezvizapi/client.py,sha256=uhtQ4bdM0zmnAPEt3cvxGtrqLFf0C15A5zIBE719pDE,86179
+pyezvizapi/constants.py,sha256=ntH7gNNRHQ66Dek2Uhk9PD4wXT0h7QTDn929LFGSP9I,12333
+pyezvizapi/exceptions.py,sha256=28lLyM0ILTRHgWqr9D-DqqKFXx7POuF0WAZctdC8Kbc,735
+pyezvizapi/light_bulb.py,sha256=ADLrPZ6NL4vANzmohU63QuD9qVGkKHkX9C0o7Evbv-A,5730
+pyezvizapi/mqtt.py,sha256=9i2dkVuNgf9KB2b-58HqHuKIzl-Ouuodg0dJ0DYpUOo,21649
+pyezvizapi/test_cam_rtsp.py,sha256=w7GPcYIeK78TxL8zFDihdGSDQNWcYrurwZOr6uFzzgo,4902
+pyezvizapi/test_mqtt.py,sha256=6thgcsfvl-wSR2Xrp8miG7PHfg9Q-a4AZ8VvOhEsBBQ,1651
+pyezvizapi/utils.py,sha256=zjbvQiJ_Q-qwbB_FImXVjuaRct9cogBRKDxzFHbx4ek,5940
+pyezvizapi-1.0.1.7.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyezvizapi-1.0.1.7.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pyezvizapi-1.0.1.7.dist-info/METADATA,sha256=e4GDIcD5BMofWTvFXl6EIUpF-2vrRGp1n9VTMZCOKPs,694
+pyezvizapi-1.0.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyezvizapi-1.0.1.7.dist-info/entry_points.txt,sha256=_BSJ3eNb2H_AZkRdsv1s4mojqWn3N7m503ujvg1SudA,56
+pyezvizapi-1.0.1.7.dist-info/top_level.txt,sha256=gMZTelIi8z7pXyTCQLLaIkxVRrDQ_lS2NEv0WgfHrHs,11
+pyezvizapi-1.0.1.7.dist-info/RECORD,,

pyezvizapi-1.0.1.6.dist-info/RECORD

@@ -1,19 +0,0 @@
-pyezvizapi/__init__.py,sha256=yWITfZOi5zvKblfaeB2ft-wXYmZ2NviYVq_tsK8YkSk,1334
-pyezvizapi/__main__.py,sha256=OsawbYa-eoLUTOMr4xWeryq4sDzs09WL9GELKQTbda8,16396
-pyezvizapi/api_endpoints.py,sha256=rk6VinLVCn-B6DxnhfV79liplNpgUsipNbTEa_MRVwU,2755
-pyezvizapi/camera.py,sha256=BpmLySbnWWEKimSwgjx_cB60Q-6dbgdY-NA--NzUvps,11486
-pyezvizapi/cas.py,sha256=d31ZflYSD9P40MnsNRNZbT0HVLvlnHokKpLbdAjWQ74,5631
-pyezvizapi/client.py,sha256=lak8r1Src1R57dQYwzVDq7NRt1iIOdkESyuR2FWqmRQ,85563
-pyezvizapi/constants.py,sha256=jjLO-Ne9jq9m9_giYB4rnPXDZKkzKhesVXBqP1B3-00,12304
-pyezvizapi/exceptions.py,sha256=28lLyM0ILTRHgWqr9D-DqqKFXx7POuF0WAZctdC8Kbc,735
-pyezvizapi/light_bulb.py,sha256=ADLrPZ6NL4vANzmohU63QuD9qVGkKHkX9C0o7Evbv-A,5730
-pyezvizapi/mqtt.py,sha256=Y4X99Z0Avm32SE8vog7CNsv6tGUPmPYUZUgPDGS0QJA,7866
-pyezvizapi/test_cam_rtsp.py,sha256=w7GPcYIeK78TxL8zFDihdGSDQNWcYrurwZOr6uFzzgo,4902
-pyezvizapi/utils.py,sha256=5J10o3h-y8prWDvl3LSAF-9wS1jBgBMg5cpAEebcuSM,4936
-pyezvizapi-1.0.1.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyezvizapi-1.0.1.6.dist-info/licenses/LICENSE.md,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pyezvizapi-1.0.1.6.dist-info/METADATA,sha256=GAvczQGW5LSpRKQg5jCaExw9KM4GcvqKa0L9WYWvMxc,694
-pyezvizapi-1.0.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyezvizapi-1.0.1.6.dist-info/entry_points.txt,sha256=_BSJ3eNb2H_AZkRdsv1s4mojqWn3N7m503ujvg1SudA,56
-pyezvizapi-1.0.1.6.dist-info/top_level.txt,sha256=gMZTelIi8z7pXyTCQLLaIkxVRrDQ_lS2NEv0WgfHrHs,11
-pyezvizapi-1.0.1.6.dist-info/RECORD,,