面向硬件工程师的可视化上位机设计工具
官网 • 使用说明 • 演示视频 • 快速开始 • 功能特性 • 协议文档 • 常见问题
PyQt UI Designer 是一个零代码 / 低代码的桌面上位机设计器。拖拽控件、配置属性、绑定串口、TCP 或 MQTT 数据，就能生成可独立运行的 PyQt5 上位机程序，并在 Windows 打包为 exe、在 macOS 打包为 .app。不必再为每个硬件项目从零手写界面、通信收发和协议解析。
点击图片前往 B 站观看。视频演示了从拖拽设计、数据绑定、实时预览到导出打包的完整流程，画面均为软件实际运行录屏。
从 Releases 或官网下载对应平台的压缩包。压缩包内已包含 Python 和 Qt，不需要另外安装。
| 平台 | 文件 | 运行方式 |
|---|---|---|
| Windows 10/11 | PyQt-UI-Designer-vX.Y.Z-windows-x64.zip |
解压后运行 main.exe |
| macOS（Apple Silicon） | PyQt-UI-Designer-vX.Y.Z-macos-arm64.zip |
解压后打开 .app |
| macOS（Intel） | PyQt-UI-Designer-vX.Y.Z-macos-x64.zip |
解压后打开 .app |
每个压缩包都附带 .sha256 校验文件。安装包没有做代码签名，第一次打开时系统可能会拦截，处理方法见常见问题。
仓库里的 demo 包含可编辑的 .uidp 工程、设计器导出的完整代码和模拟串口设备。按下文"从源码运行"安装好依赖后，在仓库根目录运行：
python demo/simulate.py选择 DEMO 端口并连接，就能看到温度、压力采集、双通道实时曲线、运行状态和命令发送。连接真实设备时运行 python demo/main.py。整个 demo 文件夹也可以复制到仓库外独立运行。
环境要求：Python 3.10+，Windows 10/11 或 macOS（Apple Silicon / Intel）。
Windows：
git clone https://github.com/txp666/PyQt-UI-Designer.git
cd PyQt-UI-Designer
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.pymacOS：
git clone https://github.com/txp666/PyQt-UI-Designer.git
cd PyQt-UI-Designer
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python main.pyApple Silicon 请使用原生 arm64 Python，Intel Mac 使用 x86_64 Python。依赖清单已包含 Apple Silicon 所需的 Qt 5 运行库条件，不要另行固定为只有 Intel 安装包的旧版 Qt。
- 拖拽式 UI 设计，所见即所得
- 网格吸附与对齐辅助（左 / 右 / 顶 / 底对齐、横纵分布）
- 画布大小自由设置，支持缩放
- 深色 / 浅色主题切换，Windows 11 云母效果
- 工程文件
.uidp保存与加载
| 分类 | 控件 |
|---|---|
| 基础控件 | 按钮、标签、输入框、下拉框、开关、滑块、数值框 |
| 布局控件 | 水平布局、垂直布局、弹性布局、分组框、选项卡、分割线、卡片容器 |
| 显示控件 | LED 指示灯、数值显示、进度条、进度环、图片显示 |
| 图表控件 | 实时曲线（多通道、游标、数据保存 / 加载）、仪表盘 |
| 通信控件 | 数据表格 |
| 复合控件 | 串口配置卡片、TCP 配置卡片、MQTT 配置卡片、数据发送卡片、数据接收卡片、Modbus 配置卡片、日志显示框 |
- 串口管理：自动扫描端口，可配置波特率、数据位、校验位、停止位和流控
- TCP 客户端 / 服务端：客户端连接设备，或者监听端口让设备主动连入；服务端可同时接多个设备，每个连接独立切帧
- MQTT 订阅 / 发布：连接 broker，订阅一个或多个主题（支持
+、#通配符）接收数据，命令发布到指定主题；支持用户名密码、QoS 0/1/2 和 TLS - 三种链路共用同一套解析模式、数据绑定、曲线、表格和日志；命令会发往每一条已连接的链路
- 键值匹配：解析
key1=value1,key2=value2、JSON 顶层字段或 CSV（自动命名为ch0、ch1…） - JSON 路径：解析 JSON 数据，支持嵌套路径
- HEX 字节提取：从二进制帧中按偏移提取数据，支持多种数据类型
- Modbus RTU：完整的寄存器解析，支持多种数据类型、字节序和功能码过滤，正常响应和异常响应都校验 CRC
- Modbus TCP：按 MBAP 头切帧，输出与 RTU 完全相同的字典，绑定配置通用
- 串口、TCP、MQTT 都提供四种解析模式（行文本、HEX 帧、Modbus RTU、Modbus TCP），并能自动识别行协议格式
- 文本模式：可选换行符
- HEX 模式：支持帧头帧尾和数据类型打包
- Modbus 模式：自动组帧并支持轮询；按链路选择帧格式，解析模式为
modbus_tcp的链路发 MBAP 帧，其余链路发带 CRC 的 RTU 帧 - 命令模板：用
{value}占位符插入控件当前的值
- 一键导出为可独立运行的 Python 项目（
main.py、ui.py、comm_hub.py、serial_handler.py、tcp_handler.py、mqtt_handler.py、data_binding.py、theme_support.py） - 内置 Nuitka 一键打包，实时显示编译输出；完成后自动清理编译缓存、重命名并压缩为 zip
- 自定义上位机名称，会同步到窗口标题和打包产物
| 协议 | 状态 | 说明 |
|---|---|---|
| 串口（Serial） | ✅ 已支持 | RS-232/485/TTL，支持行文本、HEX 帧、Modbus RTU 解析 |
| TCP Client/Server | ✅ 已支持 | TCP 客户端或服务端，服务端支持多个设备连入；解析模式与串口相同，另支持 Modbus TCP（MBAP），选 modbus_tcp 后 Modbus 命令自动按 MBAP 组帧 |
| MQTT | ✅ 已支持 | 订阅 / 发布，支持通配符主题、用户名密码、QoS 0/1/2 和 TLS；每条消息按一帧解析，纯数值载荷可按主题名绑定 |
| UDP | 📋 计划中 | UDP 数据报通信 |
| Bluetooth | 📋 计划中 | 蓝牙串口（SPP）/ BLE |
通信部分采用模块化架构：每条链路实现同一组信号，由 CommHub 汇总后供绑定、图表、表格和日志使用，方便扩展更多协议，欢迎贡献 PR。链路细节见 docs/protocol.md。
完整的图文说明见官网使用说明，协议格式见 docs/protocol.md。
- 设计界面：从左侧控件面板把控件拖到画布上，在右侧属性编辑器里配置属性。
- 绑定数据：选中显示类控件（数值显示、LED、进度条等），设置"绑定键"（设备数据中的字段名）和"解析模式"（键值匹配、JSON 路径、HEX 字节提取或 Modbus）。
- 配置命令：选中交互类控件（按钮、开关、滑块等），设置发送模式（文本、HEX 或 Modbus）、命令内容，以及可选的
{value}命令模板。 - 预览运行：切换到"预览运行"页面，点击"运行预览"，用串口、TCP 或 MQTT 配置卡片连接设备后即可实时测试。
- 导出与打包：导出代码的快捷键在 Windows 上是
Ctrl+Shift+E，在 Mac 上是⌘⇧E，也可以点击导航栏的"导出代码"；在预览页面点击"一键打包"，选择目录后会自动导出、用 Nuitka 编译并压缩。打包需要本机有 C/C++ 编译器：macOS 使用 Xcode Command Line Tools，Windows 使用 Nuitka 支持的编译器（Python 3.13+ 使用 MSVC）。
数据解析规则
行文本必须以实际 LF（\n，也支持 CRLF）结束；接收半包时等待下一批字节，同批多帧按顺序全部处理。JSON 字符串内部的转义 \n 保留为内容。Modbus 正常响应和异常响应都校验 CRC，损坏帧不会更新控件。
滑块、数值框、进度条、进度环和仪表盘会忽略无法转换的数据，其中整数控件拒绝超出 Qt 整数范围的值，仪表盘拒绝 NaN/Infinity；同帧其他绑定继续更新。开关支持明确的布尔文本和数值，未知文本不改变状态；LED 自定义亮灭值优先。预览与独立导出使用相同规则，HEX 帧头尾的奇数位十六进制文本自动在前面补零。
串口、TCP 和 MQTT 配置卡片的"默认解析模式"可选 line、hex、modbus、modbus_tcp 或"项目设置"。"项目设置"使用 .uidp 的 serial.parser / parserConfig，默认是行文本，三种链路共用这一份帧格式配置。数据位、校验位、停止位、流控和解析模式在预览与导出程序中使用同一份实现。切换到其他解析模式时使用对应模式的配置，选择"项目设置"恢复工程配置。
TCP 服务端为每个连入的设备单独切帧，命令会写给所有已连接的设备。MQTT 把每条消息当作一帧：行文本模式下没有换行结尾的载荷也会解析；只有一个纯数值的载荷还会以主题名为键再给出一份，方便直接用主题名绑定；HEX 帧按主题各自缓存半包。多条链路同时连接时，命令会发往每一条已连接的链路。
实时曲线与历史数据
实时曲线约每 33ms 批量刷新，每通道显示缓存最多 10,000 点。全部采样另存到系统临时文件，"保存"会导出完整历史 CSV/JSON，超过显示缓存的部分也会保留。清空曲线、停止预览或关闭控件后临时记录释放，请先保存需要保留的数据。大文件建议使用 CSV，CSV 加载和历史导出均按流处理。
加载历史曲线保留当前采集绑定、解析模式和通道勾选状态。已有配置的图表要求文件通道名称、数量匹配，唯一名称可以乱序；不匹配时提示错误并保留原数据。空白且未配置的默认图表仍可导入新通道。
异常数值不会中断同帧其他曲线通道，也不会写入历史。含非有限数或非法数值的历史文件会被拒绝，当前数据保持不变。JSON 在通道名唯一时仍使用名称到样本数组的对象格式；同名通道使用有序的 name / values 通道数组，避免重复键丢数据，并兼容读取旧格式。
预览、命令与工程编辑
开关、滑块和数值框支持接收数据回填；设备回填不会触发命令发送，用户操作仍按配置发送。快速断开重连时，旧连接排队的数据和错误会被忽略。
修改设计、打开其他工程或新建工程会停止旧预览并断开连接；重新运行后使用当前设计，避免发送旧命令。停止预览会释放控件及其定时器和信号连接，可连续启停。
Modbus 按钮只使用当前可见的协议设置，非法地址、数量或数值不会发送；HEX 内容、帧头尾和二进制数值在预览与导出中使用同一编码规则。Modbus 卡片只有在完整写入命令后才显示"已发送"；写入失败或短写会提示失败并停止轮询，"已发送"不代表设备已确认执行。Modbus 开关在预览和导出中都发送 FC05 写单线圈命令。
新建、打开和退出时，会提供"保存 / 放弃 / 取消"选择。取消保存或保存失败会中止切换；项目在保存和载入前均校验，失败保留当前画布及已有文件。保存通过同目录临时文件原子替换，避免写入中断直接破坏原文件。尺寸编辑遵守控件最小宽高，多标签页独立保存布局及子控件位置。
标签名称在离开编辑框或保存、预览、导出时应用，避免输入中间状态改变控件所属页面。减少页数时，超出页的控件移到最后一页；空名称保留一个默认页。跨容器对齐使用画布坐标，自动布局中的子控件继续由布局管理。
导出细节与主题
导出会保留按钮禁用状态、输入框默认文本和只读状态、下拉框默认选项。发送、接收、表格、日志、Modbus 以及串口 / TCP / MQTT 配置卡片的自定义属性会保留到导出程序；表格和日志自动接收所有链路的数据，接收区中的 <、> 等内容按原文显示。
导出与打包继承设置页当前的浅色、深色或"跟随系统"模式。"跟随系统"会在独立程序启动及系统外观变化时更新。主题切换同步设计画布、运行预览、原生 Qt 控件及曲线配色，保留控件值、曲线历史、复选状态和自定义字号 / 颜色；接收与日志终端保持深色底以兼容已有彩色消息。
图片控件使用的本地文件会复制到导出目录的 assets/，随整个项目移动后仍可加载；相对图片路径以已保存工程所在目录为基准，未保存工程以当前工作目录为基准。图片文件不存在或不可读时，导出会提示错误。
导入工程的控件 ID 可包含空格、引号和中文，导出时保留为字典键。代码生成及语法检查完成后才写入目标目录，配置错误不会先覆盖已有的导出文件。
macOS 操作提示
- 新建、打开、保存分别使用
⌘N、⌘O、⌘S。 - 选中画布控件后按
Delete（⌫）删除；Fn+Delete同样支持。 - 触控板双指滚动平移画布，按住
⌘滚动缩放。 - 串口一般显示为
/dev/cu.usbserial-*或/dev/cu.usbmodem*，保留设备路径大小写；USB 转串口驱动按芯片厂商要求安装。 - "打开输出目录"使用 Finder；云母效果仅在 Windows 11 可用。
- 源码运行时，一键打包优先使用当前虚拟环境。独立
.app中的一键打包仍需另外安装 Python 与编译工具；可在终端激活安装了本项目依赖的虚拟环境后启动应用。 - 找到的 Python 缺少打包依赖时，会在导出目录创建
.build-venv再安装依赖，兼容 Homebrew 的系统 Python 保护机制；后续打包可复用此环境。
Windows 提示"Windows 已保护你的电脑"：exe 没有数字签名（代码签名证书需要付费购买），不是病毒。点击"更多信息"→"仍要运行"即可。
macOS 提示无法验证开发者：.app 没有做 Apple Developer ID 签名和公证。第一次打开被拦截后，到"系统设置 → 隐私与安全性"中点击"仍要打开"。
更多问题（找不到串口、控件不刷新、曲线数据保存等）见官网常见问题。
python -m unittest discover -s tests -v
python tests/smoke_gui.py第二项需要可用的桌面会话，会打开设计器及导出的测试程序，然后自动退出。macOS 的无边框窗口依赖 Cocoa，不能用 Qt offscreen 插件代替原生窗口验证。
python deploy.pymacOS 首次打包前先安装编译工具：
xcode-select --install
source .venv/bin/activate
python deploy.py
open "build/PyQt UI Designer.app"输出为 build/PyQt UI Designer.app 和同名 zip；Windows 输出为 build/PyQt UI Designer/main.exe 和同名 zip。两者都包含 Python、Qt 和图标资源，运行产物无需再安装 Python。打包按本机 Python 的架构生成，不支持在 Windows 交叉编译 Mac 应用。最低 macOS 版本取决于用于构建的 Python、Qt 和编译工具，请以 Nuitka 构建日志为准。
.app 压缩使用 macOS ditto，保留可执行权限和框架符号链接。默认构建未做 Apple Developer ID 签名与公证，对外分发前需另行处理。
同步 app/common/metadata.py 中的版本号与 docs/release-notes/vX.Y.Z.md，提交后推送对应的 vX.Y.Z 标签。GitHub Actions 会构建三个平台、验证压缩包校验值及解压后的应用启动，全部通过后才发布 GitHub Release。
PyQt-UI-Designer/
├── main.py # 程序入口
├── deploy.py # 打包设计器本身（Nuitka）
├── requirements.txt # 依赖清单
├── app/
│ ├── common/ # 配置、版本信息、打包支持、更新检查
│ ├── core/ # 工程读写、数据绑定、协议解析、串口 / TCP / MQTT 运行时、代码生成
│ ├── designer/ # 设计画布、控件面板、属性编辑器、选择与对齐
│ ├── view/ # 主窗口，以及设计器、预览运行、设置页面
│ └── widgets/ # 控件定义：基础、布局、显示、图表、通信、复合
├── demo/ # 可独立运行的导出示例、源工程与模拟设备
├── examples/tutorials/ # 视频教程里搭建的工程（.uidp）及各自的数据格式
├── docs/
│ ├── protocol.md # 通信协议文档
│ └── release-notes/ # 各版本发布说明
├── images/ # README 图片
└── tests/ # 单元测试与冒烟测试
- PyQt5：GUI 框架
- PyQt-Fluent-Widgets：Fluent Design 风格控件库
- pyqtgraph：高性能实时图表
- pyserial：串口通信
- paho-mqtt：MQTT 客户端
- truststore：用操作系统的证书库校验 HTTPS 和 MQTT TLS 连接
- Nuitka：把 Python 编译打包为 Windows exe / macOS
.app
遇到问题或有功能建议，欢迎提交 Issue。UDP、蓝牙等协议在计划中，也欢迎提交 PR。
本项目采用 GPLv3 许可证开源。