citrascope 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

citrascope/__main__.py

@@ -1,21 +1,24 @@
 import click
 
 from citrascope.citra_scope_daemon import CitraScopeDaemon
-from citrascope.settings._citrascope_settings import CitraScopeSettings
+from citrascope.settings.citrascope_settings import CitraScopeSettings
 
 
 @click.group()
 @click.option("--dev", is_flag=True, default=False, help="Use the development API (dev.app.citra.space)")
 @click.option("--log-level", default="INFO", help="Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)")
+@click.option("--keep-images", is_flag=True, default=False, help="Keep image files after upload (do not delete)")
 @click.pass_context
-def cli(ctx, dev, log_level):
-    ctx.obj = {"settings": CitraScopeSettings(dev=dev, log_level=log_level)}
+def cli(ctx, dev, log_level, keep_images):
+    ctx.obj = {"settings": CitraScopeSettings(dev=dev, log_level=log_level, keep_images=keep_images)}
 
 
 @cli.command("start")
+@click.option("--web-host", default="0.0.0.0", help="Web server host address (default: 0.0.0.0)")
+@click.option("--web-port", default=24872, type=int, help="Web server port (default: 24872)")
 @click.pass_context
-def start(ctx):
-    daemon = CitraScopeDaemon(ctx.obj["settings"])
+def start(ctx, web_host, web_port):
+    daemon = CitraScopeDaemon(ctx.obj["settings"], enable_web=True, web_host=web_host, web_port=web_port)
     daemon.run()
 
 

citrascope/api/abstract_api_client.py

@@ -21,3 +21,10 @@ class AbstractCitraApiClient(ABC):
     @abstractmethod
     def get_ground_station(self, ground_station_id):
         pass
+
+    @abstractmethod
+    def put_telescope_status(self, body):
+        """
+        PUT to /telescopes to report online status.
+        """
+        pass

citrascope/api/citra_api_client.py

@@ -6,6 +6,20 @@ from .abstract_api_client import AbstractCitraApiClient
 
 
 class CitraApiClient(AbstractCitraApiClient):
+    def put_telescope_status(self, body):
+        """
+        PUT to /telescopes to report online status.
+        """
+        try:
+            response = self._request("PUT", "/telescopes", json=body)
+            if self.logger:
+                self.logger.debug(f"PUT /telescopes: {response}")
+            return response
+        except Exception as e:
+            if self.logger:
+                self.logger.error(f"Failed PUT /telescopes: {e}")
+            return None
+
     def __init__(self, host: str, token: str, use_ssl: bool = True, logger=None):
         self.base_url = ("https" if use_ssl else "http") + "://" + host
         self.token = token
@@ -57,8 +71,10 @@ class CitraApiClient(AbstractCitraApiClient):
 
     def upload_image(self, task_id, telescope_id, filepath):
         """Upload an image file for a given task."""
+        file_size = os.path.getsize(filepath)
         signed_url_response = self._request(
-            "POST", f"/my/images?filename=citra_task_{task_id}_image.fits&telescope_id={telescope_id}&task_id={task_id}"
+            "POST",
+            f"/my/images?filename=citra_task_{task_id}_image.fits&telescope_id={telescope_id}&task_id={task_id}&file_size={file_size}",
         )
         if not signed_url_response or "uploadUrl" not in signed_url_response:
             if self.logger:
@@ -99,3 +115,16 @@ class CitraApiClient(AbstractCitraApiClient):
             if self.logger:
                 self.logger.error(f"Failed to mark task {task_id} as complete: {e}")
             return None
+
+    def mark_task_failed(self, task_id):
+        """Mark a task as failed using the API."""
+        try:
+            body = {"status": "Failed"}
+            response = self._request("PUT", f"/tasks/{task_id}", json=body)
+            if self.logger:
+                self.logger.debug(f"Marked task {task_id} as failed: {response}")
+            return response
+        except Exception as e:
+            if self.logger:
+                self.logger.error(f"Failed to mark task {task_id} as failed: {e}")
+            return None

