BCI++
HARDWARE INTERFACE
MODULE OVERVIEW
USER INTERFACE
The main panel is represented in the following figure and is divided into several parts each one
related to a specific aspect.
Files tab
Using the yellow button it is possible to select the base file name for the current session. Every time
an acquisition is started a new file is created on the basis of the base filename followed by the
incremental value of the current acquisition. If no base name is activated, an incremental filename is
generated and the file is saved in the default directory c:\HIMSaves. During the acquisition the HIM
saves an intermediate binary file, the acquisition is stopped the file is converted to an ascii file
directly loadable by Matlab.
Data are stored column wise and each row represents a sample:
Name
Signal AEnima Manual HW
Algorithm
Algorithm AUX Communication
triggers triggers triggers Classification feedback
Stats
Width 1… n 1
1
1
1
0..m
1
1
A log file with auxiliary information is also saved.
Device selection tab
Using the Device control, you can select which is the instrument you are going to connect to. The
“Com Port” selection box makes sense only for devices which are connected to the HIM using a
Serial port or an SPP compatible Bluetooth port.
The following devices are currently supported:
Simulator: this is a virtual device which simulate synthesized signals at a sample frequency of
256Hz;
Play file: this is a virtual instrument which reproduces a signal stored in a selectable file at 256Hz.
Using the provided Matlab routine (CreateBinFromMatrix.m) it is possible to save a compatible file
starting from a Matrix with a signal. The maximum number of supported channels is 256. When the
end of the stream is reached the file is automatically rolled up.
Bluesilk and KimeraII: are two devices developed by the Sensibilab based on Bluetooth® SPP;
Interactive file player: is another virtual instrument similar to the Play file. This instrument loads
the signal from 5 files contained in the HIM/Data folder and called respectively LEFT.bin,
RIGHT.bin, CENTER.bin, UP.bin, DOWN.bin. When started, a little user interface is displayed and
can be used to online switch between different file in order to simulate the behaviour of the user.
The signal can be changed by overwriting the sample signal in the /Data folder: the only limitation
is that every file must have the same number of elements.
Phedra and WDAM: are multi signal Bluetooth® wearable devices distributed by SXT s.r.l.
Sistemi per Telemedicina (www.sxt-telemed.it)
PLE: is an 8 channels 16bit resolution at Hz Bluetooth acquisition board distributed by SXT s.r.l.
Sistemi per Telemedicina (www.sxt-telemed.it)
g.Mobilab: is an 8 channel Bluetooth® EEG acquisition distributed by G.Tech (www.gtec.au ). In
order to use this device the file gMOBIlabplus.dll must be located in the HIM directory (we can’t
distribute that file since it is protected by copyright).
Neuroscan: is a diffused clinical EEG device with a lot of configurable features by Compumedics
(www.neuroscan.com ). The connection with the device is achieved using a client TCP/IP
connection with the Scan 4.3 software. In order to configure the connections you can manually edit
the file Neuroscan.txt in the HIM folder.
Main control tab
This tab allow to manually manage the acquisition when the AEnima module is not in use. Three
buttons are used to establish a connection with the device, to start the acquisition and to stop it.
Algorithms tab
This tab allows the selection of an algorithm and the initialization of the corresponding plug-in.
Each plug in is composed of a DLL, in order to register a new plug-in you can manually edit the
text file “HIM\AlgoSettings.txt” by adding a line with the name of the DLL and a second line with
the friendly name to display in the control.
While all the functions are handled by the main module, the algorithm must be specified by your
plug-in. The processing is handled by a class called Algorithm from which you can inherit the
common interface with the HIM and many other useful functions. The processing can be done both
by C functions and by Matlab using the already included automation APIs. In order to make the use
of pre-existing algorithms easier both calls based on moving windows or based on a sample by
sample approach are supported. In order to support the set-up of new plug-in a specific wizard for
VisualC++ can be installed. The wizard will guide you in the creation of a new DLL containing
your Matlab or C based algorithms.
Manual triggers, display and terminal tabs
Using the buttons in this tab you will have the possibility to add manual triggers to your acquisition.
When one of the button is pressed, the corresponding value is appended in the Manual Triggers
channels.
The two buttons of the display section allow to toggle the visualization of the signal plot and of the
algorithms output plot. The Terminal tab is used to display messages to the operator
The plot
This window gives a real-time visualization of the plot of the signal. Stating from the top left corner
you can:
 Select a spatial filter for visualization. Data are not affected by this filter;
 Select a time domain filter for visualization. Some sample filter for signals at 256Hz are
included, you can customize this menu by creating new MA or IIR filters in Matlab and
saving the resulting weight using the “SaveFilter.m” Matlab routine and by registering them
editing the file HIM/Filters/Settings.txt;
 Pause and restart the visualization of the plot (This commands don’t affect the acquisition);
 Modify the layout of the page
