biosignal-device-interface 0.1.0__py3-none-any.whl

biosignal_device_interface/devices/otb/otb_muovi.py

@@ -0,0 +1,291 @@
+# Python Libraries
+"""
+Device class for real-time interfacing the Muovi device.
+Developer: Dominik I. Braun
+Contact: dome.braun@fau.de
+Last Update: 2024-06-05
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Union, Dict
+from PySide6.QtNetwork import QTcpSocket, QTcpServer, QHostAddress
+import numpy as np
+
+# Local Libraries
+from biosignal_device_interface.devices.core.base_device import BaseDevice
+from biosignal_device_interface.constants.devices.core.base_device_constants import (
+    DeviceType,
+    DeviceChannelTypes,
+)
+
+# Constants
+from biosignal_device_interface.constants.devices.otb_muovi_constants import (
+    MUOVI_CONVERSION_FACTOR_DICT,
+    MuoviWorkingMode,
+    MuoviDetectionMode,
+    MUOVI_WORKING_MODE_CHARACTERISTICS_DICT,
+    MUOVI_SAMPLES_PER_FRAME_DICT,
+    MUOVI_AVAILABLE_CHANNELS_DICT,
+)
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QMainWindow, QWidget
+    from aenum import Enum
+
+
+class OTBMuovi(BaseDevice):
+    """
+    Muovi device class derived from BaseDevice class.
+
+    Args:
+        parent (Union[QMainWindow, QWidget], optional):
+            Parent widget to which the device is assigned to.
+            Defaults to None.
+
+        is_muovi_plus (bool):
+            True if the device is a Muovi Plus, False if not.
+
+    The Muovi class is using a TCP/IP protocol to communicate with the device.
+    """
+
+    def __init__(
+        self,
+        parent: Union[QMainWindow, QWidget] = None,
+        is_muovi_plus: bool = False,
+    ) -> None:
+        """
+        Initialize the Muovi device.
+
+        Args:
+            parent (Union[QMainWindow, QWidget], optional): Parent widget. Defaults to None.
+            is_muovi_plus (bool, optional): Boolean to initialize the Muovi device as Muovi+ (64 biosignal channels) or Muovi (32 biosignal channels). Defaults to False (Muovi).
+        """
+        super().__init__(parent)
+
+        # Device Parameters
+        self._device_type: DeviceType = (
+            DeviceType.OTB_MUOVI_PLUS if is_muovi_plus else DeviceType.OTB_MUOVI
+        )
+
+        # Connection Parameters
+        self._interface: QTcpServer = None
+        self._client_socket: QTcpSocket | None = None
+
+        # Configuration Parameters
+        self._working_mode: MuoviWorkingMode = MuoviWorkingMode.NONE
+        self._detection_mode: MuoviDetectionMode = MuoviDetectionMode.NONE
+        self._configuration_command: int | None = None
+
+    def _connect_to_device(self) -> bool:
+        super()._connect_to_device()
+
+        self._interface = QTcpServer(self)
+        self._received_bytes: bytearray = bytearray()
+
+        if not self._interface.listen(
+            QHostAddress(self._connection_settings[0]), self._connection_settings[1]
+        ):
+            return False
+
+        self._interface.newConnection.connect(self._make_request)
+
+        self._connection_timeout_timer.start()
+
+        return True
+
+    def _make_request(self) -> bool:
+        super()._make_request()
+        self._client_socket = self._interface.nextPendingConnection()
+
+        if self._client_socket:
+
+            self._client_socket.readyRead.connect(self._read_data)
+
+            if not self._is_connected:
+                self._is_connected = True
+                self.connect_toggled.emit(self._is_connected)
+                self._connection_timeout_timer.stop()
+                return True
+
+            elif not self._is_configured:
+                self._is_configured = True
+                self.configure_toggled.emit(self._is_configured)
+                return True
+
+    def _disconnect_from_device(self) -> bool:
+        super()._disconnect_from_device()
+
+        if self._client_socket is not None:
+            self._client_socket.readyRead.disconnect(self._read_data)
+            self._client_socket.disconnectFromHost()
+            self._client_socket.close()
+
+        if self._interface is not None:
+            self._interface.close()
+
+        return True
+
+    def configure_device(
+        self, settings: Dict[str, Union[Enum, Dict[str, Enum]]]  # type: ignore
+    ) -> None:
+        super().configure_device(settings)
+
+        if not self._is_connected or self._client_socket is None:
+            return
+
+        # Check if detection mode is valid for working mode (Case EEG -> MONOPOLAR_GAIN_4 => MONOPOLAR_GAIN_8)
+        if self._working_mode == MuoviWorkingMode.EEG:
+            if self._detection_mode == MuoviDetectionMode.MONOPOLAR_GAIN_4:
+                self._detection_mode = MuoviDetectionMode.MONOPOLAR_GAIN_8
+
+        self._conversion_factor_biosignal = MUOVI_CONVERSION_FACTOR_DICT[
+            self._detection_mode
+        ]
+        self._conversion_factor_auxiliary = self._conversion_factor_biosignal
+
+        # Set configuration parameters for data transfer
+        working_mode_characteristics = MUOVI_WORKING_MODE_CHARACTERISTICS_DICT[
+            self._working_mode
+        ]
+        self._sampling_frequency = working_mode_characteristics["sampling_frequency"]
+        self._bytes_per_sample = working_mode_characteristics["bytes_per_sample"]
+        self._samples_per_frame = MUOVI_SAMPLES_PER_FRAME_DICT[self._device_type][
+            self._working_mode
+        ]
+
+        self._number_of_channels = MUOVI_AVAILABLE_CHANNELS_DICT[self._device_type][
+            DeviceChannelTypes.ALL
+        ]
+        self._number_of_biosignal_channels = MUOVI_AVAILABLE_CHANNELS_DICT[
+            self._device_type
+        ][DeviceChannelTypes.BIOSIGNAL]
+        self._biosignal_channel_indices = np.arange(self._number_of_biosignal_channels)
+
+        self._number_of_auxiliary_channels = MUOVI_AVAILABLE_CHANNELS_DICT[
+            self._device_type
+        ][DeviceChannelTypes.AUXILIARY]
+        self._auxiliary_channel_indices = np.arange(
+            self._number_of_biosignal_channels,
+            self._number_of_biosignal_channels + self._number_of_auxiliary_channels,
+        )
+
+        self._buffer_size = (
+            self._number_of_channels * self._samples_per_frame * self._bytes_per_sample
+        )
+
+        self._received_bytes = bytearray()
+
+        self._configure_command()
+        self._send_configuration_to_device()
+
+    def _send_configuration_to_device(self) -> None:
+        configuration_bytes = int(self._configuration_command).to_bytes(
+            1, byteorder="big"
+        )
+
+        success = self._client_socket.write(configuration_bytes)
+
+        if success == -1:
+            self._disconnect_from_device()
+
+    def _configure_command(self) -> None:
+        self._configuration_command = self._working_mode.value << 2
+        self._configuration_command += self._detection_mode.value
+
+    def _start_streaming(self) -> None:
+        super()._start_streaming()
+
+        if self._configuration_command is None:
+            return
+
+        self._configuration_command += 1
+        self._send_configuration_to_device()
+
+    def _stop_streaming(self) -> None:
+        super()._stop_streaming()
+
+        if self._configuration_command is None:
+            return
+
+        self._configuration_command -= 1
+        self._send_configuration_to_device()
+
+    def clear_socket(self) -> None:
+        if self._client_socket is not None:
+            self._client_socket.readAll()
+
+    def _read_data(self) -> None:
+        super()._read_data()
+
+        if not self._is_streaming:
+            self.clear_socket()
+            return
+
+        while self._client_socket.bytesAvailable() > self._buffer_size:
+            packet = self._client_socket.read(self._buffer_size)
+            if not packet:
+                continue
+
+            self._received_bytes.extend(packet)
+
+            while len(self._received_bytes) >= self._buffer_size:
+                data_to_process = self._received_bytes[: self._buffer_size]
+                self._process_data(data_to_process)
+                self._received_bytes = self._received_bytes[self._buffer_size :]
+
+    def _process_data(self, data: bytearray) -> None:
+        super()._process_data(data)
+
+        decoded_data = self._bytes_to_integers(data)
+
+        processed_data = decoded_data.reshape(
+            self._number_of_channels, -1, order="F"
+        ).astype(np.float32)
+
+        # Emit the data
+        self.data_available.emit(processed_data)
+        self.biosignal_data_available.emit(self._extract_biosignal_data(processed_data))
+        self.auxiliary_data_available.emit(self._extract_auxiliary_data(processed_data))
+
+    # Convert channels from bytes to integers
+    def _bytes_to_integers(
+        self,
+        data: bytearray,
+    ) -> np.ndarray:
+        channel_values = []
+        # Separate channels from byte-string. One channel has
+        # "bytes_in_sample" many bytes in it.
+        for channel_index in range(len(data) // 2):
+            channel_start = channel_index * self._bytes_per_sample
+            channel_end = (channel_index + 1) * self._bytes_per_sample
+            channel = data[channel_start:channel_end]
+
+            # Convert channel's byte value to integer
+            match self._working_mode:
+                case MuoviWorkingMode.EMG:
+                    value = self._decode_int16(channel)
+                case MuoviWorkingMode.EEG:
+                    value = self._decode_int24(channel)
+
+            channel_values.append(value)
+
+        return np.array(channel_values)
+
+    def _decode_int16(self, bytes_value: bytearray) -> int:
+        value = None
+        # Combine 2 bytes to a 16 bit integer value
+        value = bytes_value[0] * 2**8 + bytes_value[1]
+        # See if the value is negative and make the two's complement
+        if value >= 2**15:
+            value -= 2**16
+        return value
+
+    # Convert byte-array value to an integer value and apply two's complement
+    def _decode_int24(self, bytes_value: bytearray) -> int:
+        value = None
+        # Combine 3 bytes to a 24 bit integer value
+        value = bytes_value[0] * 2**16 + bytes_value[1] * 2**8 + bytes_value[2]
+        # See if the value is negative and make the two's complement
+        if value >= 2**23:
+            value -= 2**24
+        return value

biosignal_device_interface/devices/otb/otb_quattrocento.py

@@ -0,0 +1,235 @@
+"""
+1)  Quattrocento Light class for real-time interface to 
+    Quattrocento using OT Biolab Light.
+
+2)  Quattrocento class for direct real-time interface to 
+    Quattrocento without using OT Biolab Light.
+
+Developer: Dominik I. Braun
+Contact: dome.braun@fau.de
+Last Update: 2023-06-05
+"""
+
+# Python Libraries
+from __future__ import annotations
+from typing import TYPE_CHECKING, Union, Dict
+from PySide6.QtNetwork import QTcpSocket, QHostAddress
+from PySide6.QtCore import QIODevice
+import numpy as np
+
+
+from biosignal_device_interface.devices.core.base_device import BaseDevice
+from biosignal_device_interface.constants.devices.core.base_device_constants import (
+    DeviceType,
+)
+from biosignal_device_interface.constants.devices.otb_quattrocento_constants import (
+    COMMAND_START_STREAMING,
+    COMMAND_STOP_STREAMING,
+    CONNECTION_RESPONSE,
+    QUATTROCENTO_LIGHT_STREAMING_FREQUENCY_DICT,
+    QUATTROCENTO_SAMPLING_FREQUENCY_DICT,
+    QuattrocentoLightSamplingFrequency,
+    QuattrocentoLightStreamingFrequency,
+)
+
+
+if TYPE_CHECKING:
+    # Python Libraries
+    from PySide6.QtWidgets import QMainWindow, QWidget
+    from aenum import Enum
+
+
+class OTBQuattrocentoLight(BaseDevice):
+    """
+    QuattrocentoLight device class derived from BaseDevice class.
+    The QuattrocentoLight is using a TCP/IP protocol to communicate with the device.
+
+    This class directly interfaces with the OT Biolab Light software from
+    OT Bioelettronica. The configured settings of the device have to
+    match the settings from the OT Biolab Light software!
+    """
+
+    def __init__(
+        self,
+        parent: Union[QMainWindow, QWidget] = None,
+    ) -> None:
+        super().__init__(parent)
+
+        # Device Parameters
+        self._device_type: DeviceType = DeviceType.OTB_QUATTROCENTO_LIGHT
+
+        # Device Information
+        self._number_of_channels: int = 408  # Fix value
+        self._auxiliary_channel_start_index: int = 384  # Fix value
+        self._number_of_auxiliary_channels: int = 16  # Fix value
+        self._conversion_factor_biosignal: float = 5 / (2**16) / 150 * 1000  # in mV
+        self._conversion_factor_auxiliary: float = 5 / (2**16) / 0.5  # in mV
+        self._bytes_per_sample: int = 2  # Fix value
+        # Quattrocento unique parameters
+        self._streaming_frequency: int | None = None
+
+        # Connection Parameters
+        self._interface: QTcpSocket = QTcpSocket()
+
+        # Configuration Parameters
+        self._grids: list[int] | None = None
+        self._grid_size: int = 64  # TODO: This is only valid for the big electrodes
+        self._streaming_frequency_mode: QuattrocentoLightStreamingFrequency | None = (
+            None
+        )
+        self._sampling_frequency_mode: QuattrocentoLightSamplingFrequency | None = None
+
+    def _connect_to_device(self) -> bool:
+        super()._connect_to_device()
+
+        self._received_bytes: bytearray = bytearray()
+        return self._make_request()
+
+    def _make_request(self) -> bool:
+        super()._make_request()
+        # Signal self.connect_toggled is emitted in _read_data
+        self._interface.connectToHost(
+            QHostAddress(self._connection_settings[0]),
+            self._connection_settings[1],
+            QIODevice.ReadWrite,
+        )
+
+        if not self._interface.waitForConnected(1000):
+            self._disconnect_from_device()
+            return False
+
+        self._interface.readyRead.connect(self._read_data)
+
+        return True
+
+    def _disconnect_from_device(self) -> None:
+        super()._disconnect_from_device()
+
+        self._interface.disconnectFromHost()
+        self._interface.readyRead.disconnect(self._read_data)
+        self._interface.close()
+
+    def configure_device(
+        self, settings: Dict[str, Union[Enum, Dict[str, Enum]]]  # type: ignore
+    ) -> None:
+        super().configure_device(settings)
+
+        # Configure the device
+        self._number_of_biosignal_channels = len(self._grids) * self._grid_size
+        self._biosignal_channel_indices = np.array(
+            [
+                i * self._grid_size + j
+                for i in self._grids
+                for j in range(self._grid_size)
+            ]
+        )
+
+        self._auxiliary_channel_indices = np.array(
+            [
+                i + self._auxiliary_channel_start_index
+                for i in range(self._number_of_auxiliary_channels)
+            ]
+        )
+
+        self._streaming_frequency = QUATTROCENTO_LIGHT_STREAMING_FREQUENCY_DICT[
+            self._streaming_frequency_mode
+        ]
+        self._sampling_frequency = QUATTROCENTO_SAMPLING_FREQUENCY_DICT[
+            self._sampling_frequency_mode
+        ]
+
+        self._samples_per_frame = self._sampling_frequency // self._streaming_frequency
+
+        self._buffer_size = (
+            self._bytes_per_sample * self._number_of_channels * self._samples_per_frame
+        )
+
+        self._is_configured = True
+        self.configure_toggled.emit(True)
+
+    def _start_streaming(self) -> None:
+        super()._start_streaming()
+
+        self._interface.write(COMMAND_START_STREAMING)
+
+    def _stop_streaming(self) -> None:
+        super()._stop_streaming()
+
+        self._interface.write(COMMAND_STOP_STREAMING)
+        self._interface.waitForBytesWritten(1000)
+
+    def clear_socket(self) -> None:
+        super().clear_socket()
+
+        self._interface.readAll()
+
+    def _read_data(self) -> None:
+        super()._read_data()
+
+        # Wait for connection response
+        if not self._is_connected:
+            if self._interface.bytesAvailable() == len(CONNECTION_RESPONSE):
+                if self._interface.readAll() == CONNECTION_RESPONSE:
+
+                    self._is_connected = True
+                    self.connect_toggled.emit(True)
+                    return
+
+        if not self._is_streaming:
+            self.clear_socket()
+            return
+
+        while self._interface.bytesAvailable() > self._buffer_size:
+            packet = self._interface.read(self._buffer_size)
+            if not packet:
+                continue
+
+            self._received_bytes.extend(packet)
+
+            while len(self._received_bytes) >= self._buffer_size:
+                data_to_process = self._received_bytes[: self._buffer_size]
+                self._process_data(data_to_process)
+                self._received_bytes = self._received_bytes[self._buffer_size :]
+
+    def _process_data(self, data: bytearray) -> None:
+        super()._process_data(data)
+
+        # Decode the data
+        decoded_data = np.frombuffer(data, dtype=np.int16)
+
+        # Reshape it to the correct format
+        processed_data = decoded_data.reshape(
+            self._number_of_channels, -1, order="F"
+        ).astype(np.float32)
+
+        # Emit the data
+        self.data_available.emit(processed_data)
+        self.biosignal_data_available.emit(self._extract_biosignal_data(processed_data))
+        self.auxiliary_data_available.emit(self._extract_auxiliary_data(processed_data))
+
+    def get_device_information(self) -> Dict[str, Enum | int | float | str]:
+        return super().get_device_information()
+
+
+class OTBQuattrocento(BaseDevice):
+    """
+    Quattrocento device class derived from BaseDevice class.
+
+    The Quattrocento class is using a TCP/IP protocol to communicate with the device.
+    """
+
+    def __init__(
+        self,
+        parent: Union[QMainWindow, QWidget] = None,
+    ) -> None:
+        super().__init__(parent)
+
+        # Device Parameters
+        self._device_type: DeviceType = DeviceType.OTB_QUATTROCENTO
+
+        # Device Information
+        self._conversion_factor_biosignal: float = 5 / (2**16) / 150 * 1000
+        self._conversion_factor_auxiliary: float = 5 / (2**16) / 0.5
+
+        # Connection Parameters
+        self._interface: QTcpSocket = QTcpSocket()

biosignal_device_interface/gui/device_template_widgets/__init__.py

@@ -0,0 +1,6 @@
+# OTB Devices
+from biosignal_device_interface.gui.device_template_widgets.otb import (
+    MuoviWidget,
+    MuoviPlusWidget,
+    QuattrocentoLightWidget,
+)

biosignal_device_interface/gui/device_template_widgets/all_devices_widget.py

@@ -0,0 +1,39 @@
+"""
+Template for the QWidget that enables the user to interact with all available devices.
+Developer: Dominik I. Braun
+Contact: dome.braun@fau.de
+Last Update: 2024-06-05
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Dict
+
+from biosignal_device_interface.gui.device_template_widgets.core.base_multiple_devices_widget import (
+    BaseMultipleDevicesWidget,
+)
+from biosignal_device_interface.constants.devices.core.base_device_constants import (
+    DeviceType,
+)
+from biosignal_device_interface.gui.device_template_widgets import (
+    MuoviPlusWidget,
+    MuoviWidget,
+    QuattrocentoLightWidget,
+)
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QWidget, QMainWindow
+    from biosignal_device_interface.gui.device_template_widgets.core.base_device_widget import (
+        BaseDeviceWidget,
+    )
+
+
+class AllDevicesWidget(BaseMultipleDevicesWidget):
+    def __init__(self, parent: QWidget | QMainWindow | None = None):
+        super().__init__(parent)
+
+        self._device_selection: Dict[DeviceType, BaseDeviceWidget] = {
+            DeviceType.OTB_QUATTROCENTO_LIGHT: QuattrocentoLightWidget(self),
+            DeviceType.OTB_MUOVI: MuoviWidget(self),
+            DeviceType.OTB_MUOVI_PLUS: MuoviPlusWidget(self),
+        }
+        self._set_devices(self._device_selection)

biosignal_device_interface/gui/device_template_widgets/core/base_device_widget.py

@@ -0,0 +1,121 @@
+"""
+Base Device class for real-time interfaces to hardware devices.
+Developer: Dominik I. Braun
+Contact: dome.braun@fau.de
+Last Update: 2024-06-05
+"""
+
+# Python Libraries
+from __future__ import annotations
+from typing import TYPE_CHECKING, Union, Dict
+from abc import abstractmethod
+from PySide6.QtWidgets import QWidget, QMainWindow
+from PySide6.QtGui import QCloseEvent
+from PySide6.QtCore import Signal
+import numpy as np
+
+# Import Devices
+from biosignal_device_interface.devices.core.base_device import BaseDevice
+
+if TYPE_CHECKING:
+    from enum import Enum
+
+
+class BaseDeviceWidget(QWidget):
+    # Signals
+    data_arrived: Signal = Signal(np.ndarray)
+    biosignal_data_arrived: Signal = Signal(np.ndarray)
+    auxiliary_data_arrived: Signal = Signal(np.ndarray)
+    connect_toggled: Signal = Signal(bool)
+    configure_toggled: Signal = Signal(bool)
+    stream_toggled: Signal = Signal(bool)
+
+    def __init__(self, parent: QWidget | QMainWindow | None = None):
+        super().__init__(parent)
+
+        self.parent_widget: QWidget | QMainWindow | None = parent
+
+        # Device Setup
+        self.device: BaseDevice | None = None
+        self._device_params: Dict[str, Union[str, int, float]] = {}
+
+        # GUI setup
+        self.ui: object = None
+
+    @abstractmethod
+    def _toggle_connection(self) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _connection_toggled(self, is_connected: bool) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _toggle_configuration(self) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _configuration_toggled(self, is_configured: bool) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _toggle_configuration_group_boxes(self) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _toggle_stream(self) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _stream_toggled(self, is_streaming: bool) -> None:
+        """ """
+        self.stream_toggled.emit(is_streaming)
+
+    @abstractmethod
+    def _initialize_device_params(self) -> None:
+        """ """
+        pass
+
+    @abstractmethod
+    def _initialize_ui(self) -> None:
+        """ """
+        pass
+
+    def _set_device(self, device: BaseDevice) -> None:
+        """ """
+        # Device Setup
+        self.device: BaseDevice = device
+        self._initialize_device_params()
+        self._set_signals()
+        self._initialize_ui()
+
+    def _set_signals(self) -> None:
+        """ """
+        self.device.data_available.connect(self.data_arrived.emit)
+        self.device.biosignal_data_available.connect(self.biosignal_data_arrived.emit)
+        self.device.auxiliary_data_available.connect(self.auxiliary_data_arrived.emit)
+
+    def get_device_information(self) -> Dict[str, Enum | int | float | str]:
+        """
+        Gets the current configuration of the device.
+
+        Returns:
+            Dict[str, Enum | int | float | str]:
+                Dictionary that holds information about the
+                current device configuration and status.
+        """
+        return self.device.get_device_information()
+
+    def disconnect_device(self) -> None:
+        """ """
+        if self.device._is_connected or self.device._is_streaming:
+            self.device.toggle_connection()
+
+    def closeEvent(self, event: QCloseEvent) -> None:
+        self.disconnect_device()