AllSpiceMirrors/EEGFrontier
0
Fork 0
mirror of https://github.com/TheusHen/EEGFrontier.git synced 2026-04-12 23:05:49 +00:00
Files Issues Projects Releases Wiki Activity
EEGFrontier/Pendulum/README.md
TheusHen 52c98dcdfa Add EEG processing and visualization components 
- Implemented mne_tools.py for converting sample records to MNE Raw format.
- Created models.py to define data structures for sample, event, and error packets.
- Developed pyqt_focus.py for a PyQt-based focus monitoring GUI with real-time EEG data visualization.
- Added 
eflex_bridge.py to manage the EEG engine instance.
- Introduced simulator.py to simulate EEG data packets for testing purposes.
- Established a web dashboard in pendulum_web.py for live EEG data display and diagnostics.
- Configured project dependencies in pyproject.toml and 
equirements.txt.
- Added batch and PowerShell scripts for running and stopping the Reflex application.
- Created 
xconfig.py for Reflex application configuration.
2026-02-28 17:56:04 -03:00

1.9 KiB
Raw Permalink Blame History

Pendulum EEG Suite

This directory/software won't be nessesary a review from HackClub Reviewer

Note for reviwer.

This directory includes software for EEG reading from USB port, not an firmware part.

Pendulum is the host software for EEGFrontier hardware. It follows the firmware protocol from firmware/ and provides:

  • A local Reflex web dashboard (raw data, diagnostics, export tools).
  • A desktop pyqtgraph app focused on real-time focus analysis.
  • A simulation mode for development without hardware connected.

Stack

  • Python 3.11+
  • Reflex
  • pyserial
  • numpy
  • scipy
  • pyqtgraph + PyQt6
  • mne

Setup

cd Pendulum
python -m venv .venv
.venv\Scripts\activate
pip install -U pip
pip install -e .

Run

1) Web dashboard (Reflex)

cd Pendulum
reflex run

Open the localhost URL shown by Reflex.

If you hit frontend bootstrap issues on Windows (bun/npm path), use:

.\run_reflex.ps1

or:

run_reflex.bat

If you need to stop all running Reflex instances:

.\stop_reflex.ps1

2) Desktop focus monitor (pyqtgraph)

With hardware:

python -m pendulum_eeg.pyqt_focus --port COM5

Simulation:

python -m pendulum_eeg.pyqt_focus --simulate

Firmware Protocol (BIN mode)

Packet format:

  • packet = COBS(raw_packet) + 0x00
  • raw_packet = [type][ver][payload...][crc16_le]

Packet types:

  • 0x01: sample
  • 0x02: event
  • 0x7F: error

Sample payload:

  • sample_index u32
  • t_us u32
  • status24 u32
  • ch1..ch4 i32
  • flags u32
  • missed_drdy_frame u32
  • recoveries_total u32

Export formats

  • exports/*.csv
  • exports/*.npz
  • exports/*.json
  • exports/*.fif (MNE)

Notes

  • Default serial baud: 921600
  • Default firmware sample rate: 250 SPS
  • Focus score is a real-time heuristic from EEG bands and should be calibrated per user/protocol for serious studies.