digital-trigger 0.1.2__py3-none-any.whl

digital_trigger/__init__.py

@@ -0,0 +1,3 @@
+from .trigger import Trigger
+__all__ = ["Trigger"]
+__version__ = "0.1.0"

digital_trigger/trigger.py

@@ -0,0 +1,129 @@
+import serial
+
+class Trigger:
+    def __init__(self, port='COM3', baudrate=115200, timeout=0, names=None, simulate=False):
+        self.bitmask = 0
+        self.names = names
+        self.simulate = simulate
+        if not simulate:
+            self.port = serial.Serial(port, baudrate, timeout=timeout)
+            self.reset()
+            self.write()
+
+    # -- line number handling ------------------------------------------
+
+    def name2line(self, name):
+        if self.names is None:
+            raise ValueError("No line names were set. Pass names=[...] to Trigger(), or use line numbers.")
+        return self.names.index(name) + 1
+
+    def get_line_numbers(self, lines):
+        # Wrap a single item so everything below can assume an iterable.
+        if isinstance(lines, (str, int)):
+            lines = [lines]
+
+        numbers = []
+        for line in lines:
+            if isinstance(line, str):
+                line = self.name2line(line)
+            else:
+                line = int(line)
+            if not 1 <= line <= 8:
+                raise ValueError("Line number must be between 1 and 8")
+            numbers.append(line)
+        return numbers
+
+    # -- trigger control -------------------------------------------------
+
+    def open(self, line):
+        for l in self.get_line_numbers(line):
+            self.bitmask |= (1 << (l - 1))
+        self.write()
+
+    def close(self, line):
+        for l in self.get_line_numbers(line):
+            self.bitmask &= ~(1 << (l - 1))
+        # self.port.flush()  # blocks until byte is sent - not necessary
+        self.write()
+
+    def close_all(self):
+        self.bitmask = 0
+        self.write()
+
+    # -- serial I/O ------------------------------------------------------
+
+    def reset(self):
+        self.bitmask = 0
+        if not self.simulate:
+            # b'' is identical to ''.encode() for something this simple.
+            self.port.write(b'RR')  # 'RR' is a device-specific command to reset.
+        else:
+            print('Port reset')
+
+    def write(self):
+        # See documentation at the bottom here: https://www.blackboxtoolkit.com/support_usb_ttl_module.html
+        payload = format(self.bitmask, '02X')
+        if not self.simulate:
+            self.port.write(payload.encode())
+        else:
+            print('Hex code written: ' + payload)
+            # self.open_lines()
+
+    def stop(self):
+        print('Shutting down port')
+        if not self.simulate:
+            self.reset()
+            self.port.close()
+            print('Port is closed: ', not self.port.is_open)
+
+    # -- OPTIONAL EXTRAS -------------------------------------------------
+    # -- display -------------------------------------------------
+
+    def is_open(self, lines):
+        return all(self.status(lines))
+
+    def is_closed(self, lines):
+        return not any(self.status(lines))
+
+    def status(self, lines=None):
+        if lines is None:
+            lines = range(1, 9)
+
+        matches = []
+        for l in self.get_line_numbers(lines): # simplify
+            is_open = self.bitmask & (1 << (l - 1))
+            matches.append(bool(is_open))  # Unsure if should convert to bool or not?
+            # print(f"Line {str(l)} is {'open' if is_open else 'closed'} {self.line2name(l)}")
+        return matches
+
+    def open_lines(self):
+        lines = []
+        for l in range(8):
+            if self.bitmask & (1 << l):
+                lines.append(l + 1)
+        print('Open lines:', lines, "{:08b}".format(self.bitmask))
+        return lines
+
+    def line2name(self, line):
+        if self.names is None:
+            return []
+        if isinstance(line, int):
+            line = [line]
+
+        line_names = []
+        for l in line:
+            l = int(l) #just incase it's a numpy int
+            if 1 <= l <= len(self.names):
+                line_names.append(self.names[l - 1])
+            else:
+                line_names.append('unnamed')
+        return line_names
+
+    # -- context manager support ----------------------------------------
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+        return False

