Shape of the Wave · field notes

An open driver for the Muse 2 headband

The Muse 2 is a consumer EEG headband: four dry electrodes, a motion sensor and a pulse sensor. We set one up without the vendor app, wrote a small Rust program that anyone can read and change, and wrote down everything the headset told us along the way.

What it is

The headband presses four electrodes against the head: two on the forehead (AF7, AF8) and two behind the ears (TP9, TP10), measured against a reference at the centre of the forehead. It samples each at 256 times a second. It also carries an accelerometer and gyroscope, and a light sensor on the forehead that sees the pulse.

Normally all of this goes to the Muse phone app, which turns it into guided meditation and keeps the raw signal to itself. Our setup skips the app. A program called muse2 talks to the headset directly and gives you the raw numbers, live on screen and as plain CSV files.

AF7 AF8 ref TP9 TP10 back of head

Status

What has been checked against the real headset, and what has not.

PieceStateEvidence
USB console: versions, status, commandsVerifiedReplies captured from the headset over the cable.
Bluetooth discovery and connectionVerifiedFound and connected from a Mac; 17 characteristics listed.
EEG, four electrodesVerified60-second recording, about 255 samples a second per channel, no packets lost.
Accelerometer and gyroscopeVerifiedAbout 52 samples a second, gravity reads 1 g.
Pulse sensor (preset p50)Verified30-second recording, three light channels at about 64 samples a second.
Battery telemetryVerifiedBattery percent and fuel gauge decode; the last two fields read zero on this unit.
Auxiliary EEG input (preset p20)Not yet triedImplemented from the published protocol.
LinuxBuilds, not yet streamedCompiles and passes tests on Linux; streaming was run on macOS.
Open firmware on the headsetNot availableProtocol core written and tested; no flashable image. See Firmware.

Quick start

You need a Mac or Linux machine with Bluetooth, the Rust toolchain, and a Muse 2.

Build

curl -LO https://muse.shapeofthewave.com/muse2-open-driver.zip
unzip muse2-open-driver.zip && cd muse2-open-driver/host
cargo build --release
cargo test                      # the decoders, checked without a headset

Identify the headset over USB

Plug the headset in with a micro-USB cable that carries data, then:

./target/release/muse2 info

It prints the name, board, firmware and bootloader versions, and battery. No Bluetooth is involved.

Stream over Bluetooth

Unplug the cable (the radio is off while charging), hold the power button until the lights sweep, put the band on, and close the Muse phone app if it is running anywhere nearby.

./target/release/muse2 scan                         # is it visible?
./target/release/muse2 stream                       # live readout, Ctrl-C to stop
./target/release/muse2 stream --seconds 120 --out rec/sitting-still
./target/release/muse2 stream --preset p50 --out rec/with-pulse

The live readout prints one line a second: for each electrode the signal size in microvolts and its alpha share (how much of the 4 to 30 Hz power sits in the 8 to 13 Hz alpha band), then head tilt, battery, and packets received and lost.

A good fit shows 5 to 30 µV per electrode when you sit still. Hundreds of microvolts means an electrode is not touching skin: move hair, dampen the electrodes slightly, tighten the band.

The data

With --out, each run writes a folder of CSV files. Every row carries time_s, seconds since streaming began.

FileColumnsRate
eeg.csvtime_s, channel, seq, microvolts256 per second per channel
accel.csvtime_s, seq, x_g, y_g, z_g52 per second
gyro.csvtime_s, seq, x_dps, y_dps, z_dps52 per second
ppg.csvtime_s, channel, seq, raw64 per second per channel, preset p50 only
telemetry.csvtime_s, seq, battery_percent, fuel_gauge_mv, adc_raw, temperature_cevery few seconds
control.jsonleach JSON reply from the headset
meta.jsonstart time, preset, versions, stream list

What a recording looks like

TP9 AF7 AF8 TP10 0 s 1 s 2 s 3 s 4 s 50 µV
Four seconds from our first recording, sitting still, slow drift removed. The forehead electrodes (AF7, AF8) sat at about 7 µV; the left ear electrode was noisier, a sign of a looser fit. From the pulse sensor in the next recording the same program's data gives a heart rate near 83 beats a minute.

What it is good for

