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

citrascope/hardware/nina_adv_http_adapter.py

@@ -30,22 +30,16 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
     SEQUENCE_URL = "/sequence/"
 
     def __init__(self, logger: logging.Logger, images_dir: Path, **kwargs):
-        super().__init__(images_dir=images_dir)
+        super().__init__(images_dir=images_dir, **kwargs)
         self.logger: logging.Logger = logger
         self.nina_api_path = kwargs.get("nina_api_path", "http://nina:1888/v2/api")
 
-        self.filter_map = {}
-        # Load filter configuration from settings if available
-        saved_filters = kwargs.get("filters", {})
-        for filter_id, filter_data in saved_filters.items():
-            # Convert string keys back to int for internal use
-            try:
-                self.filter_map[int(filter_id)] = filter_data
-            except (ValueError, TypeError) as e:
-                self.logger.warning(f"Invalid filter ID '{filter_id}' in settings, skipping: {e}")
+        self.binning_x = kwargs.get("binning_x", 1)
+        self.binning_y = kwargs.get("binning_y", 1)
+        self.autofocus_binning = kwargs.get("autofocus_binning", 1)
 
     @classmethod
-    def get_settings_schema(cls) -> list[SettingSchemaEntry]:
+    def get_settings_schema(cls, **kwargs) -> list[SettingSchemaEntry]:
         """
         Return a schema describing configurable settings for the NINA Advanced HTTP adapter.
         """
@@ -59,22 +53,64 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
                 "required": True,
                 "placeholder": "http://localhost:1888/v2/api",
                 "pattern": r"^https?://.*",
+                "group": "Connection",
+            },
+            {
+                "name": "autofocus_binning",
+                "friendly_name": "Autofocus Binning",
+                "type": "int",
+                "default": 1,
+                "description": "Pixel binning for autofocus (1=no binning, 2=2x2, etc.)",
+                "required": False,
+                "placeholder": "1",
+                "min": 1,
+                "max": 4,
+                "group": "Imaging",
+            },
+            {
+                "name": "binning_x",
+                "friendly_name": "Binning X",
+                "type": "int",
+                "default": 1,
+                "description": "Horizontal pixel binning for observations (1=no binning, 2=2x2, etc.)",
+                "required": False,
+                "placeholder": "1",
+                "min": 1,
+                "max": 4,
+                "group": "Imaging",
+            },
+            {
+                "name": "binning_y",
+                "friendly_name": "Binning Y",
+                "type": "int",
+                "default": 1,
+                "description": "Vertical pixel binning for observations (1=no binning, 2=2x2, etc.)",
+                "required": False,
+                "placeholder": "1",
+                "min": 1,
+                "max": 4,
+                "group": "Imaging",
             },
         ]
 
     def do_autofocus(self):
-        """Perform autofocus routine for all filters.
+        """Perform autofocus routine for all enabled filters.
 
         Slews telescope to Mirach (bright reference star) and runs autofocus
-        for each filter in the filter map, updating focus positions.
+        for each enabled filter in the filter map, updating focus positions.
 
         Raises:
-            RuntimeError: If no filters discovered or network requests fail
+            RuntimeError: If no filters discovered or no enabled filters
         """
         if not self.filter_map:
             raise RuntimeError("No filters discovered. Cannot perform autofocus.")
 
-        self.logger.info("Performing autofocus routine ...")
+        # Filter to only enabled filters
+        enabled_filters = {fid: fdata for fid, fdata in self.filter_map.items() if fdata.get("enabled", True)}
+        if not enabled_filters:
+            raise RuntimeError("No enabled filters. Cannot perform autofocus.")
+
+        self.logger.info(f"Performing autofocus routine on {len(enabled_filters)} enabled filter(s) ...")
         # move telescope to bright star and start autofocus
         # Mirach ra=(1+9/60.+47.45/3600.)*15 dec=(35+37/60.+11.1/3600.)
         ra = (1 + 9 / 60.0 + 47.45 / 3600.0) * 15
@@ -96,7 +132,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
             self.logger.info("Waiting for mount to finish slewing...")
             time.sleep(5)
 
-        for id, filter in self.filter_map.items():
+        for id, filter in enabled_filters.items():
             self.logger.info(f"Focusing Filter ID: {id}, Name: {filter['name']}")
             # Pass existing focus position to preserve it if autofocus fails
             existing_focus = filter.get("focus_position", self.DEFAULT_FOCUS_POSITION)
@@ -190,42 +226,42 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
         try:
             # start connection to all equipments
             self.logger.info("Connecting camera ...")
-            cam_status = requests.get(self.nina_api_path + self.CAM_URL + "connect").json()
+            cam_status = requests.get(self.nina_api_path + self.CAM_URL + "connect", timeout=5).json()
             if not cam_status["Success"]:
                 self.logger.error(f"Failed to connect camera: {cam_status.get('Error')}")
                 return False
             self.logger.info(f"Camera Connected!")
 
             self.logger.info("Starting camera cooling ...")
-            cool_status = requests.get(self.nina_api_path + self.CAM_URL + "cool").json()
+            cool_status = requests.get(self.nina_api_path + self.CAM_URL + "cool", timeout=5).json()
             if not cool_status["Success"]:
                 self.logger.warning(f"Failed to start camera cooling: {cool_status.get('Error')}")
             else:
                 self.logger.info("Cooler started!")
 
             self.logger.info("Connecting filterwheel ...")
-            filterwheel_status = requests.get(self.nina_api_path + self.FILTERWHEEL_URL + "connect").json()
+            filterwheel_status = requests.get(self.nina_api_path + self.FILTERWHEEL_URL + "connect", timeout=5).json()
             if not filterwheel_status["Success"]:
                 self.logger.warning(f"Failed to connect filterwheel: {filterwheel_status.get('Error')}")
             else:
                 self.logger.info(f"Filterwheel Connected!")
 
             self.logger.info("Connecting focuser ...")
-            focuser_status = requests.get(self.nina_api_path + self.FOCUSER_URL + "connect").json()
+            focuser_status = requests.get(self.nina_api_path + self.FOCUSER_URL + "connect", timeout=5).json()
             if not focuser_status["Success"]:
                 self.logger.warning(f"Failed to connect focuser: {focuser_status.get('Error')}")
             else:
                 self.logger.info(f"Focuser Connected!")
 
             self.logger.info("Connecting mount ...")
-            mount_status = requests.get(self.nina_api_path + self.MOUNT_URL + "connect").json()
+            mount_status = requests.get(self.nina_api_path + self.MOUNT_URL + "connect", timeout=5).json()
             if not mount_status["Success"]:
                 self.logger.error(f"Failed to connect mount: {mount_status.get('Error')}")
                 return False
             self.logger.info(f"Mount Connected!")
 
             self.logger.info("Unparking mount ...")
-            mount_status = requests.get(self.nina_api_path + self.MOUNT_URL + "unpark").json()
+            mount_status = requests.get(self.nina_api_path + self.MOUNT_URL + "unpark", timeout=5).json()
             if not mount_status["Success"]:
                 self.logger.error(f"Failed to unpark mount: {mount_status.get('Error')}")
                 return False
@@ -241,7 +277,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
 
     def discover_filters(self):
         self.logger.info("Discovering filters ...")
-        filterwheel_info = requests.get(self.nina_api_path + self.FILTERWHEEL_URL + "info").json()
+        filterwheel_info = requests.get(self.nina_api_path + self.FILTERWHEEL_URL + "info", timeout=5).json()
         if not filterwheel_info.get("Success"):
             self.logger.error(f"Failed to get filterwheel info: {filterwheel_info.get('Error')}")
             raise RuntimeError("Failed to get filterwheel info")
@@ -250,58 +286,33 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
         for filter in filters:
             filter_id = filter["Id"]
             filter_name = filter["Name"]
-            # Use existing focus position if filter already in map, otherwise use default
+            # Use existing focus position and enabled state if filter already in map
             if filter_id in self.filter_map:
                 focus_position = self.filter_map[filter_id].get("focus_position", self.DEFAULT_FOCUS_POSITION)
+                enabled = self.filter_map[filter_id].get("enabled", True)
                 self.logger.info(
-                    f"Discovered filter: {filter_name} with ID: {filter_id}, using saved focus position: {focus_position}"
+                    f"Discovered filter: {filter_name} with ID: {filter_id}, using saved focus position: {focus_position}, enabled: {enabled}"
                 )
             else:
                 focus_position = self.DEFAULT_FOCUS_POSITION
+                enabled = True  # Default new filters to enabled
                 self.logger.info(
                     f"Discovered new filter: {filter_name} with ID: {filter_id}, using default focus position: {focus_position}"
                 )
 
-            self.filter_map[filter_id] = {"name": filter_name, "focus_position": focus_position}
+            self.filter_map[filter_id] = {"name": filter_name, "focus_position": focus_position, "enabled": enabled}
 
     def disconnect(self):
         pass
 
+    def supports_autofocus(self) -> bool:
+        """Indicates that NINA adapter supports autofocus."""
+        return True
+
     def supports_filter_management(self) -> bool:
         """Indicates that NINA adapter supports filter/focus management."""
         return True
 
-    def get_filter_config(self) -> dict[str, FilterConfig]:
-        """Get current filter configuration with focus positions.
-
-        Returns:
-            dict: Filter configuration mapping filter ID strings to FilterConfig
-        """
-        return {
-            str(filter_id): {"name": filter_data["name"], "focus_position": filter_data["focus_position"]}
-            for filter_id, filter_data in self.filter_map.items()
-        }
-
-    def update_filter_focus(self, filter_id: str, focus_position: int) -> bool:
-        """Update the focus position for a specific filter.
-
-        Args:
-            filter_id: Filter ID as string
-            focus_position: New focus position in steps
-
-        Returns:
-            bool: True if update was successful, False otherwise
-        """
-        try:
-            filter_id_int = int(filter_id)
-            if filter_id_int in self.filter_map:
-                self.filter_map[filter_id_int]["focus_position"] = focus_position
-                self.logger.info(f"Updated filter {filter_id} focus position to {focus_position}")
-                return True
-            return False
-        except (ValueError, KeyError):
-            return False
-
     def is_telescope_connected(self) -> bool:
         """Check if telescope is connected and responsive."""
         try:
@@ -433,11 +444,11 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
             for item in data:
                 self._update_all_ids(item, id_counter)
 
-    def perform_observation_sequence(self, task_id, satellite_data) -> str | list[str]:
+    def perform_observation_sequence(self, task, satellite_data) -> str | list[str]:
         """Create and execute a NINA sequence for the given satellite.
 
         Args:
-            task_id: Unique identifier for this observation task
+            task: Task object containing id and filter assignment
             satellite_data: Satellite data including TLE information
 
         Returns:
@@ -445,11 +456,14 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
         """
         elset = satellite_data["most_recent_elset"]
 
-        # Load template as JSON
+        # Load template as JSON and replace binning placeholders
         template_str = self._get_sequence_template()
+        template_str = template_str.replace("{binning_x}", str(self.binning_x))
+        template_str = template_str.replace("{binning_y}", str(self.binning_y))
+        template_str = template_str.replace("{autofocus_binning}", str(self.autofocus_binning))
         sequence_json = json.loads(template_str)
 
-        nina_sequence_name = f"Citra Target: {satellite_data['name']}, Task: {task_id}"
+        nina_sequence_name = f"Citra Target: {satellite_data['name']}, Task: {task.id}"
 
         # Replace basic placeholders (use \r\n for Windows NINA compatibility)
         tle_data = f"{elset['tle'][0]}\r\n{elset['tle'][1]}"
@@ -486,7 +500,10 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
 
         id_counter = [base_id]  # Use list so it can be modified in nested function
 
-        for filter_id, filter_info in self.filter_map.items():
+        # Select filters to use for this task
+        filters_to_use = self.select_filters_for_task(task, allow_no_filter=False)
+
+        for filter_id, filter_info in filters_to_use.items():
             filter_name = filter_info["name"]
             focus_position = filter_info["focus_position"]
 
@@ -506,7 +523,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
             # Add this triplet to the sequence
             new_items.extend(filter_triplet)
 
-            self.logger.info(f"Added filter {filter_name} (ID: {filter_id}) with focus position {focus_position}")
+            self.logger.debug(f"Added filter {filter_name} (ID: {filter_id}) with focus position {focus_position}")
 
         # Update the items list
         tle_items.clear()
@@ -565,7 +582,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
             raise RuntimeError("Failed to get images list from NINA")
 
         images_to_download = []
-        expected_image_count = len(self.filter_map)  # One image per filter
+        expected_image_count = len(filters_to_use)  # One image per filter in sequence
         images_found = len(images_response["Response"])
         self.logger.info(
             f"Found {images_found} images in NINA image history, considering the last {expected_image_count}"

citrascope/hardware/nina_adv_http_survey_template.json

@@ -174,8 +174,8 @@
                             "_autoFocusBinning": {
                               "$id": "31",
                               "$type": "NINA.Core.Model.Equipment.BinningMode, NINA.Core",
-                              "X": 1,
-                              "Y": 1
+                              "X": {autofocus_binning},
+                              "Y": {autofocus_binning}
                             },
                             "_autoFocusGain": -1,
                             "_autoFocusOffset": -1
@@ -205,8 +205,8 @@
                           "Binning": {
                             "$id": "34",
                             "$type": "NINA.Core.Model.Equipment.BinningMode, NINA.Core",
-                            "X": 4,
-                            "Y": 4
+                            "X": {binning_x},
+                            "Y": {binning_y}
                           },
                           "ImageType": "LIGHT",
                           "ExposureCount": 130,

citrascope/settings/citrascope_settings.py

@@ -65,6 +65,26 @@ class CitraScopeSettings:
         self.file_logging_enabled: bool = config.get("file_logging_enabled", True)
         self.log_retention_days: int = config.get("log_retention_days", 30)
 
+        # Autofocus configuration (top-level/global settings)
+        self.scheduled_autofocus_enabled: bool = config.get("scheduled_autofocus_enabled", False)
+        self.autofocus_interval_minutes: int = config.get("autofocus_interval_minutes", 60)
+        self.last_autofocus_timestamp: Optional[int] = config.get("last_autofocus_timestamp")
+
+        # Validate autofocus interval
+        if (
+            not isinstance(self.autofocus_interval_minutes, int)
+            or self.autofocus_interval_minutes < 1
+            or self.autofocus_interval_minutes > 1439
+        ):
+            CITRASCOPE_LOGGER.warning(
+                f"Invalid autofocus_interval_minutes ({self.autofocus_interval_minutes}). Setting to default 60 minutes."
+            )
+            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.
 
@@ -107,6 +127,11 @@ class CitraScopeSettings:
             "max_retry_delay_seconds": self.max_retry_delay_seconds,
             "file_logging_enabled": self.file_logging_enabled,
             "log_retention_days": self.log_retention_days,
+            "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

@@ -43,6 +43,11 @@ class TaskManager:
         # Task processing control (always starts active)
         self._processing_active = True
         self._processing_lock = threading.Lock()
+        # 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():
@@ -219,6 +224,20 @@ class TaskManager:
             except Exception as e:
                 self.logger.error(f"Exception in task_runner loop: {e}", exc_info=True)
                 time.sleep(5)  # avoid tight error loop
+
+            # Check for autofocus requests between tasks
+            with self._autofocus_lock:
+                should_autofocus = self._autofocus_requested
+                if should_autofocus:
+                    self._autofocus_requested = False  # Clear flag before execution
+                # Also check if scheduled autofocus should run (inside lock to prevent race condition)
+                elif self._should_run_scheduled_autofocus():
+                    should_autofocus = True
+                    self._autofocus_requested = False  # Ensure flag is clear
+
+            if should_autofocus:
+                self._execute_autofocus()
+
             self._stop_event.wait(1)
 
     def _observe_satellite(self, task: Task):
@@ -278,6 +297,92 @@ class TaskManager:
         with self._processing_lock:
             return self._processing_active
 
+    def request_autofocus(self) -> bool:
+        """Request autofocus to run at next safe point between tasks.
+
+        Returns:
+            bool: True indicating request was queued.
+        """
+        with self._autofocus_lock:
+            self._autofocus_requested = True
+            self.logger.info("Autofocus requested - will run between tasks")
+            return True
+
+    def cancel_autofocus(self) -> bool:
+        """Cancel pending autofocus request if still queued.
+
+        Returns:
+            bool: True if autofocus was cancelled, False if nothing to cancel.
+        """
+        with self._autofocus_lock:
+            was_requested = self._autofocus_requested
+            self._autofocus_requested = False
+            if was_requested:
+                self.logger.info("Autofocus request cancelled")
+            return was_requested
+
+    def is_autofocus_requested(self) -> bool:
+        """Check if autofocus is currently requested/queued.
+
+        Returns:
+            bool: True if autofocus is queued, False otherwise.
+        """
+        with self._autofocus_lock:
+            return self._autofocus_requested
+
+    def _should_run_scheduled_autofocus(self) -> bool:
+        """Check if scheduled autofocus should run based on settings.
+
+        Returns:
+            bool: True if autofocus is enabled and interval has elapsed.
+        """
+        if not self.settings:
+            return False
+
+        # Check if scheduled autofocus is enabled (top-level setting)
+        if not self.settings.scheduled_autofocus_enabled:
+            return False
+
+        # Check if adapter supports autofocus
+        if not self.hardware_adapter.supports_autofocus():
+            return False
+
+        interval_minutes = self.settings.autofocus_interval_minutes
+        last_timestamp = self.settings.last_autofocus_timestamp
+
+        # If never run (None), treat as overdue and run immediately
+        if last_timestamp is None:
+            return True
+
+        # Check if interval has elapsed
+        elapsed_minutes = (int(time.time()) - last_timestamp) / 60
+        return elapsed_minutes >= interval_minutes
+
+    def _execute_autofocus(self) -> None:
+        """Execute autofocus routine and update timestamp on both success and failure."""
+        try:
+            self.logger.info("Starting autofocus routine...")
+            self.hardware_adapter.do_autofocus()
+
+            # Save updated filter configuration after autofocus
+            if self.hardware_adapter.supports_filter_management():
+                try:
+                    filter_config = self.hardware_adapter.get_filter_config()
+                    if filter_config and self.settings:
+                        self.settings.adapter_settings["filters"] = filter_config
+                        self.logger.info(f"Saved filter configuration with {len(filter_config)} filters")
+                except Exception as e:
+                    self.logger.warning(f"Failed to save filter configuration after autofocus: {e}")
+
+            self.logger.info("Autofocus routine completed successfully")
+        except Exception as e:
+            self.logger.error(f"Autofocus failed: {str(e)}", exc_info=True)
+        finally:
+            # Always update timestamp to prevent retry spam
+            if self.settings:
+                self.settings.last_autofocus_timestamp = int(time.time())
+                self.settings.save()
+
     def start(self):
         self._stop_event.clear()
         self.poll_thread = threading.Thread(target=self.poll_tasks, daemon=True)

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,13 @@
+"""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, NTPTimeSource
+
+__all__ = [
+    "TimeHealth",
+    "TimeStatus",
+    "TimeMonitor",
+    "AbstractTimeSource",
+    "NTPTimeSource",
+]

citrascope/time/time_health.py

@@ -0,0 +1,96 @@
+"""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, unknown)."""
+
+    message: Optional[str] = None
+    """Optional status message or error description."""
+
+    @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,
+    ) -> "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
+
+        Returns:
+            TimeHealth instance
+        """
+        status = cls.calculate_status(offset_ms, pause_threshold)
+        return cls(
+            offset_ms=offset_ms,
+            status=status,
+            source=source,
+            message=message,
+        )
+
+    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,
+        }