explorepy 4.2.0__tar.gz → 4.3.1__tar.gz

{explorepy-4.2.0 → explorepy-4.3.1}/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 4.2.0
+current_version = 4.3.1
 commit = False
 tag = False
 

{explorepy-4.2.0 → explorepy-4.3.1}/CHANGELOG.rst

@@ -2,6 +2,19 @@
 Changelog
 =========
 
+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)
+------------------
+* Live impedance acquisition and recording
+* Improve parser efficiency
+* Bugfix for Linux release
+* Refactor codebase
+
 4.2.0 (15.7.2025)
 ------------------
 * Add ExplorePy and Arduino interfacing example

{explorepy-4.2.0 → explorepy-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: explorepy
-Version: 4.2.0
+Version: 4.3.1
 Author-email: MentaLab Hub <support@mentab.org>
 License: MIT
 Project-URL: Homepage, https://github.com/Mentalab-hub/explorepy
@@ -62,9 +62,9 @@ Dynamic: license-file
     :target: https://pypi.org/project/explorepy
 
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.2.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.3.1.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.2.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.3.1...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg

{explorepy-4.2.0 → explorepy-4.3.1}/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.2.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.3.1.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.2.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.3.1...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg

{explorepy-4.2.0 → explorepy-4.3.1}/docs/conf.py

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

{explorepy-4.2.0 → explorepy-4.3.1}/docs/usage.rst

@@ -55,6 +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 real-time monitoring (CSV only)
       -h, --help                      Show this message and exit.
 
 
@@ -221,10 +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.
 
-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).
+Enable imp_mode argument to record impedance data as well:
 ::
-    explore.record_data(file_name='test', do_overwrite=True, file_type='csv', duration=120)
+    explore.record_data(file_name='test', duration=120, file_type='csv', imp_mode=True)
+
+.. 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.
 