digital_trigger-0.1.2.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: digital-trigger
+Version: 0.1.2
+Summary: Simple class for simplified pySerial interface for use in TTL event marking using e.g. PsychoPy.
+Author-email: Max Lovell <max_lovell@hotmail.co.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Max-Lovell/triggers
+Project-URL: Issues, https://github.com/Max-Lovell/triggers/issues
+Keywords: psychology,neuroscience,psychopy,eeg,triggers,serial
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.0
+
+# digital-trigger
+
+Easier sending of digital triggers/event markers/TTL signals using the Serial (pySerial) package with a Black Box Toolkit USB TTL module in Python and PsychoPy.
+
+## Install
+
+```bash
+pip install digital_trigger
+```
+
+Requires Python 3.8+ and [`pyserial`](https://pypi.org/project/pyserial/) (installed automatically). 
+
+In PsychoPy you can install packages in the Builder GUI by going to: 
+Tools > Plugins and packages manager > Packages > Open PIP terminal, and run  `pip install digital-trigger`
+
+To find COM port number: 
+- run the command `python -m serial.tools.list_ports -v`
+- On Windows, open Device Manager, expand "Ports (COM & LPT)", unplug and replug to see which is your device
+- On Mac run `ls /dev/cu.*` in Terminal and look for something like /dev/cu.usbserial-XXXX or /dev/cu.usbmodemXXXX — use the cu.* name, not tty.*. 
+- On Linux, run ls `/dev/ttyUSB* /dev/ttyACM*` — USB-serial adapters are usually `ttyUSB0`
+- Arduino-style boards `ttyACM0; dmesg | tail` right after plugging in shows the assigned name, and you may need to add yourself to the dialout group for permission.
+
+Make sure your COM port is set up with a latency of 1ms (or lower) and Baudrate of 115200. This can be done under Device Manager > COM port > Advanced on Windows.
+
+## Usage
+
+### PsychoPy
+
+Add the following in a 'custom code block' in the routine where your stimuli are presented. 
+Note drag the Code Component so it sits below the stimulus component in the routine view, as PsychoPy runs them top to bottom.
+Consider managing the triggers using a 'trigger_line' variable in your conditions file.
+
+#### Before Experiment
+
+```
+from digital_trigger import Trigger
+port = Trigger('COM4', names=['cond_1', 'cond_2', 'stim_1', 'stim_2'])
+```
+
+Note you can only do this once per experiment. 
+Don't do this in multiple code blocks in different routines or you will get a 'access/permission denied' error. 
+Probably best to have a single code block jsut for this in your first routine even.
+
+#### Begin Routine
+```
+trigger_opened = False
+trigger_closed = False
+```
+
+#### Each Frame 
+```
+# Open the line the instant the stimulus is drawn to the screen...
+# Change 'image' to the name of your stimulus component
+if image.status == STARTED and not trigger_opened:
+    win.callOnFlip(port.open, 'stim_1')
+    trigger_opened = True
+
+# ...and close it the instant the stimulus is removed.
+if image.status == FINISHED and not trigger_closed:
+    win.callOnFlip(port.close, 'stim_1')
+    trigger_closed = True
+```
+
+#### End Routine
+```
+if not trigger_closed:
+    port.close('stim_1')
+```
+
+#### End Experiment
+```
+port.stop()
+```
+
+### Python
+
+```python
+from digital_trigger import Trigger
+
+port = Trigger('COM4', names=['cond_1', 'cond_2', 'stim_1', 'stim_2'])
+
+port.open('stim_1')          # turn a line on  (by name)
+port.open([1, 'cond_2'])     # turn several on (numbers and names mixed)
+port.close('stim_1')         # turn one off
+port.close_all()             # turn everything off
+port.open_lines()            # index of open lines and prints the bitmask
+port.status()                # list of bools for each port if open or closed
+
+port.stop()                  # reset all lines and close the port
+```
+
+Or as a context manager, which closes the port for you:
+
+```python
+with Trigger('COM4', names=['stim_1']) as port:
+    port.open('stim_1')
+```
+
+Resources:
+- https://www.blackboxtoolkit.com/support_usb_ttl_module.html
+- https://www.blackboxtoolkit.com/docs/pdf/USBTTLv1r19.pdf
+- https://psychopy.org/developers/pluginDevGuide.html#plugindevguide
+
+# Dev notes
+
+#### build & upload
+Setup venv:
+```
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip build twine pytest
+```
+
+re-run build:
+```
+rm -rf dist                # clear old builds so nothing stale is uploaded
+python3 -m build
+ls dist                    # confirm the new version number is shown
+twine upload --repository testpypi dist/*
+```
+
+#### test
+
+```
+cd /tmp
+rm -rf testenv
+python3 -m venv testenv
+source testenv/bin/activate
+pip install -i https://test.pypi.org/simple/ \
+    --extra-index-url https://pypi.org/simple/ \
+    digital-trigger==0.1.2          # match the version
+python -c "from digital_trigger import Trigger; t = Trigger(simulate=True, names=['stim_1']); t.open('stim_1'); print('ok', t.bitmask)"
+deactivate
+```
+
+To install from the test repo on a new computer:
+```
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ digital-trigger==0.1.2
+```
+
+Small script to check:
+```
+from digital_trigger import Trigger
+t = Trigger(simulate=True, names=['stim_1'])
+t.open('stim_1')
+print('ok', t.bitmask)
+```
+
+#### release
+```
+cd /path/to/project         # back to the project folder
+twine upload dist/*         # no --repository = real PyPI
+```

digital_trigger-0.1.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+digital_trigger/__init__.py,sha256=zLtHgzCPnQ7j_G4Cd7ShP3VuVcWn0FB5WG6E0m6ufBs,73
+digital_trigger/trigger.py,sha256=3iHN8QjYF-XKgC5j5MHjm3KaHt2hGRyxkvTL0Qw3Bs8,4170
+digital_trigger-0.1.2.dist-info/METADATA,sha256=gZEPAl3jJ-9id-x5WE3KfOvAleiGdlaMWawyuNIdDak,5793
+digital_trigger-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+digital_trigger-0.1.2.dist-info/top_level.txt,sha256=iMDKUpK3RZ1M2jaEeKVxjQf7MKgumc5vJfyFEhdihJI,16
+digital_trigger-0.1.2.dist-info/RECORD,,

digital_trigger-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

digital_trigger-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+digital_trigger