Difference between revisions of "Contributions:Blackrock"

From BCI2000 Wiki
Jump to: navigation, search
(Parameters)
(NSPInstances)
 
Line 97: Line 97:
  
 
===NSPInstances===
 
===NSPInstances===
This parameter determines how many NSPs you intend to record from.  Setting this parameter to '2' enables the hardware synchronization described earlier, and using more than 2 NSPs is untested.
+
This parameter determines how many NSPs you intend to record from.  This is the other parameter that you might want to play with, but only if you have more than one NSP.  Setting this parameter to '2' enables the hardware synchronization described earlier, and using more than 2 NSPs is untested.
  
 
===DigitalOutput===
 
===DigitalOutput===

Latest revision as of 00:51, 27 March 2016

Synopsis

The Blackrock acquisition module enables signal acquisition from Blackrock Microsystems Cerebus and Neuroport acquisition hardware through the "cbsdk" C++ API.

Location

http://www.bci2000.org/svn/trunk/src/contrib/SignalSource/Blackrock

Versioning

Author

Griffin Milsap (griffin.milsap@gmail.com)

Version History

  • V3.2 -- Enabled Firmware 6.05+ to function through a silly hack
  • V3.1 -- Digital output implementation
  • V3.0 -- Multi-NSP support with hardware synchronization
  • V2.0 -- Auto-config based implementation, enhanced usability and stability
  • V1.0 -- Analog Signal Acquisition and Digital Filtering Functionality

Source Code Revisions

  • Initial development: 4365
  • Tested under: 5304
  • Known to compile under: 5304
  • Broken since: N/A

Functional Description

The Blackrock source module is used for acquiring recordings from Blackrock NSP systems using CBSDK as provided through official Blackrock channels, or through CereLink (https://github.com/dashesy/CereLink). It also happens to be one of the first BCI2000 SignalSource modules to function under Linux. This documentation explains the parameterization and specifics on how to set up the system.

System Setup

Building the Blackrock module should copy .bat files for standard experiments into the batch directory.

Ensure your machine is connected to a switch or router that the NSP is also connected to. This module communicates to the NSP using UDP, and is susceptible to packet loss. Ensure you have a commercial grade switch to avoid dropping packets. You can also use a crossover cable to connect directly to the NSP, but this prevents other computers from receiving data from the NSP.

You will also need to change your interface's network configuration (Windows):

  • IP address: 192.168.137.XXX where XXX is less than 128. This number needs to be below 16 and not 10. Ensure no other computers have this same address on this switch.
  • Subnet Mask: 255.255.255.0
  • Default Gateway: <Blank>

To test your network configuration, open a terminal or command prompt and type ping 192.168.137.128. This is the NSP's default network address. If you can ping the NSP, you should be able to run the module.

For more details on the network setup for a multi-NSP system, please refer to the official NSP documentation

Windows

This should work out of the box with standard parameters.

Linux

If you encounter a segfault or error message on SetConfig, one of the most common issues is with permissions. NSP 6.03 and previous opens port 1002 and 1001 to communicate packets. This was a rather unfortunate choice, as administrative privileges are required in order to open ports below 1024 on standard *nix systems. NSP Firmware 6.04+ uses higher port numbers to avoid this problem. If you're running 6.03 firmware or below, you will need to start the Blackrock module with administrative privileges. One way to accomplish this is to comment out the "Start Blackrock" line in your batch file, and launch the Blackrock module from a separate terminal with "sudo ./Blackrock", executed from the bci2000/prog directory.

You may also receive an error complaining about the size of your network buffer size:

   Socket memory assignment error
   Consider using sysctl -w net.core.rmem_max=8388608
   or sysctl -w kern.ipc.maxsockbuf=8388608

Depending on your operating system (OSX or your favorite flavor of Linux) you should execute one of these commands with administrative privileges. You will need to do this once every time the computer reboots. There may be a way to do this on boot using some config file somewhere. If you have any ideas, edit this section. net.core.rmem_max is the proper key to use for Fedora 17.

Blackrock Firmware/CBSDK/Cerelink Notes

When you install the Central "NeuroPort Windows Suite" software on a PC, it comes with a firmware, and a CBSDK distribution. Unfortunately, these components have individual versioning. The version of Central appears to match the NSP Firmware version. Most of the development of this module has been done with Central/NSP Firmware 6.04.03. CBSDK (hardware library) 3.9 is the compatible SDK for this particular firmware/version. You can find out what version of central/firmware you're running by clicking the Windows->About Cerebus Suite button in Central when the NSP is on and active.

The BCI2000 Blackrock module relies on cbsdk.dll to operate. The cbsdk.dll itself relies on a few Qt dlls (QtCore4.dll, QtXml4.dll) to function. As a best-practice, you shouldn't copy these dlls into the BCI2000 prog directory, but instead add the directories that these files are found in to the system path. Here is a helpful tutorial for how to change the system path in Windows (you'll need to restart BCI2000 after doing it). You'll want to add:

  • C:\Program Files (x86)\Blackrock Microsystems\NeuroPort Windows Suite\cbsdk\lib (for cbsdk.dll)
  • C:\Program Files (x86)\Blackrock Microsystems\NeuroPort Windows Suite (for the Qt dlls)

