pyTriggerSync 0.3__py3-none-any.whl

pyTriggerSync/main.py

@@ -0,0 +1,1257 @@
+import os
+import PyQt5
+dirname = os.path.dirname(PyQt5.__file__)
+plugin_path = os.path.join(dirname, 'plugins', 'platforms')
+os.environ['QT_QPA_PLATFORM_PLUGIN_PATH'] = plugin_path
+import PyQt5.QtWidgets as Qt# QApplication, QWidget, QMainWindow, QPushButton, QHBoxLayout
+import PyQt5.QtGui as QtGui
+import PyQt5.QtCore as QtCore
+import logging
+import sys
+import argparse
+
+import abstract_instrument_interface
+import pyTriggerSync.driver
+
+
+
+graphics_dir = os.path.join(os.path.dirname(__file__), 'graphics')
+
+##This application follows the model-view-controller paradigm, but with the view and controller defined inside the same object (the GUI)
+##The model is defined by the class 'interface', and the view+controller is defined by the class 'gui'.
+
+class interface(abstract_instrument_interface.abstract_interface):
+    """
+    High-level interface for the pyTriggerSync Teensy device.
+
+    Wraps :class:`pyTriggerSync.driver.pyTriggerSync` with input validation,
+    settings persistence, and Qt signal emission. Follows the
+    model-view-controller pattern: this class is the *model*, and the companion
+    :class:`gui` class is the *view + controller*.
+
+    Class-level attributes
+    ----------------------
+    output : dict
+        Dictionary of output data produced by this interface. Defined at class
+        level so callers can inspect the keys without instantiating the class.
+        Currently empty; reserved for future use.
+
+    Signals
+    -------
+    sig_list_devices_updated : list of str
+        Emitted when the list of available devices is refreshed. Carries the
+        new list of device-descriptor strings (each in the form
+        ``"<port>: <description> [<hwid>]"``).
+    sig_delay_changed : object
+        Emitted when the output trigger delay has been read from or written to
+        the device. Carries the new delay value in nanoseconds (``int``).
+    sig_triggerduration_changed : object
+        Emitted when the output trigger duration has been read from or written
+        to the device. Carries the new duration in nanoseconds (``int``).
+    sig_mode_changed : int
+        Emitted when the device mode changes. Carries ``0`` ("Continuous
+        Trigger") or ``1`` ("Trigger Controlled by User").
+    sig_polarity_changed : int
+        Emitted when the output polarity changes. Carries ``0`` ("Negative")
+        or ``1`` ("Positive").
+    sig_divider_changed : int
+        Emitted when the sub-sampling divider changes. Carries the new divider
+        value (positive integer).
+    sig_number_of_triggers_changed : int
+        Emitted when the number of output pulses per burst changes. Carries
+        the new value (positive integer).
+    sig_external_trigger_changed : bool
+        Emitted when the external-trigger enable flag changes. Carries the new
+        boolean value.
+
+    Instance attributes
+    -------------------
+    instrument : pyTriggerSync.driver.pyTriggerSync
+        Low-level driver instance used for all serial communication with the
+        device.
+    connected_device_name : str
+        Human-readable name of the currently connected device (empty string
+        when not connected).
+    connected_device_port : str
+        Serial port of the currently connected device (set after a successful
+        connection).
+    list_devices : list of str
+        Most recently scanned list of compatible device descriptors.
+    settings : dict
+        Persistent settings dict with the following keys:
+
+        ``'delay'`` : int
+            Output trigger delay in nanoseconds. Must be >= 0. Default: ``0``.
+        ``'triggerduration'`` : int
+            Output pulse duration in nanoseconds. Must be > 0. Default: ``100``.
+        ``'mode'`` : int
+            Device operating mode: ``0`` = Continuous Trigger,
+            ``1`` = Trigger Controlled by User. Default: ``0``.
+        ``'polarity'`` : int
+            Output polarity: ``0`` = Negative, ``1`` = Positive. Default: ``1``.
+        ``'divider'`` : int
+            Sub-sampling divider (pass 1-in-N input edges through). Must be
+            > 0. Default: ``1``.
+        ``'number_of_triggers'`` : int
+            Number of output pulses per :meth:`fire_trigger` call (only
+            meaningful in mode 1). Must be > 0. Default: ``1``.
+        ``'external_trigger'`` : bool
+            When ``True``, :meth:`receive_trigger` forwards incoming triggers
+            to :meth:`fire_trigger`. Default: ``True``.
+    """
+
+    output = {}  #We define these also as class variables, to make it possible to see which data is produced by this interface without having to create an object
+
+    ## SIGNALS THAT WILL BE USED TO COMMUNICATE WITH THE GUI
+    #                                                           | Triggered when ...                                            | Sends as parameter
+    #                                                        #   -----------------------------------------------------------------------------------------------------------------------
+    sig_list_devices_updated = QtCore.pyqtSignal(list)       #   | List of devices is updated                                    | List of devices
+    sig_delay_changed = QtCore.pyqtSignal(object)            #   | Delay has changed/been read from instrument                   | New Delay
+    sig_triggerduration_changed = QtCore.pyqtSignal(object)  #   | Trigger Duration has changed/been read from instrument        | New Trigger Duration
+    sig_mode_changed = QtCore.pyqtSignal(int)                #   | The mode has changed                                          | 0 ("Continuous Trigger") or 1 ("Trigger Controlled by User")
+    sig_polarity_changed = QtCore.pyqtSignal(int)            #   | The polarity has changed                                      | 0 ("Negative") or 1 ("Positive")
+    sig_divider_changed = QtCore.pyqtSignal(int)             #   | The divider has changed                                       | New Divider
+    sig_number_of_triggers_changed = QtCore.pyqtSignal(int)  #   | The number of triggers has changed                            | New Number of Triggers
+    sig_external_trigger_changed = QtCore.pyqtSignal(bool)   #   | The external trigger setting has changed                      | New External Trigger Setting
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the interface, create the driver instance, and scan for
+        connected devices.
+
+        Parameters
+        ----------
+        **kwargs
+            Passed through to
+            :class:`abstract_instrument_interface.abstract_interface`.
+        """
+        self.output = {}
+        ### Default values of settings (might be overlapped by settings saved in .json files later)
+        self.settings = {   'delay': 0,
+                            'triggerduration': 100,
+                            'mode': 0,
+                            'polarity': 1,
+                            'divider': 1,
+                            'number_of_triggers': 1,
+                            'external_trigger' : True
+                            }
+        self.list_devices = []              #list of devices found
+        self.connected_device_name = ''
+        self.continuous_read = True
+        self._units = 'ns'
+        self._mode_names = ["Continuous Trigger", "Trigger Controlled by User"]
+        self._polarity_names = ["Negative", "Positive"]
+
+        self.instrument =  pyTriggerSync.driver.pyTriggerSync()
+        super().__init__(**kwargs)
+
+        self.refresh_list_devices()
+
+    def refresh_list_devices(self):
+        '''
+        Scan for available devices and update :attr:`list_devices`.
+
+        Calls :meth:`~pyTriggerSync.driver.pyTriggerSync.list_devices` on the
+        driver, logs the number of devices found, stores the result in
+        :attr:`list_devices`, and emits :attr:`sig_list_devices_updated` via
+        :meth:`send_list_devices`.
+        '''
+        self.logger.info(f"Looking for devices...")
+        list_valid_devices = self.instrument.list_devices()
+        self.logger.info(f"Found {len(list_valid_devices)} devices.")
+        self.list_devices = list_valid_devices
+        self.send_list_devices()
+
+    def send_list_devices(self):
+        '''
+        Emit :attr:`sig_list_devices_updated` with the current device list.
+
+        Passes :attr:`list_devices` directly as the signal payload. Typically
+        called after :meth:`refresh_list_devices`, and also called by the GUI
+        after it has connected its slots, to trigger an initial population of
+        the device combo box.
+        '''
+        self.sig_list_devices_updated.emit(self.list_devices)
+
+    def connect_device(self, device_full_name):
+        '''
+        Connect to the device identified by ``device_full_name``.
+
+        Extracts the serial port from the device descriptor string (everything
+        before the first ``':'``), calls the driver's
+        :meth:`~pyTriggerSync.driver.pyTriggerSync.connect_device`, and on
+        success calls :meth:`set_connected_state` to push the persisted
+        settings to the device. On failure, calls
+        :meth:`set_disconnected_state` and logs an error.
+
+        Parameters
+        ----------
+        device_full_name : str
+            A device descriptor string as returned by
+            :meth:`refresh_list_devices`, e.g.
+            ``"COM4: USB Serial [USB VID:PID=16C0:0483 ...]"``.
+            If empty, an error is logged and the method returns immediately.
+        '''
+        if(device_full_name==''): # Check  that the name is not empty
+            self.logger.error("No valid device has been selected")
+            return
+        self.set_connecting_state()
+        device_port = device_full_name.split(':', 1)[0]
+        self.logger.info(f"Connecting to device on port {device_port}...")
+
+        try:
+            (Msg,ID) = self.instrument.connect_device(port = device_port)
+            if(ID==1):  #If connection was successful
+                self.logger.info(f"Connected to device {device_full_name}.")
+                self.connected_device_name = device_full_name
+                self.connected_device_port = device_port
+                self.set_connected_state()
+            else: #If connection was not successful
+                self.logger.error(f"Error: {Msg}")
+                self.set_disconnected_state()
+                pass
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            self.set_disconnected_state()
+
+    def disconnect_device(self):
+        '''
+        Disconnect the currently connected device.
+
+        Calls the driver's
+        :meth:`~pyTriggerSync.driver.pyTriggerSync.disconnect_device` and
+        transitions to the disconnected state regardless of whether the
+        driver-level call succeeds (a failed disconnection typically means the
+        device was already physically unplugged, so the GUI should still reset).
+        '''
+        self.logger.info(f"Disconnecting from device {self.connected_device_name}...")
+        self.set_disconnecting_state()
+        (Msg,ID) = self.instrument.disconnect_device()
+        if(ID==1): # If disconnection was successful
+            self.logger.info(f"Disconnected from device {self.connected_device_name}.")
+            self.set_disconnected_state()
+        else: #If disconnection was not successful
+            self.logger.error(f"Error: {Msg}")
+            self.set_disconnected_state() #When disconnection is not succeful, it is typically because the device alredy lost connection
+                                          #for some reason. In this case, it is still useful to have the widget reset to disconnected state
+
+    def close(self, **kwargs):
+        '''
+        Close this interface.
+
+        Delegates entirely to
+        :meth:`abstract_instrument_interface.abstract_interface.close`, which
+        emits :attr:`~abstract_instrument_interface.abstract_interface.sig_close`,
+        saves settings, and disconnects the device if connected.
+        '''
+        super().close(**kwargs)
+
+    # ──────────────────────────────────────────────────────────────────────────
+    # Properties — thin wrappers that route attribute access through the
+    # get_*/set_* methods, so that both the GUI and external callers can use
+    # natural Python attribute syntax (e.g. ``iface.delay = 500``).
+    # ──────────────────────────────────────────────────────────────────────────
+
+    @property
+    def delay(self):
+        '''int: Output trigger delay in nanoseconds. Reads from and writes to the device.'''
+        return self.get_delay()
+
+    @delay.setter
+    def delay(self, value):
+        self.set_delay(value)
+
+    @property
+    def triggerduration(self):
+        '''int: Output pulse duration in nanoseconds. Reads from and writes to the device.'''
+        return self.get_triggerduration()
+
+    @triggerduration.setter
+    def triggerduration(self, value):
+        self.set_triggerduration(value)
+
+    @property
+    def divider(self):
+        '''int: Sub-sampling divider. Reads from and writes to the device.'''
+        return self.get_divider()
+
+    @divider.setter
+    def divider(self, value):
+        self.set_divider(value)
+
+    @property
+    def mode(self):
+        '''int: Device operating mode (0 = Continuous, 1 = User-controlled). Reads from and writes to the device.'''
+        return self.get_mode()
+
+    @mode.setter
+    def mode(self, value):
+        self.set_mode(value)
+
+    @property
+    def polarity(self):
+        '''int: Output polarity (0 = Negative, 1 = Positive). Reads from and writes to the device.'''
+        return self.get_polarity()
+
+    @polarity.setter
+    def polarity(self, value):
+        self.set_polarity(value)
+
+    @property
+    def number_of_triggers(self):
+        '''int: Number of output pulses per burst (mode 1 only). Reads from and writes to the device.'''
+        return self.get_number_of_triggers()
+
+    @number_of_triggers.setter
+    def number_of_triggers(self, value):
+        self.set_number_of_triggers(value)
+
+    def set_connected_state(self):
+        '''
+        Extend the parent :meth:`~abstract_instrument_interface.abstract_interface.set_connected_state`
+        with device-specific initialization.
+
+        After calling the parent (which emits
+        :attr:`~abstract_instrument_interface.abstract_interface.sig_connected`
+        with ``SIG_CONNECTED``), pushes all persisted values from
+        :attr:`settings` to the device in order: mode, polarity, delay,
+        trigger duration, divider, and number of triggers.
+        '''
+        super().set_connected_state()
+        self.logger.info(f"Setting parameters (based on values in config.json file)... ")
+        self.set_mode(self.settings['mode'])
+        self.set_polarity(self.settings['polarity'])
+        self.set_delay(self.settings['delay'])
+        self.set_triggerduration(self.settings['triggerduration'])
+        self.set_divider(self.settings['divider'])
+        self.set_number_of_triggers(self.settings['number_of_triggers'])
+
+    def get_delay(self):
+        '''
+        Read the current output trigger delay from the device.
+
+        Updates :attr:`settings` ``['delay']`` and emits
+        :attr:`sig_delay_changed`.
+
+        Returns
+        -------
+        int
+            Current delay in nanoseconds.
+        '''
+        self.settings['delay'] = self.instrument.delay
+        self.sig_delay_changed.emit(self.settings['delay'])
+        return self.settings['delay']
+
+    def set_delay(self, delay):
+        '''
+        Validate and write a new output trigger delay to the device.
+
+        On success, updates :attr:`settings` ``['delay']`` and emits
+        :attr:`sig_delay_changed`. On any validation or communication error,
+        logs the error and re-emits :attr:`sig_delay_changed` with the
+        previous value so the GUI reverts.
+
+        Parameters
+        ----------
+        delay : int or str
+            Desired delay in nanoseconds. Must be convertible to ``int`` and
+            be >= 0.
+        '''
+        try:
+            delay = int(delay)
+        except:
+            self.logger.error(f"Delay value must be a valid integer number.")
+            self.sig_delay_changed.emit(self.settings['delay'])
+            return
+        if delay < 0:
+            self.logger.error(f"Delay value must be >= 0.")
+            self.sig_delay_changed.emit(self.settings['delay'])
+            return
+        self.logger.info(f"Changing delay to {delay}...")
+        try:
+            self.instrument.delay = delay
+            self.settings['delay'] = self.instrument.delay
+            self.sig_delay_changed.emit(self.settings['delay'])
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return
+
+    def get_divider(self):
+        '''
+        Read the current sub-sampling divider from the device.
+
+        Updates :attr:`settings` ``['divider']`` and emits
+        :attr:`sig_divider_changed`.
+
+        Returns
+        -------
+        int
+            Current divider value.
+        '''
+        self.settings['divider'] = self.instrument.divider
+        self.sig_divider_changed.emit(self.settings['divider'])
+        return self.settings['divider']
+
+    def set_divider(self, divider):
+        '''
+        Validate and write a new sub-sampling divider to the device.
+
+        On success, updates :attr:`settings` ``['divider']`` and emits
+        :attr:`sig_divider_changed`. On any validation or communication error,
+        logs the error and re-emits :attr:`sig_divider_changed` with the
+        previous value so the GUI reverts.
+
+        Parameters
+        ----------
+        divider : int or str
+            Desired divider. Must be convertible to ``int`` and be > 0.
+        '''
+        try:
+            divider = int(divider)
+        except:
+            self.logger.error(f"Divider value must be a valid integer number.")
+            self.sig_divider_changed.emit(self.settings['divider'])
+            return
+        if divider <= 0:
+            self.logger.error(f"Divider value must be > 0.")
+            self.sig_divider_changed.emit(self.settings['divider'])
+            return
+        self.logger.info(f"Changing divider to {divider}...")
+        try:
+            self.instrument.divider = divider
+            self.settings['divider'] = self.instrument.divider
+            self.sig_divider_changed.emit(self.settings['divider'])
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return
+
+    def get_polarity(self):
+        '''
+        Read the current output polarity from the device.
+
+        Updates :attr:`settings` ``['polarity']`` and emits
+        :attr:`sig_polarity_changed`.
+
+        Returns
+        -------
+        int
+            Current polarity: ``0`` (Negative) or ``1`` (Positive).
+        '''
+        self.settings['polarity'] = self.instrument.polarity
+        self.sig_polarity_changed.emit(self.settings['polarity'])
+        return self.settings['polarity']
+
+    def set_polarity(self, polarity):
+        '''
+        Validate and write a new output polarity to the device.
+
+        On success, updates :attr:`settings` ``['polarity']`` and emits
+        :attr:`sig_polarity_changed`. On any validation or communication error,
+        logs the error and re-emits :attr:`sig_polarity_changed` with the
+        previous value so the GUI reverts.
+
+        Parameters
+        ----------
+        polarity : int or str
+            Desired polarity. Must be convertible to ``int`` and be ``0``
+            (Negative) or ``1`` (Positive).
+        '''
+        try:
+            polarity = int(polarity)
+        except:
+            self.logger.error(f"Polarity value must be a valid integer number.")
+            self.sig_polarity_changed.emit(self.settings['polarity'])
+            return
+        if polarity not in [0, 1]:
+            self.logger.error(f"Polarity value must be 0 (Negative) or 1 (Positive).")
+            self.sig_polarity_changed.emit(self.settings['polarity'])
+            return
+        self.logger.info(f"Changing polarity to {polarity}...")
+        try:
+            self.instrument.polarity = polarity
+            self.settings['polarity'] = self.instrument.polarity
+            self.sig_polarity_changed.emit(self.settings['polarity'])
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return
+
+    def get_triggerduration(self):
+        '''
+        Read the current output pulse duration from the device.
+
+        Updates :attr:`settings` ``['triggerduration']`` and emits
+        :attr:`sig_triggerduration_changed`.
+
+        Returns
+        -------
+        int
+            Current trigger duration in nanoseconds.
+        '''
+        self.settings['triggerduration'] = self.instrument.triggerduration
+        self.sig_triggerduration_changed.emit(self.settings['triggerduration'])
+        return self.settings['triggerduration']
+
+    def set_triggerduration(self, triggerduration):
+        '''
+        Validate and write a new output pulse duration to the device.
+
+        On success, updates :attr:`settings` ``['triggerduration']`` and
+        emits :attr:`sig_triggerduration_changed`. On any validation or
+        communication error, logs the error and re-emits
+        :attr:`sig_triggerduration_changed` with the previous value so the
+        GUI reverts.
+
+        Parameters
+        ----------
+        triggerduration : int or str
+            Desired pulse duration in nanoseconds. Must be convertible to
+            ``int`` and be > 0.
+        '''
+        try:
+            triggerduration = int(triggerduration)
+        except:
+            self.logger.error(f"Trigger duration value must be a valid integer number.")
+            self.sig_triggerduration_changed.emit(self.settings['triggerduration'])
+            return
+        if triggerduration <= 0:
+            self.logger.error(f"Trigger duration must be > 0.")
+            self.sig_triggerduration_changed.emit(self.settings['triggerduration'])
+            return
+        self.logger.info(f"Changing Trigger duration to {triggerduration}...")
+        try:
+            self.instrument.triggerduration = triggerduration
+            self.settings['triggerduration'] = self.instrument.triggerduration
+            self.sig_triggerduration_changed.emit(self.settings['triggerduration'])
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return
+
+    def get_number_of_triggers(self):
+        '''
+        Read the current burst pulse count from the device.
+
+        Updates :attr:`settings` ``['number_of_triggers']`` and emits
+        :attr:`sig_number_of_triggers_changed`.
+
+        Returns
+        -------
+        int
+            Current number of output pulses per burst.
+        '''
+        self.settings['number_of_triggers'] = self.instrument.number_of_triggers
+        self.sig_number_of_triggers_changed.emit(self.settings['number_of_triggers'])
+        return self.settings['number_of_triggers']
+
+    def set_number_of_triggers(self, number_of_triggers):
+        '''
+        Validate and write a new burst pulse count to the device.
+
+        On success, updates :attr:`settings` ``['number_of_triggers']`` and
+        emits :attr:`sig_number_of_triggers_changed`. On any validation or
+        communication error, logs the error and re-emits
+        :attr:`sig_number_of_triggers_changed` with the previous value so the
+        GUI reverts.
+
+        Parameters
+        ----------
+        number_of_triggers : int or str
+            Desired number of output pulses per burst. Must be convertible to
+            ``int`` and be > 0.
+        '''
+        try:
+            number_of_triggers = int(number_of_triggers)
+        except:
+            self.logger.error(f"Number of triggers must be a valid integer number.")
+            self.sig_number_of_triggers_changed.emit(self.settings['number_of_triggers'])
+            return
+        if number_of_triggers <= 0:
+            self.logger.error(f"Number of triggers must be > 0.")
+            self.sig_number_of_triggers_changed.emit(self.settings['number_of_triggers'])
+            return
+        self.logger.info(f"Changing number of triggers to {number_of_triggers}...")
+        try:
+            self.instrument.number_of_triggers = number_of_triggers
+            self.settings['number_of_triggers'] = self.instrument.number_of_triggers
+            self.sig_number_of_triggers_changed.emit(self.settings['number_of_triggers'])
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return
+
+    def fire_trigger(self):
+        '''
+        Send a trigger burst command to the device.
+
+        Calls :meth:`~pyTriggerSync.driver.pyTriggerSync.sendtrigger` on the
+        driver. If the device does not acknowledge the command, logs a warning.
+        Only valid when the device is in "Trigger Controlled by User" mode
+        (mode 1); the driver will raise :exc:`RuntimeError` if called in mode 0.
+        '''
+        try:
+            self.logger.info(f"Fire!")
+            success = self.instrument.sendtrigger()
+            if not success:
+                self.logger.warning("Trigger command was not acknowledged by the device.")
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return
+
+    def get_mode(self):
+        '''
+        Read the current operating mode from the device.
+
+        Updates :attr:`settings` ``['mode']`` and emits
+        :attr:`sig_mode_changed`.
+
+        Returns
+        -------
+        int
+            Current mode: ``0`` (Continuous Trigger) or ``1`` (Trigger
+            Controlled by User).
+        '''
+        self.settings['mode'] = self.instrument.mode
+        self.sig_mode_changed.emit(self.settings['mode'])
+        return self.settings['mode']
+
+    def set_mode(self, mode: int):
+        '''
+        Validate and write a new operating mode to the device.
+
+        On success, updates :attr:`settings` ``['mode']`` and emits
+        :attr:`sig_mode_changed`. On validation failure, logs an error and
+        returns ``None`` without emitting (radio buttons in the GUI are
+        always in a valid state, so no revert signal is needed). On
+        communication error, logs the error and returns ``None``.
+
+        Parameters
+        ----------
+        mode : int
+            Desired mode. Must be ``0`` (Continuous Trigger) or ``1``
+            (Trigger Controlled by User).
+
+        Returns
+        -------
+        int or None
+            The new mode on success, ``None`` on failure.
+        '''
+        try:
+            if mode not in [0, 1]:
+                self.logger.error(f"Mode index must be 0 (Continuous) or 1 (Trigger Controlled by User).")
+                return None
+            self.logger.info(f"Setting mode to {self._mode_names[mode]}...")
+            self.instrument.mode = mode
+            self.settings['mode'] = self.instrument.mode
+            self.sig_mode_changed.emit(self.settings['mode'])
+            return mode
+        except Exception as e:
+            self.logger.error(f"Some error occurred when changing the device mode: {e}")
+            return None
+
+    def set_external_trigger(self, external_trigger: bool):
+        '''
+        Enable or disable forwarding of external triggers to :meth:`fire_trigger`.
+
+        Updates :attr:`settings` ``['external_trigger']`` and emits
+        :attr:`sig_external_trigger_changed`. This setting is only meaningful
+        when this interface is combined with other instrument interfaces that
+        can emit trigger signals.
+
+        Parameters
+        ----------
+        external_trigger : bool
+            If ``True``, :meth:`receive_trigger` will call :meth:`fire_trigger`
+            when a trigger is received from another interface. If ``False``,
+            external triggers are ignored.
+
+        Returns
+        -------
+        bool or None
+            The new setting on success, ``None`` on failure.
+        '''
+        self.logger.info(f"Setting external trigger to {external_trigger}...")
+        try:
+            external_trigger = bool(external_trigger)
+            self.settings['external_trigger'] = external_trigger
+            self.sig_external_trigger_changed.emit(self.settings['external_trigger'])
+            return external_trigger
+        except Exception as e:
+            self.logger.error(f"Some error occurred when changing the external trigger setting: {e}")
+            self.sig_external_trigger_changed.emit(self.settings['external_trigger'])
+            return None
+
+    def receive_trigger(self, **kwargs):
+        '''
+        Handle an incoming trigger from another instrument interface.
+
+        If :attr:`settings` ``['external_trigger']`` is ``True``, forwards the
+        trigger to :meth:`fire_trigger`. Otherwise, the trigger is silently
+        ignored. This method is called by the framework when a trigger signal
+        is received from a connected instrument.
+        '''
+        if self.settings['external_trigger'] == True:
+            self.fire_trigger()
+
+
+
+class gui(abstract_instrument_interface.abstract_gui):
+    """
+    View and controller for the pyTriggerSync interface.
+
+    Builds the Qt widget layout, connects GUI events to
+    :class:`interface` methods (event functions), and updates widgets in
+    response to signals emitted by the :class:`interface` (event slots).
+
+    Attributes
+    ----------
+    interface : interface
+        Reference to the model object this GUI is bound to.
+    widgets_enabled_when_connected : list of QWidget
+        Widgets that are enabled only while a device is connected.
+    widgets_enabled_when_disconnected : list of QWidget
+        Widgets that are enabled only while no device is connected.
+    widgets_enabled_only_when_mode0 : list of QWidget
+        Widgets that are enabled only in Continuous Trigger mode (mode 0).
+    widgets_enabled_only_when_mode1 : list of QWidget
+        Widgets that are enabled only in User-Controlled mode (mode 1).
+    """
+
+    def __init__(self, interface, parent):
+        """
+        Parameters
+        ----------
+        interface : interface
+            The model object to bind this GUI to.
+        parent : QWidget
+            Parent Qt widget.
+        """
+        super().__init__(interface, parent)
+        self._decimal_digits_gui = 5 #How many decimal digits will be used to display position and voltage
+        self.initialize()
+
+    def initialize(self):
+        '''
+        Build the widget layout, wire up events and signals, and set the
+        initial widget state.
+
+        Called once from :meth:`__init__`. Calls :meth:`create_widgets`,
+        :meth:`connect_widgets_events_to_functions`, the parent
+        :meth:`~abstract_instrument_interface.abstract_gui.initialize`, and
+        then connects all :class:`interface` signals to their slots.
+        '''
+        self.create_widgets()
+        self.connect_widgets_events_to_functions()
+
+        ### Call the initialize method of the super class.
+        super().initialize()
+
+        ### Connect signals from model to event slots of this GUI
+        self.interface.sig_list_devices_updated.connect(self.on_list_devices_updated)
+        self.interface.sig_connected.connect(self.on_connection_status_change)
+        self.interface.sig_mode_changed.connect(self.on_mode_change)
+        self.interface.sig_polarity_changed.connect(self.on_polarity_change)
+        self.interface.sig_delay_changed.connect(self.on_delay_change)
+        self.interface.sig_triggerduration_changed.connect(self.on_triggerduration_change)
+        self.interface.sig_divider_changed.connect(self.on_divider_change)
+        self.interface.sig_number_of_triggers_changed.connect(self.on_number_of_triggers_change)
+        self.interface.sig_close.connect(self.on_close)
+        self.interface.sig_external_trigger_changed.connect(self.on_external_trigger_change)
+
+        ### SET INITIAL STATE OF WIDGETS
+        self.on_divider_change(self.interface.settings['divider'])
+        self.on_number_of_triggers_change(self.interface.settings['number_of_triggers'])
+        self.on_delay_change(self.interface.settings['delay'])
+        self.on_triggerduration_change(self.interface.settings['triggerduration'])
+        self.on_mode_change(mode = self.interface.settings['mode'])
+        self.on_polarity_change(polarity = self.interface.settings['polarity'])
+        self.on_external_trigger_change(external_trigger = self.interface.settings['external_trigger'])
+        self.interface.send_list_devices()
+        self.on_connection_status_change(self.interface.SIG_DISCONNECTED) #When GUI is created, all widgets are set to the "Disconnected" state
+
+    def create_widgets(self):
+        '''
+        Instantiate and lay out all Qt widgets.
+
+        Populates ``self.container`` (a :class:`QVBoxLayout`) with two rows:
+
+        - Row 0: connection panel (combo box, refresh button, connect button)
+          produced by
+          :meth:`~abstract_instrument_interface.abstract_gui.create_panel_connection_listdevices`.
+        - Row 1: mode radio buttons, divider field, num-pulses field,
+          external-trigger checkbox.
+        - Row 2: polarity radio buttons, delay field, trigger-duration field,
+          Fire button.
+
+        Also populates the widget-group lists used by
+        :meth:`on_connection_status_change` and :meth:`on_mode_change` to
+        enable/disable widgets in bulk.
+        '''
+
+        #Use the custom connection/listdevices panel, defined in abstract_instrument_interface.abstract_gui
+        hbox0, widgets_dict = self.create_panel_connection_listdevices()
+        for key, val in widgets_dict.items():
+            setattr(self,key,val)
+
+        hbox1 = Qt.QHBoxLayout()
+
+        self.buttongroup_mode = Qt.QButtonGroup(self.parent)
+        self.radio_ContinuousTrigger = Qt.QRadioButton()
+        self.radio_ContinuousTrigger.setText(self.interface._mode_names[0])
+        self.radio_ContinuousTrigger.value = "0"
+        self.label_Divider = Qt.QLabel("Divider: ")
+        self.label_Divider .setToolTip('Divider (non-negative integer number)')
+        self.label_Divider.setAlignment(QtCore.Qt.AlignRight | QtCore.Qt.AlignCenter)
+        self.edit_Divider  = Qt.QLineEdit()
+        self.edit_Divider.setAlignment(QtCore.Qt.AlignRight)
+        self.edit_Divider.setMaximumWidth(50)
+        self.radio_UserControlled = Qt.QRadioButton()
+        self.radio_UserControlled.setText(self.interface._mode_names[1])
+        self.radio_UserControlled.value = "1"
+        self.buttongroup_mode.addButton(self.radio_ContinuousTrigger)
+        self.buttongroup_mode.addButton(self.radio_UserControlled)
+        self.label_NumPulses = Qt.QLabel("Num Pulses: ")
+        self.label_NumPulses.setToolTip('Number of output pulses per trigger burst (positive integer)')
+        self.label_NumPulses.setAlignment(QtCore.Qt.AlignRight | QtCore.Qt.AlignCenter)
+        self.edit_NumPulses = Qt.QLineEdit()
+        self.edit_NumPulses.setAlignment(QtCore.Qt.AlignRight)
+        self.edit_NumPulses.setMaximumWidth(50)
+        self.checkbox_ExternalTrigger = Qt.QCheckBox("External Trigger")
+        self.checkbox_ExternalTrigger.setToolTip('This setting is only important when this interface is combined with other instrument interfaces. If checked, the device will fire a trigger whenever it receives a trigger from some other instruments. If not checked, the device will ignore any trigger received at its input, and it will only fire a trigger when the "Fire" button is pressed.')
+
+        widgets_row1 = [self.radio_ContinuousTrigger,self.label_Divider, self.edit_Divider, self.radio_UserControlled, self.label_NumPulses, self.edit_NumPulses, self.checkbox_ExternalTrigger]
+        widgets_row1_stretches = [0]*len(widgets_row1)
+        for w,s in zip(widgets_row1,widgets_row1_stretches):
+            hbox1.addWidget(w,stretch=s)
+        hbox1.addStretch(1)
+
+        hbox2 = Qt.QHBoxLayout()
+
+        self.label_Polarity = Qt.QLabel("Trigger Polarity: ")
+        self.buttongroup_polarity = Qt.QButtonGroup(self.parent)
+        self.radio_PolarityPositive = Qt.QRadioButton()
+        self.radio_PolarityPositive.setText(self.interface._polarity_names[1])
+        self.radio_PolarityPositive.value = "1"
+        self.radio_PolarityNegative = Qt.QRadioButton()
+        self.radio_PolarityNegative.setText(self.interface._polarity_names[0])
+        self.radio_PolarityNegative.value = "0"
+        self.buttongroup_polarity.addButton(self.radio_PolarityPositive)
+        self.buttongroup_polarity.addButton(self.radio_PolarityNegative)
+
+        self.label_Delay = Qt.QLabel("Delay (ns): ")
+        self.label_Delay.setToolTip('Delay of generated trigger with respect to input trigger.')
+        self.label_Delay.setAlignment(QtCore.Qt.AlignRight | QtCore.Qt.AlignCenter)
+        self.edit_Delay  = Qt.QLineEdit()
+        self.edit_Delay.setAlignment(QtCore.Qt.AlignRight)
+        self.edit_Delay.setMaximumWidth(120)
+
+        self.label_TriggerDuration = Qt.QLabel("Trigger Duration (ns): ")
+        self.label_TriggerDuration.setToolTip('Duration of generated trigger.')
+        self.label_TriggerDuration.setAlignment(QtCore.Qt.AlignRight | QtCore.Qt.AlignCenter)
+        self.edit_TriggerDuration = Qt.QLineEdit()
+        self.edit_TriggerDuration.setAlignment(QtCore.Qt.AlignRight)
+        self.edit_TriggerDuration.setMaximumWidth(120)
+
+
+
+        self.button_FireTrigger = Qt.QPushButton("Fire")
+
+        widgets_row2 = [self.label_Polarity,self.radio_PolarityPositive,self.radio_PolarityNegative,self.label_Delay,self.edit_Delay,self.label_TriggerDuration,self.edit_TriggerDuration,self.button_FireTrigger]
+        widgets_row2_stretches = [0]*len(widgets_row2)
+        for w,s in zip(widgets_row2,widgets_row2_stretches):
+            hbox2.addWidget(w,stretch=s)
+        hbox2.addStretch(1)
+
+
+        self.container = Qt.QVBoxLayout()
+        for box in [hbox0,hbox1,hbox2]:
+             self.container.addLayout(box)
+        self.container.addStretch(1)
+
+
+        # Widgets for which we want to constraint the width by using sizeHint()
+        widget_list = []
+        for w in widget_list:
+            w.setMaximumSize(w.sizeHint())
+
+        #These widgets are enabled ONLY when interface is connected to a device
+        self.widgets_enabled_when_connected = widgets_row1 + widgets_row2
+
+        #These widgets are enabled ONLY when interface is NOT connected to a device
+        self.widgets_enabled_when_disconnected = [self.combo_Devices,  self.button_RefreshDeviceList]
+
+        self.widgets_enabled_only_when_mode0 = [self.edit_Divider, self.label_Divider]
+        self.widgets_enabled_only_when_mode1 = [self.button_FireTrigger, self.checkbox_ExternalTrigger, self.label_NumPulses, self.edit_NumPulses]
+
+
+    def connect_widgets_events_to_functions(self):
+        '''
+        Connect Qt widget signals to their event-function handlers.
+
+        Called once from :meth:`initialize`. Wires button clicks, line-edit
+        ``returnPressed``, radio-button clicks, and checkbox clicks to the
+        corresponding ``click_*`` / ``press_enter_*`` methods of this class.
+        '''
+        self.button_RefreshDeviceList.clicked.connect(self.click_button_refresh_list_devices)
+        self.button_ConnectDevice.clicked.connect(self.click_button_connect_disconnect)
+
+        self.edit_Divider.returnPressed.connect(self.press_enter_edit_divider)
+        self.edit_NumPulses.returnPressed.connect(self.press_enter_edit_numpulses)
+
+        self.button_FireTrigger.clicked.connect(self.click_button_Fire)
+        self.edit_Delay.returnPressed.connect(self.press_enter_edit_delay)
+        self.edit_TriggerDuration.returnPressed.connect(self.press_enter_edit_triggerduration)
+
+        self.radio_ContinuousTrigger.clicked.connect(self.click_radio_mode)
+        self.radio_UserControlled.clicked.connect(self.click_radio_mode)
+        self.radio_PolarityNegative.clicked.connect(self.click_radio_polarity)
+        self.radio_PolarityPositive.clicked.connect(self.click_radio_polarity)
+        self.checkbox_ExternalTrigger.clicked.connect(self.click_checkbox_external_trigger)
+
+###########################################################################################################
+### Event Slots. They are normally triggered by signals from the model, and change the GUI accordingly  ###
+###########################################################################################################
+
+    def on_connection_status_change(self, status):
+        '''
+        Slot for :attr:`interface.sig_connected`. Enables/disables widget
+        groups and updates the Connect/Disconnect button label to reflect the
+        new connection state.
+
+        Parameters
+        ----------
+        status : int
+            One of ``SIG_DISCONNECTED``, ``SIG_DISCONNECTING``,
+            ``SIG_CONNECTING``, or ``SIG_CONNECTED``.
+        '''
+        if status == self.interface.SIG_DISCONNECTED:
+            self.disable_widget(self.widgets_enabled_when_connected)
+            self.enable_widget(self.widgets_enabled_when_disconnected)
+            self.button_ConnectDevice.setText("Connect")
+        if status == self.interface.SIG_DISCONNECTING:
+            self.disable_widget(self.widgets_enabled_when_connected)
+            self.enable_widget(self.widgets_enabled_when_disconnected)
+            self.button_ConnectDevice.setText("Disconnecting...")
+        if status == self.interface.SIG_CONNECTING:
+            self.disable_widget(self.widgets_enabled_when_connected)
+            self.enable_widget(self.widgets_enabled_when_disconnected)
+            self.button_ConnectDevice.setText("Connecting...")
+        if status == self.interface.SIG_CONNECTED:
+            self.enable_widget(self.widgets_enabled_when_connected)
+            self.disable_widget(self.widgets_enabled_when_disconnected)
+            self.button_ConnectDevice.setText("Disconnect")
+
+    def on_list_devices_updated(self, list_devices):
+        '''
+        Slot for :attr:`interface.sig_list_devices_updated`. Repopulates the
+        device combo box with the new list of device descriptors.
+
+        Parameters
+        ----------
+        list_devices : list of str
+            Device descriptor strings to display in the combo box.
+        '''
+        self.combo_Devices.clear()  #First we empty the combobox
+        self.combo_Devices.addItems(list_devices)
+
+    def on_mode_change(self, mode):
+        '''
+        Slot for :attr:`interface.sig_mode_changed`. Checks the appropriate
+        mode radio button and enables/disables mode-specific widgets.
+
+        Parameters
+        ----------
+        mode : int
+            New mode: ``0`` (Continuous Trigger) or ``1`` (User Controlled).
+
+        Returns
+        -------
+        bool
+            ``True`` if ``mode`` was a recognised value, ``False`` otherwise.
+        '''
+        if mode == 0:
+            self.radio_ContinuousTrigger.setChecked(True)
+            self.enable_widget(self.widgets_enabled_only_when_mode0)
+            self.disable_widget(self.widgets_enabled_only_when_mode1)
+            return True
+        if mode == 1:
+            self.radio_UserControlled.setChecked(True)
+            self.enable_widget(self.widgets_enabled_only_when_mode1)
+            self.disable_widget(self.widgets_enabled_only_when_mode0)
+            return True
+        return False
+
+    def on_polarity_change(self, polarity):
+        '''
+        Slot for :attr:`interface.sig_polarity_changed`. Checks the
+        appropriate polarity radio button.
+
+        Parameters
+        ----------
+        polarity : int
+            New polarity: ``0`` (Negative) or ``1`` (Positive).
+
+        Returns
+        -------
+        bool
+            ``True`` if ``polarity`` was a recognised value, ``False`` otherwise.
+        '''
+        if polarity == 0:
+            self.radio_PolarityNegative.setChecked(True)
+            return True
+        if polarity == 1:
+            self.radio_PolarityPositive.setChecked(True)
+            return True
+        return False
+
+    def on_external_trigger_change(self, external_trigger):
+        '''
+        Slot for :attr:`interface.sig_external_trigger_changed`. Updates the
+        External Trigger checkbox state.
+
+        Parameters
+        ----------
+        external_trigger : bool
+            New external-trigger enable state.
+        '''
+        self.checkbox_ExternalTrigger.setChecked(external_trigger)
+
+    def on_delay_change(self, value):
+        '''
+        Slot for :attr:`interface.sig_delay_changed`. Updates the Delay text
+        field.
+
+        Parameters
+        ----------
+        value : int
+            New delay in nanoseconds.
+        '''
+        self.edit_Delay.setText(f"{value}")
+
+    def on_divider_change(self, value):
+        '''
+        Slot for :attr:`interface.sig_divider_changed`. Updates the Divider
+        text field.
+
+        Parameters
+        ----------
+        value : int
+            New divider value.
+        '''
+        self.edit_Divider.setText(f"{value}")
+
+    def on_number_of_triggers_change(self, value):
+        '''
+        Slot for :attr:`interface.sig_number_of_triggers_changed`. Updates the
+        Num Pulses text field.
+
+        Parameters
+        ----------
+        value : int
+            New number of triggers per burst.
+        '''
+        self.edit_NumPulses.setText(f"{value}")
+
+    def on_triggerduration_change(self, value):
+        '''
+        Slot for :attr:`interface.sig_triggerduration_changed`. Updates the
+        Trigger Duration text field.
+
+        Parameters
+        ----------
+        value : int
+            New trigger duration in nanoseconds.
+        '''
+        self.edit_TriggerDuration.setText(f"{value}")
+
+    def on_close(self):
+        '''
+        Slot for :attr:`interface.sig_close`. Called when the interface is
+        closing. Reserved for any GUI teardown that may be needed in future.
+        '''
+        pass
+
+#######################
+### END Event Slots ###
+#######################
+
+###################################################################################################################################################
+### GUI Events Functions. They are triggered by direct interaction with the GUI, and they call methods of the interface (i.e. the model) object.###
+###################################################################################################################################################
+
+    def click_button_refresh_list_devices(self):
+        '''
+        Event function for the Refresh button. Calls
+        :meth:`interface.refresh_list_devices`.
+        '''
+        self.interface.refresh_list_devices()
+
+    def click_button_connect_disconnect(self):
+        '''
+        Event function for the Connect/Disconnect button. Calls
+        :meth:`interface.connect_device` or
+        :meth:`interface.disconnect_device` depending on the current
+        connection state.
+        '''
+        if(self.interface.instrument.connected == False): # We attempt connection
+            device_full_name = self.combo_Devices.currentText() # Get the device name from the combobox
+            self.interface.connect_device(device_full_name)
+        elif(self.interface.instrument.connected == True): # We attempt disconnection
+            self.interface.disconnect_device()
+
+    def click_button_Fire(self):
+        '''
+        Event function for the Fire button. Calls :meth:`interface.fire_trigger`.
+        '''
+        self.interface.fire_trigger()
+
+    def press_enter_edit_divider(self):
+        '''
+        Event function for the Divider field (Return key). Passes the current
+        field text to :meth:`interface.set_divider`.
+        '''
+        return self.interface.set_divider(self.edit_Divider.text())
+
+    def press_enter_edit_numpulses(self):
+        '''
+        Event function for the Num Pulses field (Return key). Passes the
+        current field text to :meth:`interface.set_number_of_triggers`.
+        '''
+        return self.interface.set_number_of_triggers(self.edit_NumPulses.text())
+
+    def press_enter_edit_delay(self):
+        '''
+        Event function for the Delay field (Return key). Passes the current
+        field text to :meth:`interface.set_delay`.
+        '''
+        return self.interface.set_delay(self.edit_Delay.text())
+
+    def press_enter_edit_triggerduration(self):
+        '''
+        Event function for the Trigger Duration field (Return key). Passes
+        the current field text to :meth:`interface.set_triggerduration`.
+        '''
+        return self.interface.set_triggerduration(self.edit_TriggerDuration.text())
+
+    def click_radio_mode(self, value):
+        '''
+        Event function for the mode radio buttons. Reads which button is
+        currently checked and calls :meth:`interface.set_mode` with the
+        corresponding mode index.
+
+        Parameters
+        ----------
+        value : bool
+            Checked state passed by Qt (unused; the checked button is
+            determined by polling the radio buttons directly).
+
+        Returns
+        -------
+        bool
+            ``True`` if a valid mode was selected, ``False`` otherwise.
+        '''
+        if self.radio_ContinuousTrigger.isChecked():
+            self.interface.set_mode(0)
+            return True
+        if self.radio_UserControlled.isChecked():
+            self.interface.set_mode(1)
+            return True
+        return False
+
+    def click_radio_polarity(self, value):
+        '''
+        Event function for the polarity radio buttons. Reads which button is
+        currently checked and calls :meth:`interface.set_polarity` with the
+        corresponding polarity index.
+
+        Parameters
+        ----------
+        value : bool
+            Checked state passed by Qt (unused; the checked button is
+            determined by polling the radio buttons directly).
+
+        Returns
+        -------
+        bool
+            ``True`` if a valid polarity was selected, ``False`` otherwise.
+        '''
+        if self.radio_PolarityNegative.isChecked():
+            self.interface.set_polarity(0)
+            return True
+        if self.radio_PolarityPositive.isChecked():
+            self.interface.set_polarity(1)
+            return True
+        return False
+
+    def click_checkbox_external_trigger(self, value):
+        '''
+        Event function for the External Trigger checkbox. Passes the new
+        checked state to :meth:`interface.set_external_trigger`.
+
+        Parameters
+        ----------
+        value : bool
+            New checked state of the checkbox (unused; the state is read
+            directly from the widget to avoid Qt signal type ambiguity).
+
+        Returns
+        -------
+        bool
+            Always ``True``.
+        '''
+        self.interface.set_external_trigger(self.checkbox_ExternalTrigger.isChecked())
+        return True
+
+#################################
+### END GUI Events Functions ####
+#################################
+
+class MainWindow(Qt.QWidget):
+    '''
+    Top-level application window.
+
+    A thin :class:`QWidget` subclass that hosts the :class:`gui` layout.
+    Window title is set to the package name. Close events are currently
+    passed through without action (teardown is handled by
+    ``app.aboutToQuit`` → :meth:`interface.close`).
+    '''
+    def __init__(self):
+        super().__init__()
+        self.setWindowTitle(__package__)
+
+    def closeEvent(self, event):
+        '''
+        Handle the window close event. Currently a no-op; interface teardown
+        is handled by ``app.aboutToQuit``.
+        '''
+        pass
+
+def main():
+    '''
+    Entry point for the pyTriggerSync application.
+
+    Parses command-line arguments, creates the Qt application, instantiates
+    the :class:`interface` and :class:`gui`, and starts the event loop.
+
+    Command-line arguments
+    ----------------------
+    -s, --decrease_verbose
+        Reduce logging verbosity.
+    -virtual
+        Use the virtual (simulated) driver instead of a real serial device.
+    '''
+    parser = argparse.ArgumentParser(description = "",epilog = "")
+    parser.add_argument("-s", "--decrease_verbose", help="Decrease verbosity.", action="store_true")
+    parser.add_argument('-virtual', help=f"Initialize the virtual driver", action="store_true")
+    args = parser.parse_args()
+    virtual = args.virtual
+
+    app = Qt.QApplication(sys.argv)
+    window = MainWindow()
+    Interface = interface(app=app,virtual=virtual)
+    Interface.verbose = not(args.decrease_verbose)
+    app.aboutToQuit.connect(Interface.close)
+    view = gui(interface = Interface, parent=window) #In this case window is the parent of the gui
+
+    window.show()
+    app.exec()# Start the event loop.
+
+if __name__ == '__main__':
+    main()