BCI2000 Wiki - User contributions [en]

Contributions:Blackrock

2016-03-27T00:51:03Z

Gmilsap: /* NSPInstances */

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

==Location==
http://{{SERVERNAME}}/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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ 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. [https://www.java.com/en/download/help/path.xml 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 [http://github.com/dashesy/CereLink 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 [http://www.youtube.com/watch?v=2FM3Em7FIOc 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]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:Blackrock

2016-03-27T00:49:47Z

Gmilsap: /* Parameters */

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

==Location==
http://{{SERVERNAME}}/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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ 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. [https://www.java.com/en/download/help/path.xml 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 [http://github.com/dashesy/CereLink 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 [http://www.youtube.com/watch?v=2FM3Em7FIOc 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. 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]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:Blackrock

2016-03-27T00:46:34Z

Gmilsap: /* Multi-NSP Synchronization */ clarification

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

==Location==
http://{{SERVERNAME}}/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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ 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. [https://www.java.com/en/download/help/path.xml 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 [http://github.com/dashesy/CereLink 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, BCI2000 will auto-configure everything based on the currently selected SampleGroup. 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 [http://www.youtube.com/watch?v=2FM3Em7FIOc 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. 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]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:Blackrock

2016-03-27T00:40:09Z

Gmilsap:

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

==Location==
http://{{SERVERNAME}}/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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ 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. [https://www.java.com/en/download/help/path.xml 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 [http://github.com/dashesy/CereLink 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 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, BCI2000 will auto-configure everything based on the currently selected SampleGroup. 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 [http://www.youtube.com/watch?v=2FM3Em7FIOc 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. 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]]

[[Category:Contributions]][[Category:Data Acquisition]]

Programming Howto:SVN Client Setup

2014-07-16T20:00:50Z

Gmilsap: /* Checking out older versions */