To further complicate things, a GPLV2 spinoff/fork of CBSDK is available in the Cerelink repository and is maintained by a non-Blackrock employee. The source code there is available under GPLV2 (still copyrighted by Blackrock Microsystems), but it should be considered a fork of the official CBSDK code provided by Blackrock. The code in CereLink currently contains a 3.9 compatible hardware library, and you *can* compile a cbsdk.dll from the code in this repository. This dll will be similar, but not identical to the official 3.9 release. If you want to rock a Linux Blackrock Source module, you'll need to compile this repository to generate a cbsdk.so for BCI2000 to use. Blackrock doesn't provide an official Linux release.

Unfortunately, Blackrock introduced a non-backward-compatible change to the ABI between CBSDK 3.9 and 3.10. CBSDK 3.10 is *required* for firmware 6.05.XX+. Because this change isn't backward compatible, we had to make a choice as to what protocol version the module will currently support. As of r5304, the Blackrock module is using CBSDK (hardware library) 3.9 and is only compatible with firmware version 6.04 and below. There is an experimental "hack" that enables this module to work with firmware 6.05+, but use it at your own risk. It seems to be quite stable, but it could result in undefined behavior. Consider yourself warned.

To make this module ONLY work with Firmware 6.05+:

  • Download BCI2000 SVN HEAD and use CMake to generate the build files, as detailed in Programming Reference:Build System. Make sure you enable Contributed source modules.
  • Edit src/contrib/SignalSource/Blackrock/lib/cbhwlib.h and make sure cbVERSION_MINOR is set to 10 (instead of 9)
  • Recompile the Blackrock module.

The module will eventually default to using official hardware library 3.10 once the author updates his system to firmware 6.05.

Multi-NSP Synchronization

The NSP systems can be daisy-chained to provide access to more channels and more fun. Although a hardware "sync" cable is provided by Blackrock Microsystems, the authors are a bit confused as to what it actually does, because it does not appear to synchronize the systems on a sample by sample basis. CBSDK opens a separate instance for each NSP and the module is just communicating with both the systems simultaneously and attempting to match up the data streams as closely as possible. To facilitate this, there is a hardware synchronization built into the module which requires a bit of hardware setup to use. This system pulses one of the digital outputs high and provided that output is connected to the correct analog input on both NSPs, the streams will be resynchronized every time NSPSyncState is set to a value of 1.

In order to enable NSP Hardware Synchronization:

  • Connect Digital Output 1 on any one of the NSPs to Analog Input 16 on all the NSPs. You'll probably need BNC T-Connectors for this.
  • Ensure Analog Input 16 is in the same SampleGroup as the channels you wish to acquire using BCI2000.
  • If BCI2000 recognizes that Analog Input 16 is being acquired at the correct SamplingRate on all NSPs and that there is more than 1 NSP, hardware synchronization will occur automatically upon SetConfig.

A hardware synchronization procedure strobes digital output 0 on the NSPs, consumes 100 ms worth of samples, then realigns the ringbuffers for each NSP to the rising edge of analog input 16. A log message will tell you which instance was corrected by how many samples. Throughout the course of a recording, dropped packets and clock skew will slowly throw the NSPs out of synchronization. On the author's system, it takes about 10 minutes for a 100 ms desynchronization to occur. At any time, NSPSyncState can be set to 1 (Especially handy as an operator function button -- see User_Reference:Operator_Module#Function_Buttons), and the re-synchronization procedure will consume 100ms of data and resynchronize. Its important to keep in mind that if the desynchronization is already greater than 100ms, the procedure will fail, due to there not being a rising edge in one of the signals.

Parameters

This module used to fully-configure the NSPs directly from BCI2000. The NSP system is sooo configurable that this became a big source of headaches. In the most recent version, you will configure the recording setup using the Blackrock "Central" software, and BCI2000 will auto-configure to match the SampleGroup dictated by the SamplingRate parameter. The NSPs always acquire data at 30Khz, but channels can be added to a SampleGroup which is downsampled (with antialiasing) in real-time by the NSP before being streamed over ethernet to receivers. You can add channels to these channel groups in the Central software by enabling continuous streaming on individual channels, and selecting the sampling rate.

The following parameters are available for configuring the Blackrock source module. You will find these parameters in the Source -- Signal Properties section.

SamplingRate

In standard use, this is one of two parameters you need to play with. This is where you select the sample group you want BCI2000 to record from. Valid sampling rates are 500 Hz, 1000 Hz, 2000 Hz, 10000 Hz, and 30000 Hz. When the SetConfig button is pressed, BCI2000 will collect all channels that are members of that SampleGroup and configure to acquire from those channels.

SampleBlockSize

There are a bunch of default SampleBlockSizes for the different SamplingRates, which you will get if you use 'auto' as the value of this parameter. They are roughly set to clock BCI2000 at about 50 Hz. Depending on the processing you're doing, you may want to lengthen the block size. Any number of samples is valid here: even 1. You may want to not do that, however. Clocking the system above 50 Hz is a bad choice. The default block size for different sample groups is as follows:

   int gGroupRates[] = { 0, 500, 1000, 2000, 10000, 30000 }; // samples per second
   int gBlockSizes[] = { 0, 10,  20,   40,   200,   600   }; // samples per block (50 Hz)

ChannelNames

These will be pulled from the Channel Label property set in the Central Software. Use 'auto' to configure this parameter.

SourceChOffset/SourceChGain

Again, these are populated automatically. Use 'auto' to configure this parameter.

NSPInstances

This parameter determines how many NSPs you intend to record from. This is the other parameter that you might want to play with, but only if you have more than one NSP. Setting this parameter to '2' enables the hardware synchronization described earlier, and using more than 2 NSPs is untested.

DigitalOutput

This parameter specifies a matrix of expressions that will be evaluated once per SampleBlock to set the digital output channels. Each row of this matrix defines an expression for one digital output. If that expression evaluates true for that block, the associated digital output will be set high, and vice versa for false. See User Reference:Expression Syntax for help with BCI2000 Expressions. An example matrix is provided below.

   Instance Output Expression
   1        1      StimulusCode!=0 // Will set output 1 on NSP1 high whenever a stimulus is on screen
   2        3      KeyDown!=0 // Will set output 3 on NSP2 high whenever a key is pressed.

States

NSPSyncState

This state records the current status of the multi-NSP hardware synchronization described earlier.

See also

User Reference:Filters, Contributions:ADCs