分享一个串口设备配置工具

seasondear

游客，如果您要查看本帖隐藏内容请回复

# 设备调试工具 使用文档
## 一、概述

设备调试工具是一款运行在 Windows 平台的通用设备调试软件，支持多种通信协议和多种设备类型。通过配置文件即可灵活添加新设备，无需修改代码。

### 主要功能

- **多协议支持**: Modbus RTU、Modbus TCP、MQTT、TCP、UDP、JSON、Ymodem
- **多设备管理**: 启动时选择设备，每个设备独立配置
- **数据读取**: 实时读取设备寄存器数据，支持公式运算、实时曲线图表
- **参数配置**: 读写设备参数，支持范围校验、枚举下拉选择
- **固件升级**: 通过 Ymodem 协议升级，支持先向密码寄存器写入密码进入升级模式
- **数据调试**: 绕过 Modbus 协议，直接发送 HEX/ASCII 原始字节，实时接收回包
- **数据导出**: 支持手动导出 CSV 与定时自动导出
- **强制断开**: 串口拔掉/松动等底层异常时，可一键强制释放连接防止程序崩溃
- **主题切换**: 浅色/深色界面主题随时切换
- **交互日志**: 通信日志分级显示，点击可展开数据详情
- **扩展性强**: 通过修改 JSON 配置文件即可增加新设备

## 二、运行方式

### 2.1 使用打包好的 exe（推荐）

- 直接双击 `dist/设备调试工具.exe` 即可运行，无需安装 Python 环境
- 首次运行会在 exe 所在目录自动生成 `config/` 配置文件夹
- 配置文件不打包进 exe，用户可随时修改或新增设备

### 2.2 源码运行

需 Python 3.8+：

```bash
pip install -r requirements.txt
python main.py
```

## 三、快速入门

### 3.1 选择设备

启动程序后，会弹出设备选择对话框：

1. 左侧列表显示所有可用的设备
2. 右侧显示选中设备的详细信息
3. 双击设备或选中后点击"选择设备"确认

### 3.2 连接设备

1. 选择设备后进入主界面
2. 点击顶部工具栏的"🔗 连接"按钮
3. 程序会根据设备配置自动选择通信方式（串口/TCP/MQTT等）
4. **设备地址**：若设备从站地址不是默认值，在「通信参数」区的"设备地址"输入框中修改（如设备为不同地址时），数据读取/参数配置/升级统一使用该地址
5. 串口未打开或被占用时会直接弹窗提示，不会卡死
6. **🛑 强制断开**：当串口被拔掉、USB 线松动、TCP 对端断开等异常情况导致连接状态不一致时，点击工具栏的"强制断开"按钮可安全释放底层资源，防止程序崩溃。该按钮对正常连接同样适用，是断开的兜底手段

### 3.3 读取数据

1. 切换到"数据读取"选项卡
2. 点击"读取一次"按钮查看当前值
3. 点击"自动读取"并设置间隔时间，实现周期性读取与实时曲线显示
4. 曲线图上方可**勾选要显示的参数**（如只显示温度）
5. 勾选"自动导出"并设置间隔秒数，可定时将数据追加写入 exe 旁 `export/data_YYYYMMDD.csv`；也可点击"导出CSV"手动保存

### 3.4 配置参数

1. 切换到"参数配置"选项卡
2. 选中要修改的参数行
3. 修改"当前值"列（带枚举选项的参数以下拉框选择，如波特率）
4. 点击"写入配置"按钮（写入后该行背景变色表示状态，数据文本不变）
5. 点击"读取全部"可一次读取所有参数，随时点"取消"停止后续参数读取

### 3.5 固件升级

1. 切换到"固件升级"选项卡
2. 在「升级密码」面板中确认/修改密码寄存器值（支持 1~2 个寄存器，由配置文件定义）
3. 点击「✍️ 写入密码」向密码寄存器写入密码进入升级模式
4. 点击"浏览"选择固件文件
5. 点击"开始升级"通过 Ymodem 传输（串口 / TCP）

### 3.6 数据调试（原始 HEX/ASCII 收发）

数据调试页面绕过 Modbus 协议层，直接向串口/TCP 发送原始字节，适用于协议逆向、自定义报文测试、AT 指令调试等场景。

> ⚠️ 数据调试使用与其他页面**同一个连接**，发送原始字节会污染 Modbus 协议状态。建议调试前先清空收发缓冲区，或在调试完成后重新连接。

#### 发送区

