# DeskMate

**Repository Path**: realmcu_admin/desk-mate

## Basic Information

- **Project Name**: DeskMate
- **Description**: BLE 调试工具，测手表 等BLE 设备
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeskMate BLE 调试工具

PyQt6 桌面端 BLE（蓝牙低功耗）设备调试工具，用于发现、连接和与 DeskMate 设备通信。

## 截图

```
┌──────────────────────────────────────────────────────┐
│  ●  ▶ 扫描                      就绪     ◀ 设备列表 │
├──────────┬───────────────────────────────────────────┤
│ 设备列表 │  📡 N/A                                   │
│ [ 0 ]    │  AA:BB:CC:DD:EE:FF                        │
│          │  ┌─────┬─────┬─────┬─────┐                │
│  🔍搜索  │  │信号  │TX   │首次  │最后  │                │
│ ┌──────┐ │  │-50dBm│—    │14:30 │14:31 │                │
│ │Scanner│ │  └─────┴─────┴─────┴─────┘                │
│ │Bonded │ │  Service UUIDs: xxxx, yyyy                │
│ ↕ RSSI  │ │  [连接] [复制地址]                         │
│ ──────── │  ┌─────────────────────────────────┐       │
│ (设备行) │  │ GATT 浏览 │ 文件传输 │ 图片 │…   │       │
│ ──────── │  │ ─── Services ───                  │       │
│ ──────── │  │ ▼ Generic Access                  │       │
│          │  │   ├── Device Name        [★]      │       │
│ ──────── │  │   ├── Appearance        [★]      │       │
│ ──────── │  │ ▼ Generic Attribute              │       │
│          │  │ …                                 │       │
│          │  └─────────────────────────────────┘       │
│ ──────── │  LOG                                       │
│ 扫描中·5 │  14:30 [INFO] BLE 扫描已启动                │
├──────────┴───────────────────────────────────────────┤
│ 扫描中  ·  已发现 5 个设备                            │
└──────────────────────────────────────────────────────┘
```

## 功能特性

### ✅ BLE 扫描
- 基于 **bleak** 的异步 BLE 扫描，实时发现附近设备
- 设备列表实时更新（信号强度、名称、MAC 地址）
- 已配对设备（Bonded）与扫描设备（Scanner）分页查看
- 设备类型自动识别（手机/耳机/键盘/手表/音箱等）
- 信号强度以信号条 + dBm 数值显示
- 扫描停止后自动标记设备为"过期"

### ✅ 设备筛选与排序
- 按名称/MAC 地址文本搜索
- 按设备名称状态（已命名/未命名）筛选
- 按信号强度阈值筛选
- 按设备类型多选筛选
- RSSI 信号强度排序

### ✅ BLE 广播数据解析
- 完整解析 AD Type（Flags、UUID、Local Name、TX Power、Manufacturer、Appearance 等）
- 多包广播展示（Connectable Undirected / Scan Response）
- 支持 `_parse_received_args` 解析 Windows BLE 平台数据
- AD 记录详情弹窗、双击查看完整数据

### ✅ GATT 通信
- 连接/断开 BLE 设备，支持连接状态管理
- 完整的 GATT 服务树浏览（Service → Characteristic → Descriptor）
- Characteristic 收藏功能
- **Read** — 读取特征值（支持 HEX / UTF-8 显示）
- **Write** — 写入特征值（支持 HEX / UTF-8 输入）
- **Notify / Indicate** — 订阅特征值通知，实时接收数据
- 连接状态可视化（顶部指示灯、行内连接按钮、详情面板状态徽标）

### ✅ 文件传输
- 选择文件并按分块传输到设备
- 支持 **Write Response**（逐块确认）和 **Write No Response**（定时发送）
- 可配置分块大小（1-512 B）和发送间隔
- 实时进度条、速度（KB/s）、ETA 估算
- RX 通知接收日志
- 传输取消和自动完成处理

### ✅ 实时日志
- 四种日志级别：INFO / OK / WARN / ERR
- 按级别筛选
- 自动滚动 / 暂停
- 上限 600 条，自动裁剪

### ✅ Win11 Fluent Design 风格
- 完整 QSS 主题系统（色彩、按钮、输入框、滚动条、ComboBox、Tooltip）
- 自定义 `QPainter` 绘制的信号强度条
- 设备行选中效果（蓝色左侧条 + 背景高亮）
- 动画过渡（筛选抽屉展开/收起）

### 🔜 内容发送面板（UI 就绪，BLE 协议待对接）
- 图片选择与发送
- 弹幕输入（时长/字号/字数限制）
- GIF 选择与发送
- 视频选择与发送

## 安装

### 环境要求

- Python 3.10+
- Windows 10/11（蓝牙 4.0+）
- 蓝牙适配器已启用

### 安装依赖

```bash
pip install PyQt6 bleak
```

### 启动

```bash
cd pc-mobile-tool
python main.py
```

调试启动参数：

```bash
# 开启扫描诊断日志
python main.py --scan-debug-log

# 开启 GATT 交互诊断日志（请求/响应/通知/订阅状态）
python main.py --gatt-debug-log
```

## 使用

| 操作 | 方式 |
|---|---|
| 开始/停止扫描 | 点击 `▶ 扫描` 按钮 / 按 **F5** |
| 选中设备 | 单击设备行 |
| 连接/断开设备 | 选中后按 **Enter** / 点击行内按钮 / 点击详情面板按钮 / 双击设备行 |
| 复制 MAC 地址 | 选中设备后按 **Ctrl+Shift+C** / 右键菜单 |
| 搜索设备 | 设备列表顶部文本框输入名称或地址 |
| 筛选 | 点击「筛选」按钮，设置名称/RSSI/类型条件 |
| RSSI 排序 | 点击「↕ RSSI」按钮切换 |
| 查看广播数据 | 选中设备后，左下方面板展示 AD 记录 |
| GATT 操作 | 连接成功后切到「GATT 浏览」标签，点击 Characteristic |
| 文件传输 | 连接成功后切到「文件传输」标签，选择文件并配置参数 |

## 项目结构

```
pc-mobile-tool/
├── main.py                          # 入口
├── deskmate/
│   ├── theme.py                     # Win11 色彩系统 + 全局 QSS
│   ├── utils.py                     # RSSI 等级/颜色、设备图标、厂商数据
│   ├── workers.py                   # BLEWorker（扫描）、BLEConnectWorker（连接）、PairedDevicesWorker
│   ├── connection_manager.py        # 连接状态管理（ConnState 状态机）
│   └── widgets/
│       ├── main_window.py           # 主窗口（布局、快捷键、扫描控制）
│       ├── device_panel.py          # 设备列表面板（搜索/筛选/排序/分页）
│       ├── device_row.py            # 设备行组件（信号条/连接按钮/右键菜单）
│       ├── signal_bars.py           # 自定义绘制信号强度条
│       ├── filter_drawer.py         # 筛选抽屉（展开/收起动画）
│       ├── broadcast_panel.py       # BLE 广播数据展示 + AD 记录解析
│       ├── detail_panel.py          # 设备详情面板 + 连接后标签页
│       ├── gatt_explorer.py         # GATT 服务/特征值树形浏览
│       ├── char_panel.py            # 特征值读写/通知操作面板
│       ├── file_transfer_panel.py   # 文件传输面板
│       ├── content_panels.py        # 图片/弹幕/GIF/视频发送面板（UI 层）
│       ├── gatt_placeholder.py      # GATT 占位组件（备用）
│       └── log_panel.py             # 日志面板
```

## 技术栈

| 层 | 技术 |
|---|---|
| GUI 框架 | **PyQt6** (Qt6 Python 绑定) |
| BLE | **bleak** (跨平台 BLE 库) |
| 平台适配 | **winrt** (Windows 已配对设备查询) |
| 主题 | 纯 QSS + 自定义 `QPainter` 绘制 |
| 异步 | `QThread` + `asyncio` 事件循环 |

## 开发状态

| 区域 | 状态 | 说明 |
|---|---|---|
| BLE 扫描 | ✅ | bleak 异步回调，广告包缓存 |
| 设备列表/筛选/排序 | ✅ | 多维度筛选、RSSI 排序 |
| 已配对设备 | ✅ | Windows winrt 查询 |
| 广播数据解析 | ✅ | 完整的 AD Type 解码 |
| GATT 浏览 | ✅ | Service → Characteristic 树形展示 |
| 特征值读写/通知 | ✅ | Read / Write / Notify / Indicate |
| 文件传输 | ✅ | 分块、ACK、进度、速度 |
| 内容发送（图片/弹幕/GIF/视频） | 🔜 UI 完成，BLE 协议待对接 |
| 嵌入式固件 | ❌ | `embedded/` 未开始 |
| 测试 | ❌ | 无测试文件 |
| 依赖管理 | ❌ | 无 `requirements.txt` |

## 许可证

本项目仅供学习和研究使用。