citrascope 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

citrascope/time/time_monitor.py

@@ -0,0 +1,164 @@
+"""Time synchronization monitoring thread for CitraScope."""
+
+import threading
+import time
+from typing import Callable, Optional
+
+from citrascope.logging import CITRASCOPE_LOGGER
+from citrascope.time.time_health import TimeHealth, TimeStatus
+from citrascope.time.time_sources import AbstractTimeSource, NTPTimeSource
+
+
+class TimeMonitor:
+    """
+    Background thread that monitors system clock synchronization.
+
+    Periodically checks clock offset against NTP servers,
+    logs warnings/errors based on drift severity, and notifies callback
+    when critical drift requires pausing observations.
+    """
+
+    def __init__(
+        self,
+        check_interval_minutes: int = 5,
+        pause_threshold_ms: float = 500.0,
+        pause_callback: Optional[Callable[[TimeHealth], None]] = None,
+    ):
+        """
+        Initialize time monitor.
+
+        Args:
+            check_interval_minutes: Minutes between time sync checks
+            pause_threshold_ms: Threshold in ms that triggers task pause
+            pause_callback: Callback function when threshold exceeded
+        """
+        self.check_interval_minutes = check_interval_minutes
+        self.pause_threshold_ms = pause_threshold_ms
+        self.pause_callback = pause_callback
+
+        # Initialize NTP time source
+        self.time_source: AbstractTimeSource = NTPTimeSource()
+        CITRASCOPE_LOGGER.info("Time monitor initialized with NTP source")
+
+        # Thread control
+        self._stop_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+
+        # Current health status
+        self._current_health: Optional[TimeHealth] = None
+        self._last_critical_notification = 0.0
+
+    def start(self) -> None:
+        """Start the time monitoring thread."""
+        if self._thread is not None and self._thread.is_alive():
+            CITRASCOPE_LOGGER.warning("Time monitor already running")
+            return
+
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._monitor_loop, daemon=True)
+        self._thread.start()
+        CITRASCOPE_LOGGER.info(f"Time monitor started (check interval: {self.check_interval_minutes} minutes)")
+
+    def stop(self) -> None:
+        """Stop the time monitoring thread."""
+        if self._thread is None:
+            return
+
+        CITRASCOPE_LOGGER.info("Stopping time monitor...")
+        self._stop_event.set()
+        self._thread.join(timeout=5.0)
+        self._thread = None
+        CITRASCOPE_LOGGER.info("Time monitor stopped")
+
+    def get_current_health(self) -> Optional[TimeHealth]:
+        """Get the current time health status (thread-safe)."""
+        with self._lock:
+            return self._current_health
+
+    def _monitor_loop(self) -> None:
+        """Main monitoring loop (runs in background thread)."""
+        # Perform initial check immediately
+        self._check_time_sync()
+
+        # Then check periodically
+        interval_seconds = self.check_interval_minutes * 60
+
+        while not self._stop_event.is_set():
+            # Wait for interval or stop signal
+            if self._stop_event.wait(timeout=interval_seconds):
+                break
+
+            self._check_time_sync()
+
+    def _check_time_sync(self) -> None:
+        """Perform a single time synchronization check."""
+        try:
+            # Query NTP for offset
+            offset_ms = self.time_source.get_offset_ms()
+
+            # Calculate health status
+            health = TimeHealth.from_offset(
+                offset_ms=offset_ms,
+                source=self.time_source.get_source_name(),
+                pause_threshold=self.pause_threshold_ms,
+            )
+
+            # Store current health (thread-safe)
+            with self._lock:
+                self._current_health = health
+
+            # Log based on status
+            self._log_health_status(health)
+
+            # Notify callback if critical
+            if health.should_pause_observations():
+                self._handle_critical_drift(health)
+
+        except Exception as e:
+            CITRASCOPE_LOGGER.error(f"Time sync check failed: {e}", exc_info=True)
+            # Create unknown status on error
+            health = TimeHealth.from_offset(
+                offset_ms=None,
+                source="unknown",
+                pause_threshold=self.pause_threshold_ms,
+                message=f"Check failed: {e}",
+            )
+            with self._lock:
+                self._current_health = health
+
+    def _log_health_status(self, health: TimeHealth) -> None:
+        """Log time health status at appropriate level."""
+        if health.offset_ms is None:
+            CITRASCOPE_LOGGER.warning("Time sync check failed - offset unknown")
+            return
+
+        offset_str = f"{health.offset_ms:+.1f}ms"
+
+        if health.status == TimeStatus.OK:
+            CITRASCOPE_LOGGER.info(f"Time sync OK: {offset_str}")
+        elif health.status == TimeStatus.CRITICAL:
+            CITRASCOPE_LOGGER.critical(
+                f"CRITICAL time drift: offset {offset_str} exceeds {self.pause_threshold_ms}ms threshold. "
+                "Task processing will be paused."
+            )
+
+    def _handle_critical_drift(self, health: TimeHealth) -> None:
+        """
+        Handle critical time drift by notifying callback.
+
+        Args:
+            health: Current time health status
+        """
+        # Rate-limit notifications (max once per 5 minutes)
+        now = time.time()
+        if now - self._last_critical_notification < 300:
+            return
+
+        self._last_critical_notification = now
+
+        if self.pause_callback is not None:
+            try:
+                self.pause_callback(health)
+            except Exception as e:
+                CITRASCOPE_LOGGER.error(f"Pause callback failed: {e}", exc_info=True)

citrascope/time/time_sources.py

@@ -0,0 +1,62 @@
+"""Time source implementations for CitraScope."""
+
+import time
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import ntplib
+
+
+class AbstractTimeSource(ABC):
+    """Abstract base class for time sources."""
+
+    @abstractmethod
+    def get_offset_ms(self) -> Optional[float]:
+        """
+        Get the clock offset in milliseconds.
+
+        Returns:
+            Clock offset in milliseconds (positive = system ahead), or None if unavailable.
+        """
+        pass
+
+    @abstractmethod
+    def get_source_name(self) -> str:
+        """Get the name of this time source."""
+        pass
+
+
+class NTPTimeSource(AbstractTimeSource):
+    """NTP-based time source using pool.ntp.org."""
+
+    def __init__(self, ntp_server: str = "pool.ntp.org", timeout: int = 5):
+        """
+        Initialize NTP time source.
+
+        Args:
+            ntp_server: NTP server hostname (default: pool.ntp.org)
+            timeout: Query timeout in seconds
+        """
+        self.ntp_server = ntp_server
+        self.timeout = timeout
+        self.client = ntplib.NTPClient()
+
+    def get_offset_ms(self) -> Optional[float]:
+        """
+        Query NTP server for clock offset.
+
+        Returns:
+            Clock offset in milliseconds, or None if query fails.
+        """
+        try:
+            response = self.client.request(self.ntp_server, version=3, timeout=self.timeout)
+            # NTP offset is in seconds, convert to milliseconds
+            offset_ms = response.offset * 1000.0
+            return offset_ms
+        except Exception:
+            # Query failed - network issue, timeout, etc.
+            return None
+
+    def get_source_name(self) -> str:
+        """Get the name of this time source."""
+        return "ntp"

citrascope/web/app.py

@@ -31,6 +31,7 @@ class SystemStatus(BaseModel):
     current_task: Optional[str] = None
     tasks_pending: int = 0
     processing_active: bool = True
+    automated_scheduling: bool = False
     hardware_adapter: str = "unknown"
     telescope_ra: Optional[float] = None
     telescope_dec: Optional[float] = None
@@ -40,7 +41,9 @@ class SystemStatus(BaseModel):
     autofocus_requested: bool = False
     last_autofocus_timestamp: Optional[int] = None
     next_autofocus_minutes: Optional[int] = None
+    time_health: Optional[Dict[str, Any]] = None
     last_update: str = ""
+    missing_dependencies: List[Dict[str, str]] = []  # List of {device, packages, install_cmd}
 
 
 class HardwareConfig(BaseModel):
@@ -179,7 +182,7 @@ class CitraScopeWebApp:
                 "personal_access_token": settings.personal_access_token,
                 "telescope_id": settings.telescope_id,
                 "hardware_adapter": settings.hardware_adapter,
-                "adapter_settings": settings.adapter_settings,
+                "adapter_settings": settings._all_adapter_settings,
                 "log_level": settings.log_level,
                 "keep_images": settings.keep_images,
                 "max_task_retries": settings.max_task_retries,
@@ -188,6 +191,8 @@ class CitraScopeWebApp:
                 "scheduled_autofocus_enabled": settings.scheduled_autofocus_enabled,
                 "autofocus_interval_minutes": settings.autofocus_interval_minutes,
                 "last_autofocus_timestamp": settings.last_autofocus_timestamp,
+                "time_check_interval_minutes": settings.time_check_interval_minutes,
+                "time_offset_pause_ms": settings.time_offset_pause_ms,
                 "app_url": app_url,
                 "config_file_path": config_path,
                 "log_file_path": log_file_path,
@@ -226,12 +231,27 @@ class CitraScopeWebApp:
             }
 
         @self.app.get("/api/hardware-adapters/{adapter_name}/schema")
-        async def get_adapter_schema(adapter_name: str):
-            """Get configuration schema for a specific hardware adapter."""
+        async def get_adapter_schema(adapter_name: str, current_settings: str = ""):
+            """Get configuration schema for a specific hardware adapter.
+
+            Args:
+                adapter_name: Name of the adapter
+                current_settings: JSON string of current adapter_settings (for dynamic schemas)
+            """
+            import json
+
             from citrascope.hardware.adapter_registry import get_adapter_schema as get_schema
 
             try:
-                schema = get_schema(adapter_name)
+                # Parse current settings if provided
+                settings_kwargs = {}
+                if current_settings:
+                    try:
+                        settings_kwargs = json.loads(current_settings)
+                    except json.JSONDecodeError:
+                        pass  # Ignore invalid JSON, use empty kwargs
+
+                schema = get_schema(adapter_name, **settings_kwargs)
                 return {"schema": schema}
             except ValueError as e:
                 # Invalid adapter name
@@ -396,6 +416,39 @@ class CitraScopeWebApp:
 
             return {"status": "active", "message": "Task processing resumed"}
 
+        @self.app.patch("/api/telescope/automated-scheduling")
+        async def update_automated_scheduling(request: Dict[str, bool]):
+            """Toggle automated scheduling on/off."""
+            if not self.daemon or not self.daemon.task_manager:
+                return JSONResponse({"error": "Task manager not available"}, status_code=503)
+
+            if not self.daemon.api_client:
+                return JSONResponse({"error": "API client not available"}, status_code=503)
+
+            enabled = request.get("enabled")
+            if enabled is None:
+                return JSONResponse({"error": "Missing 'enabled' field in request body"}, status_code=400)
+
+            try:
+                # Update server via Citra API
+                telescope_id = self.daemon.telescope_record["id"]
+                payload = [{"id": telescope_id, "automatedScheduling": enabled}]
+
+                response = self.daemon.api_client._request("PATCH", "/telescopes", json=payload)
+
+                if response:
+                    # Update local cache
+                    self.daemon.task_manager._automated_scheduling = enabled
+                    CITRASCOPE_LOGGER.info(f"Automated scheduling set to {'enabled' if enabled else 'disabled'}")
+                    await self.broadcast_status()
+                    return {"status": "success", "enabled": enabled}
+                else:
+                    return JSONResponse({"error": "Failed to update telescope on server"}, status_code=500)
+
+            except Exception as e:
+                CITRASCOPE_LOGGER.error(f"Error updating automated scheduling: {e}", exc_info=True)
+                return JSONResponse({"error": str(e)}, status_code=500)
+
         @self.app.get("/api/adapter/filters")
         async def get_filters():
             """Get current filter configuration."""
