Instrument management

@classmethod
def from_ip(cls, hostname: str, port: int = 49152) -> Instrument:
    """Create TCP instrument class.

    Use this method to connect to a device that is connected to the network,
    like a Nexus.

    Parameters
    ----------
    hostname : str
        Hostname or IP to connect to.
    port : str
        Port to connect to (default: Nexus default port).

    Returns
    -------
    instrument : Instrument
        Instrument dataclass
    """
    device = PSDevices.TCPDevice(hostname, port)
    return cls._from_device(device)

@classmethod
def from_port(cls, port: str, *, baudrate: int | None = None) -> Instrument:
    """Create serial port instrument class.

    Parameters
    ----------
    port : str
        Name of the port to connect to.
    baudrate : int, optional
        Set the baudrate. If None, use the default baudrate.

    Returns
    -------
    instrument : Instrument
        Instrument dataclass
    """
    if baudrate is None:
        device = PSDevices.SerialPortDevice(port)
    else:
        device = PSDevices.SerialPortDevice(port, baudrate=baudrate)

    return cls._from_device(device)

def abort(self) -> None:
    """Abort measurement."""
    with self._lock():
        self._comm.Abort()

def connect(self) -> None:
    """Connect to instrument."""
    if self.is_connected():
        return

    # The comm manager needs to open async, because the measurement is handled async.
    # Opening the comm manager in async sets some handlers in ClientConnection
    # that are sync or async specific. This affects the measurement,
    # receive status, and device state change events.
    self._comm = asyncio.run(self.instrument._connect_async())

    firmware_warning(self._comm.Capabilities)

def disconnect(self):
    """Disconnect from the instrument."""
    if not self.is_connected():
        return

    self._comm.Disconnect()

    del self._comm

def ensure_connection(self):
    """Raises connection error if the instrument is not connected."""
    if not self.is_connected():
        raise ConnectionError('Not connected to an instrument')

def get_current_range(self) -> AllowedCurrentRanges:
    """Get the current range for the cell.

    Returns
    -------
    current_range: AllowedCurrentRanges
    """
    with self._lock():
        return cr_enum_to_string(self._comm.CurrentRange)

def get_estimated_duration(
    self: HasCommProtocol,
    method: PalmSens.Method | MethodTypeCompatible,
) -> float:
    """Get the estimated duration for this method.

    Parameters
    -----------
    method : MethodType
        The method to get the estimated duration for.

    Returns
    -------
    float
        Estimated duration in seconds.
    """
    self.ensure_connection()

    if not isinstance(method, PalmSens.Method):
        method = method._to_psmethod()

    capabilities = self._comm.Capabilities

    return method.GetMinimumEstimatedMeasurementDuration(capabilities)

def get_instrument_serial(self) -> str:
    """Return instrument serial number.

    Returns
    -------
    serial : str
        Instrument serial.
    """
    with self._lock():
        serial = self._comm.DeviceSerial.ToString()

    return serial

def get_potential_range(self) -> AllowedPotentialRanges:
    """Get the potential range for the cell.

    Returns
    -------
    potential_range: AllowedPotentialRanges
    """
    with self._lock():
        return pr_enum_to_string(self._comm.PotentialRange)

def initialize_multiplexer(self, mux_model: int) -> int:
    """Initialize the multiplexer.

    Parameters
    ----------
    mux_model: int
        The model of the multiplexer.
        - 0 = 8 channel
        - 1 = 16 channel
        - 2 = 32 channel

    Returns
    -------
    channels : int
        Number of available multiplexes channels
    """
    with self._lock():
        model = PalmSens.MuxModel(mux_model)

        if model == PalmSens.MuxModel.MUX8R2 and (
            self._comm.ClientConnection.GetType().Equals(
                clr.GetClrType(PalmSens.Comm.ClientConnectionPS4)
            )
            or self._comm.ClientConnection.GetType().Equals(
                clr.GetClrType(PalmSens.Comm.ClientConnectionMS)
            )
        ):
            self._comm.ClientConnection.ReadMuxInfo()

        self._comm.Capabilities.MuxModel = model

        if self._comm.Capabilities.MuxModel == PalmSens.MuxModel.MUX8:
            self._comm.Capabilities.NumMuxChannels = 8
        elif self._comm.Capabilities.MuxModel == PalmSens.MuxModel.MUX16:
            self._comm.Capabilities.NumMuxChannels = 16
        elif self._comm.Capabilities.MuxModel == PalmSens.MuxModel.MUX8R2:
            self._comm.ClientConnection.ReadMuxInfo()

    channels = self._comm.Capabilities.NumMuxChannels
    return channels

