Flutter

🚀 准备工作

硬件连接指引

有关头环设备的开关机操作、状态指示灯含义及各端 SDK 的设备配对说明，请在开发前优先查阅：设备使用说明与常见问题 (FAQ)。

编译环境要求

Flutter 版本的系统兼容性矩阵如下，开发时请确认平台及编译器满足要求：

• 基础框架：Dart 3.0+ 及 Flutter 3.19.0+
• 移动端部署目标：Android 6.0+ (API 23+) 及 iOS 12.0+
• PC 端部署目标：macOS 10.15+ 及 Windows 10 build 10.0.15063+
• 底层硬件限制：设备需至少支持 BLE 5.0

安装和集成

配置私服依赖

OxyZen 仓库托管于 BrainCo 内部组件系统，您需要预先配置 Token 授权拉取：

1. 浏览器访问：BrainCo Dart Pub。
2. 登录平台（账号：<gitlab-username>，密码：<gitlab-password>）。
3. 点击平台右上方 Copy Token 获取授权令牌。
4. 在本地终端注入环境变量配置身份：

dart pub token add https://dart-pub.brainco.cn --env-var TOKEN_PUB

引入依赖清单

并在项目下的 pubspec.yaml 中补充对库依赖及数据源宿主配置：

dependencies:
  liboxyz:
    version: ^1.29.0
    hosted:
      name: liboxyz
      url: https://dart-pub.brainco.cn

执行配置下载并刷新：flutter pub get。

动态权限声明

请确保在应用中请求必要的系统蓝牙等权限（需在对应的 Android/iOS 配置文件中添加权限声明，以防应用崩溃）：

// 需要引用 permission_handler 插件辅助
final deviceInfoPlugin = DeviceInfoPlugin();
if (Platform.isAndroid) {
  final androidInfo = await deviceInfoPlugin.androidInfo;
  if (androidInfo.version.sdkInt >= 31) {
    // Android 12 及以上采用独立的周边蓝牙设备权限
    await [Permission.bluetoothScan, Permission.bluetoothConnect].request();
  } else {
    // 低版本使用基础位置权限替代感知
    await [Permission.locationWhenInUse].request();
  }
} else if (Platform.isIOS || Platform.isWindows) {
  await [Permission.bluetooth].request();
}

API 核心组件参考

BciDeviceManager (初始化与管理)

启动应用前，需完成 SDK 初始化并注册需要接收的数据：

import 'package:liboxyz/liboxyz.dart';

// 1. 初始化终端日志追踪
await AppLogger.init(level: Level.INFO);

// 注册对应的设备协议插件（如 Zenlite）
await BciDevicePluginRegistry.init({
  ZenlitePluginRegistry(),
});

// 配置需要订阅的算法指标（按需订阅以节省性能）
BciDeviceConfig.setAvailableModes({
  BciDeviceDataMode.attention,    // 订阅注意力指标
  BciDeviceDataMode.meditation,   // 订阅冥想度指标
  BciDeviceDataMode.eeg,          // 订阅 EEG 原始数据（可选）
  BciDeviceDataMode.ppg,          // 订阅 PPG 数据（可选）
});

// 4. 初始化 SDK
await BciDeviceManager.init();

// 解绑设备
await BciDeviceManager.unbind();

BleScanner (Class)

蓝牙扫描服务：

// 开始扫描蓝牙设备
await BleScanner.instance.startScan();

// 监听扫描到的设备列表
BleScanner.instance.onFoundDevices

// 停止扫描（页面卸载时务必调用以节省电量）
await BleScanner.instance.stopScan();

// 绑定指定的设备
await BciDeviceManager.bindScanResult(result);

OxyZenDevice (Class) 与 BciDeviceProxy 实例代理

用于发送系统和设备控制指令，并接收数据流回调。

// 获取绑定的硬件实例：
final device = BciDeviceManager.bondDevice as OxyZenDevice;

// EEG 数据采集控制
await device.startEEG();
await device.stopEEG();

// IMU 数据采集控制
await device.startIMU();
await device.stopIMU();

// PPG 数据采集控制
await device.startPPG();
await device.stopPPG();

// ---- 系统硬件参数设置指令 ----
await device.rename('NewDeviceName');            // 修改默认广播名
await device.setSleepIdleSeconds(30 * 60);       // 设置设备闲置自动关机时间（秒）
device.disableOrientationCheck = true;           // 禁用佩戴翻转检测

// ---- 固件升级 (OTA / DFU) ----
await OxyZenDfu.checkNewFirmware(force: true);   // 检查固件更新
final ret = device.startDfu(zipFilePath);        // 通过本地 zip 固件包升级

设备属性与数据流回调 (BciDeviceProxy / OxyZenDevice 共有模型)：

// ===== 读取只读属性/配置 =====
BciDeviceProxy.instance.id                 // 设备 UUID
BciDeviceProxy.instance.name               // 设备蓝牙名称
BciDeviceProxy.instance.state              // 当前连接状态 (enum)
BciDeviceProxy.instance.batteryLevel       // 设备电量百分比

// ===== 事件与数据回调流 (Streams) =====
// --- 系统及状态流 ---
device.onConnectivityChanged               // 连接状态变化回调
device.onDeviceInfo                        // 设备基本信息
device.onDeviceEvent                       // 设备硬件事件通知（如唤醒等）
device.onOrientationChanged                // 设备佩戴方向变化
device.onContactStateChanged               // 佩戴接触状态变化

// --- 传感器基础数据流 ---
device.onEEGData                           // 滤波后的 EEG 数据
device.onRawEEGData                        // 未滤波的原始 EEG 数据
device.onImuData                           // IMU 传感器模块数据
device.onPPGData                           // PPG 算法数据（含心率、血氧）
device.onRawPPGData                        // PPG 原始光学探测数据

// --- 算法指标结果反馈 ---
device.onMeditation                        // 冥想度
device.onCalmness                          // 平静度
device.onAwareness                         // 觉知度
device.onAttention                         // 注意力指数
device.onDrowsiness                        // 疲劳度
device.onSleepStage                        // 睡眠分期

核心数据模型参考

（此处仅列出核心的数据模型与枚举属性：）

状态与设备信息

// 蓝牙连接状态
enum BciDeviceConnectivity { disconnected, connecting, connected, disconnecting }

// 皮肤接触状态
enum BciDeviceContactState { unknown, contact, noContact }

// 佩戴方向状态
enum BciDeviceOrientation { unknown, normal, upsideDown }

// 设备事件枚举
enum BciDeviceEvent { powerOn, powerOff, leadOn, leadOff, enterPairing, inPairing, receiveDataTimeout, rename }

// 设备基本信息
class BciDeviceInfo {
  String sn;
  String firmwareVersion;
}

业务与状态机枚举

// 睡眠分期
enum SleepStage { unknown, wake, rem, light, deep }

// 设备状态机 (BciDeviceState)
enum BciDeviceState {
  disconnected,         // 断开
  connecting,           // 连接中
  connected,            // 已连接
  contacting,           // 接触检测中
  contactUpsideDown,    // 佩戴方向错误
  contacted,            // 接触良好
  analyzed              // 正在分析算法数据
}

传感器数据模型（EEG/IMU/PPG）

class EEGModel {
  final int seqNum;
  final List<double> eeg;
}

class ImuModel {
  final int seqNum;
  final AccData acc;            // 加速度数据
  final GyroData? gyro;         // 陀螺仪数据
  final EulerAngle? eulerAngle; // 欧拉角数据
}

class PpgModel {
  final int seqNum;
  final double reportRate;
  final List<PpgRawData> rawData;   // 原始 PPG 光学数据
  final List<PpgAlgoData> algoData; // 算法指标结果
}

// PPG 算法指标
class PpgAlgoData {
  final double hr;        // 心率 (bpm)
  final int hrConf;       // 心率置信度 (0-100%)
  final double spo2;      // 血氧饱和度
  final int spo2Conf;     // 血氧置信度 (0-100%)
  final SpO2State spo2State;
  final PpgContactState ppgContactState;
}

故障排查与注意事项

常见连接与配对问题

若出现“无法扫描到设备”、“连接失败”或“配对失败”等通用蓝牙排障场景，请优先参考全局指南： 👉 设备使用说明与常见问题 (FAQ)

Flutter 平台开发注意事项

• 插件版本冲突：若遇到 PermissionHandler 等权限插件的版本冲突，请谨慎降级，因为 Android 12+ 和 iOS 对蓝牙权限的审核更为严格，降级可能导致运行时崩溃或上架被拒绝。
• Android 后台连接保活：当 App 切入后台后，蓝牙数据流可能被系统挂起。若业务需要后台长时间采集，需在原生端配置前台服务（Foreground Service）并绑定常驻通知栏。

📖 完整集成示例

以上 API 参考涵盖了 SDK 核心组件的功能定义。我们提供了一套完整的开源示例工程，演示了多传感器数据融合、状态管理与跨平台权限处理等实际集成场景：

👉 OxyZen Flutter 示例工程