spectre-core 0.0.12__py3-none-any.whl → 0.0.13__py3-none-any.whl

spectre_core/receivers/_base.py

@@ -3,175 +3,326 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 from abc import ABC, abstractmethod
-from typing import Callable, Optional
-from numbers import Number
+from typing import Callable, Optional, Literal, overload
 
 from spectre_core.exceptions import ModeNotFoundError
-from ._spec_names import SpecNames
 from spectre_core.capture_configs import (
-    CaptureTemplate, CaptureModes, Parameters, Bound, PValidators, PNames,
-    get_base_capture_template, get_base_ptemplate, OneOf, CaptureConfig
+    CaptureTemplate, Parameters, CaptureConfig
 )
+from .plugins._receiver_names import ReceiverName
+from ._spec_names import SpecName
 
 class BaseReceiver(ABC):
-    def __init__(self, 
-                 name: str, 
-                 mode: Optional[str] = None):
+    """Abstract base class for software-defined radio receivers."""
+    def __init__(
+        self, 
+        name: ReceiverName, 
+        mode: Optional[str] = None
+    ) -> None:
+        """Initialise an instance of `BaseReceiver`.
+
+        :param name: The name of the receiver.
+        :param mode: The initial active operating mode. Defaults to None.
+        """
         self._name = name
 
-        self._specs: dict[str, Number | list[Number]] = {}
+        self._specs: dict[SpecName, float|int|list[float|int]] = {}
         self._add_specs()
         
-        self._capture_methods: dict[str, Callable] = {}
+        self._capture_methods: dict[str, Callable[[str, Parameters], None]] = {}
         self._add_capture_methods()
-    
-        self._pvalidators: dict[str, Callable] = {}
-        self._add_pvalidators()
-
+        
         self._capture_templates: dict[str, CaptureTemplate] = {}
         self._add_capture_templates()
+    
+        self._pvalidators: dict[str, Callable[[Parameters], None]] = {}
+        self._add_pvalidators()
 
-        self.mode = mode
+        self._mode = None
+        if mode is not None:
+            self.mode = mode
 
 
     @abstractmethod
-    def _add_specs(self) -> None:
-        pass
+    def _add_specs(
+        self
+    ) -> None:
+        """Subclasses must use `add_spec` to add hardware specifications."""
     
 
     @abstractmethod
-    def _add_capture_methods(self) -> None:
-        pass
-
+    def _add_capture_methods(
+        self
+    ) -> None:
+        """Subclasses must use `add_capture_method` to specify which method is called to capture 
+        data, for each operating mode."""
+        
 
     @abstractmethod
-    def _add_pvalidators(self) -> None:
-        pass
+    def _add_capture_templates(
+        self
+    ) -> None:
+        """Subclasses must use `add_capture_template` to define a `CaptureTemplate` for each operating mode."""
 
 
     @abstractmethod
-    def _add_capture_templates(self) -> None:
-        pass
+    def _add_pvalidators(
+        self
+    ) -> None:
+        """Subclasses must use `add_pvalidator` to add a parameter validation function (pvalidator) 
+        for each operating mode."""
 
     
     @property
-    def name(self) -> str:
+    def name(
+        self
+    ) -> ReceiverName:
+        """The name of the receiver."""
         return self._name
     
 
     @property
-    def capture_methods(self) -> dict[str, Callable]:
+    def capture_methods(
+        self
+    ) -> dict[str, Callable[[str, Parameters], None]]:
+        """For each operating mode, the method which is called to capture data."""
         return self._capture_methods
-    
-
+  
+  
     @property
-    def pvalidators(self) -> dict[str, Callable]:
-        return self._pvalidators
+    def capture_templates(
+        self
+    ) -> dict[str, CaptureTemplate]:
+        """For each operating mode, the corresponding `CaptureTemplate`."""
+        return self._capture_templates  
 
 
     @property
-    def capture_templates(self) -> dict[str, CaptureTemplate]:
-        return self._capture_templates
+    def pvalidators(
+        self
+    ) -> dict[str, Callable[[Parameters], None]]:
+        """For each operating mode, the corresponding parameter validation function (pvalidator)."""
+        return self._pvalidators
 
 
     @property
-    def specs(self) -> dict[str, Number]:
+    def specs(
+        self
+    ) -> dict[SpecName, float|int|list[float|int]]:
+        """The hardware specifications."""
         return self._specs
 
 
     @property
