Actu8HubClient 1.1.0__tar.gz

actu8hubclient-1.1.0/Actu8HubClient/Actu8HubClient.py

@@ -0,0 +1,1149 @@
+"""
+Actu8Hub Python Client Library
+================================
+
+A lightweight, non-blocking client for connecting Python-based devices
+(Raspberry Pi, Jetson Nano, Linux SBCs, etc.) to the Actu8Hub IoT platform.
+
+Features:
+  - Automatic HTTP polling or WebSocket real-time connection
+  - Sensor reading queue with batch transmission
+  - Text/string sensor value support
+  - Actuator command handling with smart confirmation
+  - Device logging with levels (debug, info, warn, error)
+  - Offline ring buffer (queues readings when connection is lost)
+  - File upload helper (2-step signed URL process)
+  - Non-blocking background sync via threading
+  - Rate limit aware: 60 requests/minute per device
+
+Usage (HTTP polling):
+    from Actu8HubClient import Actu8HubClient
+
+    hub = Actu8HubClient("a8h_YOUR_API_KEY")
+    hub.queue_reading("Temperature", 24.5)
+    hub.queue_text_reading("Status", "Normal")
+    hub.sync()
+
+Usage (WebSocket real-time):
+    from Actu8HubClient import Actu8HubClient
+    import time
+
+    hub = Actu8HubClient("a8h_YOUR_API_KEY")
+
+    def on_actuator(cmd):
+        print(f"Actuator {cmd.name}: active={cmd.is_active}, value={cmd.value}")
+        return 1  # 1=changed, 0=already matched, -1=error
+
+    hub.on_actuator(on_actuator)
+    hub.connect_websocket()
+
+    while True:
+        hub.queue_reading("Temperature", 24.5)
+        hub.queue_text_reading("Status", "Normal")
+        hub.transmit_readings()
+        hub.transmit_text_readings()
+        time.sleep(5)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import mimetypes
+import os
+import ssl
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Callable, Deque, Dict, List, Optional
+
+try:
+    import requests
+except ImportError:
+    requests = None  # type: ignore[assignment]
+
+try:
+    import websocket as _ws_mod  # websocket-client library
+except ImportError:
+    _ws_mod = None  # type: ignore[assignment]
+
+logger = logging.getLogger("actu8hub")
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_DEFAULT_BASE_URL = "https://api.actu8hub.com/functions/v1"
+_DEFAULT_WS_URL = "wss://api.actu8hub.com/functions/v1"
+_RING_BUFFER_SIZE = 50
+_HEARTBEAT_INTERVAL_S = 15
+_RECONNECT_INTERVAL_S = 5
+_UPLOAD_URL_EXPIRY_S = 300
+
+
+# ---------------------------------------------------------------------------
+# Data Structures
+# ---------------------------------------------------------------------------
+
+class LogLevel(Enum):
+    """Log severity levels matching the Actu8Hub API."""
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+
+
+@dataclass
+class ActuatorCommand:
+    """Actuator command received from the server."""
+    name: str
+    is_active: bool
+    value: float
+    command_text: str = ""  # Optional text payload for Command-type actuators
+
+
+@dataclass
+class SensorReading:
+    """Numeric sensor reading to be sent to the server."""
+    name: str
+    value: float
+
+
+@dataclass
+class TextReading:
+    """Text/string sensor reading to be sent to the server."""
+    name: str
+    text_value: str
+    media_url: Optional[str] = None
+
+
+@dataclass
+class LogEntry:
+    """Log entry to be sent to the server."""
+    message: str
+    level: LogLevel
+    timestamp_ms: float  # time.time() * 1000 when created
+
+
+@dataclass
+class _PendingConfirmation:
+    """Pending actuator confirmation waiting to be sent."""
+    name: str
+    is_active: bool
+    value: float
+    status: str = "ok"  # "ok" or "mismatch"
+
+
+# Type alias for the actuator callback.
+# Return: 1 = state changed, 0 = already matched, -1 = error
+ActuatorCallback = Callable[[ActuatorCommand], int]
+ConnectionCallback = Callable[[bool], None]
+
+
+# ---------------------------------------------------------------------------
+# Ring Buffer for offline resilience
+# ---------------------------------------------------------------------------
+
+class _RingBuffer:
+    """Fixed-size deque that silently drops oldest items when full."""
+
+    def __init__(self, maxsize: int = _RING_BUFFER_SIZE) -> None:
+        self._buf: Deque[Any] = deque(maxlen=maxsize)
+        self._lock = threading.Lock()
+
+    def append(self, item: Any) -> None:
+        with self._lock:
+            self._buf.append(item)
+
+    def drain(self) -> List[Any]:
+        """Return all items and clear the buffer atomically."""
+        with self._lock:
+            items = list(self._buf)
+            self._buf.clear()
+            return items
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._buf)
+
+    @property
+    def empty(self) -> bool:
+        return len(self) == 0
+
+
+# ---------------------------------------------------------------------------
+# Main Client Class
+# ---------------------------------------------------------------------------
+
+class Actu8HubClient:
+    """
+    Actu8Hub IoT platform client for Python devices.
+
+    Supports HTTP polling (battery-friendly) and WebSocket (real-time)
+    connection modes. All network I/O is non-blocking — sync() and
+    transmit methods will not freeze your main control loop.
+
+    Args:
+        api_key: Device API key from the Actu8Hub dashboard (``a8h_`` or ``esp32_`` prefix).
+        base_url: Override the default Supabase functions URL for self-hosted instances.
+        ws_url: Override the WebSocket URL (defaults to follow base_url).
+        ring_buffer_size: Max queued readings kept in RAM when offline (default 50).
+        max_log_queue: Maximum number of log entries to buffer (default 50).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        ws_url: Optional[str] = None,
+        ring_buffer_size: int = _RING_BUFFER_SIZE,
+        max_log_queue: int = 50,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        if ws_url is None:
+            # Follow base_url so one override covers HTTP and WebSocket
+            ws_url = (
+                _DEFAULT_WS_URL
+                if base_url.rstrip("/") == _DEFAULT_BASE_URL
+                else "wss://" + base_url.split("://", 1)[-1]
+            )
+        self._ws_url = ws_url.rstrip("/")
+
+        # Queues (thread-safe ring buffers)
+        self._readings = _RingBuffer(ring_buffer_size)
+        self._text_readings = _RingBuffer(ring_buffer_size)
+        self._logs = _RingBuffer(max_log_queue)
+        self._confirmations: List[_PendingConfirmation] = []
+        self._confirm_lock = threading.Lock()
+
+        # Callbacks
+        self._actuator_cb: Optional[ActuatorCallback] = None
+        self._connection_cb: Optional[ConnectionCallback] = None
+
+        # WebSocket state
+        self._ws: Optional[Any] = None
+        self._ws_connected = False
+        self._ws_enabled = False
+        self._ws_thread: Optional[threading.Thread] = None
+        self._ws_stop_event = threading.Event()
+        self._last_activity = 0.0
+        self._heartbeat_thread: Optional[threading.Thread] = None
+        self._heartbeat_stop_event = threading.Event()
+
+        # Background sync state
+        self._bg_thread: Optional[threading.Thread] = None
+        self._bg_stop_event = threading.Event()
+
+        # HTTP session (reuse connections)
+        self._session: Optional[Any] = None
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if currently connected (WebSocket mode) or session is open (HTTP mode)."""
+        if self._ws_enabled:
+            return self._ws_connected
+        return True  # HTTP is stateless; always "connected" if network is up
+
+    @property
+    def has_pending(self) -> bool:
+        """Check if there are unsent actuator confirmations."""
+        with self._confirm_lock:
+            return len(self._confirmations) > 0
+
+    # ------------------------------------------------------------------
+    # Callbacks
+    # ------------------------------------------------------------------
+
+    def on_actuator(self, callback: ActuatorCallback) -> None:
+        """
+        Register a callback for actuator commands from the server.
+
+        The callback receives an :class:`ActuatorCommand` (with optional
+        ``command_text`` for Command-type actuators) and must return:
+          - ``1`` — state physically changed (triggers confirmation)
+          - ``0`` — already in target state (confirms only if server is pending)
+          - ``-1`` — actuator not recognized or could not be applied
+                    (sends a "mismatch" confirmation + auto error log)
+        """
+        self._actuator_cb = callback
+
+    def on_connection(self, callback: ConnectionCallback) -> None:
+        """Register a callback for WebSocket connection status changes."""
+        self._connection_cb = callback
+
+    # ------------------------------------------------------------------
+    # Sensor Queue
+    # ------------------------------------------------------------------
+
+    def queue_reading(self, name: str, value: float) -> None:
+        """
+        Queue a numeric sensor reading for transmission.
+
+        Readings are stored in an offline ring buffer and sent on the next
+        :meth:`sync` or :meth:`transmit_readings` call. If the buffer is
+        full, the oldest reading is silently dropped.
+
+        Args:
+            name: Sensor name (must match name configured in dashboard).
+            value: Current numeric sensor value.
+        """
+        self._readings.append(SensorReading(name=name, value=value))
+
+    def queue_text_reading(self, name: str, text_value: str, media_url: Optional[str] = None) -> None:
+        """
+        Queue a text/string sensor reading for transmission.
+
+        Text readings are stored in ``sensor_text_logs`` on the server.
+        Useful for classification results, state labels, etc.
+
+        Args:
+            name: Sensor name (must match name configured in dashboard).
+            text_value: The string value (e.g., "Open", "Person Detected").
+            media_url: Optional relative storage path for an associated file.
+        """
+        self._text_readings.append(
+            TextReading(name=name, text_value=text_value, media_url=media_url)
+        )
+
+    def set_stream_url(self, name: str, url: str) -> None:
+        """
+        Set the live stream URL for a stream-type sensor.
+
+        Convenience wrapper around :meth:`queue_text_reading` for video
+        streaming sensors. The URL should point to a live stream hosted on the
+        device itself (e.g., MJPEG from a USB camera, or HLS from ffmpeg).
+        The dashboard renders the stream directly — no video data is uploaded
+        to the server.
+
+        Args:
+            name: Stream sensor name (must match name configured in dashboard).
+            url: Full URL of the live stream
+                 (e.g., ``"http://192.168.1.50:8080/stream"``).
+
+        Note:
+            For HTTPS dashboards, use a tunnel (e.g., Cloudflare Tunnel) to
+            expose the device stream over HTTPS and avoid mixed-content blocks.
+
+        Example::
+
+            hub.set_stream_url("Camera", f"http://{local_ip}:8080/stream")
+            hub.transmit_text_readings()
+        """
+        self.queue_text_reading(name, url)
+
+    # ------------------------------------------------------------------
+    # Logging
+    # ------------------------------------------------------------------
+
+    def queue_log(self, level: LogLevel, message: str) -> None:
+        """
+        Queue a log message for transmission.
+
+        Args:
+            level: Log severity level.
+            message: Log message (max 500 characters; will be truncated).
+        """
+        self._logs.append(
+            LogEntry(
+                message=message[:500],
+                level=level,
+                timestamp_ms=time.time() * 1000,
+            )
+        )
+
+    def queue_debug_log(self, message: str) -> None:
+        """Queue a debug log message."""
+        self.queue_log(LogLevel.DEBUG, message)
+
+    def queue_info_log(self, message: str) -> None:
+        """Queue an info log message."""
+        self.queue_log(LogLevel.INFO, message)
+
+    def queue_warning_log(self, message: str) -> None:
+        """Queue a warning log message."""
+        self.queue_log(LogLevel.WARN, message)
+
+    def queue_error_log(self, message: str) -> None:
+        """Queue an error log message."""
+        self.queue_log(LogLevel.ERROR, message)
+
+    @property
+    def pending_log_count(self) -> int:
+        """Number of log entries waiting to be sent."""
+        return len(self._logs)
+
+    def set_max_log_queue(self, max_entries: int) -> None:
+        """
+        Set maximum number of log entries to queue.
+
+        Args:
+            max_entries: Maximum queue size (capped at 100).
+                Oldest entries are dropped when queue is full.
+        """
+        capped = min(max_entries, 100)
+        self._logs = _RingBuffer(capped)
+
+    # ------------------------------------------------------------------
+    # HTTP Sync (Polling Mode)
+    # ------------------------------------------------------------------
+
+    def sync(self) -> bool:
+        """
+        Full HTTP sync: send readings + text readings + logs, receive
+        and process actuator commands.
+
+        This is the recommended method for polling / battery-powered devices.
+        Non-blocking — if the network is unreachable, returns ``False``
+        immediately without freezing the calling thread.
+
+        Returns:
+            ``True`` if sync succeeded, ``False`` on error.
+        """
+        return self._http_sync(sensors=True, actuators=True, logs=True)
+
+    def sync_sensors_only(self) -> bool:
+        """Send queued sensor readings only (no actuator commands received)."""
+        return self._http_sync(sensors=True, actuators=False, logs=False)
+
+    def sync_actuators_only(self) -> bool:
+        """Receive actuator commands only (no sensor data or logs sent)."""
+        return self._http_sync(sensors=False, actuators=True, logs=False)
+
+    def sync_logs_only(self) -> bool:
+        """Send only queued logs (no sensors or actuator processing)."""
+        return self._http_sync(sensors=False, actuators=False, logs=True)
+
+    # ------------------------------------------------------------------
+    # Background Auto-Sync
+    # ------------------------------------------------------------------
+
+    def start_background_sync(self, interval_s: float = 10.0) -> None:
+        """
+        Start a background thread that calls :meth:`sync` at regular intervals.
+
+        This is useful for polling mode — your main loop continues
+        uninterrupted while readings and logs are synced automatically.
+
+        Args:
+            interval_s: Seconds between sync attempts (default 10).
+        """
+        if self._bg_thread and self._bg_thread.is_alive():
+            return  # Already running
+
+        self._bg_stop_event.clear()
+
+        def _worker() -> None:
+            while not self._bg_stop_event.is_set():
+                try:
+                    self.sync()
+                except Exception:
+                    logger.exception("Background sync error")
+                self._bg_stop_event.wait(interval_s)
+
+        self._bg_thread = threading.Thread(target=_worker, daemon=True, name="actu8hub-sync")
+        self._bg_thread.start()
+        logger.info("Background sync started (interval=%ss)", interval_s)
+
+    def stop_background_sync(self) -> None:
+        """Stop the background sync thread."""
+        self._bg_stop_event.set()
+        if self._bg_thread:
+            self._bg_thread.join(timeout=5)
+            self._bg_thread = None
+        logger.info("Background sync stopped")
+
+    # ------------------------------------------------------------------
+    # WebSocket Methods (Real-Time Mode)
+    # ------------------------------------------------------------------
+
+    def connect_websocket(self) -> None:
+        """
+        Establish a WebSocket connection for real-time updates.
+
+        Actuator commands are pushed instantly when changed in the dashboard.
+        Runs in a background thread — does not block the calling thread.
+
+        Requires the ``websocket-client`` package::
+
+            pip install websocket-client
+        """
+        if _ws_mod is None:
+            raise ImportError(
+                "websocket-client is required for WebSocket mode. "
+                "Install it with: pip install websocket-client"
+            )
+
+        if self._ws_enabled:
+            return  # Already running
+
+        self._ws_enabled = True
+        self._ws_stop_event.clear()
+        self._heartbeat_stop_event.clear()
+        self._ws_thread = threading.Thread(
+            target=self._ws_run_loop, daemon=True, name="actu8hub-ws"
+        )
+        self._ws_thread.start()
+        self._start_heartbeat_thread()
+
+    def disconnect_websocket(self) -> None:
+        """Disconnect the WebSocket and stop the background thread."""
+        self._ws_enabled = False
+        self._ws_stop_event.set()
+        self._heartbeat_stop_event.set()
+        if self._ws:
+            try:
+                self._ws.close()
+            except Exception:
+                pass
+        if self._ws_thread:
+            self._ws_thread.join(timeout=5)
+            self._ws_thread = None
+        if self._heartbeat_thread:
+            self._heartbeat_thread.join(timeout=5)
+            self._heartbeat_thread = None
+        self._ws_connected = False
+        logger.info("WebSocket disconnected")
+
+    def transmit_readings(self) -> bool:
+        """
+        Send queued numeric sensor readings over WebSocket.
+
+        Returns:
+            ``True`` if sent, ``False`` if not connected or queue empty.
+        """
+        if not self._ws_connected or not self._ws:
+            return False
+
+        readings_data = self._readings.drain()
+        if not readings_data:
+            return False
+
+        readings_list: List[Dict[str, Any]] = []
+        for r in readings_data:
+            readings_list.append({"name": r.name, "value": r.value})
+
+        msg = json.dumps({"type": "sensor_readings", "readings": readings_list})
+        try:
+            self._ws.send(msg)
+            self._touch_activity()
+            return True
+        except Exception:
+            logger.exception("Failed to transmit readings over WebSocket")
+            # Re-queue readings that failed to send
+            for r in readings_data:
+                self._readings.append(r)
+            return False
+
+    def transmit_text_readings(self) -> bool:
+        """
+        Send queued text sensor readings.
+
+        If WebSocket is connected, uses the real-time ``sensor_text_readings``
+        message type. Otherwise, falls back to HTTP POST to ``/device-api/sensors``.
+
+        Returns:
+            ``True`` if sent, ``False`` if queue empty or request failed.
+        """
+        text_data = self._text_readings.drain()
+        if not text_data:
+            return False
+
+        readings_list: List[Dict[str, Any]] = []
+        for t in text_data:
+            entry: Dict[str, Any] = {"name": t.name, "text_value": t.text_value}
+            if t.media_url:
+                entry["media_url"] = t.media_url
+            readings_list.append(entry)
+
+        # Try WebSocket first if connected
+        if self._ws_connected and self._ws:
+            msg = json.dumps({"type": "sensor_text_readings", "readings": readings_list})
+            try:
+                self._ws.send(msg)
+                self._touch_activity()
+                return True
+            except Exception:
+                logger.exception("Failed to transmit text readings over WebSocket")
+                # Re-queue on failure and try HTTP fallback
+                for t in text_data:
+                    self._text_readings.append(t)
+                return False
+
+        # Fall back to HTTP
+        ok = self._post("/sensors", {"readings": readings_list})
+        if not ok:
+            # Re-queue on failure
+            for t in text_data:
+                self._text_readings.append(t)
+        return ok
+
+    def transmit_logs(self) -> bool:
+        """
+        Send queued logs over WebSocket.
+
+        Returns:
+            ``True`` if sent, ``False`` if not connected or queue empty.
+        """
+        if not self._ws_connected or not self._ws:
+            return False
+
+        log_data = self._logs.drain()
+        if not log_data:
+            return False
+
+        transmit_ms = time.time() * 1000
+        logs_list = []
+        for entry in log_data:
+            logs_list.append({
+                "message": entry.message,
+                "level": entry.level.value,
+                "millis_at_append": entry.timestamp_ms,
+            })
+
+        msg = json.dumps({
+            "type": "device_logs",
+            "millis_at_transmit": transmit_ms,
+            "logs": logs_list,
+        })
+        try:
+            self._ws.send(msg)
+            self._touch_activity()
+            return True
+        except Exception:
+            logger.exception("Failed to transmit logs over WebSocket")
+            for entry in log_data:
+                self._logs.append(entry)
+            return False
+
+    # ------------------------------------------------------------------
+    # Metadata Reporting
+    # ------------------------------------------------------------------
+
+    def report_metadata(
+        self,
+        board_type: Optional[str] = None,
+        firmware_version: Optional[str] = None,
+        sdk_version: Optional[str] = None,
+        ip_address: Optional[str] = None,
+    ) -> bool:
+        """
+        Report device metadata to the server.
+
+        Args:
+            board_type: e.g., "Raspberry Pi 4", "Jetson Nano"
+            firmware_version: Your application/firmware version string.
+            sdk_version: Python client library version.
+            ip_address: Device's local IP address.
+
+        Returns:
+            ``True`` on success, ``False`` on error.
+        """
+        payload: Dict[str, str] = {}
+        if board_type is not None:
+            payload["board_type"] = board_type
+        if firmware_version is not None:
+            payload["firmware_version"] = firmware_version
+        if sdk_version is not None:
+            payload["sdk_version"] = sdk_version
+        if ip_address is not None:
+            payload["ip_address"] = ip_address
+
+        if not payload:
+            return True
+
+        return self._post("/metadata", payload)
+
+    # ------------------------------------------------------------------
+    # File Upload Helper
+    # ------------------------------------------------------------------
+
+    def upload_file(self, filepath: str, sensor_name: str, caption: str = "") -> Optional[str]:
+        """
+        Upload a file to Actu8Hub storage and auto-link it to a sensor.
+
+        The server automatically creates a text log entry for the image,
+        so you do NOT need to call :meth:`queue_text_reading` afterwards.
+        The image will appear immediately in the dashboard.
+
+        Args:
+            filepath: Path to the local file to upload.
+            sensor_name: Name of the sensor to link the image to (must exist on this device).
+            caption: Optional caption/description (defaults to filename).
+
+        Returns:
+            The ``media_url`` (relative storage path) on success, or ``None`` on failure.
+
+        Example::
+
+            media_path = hub.upload_file("/home/pi/captures/photo.jpg", "Camera", "Person Detected")
+            # That's it! No queue_text_reading needed — the image is already linked.
+        """
+        if requests is None:
+            raise ImportError(
+                "The requests library is required. Install it with: pip install requests"
+            )
+
+        if not os.path.isfile(filepath):
+            logger.error("File not found: %s", filepath)
+            return None
+
+        filename = os.path.basename(filepath)
+        file_size = os.path.getsize(filepath)
+
+        # Step 1: Request signed upload URL (sensor_name is required)
+        req_body: Dict[str, Any] = {
+            "filename": filename,
+            "file_size": file_size,
+            "sensor_name": sensor_name,
+        }
+        if caption:
+            req_body["caption"] = caption
+
+        try:
+            session = self._get_session()
+            resp = session.post(
+                f"{self._base_url}/device-api/upload-url",
+                json=req_body,
+                headers=self._headers(),
+                timeout=15,
+            )
+            if resp.status_code != 200:
+                logger.error(
+                    "Failed to get upload URL: %s %s", resp.status_code, resp.text
+                )
+                return None
+
+            data = resp.json()
+            signed_url = data.get("signed_url")
+            media_url = data.get("media_url")
+
+            if not signed_url or not media_url:
+                logger.error("Invalid upload-url response: %s", data)
+                return None
+        except Exception:
+            logger.exception("Error requesting upload URL")
+            return None
+
+        # Step 2: PUT file to signed URL
+        try:
+            content_type = mimetypes.guess_type(filepath)[0] or "application/octet-stream"
+            with open(filepath, "rb") as f:
+                put_resp = session.put(
+                    signed_url,
+                    data=f,
+                    headers={"Content-Type": content_type},
+                    timeout=60,
+                )
+            if put_resp.status_code not in (200, 201):
+                logger.error(
+                    "File upload failed: %s %s", put_resp.status_code, put_resp.text
+                )
+                return None
+        except Exception:
+            logger.exception("Error uploading file")
+            return None
+
+        logger.info("File uploaded: %s -> %s", filepath, media_url)
+        return media_url
+
+    # ------------------------------------------------------------------
+    # Device Events
+    # ------------------------------------------------------------------
+
+    def log_event(self, sensor_name: str, description: str, seconds_ago: int = 0) -> bool:
+        """
+        Log a sensor event on the server.
+
+        Args:
+            sensor_name: Name of the sensor this event relates to.
+            description: Event description text.
+            seconds_ago: How many seconds ago the event occurred (default 0 = now).
+
+        Returns:
+            ``True`` on success, ``False`` on error.
+        """
+        payload: List[Dict[str, Any]] = [{
+            "sensor_name": sensor_name,
+            "description": description,
+        }]
+        if seconds_ago > 0:
+            payload[0]["seconds_ago"] = seconds_ago
+
+        return self._post("/events", payload)
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """
+        Gracefully shut down all connections and background threads.
+
+        Call this when your program exits.
+        """
+        self.stop_background_sync()
+        self.disconnect_websocket()
+        if self._session:
+            try:
+                self._session.close()
+            except Exception:
+                pass
+            self._session = None
+
+    def __enter__(self) -> "Actu8HubClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ==================================================================
+    # Private Methods
+    # ==================================================================
+
+    def _headers(self) -> Dict[str, str]:
+        """Common HTTP headers with API key auth."""
+        return {
+            "Content-Type": "application/json",
+            "x-device-api-key": self._api_key,
+        }
+
+    def _get_session(self) -> Any:
+        """Lazy-initialise and return a requests.Session for connection reuse."""
+        if requests is None:
+            raise ImportError(
+                "The requests library is required. Install it with: pip install requests"
+            )
+        if self._session is None:
+            self._session = requests.Session()
+        return self._session
+
+    def _post(self, path: str, payload: Any) -> bool:
+        """POST JSON to a device-api endpoint. Returns True on 2xx."""
+        try:
+            session = self._get_session()
+            resp = session.post(
+                f"{self._base_url}/device-api{path}",
+                json=payload,
+                headers=self._headers(),
+                timeout=15,
+            )
+            return 200 <= resp.status_code < 300
+        except Exception:
+            logger.exception("HTTP POST %s failed", path)
+            return False
+
+    # ------------------------------------------------------------------
+    # HTTP Sync Implementation
+    # ------------------------------------------------------------------
+
+    def _http_sync(self, sensors: bool, actuators: bool, logs: bool) -> bool:
+        """
+        Single-call HTTP sync matching the ``/device-api/sync`` endpoint.
+
+        Sends readings + text readings + confirmations + logs in one POST
+        and receives actuator state in the response.
+        """
+        try:
+            session = self._get_session()
+        except ImportError:
+            logger.error("requests library not installed")
+            return False
+
+        payload: Dict[str, Any] = {}
+
+        # Drain queues upfront so variables are always defined
+        readings_data: List[Any] = []
+        text_data: List[Any] = []
+        log_data: List[Any] = []
+
+        # Sensor readings (numeric + text combined)
+        if sensors:
+            readings_data = self._readings.drain()
+            text_data = self._text_readings.drain()
+
+            if readings_data or text_data:
+                readings_list: List[Dict[str, Any]] = []
+                for r in readings_data:
+                    readings_list.append({"name": r.name, "value": r.value})
+                for t in text_data:
+                    entry: Dict[str, Any] = {"name": t.name, "text_value": t.text_value}
+                    if t.media_url:
+                        entry["media_url"] = t.media_url
+                    readings_list.append(entry)
+                payload["sensor_readings"] = readings_list
+
+        # Pending confirmations
+        with self._confirm_lock:
+            if self._confirmations:
+                confs = []
+                for c in self._confirmations:
+                    confs.append({
+                        "name": c.name,
+                        "is_active": c.is_active,
+                        "value": c.value,
+                        "status": c.status,
+                    })
+                payload["actuator_confirmations"] = confs
+                self._confirmations.clear()
+
+        # Logs — server expects { millis_at_transmit, logs: [...] }
+        if logs:
+            log_data = self._logs.drain()
+            if log_data:
+                transmit_ms = time.time() * 1000
+                logs_list = []
+                for entry in log_data:
+                    logs_list.append({
+                        "message": entry.message,
+                        "level": entry.level.value,
+                        "millis_at_append": entry.timestamp_ms,
+                    })
+                payload["device_logs"] = {
+                    "millis_at_transmit": transmit_ms,
+                    "logs": logs_list,
+                }
+
+        try:
+            resp = session.post(
+                f"{self._base_url}/device-api/sync",
+                json=payload,
+                headers=self._headers(),
+                timeout=15,
+            )
+        except Exception:
+            logger.exception("HTTP sync failed")
+            # Re-queue drained data so it's not lost
+            for r in readings_data:
+                self._readings.append(r)
+            for t in text_data:
+                self._text_readings.append(t)
+            for entry in log_data:
+                self._logs.append(entry)
+            return False
+
+        if resp.status_code != 200:
+            logger.warning("Sync returned HTTP %s: %s", resp.status_code, resp.text[:200])
+            return False
+
+        # Process actuator commands from response
+        if actuators:
+            try:
+                data = resp.json()
+                for act in data.get("actuators", []):
+                    self._process_actuator(act)
+            except Exception:
+                logger.exception("Error processing sync response")
+
+        return True
+
+    # ------------------------------------------------------------------
+    # Actuator Processing
+    # ------------------------------------------------------------------
+
+    def _process_actuator(self, act: Dict[str, Any]) -> None:
+        """
+        Parse actuator JSON and invoke callback.
+
+        Smart confirmation:
+          - callback 1  → confirm with status="ok"
+          - callback 0  → confirm with status="ok" only if server still pending
+          - callback -1 → confirm with status="mismatch" + auto error log
+        """
+        if not self._actuator_cb:
+            return
+
+        cmd = ActuatorCommand(
+            name=act.get("name", ""),
+            is_active=bool(act.get("is_active", False)),
+            value=float(act.get("value", 0)),
+            command_text=str(act.get("command_text") or ""),
+        )
+
+        server_thinks_confirmed = act.get("device_confirmed", False)
+        try:
+            result = self._actuator_cb(cmd)
+        except Exception:
+            logger.exception("Actuator callback raised; treating as mismatch")
+            result = -1
+
+        if result == 1 or (result == 0 and not server_thinks_confirmed):
+            with self._confirm_lock:
+                self._confirmations.append(
+                    _PendingConfirmation(
+                        name=cmd.name,
+                        is_active=cmd.is_active,
+                        value=cmd.value,
+                        status="ok",
+                    )
+                )
+        elif result == -1:
+            with self._confirm_lock:
+                self._confirmations.append(
+                    _PendingConfirmation(
+                        name=cmd.name,
+                        is_active=cmd.is_active,
+                        value=cmd.value,
+                        status="mismatch",
+                    )
+                )
+            self.queue_error_log(f"Unrecognized actuator '{cmd.name}'")
+
+    # ------------------------------------------------------------------
+    # WebSocket Implementation
+    # ------------------------------------------------------------------
+
+    def _ws_run_loop(self) -> None:
+        """Background thread: connect WebSocket and handle reconnection."""
+        while self._ws_enabled and not self._ws_stop_event.is_set():
+            try:
+                ws_url = (
+                    f"{self._ws_url}/device-realtime"
+                    f"?api_key={self._api_key}"
+                )
+                self._ws = _ws_mod.WebSocketApp(  # type: ignore[union-attr]
+                    ws_url,
+                    on_open=self._on_ws_open,
+                    on_message=self._on_ws_message,
+                    on_error=self._on_ws_error,
+                    on_close=self._on_ws_close,
+                )
+                self._ws.run_forever(
+                    sslopt={"cert_reqs": ssl.CERT_NONE},
+                    ping_interval=None,
+                    ping_timeout=10,
+                )
+            except Exception:
+                logger.exception("WebSocket connection error")
+
+            # If still enabled, wait before reconnecting
+            if self._ws_enabled and not self._ws_stop_event.is_set():
+                logger.info(
+                    "WebSocket reconnecting in %ss...", _RECONNECT_INTERVAL_S
+                )
+                self._ws_stop_event.wait(_RECONNECT_INTERVAL_S)
+
+    def _on_ws_open(self, ws: Any) -> None:
+        self._ws_connected = True
+        self._touch_activity()
+        logger.info("WebSocket connected")
+        if self._connection_cb:
+            try:
+                self._connection_cb(True)
+            except Exception:
+                logger.exception("Connection callback error")
+
+    def _on_ws_message(self, ws: Any, message: str) -> None:
+        try:
+            data = json.loads(message)
+        except json.JSONDecodeError:
+            logger.warning("Invalid WebSocket message: %s", message[:100])
+            return
+
+        self._touch_activity()
+
+        msg_type = data.get("type", "")
+
+        if msg_type == "connected":
+            # Initial state — process all current actuator states
+            for act in data.get("actuators", []):
+                self._process_actuator(act)
+            self._ws_send_confirmations()
+
+        elif msg_type == "actuator_update":
+            # Real-time single actuator change
+            actuator_data = data.get("actuator", {})
+            self._process_actuator(actuator_data)
+            self._ws_send_confirmations()
+
+        elif msg_type in (
+            "heartbeat_ack",
+            "sensor_readings_ack",
+            "device_logs_ack",
+            "actuator_confirm_ack",
+            "sensor_stream_ack",
+        ):
+            # Acknowledgements — logged at debug level
+            logger.debug("Received %s", msg_type)
+
+        else:
+            logger.debug("Unknown WebSocket message type: %s", msg_type)
+
+    def _on_ws_error(self, ws: Any, error: Any) -> None:
+        logger.warning("WebSocket error: %s", error)
+
+    def _on_ws_close(self, ws: Any, close_status_code: Any, close_msg: Any) -> None:
+        was_connected = self._ws_connected
+        self._ws_connected = False
+        if was_connected:
+            logger.info("WebSocket disconnected (code=%s)", close_status_code)
+            if self._connection_cb:
+                try:
+                    self._connection_cb(False)
+                except Exception:
+                    logger.exception("Connection callback error")
+
+    def _ws_send_confirmations(self) -> None:
+        """Send pending actuator confirmations over WebSocket."""
+        with self._confirm_lock:
+            if not self._confirmations or not self._ws_connected or not self._ws:
+                return
+            confs = list(self._confirmations)
+            self._confirmations.clear()
+
+        actuators_list = []
+        for c in confs:
+            actuators_list.append({
+                "name": c.name,
+                "is_active": c.is_active,
+                "value": c.value,
+                "status": c.status,
+            })
+
+        msg = json.dumps({"type": "actuator_confirm", "actuators": actuators_list})
+        try:
+            self._ws.send(msg)
+            self._touch_activity()
+        except Exception:
+            logger.exception("Failed to send confirmations")
+            # Re-queue on failure
+            with self._confirm_lock:
+                self._confirmations.extend(confs)
+
+    def _start_heartbeat_thread(self) -> None:
+        if self._heartbeat_thread and self._heartbeat_thread.is_alive():
+            return
+
+        def _worker() -> None:
+            while self._ws_enabled and not self._heartbeat_stop_event.is_set():
+                if self._ws_connected and self._ws:
+                    idle_for = time.time() - self._last_activity
+                    if idle_for >= _HEARTBEAT_INTERVAL_S:
+                        self._send_heartbeat()
+                self._heartbeat_stop_event.wait(1.0)
+
+        self._heartbeat_thread = threading.Thread(
+            target=_worker, daemon=True, name="actu8hub-ws-heartbeat"
+        )
+        self._heartbeat_thread.start()
+
+    def _send_heartbeat(self) -> None:
+        if not self._ws_connected or not self._ws:
+            return
+        try:
+            self._ws.send(json.dumps({"type": "heartbeat"}))
+            self._touch_activity()
+        except Exception:
+            pass
+
+    def _touch_activity(self) -> None:
+        self._last_activity = time.time()