explorepy 4.1.0__tar.gz → 4.2.0__tar.gz

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

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

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

@@ -2,6 +2,15 @@
 Changelog
 =========
 
+4.2.0 (15.7.2025)
+------------------
+* Add ExplorePy and Arduino interfacing example
+* Add fieldtrip integration example
+* Add live exg and impedance acquisition example
+* Update MNE integration
+* Remove deprecated functions
+* Update documentation
+
 4.1.0 (31.3.2025)
 ------------------
 * Improve bluetooth connection UX

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: explorepy
-Version: 4.1.0
+Version: 4.2.0
 Author-email: MentaLab Hub <support@mentab.org>
 License: MIT
 Project-URL: Homepage, https://github.com/Mentalab-hub/explorepy
@@ -43,7 +43,7 @@ Requires-Dist: flake8==4.0.1; extra == "test"
 Requires-Dist: isort==5.10.1; extra == "test"
 Dynamic: license-file
 
-.. image:: logo.png
+.. image:: https://raw.githubusercontent.com/Mentalab-hub/explorepy/master/docs/logo.jpg
    :scale: 100 %
    :align: left
 
@@ -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.1.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.2.0.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.1.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.2.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
@@ -82,6 +82,7 @@ Dynamic: license-file
 
 .. end-badges
 
+
 =========================
 ``explorepy`` overview
 =========================
@@ -89,18 +90,11 @@ Dynamic: license-file
 ``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.
-* Real-time visualization of ExG, orientation and environmental data.
 * Data recording in CSV and BDF+ formats.
 * Integration with LabStreaming Layer.
 * Electrode impedance measurements.
 * Explore device configuration.
 
-Quick installation
-==================
-For Windows users, the best way to install ``explorepy`` is to download the latest ``explorepy`` version from the `release page <https://github.com/Mentalab-hub/explorepy/releases>`_. Please note that dependencies will install automatically from the release page.
-
-For other operating systems, or to build the package manually on Windows, please refer to the information below.
-
 
 Requirements
 ------------
@@ -121,7 +115,7 @@ To install ``explorepy`` from PyPI run:
 To install the latest development version (git must be installed before running this command):
 ::
 
-    pip install git+https://github.com/Mentalab-hub/explorepy
+    pip install git+https://github.com/Mentalab-hub/explorepy.git@develop
 
 
 Get started
@@ -147,17 +141,9 @@ In Python you can connect to the Explore device and print data using:
 
     import explorepy
     explorer = explorepy.Explore()
-    explorer.connect(device_name="Explore_XXXX")  # Put your device Bluetooth name
+    explorer.connect(device_name="Explore_XXXX")  # Use correct device ID here
     explorer.acquire()
 
-You can also visualize the data in real-time.
-
-::
-
-    import explorepy
-    explorer = explorepy.Explore()
-    explorer.connect(device_name="Explore_XXXX")  # Put your device Bluetooth name
-
 Documentation
 =============
 
@@ -185,7 +171,7 @@ Authors
 - `Sonja Stefani`_
 - `Alex Platt`_
 - `Andreas Gutsche`_
-- `Masooma Fazelian`_
+- `Masoome Fazelian`_
 - `Philipp Jakovleski`_
 - `Florian Sesser`_
 - `Sebastian Herberger`_
@@ -197,7 +183,7 @@ Authors
 .. _Sonja Stefani: https://github.com/SonjaSt
 .. _Alex Platt: https://github.com/Nujanauss
 .. _Andreas Gutsche: https://github.com/andyman410
-.. _Masooma Fazelian: https://github.com/fazelian
+.. _Masoome Fazelian: https://github.com/fazelian
 .. _Philipp Jakovleski: https://github.com/philippjak
 .. _Florian Sesser : https://github.com/hacklschorsch
 .. _Sebastian Herberger: https://github.com/SHerberger

{explorepy-4.1.0 → explorepy-4.2.0}/README.rst

@@ -1,4 +1,4 @@
-.. image:: logo.png
+.. image:: https://raw.githubusercontent.com/Mentalab-hub/explorepy/master/docs/logo.jpg
    :scale: 100 %
    :align: left
 
