OxyZen-SDK

简体中文

English

简体中文

English

Appearance

C# ​

🚀 准备工作 ​

硬件连接指引 ​

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

编译环境要求 ​

  • 操作系统：Windows 10 build 10.0.15063 或更高版本。
  • 软件环境：Visual Studio 2019 及以上版本。
  • 开发框架：推荐使用 .NET Framework 4.7.2+ 或 .NET Core 3.1+ 架构。

Windows 宿主环境调试提示

Windows 环境由于内置蓝牙适配器碎片化严重，要求网卡的 LMP（Link Manager Protocol）必须为 11.x（蓝牙 5.2）或更高版本，否则将导致无法拉起扫描连接或频繁重连中断。 如您当前的系统内置网卡不支持该版本要求，必须购置并使用外接 USB 蓝牙 5.0/5.2 适配器，具体驱动配置排障与推荐请参考：Windows 使用指南。

安装和集成 ​

OxyZen 仓库中提供了可以直接使用的 C# SDK 封装与 NuGet 组件，无需手动处理 C++ 导出库。

集成步骤：

  1. 导入 SDK 封装项目与原生 .dll 依赖文件。
  2. 通过 Visual Studio 的 NuGet 包管理器执行还原操作。
  3. 确保平台目标设置为 x64（不要选择 AnyCPU），否则将因架构不匹配而无法加载原生库。

API 核心组件参考 ​

BleAPI (Class) ​

负责在 Windows 平台发起 BLE 设备扫描与发现（代码中的 Zenlite 前缀为产品曾用名，保持向后兼容）：

csharp
public static class BleAPI
{
    // 开始扫描设备
    public static void StartScan(Action<ZenliteDevice> callback);
    
    // 停止扫描
    public static void StopScan();
}

ZenliteDevice (Class) ​

管理与单一 OxyZen 设备的通信生命周期：

csharp
public class ZenliteDevice
{
    // 设备属性
    public string Name { get; }
    public string Address { get; }
    public bool IsInPairingMode { get; }
    public BLEConnectivity Connectivity { get; }
    
    // 连接管理
    public void SetListener(DeviceManager listener);
    public void Connect();
    public void Disconnect();
    public void Pair(Action<ZenliteDevice, ZenliteError> callback);
    
    // 数据流控制
    public void StartEEGStream(EEGSampleRate sampleRate, Action<ZenliteDevice, ZenliteError> callback);
    public void StopEEGStream(Action<ZenliteDevice, ZenliteError> callback);
    
    public void StartIMUStream(IMUSampleRate sampleRate, IMUMode mode, Action<ZenliteDevice, ZenliteError> callback);
    public void StopIMUStream(Action<ZenliteDevice, ZenliteError> callback);
    
    public void StartPPGStream(PPGReportRate reportRate, PPGMode mode, Action<ZenliteDevice, ZenliteError> callback);
    public void StopPPGStream(Action<ZenliteDevice, ZenliteError> callback);
    
    // 设备设置
    public void SetDeviceName(string name, Action<ZenliteDevice, ZenliteError> callback);
    public void SetSleepIdleTime(int seconds, Action<ZenliteDevice, ZenliteError> callback);
    public void GetSysInfo(Action<ZenliteDevice, ZenliteError> callback);
}

DeviceManager (Class) ​

通过委托回调接收设备状态变化与传感器数据：

csharp
public class DeviceManager
{
    // 连接与设备状态
    public Action<ZenliteDevice, BLEConnectivity> OnConnectivityChanged;
    public Action<ZenliteDevice, BleDeviceInfo> OnDeviceInfo;
    public Action<ZenliteDevice, int> OnBatteryLevelChanged;
    public Action<ZenliteDevice, ContactState> OnContactStateChanged;
    public Action<ZenliteDevice, Orientation> OnOrientationChanged;
    
    // 传感器数据
    public Action<ZenliteDevice, EEGData> OnEEGData;
    public Action<ZenliteDevice, BrainWave> OnBrainWave;
    public Action<ZenliteDevice, IMUData> OnIMUData;
    public Action<ZenliteDevice, PPGData> OnPPGData;
    
    // 算法指标
    public Action<ZenliteDevice, float, float, float> OnMeditation;
    public Action<ZenliteDevice, SleepStage, float, float> OnSleep;
    public Action<ZenliteDevice, ZenliteError> OnError;
}

数据模型 ​

EEG 脑电波数据 ​

csharp
public struct EEGData
{
    public uint SequenceNumber;      // 序列号
    public float SampleRate;         // 采样率
    public float[] Data;             // EEG 数据，每组 30 个采样点
}

BrainWave 脑波频段指标 ​

csharp
public struct BrainWave
{
    public float Delta;              // Delta 波 (0.5-4 Hz)
    public float Theta;              // Theta 波 (4-8 Hz)
    public float Alpha;              // Alpha 波 (8-13 Hz)
    public float LowBeta;            // Low Beta 波 (13-17 Hz)
    public float HighBeta;           // High Beta 波 (17-30 Hz)
    public float Gamma;              // Gamma 波 (30-50 Hz)
}

IMU 惯性测量单元数据 ​

csharp
public struct IMUData
{
    public float[] AccData;         // 加速度计数据 [x, y, z]
    public float[] GyroData;        // 陀螺仪数据 [x, y, z]
    public float[] EulerAngleData;  // 欧拉角数据 [roll, pitch, yaw]
    public float SampleRate;        // 采样率
}

PPG 光电容积脉搏波数据 ​

csharp
public struct PPGData
{
    public uint SequenceNumber;      // 序列号
    public float SampleRate;         // 采样率
    public int[] RawData;            // 原始光学传感器数据
    public PPGAlgoData[] AlgoData;   // 算法指标结果
}

public struct PPGAlgoData
{
    public int HeartRate;            // 心率 (bpm)
    public int SpO2;                 // 血氧饱和度 (%)
}

枚举常量类 ​

连接状态 ​

csharp
public enum BLEConnectivity
{
    Connecting = 0,      // 连接中
    Connected = 1,       // 已连接
    Disconnecting = 2,   // 断开中
    Disconnected = 3     // 已断开
}

佩戴与接触状态 ​

csharp
public enum ContactState
{
    Unknown = 0,         // 未知
    Off = 1,             // 未正确佩戴
    EEG = 2,             // EEG 接触良好
    All = 3              // EEG 和 PPG 接触良好
}

public enum Orientation
{
    Unknown = 0,         // 未知
    Upward = 1,          // 设备佩戴正确
    Downward = 2         // 设备佩戴反了
}

故障排查与注意事项 ​

常见连接与配对问题 ​

若出现"无法扫描到设备"、"连接失败"或"配对失败"等通用蓝牙排障场景，请优先参考全局指南：

👉 设备使用说明与常见问题 (FAQ)

"类型初始值设定项异常" 或 DLL 缺失报错 ​

由于 Windows 平台编译环境差异较大（x86/x64/.NET Framework/Core），若 SDK 无法正确加载会抛出此类异常：

  • 重点排查 libzenlite.dll 与 C# 封装项目的架构是否一致。
  • 确保解决方案的构建配置已设置为 x64（严禁使用 AnyCPU，否则会因架构不匹配导致加载失败）。

Windows 平台 UI 线程安全 ​

SDK 中所有的数据回调（如 OnEEGData、OnBrainWave 等）均在后台工作线程中触发。若需在回调中更新 UI 组件（如图表刷新、文本更新），必须通过主线程调度器切回 UI 线程，否则将导致跨线程访问异常甚至应用崩溃。

  • WPF 中应使用： Application.Current.Dispatcher.Invoke(() => { ... })
  • WinForms 中应使用： this.Invoke(new Action(() => { ... }))
  • 对于高频数据（如 EEG 256 Hz），建议合并处理后定时刷新 UI，避免逐帧推送导致界面卡顿。

📖 完整集成示例 ​

以上 API 参考涵盖了 SDK 核心组件的功能定义。我们提供了包含控制台应用和 WPF 图形界面两种形式的完整示例工程，演示了以下集成场景：

  • 设备扫描、连接、配对的完整调用流程。
  • 高频数据回调的线程安全消费与环形缓冲区（Ring Buffer）实现。
  • WPF 环境下的实时脑波图表渲染。

关于上述场景的具体代码与完整工程，请查阅示例仓库：

👉 OxyZen C# 示例工程

Copyright © 2018-present BrainCo Inc.