我做了一个轻量化本地网页版嵌入式调试工具：支持 Serial / TCP / UDP、实时曲线、HEX 发送

iAllen
1 阅读6分钟

logo.png

项目名称：SerialNet Debug Studio

github.com/xiayus/Seri…

前言

平时做嵌入式开发的时候，我经常在几个工具之间来回切换：

  • 看串口日志，用 Arduino Serial Monitor
  • 看波形，用 Arduino Serial Plotter
  • 调 TCP/UDP，又要换网络调试工具
  • 发协议指令时，还得自己处理 HEX、行尾、校验

这些工具单独看都能用，但一旦进入真正的联调阶段，体验就会比较割裂：
串口、网络、日志、曲线、协议发送，基本都不在一个地方。

所以我做了一个本地运行的网页调试工具：SerialNet Debug Studio。它把 Serial / TCP / UDP 放在同一套界面里，同时支持 实时日志、多通道曲线、HEX 发送、行尾控制、校验算法、发送历史，比较适合 Arduino、ESP32、STM32、传感器网关这类项目的开发和联调。仓库当前说明的实现方式是：浏览器负责界面与图表，FastAPI 后端负责串口/TCP/UDP 通信，前后端通过 WebSocket 推送日志和解析数据，本地运行、不依赖数据库和登录。## 这个工具解决了什么问题

我做这个项目，核心不是为了“堆功能”，而是想解决几个很具体的问题。

1. Arduino Serial Monitor 对网络设备不够友好

如果设备是走 USB 串口，那 Arduino 自带工具够用。
但一旦设备跑到 Wi-Fi 上，通过 TCP/UDP 通信，联调体验就会断层：日志一个工具、发包一个工具、看曲线又是另一个工具。

2. 发送区不够协议化

嵌入式联调里，发送经常不是简单发一行字符串，而是要考虑：

  • 文本还是 HEX
  • 行结束符是 LF / CR / CRLF 还是不加
  • 是否需要校验和
  • 是否要把 TX 回显到日志
  • 是否能快速回填历史命令

这些在很多轻量工具里都不完整，但实际上很常用。README 里当前已实现的发送能力包括 Text / HEX 模式、行尾控制、校验算法、TX 回显、Enter 发送、发送历史。

3. 曲线显示需要更适合设备联调

很多时候我不是只想“看日志”，还想直接看传感器数据、ADC、状态量变化。
所以这个项目支持类似 Serial Plotter 的实时曲线，但不是只能画简单数字，而是支持 按通道名动态生成多通道曲线，例如：

temp=23.5,hum=55
adc0:1023,adc1:512,flags=0x01
x=1.2e-3,y=-4

只要设备按这种 key=value 或 key:value 的格式输出，就能自动进入图表。

SerialNet Debug Studio 有哪些功能

目前这个项目已经支持这些能力：

  • Serial（COM） ：本地串口连接、日志查看、发送与解析
  • TCP Client：连接设备主机和端口，做网络联调
  • UDP：支持发送，也可以本地监听
  • 实时日志面板：区分 [RX] / [TX] / [SYS] / [ERR]
  • 实时多通道曲线：适合传感器、ADC、状态量显示
  • 发送面板：支持 Text / HEX、行尾、校验和、发送历史
  • 本地记忆：TCP 地址端口、最近连接、命令历史都会保存在浏览器本地
  • 多语言界面：README 当前写明支持 8 种界面语言
  • 本地优先：无需账号、无需数据库、无需云服务

项目使用的是 FastAPI + Uvicorn + WebSocket + pyserial + 原生 HTML/CSS/JS + ECharts，整体结构比较清晰，后续扩展 MQTT、BLE 或更多协议也有空间。需要说明的是，README 目前把 MQTT、BLE 标在 roadmap 中，不是当前仓库已经落地的功能。

项目怎么跑起来

这个项目的启动方式很直接：

git clone https://github.com/xiayus/SerialNet-Debug-Studio.git
cd SerialNet-Debug-Studio
python -m pip install -r requirements.txt
uvicorn app:app --host 127.0.0.1 --port 8000

然后在浏览器里打开本地 8000 端口即可。README 给出的等价启动方式还包括直接指定 serialnet_debug_studio.app:app --app-dir src。页面加载后会自动连接 /ws

或者release 下载现成的直接运行

功能介绍

串口连接与实时曲线

串口模式下，左侧显示实时日志，右侧显示按通道动态生成的多通道曲线，适合传感器、ADC、状态量等嵌入式数据联调。

串口连接运行截图.png

TCP 调试界面

TCP Client 模式下可直接连接目标主机与端口，在同一界面查看日志、发送指令并观察实时图表。

TCP接口链接运行截图.png

图表自由框选

曲线面板支持自由框选局部时间范围，便于观察一段波形区间内的细节变化。

自由框选图表功能截图.png

命令历史

发送区支持历史命令快速回填，方便重复发送常用调试指令，提高联调效率。

命令历史记录截图.png

我平时怎么用它

场景 1：拿它当串口监视器增强版

如果我在调 Arduino、ESP32、STM32 这类串口设备，最常见的用法就是：

  1. 选择 Serial
  2. 选择串口号、波特率
  3. 连接设备
  4. 左侧看日志，右侧看曲线
  5. 在下方发送区发命令

相比传统串口监视器，这种方式最大的区别是：日志、绘图、协议发送在一个页面里完成。

场景 2：调 ESP32 的 TCP 服务端或客户端

很多 Wi-Fi 设备调试，本质上已经不再是“串口问题”，而是网络链路问题。 这时直接切到 TCP 模式，填设备 IP 和端口，就能继续沿用同样的日志、发送、图表工作流。

场景 3：调 UDP 收发

有些设备上报是 UDP，或者本地工具需要监听某个 UDP 端口。 这个项目目前支持 UDP 发送，也支持 本地监听，所以做轻量收发联调会比较顺手。

这个项目适合谁

我觉得它比较适合这几类开发者：

1. Arduino / ESP32 / STM32 开发者

需要同时看串口日志、发命令、看数值波形的人。

2. 做网络设备联调的人

设备通过 TCP 或 UDP 通信，希望一套界面把日志、发包、波形都整合起来。

3. 想做本地轻量调试台的人

不想引入数据库、账号系统，也不想做成重型桌面软件，只想本地跑起来就能用。

4. 想参考架构的人

这个项目本身也可以当一个范例： FastAPI 做通信后端，WebSocket 推送事件，前端负责统一展示。

仓库 README 里已经把项目结构拆得比较清楚，包括 connection_manager.py、parser.py、serial/tcp/udp transports、以及前端静态资源和本地测试脚本。

后续计划

按当前 roadmap，后面我还在考虑继续往这些方向扩展：

  1. MQTT
  2. BLE
  3. 更多协议适配层
  4. 协议插件化
  5. 更多图表类型
  6. 自定义 JS 解析脚本

结尾

如果你平时也在做 Arduino、ESP32、STM32 或其他嵌入式设备联调，欢迎体验一下这个项目，也欢迎提 issue 或交流想法。

avatar
文章
阅读
粉丝