Difference between revisions of "Contributions:NIDAQFilter"

From BCI2000 Wiki
Jump to: navigation, search
(Initializing the NIDAQFilter)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Synopsis=
+
==Synopsis==
A filter that outputs different statesr from BCI2000 to outputs connected to a National Instruments Board running DAQmx 8.5 or higher.
+
A filter that outputs different states from BCI2000 to outputs connected to a National Instruments Board running DAQmx 8.5 or higher.
=Location=
+
 
Not yet in the repository.
+
==Location==
=Versioning=
+
The file(s) should be in the following directory:
==Author==
+
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/NIDAQ-MX/NIDAQ-Logging/
Justin Renga (justin.renga@gmail.com)
+
 
==Version History==
+
==Versioning==
1.0
+
===Author===
==Source Code Revision==
+
* Justin Renga <justin.renga@gmail.com>
=Functional Description=
+
* Jeremy Hill <jezhill@gmail.com>
 +
===Version History===
 +
* 1.0
 +
* 2.0 - November 2013 - numerous fixes. From outside, the only change is that the <code>--LogNIDAQout=1</code> is now optional and independent of the other flags (i.e. you do not have to log the outgoing information to state variables if you do not want to).
 +
===Source Code Revision===
 +
Version 2.0 available from r4648, tested up to r4720
 +
 
 +
==Functional Description==
 
The NIDAQFilter uses any DAQmx 8.5 or higher compliant board and allows the user to pipe state data from BCI2000 through the board. All necesary components must be connected to the BCI computer before initiating a module using the filter.
 
The NIDAQFilter uses any DAQmx 8.5 or higher compliant board and allows the user to pipe state data from BCI2000 through the board. All necesary components must be connected to the BCI computer before initiating a module using the filter.
=Parameters=
+
==Adding and Compiling==
 +
To add and compile the NIDAQFilter module, make sure the latest NIDAQ MX drivers are installed on your computer. When that is done, go into the C:\Program Files\National Instruments\NI-DAQ\DAQmx ANSI C Dev\ folder. Inside are two folders: lib and include. The lib folder will contain the NIDAQmx.lib file (inside of the folder msvc). Copy that into the project's library folder. Inside of the include folder is the NIDAQmx.h file, which contains the function prototypes needed to use the NIDAQLogger module. Move this file into the project's include folder. Make sure the project links the new .lib file, and that the NIDAQFilter.h and NIDAQFilter.cpp files include the NIDAQmx.h file correctly. The NIDAQFilter should now be able to compile normally.
 +
 
 +
==Parameters==
 
The NIDAQFilter uses command line parameters to initialize the device(s) and set up the active ports. It then uses BCI2000 parameters for finer controls over the device, such as changing the sampling rate of the device.
 
The NIDAQFilter uses command line parameters to initialize the device(s) and set up the active ports. It then uses BCI2000 parameters for finer controls over the device, such as changing the sampling rate of the device.
==Command Line Parameters==
+
===Command Line Parameters===
===Initializing the NIDAQFilter===
+
====Initializing the NIDAQFilter====
To begin using the NIDAQFilter, use the <code>--LogNIDAQout</code> flag and set it equal to <b>1</b>. To activate device(s) for specific functions, use the following flags:
+
To activate device(s) for specific functions, use the following flags:
 
*<code>--LogDigiOut</code> --> Enable the device to use digital output characteristics
 
*<code>--LogDigiOut</code> --> Enable the device to use digital output characteristics
 
*<code>--LogAnaOut</code> --> Enable the device to use analog output characteristics
 
*<code>--LogAnaOut</code> --> Enable the device to use analog output characteristics
 
The format for the outputs for above flags is as follows:
 
The format for the outputs for above flags is as follows:
 
<center><code>[flag]="[device specification]-[port specifications]"</code></center>
 