Left clicking on a signal label you will able to access to the advanced visualization settings shown
in the following picture.
OVERVIEW OF THE SOURCE CODE
The scope of this document is to give a general overview of the source code of the HIM module.
Since the HIM accomplishes several independent function and since the understanding of the entire
source code of HIM is not necessary to develop plug-in and to interface new instruments this
document was structured as a FAQ.
This document is intended for developers with a deep knowledge of C++ and wxWidgets library.
Proceed at your own risk!!!
WHICH IS THE MAIN MODULE?
HOW DOES THE MULTIPLE INSTRUMENTATION INTERFACE WORK?
WHERE IS THE MAIN LOOP? HOW IS THE SIGNAL ACQUISITION AND PROCESSING
CHAIN STRUCTURED?
HOW DOES THE MULTIPLE INSTRUMENTATION INTERFACE WORK?
WHAT DO YOU MEAN BY VISUALIZATION FILTERS? HOW DO THEY WORK?
HOW DOES THE PROCESSING WORKS?
HOW DOES THE ALGORITHM COMMUNICATES WITH AENIMA?
HOW IS THE TCP/IP SERVER IMPLEMENTED?
WHICH LIBRARIES AND WICH IDE DO YOU USE?
The application was created using the wxWidgets ver 2.8.7 library and Visual Studio 2005, all the
other libraries will be automatically installed by BCI++ installer. The UI was designed using
wxFormBuilder v3.0. The structure reflects the typical of those application created using
wxWidgets wizard for Visual Studio and wxFormBuilder: a file (Gangia_GUI.cpp) with the
definition off all the basic graphical entities is generated by the form builder, while the application
behaviour is defined by the inherited classes.
WHICH IS THE MAIN MODULE?
The original name of HIM was Gangia, thus a lot of the class names are based on this word. The
main application is defined in ‘GangiaFrame’ class: this class manages the main form and is the
parent of all the classes which are created at runtime. GangiaFrame, when created, start a TCP/IP
server on the port 3001 (constant WX_THE_PORT). Socket and server events are received by this
object and routed to the other objects when necessary.
HOW DOES THE MULTIPLE INSTRUMENTATION INTERFACE WORK?
The multiple instrumentation interface is implemented by inheriting the base class ‘Instrument’. It is
possible to add a new instrument by deriving a specific class from the basic Instrument class and
implementing the virtual methods which related do the communication with the hardware.
Depending on the instrument the signal can be acquired from different communication streams
(serial ports, Bluetooth ports, files, TCP/IP sockets) there aren’t limitations about the kind of
hardware interface. The number of acquired channel is limited to 256 channels, the sample rate
depends on the hardware.
Please refer to HOW TO ADD A NEW INSTRUMENT for more details.
WHERE IS THE MAIN LOOP? HOW IS THE SIGNAL ACQUISITION AND PROCESSING
CHAIN STRUCTURED?
When the acquisition is started a new thread is created, all the signal related routines will be
executed by this thread. At each sample time a SampleStruct structure containing the n signal
channels and the HW trigger is generated.
typedef struct SampleStruct
{
DataStruct
Data;
AlgoStruct
Algo;
EventStruct
Events;
}SampleStruct;//TOTALE 1092 bytes
Where
/*! /struct DataStruct
This struct is used to store information about events
*/
typedef struct DataStruct
{
//! This vector contain one sample for each signal
float Signal[MAX_CHANNELS];
//! Numeber of valid elements in Signal
int
DataLen;
//! AUXiliary channel
float AUX;
//! For future use: will contain artifact identification markers
int
Artifacts;
}DataStruct;//1026
typedef struct EventStruct
{
//! Graphical triggers sent by AEnima usig the TCP/IP connection
int
AEnimaTrigg;
//! Manual triggers set using the buttons in the main panel
int
HIMTrigg;
//! Hardware triggers coming from the data acquisition device (if supported)
int
HWTrigger;
//! Communication statistics, for future use: will contain information about
communication errors
int
CommunicationStats;
}EventStruct;
/*! /struct AlgoStruct
This struct is used to store information about the online sesult of the
algorithms
*/
typedef struct AlgoStruct
{
//! Vector containing the feedback output
float Feedback[MAX_FEEDS];
//! Number of valid values int
int
FeedLen;
float Classification;
}AlgoStruct;//40 bytes
The SampleStruct is fed into the Instrument::PutSample function which will perform the following
operations:
1. HIM Trigger and AEnima Trigger acquisition;
2. Send a copy the signal into the plot window (PlotFrameHandler Class);
3. Send the structure to the active algorithm (if any), do the processing (if necessary) and
retrieves processing results (if any);
4. Calls the data saver module;
5. Check if the algorithm have generated a BCIMessage and sends it to the AEnima client (if
any is connected)
WHAT DO YOU MEAN BY VISUALIZATION FILTERS? HOW DO THEY WORK?
HOW DOES THE PROCESSING WORKS?
The HIM also provides a basic ‘Algorithm’ class which handles all the operation related to data
buffer management, the performance monitoring. When the communication with Matlab® is
needed a dedicated ‘MatAlgorithm’ class can be used: hybrid algorithms can also be implemented.
Both classes implement an algorithm model which have one of the following characteristics:
1.
2.
3.
4.
5.
Have an initialization phase;
Requires sample by sample operations (eg. Spatial and time domain filtering);
Requires windowed processing (windows can overlap over time);
Feature extraction and classification can be not simultaneous.
The result can be in the form of an analogue value (feedback) or in the form of discrete
values (classification)
The model is quite general thus the most of the algorithm are compatible. The class provides a
native support to both c4m library.
The initialization phase is carried out in the constructor of the derived class: usually a file is
accessed or a dialog is displayed. Is some settings must be sent to the AEnima model before
acquisition start the SendConfiguration function can be properly specified.
The data-entry point for the Algorithm class is the function ‘ PutSample’. In the standard definition
PutSample stores the incoming data into two different buffers whose lengths are specified in the
‘Open’ function: MainWindow and SecWindow. When one of the two windows is full, the virtual
function ‘RunMainWin’ or the ‘RunSecWin’ are called. The inherited class must implement the
necessary methods. The overlap for each window can be controlled by the ShiftMainWin and
ShiftSecondaryWin functions.
HOW IS THE TCP/IP SERVER IMPLEMENTED?
HOW DOES THE ALGORITHM COMMUNICATES WITH AENIMA?
The algorithm class have fixed length fifo memory buffer ‘SocketBuffer’ which can be accessed
using the WriteOut function. When the PutSample is executed it returns the number of valid bytes
in SocketBuffer and the messages are written into the TCP/IP socket.