== Setting up TortoiseSVN to access the BCI2000 code repository ==
To set up TortoiseSVN and download the BCI2000 source code to your computer, follow these steps:
* Download the latest stable version from http://tortoisesvn.net/, and execute the installer program. This page has been written for version 1.40, but should be rather independent of TortoiseSVN's version number.
* Create or pick an empty folder located on your machine’s harddrive. This will hold your working copy of the BCI2000 source tree, in an automatically created subfolder called "BCI2000."
* Right-click the folder you picked in the last step. From the context menu, choose the "SVN Checkout..." option – a dialog window appears.
* In the dialog window, enter the repository URL: <code><nowiki>http://www.bci2000.org/svn/tags/releases/current</nowiki></code>, choose "HEAD revision" and "include externals". Then, click OK.
* You will be prompted for your user name and password. This account is the same that you use to log into [http://{{SERVERNAME}}/tracproj Trac] and [[special:userlogin|into this Wiki]].

== Checking out older versions ==
If you think that the current version of BCI2000 is not working properly, or would like to work with an older version for some other reason, you should first check whether one of the releases in <tt>http://www.bci2000.org/svn/tags/releases</tt> suits you needs.

Otherwise, to obtain a revision that is newer than the latest binary release, you will need to do a checkout of <tt>http://www.bci2000.org/svn/trunk</tt>.

In both cases, you may enter a "Revision number" into the checkout dialog in order to obtain an older revision.
The "Show Log" button will provide you with an overview of the latest changes and their associated revision numbers.

== Working on Branches ==
Branches are versions of the source code that are developed in parallel to the main code version, e.g. to incorporate new features without affecting the stable version that is intended for end users.
To checkout a branch called "myBranch", the repository URL would be:
<code><nowiki>http://www.bci2000.org/svn/branches/myBranch</nowiki></code>.
Otherwise, the checkout process remains the same.

==Troubleshooting==
*'''Symptom:''' When trying to checkout, update, or commit, you get an error message: "PROPFIND request failed", "OPTIONS request failed", "could not connect to server", or the like.
**'''Cause:''' Quite likely, you are behind a firewall, and internet access is over a proxy server.
**'''Fix:''' To configure TortoiseSVN for use with a proxy server, right-click your desktop, choose TortoiseSVN->Settings->Network, check "Enable Proxy" and enter the appropriate information. If unsure, contact your local system administrator.

*'''Symptom:''' You configured TortoiseSVN for use with a proxy server as described above. Now, checking out works fine, however on updates or commits, you get strange errors about failed requests.
**'''Cause:''' Your proxy server is not forwarding SVN's WebDAV requests correctly.
**'''Fix:''' To keep the proxy from interfering with the protocol, change your setup to use an encrypted connection:
:*Right-click on your source tree's top folder, choose TortoiseSVN->Relocate.
:*In the "to URL" edit field, modify <code><nowiki>http://</nowiki></code> to read <code><nowiki>https://</nowiki></code>.
:*On the first connection, TortoiseSVN will display a warning message: [[Image:TortoiseCertificateWarning.PNG|center]]
::Click "Accept permanently" to continue.

==See also==
[[Programming Howto:Using TortoiseSVN]]

[[Category:Howto]] [[Category:Development]] [[Category:Prerequisites]]

User Reference:gNautilus

2014-06-04T04:40:31Z

Gmilsap: /* Configuration */

==Synopsis==
The g.Nautilus acquisition module enables signal acquisition from the g.Nautilus device via the g.NEEDaccess API.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/gNautilus

==Versioning==
===Author===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
*V0.5 -- Analog Signal Acquisition
===Source Code Revisions===
*Initial development: 4727
*Tested under: 4727
*Known to compile under: 4727
*Broken since: N/A

==Functional Description==
The g.Nautilus is a wireless headset by g.tec, and is the first in their product line to use g.NEEDaccess exclusively for realtime access. This documentation explains the parameterization and specifics on how to set up the system.

'''NOTE:''' As of the time of writing, this module is at release V0.5. As such, it is not necessarily feature complete. The current g.NEEDAccess API BETA 7XX has not implemented all functionality that will eventually be supported in this module. Also, timing is pretty awful. As of right now, the acquisition module is not recommended for real-time closed-loop use with BCI2000.

===Configuration===
Install g.NEEDAccess on your machine, along with necessary g.tec drivers. Ensure the GDSDataServer is running by checking in services.msc. You'll need your HASP dongle in order to to access g.NEEDAccess[http://www.reactiongifs.com/r/fgwtf.gif .]

'''NOTE:''' As of right now, g.NEEDAccess BETA 7XX appears to only support Windows 7+ 64 bit operating systems. As such, a 64 bit build of BCI2000 is required to make the g.Nautilus binary. g.Nautiulus can only be built using Visual Studio on Windows.

Ensure the device is charged and connected to the base station (refer to the included documentation for help with this). Start BCI2000 with the gNautilus source module.

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

===SourceCh===
The g.Nautilus claims to support 64 channels via its API. The module has only been tested up to 32 channels.

'''NOTE:''' If less than 32 channels are acquired, only the first SourceCh channels will be acquired from.

===SamplingRate===
Only the following sample rates are currently supported by the API: 250 Hz and 500 Hz.

===SampleBlockSize===
Sample block size must be set to an integer multiple of the minimum sample block size corresponding to the current SamplingRate.

'''NOTE:''' As of V0.5, and g.NEEDAccess BETA 7XX, a SampleBlockSize set to the minimum block size results in non-realtime operation. Please specify a multiple of at least 2 * minimum block size.

*250 Hz -- 8 samples per block (block length of 32 ms, system clocked at 31.25 Hz)
*500 Hz -- 15 samples per block (block length of 30 ms, system clocked at 33.33 Hz)

===ChannelNames===
Leave this blank and channels are numbered. See Operator Log for information about correct channel names.

===HostIP, HostPort, LocalIP, LocalPort===
This defines the UDP connection to the GDSDataServer. If the service is running on your machine (see services.msc), the GDSDataServer will be listening to UDP packets on port 50223 (Default) at localhost (127.0.0.1). By default, the server will send messages to the listening process (localhost -- 127.0.0.1) on port 50224. The defaults here will be used in most circumstances. Consult your network administrator if your acquisition system is different.

'''NOTE:''' Ensure UDP communications on port 50223 and 50224 are unblocked and uninterrupted by any firewalls between the server and the client.

===NautilusSN===
This is the "name" of the device to acquire from. The serial number on the base-station is used here (Format: NB-20XX.YY.ZZ). Check the operator log for discovered devices and troubleshooting hints.

===NetworkChannel===
Channels 11-18 are available for communicating with several g.Nautilus devices in the same room. In order to ensure uninterrupted connections, use different NetworkChannel settings for each g.Nautilus in the room.

==Future Work==
*Autoconfiguration!
*Parametrization of Sensitivity
*Selective Channel Acquisition
*Digital Input as States
*Head Mounted Accelerometer input as States
*Signal quality indicator states
*Battery life check
*BCI2000 Integrated impedance check mode
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

User Reference:gNautilus

2014-06-04T04:21:50Z

Gmilsap: Initial documentation

==Synopsis==
The g.Nautilus acquisition module enables signal acquisition from the g.Nautilus device via the g.NEEDaccess API.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/gNautilus

==Versioning==
===Author===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
*V0.5 -- Analog Signal Acquisition
===Source Code Revisions===
*Initial development: 4727
*Tested under: 4727
*Known to compile under: 4727
*Broken since: N/A

==Functional Description==
The g.Nautilus is a wireless headset by g.tec, and is the first in their product line to use g.NEEDaccess exclusively for realtime access. This documentation explains the parameterization and specifics on how to set up the system.

'''NOTE:''' As of the time of writing, this module is at release V0.5. As such, it is not necessarily feature complete. The current g.NEEDAccess API BETA 7XX has not implemented all functionality that will eventually be supported in this module. Also, timing is pretty awful. As of right now, the acquisition module is not recommended for real-time closed-loop use with BCI2000.

===Configuration===
Install g.NEEDAccess on your machine, along with necessary g.tec drivers. Ensure the GDSDataServer is running by checking in services.msc.

'''NOTE:''' As of right now, g.NEEDAccess BETA 7XX appears to only support Windows 7+ 64 bit operating systems. As such, a 64 bit build of BCI2000 is required to make the g.Nautilus binary. g.Nautiulus can only be built using Visual Studio on Windows.

Ensure the device is charged and connected to the base station (refer to the included documentation for help with this). Start BCI2000 with the gNautilus source module.

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

===SourceCh===
The g.Nautilus claims to support 64 channels via its API. The module has only been tested up to 32 channels.

'''NOTE:''' If less than 32 channels are acquired, only the first SourceCh channels will be acquired from.

===SamplingRate===
Only the following sample rates are currently supported by the API: 250 Hz and 500 Hz.

===SampleBlockSize===
Sample block size must be set to an integer multiple of the minimum sample block size corresponding to the current SamplingRate.

'''NOTE:''' As of V0.5, and g.NEEDAccess BETA 7XX, a SampleBlockSize set to the minimum block size results in non-realtime operation. Please specify a multiple of at least 2 * minimum block size.

*250 Hz -- 8 samples per block (block length of 32 ms, system clocked at 31.25 Hz)
*500 Hz -- 15 samples per block (block length of 30 ms, system clocked at 33.33 Hz)

===ChannelNames===
Leave this blank and channels are numbered. See Operator Log for information about correct channel names.

===HostIP, HostPort, LocalIP, LocalPort===
This defines the UDP connection to the GDSDataServer. If the service is running on your machine (see services.msc), the GDSDataServer will be listening to UDP packets on port 50223 (Default) at localhost (127.0.0.1). By default, the server will send messages to the listening process (localhost -- 127.0.0.1) on port 50224. The defaults here will be used in most circumstances. Consult your network administrator if your acquisition system is different.

'''NOTE:''' Ensure UDP communications on port 50223 and 50224 are unblocked and uninterrupted by any firewalls between the server and the client.

===NautilusSN===
This is the "name" of the device to acquire from. The serial number on the base-station is used here (Format: NB-20XX.YY.ZZ). Check the operator log for discovered devices and troubleshooting hints.

===NetworkChannel===
Channels 11-18 are available for communicating with several g.Nautilus devices in the same room. In order to ensure uninterrupted connections, use different NetworkChannel settings for each g.Nautilus in the room.

==Future Work==
*Autoconfiguration!
*Parametrization of Sensitivity
*Selective Channel Acquisition
*Digital Input as States
*Head Mounted Accelerometer input as States
*Signal quality indicator states
*Battery life check
*BCI2000 Integrated impedance check mode
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:ADCs

2014-06-04T03:50:02Z

Gmilsap: Added g.Nautilus Documentation

The following data acquisition filters are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

*[[Contributions:AmpServerProADC]]: Interface to the EGI AmpServerPro.
*[[Contributions:BioRadioADC]]: Interface to the BioRadio amplifer.
*[[Contributions:Biosemi2ADC]]: Interface to the Biosemi amplifier.
*[[Contributions:Blackrock]]: Interface Blackrock devices through CereLink.
*[[Contributions:B-Alert]]: Interface to B-Alert brain monitoring systems.
*[[Contributions:DAS_ADC]]: Interface to MeasurementComputing AD cards.
*[[Contributions:DTADC]]: Interface to Data Translation boards.
*[[Contributions:Emotiv]]: Interface to the Emotiv EPOC.
*[[Contributions:FieldTripBufferSource]]: Interface to the FieldTrip buffer.
*[[Contributions:FilePlayback]]: A source module that replays sessions from recorded data files.
*[[Contributions:gHIamp]]: Interface to the gHIamp.
*[[Contributions:gNautilus]]: Interface to the gNautilus via g.NEEDAccess.
*[[Contributions:MicromedADC]]: Interface to the Micromed EEG system.
*[[Contributions:ModularEEG]]: Interface to the ModularEEG system.
*[[Contributions:Neuralynx]]: Interface to Neuralynx systems
*[[Contributions:NIADC]]: Interface to National Instruments boards.
*[[Contributions:NIDAQ-MX]]: Interface to National Instruments boards using the MX driver.
*[[Contributions:NIDAQLogger]]: Interface to multiple National Instruments DAQ boards using MX driver (INPUT ONLY).
*[[Contributions:NIDAQFilter]]: Interface to multiple National Instruments DAQ boards using MX driver (OUTPUT ONLY).
*[[Contributions:NeuroscanADC]]: Neuroscan Acquire socket protocol client.
*[[Contributions:NeuroscanAccessSDK]]: Interface to Neuroscan Direct Access SDK.
*[[Contributions:NeuroSky]]: Interface to Neurosky MindSet.
*[[Contributions:NicoletOne]]: Interface to NicoletOne nEEG series amplifiers.
*[[Contributions:ctfneurod]]: CTF RealTime to Neuroscan Acquire relay.
*[[Contributions:RDAClientADC]]: Brain Vision RDA socket protocol client.
*[[Contributions:TDTADC]]: Interface to Tucker-Davis Pentusa systems.
*[[Contributions:TMSiADC]]: Interface to TMSi Refa and Porti systems.
*[[Contributions:vAmpADC]]: Interface to Brain Products V-amp systems.
*[[Contributions:EnobioADC]]: Interface to Enobio sensor.
*[[Contributions:MicRecorderFilter]]: Interface to the system soundcard, logging audio input.

==See also==
[[User Reference:Filters]], [[Contributions:How to use a Contributed Source Module]]

[[Category:Contents]][[Category:Data Acquisition]]

Contributions:StimBoxFilter

2013-09-25T00:24:26Z

Gmilsap: Another copy-paste error

==Synopsis==
An integration of the g.STIMbox with BCI2000

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/StimBoxFilter

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
* 2013/09/23: Initial public release;

===Source Code Revisions===
*Initial development: 4580
*Tested under: 4580
*Known to compile under: 4580
*Broken since: --

==Functional Description==
The g.STIMbox is a USB digital I/O card. This simple filter extension resides in the Application module and makes input and output with the card easy.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_STIMBOXFILTER'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--StimBoxFilter=[COMPORT]</code> command line argument (NB, as explained below, the numeric value here matters, and denotes the COM port to be used: =1 means COM port 1).

==Parameters==
The StimBoxFilter is configured in the g.STIMbox tab. The configurable parameters are:

===EnableStimBoxFilter===
Enables/Disables the StimBoxFilter. This parameter performs double-duty as the COM port selector. NOTE: The COM port that the g.STIMbox is connected to can be determined by accessing the Device Manager within the Windows control panel.
*[0] - Disabled
*Any other number indicates the COM port to attempt communication with the g.STIMbox on.

===DigitalOutputs===
This matrix of expressions that controls the outputs on the device. The g.STIMbox has 16 digital outputs which can be controlled via expressions in this matrix. Some of the outputs can only be accessed via the D-SUB connector on the front of the box. To control a port, create a new row in this matrix and change the row label to the number of the port you wish to control. If the expression in column 1 in that row evaluates to True, the port will be set high, and the port will be set low whenever the expression evaluates to False. If an 'F' is specified immediately after the row label (for example, '3F'), that port is assumed to be in 'Frequency Mode' and the port frequency will be set to whatever the expression evaluates to. If the expression evaluates to 0 or False, the port will be set low (off). Note that changing the frequency while in frequency mode will reset the port to 'high' immediately. This means that changing the frequency too often will result in the port reading 'high' all the time.

Example:

{| class="wikitable"
! (Row Label)
! (Column 1)
! (Description)
|-
! 1
| 1
| // Output 1 is always high
|-
! 2
| 0
| // Output 2 is always low
|-
! 5
| 0.5
| // Outputs don't need to be specified in order, 0.5 evaluates to True
|-
! 3
| Signal(1,1) > 50
| // Output 3 is high when the input signal exceeds 50.
|-
! 4F
| StimulusType
| // Output 4 will evaluate the state "StimulusType" to determine output frequency.
|-
! 5
| !StimBoxInput1
| // Line 3 is ignored, Output 5 = Input 1
|}

Special Notes:
*Valid frequencies for frequency mode are between 1 and 50 Hz.

==State Variables==
The StimBoxFilter outputs the following state variables:

===StimBoxInput[1-14]===
There are 14 digital inputs on the StimBox. Some of the inputs can only be accessed via the D-SUB connectors on the front of the box. These inputs are asynchronously sampled at 256 Hz and set as BCI2000 states once per block. Note that this means there is data loss if your signal changes more than once per BCI2000 block. Clocking BCI2000 at >256 blocks per second is also inadvisable, so this is expected.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:StimBoxFilter

2013-09-25T00:21:40Z

Gmilsap: Fixed copy-paste error

==Synopsis==
An integration of the g.STIMbox with BCI2000

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
* 2013/09/23: Initial public release;

===Source Code Revisions===
*Initial development: 4580
*Tested under: 4580
*Known to compile under: 4580
*Broken since: --

==Functional Description==
The g.STIMbox is a USB digital I/O card. This simple filter extension resides in the Application module and makes input and output with the card easy.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_STIMBOXFILTER'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--StimBoxFilter=[COMPORT]</code> command line argument (NB, as explained below, the numeric value here matters, and denotes the COM port to be used: =1 means COM port 1).

==Parameters==
The StimBoxFilter is configured in the g.STIMbox tab. The configurable parameters are:

===EnableStimBoxFilter===
Enables/Disables the StimBoxFilter. This parameter performs double-duty as the COM port selector. NOTE: The COM port that the g.STIMbox is connected to can be determined by accessing the Device Manager within the Windows control panel.
*[0] - Disabled
*Any other number indicates the COM port to attempt communication with the g.STIMbox on.

===DigitalOutputs===
This matrix of expressions that controls the outputs on the device. The g.STIMbox has 16 digital outputs which can be controlled via expressions in this matrix. Some of the outputs can only be accessed via the D-SUB connector on the front of the box. To control a port, create a new row in this matrix and change the row label to the number of the port you wish to control. If the expression in column 1 in that row evaluates to True, the port will be set high, and the port will be set low whenever the expression evaluates to False. If an 'F' is specified immediately after the row label (for example, '3F'), that port is assumed to be in 'Frequency Mode' and the port frequency will be set to whatever the expression evaluates to. If the expression evaluates to 0 or False, the port will be set low (off). Note that changing the frequency while in frequency mode will reset the port to 'high' immediately. This means that changing the frequency too often will result in the port reading 'high' all the time.

Example:

{| class="wikitable"
! (Row Label)
! (Column 1)
! (Description)
|-
! 1
| 1
| // Output 1 is always high
|-
! 2
| 0
| // Output 2 is always low
|-
! 5
| 0.5
| // Outputs don't need to be specified in order, 0.5 evaluates to True
|-
! 3
| Signal(1,1) > 50
| // Output 3 is high when the input signal exceeds 50.
|-
! 4F
| StimulusType
| // Output 4 will evaluate the state "StimulusType" to determine output frequency.
|-
! 5
| !StimBoxInput1
| // Line 3 is ignored, Output 5 = Input 1
|}

Special Notes:
*Valid frequencies for frequency mode are between 1 and 50 Hz.

==State Variables==
The StimBoxFilter outputs the following state variables:

===StimBoxInput[1-14]===
There are 14 digital inputs on the StimBox. Some of the inputs can only be accessed via the D-SUB connectors on the front of the box. These inputs are asynchronously sampled at 256 Hz and set as BCI2000 states once per block. Note that this means there is data loss if your signal changes more than once per BCI2000 block. Clocking BCI2000 at >256 blocks per second is also inadvisable, so this is expected.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:StimBoxFilter

2013-09-23T04:43:10Z

Gmilsap: Added documentation for the StimBoxFilter

==Synopsis==
An integration of the g.STIMbox with BCI2000

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
* 2013/09/23: Initial public release;

===Source Code Revisions===
*Initial development: 4580
*Tested under: 4580
*Known to compile under: 4580
*Broken since: --

==Functional Description==
The g.STIMbox is a USB digital I/O card. This simple filter extension resides in the Application module and makes input and output with the card easy.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_STIMBOXFILTER'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--StimBoxFilter=[COMPORT]</code> command line argument (NB, as explained below, the numeric value here matters, and denotes the COM port to be used: =1 means COM port 1).

==Parameters==
The StimBoxFilter is configured in the g.STIMbox tab. The configurable parameters are:

===EnableStimBoxFilter===
Enables/Disables the StimBoxFilter. This parameter performs double-duty as an audio host API selector. NOTE: The COM port that the g.STIMbox is connected to can be determined by accessing the Device Manager within the Windows control panel.
*[0] - Disabled
*Any other number indicates the COM port to attempt communication with the g.STIMbox on.

===DigitalOutputs===
This matrix of expressions that controls the outputs on the device. The g.STIMbox has 16 digital outputs which can be controlled via expressions in this matrix. Some of the outputs can only be accessed via the D-SUB connector on the front of the box. To control a port, create a new row in this matrix and change the row label to the number of the port you wish to control. If the expression in column 1 in that row evaluates to True, the port will be set high, and the port will be set low whenever the expression evaluates to False. If an 'F' is specified immediately after the row label (for example, '3F'), that port is assumed to be in 'Frequency Mode' and the port frequency will be set to whatever the expression evaluates to. If the expression evaluates to 0 or False, the port will be set low (off). Note that changing the frequency while in frequency mode will reset the port to 'high' immediately. This means that changing the frequency too often will result in the port reading 'high' all the time.

Example:

{| class="wikitable"
! (Row Label)
! (Column 1)
! (Description)
|-
! 1
| 1
| // Output 1 is always high
|-
! 2
| 0
| // Output 2 is always low
|-
! 5
| 0.5
| // Outputs don't need to be specified in order, 0.5 evaluates to True
|-
! 3
| Signal(1,1) > 50
| // Output 3 is high when the input signal exceeds 50.
|-
! 4F
| StimulusType
| // Output 4 will evaluate the state "StimulusType" to determine output frequency.
|-
! 5
| !StimBoxInput1
| // Line 3 is ignored, Output 5 = Input 1
|}

Special Notes:
*Valid frequencies for frequency mode are between 1 and 50 Hz.

==State Variables==
The StimBoxFilter outputs the following state variables:

===StimBoxInput[1-14]===
There are 14 digital inputs on the StimBox. Some of the inputs can only be accessed via the D-SUB connectors on the front of the box. These inputs are asynchronously sampled at 256 Hz and set as BCI2000 states once per block. Note that this means there is data loss if your signal changes more than once per BCI2000 block. Clocking BCI2000 at >256 blocks per second is also inadvisable, so this is expected.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:Extensions

2013-09-23T04:04:15Z

Gmilsap: Added page for the StimBoxFilter

A framework ''Extension'' is an optional contributed plugin which can affect multiple modules. For example, various manufacturer-specific [[User Reference:Logging Input|input-device loggers]] are provided in the <code>src/contrib/Extensions</code> folder, and these can be optionally added to the BCI2000 framework for SignalSource modules, thereby giving all source modules the ability to log input from the corresponding devices. Selecting a custom Extension, and re-building your modules to include it, requires the use of CMake and a supported C++ compiler: see the [[Programming Howto:Quickstart Guide]] for a walkthrough that shows you how to recompile BCI2000 modules.

The following user extensions are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

*[[Contributions:DataGloveLogger]]: A logger extension which acquires data from the 5DT Data Glove Ultra.
*[[Contributions:EyetrackerLogger]]: A logger extension which acquires data from Tobii eyetrackers.
*[[Contributions:GazeMonitorFilter]]: An application module filter extension which supports the EyetrackerLogger.
*[[Contributions:WiimoteLogger]]: A logger extension which acquires data from Nintendo Wii Remotes.
*[[Contributions:WebcamLogger]]: A logger extension which allows for synchronizing webcam video.
*[[Contributions:AudioExtension]]: An all purpose audio toolkit which allows for realtime multichannel audio I/O.
*[[Contributions:StimBoxFilter]]: A logger and controller for the gtec g.STIMbox.

==See also==
[[Programming Reference:EnvironmentExtension Class]]

[[Programming Tutorial:Implementing an Input Logger]][[Category:Contents]]

Contributions:Blackrock

2013-08-10T20:29:09Z

Gmilsap: /* Functional Description */

==Synopsis==
The Blackrock acquisition module enables signal acquisition from Blackrock Microsystems Cerebus and Neuroport acquisition hardware through the CereLink "cbsdk".

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/Blackrock

==Versioning==
===Author===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
*V1.0 -- Analog Signal Acquisition and Digital Filtering Functionality
===Source Code Revisions===
*Initial development: 4365
*Tested under: 4365
*Known to compile under: 4365
*Broken since: N/A

==Functional Description==
The Blackrock source module is used for acquiring recordings from the Blackrock NSP 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.

===Configuration===
Building the Blackrock module should copy .bat files for standard experiments into the batch directory, in addition to a parameter fragment for the amplifier, placed in parms/fragments/amplifiers.

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 susceptable to packet loss. In the event of a lost packet, the module will crash (this is rare with a good switch). 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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ 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.

====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.

==Parameters==
The following parameters are available for configuring the Blackrock source module. You will find these parameters in the Source -- Signal Properties section.
===SourceCh===
The Blackrock module supports a maximum of 144 analog channels. The first 128 of these channels are the analog EEG channels, and the following 16 are the analog input channels on the NSP itself.
===AnalogCh===
This parameter specifies what channels to acquire from the NSP. Again, the first 128 of these channels are the analog EEG channels, and the following 16 are analog input channels on the NSP itself. You can specify this parameter in two ways.
====Manual====
Specify a vector of 144 '0's and '1's; where there are ''SourceCh'' '1's. Example:
SourceCh = 16;
AnalogCh = 0 0 0 1 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 1 0 0 0 0 0 1 0 0 0 1 0 0 0 1 0 1 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
This parameterization acquires channels 4, 8, 9, 10, 17, 18, 19, 23, 29, 33, 37, 39, 44, 50, AINP1, and AINP2
====Automatic====
If you just want a sequential number of channels starting from channel 1, specify the number of channels to acquire as a negative number. Example:
SourceCh = 32;
AnalogCh = -32;
This parameterization acquires channels 1-32. NOTE: 0 is interpreted as -144 which means every channel is acquired.
===SignalFilter===
The following filters can be applied to *DESTRUCTIVELY* filter the data on the NSP before it is passed to BCI2000.
*0 -- No Filter
*1 -- HP 750Hz
*2 -- HP 250Hz
*3 -- HP 100Hz
*4 -- LP 50Hz
*5 -- LP 125Hz
*6 -- LP 250Hz
*7 -- LP 500Hz
*8 -- LP 150Hz
*9 -- BP 10Hz-250Hz
*10 -- LP 2.5kHz
*11 -- LP 2kHz
*12 -- BP 250Hz-5kHz
===SampleBlockSize===
Any number of samples is valid here: even 1. You may want to not do that, however. Clocking the system above 20-30 Hz [http://www.youtube.com/watch?v=2FM3Em7FIOc is a bad choice].
===SamplingRate===
Only the following sample rates are supported.
500
1000
2000
10000
30000
==Future Work==
*Digital Input as States
*Digital Output
*Serial Input
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:Blackrock

2013-01-30T16:46:58Z

Gmilsap: Finalized v1.0 Documentation

==Synopsis==
The Blackrock acquisition module enables signal acquisition from Blackrock Microsystems Cerebus and Neuroport acquisition hardware through the CereLink "cbsdk".

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/Blackrock

==Versioning==
===Author===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
*V1.0 -- Analog Signal Acquisition and Digital Filtering Functionality
===Source Code Revisions===
*Initial development: 4365
*Tested under: 4365
*Known to compile under: 4365
*Broken since: N/A

==Functional Description==
The Blackrock source module is used for acquiring recordings from the Blackrock NSP 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.

===Configuration===
Building the Blackrock module should copy .bat files for standard experiments into the batch directory, in addition to a parameter fragment for the amplifier, placed in parms/fragments/amplifiers.

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 susceptable to packet loss. In the event of a lost packet, the module will crash (this is rare with a good switch). 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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ Windows]):
IP address: 192.168.137.XXX where XXX is less than 128. 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.

