MINDGAN — EMOTIV BCI SUITE

An end-to-end Brain-Computer Interface application for motor imagery research, training, and real-time control

Fudan University · College of Biomedical Engineering

---

Overview

MINDGAN is a complete Brain-Computer Interface (BCI) desktop application that turns an Emotiv EPOC X EEG headset into a real-time motor imagery (MI) research platform. It covers the full pipeline — from data acquisition and signal-quality analysis, through deep-learning model training with conditional Deep Convolutional Generative Adversarial Network (cDCGAN) data augmentation, to real-time cursor and drone control.

The suite is built around a single modular Python package and runs as a native Tkinter GUI. Training and validation work without any headset — just load previously recorded EDF/CSV files.

Screenshot:

---

Key Features

Module	What it does
Record	Run MI paradigms with the Emotiv EPOC X, inject LSL markers, export EDF/CSV
EEG Quality	Assess contact impedance, signal quality, and power spectral density
Train	Train a cDCGAN-augmented CNN classifier with three-phase curriculum
Control	Real-time BCI cursor control using a trained model
Drone	Control a DJI Tello drone via motor imagery
Validate	Cross-session validation with publication-quality confusion matrices

---

Architecture

MINDGAN/
├── main.py                 # Entry point — launches the App
├── app.py                  # Main window (tk.Tk) — tabs, header, footer
├── config.py               # Shared config: theme, LSL streams, dep flags, .env loading
├── settings.py             # AppSettings — JSON-persisted user preferences
├── settings_dialog.py      # Settings dialog (Ctrl+,)
├── eeg_io.py               # EEG data loading (EDF/CSV → MNE Raw)
├── augmentation.py         # S&R augmentation + MARKER constants
├── model_loader.py         # Dynamic import of MINDGAN_runner.py (cv2 mock)
├── ui_widgets.py           # Reusable Tkinter widgets (card, btn, logbox, etc.)
├── recorder.py             # Recorder class — LSL streaming + Emotiv Cortex API
├── stimulus.py             # Stimulus class — MI paradigm visual cues
├── figures.py              # Publication-quality figure generation
├── record_tab.py           # Tab: Record MI sessions
├── train_tab.py            # Tab: Train hybrid DL classifier
├── control_tab.py          # Tab: Real-time BCI control simulation
├── drone_tab.py            # Tab: Tello drone control
├── validate_tab.py         # Tab: Cross-session validation
├── quality_tab.py          # Tab: EEG quality analysis
├── MINDGAN_runner.py       # cDCGAN model + classifier (dependency)
├── cortex.py               # Emotiv Cortex API websocket wrapper (dependency)
├── utils.py                # ML utility imports (dependency)
├── .env.example            # Template for Emotiv API credentials
├── .gitignore
├── requirements.txt
└── README.md

Module dependency graph:

main.py
  └── app.py (App class)
       ├── config.py (shared globals: theme, LSL streams, dep flags, .env)
       ├── settings.py (AppSettings)
       ├── settings_dialog.py (SettingsDialog)
       ├── record_tab.py ──── recorder.py ──── cortex.py (Emotiv API)
       │                  └── stimulus.py
       ├── train_tab.py ──── eeg_io.py ──── MINDGAN_runner.py (cDCGAN)
       │                  ├── augmentation.py ── utils.py
       │                  ├── model_loader.py
       │                  └── figures.py
       ├── control_tab.py
       ├── drone_tab.py
       ├── validate_tab.py ── figures.py
       └── quality_tab.py

---

Requirements

• Python 3.8+ (tested on 3.9)
• Windows recommended (audio cues use winsound)
• Emotiv EPOC X headset (optional — only for live recording)
• EmotivPRO software (optional — enables LSL streams from the headset)
• DJI Tello drone (optional — only for the Drone tab)

Training and validation work fully offline — just load previously recorded EDF/CSV files.

---

Installation

1. Clone the repository

git clone https://github.com/Meshkat22/MINDGAN_BCI_SUITE.git
cd MINDGAN_BCI_SUITE

2. Create a virtual environment (recommended)

python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate    # macOS / Linux

3. Install Python dependencies

pip install -r requirements.txt

PyTorch note: If you have an NVIDIA GPU and want CUDA acceleration, install the matching PyTorch build from pytorch.org before running the line above.

4. Configure Emotiv API credentials

The Emotiv Cortex API requires three credentials. They are loaded from a .env file.

1. Copy the template:

   copy .env.example .env        # Windows
   # cp .env.example .env        # macOS / Linux

2. Open .env in a text editor and fill in your values:

   EMOTIV_CLIENT_ID=your_client_id_here
   EMOTIV_CLIENT_SECRET=your_client_secret_here
   EMOTIV_LICENSE_KEY=your_license_key_here

