# SerialScope

**Repository Path**: wangxiufeng/serial-scope

## Basic Information

- **Project Name**: SerialScope
- **Description**: 串口示波器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SerialScope

一款基于 Qt/QML 的串口示波器应用，用于实时显示和分析串口数据。

主界面

<img src="assets/main-window.png" alt="main-windows" style="zoom:70%;" />

配置界面

<img src="assets/config-window.png" alt="config-windows" style="zoom:80%;" />

## 功能特性

- 多通道数据同时显示（支持 Line 和 Bar 图表类型）
- 灵活的面板布局配置
- 支持高频率数据流（1000+ 数据点/通道）
- 实时数据显示，低延迟响应

## 技术架构

### 核心技术栈

- **Qt 5.12+** - 应用程序框架
- **QML/QtQuick** - 现代化 UI 渲染
- **C++11** - 核心业务逻辑
- **QSerialPort** - 串口通信

### 核心模块

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  SerialPort │ ──> │  DataParser │ ──> │  ChartModel │ ──> │  ChartPanel │
│  (C++)      │     │  (C++)      │     │  (C++)      │     │  (QML)      │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
      ▲                                       │
      │                                       │
   串口数据                               QML UI 更新
```

### 模块说明

| 模块 | 职责 |
|------|------|
| `SerialPort` | 串口打开、关闭、数据接收 |
| `DataParser` | 解析二进制数据，提取通道类型和值 |
| `ChartModel` | 数据存储、批量处理、信号通知 |
| `ChartPanel` | QML Canvas 渲染图表 |
| `ConfigManager` | 配置文件加载和管理 |

## 性能优化策略

### 1. 批量数据更新

高频率数据下，频繁的信号触发会影响性能。采用批量更新机制：

```cpp
// SerialScope 中的数据缓冲
QMap<int, QVariantList> m_dataBuffer;  // type -> list of {value, timestamp}
QTimer m_flushTimer;                      // 50ms 定时刷新

void SerialScope::flushDataBuffer() {
    for (auto it = m_dataBuffer.begin(); it != m_dataBuffer.end(); ++it) {
        m_chartModel.addDataPoints(it.key(), it.value());  // 批量添加
        it.value().clear();
    }
}
```

**优势**：
- 减少信号触发次数（从每个数据点一次降为每 50ms 一次）
- 批量内存操作更高效
- 数据不丢失，全部缓冲后统一发送

### 2. 节流重绘 (Throttling)

QML 端限制 Canvas 重绘频率：

```qml
Timer {
    id: renderThrottle
    interval: 50
    running: false
    repeat: false
}

Connections {
    target: chartModel
    onDataChanged: {
        if (!renderThrottle.running) {
            chartCanvas.requestPaint()
            renderThrottle.restart()
        }
    }
}
```

**优势**：
- 避免高频率 UI 更新导致的卡顿
- 50ms 间隔足够流畅（20 FPS）
- 保证数据完整性的同时提升响应性

### 3. 数据流优化

```
串口接收 → 内存缓冲 → 定时批量处理 → UI 更新
   ↑          ↑            ↑            ↑
 实时      不阻塞      50ms刷新     节流限制
```

## 配置文件

`config.json` 定义面板和通道布局：

```json
{
  "panels": [
    {
      "name": "温度",
      "channels": [
        {
          "name": "温度传感器",
          "type": "0x54",
          "dataType": "i16",
          "length": 2,
          "endian": "little",
          "chartType": "line",
          "unit": "°C",
          "color": "#ff6b6b",
          "min": -20,
          "max": 80
        }
      ]
    }
  ]
}
```

### 配置项说明

| 字段 | 说明 |
|------|------|
| `name` | 面板/通道显示名称 |
| `type` | 数据类型标识（十六进制） |
| `dataType` | 数据类型：`u8/i8/u16/i16/u32/i32` |
| `length` | 数据字节长度 |
| `endian` | 字节序：`little` / `big` |
| `chartType` | 图表类型：`line` / `bar` |
| `unit` | 单位（显示用） |
| `color` | 图表颜色（十六进制） |
| `min/max` | Y 轴范围（可选） |

## 编译构建

### 环境要求

- Qt 5.12+
- MSVC 2017/2019 或 MinGW
- Qt Serial Port 模块

### Debug 模式编译

```bash
# 使用 Qt Creator
# 1. 打开 SerialScope.pro
# 2. 选择 Debug 配置
# 3. 构建并运行
```

### Release 模式编译

```bash
# 1. 使用 Qt Creator 选择 Release 配置
# 2. 构建项目
```

## 发布部署

### 使用 windeployqt 打包

`windeployqt` 是 Qt 自带的部署工具，可自动复制所有运行时依赖。

#### 步骤 1：编译 Release 版本

```bash
# 在 Qt Creator 中选择 Release 配置
# 构建项目
```

#### 步骤 2：执行 windeployqt

```bash
# 进入 Release 构建目录
cd build/SerialScope-Release

# 执行部署（根据你的 Qt 安装路径调整）
C:\Qt\5.12.12\msvc2017_64\bin\windeployqt SerialScope.exe
```

#### 步骤 3：检查依赖

部署后应包含以下文件：

```
SerialScope.exe          # 主程序
Qt5Core.dll             # 核心库
Qt5Gui.dll              # GUI 库
Qt5Network.dll          # 网络模块
Qt5SerialPort.dll       # 串口模块
Qt5Qml.dll              # QML 引擎
Qt5Quick.dll            # Quick 库
platforms/              # 平台插件
qml/                    # QML 模块
```

#### 步骤 4：复制配置文件

将 `config.json` 复制到可执行文件同一目录。

#### 步骤 5：打包分发

```bash
# 打包成 ZIP
powershell Compress-Archive -Path * -DestinationPath SerialScope-Portable.zip

# 或直接分发整个文件夹
```

### 完整部署脚本

```powershell
# deploy.ps1
$releaseDir = "build\SerialScope-Release"
$qtDir = "C:\Qt\5.12.12\msvc2017_64\bin"

# 复制可执行文件
Copy-Item "$releaseDir\SerialScope.exe" . -Force

# 执行 windeployqt
& "$qtDir\windeployqt" SerialScope.exe

# 复制配置
Copy-Item "config.json" . -Force

Write-Host "部署完成！"
```

## 项目结构

```
SerialScope/
├── main.cpp              # 应用入口
├── main.qml              # QML 主界面
├── serialscope.h/cpp      # 主控制器
├── serialport.h/cpp       # 串口通信
├── dataparser.h/cpp       # 数据解析
├── chartmodel.h/cpp      # 数据模型
├── configmanager.h/cpp   # 配置管理
├── channelconfig.h       # 通道配置结构
├── ChartPanel.qml        # 图表面板组件
├── config.json           # 配置文件
├── SerialScope.pro       # 项目文件
└── README.md              # 本文档
```

## 许可证

MIT License