-    def modes(self) -> list[str]:
+    def modes(
+        self
+    ) -> list[str]:
+        """The operating modes for the receiver.
+
+        :raises ValueError: If the modes are inconsistent between `capture_methods`,
+        `pvalidators` and `capture_templates`.
+        """
         capture_method_modes    = list(self.capture_methods.keys())
         pvalidator_modes        = list(self.pvalidators.keys())
         capture_template_modes  = list(self.capture_templates.keys())
-
-        if capture_method_modes == pvalidator_modes == capture_template_modes:
-            return capture_method_modes
-        else:
+        
+        if not capture_method_modes == pvalidator_modes == capture_template_modes:
             raise ValueError(f"Mode mismatch for the receiver {self.name}.")
+        return capture_method_modes
 
 
     @property
-    def mode(self) -> str:
+    def mode(
+        self
+    ) -> str:
+        """The active operating mode for the receiver."""
+        if self._mode is None:
+            raise ValueError(f"The operating mode for the receiver `{self.name.value}` is not set.")
         return self._mode
-    
+
 
     @mode.setter
-    def mode(self, value: Optional[str]) -> None:
-        if (value is not None) and value not in self.modes:
+    def mode(
+        self, 
+        value: str,
+    ) -> None:
+        """Set the active operating mode.
+
+        :param value: The new operating mode to activate.
+        :raises ModeNotFoundError: If the specified mode is not defined in `modes`.
+        """
+        if (value not in self.modes):
             raise ModeNotFoundError((f"{value} is not a defined mode for the receiver {self.name}. "
                                      f"Expected one of {self.modes}"))
         self._mode = value
 
 
     @property
-    def capture_method(self) -> Callable:
+    def capture_method(
+        self
+    ) -> Callable[[str, Parameters], None]:
+        """Start capturing data under the active operating mode."""
         return self.capture_methods[self.mode]
 
 
     @property
-    def pvalidator(self) -> Callable:
+    def pvalidator(
+        self
+    ) -> Callable[[Parameters], None]:
+        """The parameter validation function for the active operating mode."""
         return self.pvalidators[self.mode]
 
 
     @property
-    def capture_template(self) -> CaptureTemplate:
+    def capture_template(
+        self
+    ) -> CaptureTemplate:
+        """The `CaptureTemplate` for the active operating mode."""
         return self._capture_templates[self.mode]
 
 
-    def add_capture_method(self,
-                           mode: str,
-                           capture_method: Callable) -> None:
+    def add_capture_method(
+        self,
+        mode: str,
+        capture_method: Callable[[str, Parameters], None]
+    ) -> None:
+        """
+        Add a capture method for a specific operating mode.
+
+        :param mode: The operating mode.
+        :param capture_method: The function which captures data.
+        """
         self._capture_methods[mode] = capture_method
 
 
-    def add_pvalidator(self,
-                      mode: str,
-                      pvalidator: Callable) -> None:
+    def add_pvalidator(
+        self,
+        mode: str,
+        pvalidator: Callable[[Parameters], None]
+    ) -> None:
+        """
+        Add a parameter validation function for a specific operating mode.
+
+        :param mode: The operating mode.
+        :param pvalidator: The validation function.
+        """
         self._pvalidators[mode] = pvalidator
 
 
-    def add_capture_template(self,
-                             mode: str,
-                             capture_template: CaptureTemplate) -> CaptureTemplate:
+    def add_capture_template(
+        self,
+        mode: str,
+        capture_template: CaptureTemplate
+    ) -> None:
+        """
+        Add a `CaptureTemplate` for a specific operating mode.
+
+        :param mode: The operating mode.
+        :param capture_template: The capture template, defining parameter requirements.
+        """
         self._capture_templates[mode] = capture_template
 
 
-    def add_spec(self,
-                 name: str,
-                 value: Number) -> None:
+    def add_spec(
+        self,
+        name: SpecName,
+        value: float|int|list[float|int]
+    ) -> None:
+        """
+        Add a hardware specification.
+
+        :param name: The specification's name.
+        :param value: The specification's value.
+        """
         self.specs[name] = value
 
 