1. **发送模式**下拉框切换：
   - **HEX**：输入十六进制字符串，如 `01 03 00 00 00 02`
     - 支持空格、冒号 `:`、分号 `;`、逗号 `,` 作为分隔符
     - 输入时**实时校验格式**，下方显示 ✅ 有效 HEX / ❌ 格式错误提示
     - 必须成对出现（每 2 个字符为一个字节），如 `0`（奇数位）或 `GG`（非法字符）会被拒绝
     - 校验通过后显示解析字节数和格式化结果，如 `✅ 有效 HEX，共 6 字节 → 01 03 00 00 00 02`
   - **ASCII**：直接输入文本，支持 `\r` `\n` `\t` 转义，如 `AT+RAT=0\r\n`

2. **循环发送**：勾选后可按设定间隔（ms）循环发送，点击"停止循环"或取消勾选停止

3. 点击「发送」按钮，或在输入框中按 **回车** 直接发送

4. 发送成功后，通信日志会记录 `[调试] 发送 HEX/ASCII: ...`

#### 接收区

1. 点击「开始接收」启动 200ms 轮询，自动读取底层缓冲区数据
2. 可选：
   - **HEX 显示**（默认开启）：以十六进制显示，如 `01 03 04 00 64 00 C8 XX XX`
   - **时间戳**（默认开启）：每行前缀 `[HH:MM:SS.mmm]`
3. 接收区最多保留 2000 行，自动滚到底部
4. 连接断开时自动停止接收
5. 点击「清空收发缓冲」可同时清空底层串口/TCP 的收发缓冲区和显示区

### 3.7 界面主题与通信日志与关于

- 顶部工具栏「主题」下拉框可随时切换 浅色/深色 主题
- 底部「通信日志」分级彩色显示（系统/发送TX/接收RX/数据/错误）
- **点击任意日志行可展开/收起数据详情**
- Modbus 协议下，通信日志会实时显示原始报文：
  - 下发帧 TX（如 `00 01 00 00 00 06 01 03 00 00 00 01`）、回复帧 RX
  - 点击展开可查看帧解析：事务ID、从站地址、功能码（读/写哪个寄存器）、数据、CRC16 校验等
- JSON 协议下，通信日志显示完整 JSON 帧：
  - TX `[JSON →] ServiceName 读取/写入请求` → 展开看完整发送 JSON
  - RX `[JSON ←] ServiceName 读取/写入成功（N 个字段）` → 展开看设备回包完整 JSON
- 固件升级时，通信日志同时显示 **Ymodem 原始收发 hex**（`[Ymodem → 发送]`/`[Ymodem ← 接收]`），长数据包点击展开查看完整字节
- 可通过「显示」下拉框过滤日志类型，支持自动滚屏、一键复制/清空
- 页面右下角 **ℹ️ 关于** 按钮：点击弹出关于对话框（版本号 v1.0.0、开发者 shuodawang）

### 3.8 测试用模拟设备

内置"模拟温湿度485设备"（Modbus TCP, 127.0.0.1:5030）：
- 启动模拟器：`python simulator/sim_device.py --tcp --port 5030`
- 可在数据读取页验证读取与图表、设参、Ymodem 升级、数据导出全流程

## 四、配置文件说明

### 4.1 全局设备列表

文件: `config/devices.json`

```json
{
  "devices": [
    {
      "id": "设备唯一标识",
      "name": "设备显示名称",
      "description": "设备描述",
      "config_file": "设备配置文件路径"
    }

}
```

### 4.2 设备配置文件

文件: `config/devices/<device_id>.json`

#### 设备信息

```json
{
  "device": {
    "id": "设备ID",
    "name": "设备名称",
    "description": "设备描述",
    "manufacturer": "制造商",
    "version": "版本号"
  }
}
```

#### 通信配置

```json
{
  "communication": {
    "type": "serial",           // serial / tcp / udp / mqtt
    "serial": {
      "baudrate": 9600,         // 波特率
      "databits": 8,            // 数据位
      "stopbits": 1,            // 停止位
      "parity": "none",         // 校验: none/even/odd
      "timeout": 1000           // 超时(ms)
    },
    "network": {
      "host": "192.168.1.100",  // IP地址
      "port": 502,              // 端口号
      "mqtt_topic": "topic",    // MQTT主题
      "mqtt_client_id": "id"    // MQTT客户端ID
    }
  }
}
```

#### 协议配置

```json
{
  "protocol": {
    "type": "ModbusRTU",        // ModbusRTU / ModbusTCP / JSON / Ymodem
    "modbus": {
      "slave_id": 1,            // 从站地址
      "byte_order": "big_endian", // 字节序
      "register_type": "holding"  // 寄存器类型
    }
  }
}
```

