Metadata-Version: 2.1
Name: qlsdk2
Version: 0.9.0a1
Summary: SDK for quanlan device
Home-page: https://github.com/hehuajun/qlsdk
Author: hehuajun
Author-email: hehuajun@eegion.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: loguru >=0.6.0
Requires-Dist: numpy >=1.23.5
Requires-Dist: bitarray >=1.5.3
Requires-Dist: pyserial >=3.5.0
Requires-Dist: pyedflib >=0.1.42
Provides-Extra: dev
Requires-Dist: pytest >=6.0 ; extra == 'dev'
Requires-Dist: twine >=3.0 ; extra == 'dev'

## **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. **创建设备容器**
   ```python
   dc = DeviceContainer(False)
   ```

2. **连接设备**
   ```python
   device = dc.connect(device_id, timeout=30)
   ```

3. **设置采集参数**
   ```python
   device.set_acq_param([1, 2, 3, 4], 1000, 188)
   ```

4. **启动数据采集**
   ```python
   device.start_acquisition()
   ```

5. **订阅数据**
   ```python
   signal_queue = device.subscribe()[1]
   impedance_queue = device.subscribe(type="impedance")[1]
   ```

6. **设置刺激参数**
   ```python
   pd = StimulationParadigm()
   ch0 = DCStimulation(0, 1, 300, 1, 1)
   pd.add_channel(ch0)
   device.set_stim_param(pd)
   ```

7. **开始刺激**
   ```python
   device.start_stimulation()
   ```

8. **停止采集和刺激**
   ```python
   device.stop_acquisition()
   ```

## 8. 总结

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

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