citrascope/citra_scope_daemon.py

@@ -3,10 +3,12 @@ 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.indi_adapter import IndiAdapter
+from citrascope.hardware.adapter_registry import get_adapter_class
 from citrascope.logging import CITRASCOPE_LOGGER
-from citrascope.settings._citrascope_settings import CitraScopeSettings
+from citrascope.logging._citrascope_logger import setup_file_logging
+from citrascope.settings.citrascope_settings import CitraScopeSettings
 from citrascope.tasks.runner import TaskManager
+from citrascope.web.server import CitraScopeWebServer
 
 
 class CitraScopeDaemon:
@@ -15,76 +17,227 @@ class CitraScopeDaemon:
         settings: CitraScopeSettings,
         api_client: Optional[AbstractCitraApiClient] = None,
         hardware_adapter: Optional[AbstractAstroHardwareAdapter] = None,
+        enable_web: bool = True,
+        web_host: str = "0.0.0.0",
+        web_port: int = 24872,
     ):
         self.settings = settings
         CITRASCOPE_LOGGER.setLevel(self.settings.log_level)
-        self.api_client = api_client or CitraApiClient(
-            self.settings.host,
-            self.settings.personal_access_token,
-            self.settings.use_ssl,
-            CITRASCOPE_LOGGER,
-        )
-        self.hardware_adapter = hardware_adapter or IndiAdapter(
-            CITRASCOPE_LOGGER, self.settings.indi_server_url, int(self.settings.indi_server_port)
-        )
 
-    def run(self):
-        CITRASCOPE_LOGGER.info(f"CitraAPISettings host is {self.settings.host}")
-        CITRASCOPE_LOGGER.info(f"CitraAPISettings telescope_id is {self.settings.telescope_id}")
-
-        # check api for valid key, telescope and ground station
-        if not self.api_client.does_api_server_accept_key():
-            CITRASCOPE_LOGGER.error("Aborting: could not authenticate with Citra API.")
-            return
-
-        citra_telescope_record = self.api_client.get_telescope(self.settings.telescope_id)
-        if not citra_telescope_record:
-            CITRASCOPE_LOGGER.error("Aborting: telescope_id is not valid on the server.")
-            return
-
-        ground_station = self.api_client.get_ground_station(citra_telescope_record["groundStationId"])
-        if not ground_station:
-            CITRASCOPE_LOGGER.error("Aborting: could not get ground station info from the server.")
-            return
-
-        # connect to hardware server
-        CITRASCOPE_LOGGER.info(f"Connecting to hardware server with {type(self.hardware_adapter).__name__}...")
-        self.hardware_adapter.connect()
-        time.sleep(1)
-        CITRASCOPE_LOGGER.info("List of hardware devices")
-        device_list = self.hardware_adapter.list_devices() or []
-
-        # check for telescope
-        if not self.settings.indi_telescope_name in device_list:
+        # Setup file logging if enabled
+        if self.settings.file_logging_enabled:
+            self.settings.config_manager.ensure_log_directory()
+            log_path = self.settings.config_manager.get_current_log_path()
+            setup_file_logging(log_path, backup_count=self.settings.log_retention_days)
+            CITRASCOPE_LOGGER.info(f"Logging to file: {log_path}")
+
+        self.api_client = api_client
+        self.hardware_adapter = hardware_adapter
+        self.enable_web = enable_web
+        self.web_server = None
+        self.task_manager = None
+        self.ground_station = None
+        self.telescope_record = None
+        self.configuration_error: Optional[str] = None
+
+        # Create web server instance if enabled (always start web server)
+        if self.enable_web:
+            self.web_server = CitraScopeWebServer(daemon=self, host=web_host, port=web_port)
+
+    def _create_hardware_adapter(self) -> AbstractAstroHardwareAdapter:
+        """Factory method to create the appropriate hardware adapter based on settings."""
+        try:
+            adapter_class = get_adapter_class(self.settings.hardware_adapter)
+            # Ensure images directory exists and pass it to the adapter
+            self.settings.ensure_images_directory()
+            images_dir = self.settings.get_images_dir()
+            return adapter_class(logger=CITRASCOPE_LOGGER, images_dir=images_dir, **self.settings.adapter_settings)
+        except ImportError as e:
             CITRASCOPE_LOGGER.error(
-                f"Aborting: could not find configured telescope ({self.settings.indi_telescope_name}) on hardware server."
+                f"{self.settings.hardware_adapter} adapter requested but dependencies not available. " f"Error: {e}"
             )
