Chords-Python#

Overview#

Chords-Python is an open-source bag of tools for recording biopotential signals like ECG, EMG, EEG, or EOG, along with visualization using BioAmp hardware. It’s ideal for educational purposes as it promotes DIY Neuroscience and makes biopotential signal exploration more accessible for students and researchers.

Features#

Feature

Description

Connection

Supports both wired and wireless connections via Wi-Fi, Bluetooth, or USB (Serial).

Data Reading

Reads data packets from development board in real-time, efficiently processing them to prevent data loss and ensure accurate signal representation for analysis and visualization.

CSV Logging

Optionally logs incoming data to a CSV file with columns for counter and channel data, enabling easy storage, analysis, and sharing.

LSL Streaming

Streams data via Lab Streaming Layer (LSL), a protocol for time-synchronized data sharing. Enables real-time analysis, visualization, or integration with tools like BrainVision.

Applications

Provides an interface to run multiple applications simultaneously via the LSL stream.

Create Custom Application

Allows users to develop and integrate their own applications with the system.

Software Requirements#

  • Arduino IDE – Required to upload the Chords Arduino firmware to your development board.

  • Python – Ensure you have the most recent version installed.

  • VS Code or any other code editor (Alternatively, you can use the Command Prompt).

Hardware Requirements#

To use Chords-Python, you need:

Setting up the hardware#

Make all the connections according to the hardware you are using , including sensor connections with the development board, body connections with the sensor, and connections from the development board to your laptop.

Uploading the code#

Once you are all set, it is time to upload the code to your development board. Go to Chords Arduino Firmware GitHub repo, scroll down to the supported boards table, find your board name, and click on the Arduino sketch corresponding to that row. Copy the sketch and paste it into Arduino IDE. Go to tools, select your board, and the correct COM port. Now, hit the upload button.

Opening Chords-Python#

Follow these steps to set up and install Chords-Python:

  1. Ensure you have latest version of Python installed.

  2. Download the GitHub repository:

    • You can download the Chords-Python repository from GitHub by visiting the following link: Chords-Python.

    • Or, You can clone the repository using Git by running the following command:

    git clone https://github.com/upsidedownlabs/Chords-Python.git

  3. Create a Virtual Environment:

    A virtual environment allows you to manage dependencies for your project in isolation.

    • Open a terminal or command prompt.

    • Navigate to the directory where you have cloned the repository.

    • Run the following command to create a virtual environment:

    python -m venv venv
    • To activate the virtual environment:

      • On Windows:

      .\venv\Scripts\activate

      • On macOS/Linux:

      source venv/bin/activate

  4. Install the Required Python Libraries:

    Once the virtual environment is activated, you need to install the required libraries for the project.

    • In the terminal or command prompt, run the following command to install the dependencies needed to run the python script listed in the requirements.txt file:

    pip install -r requirements.txt

    • This will install all the necessary Python libraries and dependencies for Chords-Python.

  5. To launch the Flask server, run the following command :

    python app.py

Click on the generated link to open the web interface.

Interface in Light Mode

Interface in Light Mode#

Interface in Dark Mode

Interface in Dark Mode#

Connection#

The first step is to establish a connection with your device and start the stream.

There are three connection options available:

  • Wi-Fi

  • Bluetooth

  • Serial (USB)

Wi-Fi#

  1. Upload the Wi-Fi firmware through the Chords-Arduino-Firmware repository

  2. Turn on the device and connect to the access point created by the device (e.g., npg-lite-2)

  3. In the web interface:

    • Click the Wi-Fi button

    • Click the Connect button

A pop-up notification will appear indicating a successful connection.

Bluetooth#

  1. Upload the Bluetooth firmware through the Chords-Arduino-Firmware repository

  2. Turn on the device and enable Bluetooth on your computer

  3. In the web interface:

    • Click the Bluetooth button

    • Select your device from the list of available devices

    • Hit the Connect button

A pop-up notification will appear indicating a successful connection.