<center><code>[flag]="[device specification]-[port specifications]"</code></center>
Please note that if <code>--LogNIDAQout</code> is enabled, then at least one of the above flags <b>MUST</b> be used.
+
To log the outgoing information to appropriately-named states variables, use the additional flag <code>--LogNIDAQout=1</code>.
===Device Specification===
+
Note that if <code>--LogNIDAQout=1</code> is used, then at least one of the above flags <b>MUST</b> also be used.
 +
 
 +
====Device Specification====
 
The device name is to be written as "Dev1" or "Dev2" (without the quotes) in the first part of the parameter value. After the device name is specified, use a hyphen (-) to indicate the device name is finished. For example, the first part of the parameter value would look like this: <code> "Dev1-</code>.
 
The device name is to be written as "Dev1" or "Dev2" (without the quotes) in the first part of the parameter value. After the device name is specified, use a hyphen (-) to indicate the device name is finished. For example, the first part of the parameter value would look like this: <code> "Dev1-</code>.
  
 
<i>If the device numbers are unclear, run the filter with just the <code>--LogNIDAQout</code> flag specified. The device names (along with their familiar names) will appear in the operator log.</i>
 
<i>If the device numbers are unclear, run the filter with just the <code>--LogNIDAQout</code> flag specified. The device names (along with their familiar names) will appear in the operator log.</i>
===Port Specifications===
+
====Port Specifications====
 
There are two acceptable states that the user can specify for each port that they are going to use:
 
There are two acceptable states that the user can specify for each port that they are going to use:
 +
 
*<b>0</b> --> the associated port WILL NOT be used
 
*<b>0</b> --> the associated port WILL NOT be used
 
*<b>1</b> --> the associated port WILL be used
 
*<b>1</b> --> the associated port WILL be used
  
 
The values will be used for every single port that the user wants to use. For example, if the user wants to use ports 3 and 5 on a device with 10 ports, then the port specification for that device will be the following:
 
The values will be used for every single port that the user wants to use. For example, if the user wants to use ports 3 and 5 on a device with 10 ports, then the port specification for that device will be the following:
 +
 
<center><code>0010100000</code></center>
 
<center><code>0010100000</code></center>
  
Line 36: Line 50:
  
 
<i>Important: If both the NIDAQLogger([[Contributions:NIDAQLogger]]) and the NIDAQFilter are being used, and both are using the digital lines on the same device, make sure that any port that is being referenced in a parameter is referenced only once. One port cannot use both digital input and digital output functionality, and will cause BCI2000 to throw an error, saying that the line is RESERVED.</i>
 
<i>Important: If both the NIDAQLogger([[Contributions:NIDAQLogger]]) and the NIDAQFilter are being used, and both are using the digital lines on the same device, make sure that any port that is being referenced in a parameter is referenced only once. One port cannot use both digital input and digital output functionality, and will cause BCI2000 to throw an error, saying that the line is RESERVED.</i>
===A Completed Flag===
+
====A Completed Flag====
 
The following is the completed flag, whose parts were described above:
 
The following is the completed flag, whose parts were described above:
 +
 
<center><code>--LogAnaOut="Dev1-0010100000"</code></center>
 
<center><code>--LogAnaOut="Dev1-0010100000"</code></center>
  
 
The above flag tells the filter that the user wants to use the analog output ports on Device 1, which has 10 ports on it. The user wants to use the 3rd and 5th ports on the device, but leave everything else unused.
 
The above flag tells the filter that the user wants to use the analog output ports on Device 1, which has 10 ports on it. The user wants to use the 3rd and 5th ports on the device, but leave everything else unused.
==BCI2000 Parameters==
+
===BCI2000 Parameters===
 
After the commandline parameters have been set, more parameters may be configured in the Configuration dialog box in BCI2000. Under the header <i>NIDAQFilter</i>, the following parameters MAY appear, as some of them are dependant on flags being used:
 
After the commandline parameters have been set, more parameters may be configured in the Configuration dialog box in BCI2000. Under the header <i>NIDAQFilter</i>, the following parameters MAY appear, as some of them are dependant on flags being used:
*<b>#OVRanges</b> --> This parameter tells the user if there are multiple output voltage ranges that are acceptable for use. If not, then the parameter will NOT show up. The parameter is an enumeration, and is activated by the <code>--LogAnaOut</code> flag.
+
*<b>#OVRanges</b> [ENUMERATION] --> This parameter tells the user if there are multiple output voltage ranges that are acceptable for use. If not, then the parameter will NOT show up. The parameter is activated by the <code>--LogAnaOut</code> flag.
*<b>#OutSamplingRate</b>
+
*<b>FilterExpressions</b> [MATRIX] --> This parameter allows the user to associate different states to individual output lines on the board. By clicking on the Edit Matrix button, the user will see a list of the lines that are active on the board, and a space to put an expression. This parameter will always show up, regardless of the flags being used.
*<b>FilterExpressions</b>
+
==States==
=States=
+
===Template===
==Template==
 
 
The states are constructed in a contextual manner, that is to say, they are created based on the channels that the user decides to use. The template of the state names is shown below:
 
The states are constructed in a contextual manner, that is to say, they are created based on the channels that the user decides to use. The template of the state names is shown below:
 
<center><code><b>NI[device name][A:D]OUTPUT[port number-1]</b></code></center>
 
<center><code><b>NI[device name][A:D]OUTPUT[port number-1]</b></code></center>
Line 54: Line 68:
 
*[A:D] -> analog or digital state (an analog state has a bit width of 16, while a digital state has a bit width of 1). This is dependant on the way the device is being used, and is not settable by the user.
 
*[A:D] -> analog or digital state (an analog state has a bit width of 16, while a digital state has a bit width of 1). This is dependant on the way the device is being used, and is not settable by the user.
 
*[port number - 1] -> the number of the port being used (the states begin at port 0, so when port 4 is being used, the number in the state will be 3)
 
*[port number - 1] -> the number of the port being used (the states begin at port 0, so when port 4 is being used, the number in the state will be 3)
==Example==
+
===Example===
 
If the following parameter list were used as a user's command line parameter:
 
If the following parameter list were used as a user's command line parameter:
 
<center><code>--LogNIDAQout=1 --LogAnaOut="Dev1-00100010100" --LogDigiOut="Dev2-00100001010"</code></center>
 
<center><code>--LogNIDAQout=1 --LogAnaOut="Dev1-00100010100" --LogDigiOut="Dev2-00100001010"</code></center>

Latest revision as of 20:19, 30 April 2014

Synopsis

A filter that outputs different states from BCI2000 to outputs connected to a National Instruments Board running DAQmx 8.5 or higher.

Location

The file(s) should be in the following directory: http://www.bci2000.org/svn/trunk/src/contrib/SignalSource/NIDAQ-MX/NIDAQ-Logging/

Versioning

Author

  • Justin Renga <justin.renga@gmail.com>
  • Jeremy Hill <jezhill@gmail.com>

Version History

  • 1.0
  • 2.0 - November 2013 - numerous fixes. From outside, the only change is that the --LogNIDAQout=1 is now optional and independent of the other flags (i.e. you do not have to log the outgoing information to state variables if you do not want to).

Source Code Revision

Version 2.0 available from r4648, tested up to r4720

Functional Description

The NIDAQFilter uses any DAQmx 8.5 or higher compliant board and allows the user to pipe state data from BCI2000 through the board. All necesary components must be connected to the BCI computer before initiating a module using the filter.

Adding and Compiling

To add and compile the NIDAQFilter module, make sure the latest NIDAQ MX drivers are installed on your computer. When that is done, go into the C:\Program Files\National Instruments\NI-DAQ\DAQmx ANSI C Dev\ folder. Inside are two folders: lib and include. The lib folder will contain the NIDAQmx.lib file (inside of the folder msvc). Copy that into the project's library folder. Inside of the include folder is the NIDAQmx.h file, which contains the function prototypes needed to use the NIDAQLogger module. Move this file into the project's include folder. Make sure the project links the new .lib file, and that the NIDAQFilter.h and NIDAQFilter.cpp files include the NIDAQmx.h file correctly. The NIDAQFilter should now be able to compile normally.

Parameters

