Contributions:DSISerial

From BCI2000 Wiki
Jump to navigation Jump to search

Synopsis

This source module supports the Dry Sensor Interface (DSI) EEG systems made by Wearable Sensing LLC.

Location

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

Versioning

Authors

Jeremy Hill

Version History

  • Revision 1.0 2014/10/21 jhill: first commit

Source Code Revisions

  • Initial development: 4528 (Windows) and 4369 (OSX) but requires some small modifications to the framework's SourceFilter.cpp from later revisions, e.g. r4730, to support the UnfilteredChannels parameter
  • Tested under: 4528 (Windows) and 4369 (OSX)
  • Known to compile under: 4730
  • Broken since: 4731

Functional Description

This source module supports the Dry Sensor Interface (DSI) EEG systems made by Wearable Sensing LLC. It connects to them directly over a serial-port connection (BlueTooth or wired).

Version 1.0 has been tested with DSI7 and DSI24. May also work with the ANI-SI headset by Advanced Neurometrics, inc.

For best results, set the DSISerialPort environment variable, or use the --DSISerialPort command-line parameter on launch, to specify the headset's serial port address (e.g. COM4 on Windows). This allows auto-configuration of most of the necessary BCI2000 parameters using data downloaded from the headset. On Windows, the dialog that allows you to create or edit environment variables is at:

Control Panel->System->Advanced->Environment Variables

Installation

Requires the libDSI dynamic library (.dll or .dylib) corresponding to your platform. This is part of the manufacturer's API. This must be placed in the prog directory. Compiled versions of the dynamic library for 32-bit Windows and 64-bit OSX are supplied in the DSI_API subdirectory, and the appropriate one will be copied to prog during the build process.


Parameters

SampleBlockSize, SamplingRate, SourceCh, SourceChGain, SourceChOffset, TransmitChList

These parameters are the same as for other BCI2000 source modules. For current headsets (as at Oct 2014), the SamplingRate should always be 300. That means SampleBlockSize=9 gives you 30ms blocks, 12 gives you 40ms, 15 gives you 50ms, and so on. The SourceChOffset values should be all 0 and the SourceChGain values should be all 1.

HighPassFilter, LowPassFilter, NotchFilter

These parameters are made available by the SourceFilter framework component. In common with the use of SourceFilter in various other BCI2000 source modules, these parameters allow destructive filtering of the signal, i.e. removal of information before the signal is saved in the file. This can be necessary if your online and offline classification tools do not perform the appropriate filtering (P3SignalProcessing and the P300Classifier GUI do not).

UnfilteredChannels

This parameter is made available by later revisions (r4730+) of the SourceFilter framework component. List any channels here that you want to remain unfiltered (if you are recording the DSI headset's digital trigger channel TRG or the two timing-debugging channels SND and RCV, it is a good idea to include them in this list).

DSISerialPort

This is the port on which the headset connects, e.g. COM4 (Windows example) or /dev/cu.DSI7-0002-BluetoothSeri (Mac OSX example). You may specify this as a command-line parameter to the DSISerial module - for example:

start executable DSISerial --local --DSISerialPort=COM4

Alternatively you may set it permanently as a system environment variable called DSISerialPort. In either of these cases, when you launch BCI2000 it will connect to the headset, retrieve information from it, and configure the default values of various parameters appropriately.

ChannelNames

The ChannelNames parameter is used in all BCI2000 source modules to label the channels. However, it can also play a functional role to specify the order in which the signals are delivered by the headset. If you agree with the headset on what the channels should be called, then you can just use this parameter and leave Montage blank (see the Montage parameter doc below for more details).

Montage

If you want fine control of the sensor montage, or if you disagree with the headset over what the channels should be called, then you can put your own channel names in the ChannelNames parameter, and the corresponding list of identifiers that the headset believes are correct (or just numbers if you prefer) here in the Montage parameter. You can also specify explicit per-channel re-referencing in this parameter. The following specifications all work:

F3    F4    Fz            // the three named channels, referenced to DefaultReference
1     2     3             // the first three sources, whatever they are, referenced to DefaultReference
SRC01 SRC02 SRC03         // the first three sources, whatever they are, referenced to DefaultReference
F3    F4    Fz-F3/2-F4/2  // F3 and F4 referenced to DefaultReference, followed by Fz referenced to the average of F3 and F4 (do not put spaces in the expression, or punctuation other than +-/* )

If the Montage parameter is left blank, the ChannelNames parameter will be used instead - so, if you agree with the headset on nomenclature, you only need to fill out ChannelNames. If both parameters are left blank, all possible signals (potentially including some that are not connected to anything) will be delivered.

To see which channels the headset believes to be connected, and the names it gives them, you can connect automatically as described above above under DSISerialPort, not load any parameter files, and examine the ChannelNames parameter. Alternatively, you can simply ask for a ridiculously-named channel and read the error message.

DefaultReference

This is a specification of the sensor(s) to be used as the EEG reference in places where the Montage parameter does not make this explicit. If your headset has ear reference sensors and you want to use averaged ears as a reference, A1A2 will work for headsets that deliver this as a single source signal, and A1/2+A2/2 (no spaces) will work for headsets that deliver them separately. Likewise, for headsets with mastoid sensors, you could specify M1M2 or M1/2+M2/2 (no spaces) depending on headset model. The module will look for one of these reference possibilities automatically if DefaultReference is left blank. If none of these can be found, the factory reference (usually Pz) will be used, leading to potentially unorthodox-looking EEG signals.

HeadsetDescription

This is for making a note of the headset model. If you connect automatically (see DSISerialPort above) then this will be pre-filled with serial number and firmware version information.

BufferAhead

This specifies the amount of time by which to delay the signal, in order to make its delivery smooth in time, for real-time applications like spelling. If you want to enter a time in milliseconds, remember BCI2000's convention: you have to explicitly append the "ms" to the number, otherwise it will be interpreted as a number of SampleBlocks.

ImpedanceDriverOn

Select this if you want to measure impedances. It injects current at 110Hz and 130Hz. To see the results, you must also check VisualizeImpedances in the "Visualize" tab, and enable "Show Numeric Values" in the resulting visualization window.

VisualizeImpedances

(in the "Visualize" tab)

This opens the window in which impedance values can be viewed (right-click on it and ensure "Show Numeric Values" and "Show Baselines" are enabled). You will not see any informative values, however, unless the ImpedanceDriverOn parameter is also checked. Once the visualization window opens for the first time, right-click on it and enable "Show Numeric Values", or you will not see anything. Enable "Show Baselines" too, to make it clearer.

DSIAPI

(in the "System" tab)

This is the name of, or path to, the libDSI dynamic library that supplies the developer's API for the headset. Usually, it will be filled in with a platform- appropriate default and the library will be expected to be found in the same directory as the source module executable. If you wish to change this, you must specify it on the command line when you launch the module - for example:

start executable DSISerial --local --DSIAPI=some/other/path/to/libDSI.dll

This parameter is displayed in the System tab of the config dialog and is read-only after launch.

DSIAPIVersion

(in the "System" tab)

This read-only parameter is displayed in the System tab of the config dialog, and reflects the version number of the libDSI dynamic library, as specified by the manufacturer.


States

HeadsetAnalogReset

If you set this to 1 while the Running state is also 1, the headset will perform an analog reset.

It can be useful to configure one of the BCI2000 Operator's custom buttons so that it performs an analog reset. This is done in the Preferences dialog of the Operator GUI, by labelling one of the buttons 'Analog Reset' and assigning to it the command: set state HeadsetAnalogReset 1 . Bear in mind that the button will only work when the Start button has been pressed to start a run (otherwise changes in state variables do not get registered).

HeadsetBattery1

Reports the estimated battery level of the first battery in percent.

HeadsetBattery2

Reports the estimated battery level of the second battery in percent. If there is no second battery, value will be 0.

HeadsetAlarm

For debugging.

BufferedSamples

For debugging.


See also

User Reference:Filters, Contributions:ADCs