Merge pull request #374 from Mentalab-hub/develop

Release 4.1.0

Author: salman2135

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 4.0.0
+current_version = 4.1.0
 commit = False
 tag = False
 

CHANGELOG.rst

@@ -2,6 +2,13 @@
 Changelog
 =========
 
+4.1.0 (31.3.2025)
+------------------
+* Improve bluetooth connection UX
+* Add more data in IMU packet
+* Improve USB streaming
+
+
 4.0.0 (14.3.2025)
 ------------------
 * Deprecate support for Explore legacy devices

README.rst

@@ -17,9 +17,9 @@
     :target: https://pypi.org/project/explorepy
 
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.0.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.1.0.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.0.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.1.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg

docs/conf.py

@@ -28,7 +28,7 @@
 year = '2018-2025'
 author = 'Mentalab GmbH.'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '4.0.0'
+version = release = '4.1.0'
 pygments_style = 'trac'
 templates_path = ['.']
 extlinks = {

examples/markers_examples/send_8_bit_marker_during_connection_example.py

@@ -1,12 +1,12 @@
 import explorepy
 import time
 
-# for independent markers to be stored only in binary file, we only need to instantiate Explore class!
+# for independent markers, we only need to instantiate Explore class!
 exp_device = explorepy.Explore()
 
 n_markers = 20
 interval = 2
 for i in range(n_markers):
         exp_device.send_8_bit_trigger(i)
-        time.sleep(2)
+        time.sleep(interval)
 

examples/markers_examples/send_8_bit_marker_independently.py

@@ -1,6 +1,6 @@
 [Application]
 name=MentaLab ExplorePy
-version=4.0.0
+version=4.1.0
 entry_point=explorepy.cli:cli
 console=true
 icon=mentalab.ico
@@ -26,7 +26,7 @@ pypi_wheels =
     decorator==5.1.1
     distlib==0.3.7
     eeglabio==0.0.2.post4
-    explorepy==4.0.0
+    explorepy==4.1.0
     fonttools==4.42.1
     idna==3.4
     importlib-resources==6.0.1

installer/windows/installer.cfg

@@ -4,7 +4,7 @@ build-backend   = 'setuptools.build_meta'
 
 [project]
 name    = 'explorepy'
-version = "4.0.0"
+version = "4.1.0"
 license = { text = "MIT" }
 readme = { file = "README.rst", content-type = "text/markdown" }
 authors = [
@@ -25,7 +25,6 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX :: Linux",
     "Topic :: Scientific/Engineering :: Information Analysis",
-    "Topic :: Scientific/Engineering :: Neuroscience App",
     "Topic :: Software Development :: Libraries :: Python Modules"
 ]
 

pyproject.toml

@@ -16,7 +16,8 @@
 
 from explorepy._exceptions import (
     BleDisconnectionError,
-    DeviceNotFoundError
+    DeviceNotFoundError,
+    UnexpectedConnectionError
 )
 from explorepy.BTClient import BTClient
 
@@ -108,7 +109,10 @@ def connect(self):
         self.notification_thread = threading.Thread(target=self.start_read_loop, daemon=True)
         self.notification_thread.start()
         print('waiting for BLE device to show up..')
-        self.result_queue.get()
+        ret = self.result_queue.get()
+        if not ret:
+            logger.error("Got exception in read loop")
+            raise UnexpectedConnectionError("Could not connect to the device")
 
         if self.ble_device is None:
             logger.info('No device found!!')
@@ -122,13 +126,16 @@ def connect(self):
     def start_read_loop(self):
         try:
             asyncio.new_event_loop().run_until_complete(self.ble_manager())
+            self.result_queue.put(True)
         except RuntimeError as error:
             logger.info('Shutting down BLE stream loop with error {}'.format(error))
         except asyncio.exceptions.CancelledError as error:
             logger.debug('asyncio.exceptions.CancelledError from BLE stream thread {}'.format(error))
         except BleDisconnectionError as error:
             print('Got error as {}'.format(error))
             raise error
+        finally:
+            self.result_queue.put(False)
 
     def stop_read_loop(self):
         logger.debug('Stopping BLE stream loop')
@@ -152,6 +159,7 @@ async def ble_manager(self):
             raise error
         except Exception as error:
             logger.debug('Got an BLE exception with error {}'.format(error))
+            raise error
 
     async def _discover_device(self):
         if self.mac_address:

src/explorepy/BLEClient.py

@@ -20,7 +20,7 @@
 
 
 __all__ = ["Explore", "command", "tools", "log_config"]
-__version__ = '4.0.0'
+__version__ = '4.1.0'
 
 this = sys.modules[__name__]
 # TODO appropriate library

src/explorepy/__init__.py

@@ -6,6 +6,13 @@
 import sys
 
 
+class UnexpectedConnectionError(ConnectionError):
+    """
+    Generic exception thrown if an unexpected error occurs during connection
+    """
+    pass
+
+
 class InputError(Exception):
     """
     User input exception

src/explorepy/_exceptions.py

@@ -45,6 +45,7 @@
     create_marker_recorder,
     create_meta_recorder,
     create_orn_recorder,
+    get_orn_chan_len,
     local_clock,
     setup_usb_marker_port
 )
@@ -187,7 +188,8 @@ def record_data(
                                                     exg_ch=exg_ch_names)
         self.recorders['orn'] = create_orn_recorder(filename=orn_out_file,
                                                     file_type=file_type,
-                                                    do_overwrite=do_overwrite)
+                                                    do_overwrite=do_overwrite,
+                                                    n_chan=get_orn_chan_len(self.stream_processor.device_info))
 
         #  TODO: make sure older timestamp in meta file was not used in any other software!
         if file_type == 'csv':
@@ -323,7 +325,8 @@ def convert_bin(self, bin_file, out_dir='', file_type='edf', do_overwrite=False,
                                                     do_overwrite=do_overwrite, batch_mode=True)
         self.recorders['orn'] = create_orn_recorder(filename=orn_out_file,
                                                     file_type=self.recorders['file_type'],
-                                                    do_overwrite=do_overwrite, batch_mode=True)
+                                                    do_overwrite=do_overwrite, batch_mode=True,
+                                                    n_chan=get_orn_chan_len(self.stream_processor.device_info))
 
         if self.recorders['file_type'] == 'csv':
             self.recorders['marker'] = create_marker_recorder(
@@ -424,10 +427,10 @@ def stream_progress_handler(progress):
             logger.info('Conversion process terminated.')
 
     def push2lsl(self, duration=None, block=False):
-        r"""Push samples to two lsl streams (ExG and ORN streams)
+        """Push samples to three lsl streams (ExG, Marker and ORN streams)
 
         Args:
-            duration (float): duration of data acquiring (if None it streams for one hour).
+            duration (float): duration of data acquiring (if None it streams for three hours).
             block (bool): blocking mode
         """
         self._check_connection()
@@ -484,7 +487,7 @@ def set_marker(self, marker_string, time_lsl=None):
     def send_8_bit_trigger(self, eight_bit_value):
         eight_bit_value = eight_bit_value % 256
         trigger_id = 0xAB
-        cmd = [trigger_id, eight_bit_value, 1, 2, 3, 4, 5, 6, 7, 8, 0xDE, 0xAD, 0xBE, 0xEF]
+        cmd = [trigger_id, eight_bit_value, 1, 2, 3, 4, 5, 6, 7, 8, 0xAF, 0xBE, 0xAD, 0xDE]
         explore_port = setup_usb_marker_port()
         explore_port.write(bytearray(cmd))
         explore_port.close()

src/explorepy/explore.py

@@ -19,7 +19,8 @@
 class PACKET_ID(IntEnum):
     """Packet ID enum"""
 
-    ORN = 13
+    ORN_V1 = 13
+    ORN_V2 = 14
     ENV = 19
     TS = 27
     DISCONNECT = 111
@@ -332,13 +333,18 @@ def __init__(self, timestamp, payload, time_offset=0):
 
 
 class Orientation(Packet):
-    """Orientation data packet"""
-
     def __init__(self, timestamp, payload, time_offset=0):
         super().__init__(timestamp, payload, time_offset)
         self.theta = None
         self.rot_axis = None
 
+
+class OrientationV1(Orientation):
+    """Orientation data packet"""
+
+    def __init__(self, timestamp, payload, time_offset=0):
+        super().__init__(timestamp, payload, time_offset)
+
     def _convert(self, bin_data):
         data = np.copy(
             np.frombuffer(bin_data, dtype=np.dtype(
@@ -372,6 +378,51 @@ def compute_angle(self, matrix=None):
         return [theta, rot_axis]
 
 
+class OrientationV2(Orientation):
+    """Orientation data packet"""
+
+    def __init__(self, timestamp, payload, time_offset=0):
+        self.quat = None
+        super().__init__(timestamp, payload, time_offset)
+
+    def _convert(self, bin_data):
+        data = np.copy(
+            np.frombuffer(bin_data[0:18], dtype=np.dtype(
+                np.int16).newbyteorder("<"))).astype(float)
+        self.acc = 0.122 * data[0:3]  # Unit [mg/LSB]
+        self.gyro = 70 * data[3:6]  # Unit [mdps/LSB]
+        self.mag = 1.52 * np.multiply(data[6:9], np.array(
+            [-1, 1, 1]))  # Unit [mgauss/LSB]
+        data = np.copy(
+            np.frombuffer(bin_data[18:34], dtype=np.dtype(
+                np.float32).newbyteorder("<"))).astype(float)
+        self.quat = data
+        self.theta = None
+        self.rot_axis = None
+
+    def __str__(self):
+        return "Acc: " + str(self.acc) + "\tGyro: " + str(self.gyro) + "\tMag: " + str(
+            self.mag) + "\tQuat: " + str(self.quat)
+
+    def get_data(self, srate=None):
+        """Get orientation timestamp and data"""
+        return [self.timestamp
+                ], self.acc.tolist() + self.gyro.tolist() + self.mag.tolist() + self.quat.tolist()
+
+    def compute_angle(self, matrix=None):
+        """Compute physical angle"""
+        trace = matrix[0][0] + matrix[1][1] + matrix[2][2]
+        theta = np.arccos((trace - 1) / 2) * 57.2958
+        nx = matrix[2][1] - matrix[1][2]
+        ny = matrix[0][2] - matrix[2][0]
+        nz = matrix[1][0] - matrix[0][1]
+        rot_axis = 1 / np.sqrt(
+            (3 - trace) * (1 + trace)) * np.array([nx, ny, nz])
+        self.theta = theta
+        self.rot_axis = rot_axis
+        return [theta, rot_axis]
+
+
 class Environment(Packet):
     """Environment data packet"""
 
@@ -723,7 +774,8 @@ def __str__(self):
 
 
 PACKET_CLASS_DICT = {
-    PACKET_ID.ORN: Orientation,
+    PACKET_ID.ORN_V1: OrientationV1,
+    PACKET_ID.ORN_V2: OrientationV2,
     PACKET_ID.ENV: Environment,
     PACKET_ID.TS: TimeStamp,
     PACKET_ID.DISCONNECT: Disconnect,