Serial (USB)#

  1. Upload the Serial firmware through the Chords-Arduino-Firmware repository

  2. Connect the device to your computer using a USB cable

  3. In the web interface:

    • Click the Serial button

    • Click the Connect button

A pop-up notification will appear indicating a successful connection.

Note

The connection step is essential as it initiates the LSL Stream, which is required for running applications.

CSV Logging#

The raw data received from the device can be logged to a CSV file for further analysis or record-keeping. This optional feature can be enabled or disabled in the web interface.

To use CSV logging:

  1. Click the Start recording button to begin logging - A file with name is created ChordsPy_{timestamp}.csv in the same folder. - File includes columns for counter and channel data

  2. Click the Stop recording button to end logging - File will be saved in the same folder

CSV Logging

CSV Logging#

Applications#

There are many applications available that stream the LSL and can be run for various purposes.

List of available applications:

1. ECG with Heart Rate#

Overview#

The ECG with Heart Rate is a real-time application designed to visualize and analyze Electrocardiogram (ECG) data using the Lab Streaming Layer (LSL) protocol. Built with Python and PyQt5, this application provides a graphical interface for monitoring ECG signals, detecting R-peaks (heartbeats), and calculating the heart rate in real time. It applies signal processing techniques and utilizes the neurokit2 library to estimate R-peak detection and heart rate.

Features#

Features

Description

  1. Real-Time ECG Visualization

  • Displays real-time ECG signals in a dynamic plot using pyqtgraph.

  • Supports adjustable y-axis scaling based on the sampling rate (e.g. 250 Hz or 500 Hz).

  1. R-Peak Detection

  • Utilizes the neurokit2 library to detect R-peaks in the ECG signal.

  • Highlights detected R-peaks as red dots on the plot for easy visualization.

  1. Heart Rate Calculation

  • Computes heart rate (in BPM) using the time intervals between consecutive R-peaks.

  • Implements a moving average filter to smooth heart rate values and reduce noise.

  1. Interactive GUI

  • Built with PyQt5, providing a user-friendly interface with a real-time ECG plot and heart rate display.

  • Allows double-click to reset the plot’s zoom level to default settings.

  1. Signal Filtering

  • Applies a low-pass Butterworth filter to remove high-frequency noise from the ECG signal.

  • Helps in enhancing signal clarity, which can assist in identifying R-peaks.

A GUI window will appear, displaying the real-time ECG signal along with the calculated heart rate.

Heart Rate with ECG

Heart Rate with ECG#

2. EMG with Envelope#

Overview#

The EMG with Envelope is a Python-based application designed to visualize and analyze Electromyography (EMG) signals in real-time. It connects to an EMG data stream using the Lab Streaming Layer (LSL) protocol, processes the signal to extract the EMG envelope, and displays both the filtered EMG signal and its envelope in a user-friendly graphical interface. Built with PyQt5 and pyqtgraph, the application provides a responsive and interactive visualization tool for students, researchers, or developers working with EMG data.

Features#

Features

Description

  1. Real-Time EMG Signal Visualization

  • Connects to an LSL stream to acquire real-time EMG data.

  • Displays the EMG signal after applying a high-pass filter (70 Hz cutoff) to remove low-frequency noise.

  1. EMG Envelope Extraction

  • Computes the Root Mean Square (RMS) envelope of the filtered EMG signal using a moving window.

  • Applies convolution with a uniform window and pads the result to align with the original signal length.

  1. Interactive and Responsive GUI

  • Built using PyQt5 for a modern and intuitive user interface.

  • Features two synchronized plots: one for the filtered EMG signal and one for the EMG envelope.

  • Disables zoom and pan for a clean, fixed-axis visualization.

  1. Customizable Signal Processing

  • Implements a high-pass Butterworth filter to remove baseline drift and noise.

  • Adjusts the RMS window size dynamically based on the sampling rate (e.g., 25 samples for 250 Hz, 50 samples for 500 Hz).

  1. Dynamic Plot Updates

  • Updates the plots in real-time using a fixed-size circular buffer for efficient data handling.

  • Refreshes the display every 15 milliseconds for smooth and responsive visualization.

