Difference: DocsSectionsInstallationGuide (1 vs. 2)

Revision 211 Nov 2014 - Main.PhilipVanDenBroek

Line: 1 to 1
 
META TOPICPARENT name="WebHome"
Deleted:
<
<

9. INSTALLATION GUIDE

9.1. Start-up checklist

  • Ensure availability of a Matlab licence (requires version 2008a or higher)
  • Ensure access to BrainStream? code and required toolboxes (BrainStream? standard includes the fieldtrip toolbox)
  • Add the BrainStream? core folder to the Matlab path
  • Check if your hardware is supported (see Environments)
  • Define your BrainStream? project
  • Compose experiment definition tables
  • Compose user defined functions

9.1.1. Ensure availability of a MatLab licence

This availability depends on your institution's licensing agreements with MathWorks. BrainStream also requires a license for, and availability of Matlab Signal Processing Toolbox.

9.1.2. Ensure access to BrainStream code and required toolboxes

Assure availability of the BrainStream code, either through a local copy of a repository or through a connected server. It can be downloaded from: http://code.google.com/p/brainstream/downloads/list
BrainStream requires the following toolbox (standard included with the distribution of BrainStream):
* Fieldtrip toolbox: http://fieldtrip.fcdonders.nl/download

Other software used by BrainStream (all available after BrainStream download):
* Java library for reading/writing Excel, jxl.jar GNU Library or Lesser General Public License (LGPL) http://www.andykhan.com/jexcelapi/
* MSocket: Copyright (c)* 2006 MIT Lincoln Laboratory, Steven Michael (smichael@ll.mit.edu), http://www.mathworks.com/matlabcentral/fileexchange/11130
* fparser.m: Copyright (c)* 2009, urs (us) schwarz, us@neurol.unizh.ch, http://www.mathworks.com/matlabcentral/fileexchange/3915
* uipickfiles.m: Copyright (c)* 2007, Douglas M. Schwarz, http://www.mathworks.com/matlabcentral/fileexchange/10867
* inifile.m: Copyright (c)* 2003-2005 Primoz Cermelj, Slovenia (primoz.cermelj@email.si), http://www.mathworks.com/matlabcentral/fileexchange/2976

(c)* All rights reserved, BSD license (see Matlab for explanation or read BSD.txt file in third_parties subfolder in BrainStream's core folder)

9.1.3. Check if your hardware is supported

These settings concern the hardware environment you are working in. This is only required if your hardware is not yet supported by BrainStream? (see GettingStarted).

9.2. Setup accessing the hardware

Any hardware device supported by the fieldtrip toolbox (http://fieldtrip.fcdonders.nl/development/realtime), can be used as a data source within BrainStream. As soon as the corresponding xxx2ft software is started, BrainStream? will be able to access its data. Read the instructions on how to use the interfacing software for the specific hardware in use. Here, we will show how this works for the BioSemi? amplifier (see for fieldtrip instructions: http://fieldtrip.fcdonders.nl/development/realtime/biosemi).
The biosemi2ft interfacing software can be found in the fieldtrip folder: fieldtrip/realtime/acquisition/biosemi (to find the location of the fieldtrip folder distributed with BrainStream, execute fieldtrip_folder in BrainStreams? core folder). Copy this folder to a location where you want to execute biosemi2ft. Start the terminal (Mac) or command prompt (PC) and make sure to be in the folder where you copied biosemi2ft, then execute:

biosemi2ft <config_file> <gdf-file> <hostname> <port>

To tell BrainStream? it should connect to this buffer, define a key for the DataSources topic in the blocksettings. You can choose your own reference name for the datasource, which will become the key name in the blocksettings.
<data source reference> = 'buffer://<hostname>:<port>:<device>
This is necessary in order to distinct possible multiple connected datasources. An example would take the form:

[DataSources]
eeg = 'buffer://localhost:1972:biosemi_active2'

The biosemi2ft software supports fieldtrips Online Data Manager, which allows for a remotely configuration of streamed/saved channels and filter settings. BrainStream? supports this feature and in order to use it, define the configureFile key for corresponding hardware devices topic in the blocksettings. Also enable this feature by setting the OnlineDataManager key to 1, and make sure the remotePort key is set to the same port value specified at startup of biosemi2ft. BrainStream? will then send these configuration settings to the interface software along with a name for the gdf-file saving the raw data. Note that this name doesn't include path information and therefore data is stored in the folder where biosemi2ft resides.

[biosemi_active2] 
configureFile = 'biosemi_active2_cap64.cfg'
!OnlineDataManager = 1 
remotePort = 8000 
startFunction = 'cleanup'
stopFunction = 'copy_rawdata'

If the interfacing software xxx2ft does not support the Online Data Manager, make sure to set the OnlineDataManager key to 0 (default).

BrainStreams? offers the option to specify functions that execute either before starting or after stopping streaming data from the hardware device. Use the startFunction and stopFunction key for corresponding hardware devices topic. This is for example useful to have those functions start the interfacing software automatically or take care of copying the acquired gdf-file to some dedicated location. Those functions should take the form:

function my_custom_startFunction(datasource,device) 
% datasource: your reference name of the data source (in the example above: eeg)
% device: name referring to the hardware device (in the example above: biosemi_active2) 
% add code to handle specific tasks, required in your lab before connecting to the fieldtrip buffer

function my_custom_stopFunction(datasource,device) 
% datasource: your reference name of the data source (in the example above: eeg)
% device: name referring to the hardware device (in the example above: biosemi_active2) 
% add code to handle specific tasks, required in your lab after completing a block  

9.3. Add the BrainStream? core folder to the Matlab path

Matlab path must include BrainStream s core folder, any further required BrainStream? folders will be added by BrainStream.

Either save BrainStreams? core folder to Matlabs path permanently by choosing Set Path in the file menu, or make sure your working directory is at the BrainStream? core folder.

During runtime, any other folders that need to be added to the Matlab path can be handled by block file settings for the Experiment topic. The keys MatlabPathAdd and MatlabPathFnc take care of this. Specify a string cell array with folders to add (they always add recursively), or specify a function that adds folders to the Matlab path. When specific plugins require access to Java classes from within BrainStream, this function should then also add these to the Matlab's JavaClassPath.

9.4. Hardware markers

Click here to read how BrainStream? processes incoming markers.
Click here to read what options users have to insert markers. (to do: write it)

A major reason to use hardware instead of software markers is the fact that a better synchronization between presented stimuli and data can be achieved. Not all devices support solutions to insert markers by hardware, in that case you should send markers to the fieldtrip buffer directly. It depends on the specific implementaton of the xxx2ft interface software how accurate the synchronization with data will be. More specific, it depends on the size of the chunks of data constantly being updated to the buffer. For example, biosemi2ft standardly updates the buffer with chunks of data sized approximately 15 samples. In that case, a marker directly sent to the buffer would synchronize data with approximately 7.3 ms accuracy (sample rate 2048 Hz), instead of 0.5 ms when sent to the hardware (1 sample). For online experiments that in general use much lower sample rates, the difference between the two reduces considerably. These differences are especially relevant to experiment designs susceptible to accurate timing.
Users should always use BrainStreams? sndMarker function to send hardware markers, it will read from the blocksettings which function to use for the hardware device the marker should be sent to.

A custom sndMyMarker function responsible for actually sending markers to some specific hardware should obey following format:

function [event, ret] = sndMyMarker(event,m)
% m.name     = name of marker
% m.type     = type marker
% m.value = marker value (type char!)
% ret > 0 if marker was sent successfully
try
    % check m.type and m.value
    % ...
    % use type and value to sent marker out to the hardware    
    % send_my_marker(m);
    ret = 1;
catch err
    ret = 0;
end
An example using a PC's COMM port looks like this:
function [event, ret] = sndCOMMarker(event,m)
mlock
persistent serobjw
if isempty(serobjw)
   serobjw = serial('COM1');              % Creating serial port object
   serobjw.Baudrate = 115200;             % Set the baud rate at the specific value
   set(serobjw, 'Parity', 'none');        % Set parity as none
   set(serobjw, 'Databits', 8);           % set the number of data bits
   set(serobjw, 'StopBits', 1);           % set number of stop bits as 1
   set(serobjw, 'Terminator', '');        % set the terminator value to newline
   set(serobjw, 'OutputBufferSize', 512); % Buffer for write
end
try
   fopen(serobjw);
   fwrite(serobjw,str2double(m.value)); % write to serial port
   fclose(serobjw); % close it
   ret = 1;
catch err 
   event = bs_warn(event,err.message);
   disp(err.message);
   ret = 0;
end


 

9.5. Firewall settings

BrainStream? uses ports 5001 and 5002 to connect to possible Matlab clients. Furthermore, BrainStream? uses ports 1972 and further (dependent of the number of required file proxies) to connect to buffers that stream acquired data, simulated data or from file replayed data, or to install buffers related to BrainStreams? pre-processing option. Make sure these ports are not blocked by your firewall.

9.6. Test BrainStream?

 \ No newline at end of file
Added:
>
>
web page moved here

Revision 109 Nov 2009 - Main.MarianneSeverens

Line: 1 to 1
Added:
>
>
META TOPICPARENT name="WebHome"

9. INSTALLATION GUIDE

9.1. Start-up checklist

  • Ensure availability of a Matlab licence (requires version 2008a or higher)
  • Ensure access to BrainStream? code and required toolboxes (BrainStream? standard includes the fieldtrip toolbox)
  • Add the BrainStream? core folder to the Matlab path
  • Check if your hardware is supported (see Environments)
  • Define your BrainStream? project
  • Compose experiment definition tables
  • Compose user defined functions

9.1.1. Ensure availability of a MatLab licence

This availability depends on your institution's licensing agreements with MathWorks. BrainStream also requires a license for, and availability of Matlab Signal Processing Toolbox.

9.1.2. Ensure access to BrainStream code and required toolboxes

Assure availability of the BrainStream code, either through a local copy of a repository or through a connected server. It can be downloaded from: http://code.google.com/p/brainstream/downloads/list
BrainStream requires the following toolbox (standard included with the distribution of BrainStream):
* Fieldtrip toolbox: http://fieldtrip.fcdonders.nl/download

Other software used by BrainStream (all available after BrainStream download):
* Java library for reading/writing Excel, jxl.jar GNU Library or Lesser General Public License (LGPL) http://www.andykhan.com/jexcelapi/
* MSocket: Copyright (c)* 2006 MIT Lincoln Laboratory, Steven Michael (smichael@ll.mit.edu), http://www.mathworks.com/matlabcentral/fileexchange/11130
* fparser.m: Copyright (c)* 2009, urs (us) schwarz, us@neurol.unizh.ch, http://www.mathworks.com/matlabcentral/fileexchange/3915
* uipickfiles.m: Copyright (c)* 2007, Douglas M. Schwarz, http://www.mathworks.com/matlabcentral/fileexchange/10867
* inifile.m: Copyright (c)* 2003-2005 Primoz Cermelj, Slovenia (primoz.cermelj@email.si), http://www.mathworks.com/matlabcentral/fileexchange/2976

(c)* All rights reserved, BSD license (see Matlab for explanation or read BSD.txt file in third_parties subfolder in BrainStream's core folder)

9.1.3. Check if your hardware is supported

These settings concern the hardware environment you are working in. This is only required if your hardware is not yet supported by BrainStream? (see GettingStarted).

9.2. Setup accessing the hardware

Any hardware device supported by the fieldtrip toolbox (http://fieldtrip.fcdonders.nl/development/realtime), can be used as a data source within BrainStream. As soon as the corresponding xxx2ft software is started, BrainStream? will be able to access its data. Read the instructions on how to use the interfacing software for the specific hardware in use. Here, we will show how this works for the BioSemi? amplifier (see for fieldtrip instructions: http://fieldtrip.fcdonders.nl/development/realtime/biosemi).
The biosemi2ft interfacing software can be found in the fieldtrip folder: fieldtrip/realtime/acquisition/biosemi (to find the location of the fieldtrip folder distributed with BrainStream, execute fieldtrip_folder in BrainStreams? core folder). Copy this folder to a location where you want to execute biosemi2ft. Start the terminal (Mac) or command prompt (PC) and make sure to be in the folder where you copied biosemi2ft, then execute:

biosemi2ft <config_file> <gdf-file> <hostname> <port>

To tell BrainStream? it should connect to this buffer, define a key for the DataSources topic in the blocksettings. You can choose your own reference name for the datasource, which will become the key name in the blocksettings.
<data source reference> = 'buffer://<hostname>:<port>:<device>
This is necessary in order to distinct possible multiple connected datasources. An example would take the form:

[DataSources]
eeg = 'buffer://localhost:1972:biosemi_active2'

The biosemi2ft software supports fieldtrips Online Data Manager, which allows for a remotely configuration of streamed/saved channels and filter settings. BrainStream? supports this feature and in order to use it, define the configureFile key for corresponding hardware devices topic in the blocksettings. Also enable this feature by setting the OnlineDataManager key to 1, and make sure the remotePort key is set to the same port value specified at startup of biosemi2ft. BrainStream? will then send these configuration settings to the interface software along with a name for the gdf-file saving the raw data. Note that this name doesn't include path information and therefore data is stored in the folder where biosemi2ft resides.

[biosemi_active2] 
configureFile = 'biosemi_active2_cap64.cfg'
!OnlineDataManager = 1 
remotePort = 8000 
startFunction = 'cleanup'
stopFunction = 'copy_rawdata'

If the interfacing software xxx2ft does not support the Online Data Manager, make sure to set the OnlineDataManager key to 0 (default).

BrainStreams? offers the option to specify functions that execute either before starting or after stopping streaming data from the hardware device. Use the startFunction and stopFunction key for corresponding hardware devices topic. This is for example useful to have those functions start the interfacing software automatically or take care of copying the acquired gdf-file to some dedicated location. Those functions should take the form:

function my_custom_startFunction(datasource,device) 
% datasource: your reference name of the data source (in the example above: eeg)
% device: name referring to the hardware device (in the example above: biosemi_active2) 
% add code to handle specific tasks, required in your lab before connecting to the fieldtrip buffer

function my_custom_stopFunction(datasource,device) 
% datasource: your reference name of the data source (in the example above: eeg)
% device: name referring to the hardware device (in the example above: biosemi_active2) 
% add code to handle specific tasks, required in your lab after completing a block  

9.3. Add the BrainStream? core folder to the Matlab path

Matlab path must include BrainStream s core folder, any further required BrainStream? folders will be added by BrainStream.

Either save BrainStreams? core folder to Matlabs path permanently by choosing Set Path in the file menu, or make sure your working directory is at the BrainStream? core folder.

During runtime, any other folders that need to be added to the Matlab path can be handled by block file settings for the Experiment topic. The keys MatlabPathAdd and MatlabPathFnc take care of this. Specify a string cell array with folders to add (they always add recursively), or specify a function that adds folders to the Matlab path. When specific plugins require access to Java classes from within BrainStream, this function should then also add these to the Matlab's JavaClassPath.

9.4. Hardware markers

Click here to read how BrainStream? processes incoming markers.
Click here to read what options users have to insert markers. (to do: write it)

A major reason to use hardware instead of software markers is the fact that a better synchronization between presented stimuli and data can be achieved. Not all devices support solutions to insert markers by hardware, in that case you should send markers to the fieldtrip buffer directly. It depends on the specific implementaton of the xxx2ft interface software how accurate the synchronization with data will be. More specific, it depends on the size of the chunks of data constantly being updated to the buffer. For example, biosemi2ft standardly updates the buffer with chunks of data sized approximately 15 samples. In that case, a marker directly sent to the buffer would synchronize data with approximately 7.3 ms accuracy (sample rate 2048 Hz), instead of 0.5 ms when sent to the hardware (1 sample). For online experiments that in general use much lower sample rates, the difference between the two reduces considerably. These differences are especially relevant to experiment designs susceptible to accurate timing.
Users should always use BrainStreams? sndMarker function to send hardware markers, it will read from the blocksettings which function to use for the hardware device the marker should be sent to.

A custom sndMyMarker function responsible for actually sending markers to some specific hardware should obey following format:

function [event, ret] = sndMyMarker(event,m)
% m.name     = name of marker
% m.type     = type marker
% m.value = marker value (type char!)
% ret > 0 if marker was sent successfully
try
    % check m.type and m.value
    % ...
    % use type and value to sent marker out to the hardware    
    % send_my_marker(m);
    ret = 1;
catch err
    ret = 0;
end
An example using a PC's COMM port looks like this:
function [event, ret] = sndCOMMarker(event,m)
mlock
persistent serobjw
if isempty(serobjw)
   serobjw = serial('COM1');              % Creating serial port object
   serobjw.Baudrate = 115200;             % Set the baud rate at the specific value
   set(serobjw, 'Parity', 'none');        % Set parity as none
   set(serobjw, 'Databits', 8);           % set the number of data bits
   set(serobjw, 'StopBits', 1);           % set number of stop bits as 1
   set(serobjw, 'Terminator', '');        % set the terminator value to newline
   set(serobjw, 'OutputBufferSize', 512); % Buffer for write
end
try
   fopen(serobjw);
   fwrite(serobjw,str2double(m.value)); % write to serial port
   fclose(serobjw); % close it
   ret = 1;
catch err 
   event = bs_warn(event,err.message);
   disp(err.message);
   ret = 0;
end


 

9.5. Firewall settings

BrainStream? uses ports 5001 and 5002 to connect to possible Matlab clients. Furthermore, BrainStream? uses ports 1972 and further (dependent of the number of required file proxies) to connect to buffers that stream acquired data, simulated data or from file replayed data, or to install buffers related to BrainStreams? pre-processing option. Make sure these ports are not blocked by your firewall.

9.6. Test BrainStream?

 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback