Installation
Octopus Sensing supports multiple device modules. Because everyone might not need all the modules, they are not installed by default. You can install only the modules you need.
When you install octopus-sensing package, only the core package is installed. You need to install the device modules you need separately.
Pre-requirements
Some devices need additional system dependencies to be installed on your machine.
stimuli, windows, and gui modules (for scenario designing) need the following dependencies:
On Debian-based Gnu/Linux distributions (like Ubuntu), run:
sudo apt-get install libcairo2-dev libgirepository1.0-dev
On MacOS, you can use brew to install the dependencies:
brew install cairo pygobject3
camera (for video recording) module needs gstreamer package. Use one of the following commands to install it.
sudo apt-get install gstreamer-1.0 (for Debian-based Gnu/Linux distributions)
brew install gstreamer (for MacOS)
lsl (for Lab Streaming Layer support) module needs liblsl package. Refer to its official documentation: liblsl.
Installation using Pipenv (All Platforms)
We recommend using a package manager like Pipenv or a virtual environment instead of globally installing Octopus Sensing using pip to prevent package conflicts. To do so, follow these commands. (This is same as what the Quick start script does.)
mkdir my-awesome-project
cd my-awesome-project
# Or replace it with your python version
pipenv --python python3.12
pipenv install octopus-sensing
This installs Octopus Sensing inside the virtual environment created by Pipenv. You need to use pipenv to run your code. For example:
pipenv run python main.py
The octopus-sensing package is only the core module. To install device modules, use the following command:
pipenv install octopus-sensing[<device_module_name>,<another_device_module_name>,...]
# Example:
pipenv install octopus-sensing[camera,brainflow]
Refer to Pipenv website for more info.
Installation using Poetry (All Platforms)
You can also use Poetry to manage your dependencies and virtual environment. To do so, follow these commands:
mkdir my-awesome-project
cd my-awesome-project
poetry init # Follow the prompts to create pyproject.toml
# Or if you want to use a specific python version, run `poetry env use python3.12` before the next command
poetry add octopus-sensing
This installs Octopus Sensing inside the virtual environment created by Poetry. You can use poetry run to run your code. For example:
poetry run python main.py
The octopus-sensing package is only the core module. To install device modules, use the following command:
poetry run pip install "octopus-sensing[<device_module_name>,<another_device_module_name>,...]"
# Example:
poetry run pip install ".[camera,brainflow]"
Refer to Poetry website for more info.
Virtual environment (All Platforms)
We highly recommend using a virtual environment to keep your global Python environment clean. You can also use a package manager (see next sections) that creates a virtual environment and handles dependencies for you.
In this section, we use venv from Python’s standard library to create a virtual environment. Create a directory for your project and run the following commands:
mkdir my-awesome-project
cd my-awesome-project
python3 -m venv .venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
On Windows, you might need to use python and pip commands instead of python3 and pip3.
Now you can use pip to install octopus-sensing and its device modules inside this virtual environment:
pip install octopus-sensing
For intalling device modules, use the following command:
pip install octopus-sensing[<device_module_name>,<another_device_module_name>,...]
# Example:
pip install octopus-sensing[camera,brainflow]
To see a list of available device modules, see installation#available-device-modules.
Installation using pip (All Platforms)
You can use pip to install octopus-sensing globally (not recommended) as simple as:
(You might need to replace pip3 with pip depending on your system.)
Then it can be imported like:
import octopus_sensing
To install optional device modules, use the following command:
pip install octopus-sensing[<device_module_name>,<another_device_module_name>,...]
# Example:
pip install octopus-sensing[camera,brainflow]
Installation from source (All Platforms)
If you want to compile it from source for development purposes or to have the un-released features, please refer to Development.
Troubleshooting
Pip cannot install PyGObject on Windows. If users want to use octopus-sensing.stimuli or octopus-sensing.windows packages, they need to install it manually themselves. See PyGObject documentation to know how to install PyGObject on Windows.
If you saw Namespace Gst not available (or similar) while importing octopus_sensing.stimuli package, you need to install gstreamer package on your machine. On Ubuntu run sudo apt-get install gstreamer-1.0.
Available Device Modules
The following devices are installed along with the core package:
openvibe: For OpenViBE acquisition server supportsocket network device: For sending triggers to other softwares via socket connectionhttp network device: For sending triggers to other softwares via HTTP requeststest device: A simulated device for testing purposes
The following device modules are available. You can install them using pip or pipenv as shown above.
shimmer3: For Shimmer3 GSR and PPG sensor supportcamera: For video recording using your computer’s camerabrainflow: For supporting multiple biosensors supported by BrainFlow libraryopenbci: (Deprecated. Use BrainFlow instead) For OpenBCI EEG headset supportaudio: For audio recording from microphonelsl: For Lab Streaming Layer supporttobiiglasses: For Tobii Glasses eye-tracker supportgui: For all GUI components: stimuli, windows, and questionnaire