-    def get_spec(self, 
-                 spec_name: str) -> Number | list[Number]:
+    # tell static type checkers the type of specification
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.API_RETUNING_LATENCY]) -> float: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.FREQUENCY_LOWER_BOUND]) -> float: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.FREQUENCY_UPPER_BOUND]) -> float: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.SAMPLE_RATE_LOWER_BOUND]) -> int: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.SAMPLE_RATE_UPPER_BOUND]) -> int: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.BANDWIDTH_LOWER_BOUND]) -> float: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.BANDWIDTH_UPPER_BOUND]) -> float: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.RF_GAIN_UPPER_BOUND]) -> int: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.IF_GAIN_UPPER_BOUND]) -> int: ...
+    @overload
+    def get_spec(self, spec_name: Literal[SpecName.BANDWIDTH_OPTIONS]) -> list[float]: ...
+    
+    
+    def get_spec(
+        self, 
+        spec_name: SpecName
+    ) -> float|int|list[float|int]:
+        """
+        Retrieve a hardware specification.
+
+        :param spec_name: The name of the specification.
+        :raises KeyError: If the specification is not found.
+        :return: The specification's value.
+        """
         if spec_name not in self.specs:
             raise KeyError(f"Spec not found with name '{spec_name}' "
                            f"for the receiver '{self.name}'")
         return self.specs[spec_name]
 
 
-    def start_capture(self, 
-                      tag: str) -> None:
+    def start_capture(
+        self, 
+        tag: str
+    ) -> None:
+        """Start capturing data in the active operating mode.
+
+        :param tag: The tag of the capture config to load.
+        """
         self.capture_method( tag, self.load_parameters(tag) )
 
 
-    def save_parameters(self,
-                        tag: str,
-                        parameters: Parameters,
-                        force: bool = False) -> None:
+    def save_parameters(
+        self,
+        tag: str,
+        parameters: Parameters,
+        force: bool = False
+    ) -> None:
+        """Create a capture config according to the active operating mode and save the 
+        input parameters.
+
+        The input parameters are validated before being written to file.
         
+        :param tag: The tag identifying the capture config.
+        :param parameters: The parameters to save in the capture config.
+        :param force: If True, overwrites the existing file if it already exists. Defaults to False.
+        """
         parameters = self.capture_template.apply_template(parameters)
         self.pvalidator(parameters)
 
         capture_config = CaptureConfig(tag)
-        capture_config.save_parameters(self.name,
+        capture_config.save_parameters(self.name.value,
                                        self.mode,
                                        parameters,
-                                       force=force)
+                                       force)
+
+    def load_parameters(
+        self,
+        tag: str
+    ) -> Parameters:
+        """Load a capture config, and return the parameters it stores.
+
+        The parameters are validated before being returned.
 
-    def load_parameters(self,
-                        tag: str) -> Parameters:
+        :param tag: The tag identifying the capture config.
+        :return: The validated parameters stored in the capture config.
+        """
         capture_config = CaptureConfig(tag)
 
         parameters = self.capture_template.apply_template(capture_config.parameters)

spectre_core/receivers/_factory.py

@@ -2,18 +2,64 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Optional
+from typing import Optional, overload, Literal, TypeVar
 
 from spectre_core.exceptions import ReceiverNotFoundError
 from ._register import receivers
 from ._base import BaseReceiver
+from .plugins._receiver_names import ReceiverName
+from .plugins._rsp1a import RSP1A
+from .plugins._rspduo import RSPduo
+from .plugins._test import Test
 
-# used to fetch an instance of the receiver class
-def get_receiver(receiver_name: str, mode: Optional[str] = None) -> BaseReceiver:
-    Receiver = receivers.get(receiver_name)
-    if Receiver is None:
+
+@overload
+def get_receiver(
+    receiver_name: Literal[ReceiverName.RSP1A],
+    mode: Optional[str] = None
+) -> RSP1A:
+    ...
+    
+    
+@overload
+def get_receiver(
+    receiver_name: Literal[ReceiverName.RSPDUO],
+    mode: Optional[str] = None
+) -> RSPduo:
+    ...
+    
+    
+@overload
+def get_receiver(
+    receiver_name: Literal[ReceiverName.TEST],
+    mode: Optional[str] = None
+) -> Test:
+    ...
+
+
+@overload
+def get_receiver(
+    receiver_name: ReceiverName,
+    mode: Optional[str] = None
+) -> BaseReceiver:
+    ...
+
+
+def get_receiver(
+    receiver_name: ReceiverName, 
+    mode: Optional[str] = None
+) -> BaseReceiver:
+    """Get a registered receiver.
+
+    :param receiver_name: The name of the receiver.
+    :param mode: The initial operating mode for the receiver, defaults to None
+    :raises ReceiverNotFoundError: If the receiver name is not registered.
+    :return: An instance of the receiver class registered under `receiver_name`.
+    """
+    receiver_cls = receivers.get(receiver_name)
+    if receiver_cls is None:
         valid_receivers = list(receivers.keys())
         raise ReceiverNotFoundError(f"No class found for the receiver: {receiver_name}. "
                                     f"Please specify one of the following receivers {valid_receivers}")
