# go_com

**Repository Path**: user_ye/go_com

## Basic Information

- **Project Name**: go_com
- **Description**: go 实现的linux和window 调式串口工具
主要是满足linux 的串口调式
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-12
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 串口调试助手

基于 **Wails3 (Go) + Vue3 + Vite** 的跨平台串口调试工具,支持 Linux 与 Windows。

**作者:曾记大排档**

## 功能

| # | 功能 | 说明 |
|---|------|------|
| 1 | 串口选择与参数设置 | **串口下拉**列出系统枚举到的串口(选中即用);若未枚举到或需要虚拟端口/特殊设备,选择下拉中的「手动输入…」填写路径(如 `/dev/ttyUSB0`、`/dev/pts/3`、`COM3`)。**波特率下拉**(300–921600 常用档位)、数据位(5-8)、校验位(无/偶/奇)、停止位(1/1.5/2) |
| 2 | HEX / 文本收发显示 | 接收区可在 **HEX 显示** 与 **文本显示** 间切换;发送支持 **文本** 与 **HEX**(`01 A2 FF`、`01A2FF`、`01,A2` 等写法均可);可选附加换行 `\r\n` / `\n` / `\r`;显示时间戳、自动滚动、RX/TX 字节计数、一键清空 |
| 3 | 接收合并显示窗口 | 默认 **20ms**,可在日志工具栏实时调整(1–5000ms)。窗口内到达的数据合并为一条记录显示;超过窗口时长的连续数据流按窗口时长切分,避免刷屏 |
| 4 | 定时发送 | 勾选后按设定间隔(ms)周期性发送当前发送内容(与手动发送共用输入框) |
| 5 | 文件发送 | 系统文件选择框或直接输入路径;分块发送(4KB/块,块间 10ms),带进度条与取消按钮 |
| 6 | 发送自动校验后缀 | 发送时可通过下拉框在帧尾自动追加校验:**无**(默认)/ **Modbus CRC16**(低字节在前)/ **CRC32**(小端)/ **累加和** / **异或**;校验覆盖含「附加换行」在内的完整帧,TX 日志与计数均按实际发出的完整帧显示 |
| 7 | 日志保存到本地文件 | 日志工具栏 **保存日志…** 打开系统保存对话框,把当前日志(按界面 HEX/文本显示模式)写入本地 `.txt` 文件;文件含表头(导出时间、串口与参数、显示模式、RX/TX 统计)与逐条记录(完整时间戳 + 方向 + 数据,不截断) |

其他:窗口标题实时反映连接状态;串口被拔出/异常断开时自动上报状态并复位界面。

## 界面预览

**主界面(HEX 显示)** — 串口/波特率下拉、连接状态(已连接时按钮变红)、合并窗口设置、收发日志与 RX/TX 字节计数、定时发送、文件发送:

![主界面 - HEX 显示](docs/images/screenshot-main-hex.png)

**文本显示模式** — 同一份日志可按 **HEX / 文本** 一键切换显示:

![文本显示模式](docs/images/screenshot-text-mode.png)

**文件发送** — 选择文件或直接填路径,分块发送并显示进度,可随时取消:

![文件发送](docs/images/screenshot-file-send.png)

> 截图为演示效果,使用虚拟串口(`/dev/ttyUSB9`)与模拟设备回包;实际使用时串口下拉会列出真实设备。

## 环境要求

- Go 1.25+
- Node.js 18+ (构建前端)
- Linux 构建需要 GTK4 + WebKitGTK 6.0 开发包(如 Arch 的 `gtk4`/`webkitgtk-6.0`,Debian 的 `libgtk-4-dev`/`libwebkitgtk-6.0-dev`);Windows 无需额外依赖
- 可选:Wails3 CLI(`go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-beta.20`)

## 构建与运行

### 方式一:直接构建(不依赖 task 命令)

```bash
# 1. 构建前端(会输出到 frontend/dist,被 Go embed 进二进制)
cd frontend && npm install && npm run build && cd ..

# 2. 构建桌面应用
go build -tags production -trimpath -buildvcs=false -ldflags="-w -s" -o bin/com .
./bin/com            # Linux 运行
```

Windows 下构建(在 Windows 机器上执行):

```powershell
cd frontend; npm install; npm run build; cd ..
go build -tags production -trimpath -buildvcs=false -ldflags="-w -s" -o bin/com.exe .
.\bin\com.exe
```

### 方式二:使用 Wails3 CLI / Taskfile

```bash
wails3 dev            # 开发模式(前后端热重载)
wails3 build          # 生产构建
wails3 generate bindings -clean=true   # 修改 Go 服务方法后重新生成前端绑定
```

> 注意:改动 `SerialService` 的导出方法或事件后,必须重新生成 `frontend/bindings/`,否则前端调用会失败。

### 本机(受限环境)说明

若默认 Go 模块/编译缓存只读,可把缓存放到工程内(已在 `.gitignore` 中忽略):

```bash
export GOCACHE=$PWD/.gocache GOMODCACHE=$PWD/.gomodcache GOSUMDB=off
```

## 打包分发

产物统一输出到 `bin/`:

| 产物 | 适用平台 | 安装/运行 |
|------|---------|----------|
| `com` | Linux | 直接运行(需 GTK4 + WebKitGTK 6.0) |
| `com.deb` | Debian/Ubuntu 24.04+ | `sudo dpkg -i com.deb` |
| `com.rpm` | Fedora/RHEL | `sudo rpm -i com.rpm` |
| `com.pkg.tar.zst` | Arch Linux | `sudo pacman -U com.pkg.tar.zst` |
| `com-x86_64.AppImage` | 通用 Linux | `chmod +x com-x86_64.AppImage && ./com-x86_64.AppImage` |
| `com-windows-amd64.exe` / `.zip` | Windows 10+ | 双击运行(需系统自带 WebView2 运行时) |

打包命令:

```bash
# deb / rpm / archlinux(使用 wails3 内置的 nfpm,无需额外安装 nfpm)
export GOARCH=amd64 GIT_COMMITTER_NAME="你的名字" GIT_COMMITTER_EMAIL="you@example.com"
wails3 tool package -name com -format deb       -config ./build/linux/nfpm/nfpm.yaml -out "$PWD/bin"
wails3 tool package -name com -format rpm       -config ./build/linux/nfpm/nfpm.yaml -out "$PWD/bin"
wails3 tool package -name com -format archlinux -config ./build/linux/nfpm/nfpm.yaml -out "$PWD/bin"

# Windows 可执行文件(交叉编译,CGO 关闭)
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -tags production -trimpath -buildvcs=false \
  -ldflags="-w -s" -o bin/com-windows-amd64.exe .

# AppImage:手工组装 AppDir 后用 appimagetool 打包
# (wails3 generate appimage 会调用 linuxdeploy 打包 WebKit 等系统库,在部分发行版上
#  会因 soname 不匹配失败;手工 AppDir 只包含程序自身,依赖宿主机的 GTK4/WebKitGTK 6.0)
mkdir -p work/com.AppDir/usr/bin
cp bin/com work/com.AppDir/usr/bin/com
cp build/linux/com.desktop work/com.AppDir/com.desktop
cp build/appicon.png work/com.AppDir/com.png
ln -sf usr/bin/com work/com.AppDir/AppRun
cd work && curl -fsSL -o appimagetool \
  https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage
chmod +x appimagetool && APPIMAGE_EXTRACT_AND_RUN=1 ./appimagetool --no-appstream com.AppDir com-x86_64.AppImage
```

> 发布前建议修改包元信息:`build/linux/nfpm/nfpm.yaml`(vendor / homepage / maintainer / 版本)、`build/linux/com.desktop`(菜单显示名)、`build/config.yml` 与 `Taskfile.yml`(应用名 `APP_NAME`)。应用名当前沿用模板默认的 `com`;若改名需同步 `main.go` 的 `application.Options{Name}`、`Taskfile.yml` 的 `APP_NAME`,以及 `go.mod` 模块名并重新生成 bindings。
>
> Linux 包依赖 **GTK4 + WebKitGTK 6.0**(当前构建即此组合);若要用旧版 GTK3 + WebKit2GTK 4.1,需以 `-tags gtk3` 构建并相应调整 `nfpm.yaml` 的 depends。