Things it does well

  • Seeing your own alpha rhythm. Close your eyes and relax: within seconds a 8 to 13 Hz wave grows at the back electrodes. Open them and it fades. It is the oldest result in EEG and you can reproduce it in a minute.
  • Meditation and focus feedback you control. The app scores "calm" with a hidden formula. With raw data you can pick your own measure, such as the alpha-to-beta ratio or how steady the signal is, and watch it change.
  • Blinks, jaw clenches and head movement. These are huge signals. They make reliable hands-free switches and good first experiments.
  • Pulse and breath. The forehead light sensor gives heart rate and its variability; the accelerometer shows breathing as a slow rocking.
  • Sleep onset and drowsiness. The slide from alpha into slower theta is visible as you nod off.
  • Teaching and tinkering. Real biosignals, a readable driver of about a thousand lines, and plain CSV out.

Things it does not do

  • It does not read thoughts, words or images. Four electrodes see broad rhythms, not content.
  • It is not a medical device and cannot diagnose anything.
  • It covers the forehead and the area behind the ears only. Nothing over the top or back of the head.
  • Dry electrodes are noisy. Movement, a loose fit and muscle tension swamp the brain signal, so sit still for anything you want to trust.

The USB console

The manual describes the micro-USB port as a charging port. On our unit it is also a serial console. Plugged into a computer the headset appears as a USB serial device (USB id 0483:5740, an STMicroelectronics id) and answers the same short text commands the phone app sends over Bluetooth. We have not seen this written up elsewhere.

$ muse2 usb v1
v1 -> {"ap":"headset","sp":"Blackcomb_revB","tp":"consumer","hw":"30.2","bn":1,"fw":"1.0.27","bl":"1.1.0","pv":1,"rc":0}
CommandWhat came back
v1versions: board, hardware, firmware, bootloader
sstatus: name, serial, address, processor id, battery, preset
h d khalt, start, keep-alive: each acknowledged
p21 p20 p50choose which sensors stream
a l x zacknowledged; purpose not yet known
btwo counters, rd and rt; purpose not yet known

Two limits. Sensor data does not come out of the USB port, even after the start command. And while the cable is in, the radio is off, so you cannot charge and stream at once. Interaxon's own radio test report says the same.

Firmware

We wanted open firmware on the headset itself. There is none. The Muse 2 runs Interaxon's closed firmware (1.0.27 on ours) on an STM32 microcontroller, and nobody has published a replacement or a dump. So the work has two layers.

Done: an open host

Everything on the computer side is ours and readable: the transport, the packet decoders, the recording, the band-power maths. The headset's firmware is treated as a black box that speaks a documented protocol.

Started: understanding the firmware

What a real open firmware still needs: a genuine image to study, the chip identities, and a way to recover a headset if a flash goes wrong. Until those exist, flashing anything would risk the device.

Protocol

Enough to write your own client in any language.

IdStreamPacket after the 2-byte counter
0003 to 0006EEG TP9, AF7, AF8, TP10twelve 12-bit samples; µV = 0.48828125 × (raw − 2048)
0007EEG auxiliary inputsame, preset p20
0009gyroscopethree (x, y, z) of signed 16-bit; × 0.0074768 degrees per second
000aaccelerometerthree (x, y, z) of signed 16-bit; × 0.0000610352 g
000btelemetrybattery ÷ 512 percent, fuel gauge × 2.2 mV, ADC, temperature
000f to 0011pulse sensor: ambient, infrared, redsix 24-bit samples, preset p50

The packet layouts come from the long-standing community projects muse-lsl and muse-js.

Troubleshooting

SymptomCause and fix
"No Muse seen"The cable is still plugged in, the headset is off, or the phone app has the connection. Unplug, power on, close the app.
Bluetooth "not authorized" on a MacmacOS grants Bluetooth per application. Run from a terminal app that has it under System Settings, Privacy and Security, Bluetooth. A plain SSH login is refused; a tmux session started from an allowed terminal works.
Connects, then the headset switches offThe headset often drops the first connection after power-on within two seconds; the next one holds, and muse2 retries by itself. Left unconnected, the headset switches itself off: press the power button again.
Signal in the hundreds of microvoltsAn electrode is off the skin. Adjust the fit and wait a few seconds for it to settle.
muse2 info finds no portThe cable is charge-only. Use one that carries data.
Stream stops after ten seconds in your own clientSend the keep-alive command k every couple of seconds.

Source

One archive holds the host driver, the firmware protocol library, and the protocol notes. MIT licence.

Download the source (76 KB zip)