-    return Receiver(receiver_name, 
-                    mode = mode)
+    return receiver_cls(receiver_name, 
+                        mode = mode)

spectre_core/receivers/_register.py

@@ -2,20 +2,41 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# Global dictionaries to hold the mappings
-receivers = {}
+from typing import TypeVar, Callable, Type
 
-# classes decorated with @register_receiver("<receiver_name>")
-# will be added to the global map of receivers with key "receiver_name"
-def register_receiver(receiver_name: str):
-    def decorator(cls):
+from .plugins._receiver_names import ReceiverName
+from ._base import BaseReceiver
+
+# map populated at runtime via the `register_receiver` decorator.
+receivers: dict[ReceiverName, Type[BaseReceiver]] = {}
+
+T = TypeVar('T', bound=BaseReceiver)
+def register_receiver(
+    receiver_name: ReceiverName,
+) -> Callable[[Type[T]], Type[T]]:
+    """Decorator to register a fully implemented `BaseReceiver` subclass under a specified `receiver_name`.
+
+    :param receiver_name: The name of the receiver.
+    :raises ValueError: If the provided `receiver_name` is already registered.
+    :return: A decorator that registers the `BaseReceiver` subclass under the given `receiver_name`.
+    """
+    def decorator(
+        cls: Type[T]
+    ) -> Type[T]:
+        if receiver_name in receivers:
+            raise ValueError(f"The receiver '{receiver_name}' is already registered!")
         receivers[receiver_name] = cls
         return cls
     return decorator
 
-# return a list of all receiver names
-def list_all_receiver_names() -> list[str]:
-    return list(receivers.keys())
+
+def get_registered_receivers(
+) -> list[str]:
+    """List all registered receivers.
+
+    :return: The string values of all registered `ReceiverName` enum keys.
+    """
+    return [k.value for k in receivers.keys()]
 
 
 

spectre_core/receivers/_spec_names.py

@@ -2,19 +2,30 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from dataclasses import dataclass
+from enum import Enum
 
-@dataclass(frozen=True)
-class SpecNames:
-    """A centralised store of specification names"""
-    FREQUENCY_LOWER_BOUND   : str = "frequency_lower_bound"
-    FREQUENCY_UPPER_BOUND   : str = "frequency_upper_bound"
-    SAMPLE_RATE_LOWER_BOUND : str = "sample_rate_lower_bound"
-    SAMPLE_RATE_UPPER_BOUND : str = "sample_rate_upper_bound"
-    BANDWIDTH_LOWER_BOUND   : str = "bandwidth_lower_bound"
-    BANDWIDTH_UPPER_BOUND   : str = "bandwidth_upper_bound"
-    BANDWIDTH_OPTIONS       : str = "bandwidth_options"
-    DEFINED_BANDWIDTHS      : str = "defined_bandwidths"
-    IF_GAIN_UPPER_BOUND     : str = "if_gain_upper_bound"
-    RF_GAIN_UPPER_BOUND     : str = "rf_gain_upper_bound"
-    API_RETUNING_LATENCY    : str = "api_retuning_latency"
+class SpecName(Enum):
+    """A hardware specification name.
+    
+    :ivar FREQUENCY_LOWER_BOUND: The lower bound for the center frequency, in Hz.
+    :ivar FREQUENCY_UPPER_BOUND: The upper bound for the center frequency, in Hz.
+    :ivar SAMPLE_RATE_LOWER_BOUND: The lower bound for the sampling rate, in Hz.
+    :ivar SAMPLE_RATE_UPPER_BOUND: The upper bound for the sampling rate, in Hz.
+    :ivar BANDWIDTH_LOWER_BOUND: The lower bound for the bandwidth, in Hz.
+    :ivar BANDWIDTH_UPPER_BOUND: The upper bound for the bandwidth, in Hz.
+    :ivar BANDWIDTH_OPTIONS: The permitted bandwidths for the receiver, in Hz.
+    :ivar IF_GAIN_UPPER_BOUND: The upper bound for the intermediate frequency gain, in dB.
+    Negative values indicate attenuation.
+    :ivar RF_GAIN_UPPER_BOUND: The upper bound for the radio frequency gain, in dB. 
+    Negative values indicate attenuation.
+    """
+    FREQUENCY_LOWER_BOUND    = "frequency_lower_bound"
+    FREQUENCY_UPPER_BOUND    = "frequency_upper_bound"
+    SAMPLE_RATE_LOWER_BOUND  = "sample_rate_lower_bound"
+    SAMPLE_RATE_UPPER_BOUND  = "sample_rate_upper_bound"
+    BANDWIDTH_LOWER_BOUND    = "bandwidth_lower_bound"
+    BANDWIDTH_UPPER_BOUND    = "bandwidth_upper_bound"
+    BANDWIDTH_OPTIONS        = "bandwidth_options"
+    IF_GAIN_UPPER_BOUND      = "if_gain_upper_bound"
+    RF_GAIN_UPPER_BOUND      = "rf_gain_upper_bound"
+    API_RETUNING_LATENCY     = "api_retuning_latency"

