Release 3.1.0

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.0.0
+current_version = 3.1.0
 commit = False
 tag = False
 

AUTHORS.rst

@@ -2,8 +2,10 @@
 Authors
 =======
 
-* Mohamad Atayi - mentalab.com
-* Masooma Fazelian - mentalab.com
+
 * Salman Rahman - mentalab.com
 * Andrea Escartin - mentalab.com
+* Sonja Stefani - mentalab.com
+* Mohamad Atayi - mentalab.com
+* Masoome Fazelian - mentalab.com
 * Alex Platt - mentalab.com

CHANGELOG.rst

@@ -2,6 +2,22 @@
 Changelog
 =========
 
+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

MANIFEST.in

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

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/v2.0.0.svg
+.. |commits-since| image:: https://img.shields.io/github/commits-since/Mentalab-hub/explorepy/v3.1.0.svg
     :alt: Commits since latest release
-    :target: https://github.com/Mentalab-hub/explorepy/compare/v2.0.0...master
+    :target: https://github.com/Mentalab-hub/explorepy/compare/v3.1.0...master
 
 
 .. |wheel| image:: https://img.shields.io/pypi/wheel/explorepy.svg
@@ -60,7 +60,7 @@ For other operating systems, or to build the package manually on Windows, please
 Requirements
 ------------
 
-* Python 3.7 to Python 3.12.
+* 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``

docs/conf.py

@@ -26,10 +26,10 @@
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'explorepy'
-year = '2018-2022'
+year = '2018-2024'
 author = 'Mentalab GmbH.'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '2.0.0'
+version = release = '3.1.0'
 
 pygments_style = 'trac'
 templates_path = ['.']

docs/installation.rst

@@ -4,14 +4,14 @@ Installation
 
 Minimal Requirements
 ------------
-* Python 3.7 to Python 3.12
+* Python 3.10 to Python 3.12. We recommend Python 3.10.
 * 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.7 to Python 3.12
+* Python 3.10
 * Microsoft Build Tools for Visual Studio 2019 (only Windows)
 * 8GB RAM
 * Intel i7 or higher CPU
@@ -22,148 +22,134 @@ How to install
 Windows
 ^^^^^^^
 
-Option 1: Installing .exe file (basic)
+Option 1: Installing via installer file (basic)
 """"""""
 
-*This option is best for users who only intend to use* ``explorepy`` *from a command-line prompt.*
+*This option is best for users who only intend to use* ``explorepy`` *via graphical user interface*
 
 For example, if you want to quickly visualize and record data, use Option 1.
 If you intend to add ``explorepy`` commands to a Python script
 (e.g. an experiment script), install ``explorepy`` via Anaconda instead.
 
 For an overview of ``explorepy`` commands, click `here <https://explorepy.readthedocs.io/en/latest/usage.html#command-line-interface>`_.
 
-On a Windows machine, ``explorepy`` can be installed using the .exe installable file uploaded to
-``explorepy``'s `release page <https://github.com/Mentalab-hub/explorepy/releases/download/v1.5.0/MentaLab_ExplorePy_1.5.0.exe>`_. Please note that the dependencies will be installed automatically.
-
-A standalone Mac installer is also available. Please contact Mentalab support to get Mac installer.
+On a Windows and Mac operating systems, standalone desktop software ``explorepy-desktop`` can be installed using the .exe installable file uploaded to
+`release page <https://github.com/Mentalab-hub/explore-desktop-release/releases/latest/>`_. Please note that the dependencies will be installed automatically.
 
 
 Option 2: Installing from Python Package Index (PyPI) and pip (advanced)
 """"""""
+*To install explorepy for any python version except 3.10, please contact [email protected].*
 
 *This option is best for users who intend to include* ``explorepy`` *functionalities in their own Python scripts.*
-
 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 install the `Anaconda Windows installer <https://www.anaconda.com/distribution/#download-section>`_.
 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 Conda command prompt.
 4. We recommend using a virtual environment. To do this:
 
-   a. In Conda command prompt: ``conda create -n myenv python=3.8``
+   a. In Conda command prompt: ``conda create -n myenv python=3.10``
    b. Activate the virtual environment: ``conda activate myenv``
 
 5. Upgrade your pip: ``python -m pip install --upgrade pip``
 6. Run: ``pip install explorepy``, to install ``explorepy`` from PyPI.
 
 Ubuntu
 ^^^^^^
-1. Install Bluetooth header files using ``sudo apt-get install libbluetooth-dev``
-2. We recommend installing Anaconda. Download and install the `Anaconda Python 3.7 Ubuntu installer <https://www.anaconda.com/distribution/#download-section>`_.
+1. From Linux Terminal, run these commands one by one: ``sudo apt-get install libbluetooth-dev`` and ``sudo apt-get install build-essential`` and ``conda install -c conda-forge liblsl``.
+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 Conda command prompt: ``conda create -n myenv python=3.8``
+   a. In Conda command prompt: ``conda create -n myenv python=3.10``
    b. Activate the virtual environment: ``conda activate myenv``
 
 4. Upgrade your pip: ``python -m pip install --upgrade pip``
 5. Run: ``pip install explorepy``, to install ``explorepy`` from PyPI.
+6. From Linux Terminal, run: ``sudo apt install libxcb-cursor0``
 
-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 install the `Anaconda Python 3.7 Mac installer <https://www.anaconda.com/distribution/#download-section>`_. 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 virtual environment in Conda.
+Set up USB streaming in Linux
+"""""""""""""""""""""""""""""
+a. Set up ``udev`` rules for appropiate permission to ``/dev/ttyACM*`` in Linux
 
-   a. In Conda command prompt: ``conda create -n myenv python=3.10``
-   b. Activate the virtual environment: ``conda activate myenv``
+    *Steps to Execute the Udev Script Manually*
 
-5. Upgrade your pip: ``python -m pip install --upgrade pip``
-6. Run: ``pip install explorepy``, to install ``explorepy`` from PyPI.
-7. Run: ``brew install blueutil``, to install blueutil for bluetooth communication
-7. Connect your Explore device from Mac Bluetooth menu and run your Python script.
+    1. Create a file named ``setup_udev_rule.sh`` and include the following script
 
-Quick test
-----------
+        ::
 
-* Open the Conda command prompt (if you used pip) or Windows command prompt (if you used the installable file).
-* Activate the virtual environment (this step is only necessary in the Conda command prompt): ``conda activate myenv``
-* Run ``explorepy acquire -n DEVICE-NAME``
-* To stop the command execution, press ``Ctrl+C``
+            #!/bin/bash
 
-Troubleshooting
----------------
+            RULE='SUBSYSTEM=="tty", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", SYMLINK+="stm_virtual_com", MODE="0666"'
 
-**1. Pylsl import issue**
+            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."
 
-        self._handle = _dlopen(self._name, mode)
-    OSError: [WinError 126] The specified module could not be found
+    2. Make the ``setup_udev_rule.sh`` executable ::
 
+         chmod +x setup_udev_rule.sh
 
-Solution: Install an older version of Pylsl. To do this, run: ::
+    3. Execute the script ::
 
-    pip install pylsl==1.13.1
+        ./setup_udev_rule.sh
 
-Alternatively, install `MS Visual C++ redistributable (vc_redist) <https://support.microsoft.com/en-ca/help/2977003/the-latest-supported-visual-c-downloads>`_.
+    *To remove the udev rule when no longer required*  ::
 
---------------------
+        sudo rm /etc/udev/rules.d/99-stm-virtual-com.rules
 
 
-**2. Anaconda asyncio events library raises "NotImplementedError" error in Windows**
+b. Alternate method: Temporarily granting appropriate permissions to ``/dev/ttyACM*``
 
-::
 
-    File "c:\users\jose\anaconda3\lib\site-packages\bokeh\server\server.py", line 407, in __init__
-        http_server.add_sockets(sockets)
-    File "c:\users\jose\anaconda3\lib\site-packages\tornado\tcpserver.py", line 165, in add_sockets
-        self._handlers[sock.fileno()] = add_accept_handler(
-    File "c:\users\jose\anaconda3\lib\site-packages\tornado\netutil.py", line 279, in add_accept_handler
-        io_loop.add_handler(sock, accept_handler, IOLoop.READ)
-    File "c:\users\jose\anaconda3\lib\site-packages\tornado\platform\asyncio.py", line 100, in add_handler
-        self.asyncio_loop.add_reader(fd, self._handle_events, fd, IOLoop.READ)
-    File "c:\users\jose\anaconda3\lib\asyncio\events.py", line 501, in add_reader
-        raise NotImplementedError
+    1. Identify the device (ttyACM0, ttyACM1, ttyACM2, etc) in ``/dev`` directory
 
-Solution: Downgrade your Anaconda distribution to version 3.6 or 3.7.
 
----------------------
+    2. Execute this command in the terminal (replcae * with appropiate id) ::
 
-**3. No module named 'numpy'**
+            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. Download and installer `Anaconda<https://www.anaconda.com/download>`/Miniconda/.
+4. We recommend using a virtual environment in Conda.
 
-    ERROR: Command errored out with exit status 4294967295:
-     command: 'C:\Users\mh\Anaconda3\envs\test130_38\python.exe' -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\mh_at\\AppData\\Local\\Temp\\pip-install-6fpsl7b1\\pyedflib_e1c2dcc3a4dc46af9468c24083cbda2b\\setup.py'"'"'; __file__='"'"'C:\\Users\\mh_at\\AppData\\Local\\Temp\\pip-install-6fpsl7b1\\pyedflib_e1c2dcc3a4dc46af9468c24083cbda2b\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base 'C:\Users\mh_at\AppData\Local\Temp\pip-pip-egg-info-48yn2fu3'
-         cwd: C:\Users\mh\AppData\Local\Temp\pip-install-6fpsl7b1\pyedflib_e1c2dcc3a4dc46af9468c24083cbda2b\
-    Complete output (4 lines):
-    No module named 'numpy'
-    *** package "numpy" not found ***
-    pyEDFlib requires a version of NumPy, even for setup.
-    Please get it from http://numpy.scipy.org/ or install it through your package manager.
-    ----------------------------------------
-    ERROR: Command errored out with exit status 4294967295: python setup.py egg_info Check the logs for full command output.
+   a. In Conda command prompt: ``conda create -n myenv python=3.10``
+   b. Activate the virtual environment: ``conda activate myenv``
 
+5. Upgrade your pip: ``python -m pip install --upgrade pip``
+6. Run: ``pip install explorepy``, to install ``explorepy`` from PyPI.
+7. Connect your Explore device from Mac Bluetooth menu and run your Python script.
 
-Solution: Install numpy separately using ``pip install numpy`` and then install ``explorepy``.
+Quick test
+----------
 
----------------------
+* Open the Conda command prompt (if you used pip) or Windows command prompt (if you used the installable file).
+* Activate the virtual environment (this step is only necessary in the Conda command prompt): ``conda activate myenv``
+* Run ``explorepy acquire -n DEVICE-NAME``
+* To stop the command execution, press ``Ctrl+C``
+
+Troubleshooting
+---------------
 
-**4. OSError: A socket operation was attempted to an unreachable network.**
+**1. OSError: A socket operation was attempted to an unreachable network.**
 
 Solution: Ensure that your Explore device is paired with your computer and try again.
 
 ---------------------
 
-**5. ValueError: Error opening socket.**
+**2. ValueError: Error opening socket.**
 
 Solution: Ensure the Bluetooth module of your computer's operating system is on and working.
 
 ---------------------
 
-**6. OSError: The handle is invalid.**
+**3. OSError: The handle is invalid.**
 
 Solution: Ensure the Bluetooth module of your computer's operating system is on and working.
 

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
@@ -11,6 +9,5 @@ PyYAML==6.0.1
 PyYAML==6.0.1
 scipy==1.11.1
 sentry_sdk==1.19.1
-tornado==6.3.2
 sphinx-rtd-theme==1.3.0
 sphinx==7.2.4