@@ -412,65 +465,131 @@ class CitraScopeWebApp:
                 CITRASCOPE_LOGGER.error(f"Error getting filter config: {e}", exc_info=True)
                 return JSONResponse({"error": str(e)}, status_code=500)
 
-        @self.app.patch("/api/adapter/filters/{filter_id}")
-        async def update_filter(filter_id: str, update: dict):
-            """Update focus position and/or enabled state for a specific filter."""
+        @self.app.post("/api/adapter/filters/batch")
+        async def update_filters_batch(updates: List[Dict[str, Any]]):
+            """Update multiple filters atomically with single disk write.
 
+            Args:
+                updates: Array of filter updates, each containing:
+                    - filter_id (str): Filter ID
+                    - focus_position (int, optional): Focus position in steps
+                    - enabled (bool, optional): Whether filter is enabled
+
+            Returns:
+                {"success": true, "updated_count": N} on success
+                {"error": "..."} on validation failure
+            """
             if not self.daemon or not self.daemon.hardware_adapter:
-                return JSONResponse({"error": "Hardware adapter not available"}, status_code=503)
+                return JSONResponse({"error": "Hardware adapter not initialized"}, status_code=503)
 
-            if not self.daemon.hardware_adapter.supports_filter_management():
-                return JSONResponse({"error": "Adapter does not support filter management"}, status_code=404)
+            if not updates or not isinstance(updates, list):
+                return JSONResponse({"error": "Updates must be a non-empty array"}, status_code=400)
 
             try:
-                # Get current filter config
-                filter_config = self.daemon.hardware_adapter.get_filter_config()
-                if filter_id not in filter_config:
-                    return JSONResponse({"error": f"Filter {filter_id} not found"}, status_code=404)
-
-                # Validate focus_position if provided
-                if "focus_position" in update:
-                    focus_position = update["focus_position"]
-                    if not isinstance(focus_position, int):
-                        return JSONResponse({"error": "focus_position must be an integer"}, status_code=400)
-
-                    # Typical focuser range is 0-65535 (16-bit unsigned)
-                    if focus_position < 0 or focus_position > 65535:
-                        return JSONResponse({"error": "focus_position must be between 0 and 65535"}, status_code=400)
-
-                    # Update focus position via adapter interface
-                    if not self.daemon.hardware_adapter.update_filter_focus(filter_id, focus_position):
-                        return JSONResponse({"error": "Failed to update filter focus in adapter"}, status_code=500)
-
-                # Validate and update enabled state if provided
-                if "enabled" in update:
-                    enabled = update["enabled"]
-                    if not isinstance(enabled, bool):
-                        return JSONResponse({"error": "enabled must be a boolean"}, status_code=400)
-
-                    # Belt and suspenders: Ensure at least one filter remains enabled
-                    if not enabled:
-                        enabled_count = sum(1 for f in filter_config.values() if f.get("enabled", True))
-                        if enabled_count <= 1:
+                filter_config = self.daemon.hardware_adapter.filter_map
+
+                # Phase 1: Validate ALL updates before applying ANY changes
+                validated_updates = []
+                for idx, update in enumerate(updates):
+                    if not isinstance(update, dict):
+                        return JSONResponse({"error": f"Update at index {idx} must be an object"}, status_code=400)
+
+                    if "filter_id" not in update:
+                        return JSONResponse({"error": f"Update at index {idx} missing filter_id"}, status_code=400)
+
+                    filter_id = update["filter_id"]
+                    try:
+                        filter_id_int = int(filter_id)
+                    except (ValueError, TypeError):
+                        return JSONResponse(
+                            {"error": f"Invalid filter_id at index {idx}: {filter_id}"}, status_code=400
+                        )
+
+                    if filter_id_int not in filter_config:
+                        return JSONResponse({"error": f"Filter ID {filter_id} not found"}, status_code=404)
+
+                    validated_update = {"filter_id_int": filter_id_int}
+
+                    # Validate focus_position if provided
+                    if "focus_position" in update:
+                        focus_position = update["focus_position"]
+                        if not isinstance(focus_position, int):
                             return JSONResponse(
-                                {
-                                    "error": "Cannot disable last enabled filter. At least one filter must remain enabled."
-                                },
-                                status_code=400,
+                                {"error": f"focus_position at index {idx} must be an integer"}, status_code=400
+                            )
+                        if focus_position < 0 or focus_position > 65535:
+                            return JSONResponse(
+                                {"error": f"focus_position at index {idx} must be between 0 and 65535"}, status_code=400
                             )