3. Get your credentials from the Emotiv Developer Portal.

5. Run the application

python main.py

The GUI window will open. The header shows live status pills for each optional dependency (Cortex, NumPy, Torch, MPL, Sound, Tello) — green means installed, red means missing.

---

Usage Guide

Tab 1 — Record (Motor Imagery Session)

1. Connect the Emotiv EPOC X headset and open EmotivPRO.
2. In EmotivPRO, enable LSL streams.
3. In the app, click Connect.
4. Configure the number of trials and MI type (Left / Right hand).
5. Click Start Recording and follow the on-screen cues.
6. Data is exported as EEG_<timestamp>.csv, markers_<timestamp>.csv, and EEG.edf.

Screenshot:

Tab 2 — EEG Quality

• Inspects contact impedance per channel, signal quality, and power spectral density.
• Use this before recording to ensure good electrode contact.

Tab 3 — Train (cDCGAN Classifier)

1. Select one or more EDF/CSV files from previous recordings.
2. Configure hyperparameters (epochs, batch size, augmentation factor).
3. Enable cDCGAN for three-phase curriculum training.
4. Click Start Training and monitor loss/accuracy in real-time.
5. The trained model is saved as a .pth file.

Screenshot:

Tab 4 — Control (Real-time BCI)

1. Load a trained model.
2. Connect the headset and start EEG streaming.
3. The classifier decodes motor imagery in real-time.
4. Control a virtual cursor with left/right hand imagination.

Tab 5 — Drone (Tello Control)

1. Load a trained model.
2. Connect the DJI Tello drone to your computer's Wi-Fi.
3. Use motor imagery to take off, steer, and land.

Tab 6 — Validate (Cross-session)

1. Load a trained model.
2. Select a recording session from a different day (cross-session validation).
3. Run real-time trials and view the confusion matrix and per-trial results.

---

Model Architecture

Three-phase curriculum training

Phase	Epochs	Description
Phase 1	1–100	S&R augmentation only; GAN warm-up (no GAN data in classifier)
Phase 2	101–200	Progressive GAN mixing (λ: 0 → 1)
Phase 3	201–300	Full GAN + S&R augmentation

CNN Classifier

• Input: (batch, 1, 14, 1000) — 14 EEG channels, 1000 samples (~7.8s at 128 Hz)
• Temporal convolution → Depthwise spatial convolution → Pooling → Fully-connected
• Output: 2 classes (Left / Right hand imagery)

Data Augmentation

• S&R (Segment & Recombine) — cuts and recombines real EEG segments to multiply dataset size.
• cDCGAN — generates synthetic EEG trials with class-conditional control.

This combination achieves robust classification even with small datasets (60–120 trials), which is critical for BCI applications where data collection is expensive.

---

Dependencies

Package	Purpose
numpy	Numerical operations
scipy	Signal processing
pandas	Data handling
scikit-learn	ML metrics
torch	Deep learning (CNN + GAN)
mne	EEG data loading and processing
pyedflib	EDF file writing
pylsl	Lab Streaming Layer for real-time EEG
matplotlib	Plotting and figures
websocket-client	Emotiv Cortex API communication
python-dispatch	Event dispatch for Cortex API
python-dotenv	Loads .env credentials
djitellopy	DJI Tello drone control (optional)
opencv-python	GradCAM visualization (optional — auto-mocked if absent)

---

Settings

User preferences (last subject ID, default folders, theme, etc.) are stored in mindgan_settings.json and persisted between sessions. The file is auto-created on first run.

Open the settings dialog at any time with Ctrl+, or click the ⚙ button in the header.

---

Troubleshooting

Problem	Solution
Emotiv credentials not found warning	Copy .env.example to .env and fill in your credentials
Cortex status pill is red	Install websocket-client and python-dispatch, and ensure EmotivPRO is running
Tello status pill is red	Install djitellopy (pip install djitellopy)
No audio cues on non-Windows	Audio beeps use winsound (Windows only). The app runs fine without them.
Training is very slow	Install a CUDA-enabled PyTorch build if you have an NVIDIA GPU
MINDGAN_runner.py not found	Ensure all files are in the same folder — do not move modules separately

---

Author

Meshkat Ahmad

• Master's Student, Electronic Information Engineering
• College of Biomedical Engineering, Fudan University
• GitHub: Meshkat22

---

License

MIT License — see LICENSE for details.

---

Acknowledgments

• Emotiv EPOC X headset and EmotivPRO software
• MNE-Python for EEG data processing
• PyTorch for deep learning
• Fudan University BCI Lab