A GUI window will appear, displaying the real-time EMG signal along with the calculated EMG Envelope.

EMG with Envelope

EMG with Envelope#

Features#

Features

Description

  1. Real-Time EOG Signal Visualization

  • Displays the filtered EOG signal in real-time using a low-pass filter (10 Hz cutoff).

  • Dynamically updates the plot with a 5-second rolling window for continuous monitoring.

  1. Dual-Plot Interface

  • EOG Signal Plot: Displays the filtered EOG signal with detected peaks marked in red.

  • Blink Detection Plot: Shows a binary representation of detected blinks (1 for blink, 0 for no blink).

  1. Blink Detection

  • Detects blinks by identifying peaks in the filtered EOG signal.

  • Uses a dynamic threshold based on the mean and standard deviation of the signal to distinguish blinks from noise.

  • Implements a minimum time gap (0.1 seconds) between detected blinks to avoid false positives.

  1. User-Friendly GUI

  • Built with PyQt5 for a responsive and intuitive interface.

  • Includes features like grid lines, auto-scaling, and zoom disablement for better usability.

A GUI window will appear, displaying the real-time EOG signal along with the Blinks marked as Red dot.

EOG with Blinks

EOG with Blinks#

4. EEG with FFT#

Overview#

The EEG with FFT and Brainwave Power is a Python-based application designed to visualize and analyze Electroencephalography (EEG) signals in real-time. It connects to an EEG data stream using the Lab Streaming Layer (LSL) protocol, processes the signal to remove noise, and performs Fast Fourier Transform (FFT) to compute the power of different brainwave frequency bands (Delta, Theta, Alpha, Beta, and Gamma). The application provides a graphical user interface (GUI) built with PyQt5 and pyqtgraph for real-time visualization of raw EEG signals, FFT results, and brainwave power distribution.

Features#

Features

Description

  1. Multi-Channel EEG Visualization

  • Displays raw EEG signals from all available channels in real-time.

  • Each channel shown in a scrolling plot with 500-sample moving window.

  1. Multi-Channel FFT Analysis

  • Computes and displays FFT for all EEG channels simultaneously.

  • Visualizes the FFT results in a separate plot, focusing on the 0-50 Hz range.

  1. Signal Processing

  • Applies a notch filter to remove 50 Hz powerline interference.

  • Uses a bandpass filter (0.5-48 Hz) to isolate relevant EEG frequencies.

  • Implements a Hanning window for FFT computation to reduce spectral leakage.

  1. Single-Channel Brainwave Power Analysis
  • Calculates the power of five brainwave frequency bands:

    • Delta (0.5-4 Hz)

    • Theta (4-8 Hz)

    • Alpha (8-13 Hz)

    • Beta (13-30 Hz)

    • Gamma (30-45 Hz)

  • Displays the power of each band in a bar chart for easy comparison.

  1. User-Friendly GUI
  • Provides a clean and intuitive interface with Three-panels:

    • Top-left: Multi-channel EEG waveforms

    • Top-right: Multi-channel FFT results

    • Bottom-right: Single-channel brainwave power analysis

  • Allows users to monitor multi-channel EEG data and its frequency components simultaneously.

A GUI window will appear, displaying the real-time EEG signal along with the calculated FFT and Brainwave power distribution.

EEG with FFT

EEG with FFT#

5. EEG Tug of War Game#

Overview#

The EEG Tug of War Game is a Python-based application that leverages Electroencephalography (EEG) signals to create an interactive two-player game. Players control the movement of a ball on the screen by modulating their brain activity, specifically the Alpha and Beta frequency bands. The game uses the Lab Streaming Layer (LSL) protocol to acquire real-time EEG data, processes the signals to calculate relative power in the Alpha and Beta bands, and translates these into forces that move the ball. The first player aims to push the ball onto the opponent’s side to score and win the game. The application is built using the pygame library for the graphical interface and integrates with pylsl for EEG data acquisition.

Features#

Features

