KSC101

Communicate with a K-Cube Solenoid Controller from Thorlabs.

KSC (Interface)

KSC(equipment: Equipment)

Communicate with a K-Cube Solenoid Controller from Thorlabs.

Regular-expression patterns that are used to select this Resource when connect() is called.

manufacturer=r"Thorlabs"
model=r"KSC"

Parameters:

Name	Type	Description	Default
equipment	Equipment	An Equipment instance.	required

A Connection instance supports the properties that are defined in ThorlabsMotion.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def __init__(self, equipment: Equipment) -> None:
    """Communicate with a K-Cube Solenoid Controller from Thorlabs.

    Regular-expression patterns that are used to select this Resource when
    [connect()][msl.equipment.schema.Equipment.connect] is called.
    ```python
    manufacturer=r"Thorlabs"
    model=r"KSC"
    ```

    Args:
        equipment: An [Equipment][] instance.

    A [Connection][msl.equipment.schema.Connection] instance supports the _properties_
    that are defined in [ThorlabsMotion][msl.equipment_resources.thorlabs.motion.ThorlabsMotion].
    """
    super().__init__(equipment)

    self._motion: ThorlabsMotion = ThorlabsMotion(equipment)

    if self._motion._init_defaults:  # pyright: ignore[reportPrivateUsage]  # noqa: SLF001
        self.operating_mode = KSC.OperatingMode.MANUAL
        self.set_cycle_parameters()
        self.set_display_parameters()
        self.set_trigger_parameters()

equipment property

equipment: Equipment

The Equipment associated with the interface.

interlock_mode property writable

interlock_mode: bool

Get/set the interlock mode.

Whether the hardware interlock is required (True) or not required (False).

operating_mode property writable

operating_mode: OperatingMode

Get/set the operating mode of the Solenoid Controller.

timeout property writable

timeout: float | None

The timeout, in seconds, for read and write operations.

A value <0 will set the timeout to be None (blocking mode).

OperatingMode (IntEnum)

Solenoid operating mode.

Attributes:

Name	Type	Description
MANUAL	int	Upon calling open_shutter the shutter remains open until close_shutter is called.
SINGLE	int	Upon calling open_shutter the shutter remains open for on_duration seconds, see set_cycle_parameters, and then closes. The shutter can also be closed by rotating the wheel on the controller downwards before on_duration elapses.
AUTO	int	The shutter will open for on_duration seconds then close for off_duration seconds and repeat between open/close states cycle_count times, see set_cycle_parameters.
TRIGGERED	int	In triggered mode, a rising/falling edge on a configured TRIG input will open the shutter, which will remain open until a falling/rising edge is detected, see set_trigger_parameters.

TriggerMode (IntEnum)

Solenoid trigger I/O mode.

Attributes:

Name	Type	Description
DISABLED	int	TRIG port is not used. 0
INPUT	int	Digital input. 1
OUTPUT	int	Digital output. 10

TriggerPolarity (IntEnum)

Solenoid trigger polarity mode.

Attributes:

Name	Type	Description
HIGH	int	Active high. 1
LOW	int	Active low. 2

close_shutter

close_shutter() -> None

Close the shutter.

Note

It is not possible to query whether the shutter is open or closed.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def close_shutter(self) -> None:
    """Close the shutter.

    !!! note
        It is not possible to query whether the shutter is open or closed.
    """
    _ = self._motion.write(0x04CB, param1=1, param2=2, dest=0x50)

disconnect

disconnect() -> None

Disconnect from the Solenoid Controller.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def disconnect(self) -> None:  # pyright: ignore[reportImplicitOverride]
    """Disconnect from the Solenoid Controller."""
    if hasattr(self, "_motion"):
        self._motion.disconnect()

get_cycle_parameters

get_cycle_parameters() -> KSCCycleParameters

Get the cycle parameters of the Solenoid Controller.

Returns:

