Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@cboulay
cboulay committed Aug 13, 2023
1 parent 4ceaacd commit 398ae6d
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 38 deletions.
61 changes: 42 additions & 19 deletions BUILD.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,30 @@
# CBSDK Build Instructions

Most users will only need to download directly from the [releases page](https://github.com/CerebusOSS/CereLink/releases).

Other users who just want the CLI commands, or if the below instructions aren't working for you, should check out the GitHub Actions [workflow scripts](https://github.com/CerebusOSS/CereLink/blob/master/.github/workflows/build_cbsdk.yml).

Continue here only if you want to build CereLink (and cerebus.cbpy) from source.

## Requirements

We assume you already have a build environment with an appropriate C++ toolchain and CMake installed.

### Qt6

We are working on eliminating the Qt dependency. For now, you must install it.

* Windows:
* [CMake](https://cmake.org/download/)
* Make sure to add cmake to the path.
* [Qt6](https://www.qt.io/download-open-source/)
* Using the installer, choose the most recent non-preview libraries that match your compiler.
* [Qt6](https://www.qt.io/download-open-source/)
* Get the latest 6.x LTS (last tested with 6.5.2)
* The version of the library you download should match your compiler (MSVC or MinGW)
* Mac - Use [homebrew](https://brew.sh/)
* `brew install cmake qt`
* `brew install qt`
* Ubuntu (/Debian)
* `sudo apt-get install build-essential cmake qt6-default`
* Ubuntu 18.04 not supported.
* `sudo apt-get update -y`
* Ubuntu 20.04 requires a backport ppa: `sudo add-apt-repository ppa:okirby/qt6-backports`
* `sudo apt-get install qt6-base-dev`

### Matlab (optional)

Expand All @@ -21,30 +35,32 @@ If you want to build the Matlab wrappers then you will need to have Matlab devel
Here are some cmake one-liners that work if your development environment happens to match perfectly. If not, then modify the cmake options according to the [CMake Options](#cmake-options) instructions below.

* Windows:
* `cmake -B build -S . -G "Visual Studio 16 2019" -DCMAKE_PREFIX_PATH=C:\Qt\6.4.2\msvc2019_64\lib\cmake\Qt6 -DBUILD_STATIC=ON -DBUILD_CLI=ON -DCMAKE_INSTALL_PREFIX=install`
* `cmake -B build -S . -G "Visual Studio 16 2019" -DCMAKE_PREFIX_PATH=C:\Qt\6.5.2\msvc2019_64 -DBUILD_STATIC=ON -DCMAKE_INSTALL_PREFIX=../install -DCPACK_PACKAGE_DIRECTORY=../dist`
* MacOS
* `cmake -B build -S . -DQt6_DIR=$(brew --prefix qt6)/lib/cmake/Qt6 -DCMAKE_INSTALL_PREFIX=install`
* If you are going to use the Xcode generator then you also need to use the old build system: `-G Xcode -T buildsystem=1`
* `cmake -B build -S . -DQt6_DIR=$(brew --prefix qt6)/lib/cmake/Qt6 -DCMAKE_INSTALL_PREFIX=${PWD}/install -DCPACK_PACKAGE_DIRECTORY=${PWD}/dist`
* If you are going to use the Xcode generator then you also need to use the old build system. Append: `-G Xcode -T buildsystem=1`
* Linux
* `cmake -B build -S . -DCMAKE_INSTALL_PREFIX=install`
* `cmake -B build -S . -DCMAKE_INSTALL_PREFIX=${PWD}/install -DCPACK_PACKAGE_DIRECTORY=${PWD}/dist`

Then follow that up with:
Then follow that up with (append a processor # after the -j to use more cores):
* `cmake --build build --config Release -j`
* `cmake --build build --target=install --config Release -j`

And optionally:
And optionally, to build zips or debs:
* `cmake --build build --target package --config Release -j`

The build products should appear in the CereLink/dist directory.
The build products should appear in the CereLink/install or CereLink/build/install directory.

Note: This may generate an error related to the CLI builds. Please see further instructions in the cli\README.md
Note: This may generate an error related to the CLI builds. Please see further instructions in the [cli\README.md](./cli/README.md).

### CMake Options

* `-G <generator name>`
* Call `cmake -G` to see a list of available generators.
* `-DQt6_DIR=<path/to/qt/binaries>/lib/cmake/Qt6`
* This is the path to the folder holding Qt6Config.cmake for the compiler+architecture you are using.
* or `-DCMAKE_PREFIX_PATH=<path/to/qt/binaries>`
* In my experience, Windows' CMake sometimes cannot find all the Qt modules when using the above option, but it usually works with the change to the prefix path.
* `-DBUILD_STATIC=ON`
* Whether to build cbsdk_static lib. This is required by the Python and Matlab wrappers.
* `-DBUILD_CBMEX=ON`
Expand All @@ -54,21 +70,28 @@ Note: This may generate an error related to the CLI builds. Please see further i
* `-DBUILD_TEST=ON`
* `-DBUILD_HDF5=ON`
* Should only build if HDF5 found, but I have had to manually disable this in my builds.
* `DMatlab_ROOT_DIR=<path/to/matlab/root>`
* `-DMatlab_ROOT_DIR=<path/to/matlab/root>`
* This should only be necessary if cmake cannot find Matlab automatically.
* e.g.: `-DMatlab_ROOT_DIR=/Applications/MATLAB_R2016a.app/`
* Alternatively, you could populate the ../Matlab directories with the Matlab include and lib files.
* `-DCBMEX_INSTALL_PREFIX` can be used to install cbmex to given directory.
* `-DBUILD_CLI=ON`
* to build the C#/CLI bindings. Buggy.

# cerebus.cbpy (Python lib) Build Instructions

* Open a Terminal or Anaconda prompt and activate your Python environment.
* Your Python environment must already have Cython, numpy, pip, and wheel installed.
* Your Python environment must match that of the eventual machine that will run the package, and it must already have Cython, numpy, pip, and wheel installed.
* We do not set these as explicit dependencies on the package to avoid bundling them
* Change to the CereLink directory.
* Set the QTDIR environment variable: `set QTDIR=C:\Qt\6.4.2\msvc2019_64`
* Make sure the CereLink Visual Studio project is closed.
* `pip install .`
* If you haven't already, build CereLink following the above instructions.
* Set the QTDIR environment variable:
* Windows: `set QTDIR=C:\Qt\6.5.2\msvc2019_64`
* Mac: `set QTDIR==$(brew --prefix qt6)`
* Windows: Close Visual Studio.
* Install locally: `pip install .`
* or, if you are making a wheel to bring to another machine,
* activate an environment matching the target machine,
* `pip wheel . -w dist/`
* The wheels will be in the `dist` folder.
* See the [Wiki](https://github.com/CerebusOSS/CereLink/wiki/cerebus.cbpy) for more information.
51 changes: 32 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,52 @@
CereLink
========
# CereLink

Blackrock Microsystems Cerebus Link

The software develoment kit for Blackrock Microsystems neural signal processing hardware includes:
* c++ library (cbsdk): cross platform library for two-way communication with hardware
* MATLAB/Octave wrapper (cbmex/cboct): MATLAB executable (mex) to configure and pull data using cbsdk
* Python wrapper (cerebus.cbpy): Python binding for cbsdk to configure, pull data, and receive callbacks
* File conversion utility (n2h5): Converts nsx and nev files to hdf5 format

c++ library (cbsdk): cross platform library for two-way communication with hardware
Downloads are on the [releases page](https://github.com/CerebusOSS/CereLink/releases).

MATLAB/Octave wrapper (cbmex/cboct): MATLAB executable (mex) to configure and pull data using cbsdk
## Build

Python wrapper (cerebus.cbpy): Python binding for cbsdk to configure, pull data, and receive callbacks
The BUILD.md document has the most up-to-date build instructions.

File conversion utility (n2h5): Converts nsx and nev files to hdf5 format
## Usage

Downloads are on the [releases page](https://github.com/CerebusOSS/CereLink/releases).
### Testing with nPlayServer

# Project wiki
On Windows, download and install the latest version of Cerebus Central Suite from the [Blackrock Neurotech support website (scroll down)](https://blackrockneurotech.com/support/).

https://github.com/CerebusOSS/CereLink/wiki
#### Testing with a localhost client

# Build
After installing, navigate an explorer Window to `C:\Program Files\Blackrock Microsystems\Cerebus Central Suite\` and run `runNPlayAndCentral.bat`. This will run a device simulator (nPlayServer) and Central on the localhost loopback. cbsdk / cerebus / cbmex should be able to connect as a Slave (Central is the Master) to the nPlay instance.

The BUILD.md document has the most up-to-date build instructions.
#### Testing with a networked client

# Usage
If you want to test using nPlayServer on one computer with CereLink on a secondary computer, then you will have to run nPlayServer with special settings. It will also make your life easier if you change the IP address of the network adapter of your Windows machine to mimic that of a Cerebus device (192.168.137.128 for NSP or 192.168.137.200 for Gemini Hub).

## Testing on nPlayServer
> Run `nPlayServer --help` to get a list of available options.
On Windows, download and install the latest version of Cerebus Central Suite from the [Blackrock Neurotech research/support/software](https://blackrockneurotech.com/research/support/#manuals-and-software-downloads) website.
After installing, navigate an explorer Window to `C:\Program Files\Blackrock Microsystems\Cerebus Central Suite\` and run `runNPlayAndCentral.bat`. This will run a device simulator (nPlayServer) and Central on the localhost loopback. cbsdk / cerebus / cbmex should be able to connect as a Slave (Central is the Master) to the nPlay instance.
* Emulating Legacy NSP: `nPlayServer -L --network inst=192.168.137.128:51001 --network bcast=192.168.137.255:51002`
* Emulating Gemini Hub: `nPlayServer -L --network inst=192.168.137.200:51002 --network bcast=192.168.137.255:51002`

### cerebus.cbpy

* Download a wheel from the releases page or [build it yourself](BUILD.md#cerebuscbpy-python-lib-build-instructions).
* Activate a Python environment with pip, Cython, and numpy
* Install the wheel: `pip install path\to\filename.whl`
* Test with `python -c "from cerebus import cbpy; cbpy.open(parameter=cbpy.defaultConParams())"`
* You might get `RuntimeError: -30, Instrument is offline.`. That's OK, depending on your device and network settings.

## Getting Help

## cerebus.cbpy
First, read the frequently asked questions and answers in the [project wiki](https://github.com/CerebusOSS/CereLink/wiki).

To install the package, activate your Python environment and install the wheel downloaded from the release page that matches your NSP firmware version, your target platform, and Python version. If there is not a matching wheel on the Releases page then you will have to [build](BUILD.md) it yourself.
Second, search the [issues on GitHub](https://github.com/CerebusOSS/CereLink/issues).

When installing cerebus.cbpy, the main numpy and Cython dependencies should install automatically.
Finally, open an issue.

At runtime, the Qt libraries are also required. On Linux and Mac, it is usually sufficient to install Qt6 at the system level with apt or homebrew. In Windows, it _should_ be sufficient to have Qt6Core.dll on the path somewhere, but I've found this to be unreliable depending on the Python environment manager. The most reliable approach is to copy Qt6Core.dll into the same folder as your .pyd file, which should be in `path/to/python/env/Lib/site-packages/cerebus`.
This is a community project and is not officially supported by Blackrock Neurotech.

0 comments on commit 398ae6d

Please sign in to comment.