====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.

==Parameters==
The following parameters are available for configuring the Blackrock source module. You will find these parameters in the Source -- Signal Properties section.
===SourceCh===
The Blackrock module supports a maximum of 144 analog channels. The first 128 of these channels are the analog EEG channels, and the following 16 are the analog input channels on the NSP itself.
===AnalogCh===
This parameter specifies what channels to acquire from the NSP. Again, the first 128 of these channels are the analog EEG channels, and the following 16 are analog input channels on the NSP itself. You can specify this parameter in two ways.
====Manual====
Specify a vector of 144 '0's and '1's; where there are ''SourceCh'' '1's. Example:
SourceCh = 16;
AnalogCh = 0 0 0 1 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 1 0 0 0 0 0 1 0 0 0 1 0 0 0 1 0 1 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
This parameterization acquires channels 4, 8, 9, 10, 17, 18, 19, 23, 29, 33, 37, 39, 44, 50, AINP1, and AINP2
====Automatic====
If you just want a sequential number of channels starting from channel 1, specify the number of channels to acquire as a negative number. Example:
SourceCh = 32;
AnalogCh = -32;
This parameterization acquires channels 1-32. NOTE: 0 is interpreted as -144 which means every channel is acquired.
===SignalFilter===
The following filters can be applied to *DESTRUCTIVELY* filter the data on the NSP before it is passed to BCI2000.
*0 -- No Filter
*1 -- HP 750Hz
*2 -- HP 250Hz
*3 -- HP 100Hz
*4 -- LP 50Hz
*5 -- LP 125Hz
*6 -- LP 250Hz
*7 -- LP 500Hz
*8 -- LP 150Hz
*9 -- BP 10Hz-250Hz
*10 -- LP 2.5kHz
*11 -- LP 2kHz
*12 -- BP 250Hz-5kHz
===SampleBlockSize===
Any number of samples is valid here: even 1. You may want to not do that, however. Clocking the system above 20-30 Hz [http://www.youtube.com/watch?v=2FM3Em7FIOc is a bad choice].
===SamplingRate===
Only the following sample rates are supported.
500
1000
2000
10000
30000
==Future Work==
*Digital Input as States
*Digital Output
*Serial Input
==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:Blackrock

2013-01-29T20:07:08Z

Gmilsap: More information

==Synopsis==
The Blackrock acquisition module enables signal acquisition from Blackrock Microsystems Cerebus and Neuroport acquisition hardware through the CereLink "cbsdk".

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/Blackrock

==Versioning==
===Author===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
*V1.0 -- Analog Signal Acquisition and Digital Filtering Functionality
===Source Code Revisions===
*Initial development: 4365
*Tested under: 4365
*Known to compile under: 4365
*Broken since: N/A

==Functional Description==
The Blackrock source module is used for acquiring recordings from the Blackrock NSP 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.

===Configuration===
Building the Blackrock module should copy .bat files for standard experiments into the batch directory, in addition to a parameter fragment for the amplifier, placed in parms/fragments/amplifiers.

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 susceptable to packet loss. In the event of a lost packet, the module will crash (this is rare with a good switch). 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 ([http://www.howtogeek.com/howto/19249/how-to-assign-a-static-ip-address-in-xp-vista-or-windows-7/ Windows]):
IP address: 192.168.137.XXX where XXX is less than 128. 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.

====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.

==Parameters==
The following parameters are available for configuring the Blackrock source module. You will find these parameters in the Source -- Signal Properties section.
===SourceCh===
"Source:Signal%20Properties int SourceCh= 144 // number of digitized and stored channels
===AnalogCh===
"Source:Signal%20Properties intlist AnalogCh= 0 // Analog channels to acquire from Blackrock
===SignalFilter===
"Source:Signal%20Properties int SignalFilter= 0 // Filter to apply to data:
*0 -- No Filter
*1 -- HP 750Hz
*2 -- HP 250Hz
*3 -- HP 100Hz
*4 -- LP 50Hz
*5 -- LP 125Hz
*6 -- LP 250Hz
*7 -- LP 500Hz
*8 -- LP 150Hz
*9 -- BP 10Hz-250Hz
*10 -- LP 2.5kHz
*11 -- LP 2kHz
*12 -- BP 250Hz-5kHz
===SampleBlockSize===
1000 // number of samples transmitted at a time",
===SamplingRate===
30000Hz

Contributions:Blackrock

2013-01-25T19:55:26Z

Gmilsap: Documentation Template (WIP)

Contributions:ADCs

2013-01-25T19:39:54Z

Gmilsap: Added a link to new documentation page

The following data acquisition filters are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

*[[Contributions:AmpServerProADC]]: Interface to the EGI AmpServerPro.
*[[Contributions:BioRadioADC]]: Interface to the BioRadio amplifer.
*[[Contributions:Biosemi2ADC]]: Interface to the Biosemi amplifier.
*[[Contributions:Blackrock]]: Interface Blackrock devices through CereLink.
*[[Contributions:B-Alert]]: Interface to B-Alert brain monitoring systems.
*[[Contributions:DAS_ADC]]: Interface to MeasurementComputing AD cards.
*[[Contributions:DTADC]]: Interface to Data Translation boards.
*[[Contributions:Emotiv]]: Interface to the Emotiv EPOC.
*[[Contributions:FieldTripBufferSource]]: Interface to the FieldTrip buffer.
*[[Contributions:FilePlayback]]: A source module that replays sessions from recorded data files.
*[[Contributions:gHIamp]]: Interface to the gHIamp.
*[[Contributions:MicromedADC]]: Interface to the Micromed EEG system.
*[[Contributions:ModularEEG]]: Interface to the ModularEEG system.
*[[Contributions:Neuralynx]]: Interface to Neuralynx systems
*[[Contributions:NIADC]]: Interface to National Instruments boards.
*[[Contributions:NIDAQ-MX]]: Interface to National Instruments boards using the MX driver.
*[[Contributions:NIDAQLogger]]: Interface to multiple National Instruments DAQ boards using MX driver (INPUT ONLY).
*[[Contributions:NIDAQFilter]]: Interface to multiple National Instruments DAQ boards using MX driver (OUTPUT ONLY).
*[[Contributions:NeuroscanADC]]: Neuroscan Acquire socket protocol client.
*[[Contributions:NeuroscanAccessSDK]]: Interface to Neuroscan Direct Access SDK.
*[[Contributions:NeuroSky]]: Interface to Neurosky MindSet.
*[[Contributions:NicoletOne]]: Interface to NicoletOne nEEG series amplifiers.
*[[Contributions:ctfneurod]]: CTF RealTime to Neuroscan Acquire relay.
*[[Contributions:RDAClientADC]]: Brain Vision RDA socket protocol client.
*[[Contributions:TDTADC]]: Interface to Tucker-Davis Pentusa systems.
*[[Contributions:TMSiADC]]: Interface to TMSi Refa and Porti systems.
*[[Contributions:vAmpADC]]: Interface to Brain Products V-amp systems.
*[[Contributions:EnobioADC]]: Interface to Enobio sensor.
*[[Contributions:MicRecorderFilter]]: Interface to the system soundcard, logging audio input.

==See also==
[[User Reference:Filters]], [[Contributions:How to use a Contributed Source Module]]

[[Category:Contents]][[Category:Data Acquisition]]

Contributions:AudioExtension

2012-06-13T14:52:33Z

Gmilsap: /* Known Issues */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
* 2012/06/11: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module in halted state exhibits some sort of bug regarding state logging. When running state is resumed, envelope states may fail to update for 15-30 seconds. The bug seems to be unrelated to how long system was halted -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface. This bug will never happen on the first run after BCI2000 is started up. If you do see the behavior, either wait for it to go away or restart BCI2000 and perform a new recording.
* Bandpass filtering in filterbanks doesn't appear to function correctly.
* AudioExtension processes audio in a separate thread and the internal audio callback is called from yet-another context (Sometimes a system interrupt). In order to prevent deadlock, the Audio callback must not lock or wait for external threads. As such, it will simply copy the last good audio buffer to the output stream if the audio thread has not posted new data to use yet. This can result in slowed "timestretching" effects on audio input files if the audio thread cannot keep up with the audio callbacks. To prevent this behavior, ensure your audio block size is large enough (at least 1024 frames). If you are using a lower latency audio API (such as ASIO) you are probably okay to use audio block sizes around 512 frames. Either way, be mindful that audio playback may not necessarily operate in real-time and you will receive NO WARNING WHATSOEVER when it fails to.

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument (NB, as explained below, the numeric value here matters, and denotes the audio API to be used: =1 means DirectSound).

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#Known_Issues|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-12T18:16:24Z

Gmilsap: Removed irrelevant documentation

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
* 06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function correctly.
* AudioExtension processes audio in a separate thread and the internal audio callback is called from yet-another context (Sometimes a system interrupt). In order to prevent deadlock, the Audio callback must not lock or wait for external threads. As such, it will simply copy the last good audio buffer to the output stream if the audio thread has not posted new data to use yet. This can result in slowed "timestretching" effects on audio input files if the audio thread cannot keep up with the audio callbacks. To prevent this behavior, ensure your audio block size is large enough (at least 1024 frames). If you are using a lower latency audio API (such as ASIO) you are probably okay to use audio block sizes around 512 frames. Either way, be mindful that audio playback may not necessarily operate in real-time and you will receive NO WARNING WHATSOEVER when it fails to.

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#Known_Issues|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

File:AudioExtensionBlockDiagram.png

2012-06-11T21:20:53Z

Gmilsap:

Visual description of data flow within [[Contributions:AudioExtension]]

Source file is here. https://docs.google.com/drawings/d/1Qc7abVU7jVMK02mGVuSXOlF4wBEmRsSI1tBggdNVO7w/edit

Contributions:AudioExtension

2012-06-11T21:10:13Z

Gmilsap: /* Version History */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
* 06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function correctly.
* AudioExtension processes audio in a separate thread and the internal audio callback is called from yet-another context (Sometimes a system interrupt). In order to prevent deadlock, the Audio callback must not lock or wait for external threads. As such, it will simply copy the last good audio buffer to the output stream if the audio thread has not posted new data to use yet. This can result in slowed "timestretching" effects on audio input files if the audio thread cannot keep up with the audio callbacks. To prevent this behavior, ensure your audio block size is large enough (at least 1024 frames). If you are using a lower latency audio API (such as ASIO) you are probably okay to use audio block sizes around 512 frames. Either way, be mindful that audio playback may not necessarily operate in real-time and you will receive NO WARNING WHATSOEVER when it fails to.

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#Known_Issues|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T21:09:21Z

Gmilsap: /* Known Issues */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function correctly.
* AudioExtension processes audio in a separate thread and the internal audio callback is called from yet-another context (Sometimes a system interrupt). In order to prevent deadlock, the Audio callback must not lock or wait for external threads. As such, it will simply copy the last good audio buffer to the output stream if the audio thread has not posted new data to use yet. This can result in slowed "timestretching" effects on audio input files if the audio thread cannot keep up with the audio callbacks. To prevent this behavior, ensure your audio block size is large enough (at least 1024 frames). If you are using a lower latency audio API (such as ASIO) you are probably okay to use audio block sizes around 512 frames. Either way, be mindful that audio playback may not necessarily operate in real-time and you will receive NO WARNING WHATSOEVER when it fails to.

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#Known_Issues|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T21:02:55Z

Gmilsap: /* Parameters */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#Known_Issues|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T21:02:27Z

Gmilsap: /* Parameters */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#Versioning|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T21:01:55Z

Gmilsap: Linked Known Issues

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter [[Contributions:AudioExtension#KnownIssues|*See Known Issues*]]
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T21:00:16Z

Gmilsap: Documented State Variables for AudioExtension

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter *See known issues*
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
The AudioExtension outputs the following state variables:

===Audio[In/Out]Envelope[0-3]===
These are the envelope values of each channel (up to channel 4) of the audio inputs and outputs (in the AudioMixer matrix). These 16 bit unsigned values correspond to the resulting envelope after the audio envelope extraction. For architectural reasons, it is not possible to publish states after system startup, so you are limited to four channels of input and output. The AudioExtension can be easily modified to change the number of channels by editing the <code>#define NUM_INPUT_ENVELOPES 4</code> and <code>#define NUM_OUTPUT_ENVELOPES</code> lines in AudioExtension.cpp, and recompiling your source module.

===AudioFrame===
This 32 bit unsigned number corresponds to the current frame of audio data in the recorded output files. This can be used to resynchronize the lossless audio to the resulting .dat file offline. Audio is sampled internally at 44100 Hz, so this number will roll over once every 27 hours or so.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T20:50:26Z

Gmilsap: Added AudioExtension Parameters to documentation

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The AudioExtension is configured in the Source tab within the AudioExtension section. The configurable parameters are:

*<code>EnableAudioExtension</code> - Enables/Disables the AudioExtension. This parameter performs double-duty as an audio host API selector. The following values of this parameter are valid. NOTE: Not all audio APIs are available on all platforms.
**[0] - Disabled
**[1] - DirectSound
**[2] - MME
**[3] - ASIO
**[4] - SoundManager
**[5] - CoreAudio
**[6] - Disabled
**[7] - OSS
**[8] - ALSA
**[9] - AL
**[10] - BeOs
**[11] - WDMKS
**[12] - JACK
**[13] - WASAPI
**[14] - AudioScienceHPI

*<code>AudioMixer</code> - This matrix of expressions mixes input (rows) to output(columns). It must be dimensioned with exactly <code>n</code> columns where <code>n</code> is the number of outputs. Row labels define the input source. Change row labels by double clicking on the row. The following inputs are valid row labels.
**<code>X</code> - This is automatically interpreted as INPUT[X]
**<code>INPUT[X]</code> - This input will come from channel X on the sound card input.
**<code>FILE[X]</code> - This input will come from channel X in the AudioInputFile.
**<code>TONE[X]</code> - This input will be a synthesized sine wave with the frequency of X Hz.
**<code>NOISE[X]</code> - This input will be generated white noise at X Hz. NOTE: NOISE[] is white noise at the audio sampling rate (which defaults to 44100)
*<code>AudioInputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default input device on this host API.
*<code>AudioOutputDevice</code> - The index for the device to use as the audio input device on the current Host API. See the operator log after "Set Config" for valid device indices on the selected host API. A value of -1 for this parameter selects the default output device on this host API.
*<code>AudioInputFile</code> - Audio file to use as audio input to AudioMixer. The selected file can have any non-zero number of channels and be encoded in almost any format (except MP3), but MUST be encoded at 44100 Hz.
*<code>AudioRecordInput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordOutput</code> - Enables/Disables recording of audio data to a file in the DataDirectory.
*<code>AudioRecordingFormat</code> - Changes the file format and encoding options of the recorded output files. This parameter has the following three options:
**Raw - Records to 16 bit Microsoft formatted WAV files with no compression. These files open directly in MATLAB if that's interesting to you.
**Lossless - Records to FLAC formatted files. These files are slightly smaller than RAW files, but have no quality loss.
**Lossy - Records to Ogg Vorbis files. These files are similar to MP3 but do not have the associated licensing issues. They are compressed using a lossy algorithm, so the resulting files are very small but sound slightly worse than lossless encoding. This format is good for long recordings where perfect quality is not necessary.
*<code>Audio[Input/Output]Filterbank</code> - A filterbank which filters audio input and output before rectification/smoothing for envelope extraction. These butterworth filters will not be applied to the audible signal. The format of the filter bank is as follows:
**Type - The characteristic of the filter. The following values are valid.
***Lowpass - Creates a low pass filter
***Highpass - Creates a high pass filter
***Bandpass - Creates a band pass filter *See known issues*
***Bandstop - Creates a band stop, or notch filter
**Order - The order of the filter model. Higher order filters are more accurate but more expensive computationally.
**Cutoff1 - The cutoff frequency for Lowpass and Highpass filters, and the cut-on frequency for Bandpass and Bandstop filters.
**Cutoff2 - The cut-off frequency for Bandpass and Bandstop filters.
The matrix can have as many rows as necessary to filter the signal. Filters can be applied in any order and their transfer functions are multiplied before filtering occurs.
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>AudioEnvelopeSmoothing</code> - The cutoff frequency for the low pass filter which is applied to the filtered and full-wave rectified audio data. This should be set to the highest frequency you want to see in the resulting audio envelope.

==State Variables==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye. The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.

===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0. They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled. (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].

===PosX, PosY===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled. Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535. (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.

===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled. It corresponds to the length of the longest chord drawn from one side of the pupil to the other. The size will change depending on the eye position and distance from the screen. Although it is given in mm, it would be best to use this as a relative measurement.

===EyeDist===
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation. The actual measurement will depend on whether or not the test subject is wearing glasses or not.

===EyeValidity===
This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.
* 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
* 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
* 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
* 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
* 4 - The actual gaze data is missing or definitely belonging to the other eye.

{| class="wikitable"
|-
! Code (Right - Left)
! Description
|-
| 0 - 0
| Both eyes found. Data is valid for both eyes.
|-
| 0 - 4 or 4 - 0
| One eye found. Gaze data is the same for both eyes.
|-
| 1 - 3 or 3 - 1
| One eye found. Gaze data is the same for both eyes.
|-
| 2 - 2
| One eye found. Gaze data is the same for both eyes.
|-
| 4 - 4
| No eye found. Gaze data for both eyes are invalid.
|}

It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

===EyetrackerStatesOK===
Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T19:26:06Z

Gmilsap: /* Block Diagram */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[Image:AudioExtensionBlockDiagram.png]]

==Parameters==
The eyetracker is configured in the Source tab within the EyetrackerLogger section. The configurable parameters are:

*<code>LogEyetracker</code> - Enables/Disables logging of Eyetracker states
*<code>NetworkLocation</code> - The network address of the Eyetracker given by the Tobii Eyetracker Browser
*<code>Port</code> - The port that the Tobii communicates over - Tobii default is 4455
*<code>LogGazeData</code> - Enables/Disables logging of gaze data
*<code>LogEyePos</code> - Enables/Disables logging of eye position (as seen from the camera)
*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>GazeScale</code> - Scales the incoming gaze data first
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling

Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

The following code retreives the actual ~(0.0-1.0) range that the eyetracker outputs directly (assuming you've scaled and offset the signal to avoid clipping) from each eye and averages it to find a gaze position.
<pre>
float x = State( "EyetrackerLeftEyeGazeX" ) + State( "EyetrackerRightEyeGazeX" ); x /= ( 2.0f * 65535.0f );
float y = State( "EyetrackerLeftEyeGazeY" ) + State( "EyetrackerRightEyeGazeY" ); y /= ( 2.0f * 65535.0f );
x -= ( float )Parameter( "GazeOffset" ); x /= ( float )Parameter( "GazeScale" );
y -= ( float )Parameter( "GazeOffset" ); y /= ( float )Parameter( "GazeScale" );
</pre>

==State Variables==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye. The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.

===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0. They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled. (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].

===PosX, PosY===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled. Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535. (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.

===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled. It corresponds to the length of the longest chord drawn from one side of the pupil to the other. The size will change depending on the eye position and distance from the screen. Although it is given in mm, it would be best to use this as a relative measurement.

===EyeDist===
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation. The actual measurement will depend on whether or not the test subject is wearing glasses or not.

===EyeValidity===
This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.
* 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
* 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
* 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
* 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
* 4 - The actual gaze data is missing or definitely belonging to the other eye.

{| class="wikitable"
|-
! Code (Right - Left)
! Description
|-
| 0 - 0
| Both eyes found. Data is valid for both eyes.
|-
| 0 - 4 or 4 - 0
| One eye found. Gaze data is the same for both eyes.
|-
| 1 - 3 or 3 - 1
| One eye found. Gaze data is the same for both eyes.
|-
| 2 - 2
| One eye found. Gaze data is the same for both eyes.
|-
| 4 - 4
| No eye found. Gaze data for both eyes are invalid.
|}

It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

===EyetrackerStatesOK===
Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

File:AudioExtensionBlockDiagram.png

2012-06-11T19:25:42Z

Gmilsap: Visual description of data flow within Contributions:AudioExtension

Visual description of data flow within [[Contributions:AudioExtension]]

Contributions:AudioExtension

2012-06-11T19:23:58Z

Gmilsap: /* Block Diagram */

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

[[File:AudioExtensionBlockDiagram.png]]

==Parameters==
The eyetracker is configured in the Source tab within the EyetrackerLogger section. The configurable parameters are:

*<code>LogEyetracker</code> - Enables/Disables logging of Eyetracker states
*<code>NetworkLocation</code> - The network address of the Eyetracker given by the Tobii Eyetracker Browser
*<code>Port</code> - The port that the Tobii communicates over - Tobii default is 4455
*<code>LogGazeData</code> - Enables/Disables logging of gaze data
*<code>LogEyePos</code> - Enables/Disables logging of eye position (as seen from the camera)
*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>GazeScale</code> - Scales the incoming gaze data first
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling

Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

The following code retreives the actual ~(0.0-1.0) range that the eyetracker outputs directly (assuming you've scaled and offset the signal to avoid clipping) from each eye and averages it to find a gaze position.
<pre>
float x = State( "EyetrackerLeftEyeGazeX" ) + State( "EyetrackerRightEyeGazeX" ); x /= ( 2.0f * 65535.0f );
float y = State( "EyetrackerLeftEyeGazeY" ) + State( "EyetrackerRightEyeGazeY" ); y /= ( 2.0f * 65535.0f );
x -= ( float )Parameter( "GazeOffset" ); x /= ( float )Parameter( "GazeScale" );
y -= ( float )Parameter( "GazeOffset" ); y /= ( float )Parameter( "GazeScale" );
</pre>

==State Variables==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye. The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.

===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0. They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled. (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].

===PosX, PosY===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled. Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535. (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.

===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled. It corresponds to the length of the longest chord drawn from one side of the pupil to the other. The size will change depending on the eye position and distance from the screen. Although it is given in mm, it would be best to use this as a relative measurement.

===EyeDist===
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation. The actual measurement will depend on whether or not the test subject is wearing glasses or not.

===EyeValidity===
This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.
* 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
* 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
* 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
* 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
* 4 - The actual gaze data is missing or definitely belonging to the other eye.

{| class="wikitable"
|-
! Code (Right - Left)
! Description
|-
| 0 - 0
| Both eyes found. Data is valid for both eyes.
|-
| 0 - 4 or 4 - 0
| One eye found. Gaze data is the same for both eyes.
|-
| 1 - 3 or 3 - 1
| One eye found. Gaze data is the same for both eyes.
|-
| 2 - 2
| One eye found. Gaze data is the same for both eyes.
|-
| 4 - 4
| No eye found. Gaze data for both eyes are invalid.
|}

It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

===EyetrackerStatesOK===
Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T18:18:41Z

Gmilsap: Functional Description

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
* Fix Known Issues
* Add per-sample resolution to envelopes

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [[Programming_Reference:Events|bcievent]] interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
Experiments which require audio input or real-time audio synthesis based on system state are now possible with the AudioExtension. This extension is capable of recording multiple channels of audio input, synthesizing tones or noise, and reading encoded audio files. These channels are input to a mixing matrix which mixes those inputs to multiple channels of audio output. Both input and output are run through a simple filterbank, then they have their envelope extracted and logged into states via the bcievent interface. Audio input and output channels can be recorded into audio files losslessly and can be resynchronized offline. The mixing matrix is a matrix of expressions which can be used to dynamically change audio mixing based on the system state.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_AUDIOEXTENSION'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--EnableAudioExtension=1</code> command line argument.

==Block Diagram==

==Parameters==
The eyetracker is configured in the Source tab within the EyetrackerLogger section. The configurable parameters are:

*<code>LogEyetracker</code> - Enables/Disables logging of Eyetracker states
*<code>NetworkLocation</code> - The network address of the Eyetracker given by the Tobii Eyetracker Browser
*<code>Port</code> - The port that the Tobii communicates over - Tobii default is 4455
*<code>LogGazeData</code> - Enables/Disables logging of gaze data
*<code>LogEyePos</code> - Enables/Disables logging of eye position (as seen from the camera)
*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>GazeScale</code> - Scales the incoming gaze data first
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling

Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

The following code retreives the actual ~(0.0-1.0) range that the eyetracker outputs directly (assuming you've scaled and offset the signal to avoid clipping) from each eye and averages it to find a gaze position.
<pre>
float x = State( "EyetrackerLeftEyeGazeX" ) + State( "EyetrackerRightEyeGazeX" ); x /= ( 2.0f * 65535.0f );
float y = State( "EyetrackerLeftEyeGazeY" ) + State( "EyetrackerRightEyeGazeY" ); y /= ( 2.0f * 65535.0f );
x -= ( float )Parameter( "GazeOffset" ); x /= ( float )Parameter( "GazeScale" );
y -= ( float )Parameter( "GazeOffset" ); y /= ( float )Parameter( "GazeScale" );
</pre>

==State Variables==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye. The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.

===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0. They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled. (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].

===PosX, PosY===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled. Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535. (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.

===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled. It corresponds to the length of the longest chord drawn from one side of the pupil to the other. The size will change depending on the eye position and distance from the screen. Although it is given in mm, it would be best to use this as a relative measurement.

===EyeDist===
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation. The actual measurement will depend on whether or not the test subject is wearing glasses or not.

===EyeValidity===
This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.
* 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
* 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
* 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
* 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
* 4 - The actual gaze data is missing or definitely belonging to the other eye.

{| class="wikitable"
|-
! Code (Right - Left)
! Description
|-
| 0 - 0
| Both eyes found. Data is valid for both eyes.
|-
| 0 - 4 or 4 - 0
| One eye found. Gaze data is the same for both eyes.
|-
| 1 - 3 or 3 - 1
| One eye found. Gaze data is the same for both eyes.
|-
| 2 - 2
| One eye found. Gaze data is the same for both eyes.
|-
| 4 - 4
| No eye found. Gaze data for both eyes are invalid.
|}

It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

===EyetrackerStatesOK===
Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T15:04:58Z

Gmilsap:

==Synopsis==
An environment extension which manages multichannel, low latency audio I/O.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/AudioExtension

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
===Version History===
06/11/2012: Initial public release;

===Source Code Revisions===
*Initial development: 4095
*Tested under: 4095
*Known to compile under: 4095
*Broken since: --

===Todo===
Fix Known Issues

===Known Issues===
* Leaving the module running for long periods of time in halted state causes a long time of no state logging before signal goes to realtime. Seems to be unrelated to how long system was left running (~12-15 seconds) -- Not sure if this is an issue with the extension itself, or an issue with the [Programming_Reference:Events] bcievent interface.
* Bandpass filtering in filterbanks doesn't appear to function

==Functional Description==
In many cases, an experiment may require data about where the participant is looking. In these experiments, an eyetracker is the only way to gather data relating to gaze position and eye location. There are many eyetracking methods currently on the market, but many of these require the subject to hold their head steady -- often while strapped to a structure of some sort. The Tobii eyetrackers require no such restriction so they were a natural choice when it came to interfacing with BCI2000.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_EYETRACKERLOGGER'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--LogEyetracker=1</code> command line argument.

==Usage and Calibration==
Set up the eyetracker as detailed in the documentation that came with your device. The device will connect to your machine and communicate through the ethernet port. As such, it'd be wise to disconnect and turn off any other networking devices while using the eyetracker. It is possible that your network request could go out over a different network interface if you're not careful which makes for a troubleshooting nightmare. When you start the source module, ensure that the <code>--LogEyetracker=1</code> command line parameter is set. Run the Eyetracker Browser utility which came with your eyetracker drivers and use it to locate the device on your local network. Copy the network address to the clipboard and paste it in the <code>NetworkLocation</code> parameter within BCI2000. If the listed port is different, put that in the <code>Port</code> parameter in the BCI2000 operator.

Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eyewear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).

BCI2000 does not provide any way to calibrate the eyetracker. This should be done using the Tobii SDK sample application. The SDK can be obtained here: http://www.tobii.com/analysis-and-research/global/products/software/tobii-software-development-kit/. The 2.0 or Beta 3.0 SDK can be used to calibrate the device. When installed, open <code>C:\Program Files\Tobii\Tobii Eye Tracker SDK 2.0.1\samples\<\code> for the 2.0.1 SDK or <code>C:\Program Files\Tobii\SDK\Samples\</code> for the 3.0 Beta SDK and find the "Eye Tracker Components C++" or "EyetrackerComponents.Cpp" sample project. There should be a pre-built executable in this directory or a "prebuild" directory which can be used to run a calibration. Use the network address from the Eyetracker Browser and follow the instructions to calibrate and test your device. When you're done you can close the calibration utility and run BCI2000 - which will use the calibration saved on the device.

If you're using an T60/T120 or any future Tobii eyetracker with an attached display, you'll probably have it in a dual screen setup showing different things on both monitors - either extended or dualview. Typically, the Tobii monitor is used to present the task to the subject and the other monitor is used for the experimenter to control BCI2000 from. This can present a bit of a problem when calibrating because the sample application will only run on your "primary display" which may or may not be your Tobii monitor. Either set your primary display to be the Tobii screen or temporarily set the screen configuration into "clone" mode. A different screen resolution or aspect ratio does not impact the Tobii calibration process.

Once the device is calibrated, it can be used reliably in BCI2000. The logger will report information about eye validity in a text visualization window and feed states into the system.

==Parameters==
The eyetracker is configured in the Source tab within the EyetrackerLogger section. The configurable parameters are:

*<code>LogEyetracker</code> - Enables/Disables logging of Eyetracker states
*<code>NetworkLocation</code> - The network address of the Eyetracker given by the Tobii Eyetracker Browser
*<code>Port</code> - The port that the Tobii communicates over - Tobii default is 4455
*<code>LogGazeData</code> - Enables/Disables logging of gaze data
*<code>LogEyePos</code> - Enables/Disables logging of eye position (as seen from the camera)
*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>GazeScale</code> - Scales the incoming gaze data first
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling

Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

The following code retreives the actual ~(0.0-1.0) range that the eyetracker outputs directly (assuming you've scaled and offset the signal to avoid clipping) from each eye and averages it to find a gaze position.
<pre>
float x = State( "EyetrackerLeftEyeGazeX" ) + State( "EyetrackerRightEyeGazeX" ); x /= ( 2.0f * 65535.0f );
float y = State( "EyetrackerLeftEyeGazeY" ) + State( "EyetrackerRightEyeGazeY" ); y /= ( 2.0f * 65535.0f );
x -= ( float )Parameter( "GazeOffset" ); x /= ( float )Parameter( "GazeScale" );
y -= ( float )Parameter( "GazeOffset" ); y /= ( float )Parameter( "GazeScale" );
</pre>

==State Variables==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye. The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.

===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0. They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled. (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].

===PosX, PosY===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled. Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535. (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.

===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled. It corresponds to the length of the longest chord drawn from one side of the pupil to the other. The size will change depending on the eye position and distance from the screen. Although it is given in mm, it would be best to use this as a relative measurement.

===EyeDist===
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation. The actual measurement will depend on whether or not the test subject is wearing glasses or not.

===EyeValidity===
This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.
* 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
* 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
* 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
* 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
* 4 - The actual gaze data is missing or definitely belonging to the other eye.

{| class="wikitable"
|-
! Code (Right - Left)
! Description
|-
| 0 - 0
| Both eyes found. Data is valid for both eyes.
|-
| 0 - 4 or 4 - 0
| One eye found. Gaze data is the same for both eyes.
|-
| 1 - 3 or 3 - 1
| One eye found. Gaze data is the same for both eyes.
|-
| 2 - 2
| One eye found. Gaze data is the same for both eyes.
|-
| 4 - 4
| No eye found. Gaze data for both eyes are invalid.
|}

It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

===EyetrackerStatesOK===
Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:AudioExtension

2012-06-11T14:41:21Z

Gmilsap: Setting up format

==Synopsis==
A filter that records state information from ''Tobii Eyetrackers'' into state variables.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/EyetrackerLogger

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com), Jeremy Hill (jezhill@gmail.com).
===Version History===
06/09/2011: Initial public release;
06/10/2011: Hacked in scale and offset for gaze data;

===Source Code Revisions===
*Initial development: 3318
*Tested under: 3318
*Known to compile under: 3318
*Broken since: --

===Todo===
*Upgrade SDK version to 3.0 (once it's out of beta)
*Include a fixation/monitor filter
*Maybe a Qt calibration app

==Functional Description==
In many cases, an experiment may require data about where the participant is looking. In these experiments, an eyetracker is the only way to gather data relating to gaze position and eye location. There are many eyetracking methods currently on the market, but many of these require the subject to hold their head steady -- often while strapped to a structure of some sort. The Tobii eyetrackers require no such restriction so they were a natural choice when it came to interfacing with BCI2000.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_EYETRACKERLOGGER'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--LogEyetracker=1</code> command line argument.

==Usage and Calibration==
Set up the eyetracker as detailed in the documentation that came with your device. The device will connect to your machine and communicate through the ethernet port. As such, it'd be wise to disconnect and turn off any other networking devices while using the eyetracker. It is possible that your network request could go out over a different network interface if you're not careful which makes for a troubleshooting nightmare. When you start the source module, ensure that the <code>--LogEyetracker=1</code> command line parameter is set. Run the Eyetracker Browser utility which came with your eyetracker drivers and use it to locate the device on your local network. Copy the network address to the clipboard and paste it in the <code>NetworkLocation</code> parameter within BCI2000. If the listed port is different, put that in the <code>Port</code> parameter in the BCI2000 operator.

Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eyewear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).

BCI2000 does not provide any way to calibrate the eyetracker. This should be done using the Tobii SDK sample application. The SDK can be obtained here: http://www.tobii.com/analysis-and-research/global/products/software/tobii-software-development-kit/. The 2.0 or Beta 3.0 SDK can be used to calibrate the device. When installed, open <code>C:\Program Files\Tobii\Tobii Eye Tracker SDK 2.0.1\samples\<\code> for the 2.0.1 SDK or <code>C:\Program Files\Tobii\SDK\Samples\</code> for the 3.0 Beta SDK and find the "Eye Tracker Components C++" or "EyetrackerComponents.Cpp" sample project. There should be a pre-built executable in this directory or a "prebuild" directory which can be used to run a calibration. Use the network address from the Eyetracker Browser and follow the instructions to calibrate and test your device. When you're done you can close the calibration utility and run BCI2000 - which will use the calibration saved on the device.

If you're using an T60/T120 or any future Tobii eyetracker with an attached display, you'll probably have it in a dual screen setup showing different things on both monitors - either extended or dualview. Typically, the Tobii monitor is used to present the task to the subject and the other monitor is used for the experimenter to control BCI2000 from. This can present a bit of a problem when calibrating because the sample application will only run on your "primary display" which may or may not be your Tobii monitor. Either set your primary display to be the Tobii screen or temporarily set the screen configuration into "clone" mode. A different screen resolution or aspect ratio does not impact the Tobii calibration process.

Once the device is calibrated, it can be used reliably in BCI2000. The logger will report information about eye validity in a text visualization window and feed states into the system.

==Parameters==
The eyetracker is configured in the Source tab within the EyetrackerLogger section. The configurable parameters are:

*<code>LogEyetracker</code> - Enables/Disables logging of Eyetracker states
*<code>NetworkLocation</code> - The network address of the Eyetracker given by the Tobii Eyetracker Browser
*<code>Port</code> - The port that the Tobii communicates over - Tobii default is 4455
*<code>LogGazeData</code> - Enables/Disables logging of gaze data
*<code>LogEyePos</code> - Enables/Disables logging of eye position (as seen from the camera)
*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)
*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
*<code>GazeScale</code> - Scales the incoming gaze data first
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling

Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

The following code retreives the actual ~(0.0-1.0) range that the eyetracker outputs directly (assuming you've scaled and offset the signal to avoid clipping) from each eye and averages it to find a gaze position.
<pre>
float x = State( "EyetrackerLeftEyeGazeX" ) + State( "EyetrackerRightEyeGazeX" ); x /= ( 2.0f * 65535.0f );
float y = State( "EyetrackerLeftEyeGazeY" ) + State( "EyetrackerRightEyeGazeY" ); y /= ( 2.0f * 65535.0f );
x -= ( float )Parameter( "GazeOffset" ); x /= ( float )Parameter( "GazeScale" );
y -= ( float )Parameter( "GazeOffset" ); y /= ( float )Parameter( "GazeScale" );
</pre>

==State Variables==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye. The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.

===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0. They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled. (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].

===PosX, PosY===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled. Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535. (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.

===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled. It corresponds to the length of the longest chord drawn from one side of the pupil to the other. The size will change depending on the eye position and distance from the screen. Although it is given in mm, it would be best to use this as a relative measurement.

===EyeDist===
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation. The actual measurement will depend on whether or not the test subject is wearing glasses or not.

===EyeValidity===
This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.
* 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
* 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
* 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
* 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
* 4 - The actual gaze data is missing or definitely belonging to the other eye.

{| class="wikitable"
|-
! Code (Right - Left)
! Description
|-
| 0 - 0
| Both eyes found. Data is valid for both eyes.
|-
| 0 - 4 or 4 - 0
| One eye found. Gaze data is the same for both eyes.
|-
| 1 - 3 or 3 - 1
| One eye found. Gaze data is the same for both eyes.
|-
| 2 - 2
| One eye found. Gaze data is the same for both eyes.
|-
| 4 - 4
| No eye found. Gaze data for both eyes are invalid.
|}

It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

===EyetrackerStatesOK===
Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Contributions:Extensions

2012-06-11T14:38:07Z

Gmilsap: Added page for AudioExtension

A framework ''Extension'' is an optional contributed plugin which can affect multiple modules. For example, various manufacturer-specific [[User Reference:Logging Input|input-device loggers]] are provided in the <code>src/contrib/Extensions</code> folder, and these can be optionally added to the BCI2000 framework for SignalSource modules, thereby giving all source modules the ability to log input from the corresponding devices. Selecting a custom Extension, and re-building your modules to include it, requires the use of CMake and a supported C++ compiler: see the [[Programming Howto:Quickstart Guide]] for a walkthrough that shows you how to recompile BCI2000 modules.

The following user extensions are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

*[[Contributions:DataGloveLogger]]: A logger extension which acquires data from the 5DT Data Glove Ultra.
*[[Contributions:EyetrackerLogger]]: A logger extension which acquires data from Tobii eyetrackers.
*[[Contributions:GazeMonitorFilter]]: An application module filter extension which supports the EyetrackerLogger.
*[[Contributions:WiimoteLogger]]: A logger extension which acquires data from Nintendo Wii Remotes.
*[[Contributions:WebcamLogger]]: A logger extension which allows for synchronizing webcam video.
*[[Contributions:AudioExtension]]: An all purpose audio toolkit which allows for realtime multichannel audio I/O

==See also==
[[Programming Reference:EnvironmentExtension Class]]

[[Programming Tutorial:Implementing an Input Logger]][[Category:Contents]]

User Reference:gHIamp

2012-02-24T17:48:23Z

Gmilsap: Work in Progress

==Synopsis==
The g.HIamp is a 256 channel amplifier from g.tec. The contributed source module acquires raw signals from the amplifier in real time for use in BCI2000.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/gHIampSource

==Versioning==

===Authors===
Griffin Milsap (griffin.milsap@gmail.com)
Rensselaer Polytechnic Institute

===Version History===
Version 0.9: August 2011
* Supports one g.HIamp
* Supports Filters
* Referencing by any channel
* Future compatible with g.HIamp master/slave configurations
* Using g.HIamp C API version 1.11.02

===Source Code Revisions===
*Initial development: 3472
*Tested under: 3763
*Known to compile under: 3798
*Broken since: --

==Functional Description==
Acquires raw data from the g.HIamp.

==Installation==
Compile the gHIampSource module using [[Programming_Reference:Build_System#How_To_Build_Using_CMake|CMake and your compiler]]. The resulting gHIampSource.exe should be placed in the prog directory automatically.

==Parameters==
* '''SourceCh''' represents the total number of channels to be logged from the source module.
* '''SampleBlockSize''' should be set equal to the size of the sample block pulled from the device. 
** '''NOTE:''' Only specific combinations of SampleBlockSize and SampleRate are valid! See [[#Valid Operating Modes]]
* '''SampleRate''' determines the rate at which the device samples data. 
** '''NOTE:''' Only specific combinations of SampleBlockSize and SampleRate are valid! See [[#Valid Operating Modes]]
* '''ChannelNames''' is a convenience parameter. Name channels here and they can be referenced by these names later.
* '''SourceChOffset''' should be set to a list of "0"s -- one 0 for each channel as indicated by SourceCh, separated by spaces.
* '''SourceChGain''' should be set to a list of "1"s -- one 0 for each channel as indicated by SourceCh, separated by spaces.
* '''DeviceIDMaster''' is the serial number identifier of the master g.HIamp device. This serial can be found on the physical device and is typically in a "'''HA-20XX.XX.XX'''" format. This parameter can also be set to "'''auto'''" if there is only one g.HIamp device connected to the machine.
* '''DeviceIDs''' is a list of device serials (typically in "'''HA-20XX.XX.XX'''" format) which corresponds to the devices to record channels from. One of these serials must be specified as the master device in the "DeviceIDMaster" parameter. This parameter can also be set to "'''auto'''" if there is only one g.HIamp device connected to the machine. 
** '''NOTE:''' Device slaving is not yet supported by the module OR the g.HIamp C API. -- This parameter only exists for future compatibility. 
* '''RefChList''' is a list of channels which can act as "Reference" channels for each amp. If left blank, no channel will be used as a reference, and the raw signal will be recorded in the output. 
** '''NOTE:''' If specifying reference channels, there must be one reference channel per device specified in "DeviceIDs" in the same order. 
* '''SourceChList'''
* '''FilterEnabled'''
* '''FilterHighPass'''
* '''FilterLowPass'''
* '''FilterModelOrder'''
* '''FilterType'''
* '''NotchEnabled'''
* '''NotchHighPass'''
* '''NotchLowPass'''
* '''NotchModelOrder'''
* '''NotchType'''
* '''SourceBufferSize'''

===Valid Operating Modes===
The gHIamp only accepts specific combinations of sampling rates and sample block sizes. The following table shows all valid combinations of sample rate and block size. Operating outside of these modes is untested and could result in problems.

{| border="1"
!Sample Rate
!Valid Sample Block Sizes
|-
|256 Samples per second
|1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 32 64 128 256
|-
|512 Samples per second
|2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 32 64 128 256
|-
|600 Samples per second
|4 5 6 7 8 9 10 11 12 13 15 16 17 32 64 128 256
|-
|1200 Samples per second
|8 9 10 11 12 13 14 15 16 32 64 128 256
|-
|2400 Samples per second
|16 32 64 128 256
|-
|4800 Samples per second
|32 64 128 256
|}

==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Help:Editing

2012-02-24T17:25:03Z

Gmilsap: This should be easier.

http://www.mediawiki.org/wiki/Help:Editing

Help:Formatting

2012-02-24T17:24:01Z

Gmilsap: Gah... Too much work.

User Reference:gHIamp

2012-02-24T17:20:40Z

Gmilsap: Added Valid Operating Modes

Help:Formatting

2012-02-24T17:15:45Z

Gmilsap: Added a formatting help page from MediaWiki

You can format your text by using wiki markup. This consists of normal characters like asterisks, single quotes or equal signs which have a special function in the wiki, sometimes depending on their position. For example, to format a word in ''italic'', you include it in two pairs of single quotes like <code><nowiki>''this''</nowiki></code>.

== Text formatting markup ==

{| class="wikitable"
! Description
! width=40% | You type
! width=40% | You get
|-
! colspan="3" style="background:#ABE" | character (inline) formatting – ''applies anywhere''
|-
| Italic text
| <pre>
''italic''
</pre>
|
''italic''
|-
| Bold text
| <pre>
'''bold'''
</pre>
|
'''bold'''
|-
| Bold and italic
| <pre>
'''''bold & italic'''''
</pre>
|
'''''bold & italic'''''
|-
| Escape wiki markup
| <pre>
<nowiki>no ''markup''</nowiki>
</pre>
|
<nowiki>no ''markup''</nowiki>
|-
| Escape wiki markup once
| <pre>
[[API]]<nowiki/>extension
</pre>
|
[[API]]<nowiki/>extension
|-
! colspan="3" style="background:#ABE" | section formatting – ''only at the beginning of the line''
|-
| Headings of different levels
| <pre>

== Level 2 ==

=== Level 3 ===

==== Level 4 ====

===== Level 5 =====

====== Level 6 ======

</pre>
----
|

== Level 2 ==

=== Level 3 ===

==== Level 4 ====

===== Level 5 =====

====== Level 6 ======

|-
| Horizontal rule
| <pre>
Text above
----
Text below
</pre>
|
Text above
----
Text below
|-
| Bullet list
|
<pre>
* Start each line
* with an [[Wikipedia:asterisk|asterisk]] (*).
** More asterisks gives deeper
*** and deeper levels.
* Line breaks don't break levels.
*** But jumping levels creates empty space.
Any other start ends the list.
</pre>
|
* Start each line
* with an [[Wikipedia:asterisk|asterisk]] (*).
** More asterisks gives deeper
*** and deeper levels.
* Line breaks don't break levels.
*** But jumping levels creates empty space.
Any other start ends the list.
|-
| Numbered list
|
<pre>
# Start each line
# with a [[Wikipedia:Number_sign|number sign]] (#).
## More number signs gives deeper
### and deeper
### levels.
# Line breaks don't break levels.
### But jumping levels creates empty space.
# Blank lines

# end the list and start another.
Any other start also
ends the list.
</pre>
|
# Start each line
# with a [[Wikipedia:Number_sign|number sign]] (#).
## More number signs gives deeper
### and deeper
### levels.
# Line breaks don't break levels.
### But jumping levels creates empty space.
# Blank lines

# end the list and start another.
Any other start also
ends the list.
|-
| Definition list
| <pre>
;item 1
: definition 1
;item 2
: definition 2-1
: definition 2-2
</pre>
|
;item 1
: definition 1
;item 2
: definition 2-1
: definition 2-2
|-
| Indent text
| <pre>
: Single indent
:: Double indent
::::: Multiple indent
</pre>
----
|
: Single indent
:: Double indent
::::: Multiple indent
|-
| Mixture of different types of list
|
<pre>
# one
# two
#* two point one
#* two point two
# three
#; three item one
#: three def one
# four
#: four def one
#: this looks like a continuation
#: and is often used
#: instead of <nowiki> </nowiki>
# five
## five sub 1
### five sub 1 sub 1
## five sub 2
</pre>
----
|
# one
# two
#* two point one
#* two point two
# three
#; three item one
#: three def one
# four
#: four def one
#: this looks like a continuation
#: and is often used
#: instead of <nowiki> </nowiki>
# five
## five sub 1
### five sub 1 sub 1
## five sub 2{{anchor|pre}}
|-
| Preformatted text
| <pre>
Start each line with a space.
Text is '''preformatted''' and
''markups'' '''''can''''' be done.
</pre>
----
|
Start each line with a space.
Text is '''preformatted''' and
''markups'' '''''can''''' be done.
|-
| Preformatted text blocks
| <pre> <nowiki><nowiki>Start with a space in the first column,
(before the <nowiki>).

Then your block format will be
maintained.

This is good for copying in code blocks:

def function():
"""documentation string"""

if True:
print True
else:
print False</nowiki></nowiki>
</pre>
|
<nowiki>Start with a space in the first column,
(before the <nowiki>).

Then your block format will be
maintained.

This is good for copying in code blocks:

def function():
"""documentation string"""

if True:
print True
else:
print False</nowiki>
|}

== Paragraphs ==

MediaWiki ignores single line breaks. To start a new paragraph, leave an empty line. You can force a line break within a paragraph with the HTML tag <code> </code>.

== HTML tags ==

Some [[wikipedia:HTML|HTML]] tags are allowed in MediaWiki, for example <code><code></code>, <code><div></code>, <code><nowiki></nowiki></code> and <code><nowiki></nowiki></code>. These apply anywhere you insert them.

{| class="wikitable"
! Description
! width=40% | You type
! width=40% | You get
|-
| Inserted (Displays as underline in most browsers.)
| <pre>
<ins>Inserted</ins>

or

Underline
</pre>
|
<ins>Inserted</ins>

or

Underline
|-
| Deleted (Displays as strikethrough in most browsers.)
| <pre>
<del>Deleted</del>

or

Deleted
</pre>
|
<del>Deleted</del>

or

Deleted
|-
| Fixed width text
| <pre>
<code>Source code</code>

or

<tt>Fixed width text</tt>
</pre>
|
<code>Source code</code>

or

<tt>Fixed width text</tt>
|-
| Blockquotes
| <pre>
text above
text above
<blockquote>blockquote</blockquote>
text below
text below
</pre>
|
text above
text above
<blockquote>blockquote</blockquote>
text below
text below
|-
| Comment
| <pre>

Comments are only visible
in the edit window.
</pre>
|

Comments are only visible
in the edit window.
|-
| Completely preformatted text
| <pre>
<pre> Text is '''preformatted''' and
''markups'' '''''cannot''''' be done</pre>
</pre>
----
|
<pre> Text is '''preformatted''' and
''markups'' '''''cannot''''' be done</pre>
|-
| '''Customized''' preformatted text
| <pre>
<pre style="color:red">
Text is '''preformatted'''
with a style and
''markups'' '''''cannot''''' be done
</pre>
</pre>
----
|
<pre style="color:red">
Text is '''preformatted'''
with a style and
''markups'' '''''cannot''''' be done
</pre>
|-
| '''Customized''' preformatted text with text wrap according to screen width
| <pre>
<pre style="white-space: pre-wrap">
This longer sentence is used to demonstrate text wrapping. </pre>
</pre>
|
<pre style="white-space: pre-wrap">
This longer sentence is used to demonstrate text wrapping.</pre>
|}

== Inserting symbols ==

Symbols and other special characters not available on your keyboard can be inserted through a special sequence of characters. Those sequences are called HTML entities. For example, the following sequence (entity) '''&rarr;''' when inserted will be shown as <ins>right arrow</ins> HTML symbol → and '''&mdash;''' when inserted will be shown as an <ins>em dash</ins> HTML symbol —
----

{| class="wikitable" align=center width=100%
! colspan=32 | HTML symbol entities
|- align=center| '''Á
| '''á
| '''Â
| '''â
| '''´
| '''Æ
| '''æ
| '''À
| '''à
| '''&alefsym;
| '''Α
| '''α
| '''&
| '''&and;
| '''&ang;
| '''Å
| '''å
| '''≈
| '''Ã
| '''ã
| '''Ä
| '''ä
| '''&bdquo;
| '''Β
| '''β
| '''¦
| '''•
| '''∩
| '''Ç
| '''ç
| '''¸
| '''¢
|- align=center
| '''Χ
| '''χ
| '''&circ;
| '''&clubs;
| '''&cong;
| '''©
| '''&crarr;
| '''∪
| '''¤
| '''&dagger;
| '''&Dagger;
| '''↓
| '''&dArr;
| '''°
| '''Δ
| '''δ
| '''&diams;
| '''÷
| '''É
| '''é
| '''Ê
| '''ê
| '''È
| '''è
| '''∅
| '''&emsp;
| '''&ensp;
| '''Ε
| '''ε
| '''&equiv;
| '''Η
| '''η
|- align=center
| '''Ð
| '''ð
| '''Ë
| '''ë
| '''€
| '''∃
| '''&fnof;
| '''∀
| '''½
| '''¼
| '''¾
| '''&frasl;
| '''Γ
| '''γ
| '''≥
| '''>
| '''↔
| '''⇔
| '''&hearts;
| '''…
| '''Í
| '''í
| '''Î
| '''î
| '''¡
| '''Ì
| '''ì
| '''&image;
| '''∞
| '''∫
| '''Ι
| '''ι
|- align=center
| '''¿
| '''∈
| '''Ï
| '''ï
| '''Κ
| '''κ
| '''Λ
| '''λ
| '''&lang;
| '''«
| '''←
| '''⇐
| '''&lceil;
| '''“
| '''≤
| '''&lfloor;
| '''&lowast;
| '''&loz;
| '''&lrm;
| '''&lsaquo;
| '''‘
| '''<
| '''¯
| '''—
| '''µ
| '''·
| '''−
| '''Μ
| '''μ
| '''∇
| ''' 
| '''–
|- align=center
| '''≠
| '''&ni;
| '''¬
| '''∉
| '''&nsub;
| '''Ñ
| '''ñ
| '''Ν
| '''ν
| '''Ó
| '''ó
| '''Ô
| '''ô
| '''&OElig;
| '''&oelig;
| '''Ò
| '''ò
| '''&oline;
| '''Ω
| '''ω
| '''Ο
| '''ο
| '''&oplus;
| '''&or;
| '''ª
| '''º
| '''Ø
| '''ø
| '''Õ
| '''õ
| '''&otimes;
| '''Ö
|- align=center
| '''ö
| '''¶
| '''∂
| '''&permil;
| '''&perp;
| '''Φ
| '''φ
| '''Π
| '''π
| '''ϖ
| '''±
| '''£
| '''′
| '''″
| '''∏
| '''&prop;
| '''Ψ
| '''ψ
| '''"
| '''√
| '''&rang;
| '''»
| '''→
| '''⇒
| '''&rceil;
| '''”
| '''&real;
| '''®
| '''&rfloor;
| '''Ρ
| '''ρ
| '''&rlm;
|- align=center
| '''&rsaquo;
| '''’
| '''&sbquo;
| '''&Scaron;
| '''&scaron;
| '''⋅
| '''§
| '''
| '''Σ
| '''σ
| '''&sigmaf;
| '''&sim;
| '''&spades;
| '''⊂
| '''&sube;
| '''∑
| '''⊃
| '''¹
| '''²
| '''³
| '''&supe;
| '''ß
| '''Τ
| '''τ
| '''&there4;
| '''Θ
| '''θ
| '''&thetasym;
| ''' 
| '''Þ
| '''þ
| '''&tilde;
|- align=center
| '''×
| '''™
| '''Ú
| '''ú
| '''↑
| '''&uArr;
| '''Û
| '''û
| '''Ù
| '''ù
| '''¨
| '''&upsih;
| '''Υ
| '''υ
| '''Ü
| '''ü
| '''&weierp;
| '''Ξ
| '''ξ
| '''Ý
| '''ý
| '''¥
| '''ÿ
| '''&Yuml;
| '''Ζ
| '''ζ
| '''&zwj;
| '''&zwnj;'''
|}

{| class="wikitable"
! Description
! width=40% | You type
! width=40% | You get
|-
| Copyright symbol
| <tt><pre>
&copy;
</pre></tt>
|
:::'''©'''
|-
| Greek delta letter symbol
| <tt><pre>
&delta;
</pre></tt>
|
:::'''δ'''
|-
| Euro currency symbol
| <tt><pre>
&euro;
</pre></tt>
|
:::'''€'''
|}

See the list of all HTML entities on the Wikipedia article [[w:List of HTML entities|List of HTML entities]]. Additionally, MediaWiki supports two non-standard entity reference sequences: <code>&רלמ;</code> and <code>&رلم;</code> which are both considered equivalent to <code>&rlm;</code> which is a [[w:Right-to-left mark|right-to-left mark]]. (Used when combining right to left languages with left to right languages in the same page.)

== HTML tags and symbol entities displayed themselves (with and without interpreting them) ==

:<tt>&amp;euro;</tt>  → '''&euro;'''

:<tt>Typo to be corrected</tt>  → '''Typo to be corrected'''

:<tt>&lt;span style="color: red; text-decoration: line-through;">Typo to be corrected&lt;/span></tt>  → '''Typo to be corrected'''

== Other formatting ==

Beyond the text formatting markup shown above, here are some other formatting references:

* [[Help:Links|Links]]
* [[Help:Images|Images]]
* [[Help:Tables|Tables]]

[[Category:Help|Formatting]]

Help:Editing

2012-02-24T17:11:34Z

Gmilsap: Got sick of looking for formatting help only to be booted to a blank page.

User Reference:gHIamp

2012-02-24T17:04:06Z

Gmilsap: /* Parameters */

User Reference:gHIamp

2012-02-24T16:41:39Z

Gmilsap: /* Source Code Revisions */

User Reference:gHIamp

2012-02-24T16:36:08Z

Gmilsap: Started on Documentation for gHIampSource

Contributions:ADCs

2012-02-24T15:24:29Z

Gmilsap: Added a link to gHIamp documentation

The following data acquisition filters are available in the [[Contributions:Contents|Contributions]] section of BCI2000:

*[[Contributions:AmpServerProADC]]: Interface to the EGI AmpServerPro.
*[[Contributions:BioRadioADC]]: Interface to the BioRadio amplifer.
*[[Contributions:Biosemi2ADC]]: Interface to the Biosemi amplifier.
*[[Contributions:B-Alert]]: Interface to B-Alert brain monitoring systems.
*[[Contributions:DAS_ADC]]: Interface to MeasurementComputing AD cards.
*[[Contributions:DTADC]]: Interface to Data Translation boards.
*[[Contributions:Emotiv]]: Interface to the Emotiv EPOC.
*[[Contributions:FieldTripBufferSource]]: Interface to the FieldTrip buffer.
*[[Contributions:FilePlayback]]: A source module that replays sessions from recorded data files.
*[[Contributions:gHIamp]]: Interface to the gHIamp.
*[[Contributions:MicromedADC]]: Interface to the Micromed EEG system.
*[[Contributions:ModularEEG]]: Interface to the ModularEEG system.
*[[Contributions:Neuralynx]]: Interface to Neuralynx systems
*[[Contributions:NIADC]]: Interface to National Instruments boards.
*[[Contributions:NIDAQ-MX]]: Interface to National Instruments boards using the MX driver.
*[[Contributions:NIDAQLogger]]: Interface to multiple National Instruments DAQ boards using MX driver (INPUT ONLY).
*[[Contributions:NIDAQFilter]]: Interface to multiple National Instruments DAQ boards using MX driver (OUTPUT ONLY).
*[[Contributions:NeuroscanADC]]: Neuroscan Acquire socket protocol client.
*[[Contributions:NeuroscanAccessSDK]]: Interface to Neuroscan Direct Access SDK.
*[[Contributions:NeuroSky]]: Interface to Neurosky MindSet.
*[[Contributions:NicoletOne]]: Interface to NicoletOne nEEG series amplifiers.
*[[Contributions:ctfneurod]]: CTF RealTime to Neuroscan Acquire relay.
*[[Contributions:RDAClientADC]]: Brain Vision RDA socket protocol client.
*[[Contributions:TDTADC]]: Interface to Tucker-Davis Pentusa systems.
*[[Contributions:TMSiADC]]: Interface to TMSi Refa and Porti systems.
*[[Contributions:vAmpADC]]: Interface to Brain Products V-amp systems.
*[[Contributions:EnobioADC]]: Interface to Enobio sensor.
*[[Contributions:MicRecorderFilter]]: Interface to the system soundcard, logging audio input.

==See also==
[[User Reference:Filters]], [[Contributions:How to use a Contributed Source Module]]

[[Category:Contents]][[Category:Data Acquisition]]

Contributions:NeuroSky

2012-02-07T14:08:08Z

Gmilsap: /* Known Issues */

==Synopsis==
NeuroSky Mindset Acquisition Module

===Known Issues===

As of binary release of 3.0.4, the module will erroneously report that COM port baud rate must be set to 57600. Regardless of what it says, '''ensure your baud rate is set to 9600'''. This has been fixed in HEAD

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/NeuroSky

==Versioning==

===Authors===
Griffin Milsap (griffin.milsap@gmail.com)

===Version History===

===Source Code Revisions===

==Functional Description==
Acquires signal data from the NeuroSky Mindset. Device must first be connected and paired via Bluetooth.

Note: Current module only works with the single channel Mindset device. A future version (June 2011) will include support for newer NeuroSky devices.

==Installation==
Copy the Thinkgear.dll to the prog directory for the module to work.

==Parameters==

* The device has one channel, so '''SourceCh''' must be set to 1.
* The device's sampling rate is 512Hz, so the '''SamplingRate''' parameter must be set to 512.
* Ideally, the device has no DC offset, so '''SourceChOffset''' should be set to 0
* '''SourceChGain''' must be set to the Neurosky's actual conversion factor: 0.2197.

* '''COMPort''' is an enumerated parameter which allows you to select which COM port the device resides on. This can be found by looking through your bluetooth settings. It is also possible to set the COM port to a lower number, if the default COM port is over 16.

==States==
States regarding signal quality are in the works.

==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:NeuroSky

2012-02-07T14:06:23Z

Gmilsap:

==Synopsis==
NeuroSky Mindset Acquisition Module

===Known Issues===

As of binary release of 3.0.4, the module will erroneously report that COM port baud rate must be set to 57600. Regardless of what it says, ensure your baud rate is set to 9600. This has been fixed in HEAD

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/NeuroSky

==Versioning==

===Authors===
Griffin Milsap (griffin.milsap@gmail.com)

===Version History===

===Source Code Revisions===

==Functional Description==
Acquires signal data from the NeuroSky Mindset. Device must first be connected and paired via Bluetooth.

Note: Current module only works with the single channel Mindset device. A future version (June 2011) will include support for newer NeuroSky devices.

==Installation==
Copy the Thinkgear.dll to the prog directory for the module to work.

==Parameters==

* The device has one channel, so '''SourceCh''' must be set to 1.
* The device's sampling rate is 512Hz, so the '''SamplingRate''' parameter must be set to 512.
* Ideally, the device has no DC offset, so '''SourceChOffset''' should be set to 0
* '''SourceChGain''' must be set to the Neurosky's actual conversion factor: 0.2197.

* '''COMPort''' is an enumerated parameter which allows you to select which COM port the device resides on. This can be found by looking through your bluetooth settings. It is also possible to set the COM port to a lower number, if the default COM port is over 16.

==States==
States regarding signal quality are in the works.

==See also==
[[User Reference:Filters]], [[Contributions:ADCs]]

[[Category:Contributions]][[Category:Data Acquisition]]

Contributions:GazeMonitorFilter

2011-07-19T15:58:17Z

Gmilsap: /* Parameters */ New image size parameter

==Synopsis==
An application filter which greatly eases using the [[Contributions:EyetrackerLogger|EyetrackerLogger]] extension which is capable of visualizing eye tracker states in real time, manages fixation enforcement, and provides functionality for re-alignment of the subject.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/GazeMonitorFilter

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com).
===Version History===
07/08/2011: Initial release

===Source Code Revisions===
*Initial development: 3389
*Tested under: 3389
*Known to compile under: 3389
*Broken since: --

==Functional Description==
GazeMonitorFilter is a "drop-in" application module extension which automatically performs tasks commonly associated with using an eye tracker. It has been designed for use with the [[Contributions:EyetrackerLogger|EyetrackerLogger]] extension. When added into an application module, the GazeMonitorFilter is capable of drawing to the application window or in a layer on top of the application visualization screen.

===Fixation Management===
Even without eyetracker states, the GazeMonitorFilter is capable of drawing fixation images on the screen, but with Eyetracker<Left/Right>EyeGaze<X/Y> states, GazeMonitorFilter is capable of enforcing this fixation and setting the <code>FixationViolated</code> state which indicates violation of the fixation should it occur. The fixation is entirely parameterized and allows for detailed configuration of fixation management.

===Visualization===
GazeMonitorFilter is also capable of drawing a visualization of eye position (if it's logged) and gaze location (if it's logged) to the application window visualization screen. This enables the experimenter to monitor the eye tracker states visually in realtime for early detection (and later correction) of acquiring poor gaze data.

===Subject Correction===
With many eye trackers, accuracy diminishes as gaze diverts from the center of the screen. Even if the eye tracker is well calibrated, a sizable difference can exist between where the subject is actually looking and where the eye tracker gaze data reports the subject is looking. With Tobii eye trackers, this was seen more prominently as the subject's head changed position or orientation. GazeMonitorFilter provides functionality for giving the subject visual feedback and prompts which direct the subject to move back to the position they calibrated in.

If asked nicely, the GazeMonitorFilter may also brew you a cup of coffee.

==Integration into BCI2000==
Compile the extension into your application modules by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_GAZEMONITORFILTER'''.

==Parameters==
The GazeMonitorFilter is configured in the Application tab within the GazeMonitor section. The configurable parameters are:

*<code>VisualizeGazeMonitorFilter</code> - Enables/Disables visualization of eye tracker states on the application visualization window
*<code>EnforceFixation</code> - Enables/Disables fixation management.
*<code>FixationX</code> - Expression which defines requested fixation location X coordinate. (0.0 - 1.0)
*<code>FixationY</code> - Expression which defines requested fixation location Y coordinate. (0.0 - 1.0)
*<code>BlinkTime</code> - The amount of time allowed for which eye states reported by [[Contributions:EyetrackerLogger|EyetrackerLogger]] can remain "invalid" before fixation has been violated.
*<code>SaccadeTime</code> - The amount of time allowed for which valid gaze data reported by [[Contributions:EyetrackerLogger|EyetrackerLogger]] can exist outside of the designated fixation before fixation has been violated.
*<code>FixationRadius</code> - The maximum distance from the center of fixation (FixationX, FixationY) from which the gaze data can deviate without violating fixation.
*<code>FixationImage</code> - The image displayed at the center of fixation while fixation is not violated.
*<code>FixationViolationImage</code> - The image displayed at the center of fixation while fixation is violated.
*<code>FixationImageSize</code> - The fixation image size in percentage of the screen height
*<code>FixationViolationSound</code> - The sound played every time fixation has just been violated.
*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.

===Notes===
*For <code>FixationX</code> and <code>FixationY</code>, the top left corner of the screen is (0.0, 0.0) and the bottom right corner of the screen is (1.0, 1.0)
*Specifying large images for <code>FixationImage</code> and <code>FixationViolationImage</code> is not recommended as it may have a detrimental impact on overall system timing.
*If either of the timing parameters (<code>BlinkTime</code> and <code>SaccadeTime</code>) trigger a fixation violation, fixation violation will not occur again when the other timing parameter triggers if fixation has not been acquired again. (Example: One second is allotted for <code>BlinkTime</code> and 4 seconds is allotted for <code>SaccadeTime</code>. Gaze moves outside of fixation and eyes close immediately thereafter and remain closed. <code>FixationViolated</code> is set after one second of the eyes being closed, and is not thrown again when the four seconds of gaze existing outside the allowed fixation radius elapse.)
*A Fixation image can be drawn when there is no gaze data available to enforce the fixation. That said, FixationViolationImage, FixationViolationSound are not ever presented and the fixation timing and radius parameters remain unused due to lack of ability to determine if fixation has indeed been violated.
*Real time visualization of gaze data on the application visualization screen is controlled by the <code>VisualizeGazeMonitorFilter</code> parameter declared by GazeMonitorFilter and the <code>AppWindow<Spatial/Temporal>Decimation</code> parameters declared by the ApplicationWindow class. Control the performance of your system by decimating how often and how large GazeMonitorFilter visualization updates are.

==State Variables==
*<code>FixationViolated</code> - This state is set to "1" when the GazeMonitorFilter has determined that fixation is violated and is set back to 0 when fixation is acquired again.
*<code>GazeCorrectionMode</code> - This state is monitored by GazeMonitorFilter. When this state is set to "1", GazeMonitorFilter will perform the gaze correction procedure. When the procedure has completed, the state is set by GazeMonitorFilter back to 0.

==Gaze Correction Mode==
Gaze correction mode is initiated by setting the state <code>GazeCorrectionMode</code> to "1". GazeMonitorFilter will then perform the gaze correction procedure and set the state back to "0" when the procedure has concluded.

During the procedure, a prompt will be displayed to the subject on the application window at their current gaze location. The prompt position is "smoothed" to increase readability of the prompt and is not an accurate representation of where the subject's gaze is located at any particular frame.

===Gaze Correction Procedure===
#Subject is prompted to "Fixate". The subject will need to move his/her gaze into the fixation position/radius in order to continue in the procedure.
#Subject is prompted to move "Closer" to the screen or "Further" from the screen. The subject will need to move his/her eyes to between 550mm and 600mm away from the screen in order to continue in the procedure. Once the subject is fixated and at the correct distance from the screen, the fixation radius indicator will turn green.
#Subject must hold this position for four seconds. After four seconds (and a visual count down prompt) the procedure will be complete and the <code>GazeCorrectionMode</code> will be set back to "0"

*Note -- Eye position data is displayed to the experimenter through the application visualization window through the use of the <code>VisualizeGazeMonitorFilter</code> parameter if and only if eye position data is being logged. If the subject calibrated with their eyes centered in the eye tracker's cameras, the experimenter can re-position the subject's head during this procedure based on the feedback provided by the application visualization window. This eye position data was not included explicitly as part of the gaze correction procedure for ease of use.

==Integration of GazeMonitorFilter Capabilities==
If you wish for your task to interact with the GazeMonitorFilter, you may need to make a few small source code modifications to your task.

===Triggering Gaze Correction Mode from Within a Task===
Integration of gaze correction mode into a task consists of setting the GazeCorrectionMode state to "1" if it exists, and waiting for the state to be set back to "0" before continuing with the run. This is done as follows:

*Check for the existence of the GazeCorrectionMode state in <code>Preflight()</code>
<pre>
void
MyTask::Preflight( const SignalProperties&, SignalProperties& ) const
{
...
OptionalState( "GazeCorrectionMode" );
...
}
</pre>

*To turn on gaze correction mode
<pre>
if( States->Exists( "GazeCorrectionMode" ) )
{
State( "GazeCorrectionMode" ) = 1;
// Disable drawing of your stimuli in here
}
</pre>

*To wait for gaze correction mode to complete
<pre>
void
MyTask::Process( const GenericSignal&, GenericSignal& )
{
...
if( !OptionalState( "GazeCorrectionMode", 0 ) )
{
// Update stimuli and continue performing task related things
}
...
}
</pre>

===Triggering Gaze Correction Mode Manually===
The BCI2000 Operator provides "function" buttons which can be scripted to modify the environment. The following changes are necessary to set one of the "function" buttons to modify the <code>GazeCorrectionMode</code> state in order to allow the experimenter to trigger this mode at will:

*Open Operator.exe
*File->Preferences
*In the "Function Buttons" choose a button to modify and set the Name to "Correction" and the command to:
<pre>
SET STATE GazeCorrectionMode 1
</pre>

===Reacting to Fixation Violation Within a Task===
It may be the case that you want your task to react to a fixation violation event; for example, you may end a trial if fixation has been violated. To do this, make the following changes in your task's source code:

*Check for the existence of the <code>FixationViolated</code> state in <code>Preflight()</code>
<pre>
void
MyTask::Preflight( const SignalProperties&, SignalProperties& ) const
{
...
OptionalState( "FixationViolated" );
...
}
</pre>

*Read the state this way wherever you need to react to it:
<pre>
if( OptionalState( "FixationViolated", 0 ) )
{
// React to the fixation being violated
}
</pre>

==See also==
[[Contributions:EyetrackerLogger]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]

Programming Reference:Events

2011-07-13T16:57:28Z

Gmilsap: /* Limitations */

This page describes how to record asynchronous information ("events") along with brain signal data. This usage of the term "event" is unrelated to "events" as part of [[Programming Reference:Contents#Programming_Interface_Documentation|BCI2000 API class interfaces]].

As data are recorded by data acquisition hardware in chunks, BCI2000 processes them synchronously.
Still, recording information that is asynchronous to brain signal data acquisition may be of interest to an experimenter. Typically, mouse or keyboard input may be of interest to record in an experiment, and ideally should provide a temporal resolution that corresponds to the brain signal's sampling rate.

==Concept==
In the BCI2000 programming API, asynchronous information may be represented as ''Events''.

Here, an ''Event'' is an object that
*consists of two elements: a string descriptor and a time stamp, and
*is recorded in a data file together with brain signals.

==Implementation==
In the current version of BCI2000, events are mapped to [[BCI2000 Glossary#State|state variables]]. By comparing an event's time stamp to data acquisition time stamps, it is possible to associate events with single samples, and to map an event to a change in a state variable's value.

==Limitations==
*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.
*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.
*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. While the event API is available to all BCI2000 modules, it is advisable to use events in data acquisition modules only, thereby ensuring correct operation also in situations where processing modules are distributed across multiple machines in a network.
*The <tt>bcievent</tt> asynchronous stream interface should only be called between "StartRun" and "StopRun". Logging events with <tt>bcievent</tt> outside of a run could result in delayed state logging through the <tt>bcievent</tt> interface.

==Event API==
When including the <tt>src/shared/accessors/BCIEvent.h</tt> header file into a source code file, a symbol <tt>bcievent</tt> will be available.
The <tt>bcievent</tt> symbol behaves like a <tt>std::ostream</tt>; writing to that stream creates an event, fills it descriptor with whatever has been written into the stream, and stamps the event with the current time.
The <tt>bcievent</tt> symbol's <tt>ostream</tt> behavior makes it convenient to include numeric information into the event's string descriptor.
To allow for true asynchrony, BCI2000 events may be issued from any thread within a BCI2000 module, i.e. the <tt>bcievent</tt> interface is thread-safe.

==Descriptor Syntax==
An event descriptor consists of a name, a value, and optionally a duration, with data fields being separated with white space:
<name> <value> [<duration>]
Currently, events are mapped to state variables, so the following restrictions apply:
*The name field must match the name of a state variable, and that state variable must exist in the system before it appears in an event.
*The value field must specify an unsigned integer value that "fits into" the number of bits reserved for the corresponding state variable.
*Currently, the duration must either be omitted, or 0. When mapping the event to a state variable, a duration of 0 means that the state variable is set to the specified value for a single sample only, and to zero for subsequent samples. A non-specified duration means that the state variable is changed, and keeps its value for subsequent samples.

==Example==
In this example, an event "MyEvent" will be created, its value field set to <tt>currentValue</tt>, and its duration field empty.
Please note that the name is followed with a space character separating name and value.
The event will be time stamped either when the stream is flushed explicitly, as indicated for the "AnotherEvent" event, or when the <tt>bcievent</tt> object goes out of scope, as indicated for the "MyEvent" event. Unless there is time-consuming code between the <tt>bcievent</tt> statement, and the next closing brace, there is no need to explicitly flush the <tt>bcievent</tt> stream object.

#include "BCIEvent.h"
...
using namespace std;
...
{
int currentValue;
...
bcievent << "MyEvent " << currentValue;
bcievent << "AnotherEvent " << currentValue << flush; // AnotherEvent is time stamped here
...
} // MyEvent is time stamped here

==See also==
[[Programming Reference:Environment Class]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

Events are used to implement keyboard, mouse, and joystick logging: [[User Reference:Logging Input]]

[[Category:Development]] [[Category:Data Acquisition]] [[Category:Framework API]]

Programming Reference:Events

2011-07-13T16:55:30Z

Gmilsap: /* Limitations */

This page describes how to record asynchronous information ("events") along with brain signal data. This usage of the term "event" is unrelated to "events" as part of [[Programming Reference:Contents#Programming_Interface_Documentation|BCI2000 API class interfaces]].

As data are recorded by data acquisition hardware in chunks, BCI2000 processes them synchronously.
Still, recording information that is asynchronous to brain signal data acquisition may be of interest to an experimenter. Typically, mouse or keyboard input may be of interest to record in an experiment, and ideally should provide a temporal resolution that corresponds to the brain signal's sampling rate.

==Concept==
In the BCI2000 programming API, asynchronous information may be represented as ''Events''.

Here, an ''Event'' is an object that
*consists of two elements: a string descriptor and a time stamp, and
*is recorded in a data file together with brain signals.

==Implementation==
In the current version of BCI2000, events are mapped to [[BCI2000 Glossary#State|state variables]]. By comparing an event's time stamp to data acquisition time stamps, it is possible to associate events with single samples, and to map an event to a change in a state variable's value.

==Limitations==
*Time stamps have millisecond resolution. Up to sampling rates of 1kHz, this is not a practical restriction though.
*Association of event time stamps with sample positions cannot be more accurate than [[User Reference:Timing|time stamps assigned to data blocks]] by the data acquisition module. If data transmission latency between data acquisition hardware, and its associated jitter, are large compared to a single sample's duration, then event positions cannot be expected to be precise. Still, for data acquisition devices that are connected directly to the machine running the data acquisition module (i.e., not over a network connection), and for sampling rates below 1kHz, transmission latency and jitter may be expected to be below a sample's duration.
*Event time stamps must refer to the same physical time base that is used to stamp acquired data packets. This limits the use of events to BCI2000 modules that run on the same machine as the data acquisition module. While the event API is available to all BCI2000 modules, it is advisable to use events in data acquisition modules only, thereby ensuring correct operation also in situations where processing modules are distributed across multiple machines in a network.
*The <tt>bcievent</tt> asynchronous stream interface should only be called between "StartRun" and "StopRun". Logging events with bcievent outside of a run could result in delayed state logging through the bcievent interface.

==Event API==
When including the <tt>src/shared/accessors/BCIEvent.h</tt> header file into a source code file, a symbol <tt>bcievent</tt> will be available.
The <tt>bcievent</tt> symbol behaves like a <tt>std::ostream</tt>; writing to that stream creates an event, fills it descriptor with whatever has been written into the stream, and stamps the event with the current time.
The <tt>bcievent</tt> symbol's <tt>ostream</tt> behavior makes it convenient to include numeric information into the event's string descriptor.
To allow for true asynchrony, BCI2000 events may be issued from any thread within a BCI2000 module, i.e. the <tt>bcievent</tt> interface is thread-safe.

==Descriptor Syntax==
An event descriptor consists of a name, a value, and optionally a duration, with data fields being separated with white space:
<name> <value> [<duration>]
Currently, events are mapped to state variables, so the following restrictions apply:
*The name field must match the name of a state variable, and that state variable must exist in the system before it appears in an event.
*The value field must specify an unsigned integer value that "fits into" the number of bits reserved for the corresponding state variable.
*Currently, the duration must either be omitted, or 0. When mapping the event to a state variable, a duration of 0 means that the state variable is set to the specified value for a single sample only, and to zero for subsequent samples. A non-specified duration means that the state variable is changed, and keeps its value for subsequent samples.

==Example==
In this example, an event "MyEvent" will be created, its value field set to <tt>currentValue</tt>, and its duration field empty.
Please note that the name is followed with a space character separating name and value.
The event will be time stamped either when the stream is flushed explicitly, as indicated for the "AnotherEvent" event, or when the <tt>bcievent</tt> object goes out of scope, as indicated for the "MyEvent" event. Unless there is time-consuming code between the <tt>bcievent</tt> statement, and the next closing brace, there is no need to explicitly flush the <tt>bcievent</tt> stream object.

#include "BCIEvent.h"
...
using namespace std;
...
{
int currentValue;
...
bcievent << "MyEvent " << currentValue;
bcievent << "AnotherEvent " << currentValue << flush; // AnotherEvent is time stamped here
...
} // MyEvent is time stamped here

==See also==
[[Programming Reference:Environment Class]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

Events are used to implement keyboard, mouse, and joystick logging: [[User Reference:Logging Input]]

[[Category:Development]] [[Category:Data Acquisition]] [[Category:Framework API]]

Contributions:WebcamLogger

2011-07-13T16:48:48Z

Gmilsap: /* Version History */

==Synopsis==
A filter that records video recorded from a webcam to an avi file, and stores the frame number in a State variable.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/WebcamLogger

==Versioning==
===Authors===
Adam Wilson (adam.wilson@uc.edu)
===Version History===
07/06/11 - Full commit with support for MSVC and MinGW.

07/13/11 - Bugfixes

===Source Code Revisions===

===Todo===
* Add geometry decimation (e.g., save other than 320x240).

==Functional Description==
For many experiments, visual information about how a subject is behaving during an experiment is desired. This extension acquires video from most webcams, and writes to an AVI video file. It also records the current frame number as a state variable, so that the video can be synchronized with brain data with a resolution of the block size. Other options include the ability to overlay the date and time directly on the video (useful for long-term monitoring), and time decimation (i.e., save every Nth frame).

PROTIP: This module can also be used to perform screen capture with the proper virtual screencast webcam driver. Dubious website, but this product works well: http://www.pcwinsoft.com/screencamera/landing.asp

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_WEBCAMLOGGER'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--LogWebcam=1</code> command line argument.

==Usage==
The webcam should be installed and configured per the device instructions. The Webcam logger uses the OpenCV (version 2.2) library for display and saving; supported webcams can be found at: [http://opencv.willowgarage.com/wiki/Welcome/OS].

Camera options are found in the ''Source'' tab of the Configuration window.

==Parameters==
The Webcam logger is configured in the ''Source'' tab within the WebcamLogger section. The configurable parameters are:

*<code>LogWebcam</code> - Enables/Disables logging of Webcam states
*<code>CameraNumber</code> - the webcam number for systems with multiple cameras, 0 for the default camera
*<code>WebcamDecimation</code> - The decimation factor for saving and viewing video; the logger saves/displays every Nth frame.
*<code>WebcamDateTimeLocation</code> - The location of the date/time overlay in saved video (0: none, 1: UpperRight, 2: UpperLeft, 3: LowerRight, 4: LowerLeft).

The video is saved with a resolution of 320x240 pixels. A parameter that allows configuration of the geometry will be provided in a future version.

==State Variables==

===WebcamFrame===
The frame number of the video. This can be used to synchronize the video with the recorded neural data. It is a 24-bit value, allowing 16,777,216 frames before overflowing. If the webcam can capture at 30 frame/sec, and is decimated at a factor of 5 (i.e., 6 frames/sec), this allows more than a month of video before it will go back to frame 0. In other words, this should not be an issue for most users.

==See also==
[[User Reference:Logging Input]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]