+                        validated_update["focus_position"] = focus_position
+
+                    # Validate enabled if provided
+                    if "enabled" in update:
+                        enabled = update["enabled"]
+                        if not isinstance(enabled, bool):
+                            return JSONResponse({"error": f"enabled at index {idx} must be a boolean"}, status_code=400)
+                        validated_update["enabled"] = enabled
+
+                    validated_updates.append(validated_update)
+
+                # Validate at least one filter remains enabled
+                current_enabled = {fid for fid, fdata in filter_config.items() if fdata.get("enabled", True)}
+                for validated in validated_updates:
+                    if "enabled" in validated:
+                        if validated["enabled"]:
+                            current_enabled.add(validated["filter_id_int"])
+                        else:
+                            current_enabled.discard(validated["filter_id_int"])
+
+                if not current_enabled:
+                    return JSONResponse(
+                        {"error": "Cannot disable all filters. At least one filter must remain enabled."},
+                        status_code=400,
+                    )
+
+                # Phase 2: Apply all validated updates
+                for validated in validated_updates:
+                    filter_id_int = validated["filter_id_int"]
 
-                    # Update enabled state via adapter interface
-                    if not self.daemon.hardware_adapter.update_filter_enabled(filter_id, enabled):
-                        return JSONResponse({"error": "Failed to update filter enabled state"}, status_code=500)
+                    if "focus_position" in validated:
+                        if not self.daemon.hardware_adapter.update_filter_focus(
+                            str(filter_id_int), validated["focus_position"]
+                        ):
+                            return JSONResponse(
+                                {"error": f"Failed to update filter {filter_id_int} focus"}, status_code=500
+                            )
 
-                # Save to settings
+                    if "enabled" in validated:
+                        if not self.daemon.hardware_adapter.update_filter_enabled(
+                            str(filter_id_int), validated["enabled"]
+                        ):
+                            return JSONResponse(
+                                {"error": f"Failed to update filter {filter_id_int} enabled state"}, status_code=500
+                            )
+
+                # Phase 3: Save once after all updates
                 self.daemon._save_filter_config()
 
-                return {"success": True, "filter_id": filter_id, "updated": update}
-            except ValueError:
-                return JSONResponse({"error": "Invalid filter_id format"}, status_code=400)
+                return {"success": True, "updated_count": len(validated_updates)}
+
             except Exception as e:
-                CITRASCOPE_LOGGER.error(f"Error updating filter: {e}", exc_info=True)
+                CITRASCOPE_LOGGER.error(f"Error in batch filter update: {e}", exc_info=True)
+                return JSONResponse({"error": str(e)}, status_code=500)
+
+        @self.app.post("/api/adapter/filters/sync")
+        async def sync_filters_to_backend():
+            """Explicitly sync filter configuration to backend API.
+
+            Call this after batch filter updates to sync enabled filters to backend.
+            """
+            if not self.daemon or not self.daemon.hardware_adapter:
+                return JSONResponse({"error": "Hardware adapter not initialized"}, status_code=503)
+
+            try:
+                self.daemon._sync_filters_to_backend()
+                return {"success": True, "message": "Filters synced to backend"}
+            except Exception as e:
+                CITRASCOPE_LOGGER.error(f"Error syncing filters to backend: {e}", exc_info=True)
                 return JSONResponse({"error": str(e)}, status_code=500)
 
         @self.app.post("/api/adapter/autofocus")
