# controller-debug-tool

**Repository Path**: migeking_admin/controller-debug-tool

## Basic Information

- **Project Name**: controller-debug-tool
- **Description**: 通用控制器调试工具，用于通过串口和TCP Socket与嵌入式控制器进行通信、配置、实时数据监控和报文调试
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 控制器调试工具

通用控制器调试工具，用于通过串口和TCP Socket与嵌入式控制器进行通信、配置、实时数据监控和报文调试。

## 环境要求

- Python 3.11+
- Windows / Linux / macOS

## 安装

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

## 运行应用

```bash
# 激活虚拟环境后运行
python -m src.main
```

## 调试运行

### 使用命令行调试
```bash
# 带调试输出运行
python -m src.main 2>&1

# 使用 Python 调试器
python -m pdb -m src.main
```

### 使用 IDE 调试
在 VS Code 或 PyCharm 中，设置入口文件为 `src/main.py`，然后使用 IDE 的调试功能。

## 打包发布

### 使用 PyInstaller 打包

```bash
# 安装 PyInstaller
pip install pyinstaller

# 打包为单文件可执行程序
pyinstaller --onefile --windowed --name "控制器调试工具" src/main.py

# 打包为目录形式（启动更快）
pyinstaller --onedir --windowed --name "控制器调试工具" src/main.py
```

打包完成后，可执行文件位于 `dist/` 目录。

### 打包选项说明
- `--onefile`: 打包为单个可执行文件
- `--onedir`: 打包为目录（包含依赖）
- `--windowed`: Windows下不显示控制台窗口
- `--icon=icon.ico`: 指定应用图标（可选）

### 完整打包命令（推荐）
```bash
pyinstaller --onedir --windowed --name "ControllerDebugTool" \
    --add-data "sample_config.ini;." \
    --add-data "sample_rules.json;." \
    src/main.py
```

## 项目结构

```
controller-debug-tool/
├── src/
│   ├── config/      # 配置管理模块
│   ├── connection/  # 连接管理模块
│   ├── data/        # 数据处理模块
│   ├── ui/          # 用户界面模块
│   └── logging/     # 日志模块
├── tests/           # 测试目录
├── sample_config.ini    # 示例配置文件
├── sample_rules.json    # 示例解析规则
├── requirements.txt     # 依赖列表
└── .gitignore           # Git忽略文件
```

## 运行测试

```bash
# 运行所有测试
pytest tests/

# 运行测试并显示详细输出
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_config_manager.py -v
```

## 功能说明

### 配置文件管理
- 支持加载/保存 INI 格式配置文件
- 图形化配置编辑器
- 配置验证（IP、端口、波特率、MAC地址等）

### 连接管理
- 串口连接（Star、Zigbee、RS485）
- TCP Socket 连接
- 多连接并行管理

### 数据监控
- 实时数据接收显示
- 十六进制/ASCII 双格式显示
- 关键字过滤和时间范围过滤
- 字段值高亮

### 报文发送
- 十六进制字符串直接输入
- 基于解析规则的表单化构造
- 单次发送和循环发送模式

### 解析规则
- JSON 格式解析规则定义
- 支持多种数据类型（uint8/16/32, int8/16/32, float32）
- 自动校验和计算

## 示例文件

项目包含示例文件供快速测试：

- `sample_config.ini` - 示例配置文件，包含TCP、串口等配置
- `sample_rules.json` - 示例解析规则，定义帧格式和字段

## 常见问题

### Qt/PyQt5 相关问题

#### 1. 缺少 Qt 平台插件
```
qt.qpa.plugin: Could not find the Qt platform plugin "windows" in ""
```

**解决方案：**
```bash
# 重新安装 PyQt5
pip uninstall PyQt5 PyQt5-Qt5 PyQt5-sip
pip install PyQt5
```

#### 2. DLL 加载失败
```
ImportError: DLL load failed while importing QtCore
```

**解决方案：**
- 确保使用正确的 Python 位数（32位/64位）
- Windows 用户可能需要安装 [Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe)

#### 3. 高DPI警告
```
Attribute Qt::AA_EnableHighDpiScaling must be set before QCoreApplication is created.
```

这是一个无害的警告，不影响程序运行。

### 依赖安装问题

#### 完整依赖安装
```bash
# 升级 pip
python -m pip install --upgrade pip

# 安装所有依赖
pip install PyQt5>=5.15.0 pyserial>=3.5 hypothesis>=6.82.0 pytest>=7.4.0

# 或使用 requirements.txt
pip install -r requirements.txt
```

#### 验证安装
```bash
# 检查 PyQt5 是否正确安装
python -c "from PyQt5.QtWidgets import QApplication; print('PyQt5 OK')"

# 检查 pyserial 是否正确安装
python -c "import serial; print('pyserial OK')"
```

### Linux 特殊说明

Ubuntu/Debian 用户可能需要安装系统级 Qt 库：
```bash
sudo apt-get install python3-pyqt5 libxcb-xinerama0
```

### macOS 特殊说明

如果遇到权限问题：
```bash
# 使用 Homebrew 安装 Python
brew install python@3.11

# 创建虚拟环境
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## 依赖列表

| 包名 | 版本 | 说明 |
|------|------|------|
| PyQt5 | >=5.15.0 | GUI框架 |
| pyserial | >=3.5 | 串口通信 |
| hypothesis | >=6.82.0 | 属性测试框架 |
| pytest | >=7.4.0 | 测试框架 |
| pyinstaller | >=6.0.0 | 打包工具（可选） |

## 许可证

MIT License