explorepy 4.3.0__tar.gz → 4.5.0__tar.gz

{explorepy-4.3.0 → explorepy-4.5.0}/CHANGELOG.rst

@@ -1,6 +1,17 @@
 
 Changelog
 =========
+4.5.0 (5.6.2025)
+------------------
+* Live impedance
+* Allow pushing preprocessed data to lab streaming layer
+* Support new FW version
+
+4.3.1 (17.9.2025)
+------------------
+* Bugfix for 32 channel impedance recording
+* Bugfix for BLE connection drop
+* Update binary converter
 
 4.3.0 (10.9.2025)
 ------------------

{explorepy-4.3.0 → explorepy-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: explorepy
-Version: 4.3.0
+Version: 4.5.0
 Author-email: MentaLab Hub <support@mentab.org>
 License: MIT
 Project-URL: Homepage, https://github.com/Mentalab-hub/explorepy
@@ -18,14 +18,14 @@ Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Description-Content-Type: text/markdown
+Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: AUTHORS.rst
-Requires-Dist: numpy
-Requires-Dist: scipy
-Requires-Dist: pyEDFlib==0.1.38
+Requires-Dist: numpy==2.1.3
+Requires-Dist: scipy==1.17.1
+Requires-Dist: pyEDFlib==0.1.42
 Requires-Dist: click==7.1.2
-Requires-Dist: appdirs==1.4.3
+Requires-Dist: appdirs==1.4.4
 Requires-Dist: sentry_sdk==2.8.0
 Requires-Dist: mne
 Requires-Dist: eeglabio
@@ -33,7 +33,7 @@ Requires-Dist: pandas
 Requires-Dist: pyserial
 Requires-Dist: pyyaml
 Requires-Dist: bleak==0.22.3
-Requires-Dist: pylsl
+Requires-Dist: pylsl==1.18.2
 Requires-Dist: numba
 Provides-Extra: test
 Requires-Dist: pytest==6.2.5; extra == "test"
@@ -44,9 +44,8 @@ Requires-Dist: isort==5.10.1; extra == "test"
 Dynamic: license-file
 
 .. image:: https://raw.githubusercontent.com/Mentalab-hub/explorepy/master/docs/logo.jpg
-   :scale: 100 %
-   :align: left
-
+   :alt: Explorepy
+   :target: https://github.com/Mentalab-hub/explorepy
 
 .. start-badges
 
@@ -62,9 +61,9 @@ Dynamic: license-file
     :target: https://pypi.org/project/explorepy
 
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.3.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.5.0.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.3.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.5.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
@@ -84,10 +83,10 @@ Dynamic: license-file
 
 
 =========================
-``explorepy`` overview
+ExplorePy overview
 =========================
 
-``explorepy`` is an open-source Python API designed to collect and process ExG data using Mentalab's Explore device. Amongst other things, ``explorepy`` provides the following features:
+ExplorePy is an open-source Python API designed to collect and process ExG data using Mentalab's Explore device. Amongst other things, ExplorePy provides the following features:
 
 * Real-time streaming of ExG, orientation and environmental data.
 * Data recording in CSV and BDF+ formats.
@@ -106,7 +105,7 @@ Requirements
 
 Detailed installation instructions can be found on the `installation page <https://explorepy.readthedocs.io/en/latest/installation.html>`_.
 
-To install ``explorepy`` from PyPI run:
+To install ExplorePy from PyPI run:
 ::
 
     pip install explorepy
@@ -123,12 +122,14 @@ Get started
 
 CLI command
 -----------
-To check ``explorepy`` is running use:
+To check ExplorePy is running use:
 ::
+
     explorepy acquire -n Explore_XXXX
 
 For help, use:
 ::
+
     explorepy -h
 
 

{explorepy-4.3.0 → explorepy-4.5.0}/README.rst

@@ -1,7 +1,6 @@
 .. image:: https://raw.githubusercontent.com/Mentalab-hub/explorepy/master/docs/logo.jpg
-   :scale: 100 %
-   :align: left
-
+   :alt: Explorepy
+   :target: https://github.com/Mentalab-hub/explorepy
 
 .. start-badges
 
@@ -17,9 +16,9 @@
     :target: https://pypi.org/project/explorepy
 
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.3.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.5.0.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.3.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.5.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
@@ -39,10 +38,10 @@
 
 
 =========================
-``explorepy`` overview
+ExplorePy overview
 =========================
 
-``explorepy`` is an open-source Python API designed to collect and process ExG data using Mentalab's Explore device. Amongst other things, ``explorepy`` provides the following features:
+ExplorePy is an open-source Python API designed to collect and process ExG data using Mentalab's Explore device. Amongst other things, ExplorePy provides the following features:
 
 * Real-time streaming of ExG, orientation and environmental data.
 * Data recording in CSV and BDF+ formats.
@@ -61,7 +60,7 @@ Requirements
 
 Detailed installation instructions can be found on the `installation page <https://explorepy.readthedocs.io/en/latest/installation.html>`_.
 
-To install ``explorepy`` from PyPI run:
+To install ExplorePy from PyPI run:
 ::
 
     pip install explorepy
@@ -78,12 +77,14 @@ Get started
 
 CLI command
 -----------
-To check ``explorepy`` is running use:
+To check ExplorePy is running use:
 ::
+
     explorepy acquire -n Explore_XXXX
 
 For help, use:
 ::
+
     explorepy -h
 
 

{explorepy-4.3.0 → explorepy-4.5.0}/docs/conf.py

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

{explorepy-4.3.0 → explorepy-4.5.0}/docs/usage.rst

@@ -55,7 +55,7 @@ Connects to a device and records ExG and orientation data into two separate file
       -d, --duration <integer>        Recording duration in seconds
       --edf                           Write in EDF file
       --csv                           Write in csv file (default type)
-      --imp-mode                      Enable impedance mode with live monitoring
+      --imp-mode                      Enable impedance mode with real-time monitoring (CSV only)
       -h, --help                      Show this message and exit.
 
 
@@ -222,14 +222,13 @@ Recording
 You can record data in realtime to EDF (BDF+) or CSV files using:
 ::
     explore.record_data(file_name='test', duration=120, file_type='csv')
+This will record data in three separate files: "``test_ExG.csv``", "``test_ORN.csv``" and "``test_marker.csv``", which contain ExG data, orientation data (accelerometer, gyroscope, magnetometer) and event markers respectively. It is also possible to add arguments to overwrite files.
 
-To also record impedance data, use:
+Enable imp_mode argument to record impedance data as well:
 ::
     explore.record_data(file_name='test', duration=120, file_type='csv', imp_mode=True)
 
-This will record data in three separate files: "``test_ExG.csv``", "``test_ORN.csv``" and "``test_marker.csv``", which contain ExG data, orientation data (accelerometer, gyroscope, magnetometer) and event markers respectively. Add command arguments to overwrite files and set the duration of the recording (in seconds).
-::
-    explore.record_data(file_name='test', do_overwrite=True, file_type='csv', duration=120)
+.. note:: Impedance recording is only supported for CSV files!
 
 .. note:: To load EDF files, you can use `pyedflib <https://github.com/holgern/pyedflib>`_ or `mne <https://github.com/mne-tools/mne-python>`_ (for mne, you may need to change the file extension to ``bdf`` manually) in Python.
 

{explorepy-4.3.0 → explorepy-4.5.0}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend   = 'setuptools.build_meta'
 
 [project]
 name    = 'explorepy'
-version = "4.3.0"
+version = "4.5.0"
 license = { text = "MIT" }
-readme = { file = "README.rst", content-type = "text/markdown" }
+readme = { file = "README.rst", content-type = "text/x-rst"}
 authors = [
   { name = "MentaLab Hub", email = "support@mentab.org" },
 ]
@@ -29,11 +29,11 @@ classifiers = [
 ]
 
 dependencies = [
-    'numpy',
-    'scipy',
-    'pyEDFlib==0.1.38',
+    'numpy==2.1.3',
+    'scipy==1.17.1',
+    'pyEDFlib==0.1.42',
     'click==7.1.2',
-    'appdirs==1.4.3',
+    'appdirs==1.4.4',
     'sentry_sdk==2.8.0',
     'mne',
     'eeglabio',
@@ -41,7 +41,7 @@ dependencies = [
     'pyserial',
     'pyyaml',
     'bleak==0.22.3',
-    'pylsl',
+    'pylsl==1.18.2',
     'numba']
 
 [tool.setuptools]
@@ -60,3 +60,39 @@ test = [
 
 [project.scripts]
 explorepy = "explorepy.cli:cli"
+
+# bumpoversion config
+[tool.bumpversion]
+current_version = "4.5.0"
+commit = false
+tag = false
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "README.rst"
+search = "v{current_version}."
+replace = "v{new_version}."
+
+[[tool.bumpversion.files]]
+filename = "docs/conf.py"
+search = "version = release = '{current_version}'"
+replace = "version = release = '{new_version}'"
+
+[[tool.bumpversion.files]]
+filename = "src/explorepy/__init__.py"
+search = "__version__ = '{current_version}'"
+replace = "__version__ = '{new_version}'"
+
+[[tool.bumpversion.files]]
+filename = "installer/windows/installer.cfg"
+search = "explorepy=={current_version}"
+replace = "explorepy=={new_version}"
+
+[[tool.bumpversion.files]]
+filename = "installer/windows/installer.cfg"
+search = "version={current_version}"
+replace = "version={new_version}"

{explorepy-4.3.0 → explorepy-4.5.0}/src/explorepy/BLEClient.py

@@ -17,6 +17,7 @@ from bleak import (
 
 from explorepy._exceptions import (
     BleDisconnectionError,
+    BleDisconnectionFailedError,
     DeviceNotFoundError,
     UnexpectedConnectionError
 )
@@ -200,7 +201,22 @@ class BLEClient(BTClient):
         if self.notify_task:
             self.notify_task.cancel()
         self.read_event.set()
-        time.sleep(1)
+
+        min_time_to_wait = 0.5
+        max_time_to_wait = 5.
+        wait_start = time.time()
+        time_passed = 0.
+        if self.client is not None:
+            while self.client.is_connected:
+                time.sleep(0.1)
+                time_passed = time.time() - wait_start
+                if time_passed >= max_time_to_wait:
+                    raise BleDisconnectionFailedError(f"Bleak client still not reporting disconnected after waiting "
+                                                      f"{max_time_to_wait}.")
+        if time_passed < min_time_to_wait:
+            # Artificial delay to make the user think things are happening :)
+            time.sleep(min_time_to_wait - time_passed)
+
         self.stop_read_loop()
         self.ble_device = None
         self.buffer = Queue()

{explorepy-4.3.0 → explorepy-4.5.0}/src/explorepy/__init__.py

@@ -20,11 +20,11 @@ from .explore import Explore  # noqa
 
 
 __all__ = ["Explore", "command", "tools", "log_config"]
-__version__ = '4.3.0'
+__version__ = '4.5.0'
 
 this = sys.modules[__name__]
 # TODO appropriate library
-bt_interface_list = ['sdk', 'ble', 'mock', 'pyserial', 'usb']
+bt_interface_list = ['sdk', 'ble', 'mock', 'pyserial', 'usb', 'csv']
 this._bt_interface = 'ble'
 
 if not sys.version_info >= (3, 6):

{explorepy-4.3.0 → explorepy-4.5.0}/src/explorepy/_exceptions.py

@@ -55,6 +55,23 @@ class BleDisconnectionError(Exception):
     pass
 
 
+class BleDisconnectionFailedError(Exception):
+    """
+    Exception for client fails to achieve disconnected state
+    """
+    pass
+
+
+class ImpedanceModeActiveError(Exception):
+    """
+    Exception for ASR, raised when impedance is running
+    """
+
+    def __init__(self, message="ASR can not run because impedance mode is active.\n"
+                               "Please disable impedance and try again\n"):
+        super().__init__(message)
+
+
 class ExplorePyDeprecationError(Exception):
     def __init__(self, message="Explorepy support for legacy devices is deprecated.\n"
                                "Please install explorepy 3.2.1 from Github or use the following command from Anaconda "

{explorepy-4.3.0 → explorepy-4.5.0}/src/explorepy/cli.py

@@ -76,7 +76,7 @@ def acquire(name, address, duration):
 @click.option("--edf", 'file_type', flag_value='edf', help="Write in EDF file")
 @click.option("--csv", 'file_type', flag_value='csv', help="Write in csv file (default type)", default=True)
 @click.option("--imp-mode", is_flag=True, help="Enable impedance mode with live monitoring")
-@click.option("-nf", "--notch-freq", help="Notch frequency for impedance mode initialization", type=float, default=50.0)
+@click.option("-nf", "--notch-freq", help="Notch frequency for impedance mode initialization", type=float, default=None)
 @verify_inputs
 def record_data(address, name, filename, overwrite, duration, file_type, imp_mode, notch_freq):
     """Record data from Explore to a file"""

{explorepy-4.3.0 → explorepy-4.5.0}/src/explorepy/command.py

@@ -16,6 +16,7 @@ class CommandID(Enum):
     """Command ID enum class"""
     API2BCMD = b'\xA0'
     API4BCMD = b'\xB0'
+    API64BCMD = b'\xC0'
 
 
 class OpcodeID(Enum):
@@ -27,6 +28,7 @@ class OpcodeID(Enum):
     CMD_ZM_ENABLE = b'\xA7'
     CMD_SOFT_RESET = b'\xA8'
     CMD_TEST_SIG = b'\xAA'
+    CMD_SET_EMMC_TIME = b'\xAB'
 
 
 class DeviceConfiguration:
@@ -182,6 +184,19 @@ class Command4B(Command):
         """prints the appropriate info about the command. """
 
 
+class Command64B(Command):
+    """An abstract base class for Explore 40 Byte command data length packets"""
+
+    def __init__(self):
+        super().__init__()
+        self.pid = CommandID.API64BCMD
+        self.payload_length = int2bytearray(40, 2)
+
+    @abc.abstractmethod
+    def __str__(self):
+        """prints the appropriate info about the command. """
+
+
 class SetSPS(Command2B):
     """Set the sampling rate of ExG device"""
 
@@ -213,6 +228,34 @@ class SetSPS(Command2B):
         return "Set sampling rate command"
 
 
+class SetBinaryTime(Command64B):
+    def __init__(self):
+        super().__init__()
+        self.opcode = OpcodeID.CMD_SET_EMMC_TIME
+        from datetime import datetime
+        now = datetime.now()
+        if not (2020 < now.year < 2099):
+            raise ValueError(f"Unsupported year: {now.year}")
+        date_time = bytes(
+            [
+                now.year - 2000,
+                now.month,
+                now.day,
+                now.weekday(),
+                now.hour,
+                now.minute,
+                now.second,
+                1,
+                2,
+                3,
+            ]
+        )
+        self.param = date_time + bytes(41)
+
+    def __str__(self):
+        return "set time cmd"
+
+
 class MemoryFormat(Command2B):
     """Format device memory"""
 
@@ -282,7 +325,8 @@ class SetChTest(Command2B):
 
 COMMAND_CLASS_DICT = {
     CommandID.API2BCMD: Command2B,
-    CommandID.API4BCMD: Command4B
+    CommandID.API4BCMD: Command4B,
+    CommandID.API64BCMD: Command64B
 }
 
 

explorepy-4.5.0/src/explorepy/csv_client.py

@@ -0,0 +1,219 @@
+import os
+import time
+from enum import (
+    Enum,
+    auto
+)
+
+import numpy as np
+from pylsl import local_clock
+
+from explorepy.packet import (
+    BleImpedancePacket,
+    DeviceInfoBLE,
+    OrientationV2
+)
+
+
+class ClientState(Enum):
+    DISCONNECTED = auto()
+    CONNECTED = auto()
+    STREAMING = auto()
+    STOPPED = auto()
+
+
+class PacketSize(Enum):
+    EEG_8 = 40
+    EEG_32 = 112
+    ORN = 50
+    DEVICE_INFO = 38
+
+
+class CsvClient:
+    def __init__(self, channel_count, file_path: str = None):
+        if file_path is None:
+            self.file_name = "32channel_semidry_artefacts_ExG.csv"
+            file_path = os.path.join("/Users/sonjastefani/Documents/dev/explore-desktop/test-data/", self.file_name)
+        else:
+            self.file_name = os.path.split(file_path)[-1]
+
+        if not os.path.isfile(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        self.server = CsvServer(
+            channel_count=channel_count,
+            csv_path=file_path,
+            loop=True
+        )
+        self._state = ClientState.DISCONNECTED
+
+    def set_state(self, state: ClientState):
+        if not isinstance(state, ClientState):
+            raise ValueError("Invalid client state")
+        self._state = state
+
+    def get_state(self) -> ClientState:
+        return self._state
+
+    def connect(self):
+        if self._state != ClientState.DISCONNECTED:
+            return False
+        self.set_state(ClientState.CONNECTED)
+        return True
+
+    def disconnect(self):
+        self.set_state(ClientState.DISCONNECTED)
+        return True
+
+    def start_streaming(self):
+        if self._state != ClientState.CONNECTED:
+            raise RuntimeError(f"Cannot start streaming from state {self._state}")
+        self.set_state(ClientState.STREAMING)
+
+    def stop_streaming(self):
+        if self._state == ClientState.STREAMING:
+            self.set_state(ClientState.STOPPED)
+
+    def read(self):
+        if self._state != ClientState.STREAMING:
+            if self._state == ClientState.CONNECTED:
+                self.set_state(ClientState.STREAMING)
+                device_info_packet = DeviceInfoMock(timestamp=self.server.ts, payload=None)
+                device_info_packet.packet_size = PacketSize.DEVICE_INFO
+                device_info_packet.set_info(self.server.device_info)
+                return device_info_packet
+
+        self.server.tick += 1
+        if self.server.tick % 5 == 0:
+            orn_packet = OrientationMock(timestamp=self.server.ts, payload=None)
+            orn_packet.set_data(self.server.orn_value)
+            orn_packet.packet_size = PacketSize.ORN
+            return orn_packet
+
+        self.server.ts += self.server.time_period
+        sleep_time = self.server.ts - local_clock()
+        if sleep_time > 0:
+            time.sleep(sleep_time)
+        eeg_packet = BleImpedancePacket(timestamp=self.server.ts, payload=None)
+        try:
+            eeg_packet.data, eeg_packet.timestamp = self.server.read_sample()
+        except StopIteration:
+            self.set_state(ClientState.STOPPED)
+            return None
+        eeg_packet.packet_size = self.server.packet_size
+        return eeg_packet
+
+    def write(self, bytes):
+        pass
+
+
+class CsvServer:
+    def __init__(self, channel_count: int, csv_path: str, loop: bool = True):
+        if channel_count not in (8, 32):
+            raise ValueError("Only 8 or 32 channels supported")
+
+        self.channel_count = channel_count
+        self.loop = loop
+        self.csv_data = np.loadtxt(csv_path, delimiter=',', skiprows=1)  # skip row 0
+
+        self.csv_ts = self.csv_data[:, 0]
+        self.csv_data = self.csv_data[:, 1:]
+
+        if self.csv_data.shape[1] != channel_count:
+            print('######################', self.csv_data.shape)
+            raise ValueError(
+                f"CSV has {self.csv_data.shape[1]} columns, "
+                f"expected {channel_count}"
+            )
+
+        self.row_idx = 0
+        self.num_rows = self.csv_data.shape[0]
+        self.device_info_ble_32ch = {
+            'device_name': 'Explore_DABD',
+            'firmware_version': '9.6.9',
+            'adc_mask': [1] * 8,
+            'sampling_rate': 250,
+            'is_imp_mode': False,
+            'board_id': 'PCB_304_801p2_X',
+            'memory_info': 1,
+            'max_online_sps': 250,
+            'max_offline_sps': 2000
+        }
+
+        self.device_info_ble_8ch = {
+            'device_name': 'Explore_AAAQ',
+            'firmware_version': '7.6.9',
+            'adc_mask': [1] * 8,
+            'sampling_rate': 250,
+            'is_imp_mode': False,
+            'board_id': 'PCB_303_801E_XX',
+            'memory_info': 1,
+            'max_online_sps': 1000,
+            'max_offline_sps': 8000
+        }
+
+        self.device_info = (
+            self.device_info_ble_8ch
+            if channel_count == 8
+            else self.device_info_ble_32ch
+        )
+
+        self.fs = self.device_info['sampling_rate']
+        self.time_period = np.round(1 / self.fs, 3)
+        self.ts = local_clock()
+        self.tick = 0
+
+        self.packet_size = (
+            PacketSize.EEG_8 if channel_count == 8 else PacketSize.EEG_32
+        )
+
+        self.orn_value = [
+            5.002, -3.904, 1001.01, 420.0, -70.0, 210.0,
+            103.36, 804.08, -532.0, -0.0023,
+            -0.0028, 0.0371, 0.9993
+        ]
+
+    def read_sample(self):
+        if self.row_idx >= self.num_rows:
+            if not self.loop:
+                raise StopIteration("End of CSV reached")
+            self.row_idx = 0
+
+        ts = self.csv_ts[self.row_idx]
+        sample = self.csv_data[self.row_idx]
+        self.row_idx += 1
+
+        return sample.reshape(self.channel_count, 1), ts
+
+    def read_device_info(self):
+        return self.device_info
+
+
+class DeviceInfoMock(DeviceInfoBLE):
+    def __init__(self, timestamp, payload, time_offset=0):
+        self.timestamp = timestamp
+
+    def _convert(self, bin_data):
+        pass
+
+    def set_info(self, info):
+        self.info = info
+
+    def get_info(self):
+        return self.info
+
+
+class OrientationMock(OrientationV2):
+    """Orientation data packet"""
+
+    def __init__(self, timestamp, payload, time_offset=0):
+        self.timestamp = timestamp
+
+    def _convert(self, bin_data):
+        pass
+
+    def get_data(self, srate=None):
+        return [self.timestamp], self.data
+
+    def set_data(self, data):
+        self.data = data