qlsdk2 0.9.0

SDK for quanlan device

**v0.8.1 (2026-03-31)

新特性

• LSE设备握手指令接口

• LSE设备电刺激参数设置接口

• LSE设备电刺激停止刺激接口

• LSE设备电流实时数据接口

• LSE设备阻抗测量启动接口

• LSE设备阻抗测量停止接口

• LSE设备阻抗实时数据回调接口

• LSE设备声光刺激参数设置接口

• LSE设备声光刺激停止接口

• LSE设备查询音频可用资源列表接口

• 提供电刺激组串行执行接口

• 提供多模态组串行执行接口

**v0.8.0 (2026-03-31)

新设备

• 添加串口设备支持
• 添加新设备LSE，支持使用界面设置好的刺激参数，控制LSE设备完成刺激准备、开始刺激、结束刺激

**v0.6.1/v0.7.1 (2026-03-24)

新设备

• 优化rsc类型设备的数据包处理间隔

**v0.7.0 (2026-02-11)

支持新设备类型：RSC8-R，RSC21-R

• 设备连接
• 信号采集参数设置（通道、采样率、幅值）
• 信号数据实时订阅与自动存储
• 阻抗测量控制与数据订阅
• 刺激功能（直流、交流、方波、脉冲等多种刺激模式）

2. 目录结构

项目采用模块化设计，清晰分离核心功能、设备实现、接口定义和示例代码。

├── example/            # 示例代码目录
│   ├── ar4m/           # AR4M设备示例
│   ├── chart_*.py      # 各种设备的图表示例
│   └── pluse_*.py      # 脉冲刺激示例
├── src/                # 源代码主目录
│   ├── qlsdk/          # 核心SDK代码
│   │   ├── ar4/        # AR4设备相关
│   │   ├── ar4m/       # AR4M设备相关
│   │   ├── core/       # 核心功能模块
│   │   ├── entity/     # 实体类定义
│   │   ├── interface/  # 接口定义
│   │   ├── lse/        # LSE设备相关
│   │   ├── persist/    # 数据持久化
│   │   ├── rsc/        # RSC系列设备实现
│   │   ├── sdk/        # SDK相关
│   │   ├── tools/      # 工具类
│   │   ├── x8/         # X8设备相关
│   │   └── x8m/        # X8M设备相关
│   └── *.py            # 根目录示例和测试文件
├── test/               # 测试代码目录
├── README.md           # 项目说明文档
├── requirements.txt    # 依赖项文件
└── setup.py            # 包安装配置

3. 核心模块分析

3.1 核心功能模块 (core/)

核心模块提供基础功能，包括设备基类、消息处理、CRC工具等。

• BaseDevice: 所有设备的基类，定义了设备的基本属性和方法
• 消息处理: 包含命令、TCP、UDP等消息处理模块
• CRC工具: 用于数据校验
• 本地操作: 本地设备相关功能
• 串口通信: 支持串口设备通信

3.2 设备实现 (rsc/device/)

该目录包含各种具体设备的实现，采用工厂模式创建设备实例。

• DeviceFactory: 设备工厂类，负责注册和创建设备实例
• QLBaseDevice: 基础设备实现类
• 具体设备实现:
  • C64RS: C64RS设备
  • ARSKindling: ARSKindling设备
  • C16_rs: C16RS设备
  • C8r: C8R设备
  • C21r: C21R设备
  • C256_rs: C256RS设备

3.3 接口定义 (interface/)

定义了系统的各种接口，为设备实现提供统一的规范。

• IDevice: 设备接口
• IParser: 解析器接口
• IAnalyzer: 分析器接口
• ICollector: 收集器接口
• IStimulator: 刺激器接口
• IStore: 存储接口

3.4 数据持久化 (persist/)

负责数据的存储和处理，支持EDF/BDF文件格式。

• RscEDFHandler: RSC设备的EDF文件处理
• EdfHandler: 通用EDF文件处理
• StreamHandler: 流数据处理

