Versions Compared

Old Version 25

changes.mady.by.user Chris Rodgers

Saved on

compared with

New Version Current

changes.mady.by.user Josh Siegle

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

IMPORTANT: The Open Ephys GUI documentation has migrated to a new site – please visit https://open-ephys.github.io for the most up-to-date information.

Installing the binaries (64-bit only)

  1. Download this zip filethe Linux binaries from this page.
  2. Drag and drop the downloaded and unzipped folder to the location of your choice, and rename it "Open Ephys."
  3. Open a terminal and set your working directory to the Open Ephys folder.

  4. Type "sudo cp 40-open-ephys.rules /etc/udev/rules.d", then type your password.

  5. Type "service udev restart" on Ubuntu/Debian or "sudo udevadm control --reload-rules" on Fedora/CentOS. These last two steps will allow your computer to communicate with the Open Ephys acquisition board.
  6. Double-click the "open-ephys" executable (or type "./open-ephys" in the terminal) to run the application.

Building from source (32-bit or 64-bit)

Get the code from GitHub

  1. Create a GitHub account if you haven't already.

  2. While logged into your account, go to https://github.com/open-ephys/plugin-GUI and click the "Fork" button in the upper right. You now have your own copy of the GUI repository. Any changes you make will only affect this copy. (More info on forking here.)
  3. Make sure you have git installed (instructions here).
  4. Open a terminal and set your working directory to where you'd like the code to be saved. We recommend creating a directory dedicated to all your coding projects, such as ~/Programming.
  5. Type "git clone https://github.com/yourusername/plugin-GUI.git", where "yourusername" is replaced by your actual GitHub user name. This will download all the code from the repository onto your computer.

Install dependencies

  1. Install the Linux dependencies by running "sudo ./install_linux_dependencies.sh" in the GUI/ Resources/Scripts folder, then type your password.
  2. From the same directory, type "sudo cp 40-open-ephys.rules /etc/udev/rules.d".
  3. Type "sudo service udev restart" on Ubuntu/Debian or "sudo udevadm control --reload-rules" on Fedora/CentOS. These last two steps will allow your computer to communicate with the Open Ephys acquisition board.


Some plugins require additional dependencies to build and work. Specifically, in the case of the ones supplied by default:

  • NetworkEvents and EventBroadcaster require the ZeroMQ library
  • KWIKFormat requires an HDF5 library version greater than 1.8.12 or higherand less than 1.8.21, so you'll like have to build this from source, rather than using a package manager

This section describes the steps needed to install those dependencies on your system.

Install ZeroMQ library

This step is optional, only needed in case you want to install the ZeroMQ related plugins located in their own repository

You will need to install the ZeroMQ library, either from a PPA or from source.

Installing from a PPA. Here are the terminal commands needed to install from a PPA. Note that we specify version 3 of the API ("libzmq3"), which is necessary for the current version of the GUI. These commands work on Ubuntu-like distributions but may need to be modified for others.

sudo add-apt-repository ppa:chris-lea/zeromq
sudo apt-get update
sudo apt-get install libzmq3-dbg libzmq3-dev libzmq3

Installing from source. Alternatively, you can build from source using the instructions from http://zeromq.org/intro:get-the-software, copied below:

  1. Make sure that libtool, pkg-config, build-essential, autoconf, and automakeare installed.
  2. Check whether uuid-dev package, uuid/e2fsprogs RPM or equivalent on your system is installed.
  3. Unpack the ZeroMQ .tar.gz source archive. (from here)
  4. Run ./configure, followed by make.
  5. To install ZeroMQ system-wide run sudo make install.
  6. On Linux, run sudo ldconfig after installing ZeroMQ.

Install the HDF5 library

This step is optional, only needed in case you want to install the HDF5 related plugins located in their own repository.

In order to compile the KWIKFormat pluginand NWBFormat plugins, you need to have the HDF5 library installed. HDF5 is a file format that's optimized for scientific data sets. It is extremely powerful, and offers many advantages over traditional binary formats. The GUI now allows users to save data in the Kwik format, and NWB format which is are based on HDF5.

The plugin requires you to use version 1a specific version of the HDF5 library (≥1.8.12 , or higher, of HDF5. You can try to install from your package manager first, by running "sudo apt-get install libhdf5-serial-dev" or "sudo yum install hdf5-devel". For Ubuntu 16.04 or higher, this should work. However, if you see that this installs version 1.8.11 or lower, you will need to uninstall that older version and install a newer version of HDF5 by following the instructions on the HDF5 websiteand <1.8.21).

To install HDF5 from source, download the source from from this page and (version 1.8.20 recommended) and follow the instructions in the INSTALL file. Briefly:

  • Unzip the source code

  • In the source code directory, run configure by typing the following:

    ./configure --prefix=/usr/local/hdf5 --enable-cxx
  • Run 'make' to compile the code and then 'make check' to check for errors.
  • Run 'sudo make install' and 'sudo make check-install' to install.

Assuming this completed without errors, you're ready to start building the Open Ephys GUI. You'll need to provide the location of the libraries you've just installed by setting the following environment variables before attempting to build the GUI.

export CPLUS_INCLUDE_PATH=/usr/local/hdf5/include
export LIBRARY_PATH=/usr/local/hdf5/lib
export LD_LIBRARY_PATH=/usr/local/hdf5/lib

Build the Open Ephys GUI

Build the main application

Change your current working directory to

