跨平台串口与 BLE 蓝牙通信调试工具
功能特性 • 技术栈 • 环境要求 • 安装 • 使用指南 • 开发指南 • 项目结构
ComBridge 是一款基于 Tauri 2.0 构建的跨平台串口与 BLE 蓝牙通信调试工具,专为嵌入式开发者、物联网工程师和硬件调试场景设计。支持串口通信、原生 BLE 和 AT 指令 BLE 双模式,提供灵活的协议插件系统、可配置的 Dashboard 仪表盘和波形数据展示,帮助开发者高效地进行设备通信调试。
- 自动扫描可用串口设备
- 支持自定义波特率、数据位、校验位、停止位
- 实时数据收发与十六进制/文本显示
- 数据发送历史记录
- 数据导出功能(日志文件 + 原始数据)
- 原生 BLE 模式:直接使用操作系统原生蓝牙 API
- AT 指令 BLE 模式:通过串口 + AT 指令控制 BLE 模块(支持 ESP32、N32WB 等)
- 设备扫描与信号强度显示
- GATT 服务/特征浏览
- 特征值读写与通知订阅
- 连接参数配置(MTU、PHY、连接间隔)
- Lua 脚本驱动的协议解析
- 支持自定义数据解析钩子
- 协议与设备灵活绑定
- 内置 GH3036 协议支持
- 预置常用协议解析脚本(CSV、JSON、IMU、NMEA)
- 可配置的 Widget 展示系统
- Lua 脚本数据解析
- JSON 配置文件定义 Widget 布局
- 支持多种 Widget 类型:
- 文本显示
- 仪表盘
- LED 指示灯
- 加速度计
- 指南针
- 折线图
- 脚本热加载与动态切换
- 多通道实时波形显示
- 支持 CSV、JSON、二进制等多种数据格式
- 可配置的缓冲区大小
- 数据解析器支持
- CSV 文件导入功能
- 多连接管理
- 自动重连与心跳维护
- 消息收发监控
- Nordic SMP(Zephyr MCUmgr over BLE)+ MCUboot
.zip固件包校验、设备预检、进度展示与取消- 协议可扩展(
OtaProtocol+ProtocolRegistry)
- 基于 Ant Design v6.3.5 的美观 UI
- 深色/浅色主题切换
- 多标签页管理
- 国际化支持(中文/英文)
- 自定义无标题栏窗口
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端框架 | React 19 + TypeScript | UI 构建 |
| 状态管理 | Zustand | 轻量级状态管理 |
| UI 组件库 | Ant Design v6.3.5 | 企业级 UI 组件 |
| 路由 | React Router v7 | 页面路由管理 |
| 国际化 | react-i18next | 多语言支持 |
| 图表库 | ECharts + Recharts | 数据可视化 |
| 构建工具 | Vite | 快速开发构建 |
| 后端框架 | Tauri 2.0 (Rust) | 跨平台桌面应用 |
| 异步运行时 | Tokio | Rust 异步运行时 |
| 串口通信 | serialport-rs | 跨平台串口库 |
| BLE 通信 | bluest | Rust 蓝牙库 |
| 脚本引擎 | mlua | Lua 脚本支持 |
| 日志系统 | tracing + tracing-subscriber | 结构化日志 |
| 数据序列化 | Serde + Serde JSON + CSV | 数据序列化 |
- Windows: Windows 10/11 (x64)
- macOS: macOS 10.15+ (Intel & Apple Silicon)
- Linux: Ubuntu 18.04+ / Debian 10+ (x64)
- Node.js: >= 18.0.0
- Rust: >= 1.85.0(OTA 依赖
mcumgr-toolkit 0.20要求;其余功能最低 1.70.0) - pnpm/npm/yarn: 任意包管理器
Windows:
- Microsoft Visual Studio C++ Build Tools
- WebView2 (Windows 10/11 已内置)
macOS:
- Xcode Command Line Tools:
xcode-select --install
Linux (Ubuntu/Debian):
sudo apt install libwebkit2gtk-4.0-dev build-essential curl wget file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev- 固件包必须为
.zip(nrfutil 产线包格式:manifest.json+ MCUboot 签名的.bin) - 不支持裸
.bin文件
- 启用 MCUmgr BLE 传输:
CONFIG_MCUMGR_TRANSPORT_BT=y - 性能建议:
CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE=4096 - AT 模式为实验性支持,OTA 验收以 native BLE 为准
前往 Releases 页面下载对应平台的安装包:
- Windows:
.msi或.exe安装程序 - macOS:
.dmg安装包 - Linux:
.AppImage或.deb包
# 克隆仓库
git clone https://github.com/XiaoPb/combridge.git
cd combridge
# 安装前端依赖
npm install
# 开发模式运行
npm run tauri dev
# 构建生产版本
npm run tauri build- 点击左侧导航栏「串口」进入串口页面
- 点击「扫描」按钮扫描可用串口
- 选择目标串口,配置波特率等参数
- 点击「连接」打开串口
- 在发送面板输入数据,选择发送格式(文本/十六进制)
- 接收数据将在数据视图中实时显示
- 可通过导出功能保存通信数据
- 点击左侧导航栏「BLE」进入 BLE 页面
- 选择「原生模式」
- 点击「扫描」搜索周围 BLE 设备
- 点击目标设备进行连接
- 浏览 GATT 服务和特征
- 对特征进行读写或订阅通知
- 选择「AT 模式」
- 配置 AT 模块连接的串口
- 后续操作与原生模式相同
- 点击左侧导航栏「Dashboard」进入仪表盘页面
- 选择数据源(串口/BLE 设备)
- 选择解析脚本(或使用预置脚本)
- 导入或编辑 JSON 配置文件定义 Widget 布局
- Widget 将实时显示解析后的数据
- 点击左侧导航栏「波形」进入波形页面
- 配置波形缓冲区参数
- 选择数据解析器类型(CSV/JSON/二进制)
- 选择数据源并开始接收数据
- 波形图将实时显示数据变化
- 支持导入 CSV 文件进行离线分析
- 点击左侧导航栏「协议」进入协议页面
- 点击「加载协议」选择 Lua 脚本文件
- 在绑定配置中将协议绑定到设备
- 设备数据将自动经过协议解析
combridge-rust/
├── src/ # 前端源码 (React + TypeScript)
│ ├── api/ # Tauri API 封装
│ │ ├── index.ts # API 导出
│ │ ├── tauri.ts # Tauri 命令封装
│ │ ├── events.ts # 事件监听封装
│ │ ├── stateApi.ts # 状态管理 API
│ │ ├── waveform.ts # 波形 API
│ │ ├── gh3036.ts # GH3036 API
│ │ └── dashboard.ts # Dashboard API
│ ├── components/ # 公共组件
│ │ ├── Common/ # 通用组件
│ │ ├── Layout/ # 布局组件
│ │ ├── TitleBar/ # 标题栏组件
│ │ └── DataLogger/ # 数据日志组件
│ ├── hooks/ # 自定义 Hooks
│ │ ├── useSerial.ts # 串口 Hook
│ │ ├── useBle.ts # BLE Hook
│ │ ├── useProtocol.ts # 协议 Hook
│ │ ├── useWaveform.ts # 波形 Hook
│ │ ├── useAppDispatch.ts # 应用调度 Hook
│ │ ├── useAppState.ts # 应用状态 Hook
│ │ ├── useConnectedDevices.ts # 已连接设备 Hook
│ │ ├── useDataParser.ts # 数据解析 Hook
│ │ ├── useDebounce.ts # 防抖 Hook
│ │ ├── useLog.ts # 日志 Hook
│ │ ├── useModuleSubscribe.ts # 模块订阅 Hook
│ │ ├── useNotification.ts # 通知 Hook
│ │ └── useTheme.ts # 主题 Hook
│ ├── i18n/ # 国际化配置
│ ├── locales/ # 多语言资源
│ │ ├── zh-CN/ # 中文
│ │ └── en-US/ # 英文
│ ├── pages/ # 页面组件
│ │ ├── Home/ # 首页
│ │ ├── Serial/ # 串口页面
│ │ ├── Ble/ # BLE 页面
│ │ ├── Protocol/ # 协议页面
│ │ ├── Dashboard/ # Dashboard 页面
│ │ ├── Waveform/ # 波形页面
│ │ ├── Gh3036/ # GH3036 页面
│ │ └── System/ # 系统页面
│ ├── services/ # 服务层
│ │ ├── eventListeners.ts # 事件监听器
│ │ ├── messageParser.ts # 消息解析
│ │ ├── storageService.ts # 存储服务
│ │ └── dataFormatter.ts # 数据格式化服务
│ ├── stores/ # Zustand 状态管理
│ │ ├── serialStore.ts # 串口状态
│ │ ├── bleStore.ts # BLE 状态
│ │ ├── protocolStore.ts # 协议状态
│ │ ├── dashboardStore.ts # Dashboard 状态
│ │ ├── waveformStore.ts # 波形状态
│ │ ├── gh3036Store.ts # GH3036 状态
│ │ ├── configStore.ts # 配置状态
│ │ ├── csvChartStore.ts # CSV 图表状态
│ │ ├── logStore.ts # 日志状态
│ │ ├── notificationStore.ts # 通知状态
│ │ └── pageTabsStore.ts # 页面标签状态
│ ├── types/ # TypeScript 类型定义
│ └── utils/ # 工具函数
│
├── src-tauri/ # Tauri 后端 (Rust)
│ ├── src/
│ │ ├── main.rs # 应用入口
│ │ ├── lib.rs # 模块导出与配置
│ │ ├── compat.rs # 系统兼容性检测
│ │ ├── error.rs # 错误定义
│ │ ├── commands/ # Tauri 命令
│ │ │ ├── serial.rs # 串口命令
│ │ │ ├── ble.rs # BLE 命令
│ │ │ ├── protocol.rs # 协议命令
│ │ │ ├── waveform.rs # 波形命令
│ │ │ ├── gh3036.rs # GH3036 命令
│ │ │ ├── state.rs # 状态命令
│ │ │ ├── system.rs # 系统命令
│ │ │ ├── websocket.rs # WebSocket 命令
│ │ │ └── preferences.rs # 偏好设置命令
│ │ ├── device/ # 设备管理
│ │ │ ├── device_manager.rs # 设备管理器
│ │ │ ├── cache.rs # 设备缓存
│ │ │ ├── serial/ # 串口模块
│ │ │ │ ├── serial_manager.rs
│ │ │ │ ├── serial_config.rs
│ │ │ │ └── serial_port.rs
│ │ │ └── ble/ # BLE 模块
│ │ │ ├── ble_manager.rs
│ │ │ ├── ble_traits.rs
│ │ │ ├── native/ # 原生 BLE
│ │ │ │ ├── adapter.rs
│ │ │ │ ├── gatt_client.rs
│ │ │ │ └── native_backend.rs
│ │ │ └── at/ # AT 指令 BLE
│ │ │ ├── at_backend.rs
│ │ │ ├── at_cache.rs
│ │ │ ├── at_commands.rs
│ │ │ ├── at_parser.rs
│ │ │ └── at_transport.rs
│ │ ├── dashboard/ # Dashboard 模块
│ │ │ ├── commands.rs # Dashboard 命令
│ │ │ ├── parser_scripts.rs # 解析脚本管理
│ │ │ └── json_config.rs # JSON 配置管理
│ │ ├── waveform/ # 波形模块
│ │ │ ├── buffer.rs # 波形缓冲区
│ │ │ └── parser.rs # 数据解析器
│ │ ├── gh3036/ # GH3036 协议
│ │ │ ├── manager.rs # GH3036 管理器
│ │ │ ├── types.rs # 类型定义
│ │ │ ├── config_loader.rs # 配置加载
│ │ │ ├── factory_test.rs # 工厂测试
│ │ │ ├── csv_writer.rs # CSV 写入器
│ │ │ └── threshold_config.rs # 阈值配置
│ │ ├── protocol/ # 协议插件
│ │ │ ├── lua_engine.rs # Lua 引擎
│ │ │ ├── plugin_manager.rs # 插件管理
│ │ │ ├── hook_executor.rs # 钩子执行器
│ │ │ └── script_loader.rs # 脚本加载器
│ │ ├── service/ # 服务层
│ │ │ ├── event_bus.rs # 事件总线
│ │ │ ├── event_bridge.rs # 事件桥接
│ │ │ ├── logger.rs # 日志服务
│ │ │ ├── config.rs # 配置服务
│ │ │ ├── data_queue.rs # 数据队列
│ │ │ └── msgpack_handler.rs # MsgPack 处理器
│ │ ├── state/ # 状态管理
│ │ │ ├── app_state.rs # 应用状态
│ │ │ ├── action.rs # 状态动作
│ │ │ ├── dispatcher.rs # 状态分发器
│ │ │ ├── persistence.rs # 状态持久化
│ │ │ └── types.rs # 状态类型
│ │ └── websocket/ # WebSocket 客户端
│ │ ├── client.rs # WebSocket 客户端
│ │ ├── connection_pool.rs # 连接池
│ │ ├── message_handler.rs # 消息处理器
│ │ └── reconnection.rs # 重连机制
│ ├── parser_scripts/ # 预置 Lua 解析脚本
│ │ ├── csv_parser.lua
│ │ ├── json_parser.lua
│ │ ├── json.lua # JSON 库
│ │ ├── imu_parser.lua
│ │ ├── nmea_parser.lua
│ │ └── custom_example.lua # 自定义示例
│ ├── capabilities/ # Tauri 权限配置
│ ├── Cargo.toml # Rust 依赖配置
│ └── tauri.conf.json # Tauri 配置
│
├── libs/ # C/C++ 库
│ └── protocol_rust/ # GH3036 协议库
│ ├── gh-rpc/ # GH-RPC 通信库
│ └── rpc/ # RPC 框架
│
├── config/ # 配置文件
│ └── factory/ # 工厂配置
│ └── factory_config_GH3036.yaml
│
└── docs/ # 文档
├── api.md # API 文档
├── architecture/ # 架构文档
│ ├── README.md # 架构概览
│ ├── backend/ # 后端模块文档
│ └── frontend/ # 前端模块文档
└── device-management.md # 设备管理文档
# 安装依赖
npm install
# 启动开发服务器
npm run tauri dev
# 构建生产版本
npm run tauri build
# 类型检查
npm run build
# Rust 代码检查
cd src-tauri && cargo clippy
# Rust 代码格式化
cd src-tauri && cargo fmt-
Rust:
- 使用
rustfmt默认配置 clippy严格模式- 蛇形命名(snake_case)
- 错误处理使用
thiserror+ 自定义Result类型
- 使用
-
TypeScript/React:
- 函数组件 + Hooks
- 使用
interface定义 Props - 驼峰命名(camelCase)
- 避免使用
any
- 在
src-tauri/src/commands/对应模块添加函数 - 使用
#[tauri::command]宏标记 - 在
src-tauri/src/lib.rs的.invoke_handler()中注册 - 在前端
src/api/添加封装函数 - 更新
docs/api.md文档
- 编写 Lua 协议解析脚本
- 将脚本放入
src-tauri/parser_scripts/目录 - 通过「协议」页面加载脚本
- 绑定到目标设备
- 在
src/pages/Dashboard/widgets/创建 Widget 组件 - 定义 Widget 的配置接口
- 在
WidgetRenderer.tsx中添加渲染逻辑 - 更新 JSON 配置 Schema
- 单元测试:核心设备管理逻辑(SerialManager、BleManager)有单元测试
- 集成测试:BLE 双模式切换、协议加载/绑定流程有集成测试
- 前端测试:关键页面组件(SerialPage、BlePage)有渲染和交互测试
详细的架构文档请参阅 docs/architecture/README.md
本项目采用 MIT 许可证 - 详见 LICENSE 文件。
欢迎提交 Issue 和 Pull Request!
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
Made with ❤️ by XiaoPb