@@ -376,34 +380,100 @@ Impedance data acquisition in real-time
 """""""""""""""""""""""""""""""""""""""
 ::
 
-    # An example code for impedance data acquisition from Explore device
-
+    import argparse
+    import csv
     import time
+
+    import numpy as np
+    import pandas as pd
+    import matplotlib.pyplot as plt
+    from scipy import signal
+
     import explorepy
     from explorepy.stream_processor import TOPICS
 
 
-    def handle_imp(packet):
-        """A function that receives impedance packet values"""
-        imp_values = packet.get_impedances()
-        print(imp_values)
+    # ----------------------------- Argument Parsing ----------------------------- #
+    parser = argparse.ArgumentParser(description="Acquire and filter impedance-mode ExG data from an Explore device.")
+    parser.add_argument("--device-name", required=True, help="Name of the Explore device (e.g., Explore_AAXX)")
+    args = parser.parse_args()
+
+
+    # ----------------------------- Configuration ----------------------------- #
+    FS = 250  # Sampling rate in Hz
+    CHANNEL_LABELS = [f"ch{i}" for i in range(1, 33)]
+    OUTPUT_FILENAME = "exg_data_imp_mode.csv"
+    RECORD_SECONDS = 40
+
+
+    # ----------------------------- CSV Setup ----------------------------- #
+    csv_file = open(OUTPUT_FILENAME, 'w', newline='\n')
+    csv_writer = csv.writer(csv_file, delimiter=",")
+    csv_writer.writerow(['Timestamp'] + CHANNEL_LABELS[:8])  # Log only first 8 channels
+
 
+    # ----------------------------- Packet Handlers ----------------------------- #
+    def handle_exg_packet(packet):
+        """Callback to handle incoming ExG data packets."""
+        timestamps, signals = packet.get_data(FS)
+        data = np.concatenate((np.array(timestamps)[:, np.newaxis].T, np.array(signals)), axis=0)
+        np.savetxt(csv_file, np.round(data.T, 4), fmt='%4f', delimiter=',')
 
-    exp_device = explorepy.Explore()
 
-    # Connect to the Explore device using device bluetooth name or mac address
-    exp_device.connect('Explore_XXXX')
+    def handle_impedance_packet(packet):
+        """Callback to handle incoming impedance packets."""
+        impedance_values = packet.get_impedances()
+        print("Impedance:", impedance_values)
 
-    exp_device.stream_processor.subscribe(callback=handle_imp, topic=TOPICS.imp)
 
-    # enable impedance mode
-    exp_device.stream_processor.imp_initialize(notch_freq=50)
+    # ----------------------------- Device Initialization ----------------------------- #
+    device = explorepy.Explore()
+    device.connect(args.device_name)
+    device.stream_processor.subscribe(callback=handle_impedance_packet, topic=TOPICS.imp)
+    device.stream_processor.subscribe(callback=handle_exg_packet, topic=TOPICS.raw_ExG)
+    device.stream_processor.imp_initialize(notch_freq=50)
 
-    count = 0
-    while count < 15:
+
+    # ----------------------------- Data Acquisition Loop ----------------------------- #
+    for _ in range(RECORD_SECONDS):
         time.sleep(1)
-        count += 1
 
-    exp_device.stream_processor.disable_imp()
-    exp_device.stream_processor.unsubscribe(callback=handle_imp, topic=TOPICS.imp)
+
+    # ----------------------------- Cleanup ----------------------------- #
+    device.stream_processor.disable_imp()
+    device.stream_processor.unsubscribe(callback=handle_impedance_packet, topic=TOPICS.imp)
+    device.stream_processor.unsubscribe(callback=handle_exg_packet, topic=TOPICS.raw_ExG)
+    csv_file.close()
+
+
+    # ----------------------------- Signal Processing ----------------------------- #
+    def apply_bandpass_filter(signal_data, low_freq, high_freq, fs, order=3):
+        """Apply a Butterworth bandpass filter to the signal."""
+        b, a = signal.butter(order, [low_freq / fs, high_freq / fs], btype='bandpass')
+        return signal.filtfilt(b, a, signal_data)
+
+
+    def apply_notch_filter(signal_data, fs, freq=50, quality_factor=30.0):
+        """Apply a notch filter at the specified frequency."""
+        b, a = signal.iirnotch(freq, quality_factor, fs)
+        return signal.filtfilt(b, a, signal_data)
+
+
+    # ----------------------------- Load and Filter Data ----------------------------- #
+    df = pd.read_csv(OUTPUT_FILENAME, delimiter=',', dtype=np.float64)
+    raw_ch1 = df['ch1']
+    filtered = apply_notch_filter(raw_ch1, FS, freq=62.5)
+    filtered = apply_notch_filter(filtered, FS, freq=50)
+    filtered = apply_bandpass_filter(filtered, low_freq=0.5, high_freq=30, fs=FS)
+
+
+    # ----------------------------- Plot Filtered Signal ----------------------------- #
+    plt.figure(figsize=(10, 4))
+    plt.plot(df['Timestamp'], filtered, label='Filtered ch1')
+    plt.xlabel("Time (s)")
+    plt.ylabel("Amplitude (µV)")
+    plt.title("Filtered EEG Signal - Channel 1")
+    plt.grid(True)
+    plt.tight_layout()
+    plt.show()
 

{explorepy-4.2.0 → explorepy-4.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend   = 'setuptools.build_meta'
 
 [project]
 name    = 'explorepy'
-version = "4.2.0"
+version = "4.3.1"
 license = { text = "MIT" }
 readme = { file = "README.rst", content-type = "text/markdown" }
 authors = [

{explorepy-4.2.0 → explorepy-4.3.1}/src/explorepy/BLEClient.py

@@ -1,6 +1,7 @@
 import asyncio
 import atexit
 import logging
+import os
 import threading
 import time
 from queue import (
@@ -189,16 +190,20 @@ class BLEClient(BTClient):
     def disconnect(self):
         """Disconnect from the device"""
         self.is_connected = False
-        self.notify_task.cancel()
+        if os.name != 'nt':
+            if self.client and self.client.is_connected:
+                try:
+                    asyncio.run(self.client.stop_notify(self.eeg_tx_char_uuid))
+                except RuntimeError:
+                    # nothing to do here, this works even though there is an exception
+                    pass
+        if self.notify_task:
+            self.notify_task.cancel()
         self.read_event.set()
         time.sleep(1)
         self.stop_read_loop()
         self.ble_device = None
         self.buffer = Queue()
-        logger.info('ExplorePy disconnecting from device')
-
-    def _find_mac_address(self):
-        raise NotImplementedError
 
     def read(self, n_bytes):
         """Read n_bytes from the socket
@@ -221,7 +226,8 @@ class BLEClient(BTClient):
                 raise ConnectionAbortedError('Error reading data from BLE stream, too many bytes requested')
             return ret
         except Empty:
-            raise ConnectionAbortedError
+            if self.is_connected:
+                raise ConnectionAbortedError
         except Exception as error:
             logger.error('Unknown error reading data from BLE stream, error is {}'.format(error))
             raise ConnectionAbortedError(str(error))

{explorepy-4.2.0 → explorepy-4.3.1}/src/explorepy/BTClient.py

@@ -12,7 +12,6 @@ class BTClient(abc.ABC):
         self.mac_address = mac_address
         self.device_name = device_name
         self.bt_serial_port_manager = None
-        self.device_manager = None
 
     @abc.abstractmethod
     def connect(self):
@@ -34,10 +33,6 @@ class BTClient(abc.ABC):
     def disconnect(self):
         """Disconnect from the device"""
 
-    @abc.abstractmethod
-    def _find_mac_address(self):
-        pass
-
     @abc.abstractmethod
     def read(self, n_bytes):
         """Read n_bytes from the socket
@@ -56,7 +51,3 @@ class BTClient(abc.ABC):
         Args:
             data (bytearray): Data to be sent
         """
-
-    @staticmethod
-    def _check_mac_address(device_name, mac_address):
-        return (device_name[-4:-2] == mac_address[-5:-3]) and (device_name[-2:] == mac_address[-2:])

