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

citrascope/api/abstract_api_client.py

@@ -28,3 +28,17 @@ class AbstractCitraApiClient(ABC):
         PUT to /telescopes to report online status.
         """
         pass
+
+    @abstractmethod
+    def expand_filters(self, filter_names):
+        """
+        POST to /filters/expand to expand filter names to spectral specs.
+        """
+        pass
+
+    @abstractmethod
+    def update_telescope_spectral_config(self, telescope_id, spectral_config):
+        """
+        PATCH to /telescopes to update telescope's spectral configuration.
+        """
+        pass

citrascope/api/citra_api_client.py

@@ -140,3 +140,44 @@ class CitraApiClient(AbstractCitraApiClient):
             if self.logger:
                 self.logger.error(f"Failed to mark task {task_id} as failed: {e}")
             return None
+
+    def expand_filters(self, filter_names):
+        """Expand filter names to full spectral specifications.
+
+        Args:
+            filter_names: List of filter name strings (e.g., ["Red", "Ha", "Clear"])
+
+        Returns:
+            Response dict with 'filters' array, or None on error
+        """
+        try:
+            body = {"filter_names": filter_names}
+            response = self._request("POST", "/filters/expand", json=body)
+            if self.logger:
+                self.logger.debug(f"POST /filters/expand: {response}")
+            return response
+        except Exception as e:
+            if self.logger:
+                self.logger.error(f"Failed to expand filters: {e}")
+            return None
+
+    def update_telescope_spectral_config(self, telescope_id, spectral_config):
+        """Update telescope's spectral configuration.
+
+        Args:
+            telescope_id: Telescope UUID string
+            spectral_config: Dict with spectral configuration (discrete filters, etc.)
+
+        Returns:
+            Response from PATCH request, or None on error
+        """
+        try:
+            body = [{"id": telescope_id, "spectralConfig": spectral_config}]
+            response = self._request("PATCH", "/telescopes", json=body)
+            if self.logger:
+                self.logger.debug(f"PATCH /telescopes spectral_config: {response}")
+            return response
+        except Exception as e:
+            if self.logger:
+                self.logger.error(f"Failed to update telescope spectral config: {e}")
+            return None

citrascope/citra_scope_daemon.py

@@ -4,10 +4,13 @@ from typing import Optional
 from citrascope.api.citra_api_client import AbstractCitraApiClient, CitraApiClient
 from citrascope.hardware.abstract_astro_hardware_adapter import AbstractAstroHardwareAdapter
 from citrascope.hardware.adapter_registry import get_adapter_class
+from citrascope.hardware.filter_sync import sync_filters_to_backend
 from citrascope.logging import CITRASCOPE_LOGGER
 from citrascope.logging._citrascope_logger import setup_file_logging
 from citrascope.settings.citrascope_settings import CitraScopeSettings
 from citrascope.tasks.runner import TaskManager
+from citrascope.time.time_health import TimeHealth
+from citrascope.time.time_monitor import TimeMonitor
 from citrascope.web.server import CitraScopeWebServer
 
 
@@ -32,6 +35,7 @@ class CitraScopeDaemon:
         self.hardware_adapter = hardware_adapter
         self.web_server = None
         self.task_manager = None
+        self.time_monitor = None
         self.ground_station = None
         self.telescope_record = None
         self.configuration_error: Optional[str] = None
@@ -89,6 +93,10 @@ class CitraScopeDaemon:
                 self.task_manager.stop()
                 self.task_manager = None
 
+            if self.time_monitor:
+                self.time_monitor.stop()
+                self.time_monitor = None
+
             if self.hardware_adapter:
                 try:
                     self.hardware_adapter.disconnect()
@@ -114,6 +122,16 @@ class CitraScopeDaemon:
             # Initialize hardware adapter
             self.hardware_adapter = self._create_hardware_adapter()
 
+            # Check for missing dependencies (non-fatal, just warn)
+            if hasattr(self.hardware_adapter, "get_missing_dependencies"):
+                missing_deps = self.hardware_adapter.get_missing_dependencies()
+                if missing_deps:
+                    for dep in missing_deps:
+                        CITRASCOPE_LOGGER.warning(
+                            f"{dep['device_type']} '{dep['device_name']}' missing dependencies: {dep['missing_packages']}. "
+                            f"Install with: {dep['install_cmd']}"
+                        )
+
             # Initialize telescope
             success, error = self._initialize_telescope()
 
@@ -179,6 +197,8 @@ class CitraScopeDaemon:
 
             # Save filter configuration if adapter supports it
             self._save_filter_config()
+            # Sync discovered filters to backend on startup
+            self._sync_filters_to_backend()
 
             self.task_manager = TaskManager(
                 self.api_client,
@@ -191,6 +211,15 @@ class CitraScopeDaemon:
             )
             self.task_manager.start()
 
+            # Initialize and start time monitor (always enabled)
+            self.time_monitor = TimeMonitor(
+                check_interval_minutes=self.settings.time_check_interval_minutes,
+                pause_threshold_ms=self.settings.time_offset_pause_ms,
+                pause_callback=self._on_time_drift_pause,
+            )
+            self.time_monitor.start()
+            CITRASCOPE_LOGGER.info("Time synchronization monitoring started")
+
             CITRASCOPE_LOGGER.info("Telescope initialized successfully!")
             return True, None
 
@@ -207,6 +236,9 @@ class CitraScopeDaemon:
         - After autofocus to save updated focus positions
         - After manual filter focus updates via web API
 
+        Note: This only saves locally. Call _sync_filters_to_backend() separately
+        when enabled filters change to update the backend.
+
         Thread safety: This modifies self.settings and writes to disk.
         Should be called from main daemon thread or properly synchronized.
         """