## 使用说明

1. 点击 **刷新** 枚举串口,在「串口」**下拉框**中选择设备;若列表为空或需要特殊路径,选择下拉中的 **手动输入…** 后填写(未枚举到串口时会自动切到手动输入);
2. 在「波特率」**下拉框**中选择波特率,必要时调整数据位/校验位/停止位,点击 **打开**(按钮变红表示已连接,窗口标题同步显示已连接的串口);
3. 接收区实时显示数据,可切换 HEX/文本、是否显示时间戳,并在 **合并窗口** 中调整接收合并时长(默认 20ms);
4. 在下方输入框输入内容,选择 **文本/HEX** 模式后点击 **发送**(文本框内 `Ctrl+Enter` 快捷发送);需要自动附带校验时,在 **校验后缀** 下拉框选择(如 Modbus CRC16),发送时会自动在帧尾追加校验字节;
5. 需要周期发送时勾选 **定时发送** 并设置间隔;
6. **选择文件…** 或直接填写路径后点击 **发送文件**,进度条显示发送进度,可随时 **取消**;
7. 需要留存数据时点击日志工具栏的 **保存日志…**,在弹出的保存对话框中选择位置与文件名,即可把当前日志导出为本地文本文件(内容随当前 HEX/文本显示模式,含时间戳与收发统计)。

## 目录结构

```
main.go                  应用入口(窗口、服务注册)
serialservice.go         串口服务:打开/关闭、收发、合并窗口、文件发送(绑定给前端)
serialservice_test.go    后端集成测试(用 socat 创建虚拟串口对)
frontend/
  src/components/SerialTerminal.vue   串口调试主界面
  src/App.vue                         根组件
  bindings/                           Wails 自动生成的前端绑定(勿手改)
  public/style.css                    全局样式
build/                   各平台打包资源(Taskfile、图标、打包配置)
docs/images/             README 界面截图
bin/                     构建与打包产物(com、com.deb、com.rpm、com.pkg.tar.zst、com-x86_64.AppImage、com-windows-amd64.exe 等)
```

## 测试

后端集成测试通过 `socat` 创建 PTY 虚拟串口对,覆盖:HEX 解析、合并窗口钳制、打开/关闭、文本与 HEX 发送、接收合并与连续流切分、文件发送与取消、设备拔出状态上报。

```bash
sudo pacman -S socat        # 或 apt install socat
go test . -v
```

## 实现要点

- **串口底层**:[`go.bug.st/serial`](https://pkg.go.dev/go.bug.st/serial)(纯 Go,Linux/Windows/macOS 通用;Windows 自动处理 `COM10+` 命名)。
- **接收合并**:读循环以「窗口」为读超时;窗口内有数据即累积,静默满一个窗口即作为一批上报(事件 `serial:data`),连续数据流按窗口时长/64KB 切分。
- **前后端通信**:Wails 绑定调用(`Open/SendText/SendHex/SendFile/SetMergeWindow/...`)与事件(`serial:data` / `serial:status` / `serial:file`)。
- **发送校验后缀**:在 Go 侧计算并追加(`appendChecksum`):Modbus CRC16 采用多项式 0xA001、初值 0xFFFF、低字节在前;CRC32 为 IEEE 802.3、小端 4 字节;累加和/异或为 1 字节。校验覆盖「附加换行」之后的完整帧,发送接口返回实际写出的完整帧 HEX,TX 日志据此显示。
- **流程控制**:文件发送在 Go 侧分块流式写入,块间延迟,支持 `CancelFileSend()` 取消;读循环异常(如设备拔出)会关闭端口并上报 `serial:status`。

## 作者

**曾记大排档**

## 免责声明

本软件按「现状」提供,仅供学习与合法用途使用,不附带任何明示或暗示的担保。

使用者需自行承担使用风险:因使用本软件造成的设备损坏、数据丢失或其他任何损失,作者不承担责任。请确保在合法合规的前提下使用串口设备与数据。