Description

  1. Real-Time EEG Signal Visualization

  • Connects to an LSL stream to acquire real-time EEG data.

  • Computes the power spectral density (PSD) of Alpha (8-13 Hz) and Beta (13-30 Hz) frequency bands using Welch’s method.

  • Calculates the relative power ratio (Beta/Alpha) to determine player force.

  1. Interactive Gameplay

  • Two players compete to move a ball to the opponent’s side using their brain activity.

  • The ball’s movement is determined by the net force derived from the players’ EEG signals.

  1. Dynamic Thresholding

  • Uses a moving average of the last 10 data points to smooth the force calculations.

  • Applies a threshold to prevent small fluctuations from affecting the ball’s movement.

  1. User-Friendly GUI

  • Features a full-screen graphical interface with a central ball and two player paddles.

  • Displays real-time updates of the ball’s position and forces applied by each player.

  • Includes buttons for starting, pausing, resuming, and exiting the game.

  1. Win Condition and Feedback

  • Declares a winner when the ball reaches either side of the screen.

  • Plays a sound effect to celebrate the winner.

  • Automatically pauses the game upon a win and allows for a restart.

The game window will open, featuring buttons for START/RESTART, PLAY/PAUSE, and EXIT. These buttons offer intuitive control, allowing players to easily start, pause, resume, or exit the game as needed.

EEG Tug of War

EEG Tug of War#

For detailed instructions, check out the EEG Tug of War Game Instructable.

6. EEG Beetle Game#

Overview#

The EEG Beetle Game is a Python-based application that uses Electroencephalography (EEG) signals to control a beetle’s movement in a 2D game environment. The game leverages the Lab Streaming Layer (LSL) protocol to acquire real-time EEG data, processes the signal to detect the user’s focus level, and translates it into upward or downward movement of the beetle. The application is built using the pygame library for the game interface and integrates signal processing techniques to analyze EEG data in real-time.

Features#

Features

Description

  1. Real-Time EEG Signal Visualization

  • Connects to an LSL stream to acquire real-time EEG data.

  • Implements a notch filter to remove 50 Hz power line interference and a bandpass filter to isolate relevant EEG frequency bands (0.5–48 Hz).

  1. Focus Level Calculation

  • Computes the user’s focus level by analyzing the power spectral density of the EEG signal.

  • Focus level is calculated using the ratio of high-frequency (beta and gamma) to low-frequency (delta, theta, and alpha) power bands.

  1. Calibration System

  • Includes a calibration phase to establish a baseline focus level for the user.

  • Dynamically sets a focus threshold based on the user’s EEG data during calibration.

  1. Beetle Movement Control

  • Moves the beetle upward when the user’s focus level exceeds the threshold.

  • Moves the beetle downward when the focus level is below the threshold.

  • Implements smooth animation and boundary constraints to ensure the beetle stays within the game window.

  1. Interactive Game Interface

  • Features a 2D game environment with a beetle sprite that responds to the user’s focus level.

  • Displays real-time feedback on the beetle’s position and focus level.

  1. Dynamic Animation

  • Uses a sequence of beetle sprites to create smooth animations.

  • Adjusts animation speed based on the game’s frame rate.

A GUI window will appear, showing all calibration messages, followed by the game starting, and finally displaying the game with the beetle.

EEG Beetle Game

EEG Beetle Game#

7. GUI#

Overview#

The GUI application is a Python-based tool designed to visualize real-time data streams from an Arduino device using the Lab Streaming Layer (LSL) protocol. The application connects to an LSL stream, retrieves multi-channel data, and plots it in real-time using the pyqtgraph library.

Features#

Features

Description

  1. LSL Stream Integration

  • Automatically searches for and connects to available LSL streams.

  • Supports dynamic detection of the number of channels in the stream.

  • Displays connection status and channel count in the GUI.

  1. Real-Time Data Visualization

  • Plots real-time data for each channel in separate graphs.

  • Updates plots at a high frequency for smooth visualization.

  1. Customizable GUI

  • Built using PyQt and pyqtgraph for a responsive and interactive interface.

  • Features a clean layout with individual plots for each channel.

  • Includes a status bar to display LSL connection details.

A GUI window will appear that shows the data in real-time.