{explorepy-4.2.0 → explorepy-4.3.1}/src/explorepy/__init__.py

@@ -20,7 +20,7 @@ from .explore import Explore  # noqa
 
 
 __all__ = ["Explore", "command", "tools", "log_config"]
-__version__ = '4.2.0'
+__version__ = '4.3.1'
 
 this = sys.modules[__name__]
 # TODO appropriate library

{explorepy-4.2.0 → explorepy-4.3.1}/src/explorepy/cli.py

@@ -12,8 +12,6 @@ import explorepy
 CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
 logger = logging.getLogger(__name__)
 
-default_bt_backend = explorepy.get_bt_interface()
-
 
 @click.group(context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
 @click.option("--version", "-V", help="Print explorepy version", is_flag=True)
@@ -77,13 +75,22 @@ def acquire(name, address, duration):
 @click.option("-d", "--duration", type=int, help="Recording duration in seconds", metavar="<integer>")
 @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=None)
 @verify_inputs
-def record_data(address, name, filename, overwrite, duration, file_type):
+def record_data(address, name, filename, overwrite, duration, file_type, imp_mode, notch_freq):
     """Record data from Explore to a file"""
     explore = explorepy.explore.Explore()
     explore.connect(mac_address=address, device_name=name)
-    explore.record_data(file_name=filename, file_type=file_type,
-                        do_overwrite=overwrite, duration=duration, block=True)
+    explore.record_data(
+        file_name=filename,
+        file_type=file_type,
+        do_overwrite=overwrite,
+        duration=duration,
+        imp_mode=imp_mode,
+        notch_freq=notch_freq,
+        block=True
+    )
 
 
 @cli.command()
@@ -153,17 +160,3 @@ def soft_reset(address, name):
     explore = explorepy.explore.Explore()
     explore.connect(mac_address=address, device_name=name)
     explore.reset_soft()
-
-
-@cli.command()
-@click.option("--address", "-a", type=str, help="Explore device's MAC address")
-@click.option("--name", "-n", type=str, help="Name of the device")
-@click.option("-m", "--channel-mask", type=str, required=True,
-              help="Channel mask, it should be a binary string containing 1 and 0, "
-                   "representing the mask (LSB is channel 1).")
-@verify_inputs
-def set_channels(address, name, channel_mask):
-    """Mask the channels of the Explore device"""
-    explore = explorepy.explore.Explore()
-    explore.connect(mac_address=address, device_name=name)
-    explore.set_channels(channel_mask)

{explorepy-4.2.0 → explorepy-4.3.1}/src/explorepy/command.py

@@ -23,23 +23,12 @@ class OpcodeID(Enum):
     CMD_SPS_SET = b'\xA1'
     CMD_CH_SET = b'\xA2'
     CMD_MEM_FORMAT = b'\xA3'
-    CMD_REC_TIME_SET = b'\xB1'
-    CMD_MODULE_DISABLE = b'\xA4'
-    CMD_MODULE_ENABLE = b'\xA5'
     CMD_ZM_DISABLE = b'\xA6'
     CMD_ZM_ENABLE = b'\xA7'
     CMD_SOFT_RESET = b'\xA8'
     CMD_TEST_SIG = b'\xAA'
 
 
-class Result(Enum):
-    """Results of the command execution"""
-    API_CMD_SUCCESSFUL = b'\x01'
-    API_CMD_ILLEGAL = b'\x02'
-    API_CMD_FAILED = b'\x00'
-    API_CMD_NA = b'\xFF'
-
-
 class DeviceConfiguration:
     """Device Configuration Class"""
 
@@ -52,10 +41,6 @@ class DeviceConfiguration:
         self._last_ack_message = None
         self._last_status_message = None
 
-    def get_device_info(self):
-        """Get device information including adc mask, sampling rate and firmware version."""
-        raise NotImplementedError
-
     def change_setting(self, command):
         """Change the settings of the device based on the input command
 
@@ -147,8 +132,6 @@ class Command:
         self.opcode = None
         self.param = None
         self.fletcher = b'\xaf\xbe\xad\xde'
-
-        self.delivery_state = None
         self.result = None
 
     def translate(self):
@@ -266,26 +249,6 @@ class ZMeasurementEnable(Command2B):
         return "Impedance measurement enable command"
 
 
-class SetCh(Command2B):
-    """Change channel mask command"""
-
-    def __init__(self, ch_mask):
-        """
-
-        Args:
-            ch_mask (int): ExG channel mask. It should be integers between 1 and 255.
-        """
-        super().__init__()
-        self.opcode = OpcodeID.CMD_CH_SET
-        if 1 <= ch_mask <= 255:
-            self.param = bytes([ch_mask])
-        else:
-            raise ValueError("Invalid input")
-
-    def __str__(self):
-        return "Channel set command"
-
-
 class SoftReset(Command2B):
     """Reset the setting of the device."""