explorepy 1.8.2__tar.gz → 4.1.0__tar.gz

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

@@ -1,11 +1,9 @@
 [bumpversion]
-current_version = 1.8.2
+current_version = 4.1.0
 commit = False
 tag = False
 
-[bumpversion:file:setup.py]
-search = version='{current_version}'
-replace = version='{new_version}'
+[bumpversion:file:pyproject.toml]
 
 [bumpversion:file:README.rst]
 search = v{current_version}.

explorepy-4.1.0/AUTHORS.rst

@@ -0,0 +1,11 @@
+
+Authors
+=======
+
+
+* Salman Rahman - `salman@mentalab.com <mailto:salman@mentalab.com>`_
+* Andrea Escartin
+* Sonja Stefani -  `sonja@mentalab.com <mailto:sonja@mentalab.com>`_
+* Mohamad Atayi
+* Masoome Fazelian
+* Alex Platt

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

@@ -2,13 +2,64 @@
 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
+* Improve binary file conversion and stream parser algorithm
+
+
+3.2.1 (31.1.2025)
+------------------
+* Hotfix impedance calculation
+
+
+3.2.0 (31.1.2025)
+------------------
+* Fix critical bug in settings file modification
+* Improve BT communication
+* Disable impedance on fresh connection
+* Introduce new sampling rates
+
+
+3.1.0 (8.11.2024)
+------------------
+* Add USB streaming support
+* Improve BT communication
+
+
+3.0.1 (28.08.2024)
+------------------
+* Improve device connectivity
+* Add text marker support
+
+
+3.0.0 (7.6.2024)
+------------------
+* Improve Mac OSX support
+* Add Support for Explore Pro
+* Robust data parsing
+
+
+2.0.0 (5.1.2024)
+------------------
+* Add Mac OSX support
+* Remove browser based visualization support
+* Update build script for docs
+
+
 1.8.2 (28.8.2023)
 ------------------
 * Improve explore mock device
 * Add yaml file for RTD build
 
 
-
 1.8.1 (11.7.2023)
 ------------------
 * Bugfix record data
@@ -27,7 +78,7 @@ Changelog
 
 1.7.0 (21.12.2022)
 ------------------
-* Add suppport for new explore+ 32 ch device
+* Add support for new explore+ 32 ch device
 * Sorted timestamps in CSV
 * Settings file to preserve experiment settings
 

{explorepy-1.8.2 → explorepy-4.1.0}/MANIFEST.in

@@ -17,4 +17,4 @@ recursive-include lib *
 
 include tox.ini
 
-global-exclude *.py[cod] __pycache__  *.dylib
+global-exclude *.py[co] __pycache__  *.dylib

explorepy-4.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: explorepy
+Version: 4.1.0
+Author-email: MentaLab Hub <support@mentab.org>
+License: MIT
+Project-URL: Homepage, https://github.com/Mentalab-hub/explorepy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS
+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
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pyEDFlib==0.1.38
+Requires-Dist: click==7.1.2
+Requires-Dist: appdirs==1.4.3
+Requires-Dist: sentry_sdk==2.8.0
+Requires-Dist: mne
+Requires-Dist: eeglabio
+Requires-Dist: pandas
+Requires-Dist: pyserial
+Requires-Dist: pyyaml
+Requires-Dist: bleak==0.22.3
+Requires-Dist: pylsl
+Requires-Dist: numba
+Provides-Extra: test
+Requires-Dist: pytest==6.2.5; extra == "test"
+Requires-Dist: pytest-mock==3.10.0; extra == "test"
+Requires-Dist: pytest-html==3.2.0; extra == "test"
+Requires-Dist: flake8==4.0.1; extra == "test"
+Requires-Dist: isort==5.10.1; extra == "test"
+Dynamic: license-file
+
+.. image:: logo.png
+   :scale: 100 %
+   :align: left
+
+
+.. start-badges
+
+|docs| |version| |wheel| |supported-versions| |commits-since|
+
+.. |docs| image:: https://readthedocs.org/projects/explorepy/badge/?style=flat
+    :target: https://readthedocs.org/projects/explorepy
+    :alt: Documentation Status
+
+
+.. |version| image:: https://img.shields.io/pypi/v/explorepy.svg
+    :alt: PyPI Package latest release
+    :target: https://pypi.org/project/explorepy
+
+
+.. |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.1.0...master
+
+
+.. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
+    :alt: PyPI Wheel
+    :target: https://pypi.org/project/explorepy
+
+.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/explorepy.svg
+    :alt: Supported versions
+    :target: https://pypi.org/project/explorepy
+
+.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/explorepy.svg
+    :alt: Supported implementations
+    :target: https://pypi.org/project/explorepy
+
+
+.. end-badges
+
+=========================
+``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:
+
+* 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
+------------
+
+* Python 3.10 to Python 3.12.
+* Visual Studio 2015 community edition (Windows only. For package building).
+* Bluetooth header files (Linux only. Use: ``sudo apt-get install libbluetooth-dev``).
+
+
+Detailed installation instructions can be found on the `installation page <https://explorepy.readthedocs.io/en/latest/installation.html>`_.
+
+To install ``explorepy`` from PyPI run:
+::
+
+    pip install explorepy
+
+
+To install the latest development version (git must be installed before running this command):
+::
+
+    pip install git+https://github.com/Mentalab-hub/explorepy
+
+
+Get started
+===========
+
+CLI command
+-----------
+To check ``explorepy`` is running use:
+::
+    explorepy acquire -n Explore_XXXX
+
+For help, use:
+::
+    explorepy -h
+
+
+Python code
+-----------
+
+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.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
+=============
+
+For full API documentation, visit: https://explorepy.readthedocs.io/.
+
+Troubleshooting
+===============
+If you are having problems, please check the `troubleshooting <https://explorepy.readthedocs.io/en/latest/installation.html#troubleshooting>`_
+section of the documentation.
+
+If you are still having problems, send us your error log via Sentry (note: Explorepy will send the log
+automatically once you have provided permission), or send us the log file via email to support@mentalab.com. The log file is usually found under:
+
+* Windows: ``<Windows Drive>:\Users\<USER_NAME>\AppData\Local\mentalab\explorepy\Logs\explorepy.log``
+* Ubuntu: ``/home/<USER_NAME>/.cache/explorepy/log/explorepy.log``
+* Mac OS: ``/Users/<USER_NAME>/Library/Logs/explorepy/explorepy.log``
+
+You can also create a new issue in the GitHub repository.
+
+Authors
+=======
+- `Mohamad Atayi`_
+- `Salman Rahman`_
+- `Andrea Escartin`_
+- `Sonja Stefani`_
+- `Alex Platt`_
+- `Andreas Gutsche`_
+- `Masooma Fazelian`_
+- `Philipp Jakovleski`_
+- `Florian Sesser`_
+- `Sebastian Herberger`_
+
+
+.. _Mohamad Atayi: https://github.com/bmeatayi
+.. _Salman Rahman: https://github.com/salman2135
+.. _Andrea Escartin: https://github.com/andrea-escartin
+.. _Sonja Stefani: https://github.com/SonjaSt
+.. _Alex Platt: https://github.com/Nujanauss
+.. _Andreas Gutsche: https://github.com/andyman410
+.. _Masooma Fazelian: https://github.com/fazelian
+.. _Philipp Jakovleski: https://github.com/philippjak
+.. _Florian Sesser : https://github.com/hacklschorsch
+.. _Sebastian Herberger: https://github.com/SHerberger
+
+License
+=======
+This project is licensed under the `MIT <https://github.com/Mentalab-hub/explorepy/blob/master/LICENSE>`_ license. You can reach us at contact@mentalab.com.

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

@@ -1,6 +1,6 @@
 .. image:: logo.png
    :scale: 100 %
-   :align: center
+   :align: left
 
 
 .. start-badges
@@ -17,9 +17,9 @@
     :target: https://pypi.org/project/explorepy
 
 
-.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v1.8.2.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/v1.8.2...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v4.1.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
@@ -54,13 +54,13 @@ 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. MAC OSX is currently not supported. 
+For other operating systems, or to build the package manually on Windows, please refer to the information below.
 
 
 Requirements
 ------------
 
-* Python 3.7 to Python 3.11.
+* Python 3.10 to Python 3.12.
 * Visual Studio 2015 community edition (Windows only. For package building).
 * Bluetooth header files (Linux only. Use: ``sudo apt-get install libbluetooth-dev``).
 
