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

citrascope/hardware/filter_sync.py

@@ -0,0 +1,94 @@
+"""Filter synchronization utilities for syncing hardware filters to backend API."""
+
+
+def extract_enabled_filter_names(filter_config: dict) -> list[str]:
+    """Extract names of enabled filters from hardware configuration.
+
+    Args:
+        filter_config: Dict mapping filter IDs to config dicts with 'name' and 'enabled' keys
+
+    Returns:
+        List of filter names where enabled=True
+    """
+    enabled_names = []
+    for filter_id, config in filter_config.items():
+        if config.get("enabled", False):
+            enabled_names.append(config["name"])
+    return enabled_names
+
+
+def build_spectral_config_from_expanded(expanded_filters: list[dict]) -> tuple[dict, list[str]]:
+    """Build discrete spectral_config from API expanded filter response.
+
+    Args:
+        expanded_filters: List of filter dicts from /filters/expand API response,
+                         each with 'name', 'central_wavelength_nm', 'bandwidth_nm', 'is_known'
+
+    Returns:
+        Tuple of (spectral_config dict, list of unknown filter names)
+    """
+    filter_specs = []
+    unknown_filters = []
+
+    for f in expanded_filters:
+        filter_specs.append(
+            {"name": f["name"], "central_wavelength_nm": f["central_wavelength_nm"], "bandwidth_nm": f["bandwidth_nm"]}
+        )
+        if not f.get("is_known", True):
+            unknown_filters.append(f["name"])
+
+    spectral_config = {"type": "discrete", "filters": filter_specs}
+
+    return spectral_config, unknown_filters
+
+
+def sync_filters_to_backend(api_client, telescope_id: str, filter_config: dict, logger) -> bool:
+    """Sync enabled filters from hardware to backend API.
+
+    Extracts enabled filter names, expands them via filter library API,
+    builds spectral_config, and updates telescope record.
+
+    Args:
+        api_client: CitraApiClient instance
+        telescope_id: UUID string of telescope to update
+        filter_config: Hardware filter configuration dict
+        logger: Logger instance for output
+
+    Returns:
+        True if sync succeeded, False otherwise
+    """
+    if not filter_config:
+        logger.debug("No filter configuration to sync")
+        return False
+
+    # Extract enabled filter names
+    enabled_filter_names = extract_enabled_filter_names(filter_config)
+
+    if not enabled_filter_names:
+        logger.debug("No enabled filters to sync")
+        return False
+
+    logger.info(f"Syncing {len(enabled_filter_names)} enabled filters to backend: {enabled_filter_names}")
+
+    # Expand filter names to full spectral specs via API
+    expand_response = api_client.expand_filters(enabled_filter_names)
+    if not expand_response or "filters" not in expand_response:
+        logger.warning("Failed to expand filter names - API returned no data")
+        return False
+
+    # Build spectral_config from expanded filters
+    expanded_filters = expand_response["filters"]
+    spectral_config, unknown_filters = build_spectral_config_from_expanded(expanded_filters)
+
+    if unknown_filters:
+        logger.warning(f"Unknown filters (using defaults): {unknown_filters}")
+
+    # Update telescope spectral_config via PATCH
+    update_response = api_client.update_telescope_spectral_config(telescope_id, spectral_config)
+
+    if update_response:
+        logger.info(f"Successfully synced {len(spectral_config['filters'])} filters to backend")
+        return True
+    else:
+        logger.warning("Failed to update telescope spectral_config on backend")
+        return False

citrascope/hardware/indi_adapter.py

@@ -47,7 +47,7 @@ class IndiAdapter(PyIndi.BaseClient, AbstractAstroHardwareAdapter):
         # TetraSolver.high_memory()
 
     @classmethod
-    def get_settings_schema(cls) -> list[SettingSchemaEntry]:
+    def get_settings_schema(cls, **kwargs) -> list[SettingSchemaEntry]:
         """
         Return a schema describing configurable settings for the INDI adapter.
         """
