NeuroSky.MindWave.Sdk 2.0.4

NeuroSky MindWave Mobile Windows SDK

Modern C# SDK for NeuroSky MindWave Mobile EEG headsets — BLE + BT Classic via WinRT.

Getting Started

Step 1 — Add the NuGet package

Visual Studio — Package Manager UI

Tools → NuGet Package Manager → Manage NuGet Packages
Search: NeuroSky.MindWave.Sdk → Install

Edit .csproj directly (recommended)

<PackageReference Include="NeuroSky.MindWave.Sdk" Version="2.0.3" />

.NET CLI

dotnet add package NeuroSky.MindWave.Sdk

Step 2 — Set the Windows target framework

WinRT Bluetooth APIs require a Windows-specific TFM. Open your .csproj and confirm:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NeuroSky.MindWave.Sdk" Version="2.0.3" />
  </ItemGroup>
</Project>

Plain net8.0 will not work — WinRT types (Windows.Devices.Bluetooth) are only available with the Windows TFM suffix.

Step 3 — Find your headset's MAC address

Settings → Bluetooth & other devices → MindWave Mobile → More info

Or via PowerShell:

Get-PnpDevice -Class Bluetooth | Where-Object { $_.FriendlyName -like "*MindWave*" }

Step 4 — Connect and stream

using NeuroSky.Sdk;

await using var sdk = new NeuroSkySdk();
sdk.StateChanged += (_, state) => Console.WriteLine($"[State] {state}");

using var cts = new CancellationTokenSource();
Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };

// Connect — BLE by default
await sdk.ConnectAsync("AA:BB:CC:DD:EE:FF");

// Set notch filter for your region (removes power-line noise)
await sdk.SendCommandAsync(NeuroSkyCommand.Notch60Hz);  // Korea/USA
// await sdk.SendCommandAsync(NeuroSkyCommand.Notch50Hz);  // Europe/China

await foreach (var data in sdk.DataStream(cts.Token))
{
    Console.WriteLine($"Attention  : {data.Attention}");
    Console.WriteLine($"Meditation : {data.Meditation}");
    Console.WriteLine($"Signal     : {data.SignalQuality}");
}

That's it — four steps from zero to streaming EEG data.

Requirements

Connection Modes

Choose how to connect via the TransportMode parameter:

// BLE (default)
await sdk.ConnectAsync("AA:BB:CC:DD:EE:FF");

// BT Classic only — pair the device first in Windows Settings
await sdk.ConnectAsync("AA:BB:CC:DD:EE:FF", TransportMode.BtClassic);

Connection States

Subscribe to StateChanged to observe the lifecycle. ConnectAsync() never throws on connection failure — it transitions to Error instead, so always check the final state.

sdk.StateChanged += (_, state) =>
{
    if (state == ConnectionState.Error)
    {
        Console.WriteLine("Connection failed — verify pairing / power / MAC address.");
    }
};

Simulator (without a real device)

using NeuroSky.Sdk;

var simulator = new SimulatorTransport();
simulator.SetMode(SimulatorTransport.Mode.Focused);

await simulator.ConnectAsync("simulator");

await foreach (var data in simulator.DataStream(cts.Token))
{
    Console.WriteLine($"Attention: {data.Attention}");
}

BrainWaveData

Finding Your Device Address

ConnectAsync() takes a Bluetooth MAC address. Use FindDeviceAddressAsync() once on first launch to discover it, then store it (e.g., in app settings) for faster subsequent connections.

await using var sdk = new NeuroSkySdk();

// Discover by name — scans BLE advertisements for up to 10 s
var cached = Properties.Settings.Default.DeviceMac;
var address = !string.IsNullOrEmpty(cached)
    ? cached
    : await sdk.FindDeviceAddressAsync("MindWave Mobile");

if (address is null)
{
    Console.WriteLine("Device not found — check power and BLE adapter.");
    return;
}

Properties.Settings.Default.DeviceMac = address;
Properties.Settings.Default.Save();   // cache — skips scan next launch

await sdk.ConnectAsync(address);

Working with DataStream

Packet timing

In BLE mode, two characteristics transmit packets at different rates.

ThinkGearParser accumulates state. Regardless of which characteristic triggered the emit, each BrainWaveData object contains the latest accumulated value of every field.

Caution — attention-based filter

// Wrong pattern — drops all packets in RawEEG-only sessions
await foreach (var data in sdk.DataStream(ct))
{
    if (data.Attention == 0) continue;  // Attention is always 0 when eSense is off
    // ...
}

If StopESense is sent or StartESense is never called, the device does not transmit attention data. Attention stays at 0 and this guard silently drops every packet.

Correct patterns:

// eSense session — filter by signal quality, not value
await foreach (var data in sdk.DataStream(ct))
{
    if (data.SignalQuality == SignalQuality.NoSignal) continue;
    Console.WriteLine($"Attention: {data.Attention}");
}

// RawEEG-only session
await sdk.SendCommandAsync(NeuroSkyCommand.StopESense);
await sdk.SendCommandAsync(NeuroSkyCommand.StartRawEeg);
await foreach (var data in sdk.DataStream(ct))
{
    if (data.RawEeg.Count > 0)
        foreach (var sample in data.RawEeg) ProcessRawSample(sample);
}

// eSense + RawEEG simultaneously — process only the populated fields in each packet
await sdk.SendCommandAsync(NeuroSkyCommand.StartRawEeg);  // eSense is active by default
await foreach (var data in sdk.DataStream(ct))
{
    if (data.RawEeg.Count > 0)  UpdateRawEegChart(data.RawEeg);
    if (data.Attention > 0)     UpdateEsenseUI(data);
}

Commands

// Notch filter — removes power-line noise (call after connecting)
await sdk.SendCommandAsync(NeuroSkyCommand.Notch60Hz);  // Korea/USA (60Hz)
await sdk.SendCommandAsync(NeuroSkyCommand.Notch50Hz);  // China/Europe (50Hz)

// Raw EEG stream (disabled by default)
await sdk.SendCommandAsync(NeuroSkyCommand.StartRawEeg);
await sdk.SendCommandAsync(NeuroSkyCommand.StopRawEeg);

Transport

Project Structure

NeuroSky.Sdk/
├── NeuroSkySdk.cs              Entry point (BLE by default)
├── NeuroSkyUuid.cs             BLE UUID constants, command byte constants
├── Model/
│   └── BrainWaveData.cs        EEG data model
├── Transport/
│   ├── ITransport.cs           Common interface, ConnectionState enum
│   ├── BleTransport.cs         WinRT BLE GATT implementation
│   └── BtClassicTransport.cs   WinRT RFCOMM SPP implementation
├── Parser/
│   └── ThinkGearParser.cs      ThinkGear packet parser
└── Simulator/
    └── SimulatorTransport.cs   Simulator for development

NeuroSky.Sample/
└── Program.cs                  Console sample app

Trimming / Self-contained / AOT

The package is marked IsTrimmable=true and ships an internal TrimmerRootDescriptor.xml that preserves the BLE/BT transports, parser, and public API surface. WinRT GATT callbacks are dispatched by the Windows Bluetooth stack via reflection-like mechanisms, so without these roots the trimmer would silently strip the handlers and BLE data would never arrive.

No consumer action is required — publishing with PublishTrimmed=true, self-contained, or PublishAot=true works out of the box.

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <SelfContained>true</SelfContained>
</PropertyGroup>

Build

dotnet build
dotnet run --project NeuroSky.Sample

Changelog

v2.0.3

• Fix: TrimmerRootDescriptor.xml updated to flattened NeuroSky.Sdk FQNs — previous entries still referenced the pre-v2.0.1 nested namespaces (NeuroSky.Sdk.Transport.*, NeuroSky.Sdk.Parser.*, NeuroSky.Sdk.Model.*), so the trimmer silently dropped BLE/BT/parser types in trimmed / AOT builds despite the descriptor being shipped
• Fix: BleTransport.ConnectAsync no longer reports Connected when the handshake characteristic is missing — it now transitions to Error so the caller doesn't wait forever on a stream that will never emit

v2.0.2

• ThinkGearParser — BT Classic default case now correctly skips extended codes (>= 0x80) by reading len and skipping len bytes; previously caused parser desync
• ThinkGearParser — BT Classic case 0x83 bounds guard: prevents IndexOutOfRangeException on truncated payloads

v2.0.1

• Fix: all types flattened into NeuroSky.Sdk — using NeuroSky.Sdk; is now sufficient

v2.0.0

• WinRT BLE GATT implementation (Windows.Devices.Bluetooth)
• WinRT RFCOMM SPP implementation (Windows.Devices.Bluetooth.Rfcomm)
• TransportMode enum: Ble (default), BtClassic
• IAsyncEnumerable<BrainWaveData> stream API
• Simulator modes: Random / Focused / Relaxed / PoorSignal
• .NET 8, C# 12
• Published to NuGet.org

License

Apache License 2.0