The Open Python Muse S Athena EEG Decoder

This software allows recording, streaming via LSL and visualizing signals from the Muse S Athena headband.

• Record raw data to a file
• Decode raw data into a pandas DataFrame
• Stream data over LSL
• Visualise live LSL streams
• Stream in battery signal and display battery level in visualizer
• Validate timestamping accuracy experimentally: confirm we get time-locked ERPs
• Validate the best PPG signal extraction method
• Validate fNIRS signal extraction method

Create a virtual environment

python3 -m venv .venv

source .venv/bin/activate  # on MacOS or Linux
.venv\Scripts\activate     # on Windows

For users: Install from GitHub by opening a terminal and running:

pip install https://github.com/DominiqueMakowski/OpenMuse/zipball/main

For contributors: If you want to make changes

git clone https://github.com/DominiqueMakowski/OpenMuse.git
cd OpenMuse

python3 -m venv .venv

source .venv/bin/activate  # on MacOS or Linux
.venv\Scripts\activate     # on Windows

pip install -e .

After installing the package, open a terminal and use the following commands:

Power up the Muse S Athena headband (a blue light should appear on the front) and run:

OpenMuse find

This will print the MAC addresses of nearby Muse devices. Note the address of your device for the next steps.

OpenMuse record --address <your-muse-address> --duration 60 --outfile data.txt

Alternatively, omit --address to autodiscover a single nearby device:

OpenMuse record --duration 60 --outfile data.txt

If multiple devices are found (or none), you'll be asked to specify --address.

Once your file is recorded, you can load it in Python using:

import pandas as pd
import OpenMuse 

with open("data.txt", "r", encoding="utf-8") as f:
    messages = f.readlines()
data = OpenMuse.decode_rawdata(messages)

# Plot Movement Data
data["ACCGYRO"].plot(
    x="time",
    y=["ACC_X", "ACC_Y", "ACC_Z", "GYRO_X", "GYRO_Y", "GYRO_Z"],
    subplots=True
)

To stream data over LSL, use:

OpenMuse stream --address <your-muse-address>

This creates separate LSL streams for groups of channels (Muse_EEG, Muse_ACCGYRO, etc.).

The following options are available:

• --address: The MAC address of your Muse device (required)
• --duration: Duration of the recording in seconds (if not specified, streaming will continue until you press Ctrl+C in the terminal)
• --preset: Preset configuration (default: p1041 for all channels)
• --outfile: Optional JSON file to save the streamed data

To visualize live LSL streams, open a new terminal (while the streaming is running) and run:

OpenMuse view

Muse S Athena specs (From the Muse website):

• Wireless Connection: BLE 5.3, 2.4 GHz
• EEG Channels: 4 EEG channels (TP9, AF7, AF8, TP10) + 4 amplified Aux channels
  • Sample Rate: 256 Hz
  • Sample Resolution: 14 bits / sample
• Accelerometer: Three-axis at 52Hz, 16-bit resolution, range +/- 2G
• Gyroscope: Three-axis at 52Hz, 16-bit resolution, range +/- 250dps
• PPG Sensor: Triple wavelength: IR (850nm), Near-IR (730nm), Red (660nm), 64 Hz sample rate, 20-bit resolution
• fNIRS Sensor: 5-optode bilateral frontal cortex hemodynamics, 64 Hz sample rate, 20-bit resolution

Table derived from the signature of the data packets present in the data. More presets could exist.

This project would not have been possible without the breakthroughs of amused-Py that identified the communication protocol and AbosaSzakal's parser who documented the data structure.