spectre_core/receivers/plugins/_receiver_names.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from enum import Enum
+
+class ReceiverName(Enum):  
+    """A `spectre` supported receiver.
+    
+    :ivar RSP1A: SDRPlay RSP1A
+    :ivar RSPDUO: SDRPlay RSPduo
+    :ivar TEST: `spectre` test receiver.
+    """
+    RSP1A  = "rsp1a"
+    RSPDUO = "rspduo"
+    TEST   = "test"

spectre_core/receivers/plugins/_rsp1a.py

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from dataclasses import dataclass
+
+from ._receiver_names import ReceiverName
+from .gr._rsp1a import CaptureMethod
+from .._spec_names import SpecName
+from ._sdrplay_receiver import SDRPlayReceiver
+from .._register import register_receiver
+
+@dataclass(frozen=True)
+class Mode:
+    """An operating mode for the `RSP1A` receiver."""
+    FIXED_CENTER_FREQUENCY  = "fixed_center_frequency"
+    SWEPT_CENTER_FREQUENCY  = "swept_center_frequency"
+
+
+@register_receiver(ReceiverName.RSP1A)
+class RSP1A(SDRPlayReceiver):
+    """Receiver implementation for the SDRPlay RSP1A (https://www.sdrplay.com/rsp1a/)"""
+    def _add_specs(self) -> None:
+        self.add_spec( SpecName.SAMPLE_RATE_LOWER_BOUND, 200e3     )
+        self.add_spec( SpecName.SAMPLE_RATE_UPPER_BOUND, 10e6      )
+        self.add_spec( SpecName.FREQUENCY_LOWER_BOUND  , 1e3       )
+        self.add_spec( SpecName.FREQUENCY_UPPER_BOUND  , 2e9       )
+        self.add_spec( SpecName.IF_GAIN_UPPER_BOUND    , -20       )
+        self.add_spec( SpecName.RF_GAIN_UPPER_BOUND    , 0         )
+        self.add_spec( SpecName.API_RETUNING_LATENCY   , 50 * 1e-3 )
+        self.add_spec( SpecName.BANDWIDTH_OPTIONS, 
+                      [200000, 300000, 600000, 1536000, 5000000, 6000000, 7000000, 8000000])
+
+
+    def _add_capture_methods(
+        self
+    ) -> None:
+        self.add_capture_method(Mode.FIXED_CENTER_FREQUENCY, 
+                                CaptureMethod.fixed_center_frequency)
+        self.add_capture_method(Mode.SWEPT_CENTER_FREQUENCY,
+                                CaptureMethod.swept_center_frequency)
+    
+
+    def _add_capture_templates(
+        self
+    ) -> None:
+        self.add_capture_template(Mode.FIXED_CENTER_FREQUENCY,
+                                  self._get_capture_template_fixed_center_frequency())
+        self.add_capture_template(Mode.SWEPT_CENTER_FREQUENCY,
+                                  self._get_capture_template_swept_center_frequency())
+        
+    
+    def _add_pvalidators(
+        self
+    ) -> None:
+        self.add_pvalidator(Mode.FIXED_CENTER_FREQUENCY,
+                            self._get_pvalidator_fixed_center_frequency())
+        self.add_pvalidator(Mode.SWEPT_CENTER_FREQUENCY,
+                            self._get_pvalidator_swept_center_frequency())