def is_cell_on(self) -> bool:
    """Get cell status.

    Returns
    -------
    cell_on : bool
        Return true if the cell is on
    """
    with self._lock():
        return self._comm.CellOn

def is_connected(self) -> bool:
    """Return True if an instrument connection exists."""
    try:
        self._comm
    except AttributeError:
        return False
    else:
        return True

def is_measuring(self) -> bool:
    """Return True if device is measuring."""
    return int(self._comm.State) == CommManager.DeviceState.Measurement

def measure(
    self,
    method: MethodTypeCompatible,
    *,
    callback: Callback | CallbackEIS | None = None,
    stream: Path | str | None = None,
) -> Measurement:
    """Start measurement using given method parameters.

    Parameters
    ----------
    method: MethodType
        Method parameters for measurement
    callback: Callback, optional
        If specified, call this function on every new set of data points.
        New data points are batched, and contain all points since the last
        time it was called. Each point is an instance of `ps.data.CallbackData`
        for non-impedimetric or  `ps.data.CallbackDataEIS`
        for impedimetric measurments.

        For more advanced use cases, use `InstrumentManager.events`
        to register callbacks to various events.
    stream: Path | str | None
        If defined, stream data directly to this file in JSON Lines text format
        (https://jsonlines.org). This option is useful for long-term measurements.
        In case of a PC crash or power outage, the most recent measurement data will
        still be available.

    Returns
    -------
    measurement : Measurement
        Finished measurement.
    """
    self.ensure_connection()
    self.validate_method(method)

    # note that the comm manager must be opened async so it sets the
    # correct async event handlers
    measurement_manager = MeasurementManagerAsync(comm=self._comm)

    return asyncio.run(
        measurement_manager.measure(
            method,
            callback=callback,
            stream=stream,
            events=self.events,
        )
    )

def read_current(self) -> float:
    """Read the current in µA.

    Returns
    -------
    current : float
        Current in µA.
    """
    with self._lock():
        current = self._comm.Current

    return current

def read_potential(self) -> float:
    """Read the potential in V.

    Returns
    -------
    potential : float
        Potential in V.
    """

    with self._lock():
        potential = self._comm.Potential

    return potential

def register_receive_message_callback(self, callback: Callable[[str], None], /):
    """Register callback when a message is received.

    The callback is triggered, for example, when a method is started,
    or when `send_string` is called in MethodSCRIPT.

    Parameters
    ----------
    callback: Callable[[str], None]
        The function to call when triggered
    """
    self._receive_message_callback = callback
    self._comm.ClientConnection.ReceiveMessage += self._receive_message_handler

def set_cell(self, cell_on: bool):
    """Turn the cell on or off.

    Parameters
    ----------
    cell_on : bool
        If true, turn on the cell
    """
    with self._lock():
        self._comm.CellOn = cell_on

def set_current_range(self, current_range: AllowedCurrentRanges):
    """Set the current range for the cell.

    Parameters
    ----------
    current_range: AllowedCurrentRanges
        Set the current range as a string.
        See `pypalmsens.settings.AllowedCurrentRanges` for options.
    """
    with self._lock():
        self._comm.CurrentRange = cr_string_to_enum(current_range)

def set_multiplexer_channel(self, channel: int):
    """Sets the multiplexer channel.

    Parameters
    ----------
    channel : int
        Index of the channel to set.
    """
    with self._lock():
        self._comm.ClientConnection.SetMuxChannel(channel)

def set_mux8r2_settings(
    self,
    connect_sense_to_working_electrode: bool = False,
    combine_reference_and_counter_electrodes: bool = False,
    use_channel_1_reference_and_counter_electrodes: bool = False,
    set_unselected_channel_working_electrode: int = 0,
):
    """Set the settings for the Mux8R2 multiplexer.

    Parameters
    ---------
    connect_sense_to_working_electrode: float
        Connect the sense electrode to the working electrode. Default is False.
    combine_reference_and_counter_electrodes: float
        Combine the reference and counter electrodes. Default is False.
    use_channel_1_reference_and_counter_electrodes: float
        Use channel 1 reference and counter electrodes for all working electrodes. Default is False.
    set_unselected_channel_working_electrode: float
        Set the unselected channel working electrode to disconnected/floating (0), ground (1), or standby potential (2). Default is 0.
    """
    self.ensure_connection()

    if self._comm.Capabilities.MuxModel != PalmSens.MuxModel.MUX8R2:
        raise ValueError(
            f"Incompatible mux model: {self._comm.Capabilities.MuxModel}, expected 'MUXR2'."
        )

    mux_settings = PalmSens.Method.MuxSettings(False)
    mux_settings.ConnSEWE = connect_sense_to_working_electrode
    mux_settings.ConnectCERE = combine_reference_and_counter_electrodes
    mux_settings.CommonCERE = use_channel_1_reference_and_counter_electrodes
    mux_settings.UnselWE = PalmSens.Method.MuxSettings.UnselWESetting(
        set_unselected_channel_working_electrode
    )

    with self._lock():
        self._comm.ClientConnection.SetMuxSettings(MuxType(1), mux_settings)

def set_potential(self, potential: float):
    """Set the potential of the cell.

    Parameters
    ----------
    potential : float
        Potential in V
    """
    with self._lock():
        self._comm.Potential = potential

def set_potential_range(self, potential_range: AllowedPotentialRanges):
    """Set the potential range for the cell.

    Parameters
    ----------
    potential_range: AllowedPotentialRanges
        Set the potential range as a string.
        See `pypalmsens.settings.AllowedPotentialRanges` for options.
    """
    with self._lock():
        self._comm.PotentialRange = pr_string_to_enum(potential_range)

def status(self) -> Status:
    """Get status."""
    self.ensure_connection()
    return Status(
        self._comm.get_Status(),
        device_state=str(self._comm.get_State()),  # type:ignore
    )

def supported_applied_current_ranges(self: HasCommProtocol) -> list[AllowedCurrentRanges]:
    """List applied current ranges supported by this device.

    Returns
    -------
    current_ranges: list[AllowedCurrentRanges]
        List of supported current ranges.
    """
    self.ensure_connection()
    return CapabilitiesInterface(comm=self._comm).supported_applied_current_ranges

def supported_bipot_current_ranges(self: HasCommProtocol) -> list[AllowedCurrentRanges]:
    """List bipot current ranges supported by this device.

    Returns
    -------
    current_ranges: list[AllowedCurrentRanges]
        List of supported current ranges.
    """
    self.ensure_connection()
    return CapabilitiesInterface(comm=self._comm).supported_bipot_current_ranges

def supported_current_ranges(self: HasCommProtocol) -> list[AllowedCurrentRanges]:
    """List current ranges supported by this device.

    Returns
    -------
    current_ranges: list[AllowedCurrentRanges]
        List of supported current ranges.
    """
    self.ensure_connection()
    return CapabilitiesInterface(comm=self._comm).supported_current_ranges

def supported_methods(self: HasCommProtocol) -> list[AllowedMethods]:
    """List methods supported by this device.

    Returns
    -------
    methods: list[AllowedMethods]
        List of supported methods.
    """
    self.ensure_connection()
    return CapabilitiesInterface(comm=self._comm).supported_methods

def supported_potential_ranges(self: HasCommProtocol) -> list[AllowedPotentialRanges]:
    """List applied potential ranges supported by this device.

    Returns
    -------
    potential_ranges: list[AllowedPotentialRanges]
        List of supported potential ranges.
    """
    self.ensure_connection()
    return CapabilitiesInterface(comm=self._comm).supported_potential_ranges

def unregister_receive_message_callback(self):
    """Unregister callback from message events."""
    self._comm.ClientConnection.ReceiveMessage -= self._receive_message_handler
    del self._receive_message_callback

def validate_method(
    self: HasCommProtocol,
    method: MethodTypeCompatible,
):
    """Validate method.

    Raise ValueError if the method cannot be validated.

    Parameters
    -----------
    method: MethodType
        The method to validate.
    """
    self.ensure_connection()

    capabilities = self._comm.Capabilities

    psmethod = method._to_psmethod()
    errors = psmethod.Validate(capabilities)

    if any(error.IsFatal for error in errors):
        message = '\n'.join([error.Message for error in errors])
        raise MethodIncompatibleError(f'Method not compatible:\n{message}')

def wait_digital_trigger(self, wait_for_high: bool):
    """Wait for digital trigger.

    Parameters
    ----------
    wait_for_high: bool
        Wait for digital line high before starting
    """
    with self._lock():
        while True:
            if self._comm.DigitalLineD0 == wait_for_high:
                break
            sleep(0.05)

def add(self, manager: InstrumentManagerAsync) -> None:
    """Open and add manager to the pool.

    Parameters
    ----------
    manager : InstrumentManagerAsync
        Instance of an instrument manager.
    """
    self._loop.run_until_complete(self._async.add(manager))

def connect(self, attempts: int = 1) -> None:
    """Connect all instrument managers in the pool.

    Parameters
    ----------
    attempts: int, optional
        Number of attempts to establish connection.
        Use this if you experience connection issues via USB.
    """
    self._loop.run_until_complete(self._async.connect(attempts=attempts))

def disconnect(self) -> None:
    """Disconnect all instrument managers in the pool."""
    self._loop.run_until_complete(self._async.disconnect())

def is_connected(self) -> bool:
    """Return true if all managers in the pool are connected."""
    return self._async.is_connected()

def is_disconnected(self) -> bool:
    """Return true if all managers in the pool are disconnected."""
    return self._async.is_disconnected()

def measure(
    self,
    method: MethodType,
    callback: Sequence[Callback | CallbackEIS] | Callback | CallbackEIS | None = None,
    **kwargs,
) -> list[Measurement]:
    """Concurrently run measurement on all managers in the pool.

    For hardware synchronization, set `.general.use_hardware_sync` on the method.
    For MethodSCRIPT, use 'set_channel_sync 1'.

    In addition, the pool must contain:
    - channels from a single multichannel instrument only
    - the first channel of the multichannel instrument
    - at least two channels

    All instruments are prepared and put in a waiting state.
    The measurements are started via a hardware sync trigger on channel 1.

    Parameters
    ----------
    method : MethodType
        Method parameters for measurement.
    callback : list[Callback] | Callback | CallbackEIS | None
        If specified, call these functions/this function on every new set of data points.
        New data points are batched, and contain all points since the last
        time it was called.

        Specify a sequence of callbacks to set a different function for every channel.
        The number of callbacks must match the number of channels.

        Specify a single callback to set the same function to all channels.
    **kwargs
        These keyword parameters are passed to the measure function.
    """
    return self._loop.run_until_complete(
        self._async.measure(method=method, callback=callback, **kwargs)
    )

def remove(self, manager: InstrumentManagerAsync) -> None:
    """Close and remove manager from pool.

    Parameters
    ----------
    manager : InstrumentManagerAsync
        Instance of an instrument manager.
    """
    self._loop.run_until_complete(self._async.remove(manager))

def status(self) -> list[Status]:
    """Return status for all managers in pool.

    Returns
    -------
    list[Status]
        List of status objects.
    """
    return [manager.status() for manager in self]