Metadata-Version: 2.4
Name: bc_ecap_sdk
Version: 0.4.2
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
License-File: LICENSE
Summary: BrainCo FW proto message SDK
Author: BrainCo
License: 	
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source Code, https://github.com/BrainCoTech/bc_ecap_sdk

# 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

```bash
pip install bc-ecap-sdk
```

### Optional Dependencies

For GUI visualization tools:

```bash
pip install pyqtgraph PySide6 numpy scipy qasync pyedflib
```

## Quick Start

### Basic Usage

```python
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)
    await client.start_data_stream(parser)
    
    # Configure EEG
    await client.set_eeg_config(
        sdk.EegSampleRate.SR_250Hz,
        sdk.EegSignalGain.GAIN_6,
        sdk.EegSignalSource.NORMAL
    )
    
    # Start streaming
    await client.start_eeg_stream()
    
    # Your processing code here...
    await asyncio.sleep(10)
    
    # Stop and disconnect
    await client.stop_eeg_stream()
    client.disconnect_tcp_blocking()

asyncio.run(main())
```

### EDF Recording

```python
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

```python
# 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.

```bash
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.

```bash
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_data_stream(parser)` - Start data streaming
- `set_eeg_config(sample_rate, gain, source)` - Configure EEG
- `start_eeg_stream()` / `stop_eeg_stream()` - Control streaming
- `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](https://github.com/BrainCoTech/eeg-32ch-example) for more examples:

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

## Requirements

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

## License

See LICENSE file in the repository.