@@ -222,6 +254,22 @@ class CitraScopeDaemon:
         except Exception as e:
             CITRASCOPE_LOGGER.warning(f"Failed to save filter configuration: {e}")
 
+    def _sync_filters_to_backend(self):
+        """Sync enabled filters to backend API.
+
+        Extracts enabled filter names from hardware adapter, expands them via
+        the filter library API, then updates the telescope's spectral_config.
+        Logs warnings on failure without blocking daemon operations.
+        """
+        if not self.hardware_adapter or not self.api_client or not self.telescope_record:
+            return
+
+        try:
+            filter_config = self.hardware_adapter.get_filter_config()
+            sync_filters_to_backend(self.api_client, self.telescope_record["id"], filter_config, CITRASCOPE_LOGGER)
+        except Exception as e:
+            CITRASCOPE_LOGGER.warning(f"Failed to sync filters to backend: {e}", exc_info=True)
+
     def trigger_autofocus(self) -> tuple[bool, Optional[str]]:
         """Request autofocus to run at next safe point between tasks.
 
@@ -261,6 +309,31 @@ class CitraScopeDaemon:
             return False
         return self.task_manager.is_autofocus_requested()
 
+    def _on_time_drift_pause(self, health: TimeHealth) -> None:
+        """
+        Callback invoked when time drift exceeds pause threshold.
+
+        Automatically pauses task processing to prevent observations with
+        inaccurate timestamps. User must manually resume after fixing time sync.
+
+        Args:
+            health: Current time health status
+        """
+        if not self.task_manager:
+            return
+
+        CITRASCOPE_LOGGER.critical(
+            f"Time drift exceeded threshold: {health.offset_ms:+.1f}ms. "
+            "Pausing task processing to prevent inaccurate observations."
+        )
+
+        # Pause task processing
+        self.task_manager.pause()
+        CITRASCOPE_LOGGER.warning(
+            "Task processing paused due to time sync issues. "
+            "Fix NTP configuration and manually resume via web interface."
+        )
+
     def run(self):
         # Start web server FIRST, so users can monitor/configure
         # The web interface will remain available even if configuration is incomplete
@@ -293,6 +366,8 @@ class CitraScopeDaemon:
         """Clean up resources on shutdown."""
         if self.task_manager:
             self.task_manager.stop()
+        if self.time_monitor:
+            self.time_monitor.stop()
         if self.web_server:
             CITRASCOPE_LOGGER.info("Stopping web server...")
             if self.web_server.web_log_handler:

citrascope/hardware/abstract_astro_hardware_adapter.py

@@ -18,6 +18,7 @@ class SettingSchemaEntry(TypedDict, total=False):
     max: float  # Maximum value for numeric types
     pattern: str  # Regex pattern for string validation
     options: list[str]  # List of valid options for select/dropdown inputs
+    group: str  # Group name for organizing settings in UI (e.g., 'Camera', 'Mount', 'Advanced')
 
 
 class FilterConfig(TypedDict):
@@ -70,7 +71,7 @@ class AbstractAstroHardwareAdapter(ABC):
 
     @classmethod
     @abstractmethod
-    def get_settings_schema(cls) -> list[SettingSchemaEntry]:
+    def get_settings_schema(cls, **kwargs) -> list[SettingSchemaEntry]:
         """
         Return a schema describing configurable settings for this hardware adapter.
 
@@ -127,7 +128,7 @@ class AbstractAstroHardwareAdapter(ABC):
         pass
 
     @abstractmethod
-    def perform_observation_sequence(self, task_id, satellite_data) -> str:
+    def perform_observation_sequence(self, task, satellite_data) -> str:
         """For hardware driven by sequences, perform the observation sequence and return image path."""
         pass
 
@@ -233,6 +234,100 @@ class AbstractAstroHardwareAdapter(ABC):
         """
         return False
 
+    def supports_direct_camera_control(self) -> bool:
+        """Indicates whether this adapter supports direct camera control.
+
+        Direct camera control allows manual test captures and camera operations
+        from the UI. Remote scheduler adapters (NINA, KStars) typically do not
+        support this, as camera control is managed by the external software.
+
+        Returns:
+            bool: True if the adapter supports expose_camera() and manual captures
+        """
+        # Remote schedulers never support direct control
+        if self.get_observation_strategy() == ObservationStrategy.SEQUENCE_TO_CONTROLLER:
+            return False
+
+        # MANUAL adapters might - check for the method
+        return hasattr(self, "expose_camera") and callable(getattr(self, "expose_camera"))
+
+    def is_hyperspectral(self) -> bool:
+        """Indicates whether this adapter uses a hyperspectral camera.
+
+        Hyperspectral cameras capture multiple spectral bands simultaneously
+        (e.g., snapshot mosaic sensors) and do not require discrete filter changes.
+
+        Returns:
+            bool: True if using hyperspectral imaging, False otherwise (default)
+        """
+        return False
+
+    def select_filters_for_task(self, task, allow_no_filter: bool = False) -> dict | None:
+        """Select which filters to use for a task based on assignment.
+
+        This method handles the common logic for filter selection:
+        - If task specifies assigned_filter_name, find and validate that filter
+        - If no filter specified, look for Clear/Luminance filter (case-insensitive)
+        - Fall back to first enabled filter, or None if allow_no_filter=True
+
+        Args:
+            task: Task object with optional assigned_filter_name field
+            allow_no_filter: If True, return None when no filters available (for KStars '--')
+
+        Returns:
+            dict: Dictionary mapping filter IDs to filter info {id: {name, focus_position, enabled}}
+                  Returns None only if allow_no_filter=True and no suitable filter found
+
+        Raises:
+            RuntimeError: If assigned filter not found, disabled, or no filters available when required
+        """
+        # Task specifies a specific filter - find it
+        if task and task.assigned_filter_name:
+            target_filter_id = None
+            target_filter_info = None
+            for fid, fdata in self.filter_map.items():
+                # Case-insensitive comparison
+                if fdata["name"].lower() == task.assigned_filter_name.lower():
+                    if not fdata.get("enabled", True):
+                        raise RuntimeError(
+                            f"Requested filter '{task.assigned_filter_name}' is disabled for task {task.id}"
+                        )
+                    target_filter_id = fid
+                    target_filter_info = fdata
+                    break
+
+            if target_filter_id is None:
+                raise RuntimeError(
+                    f"Requested filter '{task.assigned_filter_name}' not found in filter map for task {task.id}"
+                )
+
+            task_id_str = task.id if task else "unknown"
+            self.logger.info(f"Using filter '{task.assigned_filter_name}' for task {task_id_str}")
+            return {target_filter_id: target_filter_info}
+
+        # No filter specified - look for Clear or Luminance (case-insensitive)
+        clear_filter_names = ["clear", "luminance", "lum", "l"]
+        for fid, fdata in self.filter_map.items():
+            if fdata.get("enabled", True) and fdata["name"].lower() in clear_filter_names:
+                task_id_str = task.id if task else "unknown"
+                self.logger.info(f"Using default filter '{fdata['name']}' for task {task_id_str}")
+                return {fid: fdata}
+
+        # No clear filter found - try first enabled filter
+        enabled_filters = {fid: fdata for fid, fdata in self.filter_map.items() if fdata.get("enabled", True)}
+        if enabled_filters:
+            first_filter_id = next(iter(enabled_filters))
+            task_id_str = task.id if task else "unknown"
+            self.logger.info(
+                f"Using first available filter '{enabled_filters[first_filter_id]['name']}' for task {task_id_str}"
+            )
+            return {first_filter_id: enabled_filters[first_filter_id]}
+
+        # No enabled filters available
+        if allow_no_filter:
+            return None
+        raise RuntimeError("No enabled filters available for observation sequence")
+
     def get_filter_config(self) -> dict[str, FilterConfig]:
         """Get the current filter configuration including focus positions.
 