@@ -505,6 +624,47 @@ class CitraScopeWebApp:
                 CITRASCOPE_LOGGER.error(f"Error cancelling autofocus: {e}", exc_info=True)
                 return JSONResponse({"error": str(e)}, status_code=500)
 
+        @self.app.post("/api/camera/capture")
+        async def camera_capture(request: Dict[str, Any]):
+            """Trigger a test camera capture."""
+            if not self.daemon:
+                return JSONResponse({"error": "Daemon not available"}, status_code=503)
+
+            if not self.daemon.hardware_adapter:
+                return JSONResponse({"error": "Hardware adapter not available"}, status_code=503)
+
+            try:
+                duration = request.get("duration", 0.1)
+
+                # Validate exposure duration
+                if duration <= 0:
+                    return JSONResponse({"error": "Exposure duration must be positive"}, status_code=400)
+                if duration > 300:
+                    return JSONResponse({"error": "Exposure duration must be 300 seconds or less"}, status_code=400)
+
+                CITRASCOPE_LOGGER.info(f"Test capture requested: {duration}s exposure")
+
+                # Take exposure using hardware adapter
+                filepath = self.daemon.hardware_adapter.expose_camera(
+                    exposure_time=duration, gain=None, offset=None, count=1
+                )
+
+                # Get file info
+                file_path = Path(filepath)
+                if not file_path.exists():
+                    return JSONResponse({"error": "Capture completed but file not found"}, status_code=500)
+
+                filename = file_path.name
+                file_format = file_path.suffix.upper().lstrip(".")
+
+                CITRASCOPE_LOGGER.info(f"Test capture complete: {filename}")
+
+                return {"success": True, "filename": filename, "filepath": str(file_path), "format": file_format}
+
+            except Exception as e:
+                CITRASCOPE_LOGGER.error(f"Error during test capture: {e}", exc_info=True)
+                return JSONResponse({"error": str(e)}, status_code=500)
+
         @self.app.websocket("/ws")
         async def websocket_endpoint(websocket: WebSocket):
             """WebSocket endpoint for real-time updates."""
@@ -581,6 +741,14 @@ class CitraScopeWebApp:
                 else:
                     self.status.next_autofocus_minutes = None
 
+            # Get time sync status from time monitor
+            if hasattr(self.daemon, "time_monitor") and self.daemon.time_monitor:
+                health = self.daemon.time_monitor.get_current_health()
+                self.status.time_health = health.to_dict() if health else None
+            else:
+                # Time monitoring not initialized yet
+                self.status.time_health = None
+
             # Get ground station information from daemon (available after API validation)
             if hasattr(self.daemon, "ground_station") and self.daemon.ground_station:
                 gs_record = self.daemon.ground_station
@@ -598,6 +766,16 @@ class CitraScopeWebApp:
             # Update task processing state
             if hasattr(self.daemon, "task_manager") and self.daemon.task_manager:
                 self.status.processing_active = self.daemon.task_manager.is_processing_active()
+                self.status.automated_scheduling = self.daemon.task_manager._automated_scheduling or False
+
+            # Check for missing dependencies from adapter
+            self.status.missing_dependencies = []
+            if hasattr(self.daemon, "hardware_adapter") and self.daemon.hardware_adapter:
+                if hasattr(self.daemon.hardware_adapter, "get_missing_dependencies"):
+                    try:
+                        self.status.missing_dependencies = self.daemon.hardware_adapter.get_missing_dependencies()
+                    except Exception as e:
+                        CITRASCOPE_LOGGER.debug(f"Could not check missing dependencies: {e}")
 
             self.status.last_update = datetime.now().isoformat()