teraflash-ctrl 1.4.0__tar.gz

teraflash_ctrl-1.4.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: teraflash-ctrl
+Version: 1.4.0
+Summary: This Python package allows the configuration and readout of the TeraFlash Pro THz spectrometer.
+Author-email: Linus Leo Stöckli <linus.stoeckli@unibe.ch>
+Project-URL: Homepage, https://github.com/unibe-icelab/teraflash-ctrl-python
+Project-URL: Bug Tracker, https://github.com/unibe-icelab/teraflash-ctrl-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+
+# TeraFlash Pro Python Package
+
+<a href="https://github.com/unibe-icelab/teraflash-ctrl-python/releases"><img src="icons/icon.png" alt=“” width="100" height="100"> </img> </a>
+
+This code is developed by the University of Bern and is no official product of Toptica Photonics AG.  
+This Python Package allows the configuration and readout of the TeraFlash Pro THz spectrometer.  
+The TCP communication protocol is probably incomplete and features may be missing as it was reverse engineered using
+wireshark. The scanning stage is not supported but a list of other features is.
+
+This is a simple library with no persistence settings (the configurations of the previous run will not be stored when the python session is closed).
+A complete GUI written in Rust is also available [here](https://github.com/unibe-icelab/teraflash-ctrl).
+
+Features:  
+- [x] Select begin time for the time window
+- [x] Select range
+- [x] Select average
+- [x] Start/Stop Laser
+- [x] Start/Stop Emitters
+- [x] Start/Stop Acquisition
+- [x] Set transmission
+- [x] Set motion mode
+- [x] Set channel
+- [x] Get status
+- [x] Get data (time domain and frequency domain)
+- [x] auto pulse detection function
+- [X] Set antenna range
+- [ ] ...
+
+## I. Installation
+Download the [latest release](https://github.com/unibe-icelab/teraflash-ctrl-python/releases) or the [current state](https://github.com/unibe-icelab/teraflash-ctrl-python/archive/refs/heads/main.zip)
+as a zip archive, move it into your working directory and then run:
+```shell
+pip install teraflash-ctrl-python-v1.4.0.zip
+```
+for the latest version or
+```shell
+pip install teraflash-ctrl-python-main.zip
+```
+for the current state of the main branch to install the package for your virtual python environment or system-wide.
+
+## II. Taking a measurement
+When connected to the device, you can turn on the laser and then the emitter.
+After starting the acquisition, new data should be continuously updated and the most recent dataset can be obtained using `device.get_data()`:
+
+```python
+from teraflash import TeraFlash
+
+if __name__ == "__main__":
+    ip = "169.254.84.101"
+    with TeraFlash(ip) as device:
+        print(device.get_status())
+        device.set_laser(True)
+        device.set_emitter(1, True)
+        device.set_acq_start()
+        print(device.get_data())
+```
+
+Always use the context manager to ensure that the connection is properly closed upon exiting!  
+Consult the [`example.py`](example.py) for usage.  
+  
+  
+_Disclaimer: This package is provided on a best effort basis with no guarantee as to the functionality and correctness. Use at your
+own risk.
+Users are encouraged to contribute by submitting [issues](https://github.com/unibe-icelab/teraflash-ctrl-python/issues) and/or [pull requests](https://github.com/unibe-icelab/teraflash-ctrl-python/pulls) for bug reporting or feature requests._
+
+
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/

teraflash_ctrl-1.4.0/README.md

@@ -0,0 +1,72 @@
+# TeraFlash Pro Python Package
+
+<a href="https://github.com/unibe-icelab/teraflash-ctrl-python/releases"><img src="icons/icon.png" alt=“” width="100" height="100"> </img> </a>
+
+This code is developed by the University of Bern and is no official product of Toptica Photonics AG.  
+This Python Package allows the configuration and readout of the TeraFlash Pro THz spectrometer.  
+The TCP communication protocol is probably incomplete and features may be missing as it was reverse engineered using
+wireshark. The scanning stage is not supported but a list of other features is.
+
+This is a simple library with no persistence settings (the configurations of the previous run will not be stored when the python session is closed).
+A complete GUI written in Rust is also available [here](https://github.com/unibe-icelab/teraflash-ctrl).
+
+Features:  
+- [x] Select begin time for the time window
+- [x] Select range
+- [x] Select average
+- [x] Start/Stop Laser
+- [x] Start/Stop Emitters
+- [x] Start/Stop Acquisition
+- [x] Set transmission
+- [x] Set motion mode
+- [x] Set channel
+- [x] Get status
+- [x] Get data (time domain and frequency domain)
+- [x] auto pulse detection function
+- [X] Set antenna range
+- [ ] ...
+
+## I. Installation
+Download the [latest release](https://github.com/unibe-icelab/teraflash-ctrl-python/releases) or the [current state](https://github.com/unibe-icelab/teraflash-ctrl-python/archive/refs/heads/main.zip)
+as a zip archive, move it into your working directory and then run:
+```shell
+pip install teraflash-ctrl-python-v1.4.0.zip
+```
+for the latest version or
+```shell
+pip install teraflash-ctrl-python-main.zip
+```
+for the current state of the main branch to install the package for your virtual python environment or system-wide.
+
+## II. Taking a measurement
+When connected to the device, you can turn on the laser and then the emitter.
+After starting the acquisition, new data should be continuously updated and the most recent dataset can be obtained using `device.get_data()`:
+
+```python
+from teraflash import TeraFlash
+
+if __name__ == "__main__":
+    ip = "169.254.84.101"
+    with TeraFlash(ip) as device:
+        print(device.get_status())
+        device.set_laser(True)
+        device.set_emitter(1, True)
+        device.set_acq_start()
+        print(device.get_data())
+```
+
+Always use the context manager to ensure that the connection is properly closed upon exiting!  
+Consult the [`example.py`](example.py) for usage.  
+  
+  
+_Disclaimer: This package is provided on a best effort basis with no guarantee as to the functionality and correctness. Use at your
+own risk.
+Users are encouraged to contribute by submitting [issues](https://github.com/unibe-icelab/teraflash-ctrl-python/issues) and/or [pull requests](https://github.com/unibe-icelab/teraflash-ctrl-python/pulls) for bug reporting or feature requests._
+
+
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/

teraflash_ctrl-1.4.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "teraflash-ctrl"
+version = "1.4.0"
+authors = [
+    { name = "Linus Leo Stöckli", email = "linus.stoeckli@unibe.ch" },
+]
+description = "This Python package allows the configuration and readout of the TeraFlash Pro THz spectrometer."
+readme = "README.md"
+license-files = ["LICENSE"]
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy",
+    "scipy"
+]
+[project.urls]
+"Homepage" = "https://github.com/unibe-icelab/teraflash-ctrl-python"
+"Bug Tracker" = "https://github.com/unibe-icelab/teraflash-ctrl-python/issues"

teraflash_ctrl-1.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

teraflash_ctrl-1.4.0/src/__init__.py

@@ -0,0 +1,8 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""

teraflash_ctrl-1.4.0/src/interface.py

@@ -0,0 +1,356 @@
+"""
+Copyright (c) 2026 University of Bern, Space Research & Planetary Sciences, Linus Leo Stöckli.
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/
+"""
+
+import time
+from queue import Queue, Empty
+import threading
+
+import numpy as np
+import platform
+import socket
+import subprocess
+import logging
+
+from math_utils import get_fft
+
+
+class DataContainer:
+
+    def __init__(self, n=1000):
+        """
+            Data container that stores the data sent by the instrument
+        Args:
+            n: length of dataset (depends on the selected range)
+        """
+        self.time = np.zeros(n)
+        self.freq = np.zeros(n)
+
+        self.signal_1 = np.zeros(n)
+        self.fft_1_amp = np.zeros(n)
+        self.fft_1_phase = np.zeros(n)
+
+        self.signal_2 = np.zeros(n)
+        self.fft_2_amp = np.zeros(n)
+        self.fft_2_phase = np.zeros(n)
+
+
+# global variables for thread communication
+data = DataContainer()
+n_avg = 0
+status = ""
+
+
+class TopticaSocket:
+    def __init__(self,
+                 ip: str,
+                 running: threading.Event,
+                 connected: threading.Event,
+                 cmd_ack: threading.Event,
+                 buffer_emptied: threading.Event,
+                 range_changed: threading.Event,
+                 acq_running: threading.Event,
+                 avg_data: threading.Event):
+        """
+            TCP Socket struct, used for the communication between the server (Computer) and the client (instrument)
+            with two TCP connections (one for configuration and one for data transmission)
+        Args:
+            ip: ip address
+            running: threading event that signals if the application is running
+            connected: threading event that signals if a client is connected
+            cmd_ack: threading event that signals when a command is acknowledged
+            range_changed: threading event that signals when the range has been changed in the configuration
+        """
+        self.send_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00'
+        self.r_stat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x02'
+        self.r_dat_header = b'\xcd\xef\x124x\x9a\xfe\xdc\x00\x00\x00\x01\x00\t\x1a\xe6\x03\xe8\x00\x00\x04L\x00\x00\x0c\xcc\xcc\xcc\x00\x00\x16\x0b\x00\x00]\xd8\x00\x00\x00\x01\x00\x00\x00\x01\x00\x00\x00\x01\x00\x00\x00\x00'
+        self.r_dat_header = b'\xcd\xef\x124x\x9a\xfe'
+        self.full_data_header_len = 52
+        self.read_header_len = 19
+        self.data_header_len = 7
+
+        self.avg_countdown = 0
+
+        self.config_server_address = (ip, 6341)
+        self.data_server_address = (ip, 6342)
+
+        self.t_begin = 1000.00
+        self.range = 50
+        self.antenna_range = 1000.0
+
+        self.running = running
+        self.connected = connected
+        self.cmd_ack = cmd_ack
+        self.range_changed = range_changed
+        self.buffer_emptied = buffer_emptied
+        self.acq_running = acq_running
+        self.avg_data = avg_data
+
+        if not self.ping(ip):
+            raise ConnectionError
+
+    @staticmethod
+    def ping(host: str):
+        """
+            determines whether a device is connected or not
+        Args:
+            host: IP address as a string
+
+        Returns: True for connected, False for not connected
+
+        """
+        res = False
+        ping_param = "-n" if platform.system().lower() == "windows" else "-c"
+        command = ['ping', ping_param, '1', host]
+        result = subprocess.call(command)
+        if result == 0:
+            res = True
+        return res
+
+    def wait_for_answer(self, client: socket, length: int = 1024):
+        """
+            waits for the device to acknowledge the previously sent command
+        Args:
+            client: socket object
+            length: length of the buffer
+
+        Returns: True for valid response, False for error
+
+        """
+        while self.running.is_set():
+            _data = client.recv(length)[self.read_header_len:]
+            if _data:
+                _data_decoded = _data.decode("utf-8", "ignore")
+                if "OK" in _data_decoded:
+                    logging.debug(f"[TCP CONF] received: {_data_decoded}")
+                    return True
+                elif "MON" in _data_decoded:
+                    return True
+                logging.debug(f"[TCP CONF] received: {_data_decoded}")
+            else:
+                logging.error(f"[TCP CONF] No valid reply from device: {_data.decode('utf-8', 'ignore')}")
+                return False
+
+    def run_conf_tcp(self, cmd_queue: Queue):
+        """
+            Config TCP thread on port 6341. This handles all the configurations for the device.
+        Args:
+            cmd_queue: Queue from main thread with all the interactive
+
+        Returns:
+
+        """
+        global status
+        global data
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            # Set the SO_REUSEADDR option to allow reuse of the port
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            # bind server to the address (only works when the address exists)
+            s.bind(self.config_server_address)
+            logging.info(f"[TCP CONF] Starting server at address {self.config_server_address}")
+            # wait for connections
+            s.listen()
+            # accept connection from device
+            client, addr = s.accept()
+            logging.info(f"[TCP CONF] Connected by client with address {addr}")
+            # now we are connected
+            self.connected.set()
+
+            while self.running.is_set():
+                # check the queue for commands
+                try:
+                    cmd = cmd_queue.get(block=False)
+                    logging.debug(f"[TCP CONF] sending: {cmd}")
+                    (b, c) = cmd
+                    message = self.send_header + b + c.encode()
+                    # send command
+                    client.send(message)
+                    if b == b'\x14':
+                        # if we request the status, save the response
+                        status = client.recv(2048)[self.read_header_len:].decode("utf-8", "ignore")
+                        self.cmd_ack.set()
+                    elif "RANGE" in c:
+                        # if we change the range, also change it for the data thread
+                        parts = c.split(" ")
+                        self.range = float(parts[-1])
+                        data.time = np.linspace(self.t_begin, self.t_begin + self.range, 20 * int(self.range) + 1)
+                        # wait for acknowledge
+                        if not self.wait_for_answer(client):
+                            return
+                        self.cmd_ack.set()
+                    elif "BEGIN" in c:
+                        # if we change the range, also change it for the data thread
+                        parts = c.split(" ")
+                        self.t_begin = float(parts[-1])
+                        data.time = np.linspace(self.t_begin, self.t_begin + self.range, 20 * int(self.range) + 1)
+                        # wait for acknowledge
+                        if not self.wait_for_answer(client):
+                            return
+                        self.cmd_ack.set()
+                    else:
+                        # wait for acknowledge
+                        if not self.wait_for_answer(client):
+                            return
+                        self.cmd_ack.set()
+                except Empty:
+                    # just to a simple heartbeat
+                    (b, c) = (b'\x12', "SYSTEM : MONITOR 1")
+                    message = self.send_header + b + c.encode()
+                    client.send(message)
+                    # wait for acknowledge
+                    if not self.wait_for_answer(client):
+                        return
+                time.sleep(0.25)
+
+    def run_tcp_dat(self, cmd_queue: Queue, config_queue: Queue):
+        """
+            Data TCP thread on port 6342. This handles receives all the streamed data from the device and decodes it.
+        """
+        global data
+        global n_avg
+        types = np.dtype([
+            ("signal_1", np.int32),
+            ("signal_2", np.int32),
+        ])
+        antenna_range = 1000.0
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            # Set the SO_REUSEADDR option to allow reuse of the port
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            # bind server to the address (only works when the address exists)
+            s.bind(self.data_server_address)
+            logging.info(f"[TCP DAT] Starting server at address {self.data_server_address}")
+            # wait for connections
+            s.listen()
+            # accept connection from device
+            client, addr = s.accept()
+            client.settimeout(2)
+
+            logging.info(f"[TCP DAT] Connected by client with address {addr}")
+            # now we are connected
+            while self.running.is_set():
+                if self.range_changed.is_set():
+                    # range has changed and needs to be adjusted
+                    # need to empty the read buffer
+                    while self.running.is_set():
+                        logging.debug(f"emptying buffer...")
+                        try:
+                            client.recv(32100)
+                        except socket.timeout:
+                            break
+                    self.buffer_emptied.set()
+                    self.range_changed.clear()
+
+                # data always comes in the shape of 4 datasets each as 16bit ints with length of
+                # (20 * self.range + 1)
+                # the header is 52 8 bit ints and since we read 8 bit ints we need to multiply the data by 2
+                if self.range_changed.is_set():
+                    continue
+                if not self.acq_running.is_set():
+                    # no data received
+                    time.sleep(1.0)
+                    continue
+                try:
+                    raw_data = client.recv(2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len)
+                except socket.timeout:
+                    continue
+                if not raw_data:
+                    # no data received
+                    time.sleep(1.0)
+                    continue
+
+                if raw_data[:self.data_header_len] != self.r_dat_header:
+                    continue
+
+                if len(raw_data) != 2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len:
+                    skip_this = False
+                    while self.running.is_set():
+                        try:
+                            to_append = client.recv(
+                                2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len - len(raw_data))
+                            raw_data += to_append
+                            if len(raw_data) == 2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len:
+                                break
+                            if len(raw_data) == 2 * 4 * (20 * int(self.range) + 1) + self.full_data_header_len:
+                                skip_this = True
+                                break
+                        except socket.timeout:
+                            skip_this = True
+                            break
+                    if skip_this:
+                        continue
+
+                # TODO: the following code is not properly implemented yet, we need
+                # to check how we handle it, if the data comes not in the proper packet length
+
+                _data = raw_data[self.full_data_header_len:]
+
+                # check if header is at the beginning of the received payload
+                # if raw_data[:self.data_header_len] == self.r_dat_header:
+                #     # remove the header
+                #     _data = raw_data[self.data_header_len:]
+                # else:
+                #     _data = raw_data[self.data_header_len:]
+                #     # print("header not in the beginning")
+                #     while self.running.is_set():
+                #         logging.info("data does not have correct length...")
+                #
+                #         # check if the data is of the correct length
+                #         if len(_data) != 2 * 4 * (20 * self.range + 1):
+                #             _data = _data + client.recv(2 * 4 * (20 * int(self.range) + 1) - len(_data))
+                #         else:
+                #             break
+                try:
+                    # decode received payload to 32 bit ints
+                    types = types.newbyteorder('>')
+                    arr = np.frombuffer(_data, dtype=types)
+
+                    if not config_queue.empty():
+                        antenna_range = config_queue.get()
+
+                    scale_factor = 20.0 * 1000.0 / antenna_range;
+
+                    # TODO: make subtracting offset optional.
+                    signal_1 = arr['signal_1'] / scale_factor / 2 ** 16 - arr['signal_1'][0] / scale_factor / 2 ** 16
+                    signal_2 = arr['signal_2'] / scale_factor / 2 ** 16 - arr['signal_2'][0] / scale_factor / 2 ** 16
+
+                    if self.avg_data.is_set():
+                        if data.signal_1.shape == signal_1.shape:
+                            data.signal_1 += signal_1
+                        else:
+                            data.signal_1 = signal_1
+                        if data.signal_2.shape == signal_2.shape:
+                            data.signal_2 += signal_2
+                        n_avg += 1
+                    else:
+                        data.signal_1 = signal_1
+                        data.signal_2 = signal_2
+                        n_avg = 0
+
+                    # do fft of signal 1
+                    pulse = data.signal_1
+                    f, a, arg = get_fft(data.time, pulse)
+                    data.freq = f
+                    data.fft_1_amp = a / np.max(a)
+                    data.fft_1_phase = arg
+
+                    # do fft of signal 2
+                    pulse = data.signal_2
+                    f, a, arg = get_fft(data.time, pulse)
+                    data.fft_2_amp = a / np.max(a)
+                    data.fft_2_phase = arg
+
+                    # update avg countdown
+                    if self.avg_countdown > 0:
+                        self.avg_countdown -= 1
+
+                except Exception as e:
+                    logging.error(e)
+                    logging.error(f"{len(data.signal_1)=}")