#### 数据寄存器（读取）

```json
{
  "data_registers": [
    {
      "name": "温度",           // 寄存器名称
      "address": 0,             // 寄存器地址
      "quantity": 1,            // 寄存器数量
      "data_type": "uint16",    // 数据类型
      "unit": "°C",             // 单位
      "formula": "value / 10.0", // 运算公式
      "access": "r",            // 访问权限: r/w/rw
      "description": "描述信息"
    }

}
```

**支持的数据类型**: `uint16`, `int16`, `uint32`, `int32`, `float32`

**公式说明**: `value` 表示原始寄存器值，支持四则运算。
- 示例: `value / 10.0` — 原始值263 → 显示26.3
- 示例: `(value - 1000) / 10.0` — 偏移换算

#### 配置寄存器（读写）

```json
{
  "config_registers": [
    {
      "name": "温度报警上限",
      "address": 10,
      "quantity": 1,
      "data_type": "uint16",
      "unit": "°C",
      "formula": "value / 10.0",
      "access": "rw",
      "description": "温度报警上限设定值",
      "min": 0,           // 最小值校验
      "max": 100,         // 最大值校验
      "default": 50       // 默认值
    },
    {
      "name": "波特率",
      "address": 21,
      "data_type": "uint16",
      "min": 0,
      "max": 5,
      "default": 3,
      "options": [          // 枚举选项：参数配置页以下拉框显示，只下发对应枚举值
        { "label": "1200", "value": 0 },
        { "label": "2400", "value": 1 },
        { "label": "9600", "value": 3 }

    }

}
```

> 偏移量类参数（如温度偏移量）可用 `data_type: "int16"` 支持负值。

#### 升级配置

```json
{
  "supports_upgrade": true,
  "upgrade": {
    "protocol": "Ymodem",
    "baudrate": 115200,
    "password_registers": [        // 支持 1~2 个密码寄存器
      { "register": 100, "value": 23130, "name": "升级密码1" },
      { "register": 101, "value": 23130, "name": "升级密码2" }

  }
}
```

> 说明：在「固件升级」页**手动点击「写入密码」**向密码寄存器写入密码使设备进入升级模式，随后点击「开始升级」通过 Ymodem 协议传输固件。旧格式 `password_register` / `password_value`（单一寄存器）仍兼容。

#### JSON 协议配置（MRTU 遥测终端等）

部分设备使用 JSON 协议配置参数（如 MRTU 遥测终端，通过串口发送 JSON 帧，设备回显当前配置）。这类设备的配置文件**不需要** `data_registers` / `config_registers`，而是通过 `json_config` 定义：

```json
{
  "json_config": {
    "device_id": "010301M86E2170000001",
    "services": [
      {
        "service_id": "CommunicateSet",
        "label": "通信参数",
        "fields": [
          {
            "name": "服务器IP",
            "json_path": "params.ServerIP",
            "field_type": "string",
            "default": "mqtt.rzhtiot.com"
          },
          {
            "name": "上报间隔(秒)",
            "json_path": "params.Reportt",
            "field_type": "scalar",
            "default": 60
          },
          {
            "name": "485波特率",
            "json_path": "params.ModUBR",
            "field_type": "scalar",
            "default": 9600,
            "options": [
              { "label": "1200", "value": 0 },
              { "label": "2400", "value": 1 },
              { "label": "9600", "value": 3 }

          }

      },
      {
        "service_id": "DeviceAttributeSet",
        "label": "485采集参数",
        "fields": [
          {
            "name": "从机地址数组",
            "json_path": "params.ModA",
            "field_type": "array",
            "array_size": 10,
            "default": [1, 1, 0, 2, 0, 0, 0, 0, 0, 0
          },
          {
            "name": "起始地址数组",
            "json_path": "params.ModRA",
            "field_type": "array",
            "array_size": 10,
            "default": [4000, 20000, 42000, 42100, 43000, 44000, 45000, 46000, 47000, 48000
          }

      }

  }
}
```

**字段类型**：
| field_type | UI 显示 | 编辑方式 |
|------------|---------|---------|
| `scalar` | QLineEdit（数字） | 直接输入 |
| `string` | QLineEdit（文本） | 直接输入 |
| `array` | &#128221; 编辑按钮 | 点击弹出数组编辑对话框，逐元素修改 |

