Install instructions#

BSL requires Python version 3.8 or higher. BSL is available on GitHub and on Pypi.

  • Pypi: Install BSL using pip

    $ pip install bsl
    
  • Conda: A conda-forge distribution is not yet available.

  • GitHub: Clone the main repository and install with pip install .

    $ git clone https://github.com/bsl-tools/bsl
    $ pip install .
    

    For the developer mode, use -e flag: pip install -e ..

Optional dependencies#

BSL installs the following dependencies:

Additional functionalities requires:

The additional functionalities can be installed with the keywords:

  • build for build dependencies

  • doc for doc rendering dependencies

  • externals for pylsl and psychopy

  • parallel for parallel port trigger dependencies

  • style for code-style dependencies

  • test for development test dependencies

  • all for all of th above.

e.g. pip install bsl[parallel] will install BSL with the dependencies for parallel port triggers.

Installing pylsl and liblsl#

By default, BSL is distributed with a recent version of pylsl and liblsl that should work on Ubuntu 18.04, Ubuntu 20.04, macOS and Windows. You can test if your system supports the distributed version by running the following command in a terminal:

$ python -c 'from bsl.externals import pylsl'

If you prefer to use a different version, or if the command above raises an error, pylsl can be installed in the same environment as BSL. BSL will automatically select pylsl and will prefer the version installed in the same environment above the version distributed in bsl.externals.

pylsl requires a binary library called liblsl to operate. The binary library may or may not have been downloaded alongside pylsl. To test if an install of pylsl is working, use the following command in a terminal:

$ python -c 'import pylsl'

If this command did not raise an error, congratulation, you have a working install of pylsl! However, if an error is raised, please refer to the instructions below or to the LabStreamingLayer Slack.

Linux#

Start by installing libpugixml-dev, a light-weight C++ XML processing library.

$ sudo apt install -y libpugixml-dev

Fetch the correct binary from the liblsl release page. If your distribution is not available, the binary library must be build. At the time of writing, the binaries for Ubuntu 18.04 (bionic) and for Ubuntu 20.04 (focal) are available. Install the downloaded .deb library with:

$ sudo apt install ./liblsl.deb

macOS#

Fetch the correct binary from the liblsl release page and retrieve the .dylib binary library. Create an environment variable named PYLSL_LIB that contains the path to the downloaded binary library.

Alternatively, homebrew can be used to download and install the binary library with the command:

$ brew install labstreaminglayer/tap/lsl

Windows#

Fetch the correct binary from the liblsl release page and retrieve the .dll binary library. Create an environment variable named PYLSL_LIB that contains the path to the downloaded binary library.

Installing PsychoPy#

The parallel port trigger can either use an on-board parallel port, or an Arduino to ParallelPort converter connected via USB. The on-board parallel port requires the psychopy.parallel module. By default, BSL is distributed with a recent version of psychopy.parallel that should work on most systems.

If you prefer to use a different version, psychopy can be installed in the same environment as BSL. BSL will automatically select psychopy and will prefer the version installed in the same environment above the version distributed in bsl.externals.

Test the installation#

To test the installation, you can run a fake stream with a StreamPlayer and display it with a StreamViewer.

  • Download a sample bsl.datasets:

    import bsl
    dataset = bsl.datasets.eeg_resting_state.data_path()
    print (dataset)  # displays the path to the -raw.fif dataset
    
  • Run a StreamPlayer either from a python console or from terminal using the downloaded sample dataset resting_state-raw.fif.

    In a python console:

    import bsl
    dataset = bsl.datasets.eeg_resting_state.data_path()
    player = StreamPlayer('TestStream', dataset)
    player.start()
    

    In a terminal, navigate to the folder containing the dataset (~/bsl_data/eeg_sample):

    $ bsl_stream_player TestStream resting_state-raw.fif
    
  • Run a StreamViewer from a different terminal:

    $ bsl_stream_viewer
    

The StreamViewer should load and display:

StreamViewer