Python

🚀 准备工作

硬件连接指引

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

运行环境要求

Python 版本的跨平台特性要求根据不同的宿主系统准备环境：

• 开发语言：Python 3.10 ~ 3.12（暂不支持其他版本）。
• macOS：macOS 10.15 或更高版本。

• Windows：Windows 10 build 10.0.15063 或更高版本。

Windows 宿主环境调试提示

Windows 环境由于内置蓝牙适配器碎片化严重，要求网卡的 LMP（Link Manager Protocol）必须为 11.x（对应蓝牙 5.2）或更高版本，否则将导致连接不稳定。 如您当前的开发机系统不支持该版本，建议采购并使用外接 USB 蓝牙 5.0/5.2 适配器，关于相关适配器的采购推荐与环境配置排障，请参考 Windows 使用指南。

安装和集成

Python 版本无需编译构建，配置好依赖即可直接使用。

配置开发依赖

1. 推荐在专有虚拟环境中运作（推荐使用 conda）：

   # Conda 方案（推荐）
   conda create -n my_env python=3.10
   conda activate my_env
   
   # 或者使用原生 venv
   python3 -m venv venv
   source venv/bin/activate  # Windows 环境使用 venv\Scripts\activate

2. 安装所需依赖库：

   pip3 install bleak>=0.20.0     # 最通用的跨平台蓝牙库
   pip3 install numpy>=1.21.0     # 科学计算（避免大量数组带来的开销）

（注：若需构建桌面 GUI，建议配合 PyQt5 及 pyqtgraph 一同食用，可参考下文的开源示例中的搭建方案）

核心 API 参考

ZenLiteSDK (类)

全局设备扫描与管理类（保留 ZenLite 前缀为后向兼容考量）：

class ZenLiteSDK:
    @staticmethod
    def start_scan(callback):
        """开始扫描设备"""
        pass
    
    @staticmethod
    def stop_scan():
        """停止设备扫描"""
        pass
    
    @staticmethod
    def set_log_level(level):
        """设置日志级别"""
        pass

ZenLiteDevice (类)

设备代理对象，用于管理设备状态与发送指令：

class ZenLiteDevice:
    # --- 属性 ---
    uuid: str                   # 设备的真实蓝牙地址/唯一标识符
    name: str                   # 广播名
    rssi: float                 # 蓝牙信号强度
    in_pairing_mode: bool       # 是否处于配对模式
    connectivity: Connectivity  # 连接状态 (enum)
    battery_level: int          # 当前电量百分比
    hardware_revision: str      # 硬件版本
    firmware_revision: str      # 固件版本
    
    # --- 连接触发器 ---
    def set_listener(self, listener):
        """设置数据与状态回调监听"""
        pass
    def connect(self):
        """连接设备"""
        pass
    def disconnect(self):
        """断开连接"""
        pass
    def zl_pair(self, in_pairing_mode, callback):
        """设备配对"""
        pass
        
    # --- 数据通道控制 ---
    def zl_config_afe(self, sample_rate, callback):
        """设置 EEG 采样率"""
        pass
    def zl_config_imu(self, sample_rate, mode, callback):
        """设置 IMU 采样率与工作模式"""
        pass
    def zl_config_ppg(self, report_rate, mode, raw_set_reg, raw_set_value, callback):
        """设置 PPG 上报频率与工作模式"""
        pass
        
    # --- 硬件控制 ---
    def zl_set_device_name(self, name, callback):
        """修改设备蓝牙名称"""
        pass
    def zl_set_sleep_idle_time(self, seconds, callback):
        """设置设备闲置（未佩戴）自动关机时间（秒）"""
        pass

ZenLiteDeviceListener (类)

重写该类中的方法以接收设备事件与数据回调：

class ZenLiteDeviceListener:
    # --- 状态与连接信息 ---
    def on_connectivity_change(self, connectivity): pass
    def on_device_info_ready(self, device_info): pass
    def on_contact_state_change(self, contact_state): pass
    def on_orientation_change(self, orientation): pass
    def on_battery_level_change(self, battery_level): pass
    def on_error(self, error): pass

    # --- 传感器数据 ---
    def on_eeg_data(self, eeg_data): pass
    def on_raw_eeg_data(self, raw_eeg): pass
    def on_imu_data(self, imu_data): pass
    def on_ppg_data(self, ppg_data): pass
    
    # --- 算法分析指标 ---
    def on_brain_wave(self, brain_wave): pass
    def on_attention(self, attention, weighted_attention): pass
    def on_meditation(self, meditation, calmness, awareness): pass
    def on_sleep_stage(self, stage, confidence, drowsiness): pass

核心数据模型参考

EEG 脑电波数据

class EEGData:
    sequence_num: int           # 序列号
    sample_rate: float          # 采样率
    eeg_data: list[float]       # EEG 数据，每组 30 个样本

BrainWave 脑波频段指标

class BrainWave:
    delta: float                # Delta 波 (0.5-4 Hz)
    theta: float                # Theta 波 (4-8 Hz)
    alpha: float                # Alpha 波 (8-13 Hz)
    low_beta: float             # Low Beta 波 (13-17 Hz)
    high_beta: float            # High Beta 波 (17-30 Hz)
    gamma: float                # Gamma 波 (30-50 Hz)