**JSON 模式下的参数配置页**：
- 顶部出现 **Service 下拉框**（如「通信参数」/「485 采集参数」），切换即重新渲染表格
- 表格 5 列：参数名称 / JSON路径 / 当前值 / 类型 / 默认值
- **&#128229; 读取配置**：发送空 params 帧，设备回显完整当前配置，逐行填充
- **&#128228; 写入配置**：收集整帧 JSON → 预览确认 → 一次性下发 → 用回包刷新表格
- 通信日志显示完整 TX/RX JSON 帧，点击展开看格式化内容

> &#9888;&#65039; JSON 协议设备**不需要**配置 `data_registers` / `config_registers`，但仍需 `device` / `communication` / `protocol` 基础配置。

## 五、添加新设备

### 步骤

1. 在 `config/devices/` 目录下创建新设备的 JSON 配置文件
2. 在 `config/devices.json` 的 `devices` 数组中添加设备条目
3. 重启程序即可在设备列表中选择新设备

### 示例：添加一个 Modbus RTU 设备

1. 创建 `config/devices/my_device.json`:

```json
{
  "device": {
    "id": "my_device",
    "name": "我的设备",
    "description": "自定义设备",
    "manufacturer": "自定义",
    "version": "1.0"
  },
  "communication": {
    "type": "serial",
    "serial": {
      "baudrate": 9600,
      "databits": 8,
      "stopbits": 1,
      "parity": "none",
      "timeout": 1000
    }
  },
  "protocol": {
    "type": "ModbusRTU",
    "modbus": {
      "slave_id": 1,
      "byte_order": "big_endian",
      "register_type": "holding"
    }
  },
  "data_registers": [
    {
      "name": "温度",
      "address": 0,
      "quantity": 1,
      "data_type": "uint16",
      "unit": "°C",
      "formula": "value / 10.0",
      "access": "r",
      "description": "当前温度"
    }
  ],
  "config_registers": [],
  "supports_upgrade": false,
  "upgrade": null
}
```

2. 编辑 `config/devices.json`，添加:

```json
{
  "id": "my_device",
  "name": "我的设备",
  "description": "自定义设备",
  "config_file": "config/devices/my_device.json"
}
```

## 六、通信协议说明

### Modbus RTU
- 通过串口通信
- 支持功能码: 03 读保持寄存器、06 写单个寄存器、10 写多个寄存器
- 支持 CRC16 校验

### Modbus TCP
- 通过 TCP/IP 通信
- 标准 Modbus TCP 帧格式
- 默认端口 502

### MQTT
- 支持订阅/发布模式
- 接收 JSON 格式数据
- 支持用户名密码认证

### TCP/UDP
- 自定义 TCP/UDP 通信
- 支持发送和接收原始数据

### Ymodem
- 用于串口固件升级
- 支持 128/1024 字节数据包
- 支持 CRC16 校验

## 七、常见问题

### Q: 程序启动时提示"无法加载设备配置"
A: 检查 `config/devices.json` 中的 `config_file` 路径是否正确

### Q: 串口列表为空
A: 确保设备已连接电脑，检查驱动是否正确安装

### Q: Modbus 读取失败
A: 检查串口参数（波特率、数据位等）是否与设备匹配，检查从站地址是否正确

### Q: 提示"串口未打开或异常"？
A: 操作前程序会检查串口是否已连接/可用。请先在主界面点击"连接"，或确认串口未被其他程序（如 XSHELL、其他实例）占用。

### Q: 如何添加新的寄存器？
A: 编辑设备对应的 JSON 配置文件，在 `data_registers` 或 `config_registers` 数组中添加新条目

### Q: 数据调试页面发送 HEX 提示格式错误？
A: HEX 字符串必须由 0-9/A-F 组成，且每 2 个字符为一个字节（可带空格/冒号分隔）。合法示例：`01 03 00 00 00 02` 或 `01:03:00:00:00:02`。非法示例：`0`（奇数位）、`GG`（非 HEX 字符）

### Q: 数据调试发送原始字节后，Modbus 读取失败？
A: 数据调试绕过 Modbus 协议直接发送字节，会干扰 Modbus 状态机（如发送了一个非 Modbus 报文导致后续 Modbus 读取收到脏数据）。建议调试完原始字节后，点击「清空收发缓冲」再切换回 Modbus 读取，或直接重新连接

### Q: 什么时候应该用「强制断开」？
A: 正常情况下点「&#128279; 断开」即可。当遇到串口拔掉/USB 线松动/TCP 对端突然断开等异常，底层连接状态已不一致（如按钮显示未连接但实际端口被占用，或反之）时，用「&#128721; 强制断开」可安全释放资源，防止程序崩溃

hfx1972

谢谢分享，下载看看