EEG + BLE 集成

如果你想在一个地方看到完整的浏览器 EEG 流程，请阅读本指南。你将初始化 EEG WASM 层、通过 Web Bluetooth 连接、输出数据帧，并把这些帧转化为应用可用的指标。

本指南涵盖的内容

本指南展示如何把 @elata-biosciences/eeg-web 和 @elata-biosciences/eeg-web-ble 组合成一个完整的浏览器流程。完成后，你将能够：

初始化 EEG WASM 运行时
在浏览器中连接 Muse 兼容头带
接收规范化的 HeadbandFrameV1 帧
从传入的 EEG 样本实时计算频段功率
干净地停止并从断开中恢复

开始之前

你需要：

@elata-biosciences/eeg-web
@elata-biosciences/eeg-web-ble
支持 Web Bluetooth 的 Chrome 或 Edge
https:// 或 localhost
Muse 2 或 Muse S 头带

Safari 和 iOS 不支持此浏览器 BLE 流程。对于这些平台，请使用原生 BLE 外壳、桥接应用或其他传输层，并继续以 @elata-biosciences/eeg-web 作为处理边界。

选择合适的起点

从可运行的演示开始

如果想以最快速度获得参考应用，请创建 EEG BLE 演示。

EEG Web 快速上手

在添加设备传输之前，先了解浏览器 EEG 处理包。

EEG Web BLE 快速上手

查看传输包、生命周期方法和平台限制。

实时数据流教程

如果想先看教程再看这份端到端指南，请按分步版本操作。

安装包

PNPM
新项目管理

pnpm add @elata-biosciences/eeg-web @elata-biosciences/eeg-web-ble

npm install @elata-biosciences/eeg-web @elata-biosciences/eeg-web-ble

@elata-biosciences/eeg-web-ble 依赖 @elata-biosciences/eeg-web 提供的共享帧类型和 EEG WASM 层。

集成流程

初始化 EEG WASM

在创建传输或调用分析函数之前，先初始化 EEG WASM 模块。

import { initEegWasm } from "@elata-biosciences/eeg-web";

await initEegWasm();

创建 BLE 传输

预先加入 Athena 解码器，这样经典版和兼容 Athena 的头带都能通过同一套设置工作。

import { AthenaWasmDecoder } from "@elata-biosciences/eeg-web";
import { BleTransport } from "@elata-biosciences/eeg-web-ble";

const transport = new BleTransport({
  sourceName: "my-app",
  deviceOptions: {
    athenaDecoderFactory: () => new AthenaWasmDecoder(),
    logger: (msg) => console.debug("[BLE]", msg),
  },
});

订阅传输状态和数据帧

使用 onStatus 更新界面状态，使用 onFrame 处理 EEG 数据。

import type { HeadbandFrameV1 } from "@elata-biosciences/eeg-web";

transport.onStatus = (status) => {
  const el = document.getElementById("status");
  if (el) el.textContent = status.state;
};

transport.onFrame = (frame: HeadbandFrameV1) => {
  console.log("channels", frame.eeg.channelNames);
  console.log("rows", frame.eeg.samples.length);
};

通过用户操作连接并开始数据流

浏览器 BLE 流程通常需要点击或其他用户手势才能打开设备选择器。

async function connectHeadband() {
  try {
    await transport.connect();
    await transport.start();
  } catch (err) {
    console.error("Connection failed:", err);
  }
}

在较简单的应用流程中，startStreaming() 通常是最安全的默认选择，因为它在一次调用中合并了 connect() 和 start()。

将传入的帧转化为指标

在帧到达时按通道计算频段功率。

import { band_powers } from "@elata-biosciences/eeg-web";

transport.onFrame = (frame: HeadbandFrameV1) => {
  const { eeg } = frame;

  for (let ch = 0; ch < eeg.channelCount; ch++) {
    const channelSamples = eeg.samples.map((row) => row[ch]);
    const powers = band_powers(
      new Float32Array(channelSamples),
      eeg.sampleRateHz,
    );

    console.log(
      `${eeg.channelNames[ch]}: alpha=${powers.alpha.toFixed(2)} beta=${powers.beta.toFixed(2)}`,
    );
  }
};

完整示例

import {
  initEegWasm,
  band_powers,
  AthenaWasmDecoder,
} from "@elata-biosciences/eeg-web";
import type { HeadbandFrameV1 } from "@elata-biosciences/eeg-web";
import { BleTransport } from "@elata-biosciences/eeg-web-ble";

await initEegWasm();

const transport = new BleTransport({
  sourceName: "my-app",
  deviceOptions: {
    athenaDecoderFactory: () => new AthenaWasmDecoder(),
    logger: (msg) => console.debug("[BLE]", msg),
  },
});

transport.onStatus = (status) => {
  const el = document.getElementById("status");
  if (el) el.textContent = status.state;
};