@@ -124,7 +124,7 @@ If you are having problems, please check the `troubleshooting <https://explorepy
 section of the documentation.
 
 If you are still having problems, send us your error log via Sentry (note: Explorepy will send the log
-automatically once you have provided permission), or send us the log file via email to contact@mentalab.com. The log file is usually found under:
+automatically once you have provided permission), or send us the log file via email to support@mentalab.com. The log file is usually found under:
 
 * Windows: ``<Windows Drive>:\Users\<USER_NAME>\AppData\Local\mentalab\explorepy\Logs\explorepy.log``
 * Ubuntu: ``/home/<USER_NAME>/.cache/explorepy/log/explorepy.log``

{explorepy-1.8.2 → explorepy-4.1.0}/docs/conf.py

@@ -4,8 +4,7 @@ import os
 import sys
 
 sys.path.insert(0, os.path.abspath('../src/explorepy/'))
-autodoc_mock_imports = ['bluetooth', 'pylsl', 'bokeh', 'tornado',
-                        'explorepy.exploresdk', 'explorepy._exploresdk']
+autodoc_mock_imports = ['bluetooth', 'pylsl', 'bokeh', 'tornado']
 
 extensions = [
     'sphinx.ext.autodoc',
@@ -26,22 +25,18 @@ if os.getenv('SPELLCHECK'):
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'explorepy'
-year = '2018-2022'
+year = '2018-2025'
 author = 'Mentalab GmbH.'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '1.8.2'
-
+version = release = '4.1.0'
 pygments_style = 'trac'
 templates_path = ['.']
 extlinks = {
     'issue': ('https://github.com/Mentalab-hub/explorepy/issues/%s', '#'),
     'pr': ('https://github.com/Mentalab-hub/explorepy/pull/%s', 'PR #'),
 }
-# on_rtd is whether we are on readthedocs.org
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-if not on_rtd:  # only set the theme if we're building docs locally
-    html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_rtd_theme'
 
 html_use_smartypants = True
 html_last_updated_fmt = '%b %d, %Y'

explorepy-4.1.0/docs/explore_legacy_devices.rst

@@ -0,0 +1,11 @@
+============
+Legacy device and explorepy support
+============
+
+Starting from explorepy 4.0.0, latest version of explorepy will only support Explore Pro devices, meaning users will not be able to use legacy devices with explorepy 4.0.0 and onwards.
+If you want to install explorepy for legacy devices, please use the following command for windows and linux.
+   .. code-block:: bash
+
+      pip install explorepy==3.2.1
+
+To install explorepy 3.2.1 in Mac, please contact support@mentalab.com.

{explorepy-1.8.2 → explorepy-4.1.0}/docs/index.rst

@@ -12,6 +12,7 @@ Contents
    contributing
    authors
    changelog
+   explore_legacy_devices
 
 Indices and tables
 ==================

explorepy-4.1.0/docs/installation.rst

@@ -0,0 +1,153 @@
+============
+Installation
+============
+
+Minimal Requirements
+--------------------
+* Python 3.12 and upwards. We recommend using Python 3.12.
+* Microsoft Build Tools for Visual Studio 2019 (only Windows)
+* 6GB RAM (minimum 1GB *free* RAM during the session)
+* Intel i5 or higher (2x2.5GHz) CPU
+
+Recommended Requirements
+------------------------
+* Python 3.12
+* Microsoft Build Tools for Visual Studio 2019 (only Windows)
+* 8GB RAM
+* Intel i7 or higher CPU
+
+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)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+
+.. note::
+
+   Explore legacy device support is **deprecated** in ExplorePy. See the documentation on :doc:`explore_legacy_devices`.
+
+
+*To install explorepy for any Python version below 3.10, please contact support@mentalab.com*
+
+*This option is best for users who intend to include* ``explorepy`` *functionalities in their own Python scripts or use it from the command line.*
+
+For an overview of ``explorepy`` commands, click `here <https://explorepy.readthedocs.io/en/latest/usage.html#command-line-interface>`_.
+
+Windows
+^^^^^^^
+
+To install the ``explorepy`` API and all its dependencies using pip on Windows:
+
+1. Install Anaconda (or any other Python distribution; these instructions pertain to Anaconda only). Download and run the `Anaconda installer for windows <https://www.anaconda.com/download/success>`_.
+2. Install `Microsoft Build Tools for Visual Studio 2019 <https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16>`_. Select *Desktop development with C++* in the workloads tab. Make sure that *MSVCv142 - VS 2019 C++ x64/x86 build tools* and the latest version of *Windows 10 SDK* are checked.
+3. Open the Anaconda command prompt.
+4. We recommend using a conda environment. To do this:
+
+   a. In the Anaconda command prompt: ``conda create -n myenv python=3.12``
+   b. Activate the conda environment: ``conda activate myenv``
+
+5. Upgrade your pip: ``python -m pip install --upgrade pip``
+6. Install liblsl: ``conda install -c conda-forge liblsl``
+7. Run ``pip install explorepy`` to install ``explorepy`` from PyPI.
+
+Ubuntu
+^^^^^^
+1. From the terminal, run these commands one by one: ``sudo apt-get install libbluetooth-dev`` and ``sudo apt-get install build-essential``.
+2. We recommend installing Anaconda. Download and installer `Anaconda<https://www.anaconda.com/download>`/Miniconda/.
+3. We recommend using a virtual environment in Conda. To do this:
+
+   a. In the Anaconda command prompt: ``conda create -n myenv python=3.12``
+   b. Activate the conda environment: ``conda activate myenv``
+
+4. Upgrade your pip: ``python -m pip install --upgrade pip``
+5. Install liblsl: ``conda install -c conda-forge liblsl``
+6. Run ``pip install explorepy`` to install ``explorepy`` from PyPI.
+7. From the terminal, run: ``sudo apt install libxcb-cursor0``
+
+Set up USB streaming in Linux
++++++++++++++++++++++++++++++
+
+a. Set up ``udev`` rules for appropiate permission to ``/dev/ttyACM*`` in Linux
+
+    *Steps to Execute the Udev Script Manually*
+
+    1. Create a file named ``setup_udev_rule.sh`` and include the following script
+
+        ::
+
+            #!/bin/bash
+
+            RULE='SUBSYSTEM=="tty", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", SYMLINK+="stm_virtual_com", MODE="0666"'
+
+            echo "Creating udev rule..."
+            echo "$RULE" | sudo tee /etc/udev/rules.d/99-stm-virtual-com.rules > /dev/null
+
+            sudo udevadm control --reload-rules && sudo udevadm trigger
+            echo "udev rule has been created successfully!"
+            echo "You can access your device at /dev/$SYMLINK_NAME when it is connected."
+
+    2. Make the ``setup_udev_rule.sh`` executable ::
+
+         chmod +x setup_udev_rule.sh
+
+    3. Execute the script ::
+
+        ./setup_udev_rule.sh
+
+    *To remove the udev rule when no longer required*  ::
+
+        sudo rm /etc/udev/rules.d/99-stm-virtual-com.rules
+
+
+b. Alternate method: Temporarily granting appropriate permissions to ``/dev/ttyACM*``
+
+
+    1. Identify the device (ttyACM0, ttyACM1, ttyACM2, etc) in ``/dev`` directory
+
+
+    2. Execute this command in the terminal (replace * with appropiate id) ::
+
+            chmod 666 /dev/ttyACM*
+
+Mac
+^^^
+1. Install ``XCode`` from the Mac App store. For this, you may need to upgrade to the latest version of MacOS. For older versions of MacOS, find compatible versions of ``XCode`` `here <https://en.wikipedia.org/wiki/Xcode>`_. All old ``XCode`` versions are available `here <https://developer.apple.com/download/more/>`_.
+2. Accept the license agreement: ``sudo xcodebuild -license``.
+3. It is best to install Anaconda. Download  and run the `Anaconda installer for Mac <https://www.anaconda.com/download/success>`_. For older versions of MacOS, compatible version of Anaconda can be found in `this table <https://docs.continuum.io/anaconda/install/#old-os>`_ and downloaded `here <https://repo.anaconda.com/archive/index.html>`_.
+4. We recommend using a conda environment.
+
+   a. In the Anaconda command prompt: ``conda create -n myenv python=3.10``
+   b. Activate the conda environment: ``conda activate myenv``
+
+5. Upgrade your pip: ``python -m pip install --upgrade pip``
+6. Install liblsl: ``conda install -c conda-forge liblsl``
+7. Run ``pip install explorepy`` to install ``explorepy`` from PyPI.
+8. Connect your Explore device from the Bluetooth menu and run your Python script.
+
+
+Quick test
+----------
+
+*Note: If you installed the graphical user interface ExploreDesktop as outlined above, explorepy won't be available from the command line.*
+
+* Open the Anaconda command prompt.
+* Activate the virtual environment that you made before installing explorepy: ``conda activate myenv``
+* Run ``explorepy acquire -n DEVICE-NAME``
+* To stop the command execution, press ``Ctrl+C``

{explorepy-1.8.2 → explorepy-4.1.0}/docs/reference/explorepy.rst

@@ -27,11 +27,6 @@ Parser
     :members:
     :undoc-members:
 
-Dashboard
-*********
-.. autoclass:: dashboard.dashboard.Dashboard
-    :members:
-
 
 Additional tools
 ****************

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

@@ -1,7 +1,5 @@
 appdirs==1.4.3
-bokeh==2.2.3
 click==7.1.2
-Jinja2==3.0.0
 mne==0.24.1
 numpy==1.24.4
 pandas==1.3.4
@@ -10,5 +8,7 @@ pylsl==1.16.1
 PyYAML==6.0.1
 PyYAML==6.0.1
 scipy==1.11.1
-sentry_sdk==1.19.1
-tornado==6.3.2
+tornado==6.4.2
+sentry_sdk==2.8.0
+sphinx-rtd-theme==1.3.0
+sphinx==7.2.4