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

citrascope/settings/citrascope_settings.py

@@ -81,6 +81,10 @@ class CitraScopeSettings:
             )
             self.autofocus_interval_minutes = 60
 
+        # Time synchronization monitoring configuration (always enabled)
+        self.time_check_interval_minutes: int = config.get("time_check_interval_minutes", 5)
+        self.time_offset_pause_ms: float = config.get("time_offset_pause_ms", 500.0)
+
     def get_images_dir(self) -> Path:
         """Get the path to the images directory.
 
@@ -126,6 +130,8 @@ class CitraScopeSettings:
             "scheduled_autofocus_enabled": self.scheduled_autofocus_enabled,
             "autofocus_interval_minutes": self.autofocus_interval_minutes,
             "last_autofocus_timestamp": self.last_autofocus_timestamp,
+            "time_check_interval_minutes": self.time_check_interval_minutes,
+            "time_offset_pause_ms": self.time_offset_pause_ms,
         }
 
     def save(self) -> None:

citrascope/tasks/runner.py

@@ -46,6 +46,8 @@ class TaskManager:
         # Autofocus request flag (set by manual or scheduled triggers)
         self._autofocus_requested = False
         self._autofocus_lock = threading.Lock()
+        # Automated scheduling state (initialized from server on startup)
+        self._automated_scheduling = telescope_record.get("automatedScheduling", False) if telescope_record else False
 
     def poll_tasks(self):
         while not self._stop_event.is_set():

citrascope/tasks/scope/static_telescope_task.py

@@ -12,18 +12,23 @@ class StaticTelescopeTask(AbstractBaseTelescopeTask):
             raise ValueError("Could not fetch valid satellite data or TLE.")
 
         filepath = None
-        if self.hardware_adapter.get_observation_strategy() == ObservationStrategy.MANUAL:
-            self.point_to_lead_position(satellite_data)
-            filepaths = self.hardware_adapter.take_image(self.task.id, 2.0)  # 2 second exposure
-
-        if self.hardware_adapter.get_observation_strategy() == ObservationStrategy.SEQUENCE_TO_CONTROLLER:
-            # Calculate current satellite position and add to satellite_data
-            target_ra, target_dec, _, _ = self.get_target_radec_and_rates(satellite_data)
-            satellite_data["ra"] = target_ra.degrees
-            satellite_data["dec"] = target_dec.degrees
-
-            # Sequence-based adapters handle pointing and tracking themselves
-            filepaths = self.hardware_adapter.perform_observation_sequence(self.task.id, satellite_data)
+        try:
+            if self.hardware_adapter.get_observation_strategy() == ObservationStrategy.MANUAL:
+                self.point_to_lead_position(satellite_data)
+                filepaths = self.hardware_adapter.take_image(self.task.id, 2.0)  # 2 second exposure
+
+            if self.hardware_adapter.get_observation_strategy() == ObservationStrategy.SEQUENCE_TO_CONTROLLER:
+                # Calculate current satellite position and add to satellite_data
+                target_ra, target_dec, _, _ = self.get_target_radec_and_rates(satellite_data)
+                satellite_data["ra"] = target_ra.degrees
+                satellite_data["dec"] = target_dec.degrees
+
+                # Sequence-based adapters handle pointing and tracking themselves
+                filepaths = self.hardware_adapter.perform_observation_sequence(self.task, satellite_data)
+        except RuntimeError as e:
+            # Filter errors and other hardware errors
+            self.logger.error(f"Observation failed for task {self.task.id}: {e}")
+            raise
 
         # Take the image
         return self.upload_image_and_mark_complete(filepaths)

citrascope/tasks/task.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from typing import Optional
 
 
 @dataclass
@@ -18,6 +19,7 @@ class Task:
     telescopeName: str
     groundStationId: str
     groundStationName: str
+    assigned_filter_name: Optional[str] = None
 
     @classmethod
     def from_dict(cls, data: dict) -> "Task":
@@ -37,6 +39,7 @@ class Task:
             telescopeName=data.get("telescopeName", ""),
             groundStationId=data.get("groundStationId", ""),
             groundStationName=data.get("groundStationName", ""),
+            assigned_filter_name=data.get("assigned_filter_name"),
         )
 
     def __repr__(self):

citrascope/time/__init__.py

@@ -0,0 +1,14 @@
+"""Time synchronization monitoring for CitraScope."""
+
+from citrascope.time.time_health import TimeHealth, TimeStatus
+from citrascope.time.time_monitor import TimeMonitor
+from citrascope.time.time_sources import AbstractTimeSource, ChronyTimeSource, NTPTimeSource
+
+__all__ = [
+    "TimeHealth",
+    "TimeStatus",
+    "TimeMonitor",
+    "AbstractTimeSource",
+    "ChronyTimeSource",
+    "NTPTimeSource",
+]

citrascope/time/time_health.py

@@ -0,0 +1,103 @@
+"""Time health status calculation and monitoring."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class TimeStatus(str, Enum):
+    """Time synchronization status levels."""
+
+    OK = "ok"
+    CRITICAL = "critical"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class TimeHealth:
+    """Time synchronization health status."""
+
+    offset_ms: Optional[float]
+    """Clock offset in milliseconds (positive = system clock ahead)."""
+
+    status: TimeStatus
+    """Current time sync status level."""
+
+    source: str
+    """Time source used (ntp, gps, chrony, unknown)."""
+
+    message: Optional[str] = None
+    """Optional status message or error description."""
+
+    metadata: Optional[dict] = None
+    """Optional metadata (e.g., GPS satellite count, fix mode)."""
+
+    @staticmethod
+    def calculate_status(
+        offset_ms: Optional[float],
+        pause_threshold: float,
+    ) -> TimeStatus:
+        """
+        Calculate time status based on offset and pause threshold.
+
+        Args:
+            offset_ms: Clock offset in milliseconds (None if check failed)
+            pause_threshold: Threshold in milliseconds that triggers task pause
+
+        Returns:
+            TimeStatus level (OK, CRITICAL, or UNKNOWN)
+        """
+        if offset_ms is None:
+            return TimeStatus.UNKNOWN
+
+        abs_offset = abs(offset_ms)
+
+        if abs_offset < pause_threshold:
+            return TimeStatus.OK
+        else:
+            return TimeStatus.CRITICAL
+
+    @classmethod
+    def from_offset(
+        cls,
+        offset_ms: Optional[float],
+        source: str,
+        pause_threshold: float,
+        message: Optional[str] = None,
+        metadata: Optional[dict] = None,
+    ) -> "TimeHealth":
+        """
+        Create TimeHealth from offset and pause threshold.
+
+        Args:
+            offset_ms: Clock offset in milliseconds
+            source: Time source identifier
+            pause_threshold: Threshold that triggers task pause
+            message: Optional status message
+            metadata: Optional metadata dict
+
+        Returns:
+            TimeHealth instance
+        """
+        status = cls.calculate_status(offset_ms, pause_threshold)
+        return cls(
+            offset_ms=offset_ms,
+            status=status,
+            source=source,
+            message=message,
+            metadata=metadata,
+        )
+
+    def should_pause_observations(self) -> bool:
+        """Check if observations should be paused due to time sync issues."""
+        return self.status == TimeStatus.CRITICAL
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "offset_ms": self.offset_ms,
+            "status": self.status.value,
+            "source": self.source,
+            "message": self.message,
+            "metadata": self.metadata,
+        }

