Skip to main content

eeg data acquisition tutorial

This tutorial will guide you through the process of configuring, starting, and working with EEG data streams using the Instinct API. You'll learn how to set up streaming parameters, create a Stream pipeline with EEG data, and record the data for later analysis.

prerequisites​

Before you begin, ensure:

  • Your Instinct EEG headset is properly connected
  • The API service is running at http://localhost:42069
  • You have a tool to make HTTP requests (cURL, Postman, or any programming language with HTTP capabilities)
  • The headset is properly placed on the subject's head

step 1: check headset status​

First, let's verify that the headset is connected and ready:

curl -X GET http://localhost:42069/system/hostname

You should receive a response like:

{
  "name": "instinct-headset-01"
}

Before streaming, it's a good practice to check electrode impedances to ensure good signal quality:

curl -X GET http://localhost:42069/system/sensors/impedance?channels=CMS&channels=DRL

Response:

{
  "CMS": 107391312,
  "DRL": 107390736
}

step 3: create an eeg stream with recording​

To acquire and record EEG data, we'll create a stream with multiple nodes:

  1. An EEG source node that connects to the headset
  2. A filter node for basic signal processing
  3. A recorder node to save the data
  4. A WebSocket node for real-time monitoring
curl -X POST http://localhost:42069/stream/streams \
  -H "Content-Type: application/json" \
  -d '{
    "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
    "meta": {
      "name": "EEG Recording Stream",
      "description": "Acquisition and recording of EEG data"
    },
    "nodes": [
      {
        "id": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
        "type": "EXECUTABLE",
        "meta": {
          "type": "SOURCE"
        },
        "executable": "/usr/share/instinct/eeg-source",
        "config": {
          "channels": ["Fp1", "Fp2", "F7", "F3", "Fz", "F4", "F8", "T3", "C3", "Cz", "C4", "T4", "T5", "P3", "Pz", "P4", "T6", "O1", "O2"],
          "sampleRate": 250,
          "gain": 24
        }
      },
      {
        "id": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292",
        "type": "EXECUTABLE",
        "meta": {
          "type": "FILTER"
        },
        "executable": "/usr/share/instinct/signal-filter",
        "config": {
          "highpass": 0.5,
          "lowpass": 50,
          "notch": 60,
          "order": 4
        }
      },
      {
        "id": "a27463d5-ccba-4581-95d1-68426c210e55",
        "type": "EXECUTABLE",
        "meta": {
          "type": "RECORDER"
        },
        "executable": "/usr/share/instinct/csv-recorder",
        "config": {
          "filename": "/data/recordings/session-001.csv",
          "includeTimestamps": true,
          "format": "csv",
          "metadata": {
            "subjectId": "subject-001",
            "sessionId": "session-001",
            "condition": "resting-state",
            "notes": "Initial baseline recording"
          }
        }
      },
      {
        "id": "eac48e37-fdf9-4bb4-a2ba-b938fc1a781c",
        "type": "EXECUTABLE",
        "meta": {
          "type": "OUTPUT"
        },
        "executable": "/usr/share/instinct/websocket-output",
        "config": {
          "port": 36006
        }
      }
    ],
    "pipes": [
      {
        "id": "e93b59c0-4dbf-48c5-9db8-19a312fd4aed",
        "source": "5c3a1d8b-c2f6-4c8a-bcf3-1af7e51b1e06",
        "destination": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292"
      },
      {
        "id": "c68f741b-1b9e-4f82-b77c-ce14d3d29831",
        "source": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292",
        "destination": "a27463d5-ccba-4581-95d1-68426c210e55"
      },
      {
        "id": "b72e9a84-f8c3-42d6-bf85-a15c4f249fdb",
        "source": "9fb2e8d4-57a0-4e5c-a5b1-84b8f43c3292",
        "destination": "eac48e37-fdf9-4bb4-a2ba-b938fc1a781c"
      }
    ]
  }'

If successful, you'll receive a response with the stream ID:

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "success": true
}

step 4: start the stream​

Now that we've created our stream, let's start it to begin data acquisition and recording:

curl -X POST http://localhost:42069/stream/streams/7348dd95-7835-4a8a-9ec5-2e4cee1e72e2/signal \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'signal=start'

You should receive a confirmation:

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "success": true
}

step 5: connect to the websocket stream​

To receive real-time EEG data, you can connect to the WebSocket port specified in the stream configuration. Here's an example using JavaScript:

// Example code for a web application
const socket = new WebSocket('ws://localhost:36006');

socket.onopen = function (e) {
  console.log('Connection established');
};

socket.onmessage = function (event) {
  const eegData = JSON.parse(event.data);
  console.log(`Timestamp: ${eegData.timestamp}`);
  console.log(`Channels: ${eegData.channels}`);
  console.log(`Data: ${eegData.data}`);

  // Process the EEG data...
};

socket.onclose = function (event) {
  if (event.wasClean) {
    console.log(
      `Connection closed cleanly, code=${event.code} reason=${event.reason}`
    );
  } else {
    console.log('Connection died');
  }
};

socket.onerror = function (error) {
  console.log(`Error: ${error.message}`);
};

step 6: stop the stream​

When you're finished with the recording session, you can stop the stream:

curl -X POST http://localhost:42069/stream/streams/7348dd95-7835-4a8a-9ec5-2e4cee1e72e2/signal \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'signal=stop'

You should receive a confirmation:

{
  "id": "7348dd95-7835-4a8a-9ec5-2e4cee1e72e2",
  "success": true
}

next steps​

Now that you know how to acquire and record EEG data, you can:

  • Integrate the streaming into your application
  • Analyze the recorded data offline
  • Create more complex processing pipelines
  • Experiment with different signal processing algorithms

For more advanced features, see: