pyTriggerSync 0.3__py3-none-any.whl

pyTriggerSync/__init__.py

@@ -0,0 +1,6 @@
+#If this package was installed only to use the low-level driver, the PyQt library is not necessarily installed. In this case, importing stuff from main.py would generate an error
+import importlib.util
+package_name = 'PyQt5'
+spec = importlib.util.find_spec(package_name)
+if spec:
+    from .main import interface, gui

pyTriggerSync/config.json

@@ -0,0 +1,9 @@
+{
+    "delay": 1200,
+    "divider": 3,
+    "external_trigger": true,
+    "mode": 1,
+    "number_of_triggers": 5,
+    "polarity": 1,
+    "triggerduration": 1000
+}

pyTriggerSync/driver.py

@@ -0,0 +1,535 @@
+''' Note: most of docstrings in this file have been generated automatically by Claude. AI can make mistakes'''
+
+import serial
+import serial.tools.list_ports
+
+class pyTriggerSync():
+    """
+    Low-level driver to communicate with a Teensy microcontroller running the
+    ``Send_Trigger_Synced_With_External_Trigger_OnlyRemoteControl`` firmware over a
+    serial (USB) connection.
+
+    The Teensy generates an output trigger pulse synchronized to an external trigger
+    signal received on its input pin, either continuously (one output pulse per input
+    edge, optionally sub-sampled via :attr:`divider`) or in user-controlled bursts of a
+    fixed number of pulses (via :meth:`sendtrigger`). See the project's
+    ``SERIAL_PROTOCOL.md`` for the full list of serial commands understood by the
+    firmware.
+
+    Attributes
+    ----------
+    connected : bool
+        ``True`` if a device is currently connected, ``False`` otherwise.
+    port : str
+        Serial port used for the connection (e.g. ``'COM4'``). Set at construction time
+        and updated by :meth:`connect_device` to reflect the port actually connected to.
+    baudrate : int
+        Baud rate used for the serial connection. Must match the firmware (115200).
+    timeout : float
+        Read timeout (in seconds) used for the serial connection. Note that this also
+        bounds how long :meth:`sendtrigger` will wait for the immediate acknowledgement
+        of a ``trg`` command - not for the burst to actually complete (see
+        :meth:`sendtrigger`).
+    identifier : str
+        Substring expected at the start of the device's identity string (the answer to
+        ``idn?``). Used by :meth:`list_devices` to recognize a compatible device.
+    device : serial.Serial
+        The underlying PySerial connection. Only valid while :attr:`connected` is
+        ``True``; created by :meth:`connect_device`.
+    """
+
+    def __init__(self,port='COM4', baudrate=115200, timeout=0.1):
+        """
+        Parameters
+        ----------
+        port : str, optional
+            Serial port to connect to by default (used by :meth:`connect_device` when
+            no port is explicitly specified). Default is ``'COM4'``.
+        baudrate : int, optional
+            Baud rate to use for the serial connection. Must match the firmware
+            (115200). Default is ``115200``.
+        timeout : float, optional
+            Read timeout (in seconds) for the serial connection. Default is ``0.1``.
+        """
+        self.connected = False
+        self.port = port
+        self.baudrate = baudrate
+        self.timeout = timeout
+        self.identifier = 'Send_Trigger_Synced_With_External_Trigger'
+
+    def list_devices(self):
+        '''
+        Scan all serial ports currently visible to the system and check whether any of
+        them is running compatible firmware, by briefly connecting to each one in turn
+        and comparing its identity string (the answer to ``idn?``) against
+        :attr:`identifier`.
+
+        Each candidate port is connected to and disconnected from in turn; only ports
+        that open successfully and respond with a matching identity are kept.
+
+        Returns
+        -------
+        list_valid_devices : list of str
+            A list of all found valid devices. Each element is a human-readable string
+            in the format ``"<port>: <description> [<hwid>]"``.
+
+        Raises
+        ------
+        RuntimeError
+            If a device is already connected (scanning would interfere with the active
+            connection). Disconnect first.
+        '''
+        if self.connected:
+            raise RuntimeError("Cannot scan for devices while a device is connected. Disconnect first.")
+        ports = serial.tools.list_ports.comports()
+        list_valid_devices =[]
+        for port, desc, hwid in sorted(ports):
+            (Msg,ID) = self.connect_device(port)
+            if ID == 1:
+                try:
+                    device_identity = self.identity
+                    if device_identity and device_identity.startswith(self.identifier):
+                        list_valid_devices.append(f"{port}: {desc} [{hwid}]")
+                except Exception:
+                    pass
+                finally:
+                    #Always disconnect, even if reading the identity raised - otherwise the
+                    #port is left open and the handle is discarded on the next loop iteration.
+                    self.disconnect_device()
+        self.list_valid_devices = list_valid_devices
+        return self.list_valid_devices
+
+    def connect_device(self,port = None, baudrate = None, timeout = None):
+        '''
+        Attempt to connect to a device on the specified serial port.
+
+        Upon a successful connection, all relevant device parameters (mode, polarity,
+        divider, delay, trigger duration, number of triggers) are read once and cached
+        in the corresponding private attributes, so that code relying on the cached
+        values (e.g. :meth:`sendtrigger`, which reads the cached mode directly to avoid
+        an extra round-trip delay right before firing a trigger) is correct immediately
+        after connecting, without requiring an explicit read first.
+
+        Parameters
+        ----------
+        port : str, optional
+            Serial port to connect to (e.g. ``'COM4'``). If not specified, :attr:`port`
+            is used.
+        baudrate : int, optional
+            Baud rate for the connection. If not specified, :attr:`baudrate` is used.
+        timeout : float, optional
+            Read timeout (in seconds) for the connection. If not specified,
+            :attr:`timeout` is used.
+
+        Returns
+        -------
+        (Msg, ID) : (str, int)
+            ``Msg`` is a confirmation message, or the exception raised while
+            connecting. ``ID`` is 1 if the connection (including reading back all
+            device parameters) was successful, 0 otherwise.
+        '''
+        if port == None:
+            port = self.port
+        if baudrate == None:
+            baudrate = self.baudrate
+        if timeout == None:
+            timeout = self.timeout
+        try:
+            self.device = serial.Serial(port = port, baudrate = baudrate, timeout = timeout)
+            self.connected = True
+            self.port = port       #remember the port actually used, not just the configured default
+            #Populate all cached attributes by querying the device now, so that code relying
+            #on the cached values (e.g. sendtrigger()'s use of self._mode, kept deliberately
+            #cached to avoid an extra round-trip delay right before firing a trigger) is
+            #correct immediately after connecting, without requiring an explicit read first.
+            _ = self.mode
+            _ = self.polarity
+            _ = self.divider
+            _ = self.delay
+            _ = self.triggerduration
+            _ = self.number_of_triggers
+            ID = 1
+            Msg = 'Device connected on ' + self.port
+        except Exception as e:
+            ID = 0
+            Msg = e
+            #If the port opened but querying the device failed (e.g. it didn't respond as
+            #expected), don't leave a half-open connection behind.
+            try:
+                self.device.close()
+            except Exception:
+                pass
+            self.connected = False
+        return (Msg,ID)
+
+    def disconnect_device(self):
+        '''
+        Disconnect the currently connected device, closing the underlying serial
+        connection.
+
+        Returns
+        -------
+        (Msg, ID) : (str, int)
+            ``Msg`` is a confirmation message, or the exception raised while
+            disconnecting. ``ID`` is 1 if disconnection was successful, 0 otherwise.
+        '''
+        try:
+            self.device.close()
+            ID = 1
+            Msg = 'Device ' + self.port + ' succesfully disconnected.'
+        except Exception as e:
+            ID = 0
+            Msg = e
+        if(ID==1):
+            self.connected = False
+        return (Msg,ID)
+
+    def check_valid_connection(self):
+        '''
+        Verify that a device is currently connected.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected.
+        '''
+        if not(self.connected):
+            raise RuntimeError("No device is currently connected.")
+
+    def query(self, q):
+        '''
+        Send a command to the device and return its reply.
+
+        Clears any stale unread data from the input buffer first, then writes ``q``
+        (terminated with a newline) and reads back exactly one reply line.
+
+        Parameters
+        ----------
+        q : str
+            Command to send (e.g. ``"mode?"``). A trailing newline is added
+            automatically if not already present.
+
+        Returns
+        -------
+        str
+            The device's reply, decoded and stripped of leading/trailing whitespace.
+            Empty if no reply was received within the configured :attr:`timeout`.
+        '''
+        self.device.reset_input_buffer() #This makes sure that there isn't any previous unread data in the serial buffer, which would spoil the data read with the readline() call.
+        self.device.write(bytes(q.strip() + '\n', 'utf-8'))
+        data = self.device.readline()
+        return data.decode().strip()
+
+    @property
+    def identity(self):
+        '''
+        str: The device's identity string (the answer to ``idn?``).
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected.
+        '''
+        self.check_valid_connection()
+        identity_string = self.query("IDN?\n")
+        return identity_string
+
+    @property
+    def mode(self):
+        '''
+        int: The device's current operating mode: ``0`` for "Continuous
+        Trigger" (every qualifying input edge automatically fires an output pulse) or
+        ``1`` for "Trigger Controlled by User" (output pulses only fire in response to
+        :meth:`sendtrigger`).
+
+        Reading this property queries the device (``mode?``) and caches the result.
+
+        Setting this property writes the new mode to the device (``mode <value>``)
+        and reads it back to confirm the change took effect.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected; or (setter only) if the device did
+            not acknowledge the command, or if the mode read back does not match the
+            requested value.
+        ValueError
+            (setter only) If the assigned value is not ``0`` or ``1``.
+        '''
+        self.check_valid_connection()
+        self._mode = int(self.query("mode?\n"))
+        return self._mode
+
+    @mode.setter
+    def mode(self, new_mode):
+        self.check_valid_connection()
+        if new_mode in [0,1]:
+            answer = self.query("mode " + str(new_mode) + "\n")
+            if answer != '0':
+                raise RuntimeError(f"Device was not able to set the mode correctly. Code returned: " + answer)
+            self._mode = int(self.query("mode?\n"))
+            if self._mode == new_mode:
+                return self._mode
+            else:
+                raise RuntimeError(f"Device acknowledged the command, but the mode read back ({self._mode}) does not match the requested value ({new_mode}).")
+        else:
+            raise ValueError(f"Input parameter must be equal to either 0 or 1")
+        return None
+
+    @property
+    def polarity(self):
+        '''
+        int: The device's current output trigger polarity: ``0`` for
+        "Negative" (output idles high, pulses low) or ``1`` for "Positive" (output
+        idles low, pulses high).
+
+        Reading this property queries the device (``polarity?``) and caches the
+        result.
+
+        Setting this property writes the new polarity to the device
+        (``polarity <value>``) and reads it back to confirm the change took effect.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected; or (setter only) if the device did
+            not acknowledge the command, or if the polarity read back does not match
+            the requested value.
+        ValueError
+            (setter only) If the assigned value is not ``0`` or ``1``.
+        '''
+        self.check_valid_connection()
+        self._polarity = int(self.query("polarity?\n"))
+        return self._polarity
+
+    @polarity.setter
+    def polarity(self, new_polarity):
+        self.check_valid_connection()
+        if new_polarity in [0,1]:
+            answer = self.query("polarity " + str(new_polarity) + "\n")
+            if answer != '0':
+                raise RuntimeError(f"Device was not able to set the polarity correctly. Code returned: " + answer)
+            self._polarity = int(self.query("polarity?\n"))
+            if self._polarity == new_polarity:
+                return self._polarity
+            else:
+                raise RuntimeError(f"Device acknowledged the command, but the polarity read back ({self._polarity}) does not match the requested value ({new_polarity}).")
+        else:
+            raise ValueError(f"Input parameter must be equal to either 0 or 1")
+        return None
+
+    @property
+    def divider(self):
+        '''
+        int: The device's current sub-sampling divider. In Continuous Trigger
+        mode, one output pulse is emitted for every :attr:`divider` input edges (has
+        no effect during a :meth:`sendtrigger`-initiated burst).
+
+        Reading this property queries the device (``divider?``) and caches the
+        result.
+
+        Setting this property writes the new divider to the device
+        (``divider <value>``) and reads it back to confirm the change took effect.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected; or (setter only) if the device did
+            not acknowledge the command, or if the divider read back does not match
+            the requested value.
+        ValueError
+            (setter only) If the assigned value cannot be converted to a positive
+            ``int``.
+        '''
+        self.check_valid_connection()
+        self._divider = int(self.query("divider?\n"))
+        return self._divider
+
+    @divider.setter
+    def divider(self, new_divider):
+        self.check_valid_connection()
+        try:
+            new_divider = int(new_divider)
+        except:
+            raise ValueError(f"Input parameter must be a valid integer")
+        if new_divider <= 0 :
+            raise ValueError(f"Input parameter must be positive")
+        answer = self.query("divider " + str(new_divider) + "\n")
+        if answer != '0':
+            raise RuntimeError(f"Device was not able to set the divider correctly. Code returned: " + answer)
+        self._divider = int(self.query("divider?\n"))
+        if self._divider == new_divider:
+            return self._divider
+        else:
+            raise RuntimeError(f"Device was not able to set the divider correctly.")
+        return None
+
+    @property
+    def delay(self):
+        '''
+        int: The device's current delay (in nanoseconds) between an input
+        trigger edge and the generated output pulse.
+
+        Reading this property queries the device (``delay?``) and caches the result.
+
+        Setting this property writes the new delay to the device (``delay <value>``)
+        and reads it back to confirm the change took effect.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected; or (setter only) if the device did
+            not acknowledge the command, or if the delay read back does not match the
+            requested value.
+        ValueError
+            (setter only) If the assigned value cannot be converted to a non-negative
+            ``int``.
+        '''
+        self.check_valid_connection()
+        self._delay = int(self.query("delay?\n"))
+        return self._delay
+
+    @delay.setter
+    def delay(self, new_delay):
+        self.check_valid_connection()
+        try:
+            new_delay = int(new_delay)
+        except:
+            raise ValueError(f"Input parameter must be a valid integer")
+        if new_delay < 0 :
+            raise ValueError(f"Input parameter must be positive or zero")
+        answer = self.query("delay " + str(new_delay) + "\n")
+        if answer != '0':
+            raise RuntimeError(f"Device was not able to set the delay correctly. Code returned: " + answer)
+        self._delay = int(self.query("delay?\n"))
+        if self._delay == new_delay:
+            return self._delay
+        else:
+            raise RuntimeError(f"Device was not able to set the delay correctly.")
+        return None
+
+    @property
+    def triggerduration(self):
+        '''
+        int: The device's current output pulse duration, in nanoseconds.
+
+        Reading this property queries the device (``triggerduration?``) and caches
+        the result.
+
+        Setting this property writes the new duration to the device
+        (``triggerduration <value>``) and reads it back to confirm the change took
+        effect.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected; or (setter only) if the device did
+            not acknowledge the command, or if the duration read back does not match
+            the requested value.
+        ValueError
+            (setter only) If the assigned value cannot be converted to a positive
+            ``int``.
+        '''
+        self.check_valid_connection()
+        self._triggerduration = int(self.query("triggerduration?\n"))
+        return self._triggerduration
+
+    @triggerduration.setter
+    def triggerduration(self, new_triggerduration):
+        self.check_valid_connection()
+        try:
+            new_triggerduration = int(new_triggerduration)
+        except:
+            raise ValueError(f"Input parameter must be a valid integer")
+        if new_triggerduration <= 0 :
+            raise ValueError(f"Input parameter must be positive")
+        answer = self.query("triggerduration " + str(new_triggerduration) + "\n")
+        if answer != '0':
+            raise RuntimeError(f"Device was not able to set the trigger duration correctly. Code returned: " + answer)
+        self._triggerduration = int(self.query("triggerduration?\n"))
+        if self._triggerduration == new_triggerduration:
+            return self._triggerduration
+        else:
+            raise RuntimeError(f"Device was not able to set the trigger duration correctly.")
+        return None
+
+    @property
+    def number_of_triggers(self):
+        '''
+        int: The number of output pulses a single :meth:`sendtrigger` call
+        will produce (only meaningful in "Trigger Controlled by User" mode).
+
+        Reading this property queries the device (``numpulses?``) and caches the
+        result.
+
+        Setting this property writes the new pulse count to the device
+        (``numpulses <value>``) and reads it back to confirm the change took effect.
+
+        Raises
+        ------
+        RuntimeError
+            If no device is currently connected; or (setter only) if the device did
+            not acknowledge the command, or if the value read back does not match the
+            requested value.
+        ValueError
+            (setter only) If the assigned value cannot be converted to a positive
+            ``int``.
+        '''
+        self.check_valid_connection()
+        self._number_of_triggers = int(self.query("numpulses?\n"))
+        return self._number_of_triggers
+
+    @number_of_triggers.setter
+    def number_of_triggers(self, new_number_of_triggers):
+        self.check_valid_connection()
+        try:
+            new_number_of_triggers = int(new_number_of_triggers)
+        except:
+            raise ValueError(f"Input parameter must be a valid integer")
+        if new_number_of_triggers <= 0:
+            raise ValueError(f"Input parameter must be positive")
+        answer = self.query("numpulses " + str(new_number_of_triggers) + "\n")
+        if answer != '0':
+            raise RuntimeError(f"Device was not able to set the number of triggers correctly. Code returned: " + answer)
+        self._number_of_triggers = int(self.query("numpulses?\n"))
+        if self._number_of_triggers == new_number_of_triggers:
+            return self._number_of_triggers
+        else:
+            raise RuntimeError(f"Device was not able to set the number of triggers correctly.")
+        return None
+
+    def sendtrigger(self):
+        '''
+        Start a burst of output trigger pulses. Only valid in "Trigger Controlled by
+        User" mode (:attr:`mode` == 1).
+
+        Sends the ``trg`` command and waits for the device's immediate
+        acknowledgement. The acknowledgement only confirms that the device accepted
+        the command and armed the burst - it does NOT mean the burst has completed.
+        Completion depends on real trigger edges arriving on the device's input pin
+        (one edge per pulse of :attr:`number_of_triggers`) and is reported later,
+        asynchronously, directly by the device - it is not read by this method.
+
+        Returns
+        -------
+        bool
+            ``True`` if the device acknowledged the command, ``False`` otherwise.
+
+        Raises
+        ------
+        RuntimeError
+            If the device is currently in "Continuous Trigger" mode (:attr:`mode` ==
+            0), in which case sending a single trigger is not applicable.
+        '''
+        #NOTE: uses the cached self._mode (not the 'mode' property) deliberately, to avoid
+        #the extra round-trip delay of querying the device right before firing a trigger.
+        #self._mode is populated as soon as the device connects (see connect_device()),
+        #so it is guaranteed to exist and to be correct as long as nothing outside this
+        #driver changes the device's mode without going through this driver's mode setter.
+        if self._mode == 0:
+            raise RuntimeError(f"Device is in modality 'Continuous Trigger', it is not possible to send a single trigger. Change the mode to 'Trigger Controlled by User' first.")
+        data = self.query("trg 1\n")
+        if data == '0':
+            return True
+        else:
+            return False