IMU 惯性测量单元数据

class IMUData:
    acc_data: ACCData                 # 加速度计数据
    gyro_data: GyroData               # 陀螺仪数据
    euler_angle_data: EulerAngleData  # 欧拉角数据
    sample_rate: float                # 采样率
    head: ImuPoseHead                 # 头部姿态
    body: ImuPoseBody                 # 身体状态

class ACCData:
    x, y, z: list[float]              # 三轴加速度

class GyroData:
    x, y, z: list[float]              # 三轴角速度

class EulerAngleData:
    yaw, pitch, roll: list[float]     # 偏航、俯仰、翻滚角 (-180~180)

PPGData (光电容积脉搏波)

class PPGData:
    sequence_num: int                 # 序列号
    sample_rate: float                # 采样率
    raw_data: list[PPGRawData]        # 原始光学数据
    algo_data: list[PPGAlgoData]      # 分析指标结果
    respiratory_rate: float           # 呼吸频率
    respiratory_curve: list[float]    # 呼吸曲线
    respiratory_state: RespiratoryState

class PPGAlgoData:
    hr: float                   # 心率 (bpm)
    hr_conf: int                # 心率置信度 (0-100%)
    rr: float                   # 呼吸率
    spo2: float                 # 血氧饱和度
    spo2_conf: int              # 血氧置信度 (0-100%)
    hrv: float                  # 心率变异性
    stress: float               # 压力指数

class PPGRawData:
    green1_count, green2_count: int  # 绿光通道计数
    ir_count, red_count: int         # 红外/红光通道计数

枚举常量类

连接 / 佩戴状态

class Connectivity(IntEnum):
    connecting = 0      # 连接中
    connected = 1       # 已连接
    disconnecting = 2   # 断开中
    disconnected = 3    # 已断开

class ContactState(IntEnum):
    unknown = 0         # 未知
    off = 1             # 未正确佩戴
    eeg = 2             # EEG 接触良好
    all = 3             # EEG 和 PPG 接触良好

class Orientation(IntEnum):
    unknown = 0         # 未知
    upward = 1          # 设备佩戴正确
    downward = 2        # 设备佩戴反了

睡眠分期与呼吸状态

class SleepStage(IntEnum):
    unknown = -1        # 未知
    awake = 0           # 清醒
    rem = 1             # REM 睡眠
    light = 2           # 浅睡眠
    deep = 3            # 深睡眠
    
class RespiratoryState(IntEnum):
    rest = 0            # 静息
    inward = 1          # 吸气期
    outward = 2         # 呼气期

采样率与工作模式配置

class EEGSampleRate(IntEnum):
    # off = 1 关闭 EEG 数据流
    sr128 = 2           # 128 Hz
    sr256 = 3           # 256 Hz

class IMUSampleRate(IntEnum):
    # off = 1 关闭 IMU 数据流
    sr25, sr50, sr100, sr200, sr400, sr800 = 2, 3, 4, 5, 6, 7  # (Hz)

class IMUMode(IntEnum):
    # none = 0 关闭
    acc = 1             # 仅加速度计
    gyro = 2            # 仅陀螺仪
    acc_gyro = 3        # 加速度计 + 陀螺仪
    euler = 4           # 欧拉角

class PPGReportRate(IntEnum):
    # 常用 sr1；若关注 HRV 可使用 sr50
    none, off, sr1, sr5, sr25, sr50, sr100 = 0, 1, 2, 3, 4, 5, 6

class PPGMode(IntEnum):
    # 常用 algo=2（完整算法指标）
    raw_data = 1        # 仅原始光学数据
    algo = 2            # 完整算法指标（心率、血氧、HRV 等）
    spo2, hr, hrv = 3, 4, 5  # 仅单项指标

故障排查与注意事项

常见连接与配对问题

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

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

Python 平台开发注意事项

• 线程安全与 GUI 更新：所有的数据回调（如 on_eeg_data）均在后台子线程触发，因此严禁在回调中直接更新 UI，否则会导致程序崩溃或界面死锁。
  • 建议做法：请务必利用您所选 GUI 框架的跨线程派发机制（例如 PyQt 的 Signal.emit），或利用 Python 标准库的 queue.Queue 生产者消费者模型将数据转发至主线程消费。
• 内存管理：EEG 数据的推送频率较高（256 Hz），若在内存中无边界地追加至 list，将导致内存持续增长。建议在处理数据时使用固定长度的环形缓冲区（Ring Buffer）或 numpy 的滚动数组机制进行存储和修剪，防止长时间拉取后造成内存溢出。

📖 完整集成示例

我们提供了完整的开源参考项目，包含命令行版本和基于 PyQt 的实时可视化界面版本。（示例包含设备连接、数据接收、以及结合 PyQt 的完整图表流程示范）。

详见示例仓库（包含控制台版本与 GUI 图形界面版本）：

👉 OxyZen Python 示例工程