Python

示例源码、原生库获取方式和运行说明统一维护在 Python 示例仓库。

Ubuntu / Linux Python

公开 1.x Linux 示例与 macOS/Windows 示例共用 python/ 根目录；Linux 入口为 linux/example.py，不再使用独立的 python/ubuntu/ 副本。Linux 使用 Bleak/BlueZ 和 SDK 原生 C parser，目标环境为 Ubuntu 22.04、Python 3.10+，原生库按 x86_64 和 aarch64 分目录加载。

取得包含 linux/ 和 zenlite/ 的完整 Python 包后，在 python/ 或交付包根目录运行：

bash

sudo apt-get install python3-venv bluez libuv1 unzip
bash download-libs.sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r linux/requirements.txt
python linux/example.py DEVICE_NAME --pairing-id ubuntu-host-01 --pair

首次配对需让设备进入配对模式并传入 --pair；后续连接省略该参数，保留同一个 pairing ID。示例等待配对/配置响应，并检查实际 EEG 回调；未收到数据会失败退出。

此前的 ZenLite 1.5.2 Linux 库已于 2026-10-13 在 x86_64 和 aarch64 上通过原生加载、CFFI 回调注册及配对指令生成检查。当前下载器按宿主架构安装 ZenLite 1.5.5，并核验归档和库文件的 SHA-256；可用 bash download-libs.sh all 准备两种架构。取得包后需核对原生库版本。

原生库目录和运行要求见包内 linux/README.md。Docker/Colima 可用于原生库加载检查；蓝牙扫描、配对及 EEG 实机验收仍需 Ubuntu 主机和真实设备。IMU/PPG 流程尚未完成实机验证。

Windows 需安装 Microsoft Visual C++ 2015–2022 x64 Redistributable，桌面下载器提供 libuv 和 TensorFlow Lite DLL。macOS 下载器安装已发布的 ZenLite 1.5.5 arm64/x86_64 mac-compat.zip 原生库包，最低要求 macOS 12.3，并核验固定 SHA-256。

🚀 准备工作

硬件连接指引

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

运行环境要求

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

开发语言：Python 3.10 ~ 3.12（暂不支持其他版本）。
macOS：macOS 12.3 或更高版本。
Linux：Ubuntu 22.04，使用上文的 python/linux/example.py 入口及 BlueZ。
Windows：Windows 10 build 10.0.15063 或更高版本。

Windows 宿主环境调试提示

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

安装和集成

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

配置开发依赖

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

bash

# 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

安装所需依赖库：

bash

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

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

核心 API 参考

ZenLiteSDK (类)

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

python

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

ZenLiteDevice (类)

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

python

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, callback):
        """设置 PPG 上报频率与工作模式"""
        pass
        
    # --- 硬件控制 ---
    def zl_set_device_name(self, name, callback):
        """修改设备蓝牙名称"""
        pass
    def zl_set_sleep_idle_time(self, seconds, callback):
        """设置设备闲置（未佩戴）自动关机时间（秒）"""
        pass

ZenLiteDeviceListener (类)

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

python

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 脑电波数据

python

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

BrainWave 脑波频段指标

python

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 惯性测量单元数据

python

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 (光电容积脉搏波)

python

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         # 红外/红光通道计数

枚举常量类

连接 / 佩戴状态

python

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        # 设备佩戴反了

睡眠分期与呼吸状态

python

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

采样率与工作模式配置

python

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 示例工程

Python ​

Ubuntu / Linux Python ​

🚀 准备工作 ​

硬件连接指引 ​

运行环境要求 ​

安装和集成 ​

配置开发依赖 ​

核心 API 参考 ​

ZenLiteSDK (类) ​

ZenLiteDevice (类) ​

ZenLiteDeviceListener (类) ​

核心数据模型参考 ​

EEG 脑电波数据 ​

BrainWave 脑波频段指标 ​

IMU 惯性测量单元数据 ​

PPGData (光电容积脉搏波) ​

枚举常量类 ​

连接 / 佩戴状态 ​

睡眠分期与呼吸状态 ​

采样率与工作模式配置 ​

故障排查与注意事项 ​

常见连接与配对问题 ​

Python 平台开发注意事项 ​

📖 完整集成示例 ​

Python

Ubuntu / Linux Python

🚀 准备工作

硬件连接指引

运行环境要求

安装和集成

配置开发依赖

核心 API 参考

ZenLiteSDK (类)

ZenLiteDevice (类)

ZenLiteDeviceListener (类)

核心数据模型参考

EEG 脑电波数据

BrainWave 脑波频段指标

IMU 惯性测量单元数据

PPGData (光电容积脉搏波)

枚举常量类

连接 / 佩戴状态

睡眠分期与呼吸状态

采样率与工作模式配置

故障排查与注意事项

常见连接与配对问题

Python 平台开发注意事项

📖 完整集成示例