citrascope/hardware/adapter_registry.py

@@ -33,6 +33,16 @@ REGISTERED_ADAPTERS: Dict[str, Dict[str, str]] = {
         "class_name": "KStarsDBusAdapter",
         "description": "KStars/Ekos via D-Bus - Linux astronomy suite",
     },
+    "direct": {
+        "module": "citrascope.hardware.direct_hardware_adapter",
+        "class_name": "DirectHardwareAdapter",
+        "description": "Direct Hardware Control - Composable device adapters for cameras, mounts, etc.",
+    },
+    "dummy": {
+        "module": "citrascope.hardware.dummy_adapter",
+        "class_name": "DummyAdapter",
+        "description": "Dummy Adapter - Fake hardware for testing without real devices",
+    },
 }
 
 
@@ -76,11 +86,13 @@ def list_adapters() -> Dict[str, Dict[str, str]]:
     }
 
 
-def get_adapter_schema(adapter_name: str) -> list:
+def get_adapter_schema(adapter_name: str, **kwargs) -> list:
     """Get the configuration schema for a specific adapter.
 
     Args:
         adapter_name: The name of the adapter
+        **kwargs: Additional arguments to pass to the adapter's get_settings_schema method
+                  (e.g., current settings for dynamic schema generation)
 
     Returns:
         The adapter's settings schema
@@ -90,5 +102,5 @@ def get_adapter_schema(adapter_name: str) -> list:
         ImportError: If the adapter module cannot be imported
     """
     adapter_class = get_adapter_class(adapter_name)
-    # Call classmethod directly without instantiation
-    return adapter_class.get_settings_schema()
+    # Call classmethod, passing kwargs for dynamic schemas
+    return adapter_class.get_settings_schema(**kwargs)

citrascope/hardware/devices/__init__.py

@@ -0,0 +1,17 @@
+"""Device-level hardware abstractions.
+
+This module provides low-level device abstractions for direct hardware control.
+Device adapters can be composed into hardware adapters for complete system control.
+"""
+
+from citrascope.hardware.devices.camera import AbstractCamera
+from citrascope.hardware.devices.filter_wheel import AbstractFilterWheel
+from citrascope.hardware.devices.focuser import AbstractFocuser
+from citrascope.hardware.devices.mount import AbstractMount
+
+__all__ = [
+    "AbstractCamera",
+    "AbstractMount",
+    "AbstractFilterWheel",
+    "AbstractFocuser",
+]

citrascope/hardware/devices/abstract_hardware_device.py

