# VibeSerial

**Repository Path**: amoeee/vibe_serial

## Basic Information

- **Project Name**: VibeSerial
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 串口实时监控与多通道绘图工具

一个基于 `PyQt6 + pyqtgraph + pyserial` 的串口上位机，支持高波特率、多通道实时绘图、通道显示开关、HEX/ASCII 发送、循环发送和丢包统计。

## 功能概览

- 串口连接管理：端口刷新、打开/关闭串口、状态提示
- 多通道实时绘图：自动识别通道数，支持手动固定通道数
- 通道显示控制：支持 `全开/全关` 与单通道勾选显示
- 数据发送：支持 `ASCII` / `HEX`，可选追加换行，支持循环发送
- 接收统计：实时显示接收速率、总点数、异常丢包及细分类别
- 高波特率优化：自动调整消费与绘图节奏，降低界面卡顿
- 深色工业主题 UI（当前默认）

## 环境要求

- Python 3.10+（推荐 3.11 / 3.12）
- Windows（当前项目在 Windows 下开发与验证）

依赖见 [requirements.txt](./requirements.txt)：

- `PyQt6>=6.10.0`
- `pyserial>=3.5`
- `pyqtgraph>=0.13`
- `numpy>=1.24`

## 安装与运行

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.py
```

## 快速使用

1. 点击“刷新端口”，选择串口和波特率
2. 设置“显示点数”（环形缓冲容量）
3. 设置“接收通道”：
   - `自动`（0）：自动识别
   - `>0`：固定通道数（高波特率建议固定）
4. 点击“打开串口”
5. 在“通道显示”中勾选要显示的通道
6. 如需发送：
   - 选择 `ASCII` 或 `HEX`
   - 输入内容后点击“发送一次”或勾选“循环发送”

## 串口数据协议（接收）

程序按帧解析，默认帧尾为：

- `0x55 0xAA`

### 解析规则

- 每帧数据体使用小端有符号 16 位整型（`int16 little-endian`）
- 一帧通道数 = `payload_bytes / 2`
- 自动模式下会根据连续一致帧长进行锁定
- 固定通道模式下按 `通道数 * 2 + 帧尾` 的固定帧长高速解析

### 通道映射说明（重要）

当前界面显示通道与报文列采用正序映射：

- `CH1` 对应报文第一列
- `CH2` 对应报文第二列
- 以此类推

如设备协议变化，可在 `main.py` 的 `_consume_value_block` 中调整映射逻辑。

## 绘图与交互说明

- X 轴：采样点索引（最新点在右侧，接近 0）
- `AUTO` 按钮：
  - 单击：仅自适应 Y 轴
  - 长按：自适应 X/Y 轴
- 鼠标悬停：显示光标附近各通道采样值

## 发送格式说明

### ASCII

- 直接按 UTF-8 编码发送

### HEX

- 以空格或逗号分隔，如：
  - `01 03 00 FF`
  - `01,03,00,FF`

## 常见问题

### 1) 高波特率下有丢包或卡顿

- 建议固定“接收通道”而不是自动识别
- 关闭“显示接收文本”
- 适当降低“显示点数”

### 2) 打不开串口

- 检查串口是否被其他软件占用
- 确认驱动和端口号正确
- 尝试重新插拔设备并刷新端口

### 3) 通道显示顺序不符合预期

- 当前版本已按正序映射显示
- 如设备协议变化，可按上文“通道映射说明”调整

## 项目结构

```text
.
├─ main.py              # 当前主程序入口（手写 UI + 功能逻辑）
├─ requirements.txt     # Python 依赖
└─ ui/
   ├─ serial.ui         # 预留/历史 UI 资源
   ├─ serial_ui.py
   └─ serial.py
```