citrascope 0.7.0__tar.gz → 0.8.0__tar.gz

{citrascope-0.7.0 → citrascope-0.8.0}/.github/copilot-instructions.md

@@ -41,6 +41,7 @@ This project is a Python package for interacting with astronomical data and serv
 
 ## Common Tasks
 - Add new API integrations in `citrascope/api/`.
+  - Reference the [DEV Citra.space API documentation](https://dev.api.citra.space/docs) for endpoint specifications and data models
 - Extend or add hardware adapters:
   - Create new adapter class implementing `AbstractAstroHardwareAdapter` in `citrascope/hardware/`
   - Register it in `citrascope/hardware/adapter_registry.py` by adding an entry to `REGISTERED_ADAPTERS`

{citrascope-0.7.0 → citrascope-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: citrascope
-Version: 0.7.0
+Version: 0.8.0
 Summary: Remotely control a telescope while it polls for tasks, collects and edge processes data, and delivers results and data for further processing.
 Project-URL: Homepage, https://citra.space
 Project-URL: Documentation, https://docs.citra.space/citrascope/
@@ -25,6 +25,7 @@ Requires-Python: <3.13,>=3.10
 Requires-Dist: click
 Requires-Dist: fastapi>=0.104.0
 Requires-Dist: httpx
+Requires-Dist: ntplib>=0.4.0
 Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: python-dateutil
 Requires-Dist: requests
@@ -36,6 +37,14 @@ Requires-Dist: dbus-python; extra == 'all'
 Requires-Dist: pixelemon; extra == 'all'
 Requires-Dist: plotly; extra == 'all'
 Requires-Dist: pyindi-client; extra == 'all'
+Provides-Extra: all-hardware
+Requires-Dist: cv2-enumerate-cameras>=1.0.0; extra == 'all-hardware'
+Requires-Dist: opencv-python>=4.8.0; extra == 'all-hardware'
+Requires-Dist: picamera2>=0.3.12; extra == 'all-hardware'
+Requires-Dist: pixelemon; extra == 'all-hardware'
+Requires-Dist: plotly; extra == 'all-hardware'
+Requires-Dist: pyindi-client; extra == 'all-hardware'
+Requires-Dist: ximea-api>=1.0.0; extra == 'all-hardware'
 Provides-Extra: build
 Requires-Dist: build; extra == 'build'
 Provides-Extra: deploy
@@ -58,10 +67,17 @@ Requires-Dist: plotly; extra == 'indi'
 Requires-Dist: pyindi-client; extra == 'indi'
 Provides-Extra: kstars
 Requires-Dist: dbus-python; extra == 'kstars'
+Provides-Extra: rpi
+Requires-Dist: picamera2>=0.3.12; extra == 'rpi'
 Provides-Extra: test
 Requires-Dist: mockito; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
+Provides-Extra: usb-camera
+Requires-Dist: cv2-enumerate-cameras>=1.0.0; extra == 'usb-camera'
+Requires-Dist: opencv-python>=4.8.0; extra == 'usb-camera'
+Provides-Extra: ximea
+Requires-Dist: ximea-api>=1.0.0; extra == 'ximea'
 Description-Content-Type: text/markdown
 
 # CitraScope

{citrascope-0.7.0 → citrascope-0.8.0}/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-0.7.0 → citrascope-0.8.0}/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-0.7.0 → citrascope-0.8.0}/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-0.7.0 → citrascope-0.8.0}/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,83 @@ class AbstractAstroHardwareAdapter(ABC):
         """
         return False
 
+    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-0.7.0 → citrascope-0.8.0}/citrascope/hardware/adapter_registry.py

@@ -33,6 +33,11 @@ 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.",
+    },
 }
 
 
@@ -76,11 +81,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 +97,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-0.8.0/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-0.8.0/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-0.8.0/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-0.8.0/citrascope/hardware/devices/camera/abstract_camera.py

@@ -0,0 +1,102 @@
+"""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