BrainFlow Dev

Code style

We use clang-format tool to keep the same code style for all cpp files. You can download clang-format binary from LLVM Download Page We recommend installing a plugin for your text editor or IDE which will apply clang-format tool during saving. You will need to set code style option to “FILE”

Plugins for text editors and IDEs:

Unfortunately clang-format cannot handle naming, so some additional rules are:

  • methods and variables should be in lower case with underscore

  • class names should be in camel case

  • use brackets even for single line if and for statements

For C# we use the same code style as for C++, for java there is a formatter file to take care of code style.

CI and tests

If you want to commit to the core module of BrainFlow project please check that all tests are passed, you should check CI status in your PR and fix all errors if any. Also, you are able to run failed tests locally using BrainFlow emulator.

In CI warnings as errors option is enabled for C++ code and you need to fix all of them. Also, we have CppCheck static analysis tool. If you see that such check failed you need to download artifact from CppCheck Github Acttion, open generated html report and fix errors.

Pull Requests

Just try to briefly explain a goal of this PR.

Instructions to add new boards to BrainFlow

You’ve just written Python, Java, C#, R, C++ … SDKs for your board! Also, now you can use your new board with applications and frameworks built on top of BrainFlow API.

Optional: We use CI to run tests automatically, to add your board to CI pipelines you can develop a simple emulator for your device. Use emulators for existing boards as a reference and add tests for your device to Github Acttions workflows.

Instructions to build docs locally

Don’t push changes to Docs without local verification.

  • install pandoc

  • optional: install Doxygen, skip it if you dont understand what it is or don’t need to publish your local build

Install requirements:

cd docs
python -m pip install -r requirements.txt

Build docs:

make html

Debug BrainFlow’s errors

Since bindings just call methods from dynamic libraries, more likely errors occur in C++ code, it means that you need to use C++ debuger like gdb. If there is an error in binding, it should be simple to figure out and resolve the issue using language specific tools.

Steps to get more information about errors in C++ code:

  • build BrainFlow’s core module and C++ binding in debug mode

  • reproduce your issue using C++ binding

  • run it with debuger and memory checker

Example for Linux, for other OSes it’s similar:

# Change build type to Debug
python3 tools/build.py --debug --clear-build-dir --num-jobs 8
# Create a test to reproduce your issue in C++, here we will use get_data_demo
cd tests/cpp/get_data_demo
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=TYPE_FULL_PATH_TO_BRAINFLOW_INSTALLED_FOLDER -DCMAKE_BUILD_TYPE=Debug ..
# e.g. cmake -DCMAKE_PREFIX_PATH=/home/andrey/brainflow/installed -DCMAKE_BUILD_TYPE=Debug ..
make
# Run Valgrind to check memory errors
# Here we use command line for Ganglion
sudo valgrind --error-exitcode=1 --leak-check=full ./brainflow_get_data --board-id 1 --serial-port /dev/ttyACM0 --mac-address e6:73:73:18:09:b1
# Valgrind will print Error Summary and exact line numbers
# Run gdb and get backtrace
sudo gdb --args ./brainflow_get_data --board-id 1 --serial-port /dev/ttyACM0 --mac-address e6:73:73:18:09:b1
# In gdb terminal type 'r' to run the program and as soon as error occurs, type 'bt' to see backtrace with exact lines of code and call stack

BrainFlow Emulator

BrainFlow Emulator allows you to run all integration tests for all supported boards without real hardware. Our CI uses it for test automation. Also, you can run it on your own PC!

Emulators listed here intended for CI and run process to test automatically. It’s great for automation but not easy to use if you need to test it in GUI. So, for some devices there are manual emulators as well. Such emulators don’t run process to test for you. Manual emulators make it easier to run tests in GUI based applications.

Streaming Board

Streaming Board emulator works using Python binding for BrainFlow, so you need to install Python binding first.

Install emulator package:

cd emulator
python -m pip install -U .

Run tests

python emulator\brainflow_emulator\streaming_board_emulator.py python tests\python\brainflow_get_data.py --log --board-id -2 --ip-address 225.1.1.1 --ip-port 6677 --other-info -1

This emulator uses synthetic board as a master board and, IP address and port are hardcoded.

OpenBCI Cyton

Cyton emulator simulate COM port using:

  • com0com for Windows

  • pty for Linux and MacOS

You should pass test command line directly to cyton_linux.py or to cyton_windows.py. The script will add the port automatically to provided command line and will start an application.

Install emulator package:

cd emulator
python -m pip install -U .

Run tests for LinuxMacOS and Windows (port argument will be added by Emulator!)

python brainflow_emulator/cyton_linux.py python ../tests/python/brainflow_get_data.py --log --board-id 0 --serial-port
python brainflow_emulator\cyton_windows.py python ..\tests\python\brainflow_get_data.py --log --board-id 0 --serial-port

Galea

Galea emulator creates socket server and streams data to BrainFlow like it’s a real board.

Install emulator package:

cd emulator
python -m pip install -U .

Run tests:

python brainflow_emulator/galea_udp.py python ../tests/python/brainflow_get_data.py --log --ip-address 127.0.0.1 --board-id 3

OpenBCI Wifi Shield based boards

Wifi shield emulator starts http server to read commands and creates client socket to stream data.

Install emulator package:

cd emulator
python -m pip install -U .

Run tests for Ganglion, Cyton and Daisy with Wifi Shield:

python brainflow_emulator/wifi_shield_emulator.py python ../tests/python/brainflow_get_data.py --log --ip-address 127.0.0.1 --board-id 4 --ip-protocol 2 --ip-port 17982
python brainflow_emulator/wifi_shield_emulator.py python ../tests/python/brainflow_get_data.py --log --ip-address 127.0.0.1 --board-id 5 --ip-protocol 2 --ip-port 17982
python brainflow_emulator/wifi_shield_emulator.py python ../tests/python/brainflow_get_data.py --log --ip-address 127.0.0.1 --board-id 6 --ip-protocol 2 --ip-port 17982

FreeEEG32

FreeEEG32 emulator simulate COM port using:

  • com0com for Windows

  • pty for Linux and MacOS

You should pass test command line directly to freeeeg32_linux.py or to freeeeg32_windows.py. The script will add the port automatically to provided command line and will start an application.

Install emulator package:

cd emulator
python -m pip install -U .

Run tests for LinuxMacOS and Windows (port argument will be added by Emulator!)

python brainflow_emulator/freeeeg32_linux.py python ../tests/python/brainflow_get_data.py --log --board-id 17 --serial-port
python brainflow_emulator\freeeeg32_windows.py python ..\tests\python\brainflow_get_data.py --log --board-id 17 --serial-port