citrascope/time/time_monitor.py

@@ -0,0 +1,186 @@
+"""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, ChronyTimeSource, 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
+
+        # Detect and initialize best available time source
+        self.time_source: AbstractTimeSource = self._detect_best_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 _detect_best_source(self) -> AbstractTimeSource:
+        """
+        Detect and return the best available time source.
+
+        Priority order: Chrony > NTP
+
+        Returns:
+            The best available time source instance.
+        """
+        # Try ChronyTimeSource
+        chrony_source = ChronyTimeSource()
+        if chrony_source.is_available():
+            CITRASCOPE_LOGGER.info("Time monitor initialized with Chrony source")
+            return chrony_source
+
+        # Fall back to NTP
+        CITRASCOPE_LOGGER.info("Time monitor initialized with NTP source")
+        return NTPTimeSource()
+
+    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 time source for offset
+            offset_ms = self.time_source.get_offset_ms()
+
+            # Get metadata if available (e.g., GPS satellite info)
+            metadata = self.time_source.get_metadata()
+
+            # Calculate health status
+            health = TimeHealth.from_offset(
+                offset_ms=offset_ms,
+                source=self.time_source.get_source_name(),
+                pause_threshold=self.pause_threshold_ms,
+                metadata=metadata,
+            )
+
+            # 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,261 @@
+"""Time source implementations for CitraScope."""
+
+import subprocess
+import time
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import ntplib
+
+from citrascope.logging import CITRASCOPE_LOGGER
+
+
+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
+
+    def get_metadata(self) -> Optional[dict]:
+        """
+        Get optional metadata about the time source.
+
+        Returns:
+            Dictionary with metadata, or None if not applicable.
+        """
+        return None
+
+
+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"
+
+
+def _get_gpsd_metadata() -> Optional[dict]:
+    """
+    Query gpsd for satellite count and fix quality using gpspipe command.
+
+    Returns:
+        Dictionary with 'satellites' and 'fix_mode' keys, or None if unavailable.
+    """
+    try:
+        import json
+
+        # Use gpspipe to get JSON output from gpsd (cleaner than sockets)
+        # Request 10 messages to ensure we get both TPV (fix mode) and SKY (satellite count)
+        result = subprocess.run(
+            ["gpspipe", "-w", "-n", "10"],
+            capture_output=True,
+            timeout=3,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            return None
+
+        # Parse JSON lines to extract TPV (fix mode) and SKY (satellite count)
+        fix_mode = 0
+        satellites = 0
+
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+
+            try:
+                data = json.loads(line)
+                msg_class = data.get("class")
+
+                # Extract fix mode from TPV message
+                if msg_class == "TPV" and "mode" in data:
+                    fix_mode = data["mode"]
+
+                # Extract satellite count from SKY message
+                if msg_class == "SKY":
+                    # Prefer uSat (used satellites) if available
+                    if "uSat" in data:
+                        satellites = data["uSat"]
+                    # Fall back to counting satellites array
+                    elif "satellites" in data:
+                        satellites = len([s for s in data["satellites"] if s.get("used", False)])
+
+            except json.JSONDecodeError:
+                continue
+
+        return {"satellites": satellites, "fix_mode": fix_mode}
+
+    except (FileNotFoundError, OSError):
+        # gpspipe not available or gpsd not running
+        return None
+    except Exception as e:
+        CITRASCOPE_LOGGER.debug(f"Could not query gpsd: {e}")
+        return None
+
+
+class ChronyTimeSource(AbstractTimeSource):
+    """Chrony-based time source that detects GPS references."""
+
+    def __init__(self, timeout: int = 5):
+        """
+        Initialize Chrony time source.
+
+        Args:
+            timeout: Command timeout in seconds
+        """
+        self.timeout = timeout
+        self._gps_metadata: Optional[dict] = None
+        self._source_name: str = "chrony"
+
+    def is_available(self) -> bool:
+        """
+        Check if chrony is available and running.
+
+        Returns:
+            True if chronyc command succeeds, False otherwise.
+        """
+        try:
+            result = subprocess.run(
+                ["chronyc", "-c", "tracking"],
+                capture_output=True,
+                timeout=self.timeout,
+                text=True,
+            )
+            return result.returncode == 0
+        except Exception:
+            return False
+
+    def get_offset_ms(self) -> Optional[float]:
+        """
+        Query chrony for clock offset and detect GPS reference.
+
+        Returns:
+            Clock offset in milliseconds, or None if query fails.
+        """
+        try:
+            # Get tracking info for offset
+            tracking_result = subprocess.run(
+                ["chronyc", "-c", "tracking"],
+                capture_output=True,
+                timeout=self.timeout,
+                text=True,
+                check=True,
+            )
+
+            # Parse CSV output: field index 4 is "System time" in seconds
+            tracking_fields = tracking_result.stdout.strip().split(",")
+            if len(tracking_fields) > 4:
+                offset_seconds = float(tracking_fields[4])
+                offset_ms = offset_seconds * 1000.0
+            else:
+                return None
+
+            # Get sources to detect GPS reference
+            sources_result = subprocess.run(
+                ["chronyc", "-c", "sources"],
+                capture_output=True,
+                timeout=self.timeout,
+                text=True,
+                check=True,
+            )
+
+            # Parse sources to detect GPS
+            gps_detected = False
+            for line in sources_result.stdout.strip().split("\n"):
+                if not line:
+                    continue
+
+                fields = line.split(",")
+                if len(fields) < 3:
+                    continue
+
+                mode = fields[0]  # '#' = local reference
+                state = fields[1]  # '*' = currently selected
+                name = fields[2].upper()
+
+                # Check if this is a selected GPS reference
+                if "*" in state and "#" in mode:
+                    # Check for GPS-related names
+                    gps_keywords = ["GPS", "SHM", "PPS", "SOCK", "NMEA"]
+                    if any(keyword in name for keyword in gps_keywords):
+                        gps_detected = True
+                        break
+
+            # If GPS detected, query gpsd for metadata
+            if gps_detected:
+                self._source_name = "gps"
+                CITRASCOPE_LOGGER.info("GPS reference detected in chrony sources")
+                self._gps_metadata = _get_gpsd_metadata()
+                if self._gps_metadata:
+                    CITRASCOPE_LOGGER.info(
+                        f"GPS lock acquired: {self._gps_metadata['satellites']} satellites, "
+                        f"fix mode {self._gps_metadata['fix_mode']}"
+                    )
+                else:
+                    CITRASCOPE_LOGGER.warning(
+                        "GPS reference active in chrony but gpsd metadata unavailable "
+                        "(gpsd/gpspipe may not be available)"
+                    )
+            else:
+                self._source_name = "chrony"
+                self._gps_metadata = None
+                CITRASCOPE_LOGGER.warning("No GPS reference detected in chrony sources - using NTP/other time source")
+
+            return offset_ms
+
+        except Exception:
+            return None
+
+    def get_source_name(self) -> str:
+        """Get the name of this time source."""
+        return self._source_name
+
+    def get_metadata(self) -> Optional[dict]:
+        """
+        Get GPS metadata if available.
+
+        Returns:
+            Dictionary with GPS metadata, or None.
+        """
+        return self._gps_metadata