Difference between revisions of "Contributions:ParallelPortFilter"

From BCI2000 Wiki
Jump to: navigation, search
 
Line 6: Line 6:
 
===Authors===
 
===Authors===
 
Kristopher Kaleb Goering (kaleb.goering@gmail.com)
 
Kristopher Kaleb Goering (kaleb.goering@gmail.com)
 +
 +
Alex Belsten (belsten@neurotechcenter.org)
  
 
===Version History===
 
===Version History===
 
* 2015/06/30: Initial public release
 
* 2015/06/30: Initial public release
 +
* 2019/08/09: Added OutputMode
  
 
===Source Code Revisions===
 
===Source Code Revisions===
 
*Initial development: 4881
 
*Initial development: 4881
*Tested under: 4936
+
*Tested under: 6003
*Known to compile under: 4936
+
*Known to compile under: 6003
 
*Broken since: --
 
*Broken since: --
  
 
==Functional Description==
 
==Functional Description==
This simple filter extension resides in the Application module and makes input and output with the parallel port easy. The inputs are stored as states ParallelPortInput1 - ParallelPortInput24 based off the number of ports connected. For more information, see [[:Contributions:ParallelPortFilter#States|States]].
+
This simple filter extension resides in the Application module and makes output with the parallel port easy.  
  
 
==Integration into 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_PARALLELPORTFILTER'''. Once the extension is built into the source module, it can be used.
+
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 opening <code>Configure.sh.cmd</code>. In the CMake GUI, enable '''EXTENSIONS_PARALLELPORTFILTER''' and then click generate. Then recompile BCI2000. The filter will be built into the application module and will be ready for use.
 +
 
 +
==Configuring ParallelPortFilter==
 +
The ParallelPortFilter  is configured by the OutputMode and ParallelPortOutput parameters. If there are zero rows in the ParallelPortOutput matrix then nothing will be outputted to the parallel ports available on the system. See the [https://en.wikipedia.org/wiki/Parallel_port#Pinouts Parallel Port Wiki] for information about the pins that are available for writing to by the ParallelPortFilter.
  
==Configuring ParallelPortFiler==
+
To find the hardware address for the parallel ports for your machine, press '''WIN''' + '''R''' and enter ''devmgmt.msc''. In Device Manager, expand the section labeled '''Ports (Com & LPT)'''. If this section does not exist, you probably do not have LPT ports or the driver is not installed properly. Find the one labeled with (LPT1) or whatever port you are looking for. The label (LPT1 in this example) is the device name and is how the parrallel port is addressed in the ParallelPortOutput matrix parameter.  
If using the filter, SourcePorts must have a number greater than 0. Then list the names for the ports separated by spaces in SourcePortsList. The list must be the same length as the value in SourcePorts. You can then set the LPTMapping with column one in using the names as in SourcePortsList and column 2 using the corresponding hardware address. This step is optional. If not configured, LPT1 maps to 0x378 and LPT2 maps to 0x278 which should work for most users. DigitalOutputEx is only necessary if user wants to write output through the parallel port.
 
  
If the default settings for LPTMapping did not produce results, the hardware address might be different for the user's computer. To find the hardware address for the parallel ports for your machine, press '''WIN''' + '''R''' and enter ''devmgmt.msc''. In Device Manager, expand the section labeled '''Ports (Com & LPT)'''. If this section does not exist, you probably do not have LPT ports or the driver is not installed properly. Find the one labeled with (LPT1) or whatever port you are looking for. Right click and select Properties. In the Resources tab, there is a field called I/O Range and take the first value of the range which is in hexadecimal. If multiple I/O Range, read the first one; if that does not work, try the other one. Take that value as the hardware address for Parameter LPTMapping. These instructions for finding the address has been tested on Windows XP, 7, and 8.
+
The hardware address can be found by right clicking the LPT port and selecting Properties. In the Resources tab, there is a field called I/O Range and take the first value of the range which is in hexadecimal. If multiple I/O Range, read the first one; if that does not work, try the other one. These instructions for finding the address has been tested on Windows XP, 7, 8 and 10.
  
 
[[File:ParallelPortAddress.JPG]]
 
[[File:ParallelPortAddress.JPG]]
 
For some examples on configurations, see [[:Contributions:ParallelPortFilter#Example Configurations|Example Configurations]].
 
 
For better explanation of the parameters, see [[:Contributions:ParallelPortFilter#Parameters|Parameters]].
 
  
 
==Parameters==
 
==Parameters==
 
The ParallelPortFilter is configured in the ParallelPort tab.  The configurable parameters are:
 
The ParallelPortFilter is configured in the ParallelPort tab.  The configurable parameters are:
  
===SourcePorts===
+
===OutputMode===
This parameter is used to initialize the filter and to keep track of the number of ports being used. This number should be the total number of parallel ports that should be used to communicate. It should be an integer value greater than 0 if being used else 0. Most computers do not have more than 3 parallel ports but some have 4. In good practice this value should not be greater than 3 unless you are sure you have that many ports.
+
This parameter effects the way that the ParallelPortOutput parameter is interpreted. There are two options for OutputMode, Word and Bit.
 
 
===SourcePortsList===
 
This parameter lists the ports to be used and the order to communicate through them. It should be a list of the port names LPT1 - LPT3. You can not use the same port twice in on list. This list must be the same length as the value in Parameter SourcePorts.
 
 
 
===LPTMapping===
 
This parameter is to manually enter the hardware address of the ports incase that the computer being used does not conform to general use hardware addresses. Column one should have the names of the ports such as LPT1 or LPT2, same as the values in Parameter SourcePortsList, and column two should have the hexadecimal value of the port such as 0x378. The number of rows in the matrix should be equal to the value in Parameter SourcePorts, while it must have two columns if being used, no more, no less.
 
 
 
===DigitalOutputEx===
 
This matrix of expressions that controls the outputs on the parallel ports.  Each port has 8 bits which correspond to 8 rows on the matrix. If the expression evaluates to True, the bit will be set to 1 else to 0. Boolean expression work quite well here. For more information on digital output and expressions usage for ParallelPortFilter see [[::Contributions:ParallelPortFilter#Digital Output|Digital Output]].
 
 
 
==Digital Output==
 
Each port has 8 bits that can be written to. These bits can be accessed through the Parameter DigitalOutputEx. The user must write expressions for each individual bit on each port. The row label corresponds to which bit it will be written to. If multiple ports are enabled, row 1 - 8 correspond to the bits 1 - 8 on the first port and row 9 - 16 correspond to the bits 1 - 8 on the second port and so on. Expressions that evaluate to True set the corresponding bit to 1 and those that evaluate to False set the corresponding bit to 0.
 
 
 
In the case that the user wishes to send an signal or a value through the port, the user must convert the number into binary and write the corresponding zeroes and ones to the respective bits. To do that, the formula:
 
 
 
<code>mod((floor(x / 2 ^(bitnumber - 1))), 2)</code>
 
 
 
The x is the signal the user wishes to send through the port. For example if the State MousePosX was to be sent through the port, the Parameter DigitalOutputEx would be:
 
 
 
[[File:ParallelPortFilterDigitalOutExBinary.jpg]]
 
 
 
<code>State("MousePosX") / State("MousePosX") * 255</code> normalizes the coordinates to fit into eight bits which is all parallel ports can handle.
 
 
 
Not all rows have to be created. Any row not named just writes the bit as 0. The rows also can be written in whatever order if you just change the row label in the parameter. The example below just sets bit 1 and 5 to 1. All other rows are zeroes.
 
  
[[File:ParallelPortFilterRowLabelChange.jpg]]
+
====Bit====
 +
Bit mode is useful when the pins on the parallel port correspond to expressions that return Boolean values. The order in which the pins are written to for a LPT port corresponds to the order in which they appear in the ParallelPortOutput matrix. See the following image for an example:
  
For more on expressions, see [[:User Reference:Expression Syntax|Expressions]].
+
[[File:BitMode_matrix.png]]
  
==States==
+
In this example there are two parallel ports available on the system, LPT1 and LPT2. StimulusCode, Running and Recording are states that are set by the Application module (specifically the Stimulus Presentation module) and Source module. See [[User Reference:States]] for information on states. Data0 of LPT1 will be set high when the StimulusCode is equal to zero, data1 of LPT1 will always be low and data3 of LPT1 will be be high when StimulusCode is greater than 5. For LPT2, data0 will be set high when Running is equal to one and data1 will be high when Recording is equal to one.  
For each port there is 8 input bits which correspond to 8 ParallelPortInput states. Each state is either a 0 or a 1. If multiple ports are enabled, ParallelPortInput1 - ParallelPortInput8 correspond to the bits 1 - 8 on the first port and ParallelPortInput9 - ParallelPortInput16 correspond to the bits 1 - 8 on the second port and so on. Currently only 3 ports may be enabled, which should be more than enough for most computers do not have more than port LPT1 - LPT3.
 
  
==Example Configurations==
+
====Word====
This example enables port LPT1 with a new hardware address.
+
Word mode allows the user to write words (8 bit values) to a parallel port. See the following image for an example:
  
[[File:ParallelPortFilterNewAddress.jpg|1000px]]
+
[[File:WordMode_matrix.png]]
  
This example enables ports with names MRIScanner and StimulusDevice with hardware addresses. Note that the address for the ports are the same as the default values for LPT1 and LPT2. This shows that LPT names can be renamed in the Parameter Configuration to make it easier to read. This does not change the names of the addresses given by the computer itself.
+
In this example, there are two parallel ports available on the system. KeyDown and KeyUp are outputted on the LPT1 and LPT2, respectively. KeyDown and KeyUp are both 8 bit values the correspond to input from a keyboard. See [[User Reference:Logging Input]] for more information. The least significant bit of KeyDown is outputted to data0 and most significant bit is outputted to data7.
  
[[File:ParallelPortFilterNewNames.jpg|1000px]]
+
===ParallelPortOutput===
 +
This matrix of expressions that controls the outputs on the parallel ports. There should always be two columns, Device Name and Expression. Device Name should be the LPT device you want to connect to and the output for the device is what the Expression evaluates to. For more on expressions, see [[:User Reference:Expression Syntax|Expressions]].
  
 
==See also==
 
==See also==

Latest revision as of 16:28, 9 August 2019

Location

http://www.bci2000.org/svn/trunk/src/contrib/Extensions/ParallelPortFilter

Versioning

Authors

Kristopher Kaleb Goering (kaleb.goering@gmail.com)

Alex Belsten (belsten@neurotechcenter.org)

Version History

  • 2015/06/30: Initial public release
  • 2019/08/09: Added OutputMode

Source Code Revisions

  • Initial development: 4881
  • Tested under: 6003
  • Known to compile under: 6003
  • Broken since: --

Functional Description

This simple filter extension resides in the Application module and makes output with the parallel port 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 opening Configure.sh.cmd. In the CMake GUI, enable EXTENSIONS_PARALLELPORTFILTER and then click generate. Then recompile BCI2000. The filter will be built into the application module and will be ready for use.

Configuring ParallelPortFilter

The ParallelPortFilter is configured by the OutputMode and ParallelPortOutput parameters. If there are zero rows in the ParallelPortOutput matrix then nothing will be outputted to the parallel ports available on the system. See the Parallel Port Wiki for information about the pins that are available for writing to by the ParallelPortFilter.

To find the hardware address for the parallel ports for your machine, press WIN + R and enter devmgmt.msc. In Device Manager, expand the section labeled Ports (Com & LPT). If this section does not exist, you probably do not have LPT ports or the driver is not installed properly. Find the one labeled with (LPT1) or whatever port you are looking for. The label (LPT1 in this example) is the device name and is how the parrallel port is addressed in the ParallelPortOutput matrix parameter.

The hardware address can be found by right clicking the LPT port and selecting Properties. In the Resources tab, there is a field called I/O Range and take the first value of the range which is in hexadecimal. If multiple I/O Range, read the first one; if that does not work, try the other one. These instructions for finding the address has been tested on Windows XP, 7, 8 and 10.

ParallelPortAddress.JPG

Parameters

The ParallelPortFilter is configured in the ParallelPort tab. The configurable parameters are:

OutputMode

This parameter effects the way that the ParallelPortOutput parameter is interpreted. There are two options for OutputMode, Word and Bit.

Bit

Bit mode is useful when the pins on the parallel port correspond to expressions that return Boolean values. The order in which the pins are written to for a LPT port corresponds to the order in which they appear in the ParallelPortOutput matrix. See the following image for an example:

BitMode matrix.png

In this example there are two parallel ports available on the system, LPT1 and LPT2. StimulusCode, Running and Recording are states that are set by the Application module (specifically the Stimulus Presentation module) and Source module. See User Reference:States for information on states. Data0 of LPT1 will be set high when the StimulusCode is equal to zero, data1 of LPT1 will always be low and data3 of LPT1 will be be high when StimulusCode is greater than 5. For LPT2, data0 will be set high when Running is equal to one and data1 will be high when Recording is equal to one.

Word

Word mode allows the user to write words (8 bit values) to a parallel port. See the following image for an example:

WordMode matrix.png

In this example, there are two parallel ports available on the system. KeyDown and KeyUp are outputted on the LPT1 and LPT2, respectively. KeyDown and KeyUp are both 8 bit values the correspond to input from a keyboard. See User Reference:Logging Input for more information. The least significant bit of KeyDown is outputted to data0 and most significant bit is outputted to data7.

ParallelPortOutput

This matrix of expressions that controls the outputs on the parallel ports. There should always be two columns, Device Name and Expression. Device Name should be the LPT device you want to connect to and the output for the device is what the Expression evaluates to. For more on expressions, see Expressions.

See also

User Reference:Logging Input, Contributions:Extensions