GUI/Builds/Linux

  • type "make".

    This will start the process of building the GUI. If it crashes, it probably means you're missing some dependencies. If so, you can use "sudo apt-get install <libraryname>" to install them (assuming you're using Ubuntu or a related distribution). Don't forget to install the dependencies before (see below). If you discover missing dependencies, definitely let us know! 

    If you get an error message about "‘class H5::H5File’ has no member named ‘attrExists’", then you are linking to a version of HDF5 that is 1.8.11 or lower. See above for the section about installing HDF5 from source.

  • If the GUI builds successfully, run the "open-ephys" binary in the GUI/Builds/Linux/build folder.

    •  Build the plugins

    1. Using a console, enter the Builds/Linux directory
    2. Execute the following command: "make -f Makefile.plugins" to build all plugins
    • To clean the plugin build space, type "make -f Makefile.plugins clean"
    • To compile just a specific plugin, type "make -f Makefile.plugins <NameOfThePluginFolder>"
    • Only those plugins that have a Makefile file inside their source directory will be built

    Build

    1. Type "cmake .." to create the build files. You can check the page about creating build files for further details and instructions.

    2. Type "make" to build the main application. If this fails, you are probably missing dependencies (see above, and please let us know if any dependencies are missing from the instructions). 

    3. If the above steps are successful, there will be a compiled binary at Build/Debug/open-ephys. For Release build check the instructions in creating build files.
    4. You can optionally install the open-ephys binary to a directory on your path so that it can be started from any directory by typing "sudo ln -s -f Build/Debug/open-ephys /usr/bin/open-ephys" from the plugin-GUI top-level directory.

    Now you can both use the GUI and make changes to the source code. We recommend reading through the developer documentation before doing so.

    Any changes you commit can be synced with your GitHub repository by typing "git push origin master" from any directory inside your project. If you change something that you think would be useful for others, you can submit a pull request to the Open Ephys version of the GUI.

    Troubleshooting

    • If you're building the library from source, make sure you run "./configure" with the "--enable-cxx" flag. The default is to just install the C libraries.
    • If you get an error message about "‘class H5::H5File’ has no member named ‘attrExists’", then you are linking to a version of HDF5 that is 1.8.11 or lower. See above for the section about installing HDF5 from source.
    • Make sure the HDF5 header and library files are found in directories that are in your PATH and LD_LIBRARY_PATH, respectively. If this doesn't sound familiar to you, you should read up on Linux environment variables.
    • If adding header and library files folder to PATH and LD_LIBRARY_PATH doesn't work, try following steps:(assume your hdf5 is installed to "/usr/local/hdf5")
              $ sudo gedit /etc/environment
      Then add two lines at the end of the file:
              CPLUS_INCLUDE_PATH="/usr/local/hdf5/include"
              LIBRARY_PATH="/usr/local/hdf5/lib"

    Notes on distributions

    Linux Mint 18 / Ubuntu 16.04 - No problems. If you want to use the USB3 version of the Opal Kelly FPGA, you need to copy the rhd2000_usb3.bit file from Resources/Bitfiles to Builds/Linux/build and overwrite the Builds/Linux/build/libokFrontPanel.so with one of the DLLs from the Resources/DLLs/Linux-USB3 folder (select x32 or x64 based on your architecture). See the notes on the "Linux Users and USB3 boards" on the Rhythm FPGA module page


    Notes on distributions

    • Linux Mint 18 / Ubuntu 16.04 - No problems.
    • Linux Mint 13 Maya, Olivia - everything compiles and runs without issues, although installing the distro in the first place can result in nasty problems with NVIDIA drivers.
    • Ubuntu 10.10 and lower - the software will run, but there are problems loading the Opal Kelly DLL, apparently related to the version of gcc. Upgrading gcc won't fix the problem, so we currently don't recommend using older versions of Ubuntu if you want to use the Open Ephys acquisition board.
    • Ubuntu 12.10 and higher - the software seems to run fine.
    • CentOS 6.5 and higher - everything works after commenting out the "@hooks" section of the /usr/share/alsa/alsa.conf file (see discussion here). If you're planning to use the Rhythm FPGA module, make sure you use the CentOS-specific version of the Opal Kelly DLL (found in Resources/DLLs)
    • Debian 7 - You can use the Ubuntu ZeroMQ PPA, just replace wheezy with trusty in the file /etc/apt/sources.list.d/chris-lea-zeromq-wheezy.list. If you have an issue with libc being too old, you can do a partial upgrade to Debian 8 by editing /etc/apt/sources.list and replace all instances of wheezy with jessie. Then sudo apt-get update and sudo apt-get upgrade.

    Common problems

    If the GUI won't start on Linux, it's likely due to problems communicating with the audio hardware. Your computer's sound card is what generates the callbacks that drive data acquisition, so the GUI can't run unless it establishes proper communication with your audio device.

    If you're running the software inside of gdb (which is recommended, at least until all the kinks are worked out), you may see the message "Program received signal SIGSEGV ... juce_String.cpp:203" after printing "Got audio device." With certain hardware, you'll get a segfault before this point is reached. Either you have the wrong drivers (or no drivers) installed, or (more commonly) the audio hardware is in use by another application.

    How to troubleshoot:

    • As a first step, try exiting all other applications. If the audio hardware is being used by another program, the GUI might not be able to communicate with it.
    • Type sudo alsa force-reload in a terminal; this will refresh the sound server, and may fix your problem.
    • Check to see if your audio server (ALSA or PulseAudio) is the latest version. This may require downloading the latest source code and building them from scratch if the package hasn't been updated recently. For more details, check out this discussion.
    • Using the PulseAudio server as sound device might result in problems with triggering block processing in the GUI. This doesn't seem to have an impact on neural data but can lead to unexpected problems. See this thread. Completely removing PulseAudio from Ubuntu, Linux Mint etc might be tricky as it is required by many other applications. Killing PulseAudio doesn't work either as it will restart automatically. However, this small bash script allows running the GUI without PulseAudio:
      #!/bin/bash
echo autospawn = no > $HOME/.config/pulse/client.conf
pulseaudio --kill
      ... run open-ephys ...
      rm $HOME/.config/pulse/client.conf

    If you're using the Intan EVAL board, replace the RHD2000.bit file in the GUI source with main.bit from the Intan Open-Source RHD2000 Interface Software code.