The NIDAQFilter uses command line parameters to initialize the device(s) and set up the active ports. It then uses BCI2000 parameters for finer controls over the device, such as changing the sampling rate of the device.

Command Line Parameters

Initializing the NIDAQFilter

To activate device(s) for specific functions, use the following flags:

  • --LogDigiOut --> Enable the device to use digital output characteristics
  • --LogAnaOut --> Enable the device to use analog output characteristics

The format for the outputs for above flags is as follows:

[flag]="[device specification]-[port specifications]"

To log the outgoing information to appropriately-named states variables, use the additional flag --LogNIDAQout=1. Note that if --LogNIDAQout=1 is used, then at least one of the above flags MUST also be used.

Device Specification

The device name is to be written as "Dev1" or "Dev2" (without the quotes) in the first part of the parameter value. After the device name is specified, use a hyphen (-) to indicate the device name is finished. For example, the first part of the parameter value would look like this: "Dev1-.

If the device numbers are unclear, run the filter with just the --LogNIDAQout flag specified. The device names (along with their familiar names) will appear in the operator log.

Port Specifications

There are two acceptable states that the user can specify for each port that they are going to use:

  • 0 --> the associated port WILL NOT be used
  • 1 --> the associated port WILL be used

The values will be used for every single port that the user wants to use. For example, if the user wants to use ports 3 and 5 on a device with 10 ports, then the port specification for that device will be the following:

0010100000

Notice how even though the user wants to use only 2 ports, all 10 ports have been indicated. This is required. Any port that is not needed should be marked with a 0. If the number of ports specified in the parameter file does not match the number of ports found on the device, an error will be thrown, showing the number of ports were specified and how many ports there are for that device function.

Important: If both the NIDAQLogger(Contributions:NIDAQLogger) and the NIDAQFilter are being used, and both are using the digital lines on the same device, make sure that any port that is being referenced in a parameter is referenced only once. One port cannot use both digital input and digital output functionality, and will cause BCI2000 to throw an error, saying that the line is RESERVED.

A Completed Flag

The following is the completed flag, whose parts were described above:

--LogAnaOut="Dev1-0010100000"

The above flag tells the filter that the user wants to use the analog output ports on Device 1, which has 10 ports on it. The user wants to use the 3rd and 5th ports on the device, but leave everything else unused.

BCI2000 Parameters

After the commandline parameters have been set, more parameters may be configured in the Configuration dialog box in BCI2000. Under the header NIDAQFilter, the following parameters MAY appear, as some of them are dependant on flags being used:

  • #OVRanges [ENUMERATION] --> This parameter tells the user if there are multiple output voltage ranges that are acceptable for use. If not, then the parameter will NOT show up. The parameter is activated by the --LogAnaOut flag.
  • FilterExpressions [MATRIX] --> This parameter allows the user to associate different states to individual output lines on the board. By clicking on the Edit Matrix button, the user will see a list of the lines that are active on the board, and a space to put an expression. This parameter will always show up, regardless of the flags being used.

States

Template

The states are constructed in a contextual manner, that is to say, they are created based on the channels that the user decides to use. The template of the state names is shown below:

NI[device name][A:D]OUTPUT[port number-1]

Some key things about the template:

  • [device name] -> the name of the device to which the port is associated to (for example, if Device 4 is being used, then there will be a state that begins with NIDev4 will exist)
  • [A:D] -> analog or digital state (an analog state has a bit width of 16, while a digital state has a bit width of 1). This is dependant on the way the device is being used, and is not settable by the user.
  • [port number - 1] -> the number of the port being used (the states begin at port 0, so when port 4 is being used, the number in the state will be 3)

Example

If the following parameter list were used as a user's command line parameter:

--LogNIDAQout=1 --LogAnaOut="Dev1-00100010100" --LogDigiOut="Dev2-00100001010"

Then the following states would be produced:

     NIDev1AOUTPUT2     NIDev1AOUTPUT6     NIDev1AOUTPUT8
     NIDev2DOUTPUT2     NIDev2DOUTPUT7     NIDev2DOUTPUT9