Application Overview and Quick Start

🧠 MCX - Mind Control Anything

MCX is a user-friendly Brain-Computer Interface (BCI) implementation and research project. It uses EEG data from the Muse S2 headband to classify the user's mental or physiological state, ultimately allowing for control over any interfacing system.

Real-time signal collection, preprocessing, model training, and system control are all encapsulated in classes, with a graphical user interface available to manage everything.

MCX's active implementation is entirely in src_new/ and the data environment within data/gui/.

Older directories (data/json, data/models, data/npy, data/paper_data, data/sounds, and src/) remain only for archival or reference purposes.

---

🚀 Quick Start

MCX receives data over the Lab Streaming Layer (LSL), so you must achieve this in some way. We recommend (tested on Windows 11) using the BlueMuse GUI with EEG, Accelerometer, and Gyroscope transmission enabled. Please consult its documentation for details regarding connection and setup.¹

One the data streams have been established, you are ready to start the application. Alternatively, the command line flag "-sim" may be used to test the interface with garbage EEG/acc/gyro data.

To run MCX graphically:

cd src_new
python gui.py

This launches the GUI, where you can:

• Create a customized (based on existing) model architecture
• Train a model built on that architecture
• Save and load training sessions
• Perform a (user-validated) real-time test of a trained model
• Execute a program that implements the MCX interface using a chosen model

¹Note: Accelerometer and gyroscope data are not used in the classification process, but the program interface relays an estimated orientation for possible use. At the moment, this may only be disabled by removing instantiation and use of those streams in data_collector.py, augmenting the on_dir method of the program.py template class, and removing the associated methods from mind_reader.py.*

---

📂 Repository Structure

Active Components

Path	Description
src_new/	Main codebase and modules (the current, active version)
data/gui/	All live data, models, and assets used by the running application
├── archs/	Saved model architectures (.keras) and corresponding data (.pkl)
├── dats/	Collected training data true categories and corresponding EEG data (.pkl)
├── models/	Saved models (.keras) and corresponding standard scalers (.pkl)
├── sounds/	Audio files used in training process (.mp3)

Legacy / Archived

Path	Description
src/	Previous code iterations — no longer in use, and largely nonfunctional
data/json, data/models, data/npy, data/paper_data, data/sounds	Historical data and artifacts from earlier testing

---

🧩 Module Architecture

Module	Primary Function	Key Classes
gui.py	Intended executing script: launches the full visual interface and controls all user-facing functions (data collection, training, testing, execution).	MainApp (>25 interface methods managing sequential screens)*
data_collector.py	Receives data from mind_reader and yields training/testing datasets (generator functions).	Collector
inout.py	Handles string manipulation, saving, and loading of architectures, datasets, models, scalers, modifiers, etc.	DataManager
mind_reader.py	Interfaces with LSL streams, matches data to 256 Hz standard, and calculates headband orientation.	Reader (live source), FakeReader (mock data), FakeInfo (mock metadata).
models.py	Keras models and wrappers.	Model (parent), Averaging, Timeseries, BaseMeta, AvgMeta, TmsMeta (metadata string conversions).
preprocessing.py	Training and real-time signal preprocessing, feature extraction, formatting, and scaling, typically on data from data_collector.	Preprocessor, PreprocessorRealtime
program.py	Program interface with methods called from gui.	Program
robo.py	Robot control utilities used by Program1.
programs/	Contains user-defined scripts that follow Program template class. Selectable from GUI.

---

⚙️ Dependencies

You must install the necessary libraries included in requirements.txt . To create a Python virtual environment in the MCX (outer) directory:

python -m venv .venv
python -m pip install -r requirements.txt
.venv\scripts\activate

MCX notably (but not exclusively) uses the following libraries:

• numpy
• sklearn
• scipy
• matplotlib
• tensorflow keras
• customtkinter
• mne

Note: requirements.txt may contain now-unused modules. This will be addressed eventually.

---

🧰 Development Notes

• src_new/ supersedes all earlier src/ code.
• data/gui/ is the live runtime environment.
• Legacy folders are preserved for research traceability.
• For testing without hardware, mind_reader.FakeReader can replace mind_reader.Reader almost anywhere.