@@ -17,9 +17,9 @@
     :target: https://pypi.org/project/explorepy
 
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.1.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v4.2.0.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.1.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.2.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
@@ -37,6 +37,7 @@
 
 .. end-badges
 
+
 =========================
 ``explorepy`` overview
 =========================
@@ -44,18 +45,11 @@
 ``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.
-* Real-time visualization of ExG, orientation and environmental data.
 * Data recording in CSV and BDF+ formats.
 * Integration with LabStreaming Layer.
 * Electrode impedance measurements.
 * Explore device configuration.
 
-Quick installation
-==================
-For Windows users, the best way to install ``explorepy`` is to download the latest ``explorepy`` version from the `release page <https://github.com/Mentalab-hub/explorepy/releases>`_. Please note that dependencies will install automatically from the release page.
-
-For other operating systems, or to build the package manually on Windows, please refer to the information below.
-
 
 Requirements
 ------------
@@ -76,7 +70,7 @@ To install ``explorepy`` from PyPI run:
 To install the latest development version (git must be installed before running this command):
 ::
 
-    pip install git+https://github.com/Mentalab-hub/explorepy
+    pip install git+https://github.com/Mentalab-hub/explorepy.git@develop
 
 
 Get started
@@ -102,17 +96,9 @@ In Python you can connect to the Explore device and print data using:
 
     import explorepy
     explorer = explorepy.Explore()
-    explorer.connect(device_name="Explore_XXXX")  # Put your device Bluetooth name
+    explorer.connect(device_name="Explore_XXXX")  # Use correct device ID here
     explorer.acquire()
 
-You can also visualize the data in real-time.
-
-::
-
-    import explorepy
-    explorer = explorepy.Explore()
-    explorer.connect(device_name="Explore_XXXX")  # Put your device Bluetooth name
-
 Documentation
 =============
 
@@ -140,7 +126,7 @@ Authors
 - `Sonja Stefani`_
 - `Alex Platt`_
 - `Andreas Gutsche`_
-- `Masooma Fazelian`_
+- `Masoome Fazelian`_
 - `Philipp Jakovleski`_
 - `Florian Sesser`_
 - `Sebastian Herberger`_
@@ -152,7 +138,7 @@ Authors
 .. _Sonja Stefani: https://github.com/SonjaSt
 .. _Alex Platt: https://github.com/Nujanauss
 .. _Andreas Gutsche: https://github.com/andyman410
-.. _Masooma Fazelian: https://github.com/fazelian
+.. _Masoome Fazelian: https://github.com/fazelian
 .. _Philipp Jakovleski: https://github.com/philippjak
 .. _Florian Sesser : https://github.com/hacklschorsch
 .. _Sebastian Herberger: https://github.com/SHerberger