GUI

GUI#

8. EOG Keystroke Emulator#

Overview#

The EOG Keystroke Emulator is a Python-based application designed to detect eye blinks using Electrooculography (EOG) signals and translate them into keystrokes. The application leverages the Lab Streaming Layer (LSL) protocol to acquire real-time EOG data, processes the signal to detect blinks, and simulates a spacebar press whenever a blink is detected. The application is built using the tkinter library for the graphical user interface (GUI) and integrates with pyautogui for keystroke emulation.

Features#

Features

Description

  1. Real-Time EOG Signal Processing

  • Connects to an LSL stream to acquire real-time EOG data.

  • Implements a low-pass filter to smooth the EOG signal for accurate blink detection.

  1. Blink Detection

  • Detects blinks by identifying peaks in the filtered EOG signal.

  • Uses a dynamic threshold based on the mean and standard deviation of the signal to distinguish blinks from noise.

  • Incorporates a refractory period to prevent multiple detections from a single blink.

  1. Keystroke Emulation

  • Simulates a spacebar press (pyautogui.press(‘space’)) whenever a blink is detected.

  • Provides visual feedback by updating the GUI button color upon blink detection.

  1. User-Friendly GUI

  • Features a compact, movable popup window with a clean and intuitive interface.

  • Includes buttons for connecting to the LSL stream, starting/stopping blink detection, and quitting the application.

  • Displays an eye icon to represent the blink detection status.

A small window appears in the corner, displaying a Connect button. Once connected, a Start button becomes visible. Pressing the Start button initiates blink detection, and each detected blink triggers a spacebar key press.

Keystroke Emulator

Keystroke Emulator#

9. CSV Plotter#

Overview#

The CSV Plotter is a Python-based application designed to visualize data from CSV files. Built using the tkinter library for the graphical user interface (GUI) and plotly for data visualization, this tool allows users to load CSV files, select specific data channels, and generate interactive line plots.

Features#

Features

Description

  1. Load CSV Files

  • Users can load CSV files containing data with a Counter column and multiple channels (e.g., Channel1, Channel2, etc.).

  • The application automatically detects the header row and skips any metadata above it.

  1. Channel Selection

  • A dropdown menu dynamically populates with available channels (e.g., Channel1, Channel2, etc.) from the loaded CSV file.

  • Users can select a specific channel to plot.

  1. Interactive Data Visualization

  • Utilizes plotly to generate interactive line plots for the selected channel.

  • Plots include advanced features such as:

    • Zoom: Zoom in to inspect specific data ranges.

    • Pan: Move across the plot to explore different sections.

    • Autoscale: Automatically adjust the plot scale to fit the data.

    • Download Plot as PNG: Save the generated plot as a high-quality PNG image.

    • Hover-to-View Data Points: Hover over the plot to view precise data values.

  1. User-Friendly Interface

  • Simple and intuitive GUI with buttons for loading files and plotting data.

  • Displays the name of the loaded CSV file for easy reference.

A small pop-up will appear, providing options to load the file, select the channel, and plot the data.

CSV Plotter

CSV Plotter#

Create Custom application#

You can create custom applications using the provided framework by following these steps:

  1. Configure Application Metadata:

Edit the apps.yaml file in the config folder with your application details:

- title: "Your Application Title"
  icon: "path/to/your/icon.png"
  color: "your_hex_color"
  script: "path/to/{app_name}.py"
  description: "Brief description of your application"
  category: "Your Category"

Add this as a new entry in the YAML list. Replace all placeholders with your actual application details.

Note

  • The icon path should be relative to the application root directory

  • color should be in HEX format (e.g., “#FF5733”)

  • The script path should point to your Python file

  1. Create application script:

Create a new Python script in the main directory with your application name. The script should contain:

  • LSL stream connection handling to receive device data

  • User interface components using PyQt5/PyQtGraph

  • Data processing logic for incoming signals

Tip

Use the existing applications in the repository as reference implementations for: - lsl setup and data acquisition - Advanced UI layouts - Signal processing examples - Performance optimization