Difference between revisions of "Contributions:DSISerial"
|Line 31:||Line 31:|
the <tt>libDSI</tt> dynamic library (<tt>.dll</tt> or <tt>.dylib</tt> ) corresponding to your platform. This is part of the manufacturer's API. must be placed in the <tt>prog</tt> directory. Compiled versions of the dynamic library for 32-bit Windows and 64-bit OSX are supplied in the <tt>DSI_API</tt> subdirectory, and the appropriate one will be copied to prog during the build process.
Latest revision as of 23:18, 23 November 2014
- 1 Synopsis
- 2 Location
- 3 Versioning
- 4 Functional Description
- 5 Installation
- 6 Parameters
- 6.1 SampleBlockSize, SamplingRate, SourceCh, SourceChGain, SourceChOffset, TransmitChList
- 6.2 HighPassFilter, LowPassFilter, NotchFilter
- 6.3 UnfilteredChannels
- 6.4 DSISerialPort
- 6.5 ChannelNames
- 6.6 Montage
- 6.7 DefaultReference
- 6.8 HeadsetDescription
- 6.9 BufferAhead
- 6.10 ImpedanceDriverOn
- 6.11 VisualizeImpedances
- 6.12 DSIAPI
- 6.13 DSIAPIVersion
- 7 States
- 8 See also
This source module supports the Dry Sensor Interface (DSI) EEG systems made by Wearable Sensing LLC.
- 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
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
The DSISerial source module requires the libDSI dynamic library (a .dll or .dylib file) corresponding to your platform. This is part of the manufacturer's API. The file 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.
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).
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).
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.
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).
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 use the Montage parameter to give the corresponding list of identifiers that the headset believes are correct (or just numbers if you prefer—but see the caveat below). You can also specify explicit per-channel re-referencing in this parameter. The following specifications all work:
F3 F4 Fz // the three named sensor signals, 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.
Note that the manufacturer's API/driver makes the distinction between Sources and Channels. Channels are what the BCI2000 module as a whole delivers: they are time-series whose positive and negative components (signal and reference) can be explicitly specified, thereby making re-referencing easy. However, when measuring impedances, or when you specify the individual positive and negative components that constitute a Channel, you're dealing at a lower level with Sources. Sources are the time-series that the headset firmware delivers natively. Some Sources correspond to referential EEG sensors and some do not. The Sources that correspond to referential EEG sensors deliver signals that are expressed relative to the factory reference, which is typically Pz. Therefore, a raw Source signal would look somewhat unorthodox (for example, you might see some occipital alpha in the signal, even in frontal Sources). Numeric entries in the Montage parameter denote Sources in the order that the firmware happens to deliver them, but some Sources do not have numbers—for example, the Source called 'Pz' is a numberless virtual Source (its content is simply a flat zero-volt line, since Pz is the reference sensor). Support for numeric entries in the Montage parameter is a last-resort fallback for cases where the headset firmware contains no information about Source names/locations (but you should contact the manufacturer, in this case, and follow their instructions to remedy the situation). If you found this paragraph confusing, then long story short: compose your Montage parameter out of names, not numbers, if at all possible.
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. If DefaultReference is left blank, the module will look for one of these ear/mastoid reference possibilities automatically (if none of them can be found, a warning will be issued and the factory reference—usually Pz—will be used, leading to potentially unorthodox-looking EEG signals).
The DefaultReference is only applied to signals that the headset flags as being part of the referential EEG montage—it will not be applied to auxiliary bipolar sensors, to the trigger TRG, or to the clock signals SND and RCV.
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.
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.
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.
(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.
(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.
(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.
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).
Reports the estimated battery level of the first battery in percent.
Reports the estimated battery level of the second battery in percent. If there is no second battery, value will be 0.