{explorepy-4.1.0 → explorepy-4.2.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.1.0'
+version = release = '4.2.0'
 pygments_style = 'trac'
 templates_path = ['.']
 extlinks = {

{explorepy-4.1.0 → explorepy-4.2.0}/docs/installation.rst

@@ -19,25 +19,12 @@ Recommended Requirements
 How to install
 --------------
 
-Option 1: Installing via installer file (basic)
-"""""""""""""""""""""""""""""""""""""""""""""""
-
-Windows and Mac
-^^^^^^^^^^^^^^^
-
-*This option is best for users who only intend to use functionalities offered by* ``explorepy`` *via a graphical user interface*
-
-For example, if you want to quickly visualize and record data and don't need the command line interface or to use it in your own Python script, use this option.
-
-If you intend to call ``explorepy`` from the command line or a Python script (e.g. from an experiment script), install ``explorepy`` via Anaconda/pip instead.
-
-For Windows and Mac, the standalone desktop software ExploreDesktop can be installed using the installer files uploaded to the
-`release page <https://github.com/Mentalab-hub/explore-desktop-release/releases/latest/>`_. Please note that the dependencies will be installed automatically and bundled locally with the installed software.
-
-
-Option 2: Installing from Python Package Index (PyPI) and pip (advanced)
+Installing from Python Package Index (PyPI)
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
+.. note::
+    For Windows, Mac and Linux the standalone desktop software ExploreDesktop can be installed using the installer files uploaded to the
+    `release page <https://github.com/Mentalab-hub/explore-desktop-release/releases/latest/>`_.
 
 .. note::
 

{explorepy-4.1.0 → explorepy-4.2.0}/docs/requirements.txt

@@ -8,7 +8,7 @@ pylsl==1.16.1
 PyYAML==6.0.1
 PyYAML==6.0.1
 scipy==1.11.1
-tornado==6.4.2
+tornado==6.5.1
 sentry_sdk==2.8.0
 sphinx-rtd-theme==1.3.0
 sphinx==7.2.4

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

@@ -27,14 +27,6 @@ For example to get help about the visualize command, run: ``explorepy push2lsl -
 Available Commands
 """"""""""""""""""
 
-find-device
-%%%%
-Scans for nearby Mentalab Explore devices. Prints out the Name and MAC address of found devices.
-
-    Options:
-      -h, --help                      Show this message and exit.
-
-
 acquire
 %%%%
 Connects to a device with selected name or address. Only one input is necessary.
@@ -135,18 +127,6 @@ Example (overwrite):
 ::
     explorepy bin2edf -f input_file.BIN -ow
 
-calibrate-orn
-%%%%
-
-Calibrates the orientation module of a device. This module stores calibration parameters in ``explorepy``'s configuration file. Once calibrated, ``explorepy`` computes the device's orientation (degree and rotation axis).
-::
-
-    Options:
-      -a, --address TEXT   Explore device's MAC address
-      -n, --name TEXT      Name of the device
-      -ow, --overwrite     Overwrite existing file
-      -h, --help           Show this message and exit.
-
 
 format-memory
 %%%%
@@ -181,18 +161,6 @@ Example:
 ::
     explorepy set-sampling-rate -n Explore_XXXX -sr 500
 
-disable-module
-%%%%
-
-Disables a device module (orientation, environment and ExG).
-::
-
-    Options:
-      -a, --address TEXT  Explore device's MAC address
-      -n, --name TEXT     Name of the device
-      -m, --module TEXT   Module name to be disabled, options: ORN, ENV, EXG
-                          [required]
-
 
 soft-reset
 %%%%

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

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

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

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

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

@@ -56,13 +56,6 @@ def verify_inputs(func):
     return update_wrapper(wrapper, func)
 
 
-@cli.command()
-def find_device():
-    """List available Explore devices"""
-    explorepy.set_bt_interface(default_bt_backend)
-    explorepy.tools.run_ble_scanner()
-
-
 @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")
@@ -174,39 +167,3 @@ def set_channels(address, name, channel_mask):
     explore = explorepy.explore.Explore()
     explore.connect(mac_address=address, device_name=name)
     explore.set_channels(channel_mask)
-
-
-@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", "--module", required=True, type=str, help="Module name to be disabled, options: ORN, ENV, EXG")
-@verify_inputs
-def disable_module(address, name, module):
-    """Disable a module of Explore device"""
-    explore = explorepy.explore.Explore()
-    explore.connect(mac_address=address, device_name=name)
-    explore.disable_module(module)
-
-
-@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", "--module", required=True, type=str, help="Module name to be enabled, options: ORN, ENV, EXG")
-@verify_inputs
-def enable_module(address, name, module):
-    """Enable a module of Explore device"""
-    explore = explorepy.explore.Explore()
-    explore.connect(mac_address=address, device_name=name)
-    explore.enable_module(module)
-
-
-@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("-ow", "--overwrite", is_flag=True, help="Overwrite existing file")
-@verify_inputs
-def calibrate_orn(address, name, overwrite):
-    """Calibrate the orientation module"""
-    explore = explorepy.explore.Explore()
-    explore.connect(mac_address=address, device_name=name)
-    explore.calibrate_orn(do_overwrite=overwrite)

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

@@ -242,49 +242,6 @@ class MemoryFormat(Command2B):
         return "Format memory command"
 
 
-class ModuleDisable(Command2B):
-    """Module disable command"""
-
-    def __init__(self, module_name):
-        """
-
-        Args:
-            module_name (str): Module name to be disabled. Options: "EXG", "ORN", "ENV"
-        """
-        super().__init__()
-        self.opcode = OpcodeID.CMD_MODULE_DISABLE
-        if module_name == "ENV":
-            self.param = b'\x01'
-        elif module_name == "ORN":
-            self.param = b'\x02'
-        elif module_name == "EXG":
-            self.param = b'\x03'
-
-    def __str__(self):
-        return "Module disable command"
-
-
-class ModuleEnable(Command2B):
-    """Module enable command"""
-
-    def __init__(self, module_name):
-        """
-        Args:
-            module_name (str): Module name to be disabled. Options: "EXG", "ORN", "ENV"
-        """
-        super().__init__()
-        self.opcode = OpcodeID.CMD_MODULE_ENABLE
-        if module_name == "ENV":
-            self.param = b'\x01'
-        elif module_name == "ORN":
-            self.param = b'\x02'
-        elif module_name == "EXG":
-            self.param = b'\x03'
-
-    def __str__(self):
-        return "Module enable command"
-
-
 class ZMeasurementDisable(Command2B):
     """Enables Z measurement mode"""
 

{explorepy-4.1.0 → explorepy-4.2.0}/src/explorepy/explore.py

@@ -20,13 +20,10 @@ import time
 from threading import Timer
 
 import numpy as np
-from appdirs import user_cache_dir
 
 import explorepy
 from explorepy.command import (
     MemoryFormat,
-    ModuleDisable,
-    ModuleEnable,
     SetChTest,
     SetSPS,
     SoftReset
@@ -39,7 +36,6 @@ from explorepy.stream_processor import (
 )
 from explorepy.tools import (
     LslServer,
-    PhysicalOrientation,
     check_bin_compatibility,
     create_exg_recorder,
     create_marker_recorder,
@@ -559,73 +555,6 @@ class Explore:
         SettingsManager(self.device_name).set_adc_mask(channel_mask)
         return True
 
-    def disable_module(self, module_name):
-        """Disable module
-
-        Args:
-            module_name (str): Module to be disabled (options: 'ENV', 'ORN', 'EXG')
-
-        Examples:
-            >>> from explorepy.explore import Explore
-            >>> explore = Explore()
-            >>> explore.connect(device_name='Explore_2FA2')
-            >>> explore.disable_module('ORN')
-
-        Returns:
-            bool: True for success, False otherwise
-        """
-        if module_name not in ['ORN', 'ENV', 'EXG']:
-            raise ValueError('Module name must be one of ORN, ENV or EXG.')
-        self._check_connection()
-        cmd = ModuleDisable(module_name)
-        return self.stream_processor.configure_device(cmd)
-
-    def enable_module(self, module_name):
-        """Enable module
-
-        Args:
-            module_name (str): Module to be disabled (options: 'ENV', 'ORN', 'EXG')
-
-        Examples:
-            >>> from explorepy.explore import Explore
-            >>> explore = Explore()
-            >>> explore.connect(device_name='Explore_2FA2')
-            >>> explore.enable_module('ORN')
-
-        Returns:
-            bool: True for success, False otherwise
-        """
-        if module_name not in ['ORN', 'ENV', 'EXG']:
-            raise ValueError('Module name must be one of ORN, ENV or EXG.')
-        self._check_connection()
-        cmd = ModuleEnable(module_name)
-        return self.stream_processor.configure_device(cmd)
-
-    def calibrate_orn(self, do_overwrite=False):
-        """Calibrate orientation module
-
-        This method calibrates orientation sensors in order to get the real physical orientation in addition to raw
-        sensor data. While running this function you would need to move and rotate the device. This function will store
-        calibration info in the configuration file which will be used later during streaming to calculate physical
-        orientation from raw sensor data.
-
-        Args:
-            do_overwrite: to overwrite the calibration data if already exists or not
-
-        """
-        assert not (PhysicalOrientation.check_calibre_data(device_name=self.device_name) and not do_overwrite), \
-            "Calibration data already exists!"
-        PhysicalOrientation.init_dir()
-        logger.info("Start recording for 100 seconds, "
-                    "please move the device around during this time, in all directions")
-        file_name = user_cache_dir(
-            appname="explorepy", appauthor="Mentalab") + '//temp_' + self.device_name
-        self.record_data(file_name, do_overwrite=do_overwrite,
-                         duration=100, file_type='csv')
-        time.sleep(105)
-        PhysicalOrientation.calibrate(
-            cache_dir=file_name, device_name=self.device_name)
-
     def _activate_test_sig(self, channel_mask):
         """ Activate the internal ADS test signals
         """

{explorepy-4.1.0 → explorepy-4.2.0}/src/explorepy/serial_client.py

@@ -134,8 +134,7 @@ class SerialStream:
                 chunk.append(self.copy_buffer.popleft())
             return chunk
         except Exception as error:
-            logger.debug('Got error or read request: {}'.format(error))
-            print('maziar Got error or read request: {}'.format(error))
+            logger.debug('Got error on read request: {}'.format(error))
 
     def send(self, data):
         """Send data to the device

{explorepy-4.1.0 → explorepy-4.2.0}/src/explorepy/stream_processor.py

@@ -39,7 +39,6 @@ from explorepy.parser import Parser
 from explorepy.settings_manager import SettingsManager
 from explorepy.tools import (
     ImpedanceMeasurement,
-    PhysicalOrientation,
     get_local_time,
     is_explore_pro_device,
     is_usb_mode
@@ -47,7 +46,7 @@ from explorepy.tools import (
 
 
 TOPICS =\
-    Enum('Topics', 'raw_ExG filtered_ExG device_info marker raw_orn mapped_orn cmd_ack env cmd_status imp packet_bin')
+    Enum('Topics', 'raw_ExG filtered_ExG device_info marker raw_orn cmd_ack env cmd_status imp packet_bin')
 logger = logging.getLogger(__name__)
 lock = Lock()
 
@@ -68,7 +67,6 @@ class StreamProcessor:
         self.imp_calculator = None
         self.is_connected = False
         self._is_imp_mode = False
-        self.physical_orn = PhysicalOrientation()
         self._last_packet_timestamp = 0
         self._last_packet_rcv_time = 0
         self.is_bt_streaming = True
@@ -124,7 +122,6 @@ class StreamProcessor:
             callback=self._device_configurator.update_ack, topic=TOPICS.cmd_ack)
         self.subscribe(
             callback=self._device_configurator.update_cmd_status, topic=TOPICS.cmd_status)
-        self.orn_initialize(device_name)
 
     def open_file(self, bin_file, progress_callback=None):
         """Open the binary file and read until it gets device info packet
@@ -267,10 +264,6 @@ class StreamProcessor:
     def _process_orientation_batch(self, packets: List[Tuple]):
         raw_packets = [packet for packet, _ in packets]
         self.dispatch(topic=TOPICS.raw_orn, packet=raw_packets)
-        for packet, _ in packets:
-            if self.physical_orn.status == "READY":
-                processed_packet = self.physical_orn.calculate(packet=packet)
-                self.dispatch(topic=TOPICS.mapped_orn, packet=processed_packet)
 
     def _process_device_info_batch(self, packets: List[Tuple]):
         for packet, _ in packets:
@@ -317,9 +310,6 @@ class StreamProcessor:
             self.dispatch(topic=TOPICS.packet_bin, packet=packet)
         elif isinstance(packet, Orientation):
             self.dispatch(topic=TOPICS.raw_orn, packet=packet)
-            if self.physical_orn.status == "READY":
-                packet = self.physical_orn.calculate(packet=packet)
-                self.dispatch(topic=TOPICS.mapped_orn, packet=packet)
         elif isinstance(packet, EEG):
             self.last_exg_packet_timestamp = get_local_time()
             missing_timestamps = self.fill_missing_packet(packet)
@@ -483,15 +473,6 @@ class StreamProcessor:
               "Please restart your device manually.")
         return False
 
-    def orn_initialize(self, device_name):
-        res = self.physical_orn.read_calibre_data(device_name)
-        if res:
-            self.physical_orn.status = "READY"
-        else:
-            self.physical_orn.status = "NOT READY"
-            logger.debug('Calibration coefficients for physical orientation do not exist. '
-                         'If you need physical orientation, calibrate the device first.')
-
     def set_marker(self, code):
         """Set a marker in the stream"""
         logger.info(f"Setting a software marker with code: {code}")