bc-ecap-sdk 0.5.0

No project description provided

BrainCo 32ch-EEG SDK

Python SDK for BrainCo 32-channel EEG Cap, providing easy-to-use APIs for real-time EEG data acquisition, processing, and visualization.

Features

• 🧠 32-Channel EEG Data Acquisition - Real-time streaming from BrainCo EEG Cap
• 📊 Signal Processing - Built-in filters (notch, bandpass, bandstop)
• 📈 Data Visualization - Ready-to-use GUI tools for real-time and offline analysis
• 💾 EDF Recording - Save data in standard EDF+ format
• 🔌 Easy Integration - Simple async API with device auto-discovery
• 🎯 SSVEP Support - Pre-configured channel selections for SSVEP experiments

Installation

pip install bc-ecap-sdk

Optional Dependencies

For GUI visualization tools:

pip install pyqtgraph PySide6 numpy scipy qasync pyedflib

Quick Start

Basic Usage

import asyncio
import bc_ecap_sdk as sdk

async def main():
    # Auto-discover and connect to device
    devices = await sdk.scan_devices()
    addr, port = devices[0]
    
    # Create client
    client = sdk.ECapClient(addr, port)
    parser = sdk.MessageParser("eeg-cap", sdk.MsgType.EEGCap)
    
    try:
        # Recommended: One-key unified stream startup
        await client.start_stream(
            parser,
            fs=sdk.EegSampleRate.SR_250Hz,
            gain=sdk.EegSignalGain.GAIN_6,
            signal=sdk.EegSignalSource.NORMAL
        )
        
        # Your processing code here...
        await asyncio.sleep(10)
        
    finally:
        # Safe TCP disconnect and background task release
        await client.disconnect_tcp()

asyncio.run(main())

EDF Recording

import bc_ecap_sdk as sdk

# Start recording
file_path = sdk.start_edf_recording(
    output_dir="./recordings",
    participant_code="P001",
    participant_sex="M",
    participant_birthdate="01-JAN-1990",
    participant_name="TestSubject"
)

# ... collect data ...

# Stop recording
sdk.stop_edf_recording()

Signal Filtering

# Create filters
notch_50hz = sdk.BandStopFilter(sample_rate=250, low_freq=49, high_freq=51)
notch_60hz = sdk.BandStopFilter(sample_rate=250, low_freq=59, high_freq=61)
bandpass = sdk.BandPassFilter(sample_rate=250, low_freq=2, high_freq=45)

# Apply filters
filtered_value = notch_50hz.apply(raw_value)
filtered_value = notch_60hz.apply(filtered_value)
filtered_value = bandpass.apply(filtered_value)

GUI Tools

The SDK includes two powerful visualization tools:

1. Real-time EEG Viewer

Real-time visualization of 32-channel EEG data with filtering and FFT analysis.

python -m bc_ecap_sdk.examples.eeg_32ch_realtime_gui

Features:

• Real-time 32-channel waveform display
• Time domain and frequency domain views
• Channel selection (All/SSVEP Wet/SSVEP Dry)
• Live filtering (50/60Hz notch + 2-45Hz bandpass)
• Statistics display (mean, std, peak-to-peak)

2. EDF File Viewer

Load and visualize EDF recordings with playback controls.

python -m bc_ecap_sdk.examples.eeg_32ch_edf_gui

Features:

• Load and replay EDF files
• Playback controls (play/pause/speed adjustment)
• Time and frequency domain analysis
• Channel selection and filtering
• Progress bar and statistics

Channel Layout

The SDK uses the standard 10-20 system with 32 channels:

FP1, FP2, F3, F4, F7, F8, Fz,
C3, C4, Cz,
P3, P4, P7, P8, Pz,
O1, O2,
T7, T8,
FC1, FC2, FC5, FC6,
CP1, CP2, CP5, CP6,
FT9, FT10,
TP9, TP10,
IO (reference)

SSVEP Channel Presets

Wet Electrodes (7 channels):

• O1, O2 (occipital)
• P3, P4 (parietal)
• P7, P8 (temporal-parietal)
• Pz (midline)

Dry Electrodes (7 channels):

• O1 (occipital)
• P3, P4 (parietal)
• C3, C4 (central)
• F3, F4 (frontal)

API Reference

Client

• ECapClient(addr, port) - Create TCP client
• start_stream(parser, fs, gain, signal) - One-key high-level stream startup (Recommended)
• update_eeg_config(fs, gain, signal) - On-the-fly config hot-reloading (Recommended)
• disconnect_tcp() - Safely release TCP connections and background listener tasks
• start_data_stream(parser) - Start data streaming (Advanced)
• set_eeg_config(sample_rate, gain, source) - Configure EEG (Advanced)
• start_eeg_stream() / stop_eeg_stream() - Control streaming (Advanced)
• get_device_info() - Get device information
• get_battery_level() - Get battery status

Filters

• BandPassFilter(sample_rate, low_freq, high_freq) - Bandpass filter
• BandStopFilter(sample_rate, low_freq, high_freq) - Bandstop/notch filter
• NotchFilter(center_freq, sample_rate, q_factor) - Notch filter
• SosFilter.create_band_pass(order, sample_rate, low, high) - SOS bandpass

Recording

• start_edf_recording(...) - Start EDF recording
• stop_edf_recording() - Stop recording
• is_edf_recording() - Check recording status

Enums

• EegSampleRate: SR_250Hz, SR_500Hz, SR_1000Hz
• EegSignalGain: GAIN_1, GAIN_2, GAIN_4, GAIN_6, GAIN_8, GAIN_12
• EegSignalSource: NORMAL, TEST_SIGNAL

Examples

Check the GitHub repository for more examples:

• Real-time data streaming
• EDF recording with LSL markers
• Signal processing and filtering
• FFT analysis
• Custom data callbacks

Requirements

• Python 3.10+
• Network connection to BrainCo EEG Cap device
• Optional: GUI dependencies for visualization tools

License

See LICENSE file in the repository.