How brainflow-dev/brainflow works
Project Type and Purpose
• BrainFlow is an open-source, multi-language SDK for biosensor data acquisition and processing.
• Core functionality (written in C/C++) provides board-agnostic data acquisition, signal processing, and ML inference; bindings expose this core to Python, Java, C#, MATLAB, R, Julia, Rust, Node.js and standalone C++ examples.
• An emulator simulates hardware for integration tests and CI pipelines.
High-Level Components
A. C++ Core Engine (src/)
• board_controller – hardware abstraction layer (drivers for dozens of boards)
• data_handler – low-level signal processing (filters, transforms)
• ml – machine learning modules (ONNX, dynamic libs)
• utils – common utilities, networking, logging, shared types
B. Language Bindings
• python_package/ – CPython wrapper via ctypes
• java_package/ – JNI wrapper, Maven packaging
• cpp_package/ – C++ examples, CMake-based installable library
• csharp_package/, matlab_package/, r_package/, julia_package/, nodejs_package/, rust_package/ – language-specific shims calling into the compiled core
C. Emulator (emulator/brainflow_emulator)
• Python modules that emulate board output over virtual serial, UDP, etc., used by CI/CD to test all drivers
D. Third-Party Libraries (third_party/)
• Eigen, DSPFilters, ONNX Runtime, spdlog, SimpleBLE, various board SDKs
E. Build & Packaging
• CMakeLists.txt, cmake/, conanfile.py, Docker/Dockerfile, tools/ – build definitions, packaging scripts, Docker images
F. CI/CD Infrastructure
• .github/workflows/ – GitHub Actions for formatting, static analysis, unit/integration tests across platforms, deploy to PyPI/NuGet/etc.
G. Documentation & Examples
• docs/ – Sphinx/ReadTheDocs documentation and Jupyter notebooks
• examples/ in each binding package demonstrating typical usage
Relationships and Interactions
• Language Bindings → call into the Core Engine (board_shim, data_filter, ml_model symbols) via foreign-function interfaces (FFI/JNI/ctypes).
• Core Engine → loads drivers in board_controller and ML modules (dynamic or ONNX library).
• Core Engine → uses third_party libraries to accelerate math and hardware interfaces.
• Emulator ↔ Core Engine: emulator publishes fake streams that core’s board_controller consumes, enabling deterministic tests.
• Build & Packaging → compiles Core Engine into shared/static libraries, packages language bindings, builds Docker images for CI.
• CI/CD → orchestrates builds across OS/architectures, runs emulator-backed integration tests, deploys artifacts.
Architectural Patterns & Principles
• Layered Architecture: hardware abstraction → data processing → ML → API layer
• Plugin/Driver Pattern: board_controller supports plugging in new board drivers via consistent interface
• FFI Wrappers: language-agnostic core with repeatable, identical APIs across languages
• Emulation for Testability: decoupling hardware from tests
• Modular Build: CMake + Conan for flexible dependency management, Docker for reproducible environments
• Clear, descriptive labels on every component
• Capturing all essential architectural elements without over-fragmentation