WaveDrom 时序图绘制：从JSON到图形，文本化描述让波形文档可版本管理

简介面向FPGA开发、数字电路与硬件验证人员Wavedrom Editor 2.3.2 Windows 64位离线版专注于时序图快速绘制解决网络受限环境中不易获取官方工具、以及手工画图效率低的问题。压缩包共124个文件整体约83.72MB以exe主程序、dll动态运行库、pak界面与资源文件、info配置信息及html启动页为主结构完整解压后即可在Windows 64位系统独立使用。目前CSDN平台已有2159人学习下载。工具采用文本语法驱动绘图可通过简单描述生成上升沿、下降沿、高电平等常见波形并支持注释、标签和颜色标注便于表达复杂时序关系实时预览所见即所得波形可导出为SVG、PNG等格式方便嵌入设计文档或评审材料文本源码也便于版本管理内置示例可帮助新手快速掌握语法。整体上能显著提升硬件开发中的信号沟通与排错效率。 做数字电路调试的兄弟大概都有过这种经历改了 RTL 之后要更新波形文档发现上次画的时序图还是用 Visio 手工拉的线改一个信号名就得拖半天。wavedrom-editor 这类工具出现就是把“画时序图”变成了“写时序图”用一段 JSON 描述信号电平变化保存成文本文件随时能改、能 diff、能进 Git。我最近一直在用 wavedrom-editor-v2.3.2-win-x64.zip 这个版本在 Windows 10/11 的 64 位环境下解压即用所以这篇就把下载、上手、实操和踩过的一些坑一起聊透。这类工具适合的范围很明确FPGA 工程师、ASIC 前端、嵌入式驱动开发只要你的文档里需要 SPI、I2C、DDR、总线握手这类时序图WaveDrom 都能比画图软件快出一个量级。尤其是经常要更新规格书的人文本化描述几乎解决了时序图维护的所有痛点。这篇文章我尽量不堆概念直接给能用的经验和完整的示例。1. 这个工具到底解决什么问题1.1 从“画图”到“写代码”时序图也能版本管理传统画时序图最无语的地方不是画的时候慢而是后续修改成本极高。比如上面芯片手册里的读时序原来画的是 8 个时钟周期现在需求变成 16 个周期整个波形图得重新拉一遍。坐标、对齐、线宽、字体任何一个变了都要反复调。WaveDrom 的思路是彻底反过来的图形只是 JSON 数据的一种渲染结果。你写这段描述{ signal: [ { name: clk, wave: p...... }, { name: data, wave: x.345x } ] }保存后在编辑器里打开就是一个完整时序图。想改周期数改字符串长度就行想加信号在数组里加一个对象就行。这意味着一张时序图变成了一个纯文本文件你可以提交到 Git 里和 RTL 代码一起评审改了一版波形review 的人能直接看到 diff。这是 WaveDrom 比 Visio、PPT 强最核心的一点。所以千万不要把 WaveDrom 理解成“又一个画图工具”它本质是“面向时序图的声明式绘图语言”。一旦习惯这种思路你会发现自己写文档的速度至少快一倍。1.2 为什么我推荐 win-x64 zip 版本网上能下到的 WaveDrom Editor 版本不少有在线 Web 版也有安装包版。我选 v2.3.2 win-x64 zip 版本理由很直白不需要安装解压就能跑。做硬件和嵌入式的人电脑上经常装了一堆 EDA 软件许可证、环境变量、注册表互相打架是常事。zip 绿色版就没有这个烦恼解压出来是一个独立目录不写注册表不装服务卸载直接删文件夹。放在移动硬盘或者 U 盘里插到哪台 Windows 电脑上都能用特别适合公司统一配发的“锁权限”办公机。另一个原因是为了离线。很多开发环境不能连外网在线编辑器再方便也白搭。这个 zip 包启动后就是一个本地 Electron 应用所有功能都在本地执行不依赖网络打开就能写波形文档也没有数据泄露风险。对于要签保密协议的岗位来说这是很实在的加分项。2. 拿到压缩包之后解压、运行与前置环境2.1 解压即用但别放在中文路径和系统目录下载下来的文件名是 wavedrom-editor-v2.3.2-win-x64.zip注意它只适用 64 位 Windows。双击压缩包解压后里面一般是一个目录目录里有可执行文件和相关资源。首次使用我建议直接右键解压到当前目录不要直接在压缩包里双击运行。原因很简单Electron 应用的运行需要读取不少子目录资源在压缩包内直接运行会由于临时目录路径或权限问题报错。解压时有两个容易踩的坑。第一路径里不要带中文和特殊字符。虽然现代 Windows 对 Unicode 路径支持已经很好了但 Electron 底层在加载资源时遇到中文路径偶尔会出幺蛾子表现形式是启动后白屏或者某个功能按钮点了没反应。第二别把它解压到C:\Program Files这类系统保护目录。绿色软件没有管理员权限的安装过程放在系统目录下经常遇到写入失败而且每次弹 UAC 也很烦放到D:\Tools之类的工作目录最省心。2.2 x64 与 x86下载错版本会看到什么“win-x64”代表这个版本是为 x86-64 架构编译的。现在市面上的 Windows 电脑基本都是 64 位但也有少数人维护老设备用的是 32 位系统。如果你在 32 位系统上双击 x64 版本最直接的是提示“不是有效的 Win32 应用程序”或者提示缺少某个 DLL。反过来说如果你在 64 位系统上装了 x86 版本一般也能跑只是无法发挥 64 位优势而已。还有一类报错长得比较误导人就是启动时提示“无法定位程序输入点于动态链接库”。这种情况最常见的原因不是版本不对而是机器上缺少对应的 Visual C 运行库。Electron 应用通常已经静态打包了大部分依赖但某些精简版系统会缺失 UCRT 或 VC 2015-2022 运行库。解决办法不是重装系统去微软官网装一下最新的“Microsoft Visual C Redistributable”x64就好。2.3 顺带聊聊压缩包加密与传输既然标题里带了 zip顺便提一个很多人会问的时序图工程传到别人电脑如何保证不被随意改动WaveDrom 的项目本质就是一个 JSON 文件你可以用压缩包加密再发给合作方。Windows 自带 zip 加密用的是 ZipCrypto安全性其实一般只适合防君子不防小人。如果你的设计文档需要更强保护建议用 7-Zip 选 AES-256 加密然后单独通过可信渠道发送密码。另外解压后我会习惯先看一眼文件列表。正常的包里会有resources、locales等目录如果解压出来只有一个孤零零的 exe大概率下载来源有问题。下载软件类工具优先去官方 GitHub Releases 页面别在陌生下载站找所谓的“破解版”或“汉化版”。3. WaveJSON 核心语法十分钟上手3.1 波形与时钟的最小描述WaveDrom 使用 WaveJSON 作为描述格式最核心的字段是signal数组里面每个对象代表一条信号线。比如我要画一个时钟和一个数据信号最简单的写法是{ signal: [ { name: clk, wave: p... }, { name: data, wave: x.2x } ] }wave字段是逐周期描述信号状态的字符串每个字符代表一个时钟周期。p表示上升沿.表示持续电平所以p...渲染出来就是“一个上升沿后保持三个周期”。x表示未知态2表示有定义的显式电平具体数值写在data字段里。WaveJSON 把时序图压缩成了字符串这个设计非常巧妙。你不需要和坐标轴打交道只需要关心每个周期信号处于什么状态。刚开始用会不太适应但画过三五个图之后就会发现字段与波形的对应关系非常有规律记忆成本很低。3.2 进阶配置信号组、周期、文本节点实际工程里一个模块接口的时序图很少只有一两条信号更多时候是总线加控制信号。WaveDrom 将这些信号用一个数组包起来可以定义组{ signal: [ { name: clk, wave: p.... }, { name: ctrl, wave: 0.1.., data: [CS] }, [DATA, [ { name: d[3:0], wave: x.., data: [A, B] }, { name: d[7:4], wave: x.., data: [C, D] } ]] ]}数组里嵌套一个[组名, [信号列表]]结构就会渲染成一个带总线括号的分组。{}花括号则能生成总线聚合标志这在画 AXI、DDR 这类大规模并行总线时很有用。周期长度也不一定非要跟实际时钟数一致。WaveDrom 会用时钟信号作为基准用period字段调整每周期宽度还支持在任意位置插入tick作为时间标尺。比如{ signal: [ { name: clk, wave: P......, period: 2 } ], tick: [0, 1, 2, 3, 4, 5, 6] }这样画出来的时序图横轴间隔是均匀的很适合放在数据手册里和时序参数表格对应。4. 实战用 WaveDrom Editor 绘制一组 SPI 读时序4.1 需求拆解与 WaveJSON 实现拿一个最常见的 SPI 读操作来演示。需求背景主机先拉低片选然后发送读命令和寄存器地址最后读取一个字节数据。功能上需要四根信号SCK、CS_N、MOSI、MISO。先把每个信号的状态拆开。空闲阶段 CS_N 保持高电平传输阶段 CS_N 拉低SCK 在传输期间持续翻转MOSI 先发命令字节和地址字节MISO 在读取阶段返回数据。我把这个描述转成 WaveJSON{ signal: [ { name: SCK, wave: p........... }, { name: CS_N, wave: 1.0.........1 }, { name: MOSI, wave: x......., data: [CMD, ADDR, X] }, { name: MISO, wave: x.........., data: [D7, D0] } ] }这段代码在会绘制出接近数据手册风格的 SPI 时序图。写完后目测最大的感受是波形和描述完全是一一对应的想调整 MISO 数据出现的时机只要移动data数组对应位置的值不需要在画布上拖拽。这个体验一旦适应就回不去老式画图工具了。4.2 导出图片与后续处理Graph 内容完成后在编辑器里导出图片通常会提供 PNG 和 SVG 两种格式。我更推荐导出 SVG因为它是矢量图直接拖进 Word 或者开源文档里不会模糊后续要用颜色标注也能在 Inkscape 或 Illustrator 里继续编辑。如果文档要求位图再导出 PNG。不过 WaveDrom 默认的 PNG 分辨率可能偏小如果你放到论文里建议在导出设置里把缩放倍数调大或者选用高 DPI 导出。我常用的做法是SVG 作为中间格式最终在文档工具里转成所需规格的位图这样最灵活。对于不会写 WaveJSON 的同事v2.3.2 这个编辑器界面左侧是代码框右侧实时预览基本就是“所见即所得”。但注意它不是拖拽编辑你要和同事协作时最好把.json源文件当作唯一真源图片只是导出产物。项目和文档一起维护这样才能发挥版本管理的优势。5. 常见问题排查与经验补充5.1 问题速查表实际操作中我把碰到过的问题和解决办法整理成了下面的表希望对你有直接帮助。现象可能原因解决办法解压后双击 exe 无反应缺少 VC 运行库安装 Microsoft Visual C Redistributable x64启动白屏路径含中文/特殊字符移到纯英文目录提示“不是有效的 Win32 应用程序”系统是 32 位但下载了 x64 包改用 win-ia32 版本导出图片为空或模糊导出缩放倍数太低调高 SVG/PNG 导出缩放或改用 SVG复制中文注释显示乱码编辑器默认编码不匹配使用 UTF-8 编码保存 JSON 文件在压缩包内直接运行资源目录未解压先完整解压再运行 exe排障时优先级最高的永远是先看是不是运行环境问题再看是不是文件路径问题最后才怀疑功能 bug。WaveDrom Editor 本身比较稳定绝大多数启动类故障都能归到这三类。5.2 我个人的三条使用习惯第一每个项目的时序图统一放在docs/wave目录下文件命名用模块名加版本号例如spi_master_v2.json。这样即使过了几个月翻回来也知道这个时序图对应哪个 RTL 版本。第二JSON 文件里我会写注释。WaveDrom 支持注释字段可以在.json开头用//注释说明这张图的用途和修改记录。第三导出图片时顺手把源文件和图片放一起压成一个 zip 再命名方便给同事共享。另外有个小技巧如果你经常画同一类总线协议的时序图可以把信号的公共部分存成模板片段。比如 SPI、I2C、UART 各存一份基础 WaveJSON每次新建直接复制模板改数据比每次从头写快很多。这三个习惯帮我避免了很多次“这个图是谁画的、参数是什么来着”的窘境。对我来说WaveDrom 最让我回不去的是它把文档和代码统一进了一个工作流。以前更新波形图是个体力活现在反而像写测试用例一样改几行 JSON、刷新预览、提交仓库整个过程都在同一个思维节奏里。如果你也经常被时序图维护折磨不妨花一个下午把这个 zip 包跑起来模拟画一个自己手上的真实时序多半会回来把它加到常用工具箱里。本文还有配套的精品资源点击获取