Type	Description
KSCCycleParameters	The cycle parameters.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def get_cycle_parameters(self) -> KSCCycleParameters:
    """Get the cycle parameters of the Solenoid Controller.

    Returns:
        The cycle parameters.
    """
    _, on, off, n = unpack("<Hiii", self._motion.query(0x04C4, param1=1, dest=0x50))
    return KSCCycleParameters(on_duration=on * 1e-3, off_duration=off * 1e-3, cycle_count=n)

get_display_parameters

get_display_parameters() -> KSCDisplayParameters

Get the LED display parameters of the Solenoid Controller.

Returns:

Type	Description
KSCDisplayParameters	The LED display parameters.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def get_display_parameters(self) -> KSCDisplayParameters:
    """Get the LED display parameters of the Solenoid Controller.

    Returns:
        The LED display parameters.
    """
    _, i, d, t = unpack("<H20x3H8x", self._motion.query(0x0521, param1=1, dest=0x50))
    return KSCDisplayParameters(intensity=i, dimmed=d, timeout=t)

get_trigger_parameters

get_trigger_parameters() -> (
    tuple[TriggerMode, TriggerPolarity, TriggerMode, TriggerPolarity]
)

Get the trigger parameters for the TRIG1 and TRIG2 ports.

Returns:

Type	Description
tuple[TriggerMode, TriggerPolarity, TriggerMode, TriggerPolarity]	The (TRIG1 mode, TRIG1 polarity, TRIG2 mode, TRIG2 polarity) parameters.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def get_trigger_parameters(self) -> tuple[TriggerMode, TriggerPolarity, TriggerMode, TriggerPolarity]:
    """Get the trigger parameters for the `TRIG1` and `TRIG2` ports.

    Returns:
        The `(TRIG1 mode, TRIG1 polarity, TRIG2 mode, TRIG2 polarity)` parameters.
    """
    _, m1, p1, m2, p2 = unpack("<5H12x", self._motion.query(0x0524, param1=1, dest=0x50))
    return KSC.TriggerMode(m1), KSC.TriggerPolarity(p1), KSC.TriggerMode(m2), KSC.TriggerPolarity(p2)

hardware_info

hardware_info() -> ThorlabsHardwareInfo

Get the hardware information about the Solenoid controller.

Returns:

Type	Description
ThorlabsHardwareInfo	The hardware information.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def hardware_info(self) -> ThorlabsHardwareInfo:
    """Get the hardware information about the Solenoid controller.

    Returns:
        The hardware information.
    """
    return self._motion.hardware_info()

identify

identify() -> None

Instruct the Solenoid Controller to identify itself by flashing its LED display.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def identify(self) -> None:
    """Instruct the Solenoid Controller to identify itself by flashing its LED display."""
    self._motion.identify()

is_key_unlocked

is_key_unlocked() -> bool

Get the state of the safety key.

Returns:

Type	Description
bool	Whether the safety key is in the locked (False) or unlocked (True) position.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def is_key_unlocked(self) -> bool:
    """Get the state of the safety key.

    Returns:
        Whether the safety key is in the locked (`False`) or unlocked (`True`) position.
    """
    return bool(self.status() & (1 << 13))

open_shutter

open_shutter() -> None

Open the shutter.

Note

It is not possible to query whether the shutter is open or closed.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def open_shutter(self) -> None:
    """Open the shutter.

    !!! note
        It is not possible to query whether the shutter is open or closed.
    """
    _ = self._motion.write(0x04CB, param1=1, param2=1, dest=0x50)

set_cycle_parameters

set_cycle_parameters(
    on_duration: float = 0.5,
    off_duration: float = 0.5,
    cycle_count: float = 10000,
) -> None

Set the cycle parameters of the Solenoid Controller.

Parameters:

Name	Type	Description	Default
on_duration	float	The time, in seconds, that the shutter is open. The value must be between 0.01 and 10k seconds (accurate to the nearest ms). This parameter is not used if the OperatingMode is MANUAL or TRIGGERED .	0.5
off_duration	float	The time, in seconds, that the shutter is closed. The value must be between 0.01 and 10k seconds (accurate to the nearest ms). This parameter is only used if the OperatingMode is AUTO.	0.5
cycle_count	float	The number of open/close cycles to perform, only if the OperatingMode is AUTO. The value can be any integer from 0 to 1 million. If set to 0, the controller cycles indefinitely.	10000

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def set_cycle_parameters(
    self, on_duration: float = 0.5, off_duration: float = 0.5, cycle_count: float = 10_000
) -> None:
    """Set the cycle parameters of the Solenoid Controller.

    Args:
        on_duration (float): The time, in seconds, that the shutter is open. The value must
            be between 0.01 and 10k seconds (accurate to the nearest ms). This parameter is
            not used if the [OperatingMode][msl.equipment_resources.thorlabs.ksc.KSC.OperatingMode]
            is `MANUAL` or `TRIGGERED` .
        off_duration (float): The time, in seconds, that the shutter is closed. The value must be
            between 0.01 and 10k seconds (accurate to the nearest ms). This parameter is only used
            if the [OperatingMode][msl.equipment_resources.thorlabs.ksc.KSC.OperatingMode] is `AUTO`.
        cycle_count (float): The number of open/close cycles to perform, only if the
            [OperatingMode][msl.equipment_resources.thorlabs.ksc.KSC.OperatingMode] is `AUTO`.
            The value can be any integer from 0 to 1 million. If set to 0, the controller cycles indefinitely.
    """
    for duration in (on_duration, off_duration):
        if duration < 0.01 or duration > 10e3:  # noqa: PLR2004
            msg = f"Invalid solenoid on/off duration, {duration}, must be between 0.01 and 10k seconds"
            raise ValueError(msg)

    if cycle_count < 0 or cycle_count > 1e6:  # noqa: PLR2004
        msg = f"Invalid solenoid cycle count, {cycle_count}, must be between 0 and 1M"
        raise ValueError(msg)

    data = pack("<Hiii", 1, round(on_duration * 1e3), round(off_duration * 1e3), int(cycle_count))
    _ = self._motion.write(0x04C3, data=data, dest=0x50)

set_display_parameters

set_display_parameters(
    intensity: int = 50, dimmed: int = 5, timeout: int = 2
) -> None

Set the LED display parameters of the Solenoid Controller.

Parameters:

Name	Type	Description	Default
intensity	int	LED display intensity, as a percentage [0, 100].	50
dimmed	int	Percentage of the full intensity to dim the LED display. The value must be between 0 (off) to 10 (brightest).	5
timeout	int	The number of minutes of inactivity after which the intensity is dimmed. The value must be in the range [0, 480]. Set to 0 to disable dimming.	2

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def set_display_parameters(self, intensity: int = 50, dimmed: int = 5, timeout: int = 2) -> None:
    """Set the LED display parameters of the Solenoid Controller.

    Args:
        intensity (int): LED display intensity, as a percentage [0, 100].
        dimmed (int): Percentage of the full intensity to dim the LED display.
            The value must be between 0 (off) to 10 (brightest).
        timeout (int): The number of minutes of inactivity after which the intensity is dimmed.
            The value must be in the range [0, 480]. Set to 0 to disable dimming.
    """
    if intensity < 0 or intensity > 100:  # noqa: PLR2004
        msg = f"Invalid solenoid display intensity, {intensity}, must be between 0 and 100"
        raise ValueError(msg)

    if dimmed < 0 or dimmed > 10:  # noqa: PLR2004
        msg = f"Invalid solenoid display dimmed intensity, {dimmed}, must be between 0 and 10"
        raise ValueError(msg)

    if timeout < 0 or timeout > 480:  # noqa: PLR2004
        msg = f"Invalid solenoid display timeout, {timeout}, must be between 0 and 480"
        raise ValueError(msg)

    data = pack("<H20x3H8x", 1, intensity, dimmed, timeout)
    _ = self._motion.write(0x0520, data=data, dest=0x50)

set_trigger_parameters

set_trigger_parameters(
    mode1: TriggerMode | int | str = "INPUT",
    polarity1: TriggerPolarity | int | str = "HIGH",
    mode2: TriggerMode | int | str = "OUTPUT",
    polarity2: TriggerPolarity | int | str = "HIGH",
) -> None

Set the trigger parameters for the TRIG1 and TRIG2 ports.

Parameters:

Name	Type	Description	Default
mode1	TriggerMode | int | str	TRIG1 mode. Can be an enum member name (case insensitive) or value.	'INPUT'
polarity1	TriggerPolarity | int | str	TRIG1 polarity. Can be an enum member name (case insensitive) or value.	'HIGH'
mode2	TriggerMode | int | str	TRIG2 mode. Can be an enum member name (case insensitive) or value.	'OUTPUT'
polarity2	TriggerPolarity | int | str	TRIG2 polarity. Can be an enum member name (case insensitive) or value.	'HIGH'

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def set_trigger_parameters(
    self,
    mode1: TriggerMode | int | str = "INPUT",
    polarity1: TriggerPolarity | int | str = "HIGH",
    mode2: TriggerMode | int | str = "OUTPUT",
    polarity2: TriggerPolarity | int | str = "HIGH",
) -> None:
    """Set the trigger parameters for the `TRIG1` and `TRIG2` ports.

    Args:
        mode1: `TRIG1` mode. Can be an enum member name (case insensitive) or value.
        polarity1: `TRIG1` polarity. Can be an enum member name (case insensitive) or value.
        mode2: `TRIG2` mode. Can be an enum member name (case insensitive) or value.
        polarity2: `TRIG2` polarity. Can be an enum member name (case insensitive) or value.
    """
    m1 = to_enum(mode1, KSC.TriggerMode, to_upper=True)
    p1 = to_enum(polarity1, KSC.TriggerPolarity, to_upper=True)
    m2 = to_enum(mode2, KSC.TriggerMode, to_upper=True)
    p2 = to_enum(polarity2, KSC.TriggerPolarity, to_upper=True)
    data = pack("<5H12x", 1, m1, p1, m2, p2)
    _ = self._motion.write(0x0523, data=data, dest=0x50)

status

status() -> int

Get the status of the Solenoid Controller.

Returns:

Type	Description
int	The status. A 32-bit value that represents the current status of the Solenoid controller. Each of the 32 bits acts as a flag (0 or 1), simultaneously indicating 32 distinct operating conditions of the Solenoid controller.

Source code in packages/resources/src/msl/equipment_resources/thorlabs/ksc.py

def status(self) -> int:
    """Get the status of the Solenoid Controller.

    Returns:
        The status. A 32-bit value that represents the current status of the Solenoid controller.
            Each of the 32 bits acts as a flag (0 or 1), simultaneously indicating 32 distinct
            operating conditions of the Solenoid controller.
    """
    return self._motion.status()

KSCCycleParameters dataclass

KSCCycleParameters(on_duration: float, off_duration: float, cycle_count: int)

Cycle parameters of the Solenoid Controller.

Attributes:

Name	Type	Description
on_duration	float	The time, in seconds, that the shutter is open.
off_duration	float	The time, in seconds, that the shutter is closed.
cycle_count	int	The number of open/close cycles to perform. If 0, the controller cycles indefinitely.

KSCDisplayParameters dataclass

KSCDisplayParameters(intensity: int, dimmed: int, timeout: int)

LED display parameters of the Solenoid Controller.

Attributes:

Name	Type	Description
intensity	int	LED display intensity, as a percentage.
dimmed	int	Percentage of the full intensity to dim the LED display.
timeout	int	The number of minutes of inactivity after which the intensity is dimmed. If 0, dimming is disable.