> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elata.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Connect to EEG headband devices over Web Bluetooth

## When To Use This Package

Use `@elata-biosciences/eeg-web-ble` when your app needs:

* browser-side discovery of Muse-compatible devices
* live EEG streaming over Web Bluetooth
* normalized headband frames for app logic or downstream analysis

Install it alongside `@elata-biosciences/eeg-web`.

***

## Installation

```bash theme={null}
pnpm add @elata-biosciences/eeg-web-ble @elata-biosciences/eeg-web
```

`eeg-web-ble` depends on `eeg-web` for shared frame types and the WASM module.

***

## Requirements

* Browser with **Web Bluetooth** support (Chrome/Edge on desktop or Android)
* Served from a **secure context** (`https://` or `localhost`)
* Safari/iOS does **not** support Web Bluetooth. See [platform notes](/sdk/overview) for alternatives

***

## Basic Usage

`startStreaming()` is the recommended default. It wraps `connect()` and `start()` together and avoids the common mistake of connecting successfully but never beginning to stream.

```typescript theme={null}
import { initEegWasm, AthenaWasmDecoder } from "@elata-biosciences/eeg-web";
import { BleTransport } from "@elata-biosciences/eeg-web-ble";

// Initialize WASM first
await initEegWasm();

// Create transport
const transport = new BleTransport({
  deviceOptions: {
    athenaDecoderFactory: () => new AthenaWasmDecoder(),
  },
});

// Handle incoming EEG frames
transport.onFrame = (frame) => {
  console.log(`EEG samples: ${frame.eeg.samples.length} rows`);
  console.log(`Channels: ${frame.eeg.channelNames.join(", ")}`);
};

// Handle connection status changes
transport.onStatus = (status) => {
  console.log(`Transport: ${status.state}`, status.reason || "");
};

// Connect and start streaming (triggers Bluetooth device picker)
await transport.startStreaming();

// ... later
await transport.stop();
```

***

## BleTransport Lifecycle

| Method             | What it does                                               |
| ------------------ | ---------------------------------------------------------- |
| `startStreaming()` | Recommended: connects and starts the stream in one call    |
| `connect()`        | Opens Bluetooth device picker, pairs, and prepares session |
| `start()`          | Begins EEG data stream; `onFrame` callbacks fire           |
| `stop()`           | Stops the data stream; connection stays open               |
| `disconnect()`     | Releases the Bluetooth session                             |

***

## BleTransportOptions

```typescript theme={null}
const transport = new BleTransport({
  sourceName: "my-app-ble",           // name tag in frame.source
  deviceOptions: {
    athenaDecoderFactory: () => new AthenaWasmDecoder(),  // for Athena headbands
    logger: (msg) => console.debug(msg),
    onDisconnected: () => console.warn("Device disconnected"),
  },
});
```

| Option          | Type                | Description                                     |
| --------------- | ------------------- | ----------------------------------------------- |
| `sourceName`    | `string`            | Identifier included in `HeadbandFrameV1.source` |
| `deviceOptions` | `MuseDeviceOptions` | Passed to underlying `MuseBleDevice`            |
| `device`        | `BleDeviceLike`     | Inject a custom device implementation           |

***

## Athena Support

Muse S headbands with Athena firmware require an Athena decoder factory. Include it up front to keep both classic and Athena flows covered:

```typescript theme={null}
import { AthenaWasmDecoder } from "@elata-biosciences/eeg-web";
import { BleTransport } from "@elata-biosciences/eeg-web-ble";

const transport = new BleTransport({
  deviceOptions: {
    athenaDecoderFactory: () => new AthenaWasmDecoder(),
  },
});
```

Athena headbands provide 8 EEG channels, optics, accelerometer/gyroscope, and battery data in each frame.

***

## Device Info

After connecting, you can query device metadata:

```typescript theme={null}
await transport.connect();

const isAthena = transport.getIsAthena();
const boardInfo = transport.getBoardInfo();
const channelNames = transport.getEegNames();
```

***

## Platform Caveats

* Safari and iOS do not provide usable Web Bluetooth support for this workflow.
* For Safari and iOS, use a native BLE shell, companion bridge, or hybrid WebView strategy with `@elata-biosciences/eeg-web` frame contracts as the boundary.
* Firmware variants may differ in command behavior.

***

## Next

<CardGroup cols={2}>
  <Card title="Live Stream Tutorial" icon="circle-play" iconType="light" href="/sdk/tutorials/eeg-ble-live-stream">
    Step-by-step BLE streaming guide
  </Card>

  <Card title="Muse Device Details" icon="microchip" iconType="light" href="/sdk/eeg-web-ble/muse-device">
    Protocol details, characteristics, and compatibility
  </Card>

  <Card title="EEG + BLE Integration" icon="link" iconType="light" href="/sdk/guides/eeg-ble-integration">
    End-to-end streaming and processing guide
  </Card>
</CardGroup>