@@ -60,6 +60,7 @@ class IndiAdapter(PyIndi.BaseClient, AbstractAstroHardwareAdapter):
                 "description": "INDI server hostname or IP address",
                 "required": True,
                 "placeholder": "localhost or 192.168.1.100",
+                "group": "Connection",
             },
             {
                 "name": "port",
@@ -71,6 +72,7 @@ class IndiAdapter(PyIndi.BaseClient, AbstractAstroHardwareAdapter):
                 "placeholder": "7624",
                 "min": 1,
                 "max": 65535,
+                "group": "Connection",
             },
             {
                 "name": "telescope_name",
@@ -80,6 +82,7 @@ class IndiAdapter(PyIndi.BaseClient, AbstractAstroHardwareAdapter):
                 "description": "Name of the telescope device (leave empty to auto-detect)",
                 "required": False,
                 "placeholder": "Telescope Simulator",
+                "group": "Devices",
             },
             {
                 "name": "camera_name",
@@ -89,6 +92,7 @@ class IndiAdapter(PyIndi.BaseClient, AbstractAstroHardwareAdapter):
                 "description": "Name of the camera device (leave empty to auto-detect)",
                 "required": False,
                 "placeholder": "CCD Simulator",
+                "group": "Devices",
             },
         ]
 
@@ -726,5 +730,5 @@ class IndiAdapter(PyIndi.BaseClient, AbstractAstroHardwareAdapter):
     def get_observation_strategy(self) -> ObservationStrategy:
         return ObservationStrategy.MANUAL
 
-    def perform_observation_sequence(self, task_id, satellite_data) -> str:
+    def perform_observation_sequence(self, task, satellite_data) -> str:
         raise NotImplementedError

citrascope/hardware/kstars_dbus_adapter.py

@@ -84,7 +84,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
         self.scheduler: dbus.Interface | None = None
 
     @classmethod
-    def get_settings_schema(cls) -> list[SettingSchemaEntry]:
+    def get_settings_schema(cls, **kwargs) -> list[SettingSchemaEntry]:
         """
         Return a schema describing configurable settings for the KStars DBus adapter.
         """
@@ -97,6 +97,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "description": "D-Bus service name for KStars (default: org.kde.kstars)",
                 "required": False,
                 "placeholder": "org.kde.kstars",
+                "group": "Connection",
             },
             {
                 "name": "ccd_name",
@@ -106,6 +107,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "description": "Name of the camera device in your Ekos profile (check Ekos logs on connect for available devices)",
                 "required": False,
                 "placeholder": "CCD Simulator",
+                "group": "Devices",
             },
             {
                 "name": "filter_wheel_name",
@@ -115,6 +117,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "description": "Name of the filter wheel device (leave empty if no filter wheel)",
                 "required": False,
                 "placeholder": "Filter Simulator",
+                "group": "Devices",
             },
             {
                 "name": "optical_train_name",
@@ -124,6 +127,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "description": "Name of the optical train in your Ekos profile (check Ekos logs on connect for available trains)",
                 "required": False,
                 "placeholder": "Primary",
+                "group": "Devices",
             },
             {
                 "name": "exposure_time",
@@ -135,6 +139,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1.0",
                 "min": 0.001,
                 "max": 300.0,
+                "group": "Imaging",
             },
             {
                 "name": "frame_count",
@@ -146,6 +151,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1",
                 "min": 1,
                 "max": 100,
+                "group": "Imaging",
             },
             {
                 "name": "binning_x",
@@ -157,6 +163,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1",
                 "min": 1,
                 "max": 4,
+                "group": "Imaging",
             },
             {
                 "name": "binning_y",
@@ -168,6 +175,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1",
                 "min": 1,
                 "max": 4,
+                "group": "Imaging",
             },
             {
                 "name": "image_format",
@@ -178,6 +186,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
                 "required": False,
                 "placeholder": "Mono",
                 "options": ["Mono", "RGGB", "RGB"],
+                "group": "Imaging",
             },
         ]
 
@@ -223,7 +232,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
             raise FileNotFoundError(f"Template not found: {template_path}")
         return template_path.read_text()
 
-    def _create_sequence_file(self, task_id: str, satellite_data: dict, output_dir: Path) -> Path:
+    def _create_sequence_file(self, task_id: str, satellite_data: dict, output_dir: Path, task=None) -> Path:
         """
         Create an ESQ sequence file from template.
 
@@ -231,6 +240,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
             task_id: Unique task identifier
             satellite_data: Dictionary containing target information
             output_dir: Base output directory for captures
+            task: Optional task object containing filter assignment
 
         Returns:
             Path to the created sequence file
@@ -241,7 +251,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
         target_name = satellite_data.get("name", "Unknown").replace(" ", "_")
 
         # Generate job blocks based on filter configuration
-        jobs_xml = self._generate_job_blocks(output_dir)
+        jobs_xml = self._generate_job_blocks(output_dir, task)
 
         # Replace placeholders
         sequence_content = template.replace("{{JOBS}}", jobs_xml)
@@ -261,13 +271,14 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
         self.logger.info(f"Created sequence file: {sequence_file}")
         return sequence_file
 
-    def _generate_job_blocks(self, output_dir: Path) -> str:
+    def _generate_job_blocks(self, output_dir: Path, task=None) -> str:
         """
         Generate XML job blocks for each filter in filter_map.
         If no filters discovered, generates single job with no filter.
 
         Args:
             output_dir: Base output directory for captures
+            task: Optional task object containing filter assignment
 
         Returns:
             XML string containing one or more <Job> blocks
@@ -311,33 +322,31 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
 
         jobs = []
 
-        # Filter to only enabled filters
-        enabled_filters = {fid: fdata for fid, fdata in self.filter_map.items() if fdata.get("enabled", True)}
+        # Select filters to use for this task (allow_no_filter for KStars '--' fallback)
+        filters_to_use = self.select_filters_for_task(task, allow_no_filter=True)
 
-        if enabled_filters:
-            # Multi-filter mode: create one job per enabled filter
-            self.logger.info(
-                f"Generating {len(enabled_filters)} jobs for enabled filters: "
-                f"{[f['name'] for f in enabled_filters.values()]}"
-            )
-            for filter_idx in sorted(enabled_filters.keys()):
-                filter_info = enabled_filters[filter_idx]
-                filter_name = filter_info["name"]
-
-                job_xml = job_template.format(
-                    exposure=self.exposure_time,
-                    format=self.image_format,
-                    binning_x=self.binning_x,
-                    binning_y=self.binning_y,
-                    filter_name=filter_name,
-                    count=self.frame_count,
-                    output_dir=str(output_dir),
-                )
-                jobs.append(job_xml)
-        else:
-            # Single-filter mode: use '--' for no filter
+        if filters_to_use is None:
+            # No filters available - use '--' for no filter wheel
             filter_name = "--" if not self.filter_wheel_name else "Luminance"
-            self.logger.info(f"Generating single job with filter: {filter_name}")
+            task_id_str = task.id if task else "unknown"
+            self.logger.info(f"Using fallback filter '{filter_name}' for task {task_id_str}")
+
+            job_xml = job_template.format(
+                exposure=self.exposure_time,
+                format=self.image_format,
+                binning_x=self.binning_x,
+                binning_y=self.binning_y,
+                filter_name=filter_name,
+                count=self.frame_count,
+                output_dir=str(output_dir),
+            )
+            jobs.append(job_xml)
+            return "\n".join(jobs)
+
+        # Generate jobs for selected filters
+        for filter_idx in sorted(filters_to_use.keys()):
+            filter_info = filters_to_use[filter_idx]
+            filter_name = filter_info["name"]
 
             job_xml = job_template.format(
                 exposure=self.exposure_time,
@@ -521,12 +530,12 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
 
         return matching_files
 
-    def perform_observation_sequence(self, task_id: str, satellite_data: dict) -> list[str]:
+    def perform_observation_sequence(self, task, satellite_data: dict) -> list[str]:
         """
         Execute a complete observation sequence using Ekos Scheduler.
 
         Args:
-            task_id: Unique task identifier
+            task: Task object containing id and filter assignment
             satellite_data: Dictionary with keys: 'name', and either 'ra'/'dec' or TLE data
 
         Returns:
@@ -550,7 +559,7 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
             output_dir.mkdir(exist_ok=True, parents=True)
 
             # Clear task-specific directory to prevent Ekos from thinking job is already done
-            task_output_dir = output_dir / task_id
+            task_output_dir = output_dir / task.id
             if task_output_dir.exists():
                 shutil.rmtree(task_output_dir)
                 self.logger.info(f"Cleared existing output directory: {task_output_dir}")
@@ -560,20 +569,20 @@ class KStarsDBusAdapter(AbstractAstroHardwareAdapter):
             self.logger.info(f"Output directory: {task_output_dir}")
 
             # Create sequence and scheduler job files (use task-specific directory)
-            sequence_file = self._create_sequence_file(task_id, satellite_data, task_output_dir)
-            job_file = self._create_scheduler_job(task_id, satellite_data, sequence_file)
+            sequence_file = self._create_sequence_file(task.id, satellite_data, task_output_dir, task)
+            job_file = self._create_scheduler_job(task.id, satellite_data, sequence_file)
 
             # Ensure temp files are cleaned up even on failure
             try:
-                self._execute_observation(task_id, output_dir, sequence_file, job_file)
+                self._execute_observation(task.id, output_dir, sequence_file, job_file)
             finally:
                 # Cleanup temp files
                 self._cleanup_temp_files(sequence_file, job_file)
 
             # Retrieve and return captured images
-            image_paths = self._retrieve_captured_images(task_id, output_dir)
+            image_paths = self._retrieve_captured_images(task.id, output_dir)
             if not image_paths:
-                raise RuntimeError(f"No images captured for task {task_id}")
+                raise RuntimeError(f"No images captured for task {task.id}")
 
             self.logger.info(f"Observation sequence complete: {len(image_paths)} images captured")
             return image_paths

citrascope/hardware/nina_adv_http_adapter.py

@@ -39,7 +39,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
         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.
         """
@@ -53,6 +53,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
                 "required": True,
                 "placeholder": "http://localhost:1888/v2/api",
                 "pattern": r"^https?://.*",
+                "group": "Connection",
             },
             {
                 "name": "autofocus_binning",
@@ -64,6 +65,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1",
                 "min": 1,
                 "max": 4,
+                "group": "Imaging",
             },
             {
                 "name": "binning_x",
@@ -75,6 +77,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1",
                 "min": 1,
                 "max": 4,
+                "group": "Imaging",
             },
             {
                 "name": "binning_y",
@@ -86,6 +89,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
                 "placeholder": "1",
                 "min": 1,
                 "max": 4,
+                "group": "Imaging",
             },
         ]
 
@@ -440,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:
@@ -459,7 +463,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
         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]}"
@@ -496,12 +500,10 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
 
         id_counter = [base_id]  # Use list so it can be modified in nested function
 
-        # Filter to only enabled filters for observation
-        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 available for observation sequence")
+        # 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 enabled_filters.items():
+        for filter_id, filter_info in filters_to_use.items():
             filter_name = filter_info["name"]
             focus_position = filter_info["focus_position"]
 
@@ -521,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()
@@ -580,7 +582,7 @@ class NinaAdvancedHttpAdapter(AbstractAstroHardwareAdapter):
             raise RuntimeError("Failed to get images list from NINA")
 
         images_to_download = []
-        expected_image_count = len(enabled_filters)  # One image per enabled 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/settings/citrascope_settings.py

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

citrascope/tasks/runner.py

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

citrascope/tasks/scope/static_telescope_task.py

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

citrascope/tasks/task.py

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

citrascope/time/__init__.py

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