-            return
-        self.hardware_adapter.select_telescope(self.settings.indi_telescope_name)
-        self.hardware_adapter.scope_slew_rate_degrees_per_second = citra_telescope_record["maxSlewRate"]
-        CITRASCOPE_LOGGER.info(
-            f"Found configured Telescope ({self.settings.indi_telescope_name}) on hardware server"
-            + f" (slew rate: {self.hardware_adapter.scope_slew_rate_degrees_per_second} deg/sec)"
-        )
-
-        # check for camera
-        if not self.settings.indi_camera_name in device_list:
-            CITRASCOPE_LOGGER.error(
-                f"Aborting: could not find configured camera ({self.settings.indi_camera_name}) on hardware server."
+            raise RuntimeError(
+                f"{self.settings.hardware_adapter} adapter requires additional dependencies. "
+                f"Check documentation for installation instructions."
+            ) from e
+
+    def _initialize_components(self, reload_settings: bool = False) -> tuple[bool, Optional[str]]:
+        """Initialize or reinitialize all components.
+
+        Args:
+            reload_settings: If True, reload settings from disk before initializing
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        try:
+            if reload_settings:
+                CITRASCOPE_LOGGER.info("Reloading configuration...")
+                # Reload settings from file
+                new_settings = CitraScopeSettings(
+                    dev=("dev.api" in self.settings.host),
+                    log_level=self.settings.log_level,
+                    keep_images=self.settings.keep_images,
+                )
+                self.settings = new_settings
+                CITRASCOPE_LOGGER.setLevel(self.settings.log_level)
+
+                # Ensure web log handler is still attached after logger changes
+                if self.web_server:
+                    self.web_server.ensure_log_handler()
+
+                # Re-setup file logging if enabled
+                if self.settings.file_logging_enabled:
+                    self.settings.config_manager.ensure_log_directory()
+                    log_path = self.settings.config_manager.get_current_log_path()
+                    setup_file_logging(log_path, backup_count=self.settings.log_retention_days)
+
+            # Cleanup existing resources
+            if self.task_manager:
+                CITRASCOPE_LOGGER.info("Stopping existing task manager...")
+                self.task_manager.stop()
+                self.task_manager = None
+
+            if self.hardware_adapter:
+                try:
+                    self.hardware_adapter.disconnect()
+                except Exception as e:
+                    CITRASCOPE_LOGGER.warning(f"Error disconnecting hardware: {e}")
+                self.hardware_adapter = None
+
+            # Check if configuration is complete
+            if not self.settings.is_configured():
+                error_msg = "Configuration incomplete. Please set access token, telescope ID, and hardware adapter."
+                CITRASCOPE_LOGGER.warning(error_msg)
+                self.configuration_error = error_msg
+                return False, error_msg
+
+            # Initialize API client
+            self.api_client = CitraApiClient(
+                self.settings.host,
+                self.settings.personal_access_token,
+                self.settings.use_ssl,
+                CITRASCOPE_LOGGER,
             )
-            return
-        self.hardware_adapter.select_camera(self.settings.indi_camera_name)
-        CITRASCOPE_LOGGER.info(f"Found configured Camera ({self.settings.indi_camera_name}) on hardware server!")
 
-        task_manager = TaskManager(
-            self.api_client, citra_telescope_record, ground_station, CITRASCOPE_LOGGER, self.hardware_adapter
-        )
-        task_manager.start()
+            # Initialize hardware adapter
+            self.hardware_adapter = self._create_hardware_adapter()
+
+            # Initialize telescope
+            success, error = self._initialize_telescope()
+
+            if success:
+                self.configuration_error = None
+                CITRASCOPE_LOGGER.info("Components initialized successfully!")
+                return True, None
+            else:
+                self.configuration_error = error
+                return False, error
+
+        except Exception as e:
+            error_msg = f"Failed to initialize components: {str(e)}"
+            CITRASCOPE_LOGGER.error(error_msg, exc_info=True)
+            self.configuration_error = error_msg
+            return False, error_msg
+
+    def reload_configuration(self) -> tuple[bool, Optional[str]]:
+        """Reload configuration from file and reinitialize all components."""
+        return self._initialize_components(reload_settings=True)
 
-        CITRASCOPE_LOGGER.info("Starting telescope task daemon... (press Ctrl+C to exit)")
+    def _initialize_telescope(self) -> tuple[bool, Optional[str]]:
+        """Initialize telescope connection and task manager.
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        try:
+            CITRASCOPE_LOGGER.info(f"CitraAPISettings host is {self.settings.host}")
+            CITRASCOPE_LOGGER.info(f"CitraAPISettings telescope_id is {self.settings.telescope_id}")
+
+            # check api for valid key, telescope and ground station
+            if not self.api_client.does_api_server_accept_key():
+                error_msg = "Could not authenticate with Citra API. Check your access token."
+                CITRASCOPE_LOGGER.error(error_msg)
+                return False, error_msg
+
+            citra_telescope_record = self.api_client.get_telescope(self.settings.telescope_id)
+            if not citra_telescope_record:
+                error_msg = f"Telescope ID '{self.settings.telescope_id}' is not valid on the server."
+                CITRASCOPE_LOGGER.error(error_msg)
+                return False, error_msg
+            self.telescope_record = citra_telescope_record
+
+            ground_station = self.api_client.get_ground_station(citra_telescope_record["groundStationId"])
+            if not ground_station:
+                error_msg = "Could not get ground station info from the server."
+                CITRASCOPE_LOGGER.error(error_msg)
+                return False, error_msg
+            self.ground_station = ground_station
+
+            # connect to hardware server
+            CITRASCOPE_LOGGER.info(f"Connecting to hardware with {type(self.hardware_adapter).__name__}...")
+            if not self.hardware_adapter.connect():
+                error_msg = f"Failed to connect to hardware adapter: {type(self.hardware_adapter).__name__}"
+                CITRASCOPE_LOGGER.error(error_msg)
+                return False, error_msg
+
+            self.hardware_adapter.scope_slew_rate_degrees_per_second = citra_telescope_record["maxSlewRate"]
+            CITRASCOPE_LOGGER.info(
+                f"Hardware connected. Slew rate: {self.hardware_adapter.scope_slew_rate_degrees_per_second} deg/sec"
+            )
+
+            self.task_manager = TaskManager(
+                self.api_client,
+                citra_telescope_record,
+                ground_station,
+                CITRASCOPE_LOGGER,
+                self.hardware_adapter,
+                self.settings.keep_images,
+                self.settings,
+            )
+            self.task_manager.start()
+
+            CITRASCOPE_LOGGER.info("Telescope initialized successfully!")
+            return True, None
+
+        except Exception as e:
+            error_msg = f"Error initializing telescope: {str(e)}"
+            CITRASCOPE_LOGGER.error(error_msg, exc_info=True)
+            return False, error_msg
+
+    def run(self):
+        # Start web server FIRST if enabled, so users can monitor/configure
+        # The web interface will remain available even if configuration is incomplete
+        if self.enable_web:
+            self.web_server.start()
+            CITRASCOPE_LOGGER.info(f"Web interface available at http://{self.web_server.host}:{self.web_server.port}")
+
+        try:
+            # Try to initialize components
+            success, error = self._initialize_components()
+            if not success:
+                CITRASCOPE_LOGGER.warning(
+                    f"Could not start telescope operations: {error}. "
+                    f"Configure via web interface at http://{self.web_server.host}:{self.web_server.port}"
+                )
+
+            CITRASCOPE_LOGGER.info("Starting telescope task daemon... (press Ctrl+C to exit)")
+            self._keep_running()
+        finally:
+            self._shutdown()
+
+    def _keep_running(self):
+        """Keep the daemon running until interrupted."""
         try:
             while True:
                 time.sleep(1)
         except KeyboardInterrupt:
             CITRASCOPE_LOGGER.info("Shutting down daemon.")
-            task_manager.stop()
+
+    def _shutdown(self):
+        """Clean up resources on shutdown."""
+        if self.task_manager:
+            self.task_manager.stop()
+        if self.enable_web and self.web_server:
+            CITRASCOPE_LOGGER.info("Stopping web server...")
+            self.web_server.stop()

citrascope/hardware/abstract_astro_hardware_adapter.py

@@ -1,14 +1,62 @@
+import logging
 import math
 from abc import ABC, abstractmethod
+from enum import Enum
+from pathlib import Path
+from typing import Any, Optional, TypedDict
 
 
-class AbstractAstroHardwareAdapter(ABC):
+class SettingSchemaEntry(TypedDict, total=False):
+    name: str
+    friendly_name: str  # Human-readable display name for UI
+    type: str  # e.g., 'float', 'int', 'str', 'bool'
+    default: Optional[Any]
+    description: str
+    required: bool  # Whether this field is required
+    placeholder: str  # Placeholder text for UI inputs
+    min: float  # Minimum value for numeric types
+    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
+
+
+class ObservationStrategy(Enum):
+    MANUAL = 1
+    SEQUENCE_TO_CONTROLLER = 2
+
 
-    logger = None  # Optional logger, can be set by subclasses
+class AbstractAstroHardwareAdapter(ABC):
+    logger: logging.Logger  # Logger instance, must be provided by subclasses
+    images_dir: Path  # Path to images directory, must be provided during initialization
 
     _slew_min_distance_deg: float = 2.0
     scope_slew_rate_degrees_per_second: float = 0.0
 
+    def __init__(self, images_dir: Path):
+        """Initialize the adapter with images directory.
+
+        Args:
+            images_dir: Path to the images directory
+        """
+        self.images_dir = images_dir
+
+    @classmethod
+    @abstractmethod
+    def get_settings_schema(cls) -> list[SettingSchemaEntry]:
+        """
+        Return a schema describing configurable settings for this hardware adapter.
+
+        Each setting is described as a SettingSchemaEntry TypedDict with keys:
+            - name (str): The setting's name
+            - type (str): The expected Python type (e.g., 'float', 'int', 'str', 'bool')
+            - default (optional): The default value
+            - description (str): Human-readable description of the setting
+
+        Returns:
+            list[SettingSchemaEntry]: List of setting schema entries.
+        """
+        pass
+
     def point_telescope(self, ra: float, dec: float):
         """Point the telescope to the specified RA/Dec coordinates."""
         # separated out to allow pre/post processing if needed
@@ -45,6 +93,16 @@ class AbstractAstroHardwareAdapter(ABC):
     filter wheels, focus dials, and other astrophotography devices.
     """
 
+    @abstractmethod
+    def get_observation_strategy(self) -> ObservationStrategy:
+        """Get the current observation strategy from the hardware."""
+        pass
+
+    @abstractmethod
+    def perform_observation_sequence(self, task_id, satellite_data) -> str:
+        """For hardware driven by sequences, perform the observation sequence and return image path."""
+        pass
+
     @abstractmethod
     def connect(self) -> bool:
         """Connect to the hardware server."""
@@ -55,6 +113,16 @@ class AbstractAstroHardwareAdapter(ABC):
         """Disconnect from the hardware server."""
         pass
 
+    @abstractmethod
+    def is_telescope_connected(self) -> bool:
+        """Check if telescope is connected and responsive."""
+        pass
+
+    @abstractmethod
+    def is_camera_connected(self) -> bool:
+        """Check if camera is connected and responsive."""
+        pass
+
     @abstractmethod
     def list_devices(self) -> list[str]:
         """List all connected devices."""

citrascope/hardware/adapter_registry.py

@@ -0,0 +1,94 @@
+"""Hardware adapter registry.
+
+This module provides a centralized registry for all hardware adapters.
+To add a new adapter, simply add an entry to the REGISTERED_ADAPTERS dict below.
+
+Each adapter entry should include:
+- module: The full module path to import
+- class_name: The class name within that module
+- description: A human-readable description of the adapter
+
+Third-party adapters can be added by modifying this registry.
+"""
+
+import importlib
+from typing import Any, Dict, List, Type
+
+from citrascope.hardware.abstract_astro_hardware_adapter import AbstractAstroHardwareAdapter
+
+# Central registry of all available hardware adapters
+REGISTERED_ADAPTERS: Dict[str, Dict[str, str]] = {
+    "indi": {
+        "module": "citrascope.hardware.indi_adapter",
+        "class_name": "IndiAdapter",
+        "description": "INDI Protocol - Universal astronomy device control",
+    },
+    "nina": {
+        "module": "citrascope.hardware.nina_adv_http_adapter",
+        "class_name": "NinaAdvancedHttpAdapter",
+        "description": "N.I.N.A. Advanced HTTP API - Windows-based astronomy imaging",
+    },
+    "kstars": {
+        "module": "citrascope.hardware.kstars_dbus_adapter",
+        "class_name": "KStarsDBusAdapter",
+        "description": "KStars/Ekos via D-Bus - Linux astronomy suite",
+    },
+}
+
+
+def get_adapter_class(adapter_name: str) -> Type[AbstractAstroHardwareAdapter]:
+    """Get the adapter class for the given adapter name.
+
+    Args:
+        adapter_name: The name of the adapter (e.g., "indi", "nina", "kstars")
+
+    Returns:
+        The adapter class
+
+    Raises:
+        ValueError: If the adapter name is not registered
+        ImportError: If the adapter module cannot be imported (e.g., missing dependencies)
+    """
+    if adapter_name not in REGISTERED_ADAPTERS:
+        available = ", ".join(f"'{name}'" for name in REGISTERED_ADAPTERS.keys())
+        raise ValueError(f"Unknown hardware adapter type: '{adapter_name}'. " f"Valid options are: {available}")
+
+    adapter_info = REGISTERED_ADAPTERS[adapter_name]
+    module = importlib.import_module(adapter_info["module"])
+    adapter_class = getattr(module, adapter_info["class_name"])
+
+    return adapter_class
+
+
+def list_adapters() -> Dict[str, Dict[str, str]]:
+    """Get a dictionary of all registered adapters with their descriptions.
+
+    Returns:
+        Dict mapping adapter names to their info (description, module, class_name)
+    """
+    return {
+        name: {
+            "description": info["description"],
+            "module": info["module"],
+            "class_name": info["class_name"],
+        }
+        for name, info in REGISTERED_ADAPTERS.items()
+    }
+
+
+def get_adapter_schema(adapter_name: str) -> list:
+    """Get the configuration schema for a specific adapter.
+
+    Args:
+        adapter_name: The name of the adapter
+
+    Returns:
+        The adapter's settings schema
+
+    Raises:
+        ValueError: If the adapter name is not registered
+        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()