@@ -0,0 +1,79 @@
+"""Abstract base class for all hardware device types."""
+
+import logging
+from abc import ABC, abstractmethod
+
+from citrascope.hardware.abstract_astro_hardware_adapter import SettingSchemaEntry
+
+
+class AbstractHardwareDevice(ABC):
+    """Base class for all hardware devices (cameras, mounts, filter wheels, focusers).
+
+    Provides common interface elements shared by all device types.
+    """
+
+    logger: logging.Logger
+
+    def __init__(self, logger: logging.Logger, **kwargs):
+        """Initialize the hardware device.
+
+        Args:
+            logger: Logger instance for this device
+            **kwargs: Device-specific configuration parameters
+        """
+        self.logger = logger
+
+    @classmethod
+    @abstractmethod
+    def get_friendly_name(cls) -> str:
+        """Return human-readable name for this device.
+
+        Returns:
+            Friendly display name (e.g., 'ZWO ASI294MC Pro', 'Celestron CGX')
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def get_dependencies(cls) -> dict[str, str | list[str]]:
+        """Return required Python packages and installation info.
+
+        Returns:
+            Dict with keys:
+                - packages: list of required package names
+                - install_extra: pyproject.toml extra name for pip install
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def get_settings_schema(cls) -> list[SettingSchemaEntry]:
+        """Return schema describing configurable settings for this device.
+
+        Returns:
+            List of setting schema entries (without device-type prefix)
+        """
+        pass
+
+    @abstractmethod
+    def connect(self) -> bool:
+        """Connect to the hardware device.
+
+        Returns:
+            True if connection successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def disconnect(self):
+        """Disconnect from the hardware device."""
+        pass
+
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """Check if device is connected and responsive.
+
+        Returns:
+            True if connected, False otherwise
+        """
+        pass

citrascope/hardware/devices/camera/__init__.py

@@ -0,0 +1,13 @@
+"""Camera device adapters."""
+
+from citrascope.hardware.devices.camera.abstract_camera import AbstractCamera
+from citrascope.hardware.devices.camera.rpi_hq_camera import RaspberryPiHQCamera
+from citrascope.hardware.devices.camera.usb_camera import UsbCamera
+from citrascope.hardware.devices.camera.ximea_camera import XimeaHyperspectralCamera
+
+__all__ = [
+    "AbstractCamera",
+    "RaspberryPiHQCamera",
+    "UsbCamera",
+    "XimeaHyperspectralCamera",
+]

citrascope/hardware/devices/camera/abstract_camera.py

@@ -0,0 +1,114 @@
+"""Abstract camera device interface."""
+
+from abc import abstractmethod
+from pathlib import Path
+from typing import Optional
+
+from citrascope.hardware.devices.abstract_hardware_device import AbstractHardwareDevice
+
+
+class AbstractCamera(AbstractHardwareDevice):
+    """Abstract base class for camera devices.
+
+    Provides a common interface for controlling imaging cameras including
+    CCDs, CMOS sensors, and hyperspectral cameras.
+    """
+
+    @abstractmethod
+    def take_exposure(
+        self,
+        duration: float,
+        gain: Optional[int] = None,
+        offset: Optional[int] = None,
+        binning: int = 1,
+        save_path: Optional[Path] = None,
+    ) -> Path:
+        """Capture an image exposure.
+
+        Args:
+            duration: Exposure duration in seconds
+            gain: Camera gain setting (device-specific units)
+            offset: Camera offset/black level setting
+            binning: Pixel binning factor (1=no binning, 2=2x2, etc.)
+            save_path: Optional path to save the image (if None, use default)
+
+        Returns:
+            Path to the saved image file
+        """
+        pass
+
+    @abstractmethod
+    def abort_exposure(self):
+        """Abort the current exposure if one is in progress."""
+        pass
+
+    @abstractmethod
+    def get_temperature(self) -> Optional[float]:
+        """Get the current camera sensor temperature.
+
+        Returns:
+            Temperature in degrees Celsius, or None if not available
+        """
+        pass
+
+    @abstractmethod
+    def set_temperature(self, temperature: float) -> bool:
+        """Set the target camera sensor temperature.
+
+        Args:
+            temperature: Target temperature in degrees Celsius
+
+        Returns:
+            True if temperature setpoint accepted, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def start_cooling(self) -> bool:
+        """Enable camera cooling system.
+
+        Returns:
+            True if cooling started successfully, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def stop_cooling(self) -> bool:
+        """Disable camera cooling system.
+
+        Returns:
+            True if cooling stopped successfully, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_camera_info(self) -> dict:
+        """Get camera capabilities and information.
+
+        Returns:
+            Dictionary containing camera specs (resolution, pixel size, bit depth, etc.)
+        """
+        pass
+
+    def is_hyperspectral(self) -> bool:
+        """Indicates whether this camera captures hyperspectral data.
+
+        Hyperspectral cameras capture multiple spectral bands simultaneously
+        (e.g., snapshot mosaic sensors like Ximea MQ series).
+
+        Returns:
+            bool: True if hyperspectral camera, False otherwise (default)
+        """
+        return False
+
+    def get_preferred_file_extension(self) -> str:
+        """Get the preferred file extension for saved images.
+
+        This method allows each camera to define what file format it wants
+        to use, without the hardware adapter needing to know camera internals.
+
+        Returns:
+            File extension string without the dot (e.g., 'fits', 'png', 'jpg')
+        """
+        # Default implementation: use output_format if available, otherwise FITS
+        return getattr(self, "output_format", "fits")