transport.onFrame = (frame: HeadbandFrameV1) => {
  const { eeg } = frame;

  for (let ch = 0; ch < eeg.channelCount; ch++) {
    const channelSamples = eeg.samples.map((row) => row[ch]);
    const powers = band_powers(
      new Float32Array(channelSamples),
      eeg.sampleRateHz,
    );

    console.log(
      `${eeg.channelNames[ch]}: alpha=${powers.alpha.toFixed(2)} beta=${powers.beta.toFixed(2)}`,
    );
  }
};

try {
  await transport.connect();
  await transport.start();
} catch (err) {
  console.error("Connection failed:", err);
}

干净地关闭

当用户离开视图或关闭页面时，停止数据流并释放蓝牙会话。

async function shutdown() {
  await transport.stop();
  await transport.disconnect();
}

window.addEventListener("beforeunload", shutdown);

处理重连

如果断开是可恢复的，尝试重新连接并重启数据流。

transport.onStatus = (status) => {
  if (status.state === "disconnected" && status.recoverable) {
    console.log("Attempting reconnect...");

    setTimeout(async () => {
      try {
        await transport.connect();
        await transport.start();
      } catch (error) {
        console.error("Reconnect failed:", error);
      }
    }, 2000);
  }
};

了解传输生命周期

方法	作用
`startStreaming()`	一次调用完成连接并开始数据流
`connect()`	打开蓝牙选择器并准备会话
`start()`	开始 EEG 数据流并触发 `onFrame`
`stop()`	停止数据流，但保持蓝牙会话打开
`disconnect()`	释放蓝牙会话

设备说明

经典版 Muse
Athena 固件

使用标准的浏览器 BLE 流程即可。

创建传输时使用 athenaDecoderFactory。Athena 设备提供更丰富的帧内容，包括 8 路 EEG 通道和额外的传感器数据。

连接后还可以检查元数据：

await transport.connect();

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

如果你要在不同 Muse 型号之间测试，请从第一天起就启用 Athena 解码器工厂，这样以后就不需要单独的传输设置。

架构一览

浏览器 EEG BLE 流程通常如下：

初始化 @elata-biosciences/eeg-web
创建 BleTransport
通过用户手势连接
接收 HeadbandFrameV1 帧
计算频段功率、分数或状态转换等应用指标
在应用中渲染图表、分数或自适应界面

集成建议

在分析前对帧进行缓冲，以获得更稳定的结果
调用 band_powers 时使用 Float32Array
将 BLE 连接逻辑放在明确的用户操作之后
把帧处理放到应用状态中，而不是停留在 console.log
如果需要可运行的参考项目，先从演示应用开始
开发时如果没有头带，先用合成数据测试

band_powers 在大约 1 到 2 秒的数据上最有用。在 256 Hz 下，大约是 256 到 512 个样本。

下一步

Muse 设备详情

查看设备行为、协议细节和兼容性说明。

EEG Web BLE 快速上手

更详细地了解传输包 API 和平台注意事项。

通过 Web Bluetooth 输出 EEG 数据

按照面向应用步骤的教程版本完成此流程。

在现有浏览器应用中添加 EEG

在添加 BLE 传输之前，先将浏览器 EEG 处理集成到应用中。

头带传输

了解 EEG 流程使用的帧结构和传输边界。

rPPG 摄像头集成

需要多模态生物特征时，将此 EEG 流程与浏览器摄像头流水线结合使用。

概览

EEG Web SDK

EEG BLE Web SDK

摄像头 Web SDK

PPG Web SDK

会话与分析

操作与维护

贡献者

本指南涵盖的内容

开始之前

选择合适的起点

从可运行的演示开始

EEG Web 快速上手

EEG Web BLE 快速上手

实时数据流教程

安装包

集成流程

完整示例

干净地关闭

处理重连

了解传输生命周期

设备说明

架构一览

集成建议

下一步

Muse 设备详情

EEG Web BLE 快速上手

通过 Web Bluetooth 输出 EEG 数据

在现有浏览器应用中添加 EEG

头带传输

rPPG 摄像头集成

​本指南涵盖的内容

​开始之前

​选择合适的起点

从可运行的演示开始

EEG Web 快速上手

EEG Web BLE 快速上手

实时数据流教程

​安装包

​集成流程

​完整示例

​干净地关闭

​处理重连

​了解传输生命周期

​设备说明

​架构一览

​集成建议

​下一步

Muse 设备详情

EEG Web BLE 快速上手

通过 Web Bluetooth 输出 EEG 数据

在现有浏览器应用中添加 EEG

头带传输

rPPG 摄像头集成

本指南涵盖的内容

开始之前

选择合适的起点

安装包

集成流程

完整示例

干净地关闭

处理重连

了解传输生命周期

设备说明

架构一览

集成建议

下一步