Jump to content

Programming Howto:Quickstart Guide

From BCI2000 Wiki
Revision as of 23:14, 22 April 2011 by Jhill (talk | contribs)

Prerequisites

  1. If you do not already have a bci2000.org username, get one here. Your password will be mailed to you.
  2. To download the BCI2000 source-code, you will need an SVN client. If you do not have one, for Windows we recommend TortoiseSVN, which can be downloaded here. The BCI2000 wiki contains more documentation about how to set up and use SVN.
  3. Use SVN, with your username and password, to check out the latest BCI2000 source-code-included distribution, the location of which is http://www.bci2000.org/svn/trunk . We will assume that you checked out the trunk to a location C:\BCI2000\3.x on your hard-drive. Wherever you see this path below, adjust it so that it reflects the location you actually used. More information about the layout of the resulting distribution can be found here.
  4. Next you will need to download and install CMake if you do not already have it (at least version 2.8.3 is recommended). CMake can be downloaded here. Make sure you select the option add to path for all users when installing.
  5. Finally will need a C++ compiler. We will proceed on the assumption that you are on 32-bit Windows and using the free Visual C++ 2010 Express environment which can be downloaded here. Consult the documentation for the BCI2000 build system for information on other supported compilers, and more about CMake.

You should now have everything you need in order to build and customize BCI2000.

Setup

  1. Use CMake to build a project file. This is done by going to C:\BCI2000\3.x\build (which is the main workbench from which all build operations occur) and launching one of the "Make ... .bat" batch-files. If you are using Visual C++ 2010 Express, the appropriate batch file is Make VS10 Project Files.bat . It will ask you several questions: feel free to answer "y" to all of them except the last one about MFC (since MFC is not part of the free Visual C++ Express release). If successful, you should see a long list of sub-projects being created, and after several seconds of this, "Configuring done."
  2. Open the resulting solution file, ALL_BUILD.vcproj , in Visual C++ Express. The file should be located in C:\BCI2000\3.x\build .
  3. You probably do not need to build all of BCI2000 at once. To use BCI2000, the minimum you will need consists of the Operator, plus at least one SignalSource module, at least one SignalProcessing module, and at least one Application module. To build a single module in Visual C++ Express, right-click on the module's name in the list on the left, and select "Build". Building will typically take a few minutes per module. If you do not intend to modify a given module, you can always skip building it by copying the corresponding ready-built binary (for example, Operator.exe) from the prog subdirectory of a BCI2000 v.2 or v.3 binary distribution, and paste it into the corresponding directory of the distribution in which you are working, i.e. C:\BCI2000\3.x\prog . (To download the latest binary distribution, you will need to supply the same username and password that you used for SVN download.) Let's assume you have built, or copied, the following modules: Operator, SignalGenerator, ARSignalProcessing and CursorTask.
  4. Build the NewBCI2000Module and NewBCI2000Filter targets for use in the next step. The result will be two new executables, NewBCI2000Module.exe and NewBCI2000Filter.exe, in the C:\BCI2000\3.x\build directory.

Creating a project for a new BCI2000 module, from a template

  1. Navigate to C:\BCI2000\3.x\build
  2. Find NewBCI2000Module.exe there, assuming you have already built it (see "Setup", above).
  3. Launch it and answer the three questions it asks:
    1. What type of module are you creating? Enter "1" for a SignalSource module, "2" for a SignalProcessing module, or "3" for an Application module.
    2. What should be the name of the new module? This should be single word, without spaces or punctuation (For example: VeryNiceSignalProcessing. Or, at your option, something even more informative.) This name will be used as the name of a new directory that will contain the project source information, as well as for the resulting binary (.exe file).
    3. Where (i.e. inside what parent directory) should the new project directory be created? You can express this as a relative path, in which case it is interpreted relative to C:\BCI2000\3.x\build. To accept the default answer, which is ..\src\custom, just press return. This location (or some subdirectory of it) is a good choice: it maps to C:\BCI2000\3.x\src\custom which is an area reserved for your own projects.
  4. Now re-run CMake (see step 1 of "Setup", above). You should see your new project being added at the end of the long list of projects. Re-open the project file (step 2 of "Setup") and you should see it listed in the alphabetical list of projects.
  5. If you have just created a new SignalSource project, a specialized source-acquisition filter (called an Analogue-to-Digital Converter or ADC) will already have been added to the project. If your project was called Foo or FooSource this will be instantiated in files called FooADC.cpp and FooADC.h. You can find this by expanding the tree (click on the plus sign) next to your project name in Visual C++. Find the files under "Source" (or "Headers") and then "Project". Double-click them to edit. You should already be able to compile the module: try it.
  6. If you have created a SignalProcessing or Application project, you will be able to compile it, but it will not do anything until you add at least one filter to it (see next section).

Adding a new filter to a BCI2000 module, from a template

  1. Navigate to C:\BCI2000\3.x\build
  2. Find NewBCI2000Filter.exe there, assuming you have already built it (see "Setup", above).
  3. Launch it and answer the three questions it asks:
    1. What type of filter are you creating? Enter "1" for a subclass of GenericADC (although if you created a SignalSource project with the NewBCI2000Module tool, an ADC will already have been created for you), enter "2" for a subclass of GenericFilter, or "3" for a subclass of ApplicationBase.
    2. What should be the name of the filter class? This should be a legal name for a new C++ class (no spaces or punctuation). If you enter, for example, "FooFilter", then a class of this name will be implemented in two new files, FooFilter.cpp and FooFilter.h .
    3. To which project (i.e. in which project directory, relatively to build) should the filter be added? For example: ..\src\custom\VeryNiceSignalProcessing (as in all of the BCI2000 framework, directory slashes are allowed to go this / way or that \ way regardless of whether you are on Windows or not)
  4. Again, re-run CMake and re-open the master project file.
  5. Find your new files under the Source/Project and Headers/Project trees by clicking on the + sign next to the project name. Double-click them to edit.
  6. Try building the project (right-click on the project and select "build"). SignalSource and Application projects may already build successfully. SignalProcessing projects, or any project to which you have added a new GenericFilter subclass, will have at least one deliberate #error in the code. When the build attempt finishes, double-click on the error message to go to the offending line. You will see that the error is there to force you to think about the ordering of the filters in your module. Once you have resolved this issue, simply remove the #error line and select build again (the process will be quicker this time: only previously unbuilt files or newly modified files will be compiled).


Under construction

Retrieved from "http://www.bci2000.org/mediawiki/index.php?title=Programming_Howto:Quickstart_Guide&oldid=6001"