3.5 网络和发现 (rsc/network/)

负责设备的网络发现和通信。

• Discover: 设备发现功能

3.6 命令和解析 (rsc/command/, rsc/parser/)

处理设备命令和数据解析。

• 命令模块: 定义设备命令
• 解析器: 解析设备响应数据

4. 系统架构

4.1 设备管理流程

1. 设备发现: 通过网络或串口搜索设备
2. 设备连接: 与指定设备建立连接
3. 设备初始化: 设置设备参数
4. 数据采集: 启动/停止数据采集
5. 数据处理: 实时处理和存储数据
6. 刺激控制: 设置和执行刺激方案
7. 设备断开: 关闭设备连接

4.2 数据流向

1. 设备 → SDK: 设备发送原始数据到SDK
2. SDK → 解析器: 解析原始数据
3. 解析器 → 订阅者: 通过发布/订阅模式将数据发送给订阅者
4. SDK → 存储: 将数据存储到文件

4.3 关键设计模式

• 工厂模式: DeviceFactory用于创建不同类型的设备实例
• 发布/订阅模式: 用于实时数据分发
• 策略模式: 不同设备类型有不同的实现策略
• 模板方法模式: 基础设备类定义通用方法，具体设备类实现特定方法

5. 核心 API 和类

5.1 设备容器 (DeviceContainer)

用于管理设备连接和操作。

• connect(device_id, timeout): 连接指定ID的设备
• search(): 搜索可用设备

5.2 设备基类 (BaseDevice/QLBaseDevice)

所有设备的基础类，提供通用功能。

• set_acq_param(channels, sample_rate, sample_range): 设置采集参数
• start_acquisition(): 开始采集
• stop_acquisition(): 停止采集
• start_impedance(): 开始阻抗测量
• stop_impedance(): 停止阻抗测量
• set_stim_param(paradigm): 设置刺激参数
• start_stimulation(): 开始刺激
• subscribe(type): 订阅数据

5.3 刺激范式 (StimulationParadigm)

定义刺激方案。

• add_channel(channel): 添加刺激通道
• clear(): 清空刺激通道

5.4 数据存储 (RscEDFHandler)

处理数据存储。

• set_storage_path(path): 设置存储路径
• set_file_prefix(prefix): 设置文件前缀

6. 技术栈与依赖

技术/依赖	版本	用途
Python	>=3.9	开发语言
loguru	>=0.6.0	日志处理
numpy	>=1.23.5	数值计算
bitarray	>=1.5.3	位操作
Windows	Windows 10	操作系统

7. 典型使用流程

以C64RS设备为例，典型使用流程如下：

1. 创建设备容器

   dc = DeviceContainer(False)
   

2. 连接设备

   device = dc.connect(device_id, timeout=30)
   

3. 设置采集参数

   device.set_acq_param([1, 2, 3, 4], 1000, 188)
   

4. 启动数据采集

   device.start_acquisition()
   

5. 订阅数据

   signal_queue = device.subscribe()[1]
   impedance_queue = device.subscribe(type="impedance")[1]
   

6. 设置刺激参数

   pd = StimulationParadigm()
   ch0 = DCStimulation(0, 1, 300, 1, 1)
   pd.add_channel(ch0)
   device.set_stim_param(pd)
   

7. 开始刺激

   device.start_stimulation()
   

8. 停止采集和刺激

   device.stop_acquisition()
   

8. 总结

QL SDK 是一个功能完整的脑电设备控制和数据采集工具包，采用模块化设计，支持多种设备类型和功能。通过工厂模式和接口定义，实现了设备的统一管理和扩展。系统架构清晰，核心功能完善，为脑电设备的使用提供了便捷的编程接口。

该SDK不仅支持基本的数据采集和存储功能，还提供了丰富的刺激控制选项，满足不同实验场景的需求。未来通过完善接口定义、增强错误处理、添加更多设备支持等方式进一步提升系统的稳定性和可扩展性。