Programming Tutorial:Implementing a Source Module

From BCI2000 Wiki
Revision as of 16:09, 13 November 2020 by Mellinger (talk | contribs)
Jump to: navigation, search

Source modules (data acquisition modules) are factored into

  • code required for any hardware, and
  • code required to access a specific hardware.

You provide only specific code. This is in a function that waits for and reads A/D data (line 3 in the pseudo code shown at Technical Reference:Core Modules), together with some helper functions that perform initialization and cleanup tasks. Together these functions form a class derived from GenericADC. Depending on system load, it may be possible that the BCI2000 system cannot keep up with data acquisition for short periods of time. To handle such cases gracefully, it is useful to acquire data inside a separate thread, and to keep a buffer of multiple data blocks which is going to be filled when data cannot be processed in a timely manner. A framework for this kind of data acquisition is given by the BufferedADC class. In the following, we will consider a source module that is derived from the BufferedADC class.

Example Scenario

Your Tachyon Corporation A/D card comes with a C-style software interface declared in a header file "TachyonLib.h" that consists of three functions

int TachyonStart( int inSamplingRate, int inNumberOfChannels );
int TachyonStop( void );
int TachyonWaitForData( short** outBuffer, int inCount );

From the library help file, you learn that TachyonStart configures the card and starts acquisition to some internal buffer; that TachyonStop stops acquisition to the buffer, and that TachyonWaitForData will block execution until the specified amount of data has been acquired, and that it will return a pointer to a buffer containing the data in its first argument. Each of the functions will return zero if everything went well, otherwise some error value will be returned. Luckily, Tachyon Corporation gives you just what you need for a BCI2000 source module, so implementing the ADC class is quite straightforward.

Writing the ADC Header File

In your class' header file, "TachyonADC.h", you write


#include "GenericADC.h"

class TachyonADC : public GenericADC

   void Publish();
   void AutoConfig( const SignalProperties& );
   void Preflight( const SignalProperties&, SignalProperties& ) const;
   void Initialize( const SignalProperties&, const SignalProperties& );
   void Process( const GenericSignal&, GenericSignal& );
   void Halt();

   void* mHandle;
   int mSourceCh,
#endif // TACHYON_ADC_H

ADC Implementation

In the .cpp file, you will need some #includes, and a filter registration:

#include "TachyonADC.h"
#include "Tachyon/TachyonLib.h"
#include "BCIError.h"

using namespace std;

RegisterFilter( TachyonADC, 1 );

From the constructor, you request parameters and states that your ADC needs; from the destructor, you call Halt to make sure that your board stops acquiring data whenever your class instance gets destructed:

: mSourceCh( 0 ),
  mSampleBlockSize( 0 ),
  mSamplingRate( 0 )
    "Source int SourceCh=        64 64 1 128 "
        "// this is the number of digitized channels",
    "Source int SampleBlockSize= 16 5 1 128 "
        "// this is the number of samples transmitted at a time",
    "Source int SamplingRate=    128 128 1 4000 "
        "// this is the sample rate",


ADC Initialization

Your Preflight function will check whether the board works with the parameters requested, and communicate the dimensions of its output signal:

void TachyonADC::Preflight( const SignalProperties&,
                            SignalProperties& outputProperties ) const
  if( TACHYON_NO_ERROR != TachyonStart( Parameter( "SamplingRate" ), Parameter( "SourceCh" ) ) )
    bcierr << "SamplingRate and/or SourceCh parameters are not compatible"
           << " with the A/D card"
           << endl;
  outputProperties = SignalProperties( Parameter( "SourceCh" ),
                          Parameter( "SampleBlockSize" ),
                          SignalType::int16 );

Here, the last argument of the SignalProperties constructor determines not only the type of the signal propagated to the BCI2000 filters but also the format of the dat file written by the source module.

You might want to write SignalType::int32 or SignalType::float32 instead if your data acquisition hardware acquires data in one of those formats.

The actual Initialize function will only be called if Preflight did not report any errors. Thus, you may skip any further checks, and write

void TachyonADC::Initialize( const SignalProperties&, const SignalProperties& )
  mSourceCh = Parameter( "SourceCh" );
  mSampleBlockSize = Parameter( "SampleBlockSize" );
  mSamplingRate = Parameter( "SamplingRate" );
  TachyonStart( mSamplingRate, mSourceCh );

Balancing the TachyonStart call in the Initialize function, your Halt function should stop all asynchronous activity that your ADC code initiates:

void TachyonADC::Halt()

Data Acquisition

Note that the Process function may not return unless the output signal is filled with data, so it is crucial that TachyonWaitForData is a blocking function. (If your card does not provide such a function, and you need to poll for data, don't forget to call Sleep( 0 ) inside your polling loop to avoid tying up the CPU.)

void TachyonADC::Process( const GenericSignal&, GenericSignal& outputSignal )
  int valuesToRead = mSampleBlockSize * mSourceCh;
  short* buffer;
  if( TACHYON_NO_ERROR == TachyonWaitForData( &buffer, valuesToRead ) )
    int i = 0;
    for( int channel = 0; channel < mSourceCh; ++channel )
      for( int sample = 0; sample < mSampleBlockSize; ++sample )
        outputSignal( channel, sample ) = buffer[ i++ ];
    bcierr << "Error reading data" << endl;

Adding the SourceFilter

Most measurement equipment comes with hardware filters that allow you to filter out line noise. For equipment that does not offer such an option, consider adding the SourceFilter to your data acquisition module as described here.


You are done! Use your TachyonADC.cpp to replace the GenericADC descendant in an existing source module, add the TachyonADC.lib shipped with your card to the project, compile, and link.