pymmcore-plus 0.14.0__py3-none-any.whl → 0.15.2__py3-none-any.whl

pymmcore_plus/experimental/unicore/devices/_camera.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Callable, ClassVar, Literal
+
+from pymmcore_plus.core._constants import DeviceType, Keyword, PixelFormat
+
+from ._device_base import Device
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Mapping, Sequence
+
+    import numpy as np
+    from numpy.typing import DTypeLike
+
+
+class CameraDevice(Device):
+    # mandatory methods for Camera device adapters
+
+    _TYPE: ClassVar[Literal[DeviceType.Camera]] = DeviceType.Camera
+
+    @abstractmethod
+    def get_exposure(self) -> float:
+        """Get the current exposure time in milliseconds."""
+        ...
+
+    @abstractmethod
+    def set_exposure(self, exposure: float) -> None:
+        """Set the exposure time in milliseconds."""
+        ...
+
+    @abstractmethod
+    def shape(self) -> tuple[int, ...]:
+        """Return the shape of the image buffer.
+
+        This is used when querying Width, Height, *and* number of components.
+        If the camera is grayscale, it should return (width, height).
+        If the camera is color, it should return (width, height, n_channels).
+        """
+
+    @abstractmethod
+    def dtype(self) -> DTypeLike:
+        """Return the data type of the image buffer."""
+
+    @abstractmethod
+    def start_sequence(
+        self,
+        n: int | None,
+        get_buffer: Callable[[Sequence[int], DTypeLike], np.ndarray],
+    ) -> Iterator[Mapping]:
+        """Start a sequence acquisition.
+
+        This method should be implemented by the camera device adapter and should
+        yield metadata for each acquired image. The implementation should call
+        get_buffer() to get a buffer, fill it with image data, then yield the
+        metadata for that image.
+
+        The core will handle threading and synchronization.  This function may block.
+
+        Parameters
+        ----------
+        n : int | None
+            If an integer, this is the number of images to acquire.
+            If None, the camera should acquire images indefinitely until stopped.
+        get_buffer : Callable[[Sequence[int], DTypeLike], np.ndarray]
+            A callable that returns a buffer for the camera to fill with image data.
+            You should call this with the shape of the image and the dtype
+            of the image data.  The core will produce a buffer of the requested shape
+            and dtype, and you should fill it (in place) with the image data.
+
+        Yields
+        ------
+        Mapping
+            Metadata for each acquired image. This should be yielded after the
+            corresponding buffer has been filled with image data.
+        """
+        # EXAMPLE USAGE:
+        # shape, dtype = self.shape(), self.dtype()
+        # if n is None:  # acquire indefinitely until stopped
+        #    while True:
+        #        yield ...
+        #    return
+        # for _ in range(n):
+        #     image = get_buffer(shape, dtype)
+        #     get the image from the camera, and fill the buffer in place
+        #     image[:] = <your_camera_data>
+        #     notify the core that the buffer is ready, and provide any metadata
+        #     yield {"key": "value", ...}  # metadata for the image
+
+        #     TODO:
+        #     Open question: who is responsible for key pieces of metadata?
+        #     in CMMCore, each of the camera device adapters is responsible for
+        #     injecting to following bits of metadata:
+        #     - MM::g_Keyword_Metadata_CameraLabel
+        #     - MM::g_Keyword_Elapsed_Time_ms (GetCurrentMMTime - start_time)
+        #     - MM::g_Keyword_Metadata_ROI_X
+        #     - MM::g_Keyword_Metadata_ROI_Y
+        #     - MM::g_Keyword_Binning
+        #     --- while the CircularBuffer InsertMultiChannel is responsible for adding:
+        #     - MM::g_Keyword_Metadata_ImageNumber
+        #     - MM::g_Keyword_Elapsed_Time_ms
+        #     - MM::g_Keyword_Metadata_TimeInCore
+        #     - MM::g_Keyword_Metadata_Width
+        #     - MM::g_Keyword_Metadata_Height
+        #     - MM::g_Keyword_PixelType
+
+    # Standard Properties --------------------------------------------
+
+    # these are the standard properties that cameras may implement.
+    # Cameras are not required to implement all of these properties, and they may
+    # implement additional properties as well.
+    # To implement a property, you MUST define a `get_<snake_name>` method and
+    # MAY define a `set_<snake_name>` method.
+    # To modify the standard properties, you can use the following methods in your
+    # __init__, (after calling super().__init__()):
+    # self.set_property_value(name, ...)
+    # self.set_property_allowed_values(name, ...)
+    # self.set_property_limits(name, ...)
+    # self.set_property_sequence_max_length(name, ...)
+
+    STANDARD_PROPERTIES: ClassVar = MappingProxyType(
+        {
+            Keyword.ActualInterval_ms: ("actual_interval_ms", float),
+            Keyword.Binning: ("binning", int),
+            Keyword.CameraID: ("camera_id", str),
+            Keyword.CameraName: ("camera_name", str),
+            Keyword.CCDTemperature: ("ccd_temperature", float),
+            Keyword.CCDTemperatureSetPoint: ("ccd_temperature_set_point", float),
+            Keyword.EMGain: ("em_gain", float),
+            Keyword.Exposure: ("exposure", float),
+            Keyword.Gain: ("gain", float),
+            Keyword.Interval_ms: ("interval_ms", float),
+            Keyword.Offset: ("offset", float),
+            # Keyword.PixelType: ("pixel_type", str),  # don't use.  use PixelFormat
+            "PixelFormat": ("pixel_format", PixelFormat),
+            Keyword.ReadoutMode: ("readout_mode", str),
+            Keyword.ReadoutTime: ("readout_time", float),
+            Keyword.Metadata_ROI_X: ("roi_x", int),
+            Keyword.Metadata_ROI_Y: ("roi_y", int),
+        }
+    )
+
+    # optional methods
+    # def get_camera_name(self) -> str:
+    # def set_camera_name(self, value: str) -> None:
+    # def get_camera_id(self) -> str:
+    # def set_camera_id(self, value: str) -> None:
+    # def get_binning(self) -> str:
+    # def set_binning(self, value: str) -> None:
+    # def get_pixel_format(self) -> PixelFormat: ...
+    # def set_pixel_format(self, value: PixelFormat) -> None: ...
+    # def get_gain(self) -> str:
+    # def set_gain(self, value: str) -> None:
+    # def get_offset(self) -> str:
+    # def set_offset(self, value: str) -> None:
+    # def get_readout_mode(self) -> str:
+    # def set_readout_mode(self, value: str) -> None:
+    # def get_readout_time(self) -> str:
+    # def set_readout_time(self, value: str) -> None:
+    # def get_actual_interval_ms(self) -> str:
+    # def set_actual_interval_ms(self, value: str) -> None:
+    # def get_interval_ms(self) -> str:
+    # def set_interval_ms(self, value: str) -> None:
+    # def get_em_gain(self) -> str:
+    # def set_em_gain(self, value: str) -> None:
+    # def get_ccd_temperature(self) -> str:
+    # def set_ccd_temperature(self, value: str) -> None:
+    # def get_ccd_temperature_set_point(self) -> str:
+    # def set_ccd_temperature_set_point(self, value: str) -> None:
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.register_standard_properties()
+
+    def register_standard_properties(self) -> None:
+        """Inspect the class for standard properties and register them."""
+        cls = type(self)
+        for name, (snake_name, prop_type) in self.STANDARD_PROPERTIES.items():
+            if getter := getattr(cls, f"get_{snake_name}", None):
+                setter = getattr(cls, f"set_{snake_name}", None)
+                seq_loader = getattr(cls, f"load_{snake_name}_sequence", None)
+                seq_starter = getattr(cls, f"start_{snake_name}_sequence", None)
+                seq_stopper = getattr(cls, f"stop_{snake_name}_sequence", None)
+                self.register_property(
+                    name=name,
+                    property_type=prop_type,
+                    getter=getter,
+                    setter=setter,
+                    sequence_loader=seq_loader,
+                    sequence_starter=seq_starter,
+                    sequence_stopper=seq_stopper,
+                )
+
+    # Standard Properties, default implementations -------------------
+
+    # We always implement a standard binning getter.  It does not
+    # mean that the camera supports binning, unless they implement a setter.
+    def get_binning(self) -> int:
+        """Get the binning factor for the camera."""
+        return 1  # pragma: no cover

pymmcore_plus/experimental/unicore/devices/{_device.py → _device_base.py}

@@ -3,6 +3,7 @@ from __future__ import annotations
 import threading
 from abc import ABC
 from collections import ChainMap
+from enum import EnumMeta
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generic, TypeVar, final
 
 from pymmcore_plus.core import DeviceType
@@ -73,11 +74,11 @@ class Device(_Lockable, ABC):
 
     def __init_subclass__(cls) -> None:
         """Initialize the property controllers."""
-        cls._cls_prop_controllers = {
-            p.property.name: p
-            for p in cls.__dict__.values()
-            if isinstance(p, PropertyController)
-        }
+        cls._cls_prop_controllers = {}
+        for base in cls.__mro__:
+            for p in base.__dict__.values():
+                if isinstance(p, PropertyController):
+                    cls._cls_prop_controllers[p.property.name] = p
         return super().__init_subclass__()
 
     def register_property(
@@ -93,6 +94,9 @@ class Device(_Lockable, ABC):
         is_read_only: bool = False,
         is_pre_init: bool = False,
         property_type: PropArg = None,
+        sequence_loader: Callable[[TDev, Sequence[TProp]], None] | None = None,
+        sequence_starter: Callable[[TDev], None] | None = None,
+        sequence_stopper: Callable[[TDev], None] | None = None,
     ) -> None:
         """Manually register a property.
 
@@ -108,6 +112,9 @@ class Device(_Lockable, ABC):
         if property_type is None and default_value is not None:
             property_type = type(default_value)
 
+        if isinstance(property_type, EnumMeta) and allowed_values is None:
+            allowed_values = tuple(property_type)
+
         prop_info = PropertyInfo(
             name=name,
             default_value=default_value,
@@ -120,7 +127,14 @@ class Device(_Lockable, ABC):
             is_pre_init=is_pre_init,
             type=PropertyType.create(property_type),
         )
-        controller = PropertyController(property=prop_info, fget=getter, fset=setter)
+        controller = PropertyController(
+            property=prop_info,
+            fget=getter,
+            fset=setter,
+            fseq_load=sequence_loader,
+            fseq_start=sequence_starter,
+            fseq_stop=sequence_stopper,
+        )
         self._prop_controllers_[name] = controller
 
     def initialize(self) -> None:
@@ -154,26 +168,38 @@ class Device(_Lockable, ABC):
 
     # PROPERTIES
 
+    def _get_prop_or_raise(self, prop_name: str) -> PropertyController:
+        """Get a property controller by name or raise an error."""
+        if prop_name not in self._prop_controllers_:
+            raise KeyError(
+                f"Device {self.get_label()!r} has no property {prop_name!r}."
+            )
+        return self._prop_controllers_[prop_name]
+
+    def has_property(self, prop_name: str) -> bool:
+        """Return `True` if the device has a property with the given name."""
+        return prop_name in self._prop_controllers_
+
     def get_property_names(self) -> KeysView[str]:
         """Return the names of the properties."""
         return self._prop_controllers_.keys()
 
-    def property(self, prop_name: str) -> PropertyInfo:
+    def get_property_info(self, prop_name: str) -> PropertyInfo:
         """Return the property controller for a property."""
-        return self._prop_controllers_[prop_name].property
+        return self._get_prop_or_raise(prop_name).property
 
     def get_property_value(self, prop_name: str) -> Any:
         """Return the value of a property."""
         # TODO: catch errors
-        ctrl = self._prop_controllers_[prop_name]
+        ctrl = self._get_prop_or_raise(prop_name)
         if ctrl.fget is None:
             return ctrl.property.last_value
-        return self._prop_controllers_[prop_name].__get__(self, self.__class__)
+        return ctrl.__get__(self, self.__class__)
 
     def set_property_value(self, prop_name: str, value: Any) -> None:
         """Set the value of a property."""
         # TODO: catch errors
-        ctrl = self._prop_controllers_[prop_name]
+        ctrl = self._get_prop_or_raise(prop_name)
         if ctrl.is_read_only:
             raise ValueError(f"Property {prop_name!r} is read-only.")
         if ctrl.fset is not None:
@@ -181,41 +207,41 @@ class Device(_Lockable, ABC):
         else:
             ctrl.property.last_value = ctrl.validate(value)
 
-    def load_property_sequence(self, prop_name: str, sequence: Sequence[Any]) -> None:
-        """Load a sequence into a property."""
-        self._prop_controllers_[prop_name].load_sequence(self, sequence)
-
-    def start_property_sequence(self, prop_name: str) -> None:
-        """Start a sequence of a property."""
-        self._prop_controllers_[prop_name].start_sequence(self)
-
-    def stop_property_sequence(self, prop_name: str) -> None:
-        """Stop a sequence of a property."""
-        self._prop_controllers_[prop_name].stop_sequence(self)
-
     def set_property_allowed_values(
         self, prop_name: str, allowed_values: Sequence[Any]
     ) -> None:
         """Set the allowed values of a property."""
-        self._prop_controllers_[prop_name].property.allowed_values = allowed_values
+        self._get_prop_or_raise(prop_name).property.allowed_values = allowed_values
 
     def set_property_limits(
         self, prop_name: str, limits: tuple[float, float] | None
     ) -> None:
         """Set the limits of a property."""
-        self._prop_controllers_[prop_name].property.limits = limits
+        self._get_prop_or_raise(prop_name).property.limits = limits
 
     def set_property_sequence_max_length(self, prop_name: str, max_length: int) -> None:
         """Set the sequence max length of a property."""
-        self._prop_controllers_[prop_name].property.sequence_max_length = max_length
+        self._get_prop_or_raise(prop_name).property.sequence_max_length = max_length
+
+    def load_property_sequence(self, prop_name: str, sequence: Sequence[Any]) -> None:
+        """Load a sequence into a property."""
+        self._get_prop_or_raise(prop_name).load_sequence(self, sequence)
+
+    def start_property_sequence(self, prop_name: str) -> None:
+        """Start a sequence of a property."""
+        self._get_prop_or_raise(prop_name).start_sequence(self)
+
+    def stop_property_sequence(self, prop_name: str) -> None:
+        """Stop a sequence of a property."""
+        self._get_prop_or_raise(prop_name).stop_sequence(self)
 
     def is_property_sequenceable(self, prop_name: str) -> bool:
         """Return `True` if the property is sequenceable."""
-        return self._prop_controllers_[prop_name].is_sequenceable
+        return self._get_prop_or_raise(prop_name).is_sequenceable
 
     def is_property_read_only(self, prop_name: str) -> bool:
         """Return `True` if the property is read-only."""
-        return self._prop_controllers_[prop_name].is_read_only
+        return self._get_prop_or_raise(prop_name).is_read_only
 
 
 SeqT = TypeVar("SeqT")

pymmcore_plus/experimental/unicore/devices/_generic_device.py

@@ -0,0 +1,12 @@
+from pymmcore_plus.core._constants import DeviceType
+
+from ._device_base import Device
+
+
+class GenericDevice(Device):
+    """Generic device API, e.g. for devices that don't fit into other categories.
+
+    Generic Devices generally only use the device property interface.
+    """
+
+    _TYPE = DeviceType.GenericDevice

pymmcore_plus/experimental/unicore/devices/_properties.py

@@ -21,7 +21,7 @@ if TYPE_CHECKING:
 
     from typing_extensions import Self, TypeAlias
 
-    from ._device import Device
+    from ._device_base import Device
 
     PropArg: TypeAlias = (
         PropertyType | type | Literal["float", "integer", "string", "boolean"] | None
@@ -76,6 +76,13 @@ class PropertyInfo(Generic[TProp]):
     is_read_only: bool | None = None
     is_pre_init: bool = False
 
+    @property
+    def number_of_allowed_values(self) -> int:
+        """Return the number of allowed values."""
+        if self.allowed_values is None:
+            return 0
+        return len(self.allowed_values)
+
     @property
     def is_sequenceable(self) -> bool:
         """Return True if the property is sequenceable."""
@@ -291,7 +298,7 @@ def pymm_property(
     is_pre_init: bool = ...,
     name: str | None = ...,
     property_type: PropArg = ...,
-) -> Callable[[Callable[[TDev], TLim]], PropertyController[TDev, TLim]]: ...
+) -> Callable[[Callable[[TDev], TProp]], PropertyController[TDev, TProp]]: ...
 def pymm_property(
     fget: Callable[[TDev], TProp] | None = None,
     *,

pymmcore_plus/experimental/unicore/devices/_shutter.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+
+from pymmcore_plus.core._constants import DeviceType
+
+from ._device_base import Device
+
+
+class ShutterDevice(Device):
+    """Shutter device API, e.g. for physical shutters or electronic shutter control.
+
+    Or any 2-state device that can be either open or closed.
+    """
+
+    _TYPE = DeviceType.ShutterDevice
+
+    @abstractmethod
+    def get_open(self) -> bool:
+        """Return True if the shutter is open, False if it is closed."""
+
+    @abstractmethod
+    def set_open(self, open: bool) -> None:
+        """Set the shutter to open or closed.
+
+        Parameters
+        ----------
+        open : bool
+            True to open the shutter, False to close it.
+        """

pymmcore_plus/experimental/unicore/devices/_slm.py

@@ -0,0 +1,82 @@
+from abc import abstractmethod
+from collections.abc import Sequence
+from typing import ClassVar, Literal
+
+import numpy as np
+from numpy.typing import DTypeLike
+
+from pymmcore_plus.core._constants import DeviceType
+
+from ._device_base import SequenceableDevice
+
+
+class SLMDevice(SequenceableDevice[np.ndarray]):
+    """ABC for Spatial Light Modulator (SLM) devices.
+
+    SLM devices are capable of displaying images.  They are expected to represent a
+    rectangular grid of pixels that can be either 8-bit or 32-bit.  Illumination (light
+    source on or off) is logically independent of displaying the image.
+    """
+
+    _TYPE: ClassVar[Literal[DeviceType.SLM]] = DeviceType.SLM
+
+    @abstractmethod
+    def shape(self) -> tuple[int, ...]:
+        """Return the shape of the SLM image buffer.
+
+        This is used when querying Width, Height, *and* number of components.
+        If the SLM is grayscale, it should return (width, height).
+        If the SLM is color, it should return (width, height, n_channels).
+        """
+        ...
+
+    @abstractmethod
+    def dtype(self) -> DTypeLike:
+        """Return the data type of the image buffer."""
+        ...
+
+    @abstractmethod
+    def set_image(self, pixels: np.ndarray) -> None:
+        """Load the image into the SLM device adapter."""
+        ...
+
+    def get_image(self) -> np.ndarray:
+        """Get the current image from the SLM device adapter.
+
+        This is useful for verifying that the image was set correctly.
+        """
+        raise NotImplementedError("This SLM device does not support getting images.")
+
+    @abstractmethod
+    def display_image(self) -> None:
+        """Command the SLM to display the loaded image."""
+
+    @abstractmethod
+    def set_exposure(self, interval_ms: float) -> None:
+        """Command the SLM to turn off after a specified interval."""
+        ...
+
+    @abstractmethod
+    def get_exposure(self) -> float:
+        """Find out the exposure interval of an SLM."""
+        ...
+
+    # Sequence methods from SequenceableDevice
+    def get_sequence_max_length(self) -> int:
+        """Return the maximum length of an image sequence that can be uploaded."""
+        return 0  # Override in subclasses that support sequencing
+
+    def send_sequence(self, sequence: Sequence[np.ndarray]) -> None:
+        """Load a sequence of images to the SLM."""
+        # Default implementation - override in subclasses that support sequencing
+        raise NotImplementedError("This SLM device does not support sequences.")
+
+    def start_sequence(self) -> None:
+        """Start a sequence of images on the SLM."""
+        # Default implementation - override in subclasses that support sequencing
+        raise NotImplementedError("This SLM device does not support sequences.")
+
+    def stop_sequence(self) -> None:
+        """Stop a sequence of images on the SLM."""
+        # Default implementation - override in subclasses that support sequencing
+        raise NotImplementedError("This SLM device does not support sequences.")

pymmcore_plus/experimental/unicore/devices/_stage.py

@@ -4,7 +4,7 @@ from typing import ClassVar, Literal
 from pymmcore_plus.core import DeviceType
 from pymmcore_plus.core._constants import Keyword
 
-from ._device import SeqT, SequenceableDevice
+from ._device_base import SeqT, SequenceableDevice
 
 __all__ = ["_BaseStage"]
 

pymmcore_plus/experimental/unicore/devices/_state.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, cast
+
+from pymmcore_plus.core._constants import DeviceType, Keyword
+
+from ._device_base import Device
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+    from typing import ClassVar, Literal
+
+    from pymmcore import StateLabel
+    from typing_extensions import Self
+
+
+class StateDevice(Device):
+    """State device API, e.g. filter wheel, objective turret, etc.
+
+    A state device is a device that at any point in time is in a single state out of a
+    list of possible states, like a filter wheel, an objective turret, etc.  The
+    interface contains functions to get and set the state, to give states human readable
+    labels, and functions to make it possible to treat the state device as a shutter.
+
+    In terms of implementation, this base class provides the basic functionality by
+    presenting state and label as properties, which it keeps in sync with the
+    underlying device.
+
+    Parameters
+    ----------
+    state_labels: Mapping[int, str] | Iterable[tuple[int, str]]
+        A mapping (or iterable of 2-tuples) of integer state indices to string labels.
+    """
+
+    # Mandatory methods for state devices
+
+    @abstractmethod
+    def get_state(self) -> int:
+        """Get the current state of the device (integer index)."""
+        ...
+
+    @abstractmethod
+    def set_state(self, position: int) -> None:
+        """Set the state of the device (integer index)."""
+        ...
+
+    # ------------------ The rest is base class implementation ------------------
+    # (adaptors may override these methods if desired)
+
+    _TYPE: ClassVar[Literal[DeviceType.State]] = DeviceType.State
+
+    @classmethod
+    def from_count(cls, count: int) -> Self:
+        """Simplified constructor with just a number of states."""
+        if count < 1:
+            raise ValueError("State device must have at least one state.")
+        return cls({i: f"State-{i}" for i in range(count)})
+
+    def __init__(
+        self, state_labels: Mapping[int, str] | Iterable[tuple[int, str]], /
+    ) -> None:
+        super().__init__()
+        if not (states := dict(state_labels)):  # pragma: no cover
+            raise ValueError("State device must have at least one state.")
+
+        self._state_to_label: dict[int, StateLabel] = states  # type: ignore[assignment]
+        # reverse mapping for O(1) lookup
+        self._label_to_state: dict[str, int] = {lbl: p for p, lbl in states.items()}
+
+        self.register_standard_properties()
+
+    def register_standard_properties(self) -> None:
+        """Inspect the class for standard properties and register them."""
+        states, labels = zip(*self._state_to_label.items())
+        cls = type(self)
+        self.register_property(
+            name=Keyword.State,
+            default_value=states[0],
+            allowed_values=states,
+            getter=cls.get_state,
+            setter=cls._set_state,
+        )
+        self.register_property(
+            name=Keyword.Label.value,
+            default_value=labels[0],
+            allowed_values=labels,
+            getter=cls._get_current_label,
+            setter=cls._set_current_label,
+        )
+
+    def set_position_or_label(self, pos_or_label: int | str) -> None:
+        """Set the position of the device by index or label."""
+        if isinstance(pos_or_label, str):
+            label = pos_or_label
+            pos = self.get_position_for_label(pos_or_label)
+        else:
+            pos = int(pos_or_label)
+            label = self._state_to_label.get(pos, "")
+        if pos not in self._state_to_label:
+            raise ValueError(
+                f"Position {pos} is not a valid state. "
+                f"Available states: {self._state_to_label.keys()}"
+            )
+        self.set_property_value(Keyword.State, pos)  # will trigger set_state
+        self.set_property_value(Keyword.Label.value, label)
+
+    def assign_label_to_position(self, pos: int, label: str) -> None:
+        """Assign a User-defined label to a position."""
+        if not isinstance(pos, int):
+            raise TypeError(f"Position must be an integer, got {type(pos).__name__}.")
+
+        # update internal state
+        self._state_to_label[pos] = label = cast("StateLabel", str(label))
+        self._label_to_state[label] = pos
+        self._update_allowed_labels()
+
+    def get_position_for_label(self, label: str) -> int:
+        """Return the position corresponding to the provided label."""
+        if label not in self._label_to_state:
+            raise KeyError(
+                f"Label not defined: {label!r}. "
+                f"Available labels: {self._state_to_label.values()}"
+            )
+        return self._label_to_state[label]
+
+    # ------------------ private methods for internal use ------------------
+
+    def _update_allowed_labels(self) -> None:
+        """Update the allowed values for the label property."""
+        label_prop_info = self.get_property_info(Keyword.Label)
+        label_prop_info.allowed_values = list(self._state_to_label.values())
+
+    def _set_state(self, state: int) -> None:
+        # internal method to set the state, called by the property setter
+        # to keep the label and state property in sync
+        self.set_state(state)  # call the device-specific method
+        label = self._state_to_label.get(state, "")
+        self.set_property_value(Keyword.Label, label)
+
+    def _get_current_label(self) -> str:
+        # internal method to get the current label, called by the property getter
+        # to keep the label and state property in sync
+        pos = self.get_property_value(Keyword.State)
+        return self._state_to_label.get(pos, "")
+
+    def _set_current_label(self, label: str) -> None:
+        # internal method to set the label, called by the property setter
+        # to keep the label and state property in sync
+        pos = self._label_to_state.get(label)
+        if pos != self.get_property_value(Keyword.State):
+            self.set_property_value(Keyword.State, pos)  # will trigger set_state