WaveDrom v2.3.2 桌面版：JSON 文本化时序图绘制与版本管理

简介：Wavedrom Editor v2.3.2的Windows 64位版本是一款基于JavaScript的时序图绘制工具，面向FPGA开发、电子设计与嵌入式工程师，解决离线环境下快速绘制波形图与信号时序关系的需求。其文本化语法简洁直观，支持上升沿、下降沿、脉冲、注释与色彩标记，并具备实时预览与SVG、PNG导出能力，适合从入门到中高级开发者使用。资源包为zip压缩格式，共124个文件，主要包括56个pak资源文件、53个info配置信息、9个dll运行库、2个exe主程序、2个bin数据文件以及dat和html辅助文件，整体大小83.72MB，解压即可运行，便于本地免安装使用，目前已有2168人学习下载。压缩包内核心程序与依赖库齐全，提供完整的Windows 64位本地化版本，免除访问外网安装的困扰；打开html入口即可启动编辑器，通过具体文件构成，用户能快速了解软件运行原理，便于后续定制、移植或二次开发，是时序图绘制的实用工具。

1. 时序图绘制的效率黑洞：v2.3.2 桌面版把波形变成可版本管理的文本

搞过 FPGA 验证或写过硬件文档的人，都经历过手动时序图绘制最痛苦的一幕：产品手册要补一张 SPI 读时序图，画图工具里拖了半天，线是歪的，标注对不齐，改一个周期又得重画。WaveDrom Editor 把时序图写成 JSON 文本，描述信号翻转、数据采样、总线读写，渲染交给编辑器。v2.3.2 win-x64 是 Windows 桌面打包版，解压即用。

文本化的核心价值是可控和可复用：时序图能进 Git、能批量生成，改一个周期不用重拖线，渲染结果每次都稳定一致。适合三类人——硬件文档工程师、FPGA/ASIC 验证开发者、想快速产出规范波形图的学生。

下面从语法模型讲起，再给实操步骤和踩坑记录，看完你就能独立画出一张规范、可评审的时序图。

2. 从描述到画布：WaveDrom 的语法模型与渲染机制

2.1 signal 数组与 wave 字符：一段 JSON 就是一张图

WaveDrom 的描述体是一个 JSON 对象，最核心的字段是signal，它是一个数组。数组里每个元素是一条信号线，元素里再嵌signal就能形成分组。先看最基础的一段：

{ "signal": [ { "name": "clk", "wave": "p......" }, { "name": "din", "wave": "x.3.2..", "data": ["addr", "data"] } ] }

wave是整张图的时间轴骨架，一个字符代表一个单位时间。p表示时钟上升沿，.表示保持前一拍电平，x是不关心态（渲染成交叉阴影），3是下降沿，2是上升沿，=是有效数据总线。data数组是文本标注，按顺序绑定到wave对应的数据字符上。

常用字符速查表：

后面所有排错都建立在这个映射关系上。v2.3.2 编辑器左侧是源码区、右侧是渲染区，每改一个字符右侧立即重绘，这是排查语法错误最直接的反馈。新手阶段我建议盯着右侧输出写 JSON，而不是闭眼写一大段再回头调。

2.2 clock、phase 与周期：数据边沿怎么和时钟对齐

数字接口的时序图，本质就是「数据相对时钟边沿在哪一拍变化」。WaveDrom 允许在顶层定义一个clock对象，统一控制p、n字符的周期和相位：

{ "signal": [ { "name": "clk", "wave": "p......" }, { "name": "dout", "wave": "x.3.2..", "data": ["D0", "D1"] } ], "clock": { "period": 2, "phase": 0.5 } }

period定义每个字符对应的渲染宽度，值越大波形横向铺得越开；phase是相位偏移，0.5 表示数据整体挪半拍。这里dout在 clk 的第二拍之后才开始有沿，配合phase可以模拟真实的输出延迟，而不是把所有翻转都画在同一条垂直线上。

我一般会只用 phase 微调数据总线，时钟保持 0，这样画出来的图更接近示波器看到的实际信号关系。如果你发现数据沿和时钟沿完全重叠、看起来像同时变化，先检查是不是没给数据线留出相位偏移。

2.3 node 与 edge：建立时间、保持时间怎么标上去

光有波形还不够，评审时序图通常要标建立时间、保持时间、输出延迟。WaveDrom 用node和edge两个字段配合完成：

{ "signal": [ { "name": "clk", "wave": "p......", "node": ".a...." }, { "name": "dout", "wave": "x.2....", "node": "..b..." } ], "edge": ["clk~b 3 tco"] }

node字段同样是一串字符，.表示该位置没有锚点，字母则是给这一列打上一个命名锚点。edge的字符串格式是「起点信号名~终点锚点名 时间列 标签」，上面这条表示从 clk 默认位置拉一条箭头到 dout 的 b 锚点，箭头落在第 3 列，标签写 tco。

写错的地方多半是锚点字母重复或信号名写错，编辑器不会报错，只会让箭头消失。我的习惯是每个信号只用一个小写字母锚点，从 a 开始按字母序排，时间列数对着 wave 字符串数好再写，避免「看起来有箭头、实际是空的」。跨多个周期的延迟弧线可以用arc表达，但我多数场景用多条edge更直观，也更好调。

2.4 渲染管线：为什么 v2.3.2 每次画出来都一样

WaveDrom 的渲染是把 JSON 解析成中间描述，再映射成 SVG 元素，最后序列化成文本。这个过程没有随机成分，同一段 JSON 在不同时间、不同机器上渲染结果完全一致，这也是它适合进版本库的原因——diff 出来的是语义变化，不是像素变化。

v2.3.2 桌面版本质是一个桌面壳里包了固定版本的渲染库。和网页版相比，桌面版本地文件读写方便，不受浏览器安全策略限制，导出大图时内存更可控。需要注意一个边界：桌面版锁定了渲染库版本，和线上主分支可能差一两个小版本，个别新语法在 v2.3.2 里不一定会生效。我遇到过网页版能正常渲染的lanes配置，在 v2.3.2 里被静默忽略，所以正式产出以桌面版为准，别拿网页版的效果图直接交文档。

3. 上手实操：v2.3.2 画一张完整的 SPI 读时序图

3.1 搭骨架：时钟、片选与命令阶段

用编辑器画图不建议一上来就写完整复杂的 JSON。先把时钟和片选搭起来，确认时间轴长度。下面是一段 17 拍的骨架：

{ "signal": [ { "name": "clk", "wave": "p................" }, { "name": "cs_n", "wave": "1.0.............1" }, { "name": "mosi", "wave": "x................" } ] }

clk 从第 0 拍开始连续 17 拍：一个p加 16 个点。cs_n 先高后低再回高，低电平段就是命令和数据阶段的有效窗口。mosi 在片选拉低前是不关心态，用x占满整段。

这里有个容易忽略的点：所有信号的 wave 字符串长度必须一致，编辑器按列对齐，长度不一致会出现「右边多出一截但没信号」的怪相。数格子的时候把每一列的字符标上序号，比数完再数一遍可靠。编辑器右侧有刻度线，数拍时直接对刻度数，别数 JSON 里的点。

3.2 加数据：MOSI 命令字与 MISO 采样

骨架确认后，在对应位置填入命令字和数据：

{ "signal": [ { "name": "clk", "wave": "p................" }, { "name": "cs_n", "wave": "1.0.............1" }, { "name": "mosi", "wave": "x.23423423.......", "data": ["A7", "A6", "A5", "A4", "A3", "A2", "A1", "A0"] }, { "name": "miso", "wave": "z.......23423423.", "data": ["D7", "D6", "D5", "D4", "D3", "D2", "D1", "D0"] } ] }

mosi 在第 3 到第 10 列翻转 8 次，对应 8 位命令字；miso 在命令字发完后才开始驱动数据，从第 9 列起连续 8 拍。这里的z表示高阻——注意z和x语义不同，高阻是「不驱动」，不关心是「不知道什么电平」，混用会让评审的人误读总线状态。

提示：data数组长度必须和 wave 里数据字符的数量严格相等，多一项少一项都会错位。

一个实用技巧：先把 wave 写整齐，再用一个临时脚本数出数据字符个数，再填 data，能省掉大量对格子时间。我在批量生成时会在脚本里加断言，长度不一致直接报错，而不是生成一张错位图。

3.3 调布局：hscale、tick 与信号分组

波形写对后，剩下的是排版。顶层config里的hscale控制横向缩放，密集信号建议设 2 或 3：

{ "signal": [ { "name": "clk", "wave": "p................" }, { "name": "cs_n", "wave": "1.0.............1" }, { "name": "mosi", "wave": "x.23423423.......", "data": ["A7", "A6", "A5", "A4", "A3", "A2", "A1", "A0"] }, { "name": "miso", "wave": "z.......23423423.", "data": ["D7", "D6", "D5", "D4", "D3", "D2", "D1", "D0"] } ], "config": { "hscale": 2, "skin": "narrow" } }

hscale 只改变波形横向间距，不缩放文字；数据标注挤成一团时，优先缩短 data 里的字符串，而不是单纯拉大 hscale。skin有 narrow 和 wide 两种画风，narrow 更省横向空间，适合塞进表格和窄栏文档。顶部刻度由head配置控制，我一般保留刻度，评审时对拍数方便。

需要分组时，在 signal 数组里嵌一个带name的元素：

{ "signal": [ { "name": "SPI 总线", "signal": [ { "name": "mosi", "wave": "x.23423423......." }, { "name": "miso", "wave": "z.......23423423." } ]}, { "name": "clk", "wave": "p................" } ] }

分组名渲染成一条总线标题，图面上更接近协议手册的排版习惯。注意嵌套分组的 wave 长度依然要和外部信号对齐，分组本身不额外占列。

3.4 导出：SVG 进文档、PNG 进评审邮件

v2.3.2 的导出菜单提供 SVG 和 PNG 两种格式。SVG 是无损矢量，嵌入 HTML/Markdown 后放大不糊，是工程文档的首选；PNG 适合直接贴到评审邮件或群里。

一个实际经验：SVG 默认是白底，深色主题下看没问题，贴到白底文档要确认前景色。如果你想走「SVG 转 PNG」的链路，推荐先导 SVG 再用浏览器或矢量工具转换，而不是直接从编辑器导一张大尺寸 PNG——前者可二次编辑，后者改一个字符就得整张重导。导出后建议立即重新打开一次 SVG 检查有没有丢文字，桌面应用在特定字体环境下有概率丢失文本样式，遇上了换 skin 或者微调字体参数，比反复重导快。

4. 避坑指南：WaveDrom 绘图最常见的五处翻车现场

4.1 波形整体右移，数据沿和时钟对不齐

现象：JSON 放进去波形确实画出来了，但所有数据翻转都比时钟沿晚一格，看起来采样点落在边沿上。

原因：数据翻转字符在 wave 字符串里和p放在了同一列。WaveDrom 按列对齐，同一列的字符渲染在同一条垂直线上。真实电路里数据总在时钟沿之后稳定，所以这种画法从语义上就错了。

解决：把数据线的翻转字符往后移一列，例如p在第 2 列，数据沿放到第 3 列，必要时配合clock.phase做整体微调。养成习惯：写完先盯住第一组 clock 和 data 的对齐关系，确认「先沿后数据」再继续往下写。

4.2 hscale 拉大后，数据文字还是挤成一团

现象：hscale 已经改到 3，波形间距明显变宽，可 data 标签两个字符还是贴在一起。

原因：hscale 只作用在波形绘制的横向缩放，文字是独立绘制的，字号固定，间距不随 hscale 变化。拉 hscale 解决不了文字密度问题。

解决：按优先级试三个办法。一是缩短 data 项内容，把 "ADDR_0x3F" 写成 "A3"；二是把一条总线的数据拆成两行分别承载；三是用=汇流线把多拍画成一条总线，只在首尾标数据。文字挤是密度问题，不是缩放问题，先减内容再调 hscale。

4.3 data 数组长度不一致，尾部标注消失或整体错位

现象：波形还在，但最后两拍的数据标注不见了，或者标注内容全部错位到前面的信号上。

原因：data 数组按顺序绑定到 wave 中具有数据含义的字符（2、3、4、5、=）。数组比字符少，尾部没标注；数组比字符多，多出来的被丢弃。错位是因为中间多了一个或少了一个数据字符，从某个索引开始整体偏移。

解决：写 data 前先数清楚 wave 里数据字符的个数，确认相等。写完在编辑器里放大渲染区逐段核对 data 文本落在预期拍上。批量生成时在脚本里加断言，长度不一致直接报错，别把错位图带进正式文档。

4.4 中文路径和特殊字符导致渲染空白或导出失败

现象：工程文件放在带中文的目录下，编辑器打开后右侧一片空白，导出 SVG 后文件损坏或打不开。

原因：桌面套壳应用对非 ASCII 路径的处理一直不太稳定，这不是 WaveDrom 独有，很多本地工具都有这类问题。文件名里的中文、空格、括号都可能触发文件读写异常。

解决：工程文件和导出路径统一用英文、数字、下划线。JSON 内部的中文标注没问题，但文件名别带中文。遇到打不开的情况，先把 JSON 内容复制出来，在英文路径下新建文件粘贴保存，基本能救回来。我现在把「路径纯英文」写成了项目约定，所有成员默认遵守，这类问题就没再出现过。

4.5 同一份 JSON 在网页版和桌面版渲染不一致

现象：网页版渲染正常的新语法，v2.3.2 里没有效果，个别配置被静默忽略，edge 箭头样式也和网页版不同。

原因：桌面版锁定的是打包时的渲染库版本，网页版实时跟随主分支，两者不是同一个版本。新特性先在网页版生效，桌面版要等下一个 release 才跟进。

解决：正式文档以桌面版为准。如果某个特性必须用，去确认 v2.3.2 对应渲染库支持哪些配置，别拿网页版效果当验收标准。这条属于「知道有这回事就行」的坑，遇到过一回，后面自然有意识先验证再使用。

5. 进阶：把时序描述模板化，接入文档构建链路

5.1 用 Node 脚本批量生成时序 JSON

时序图一旦变成文本，就具备编程生成的可能。以 SPI 读事务为例，把地址位宽、数据位宽定义成参数，一次生成一段完整的 18 拍波形：

// gen_spi_json.js —— 参数化生成 SPI 读事务时序图描述 function buildSpiRead(addrBits, dataBits) { const total = 2 + addrBits + dataBits; // x. 占 2 列，地址 + 数据 const addrCell = '2'.repeat(addrBits); // 每个地址位一个上升沿 const dataCell = '2'.repeat(dataBits); // 每个数据位一个上升沿 const clk = 'p' + '.'.repeat(total - 1); // 总拍数 = total const mosi = 'x.' + addrCell + '.'.repeat(dataBits); const miso = 'z' + '.'.repeat(addrBits + 1) + dataCell; const addrLabels = Array.from({ length: addrBits }, (_, i) => 'A' + (addrBits - 1 - i)); const dataLabels = Array.from({ length: dataBits }, (_, i) => 'D' + (dataBits - 1 - i)); return { signal: [ { name: 'clk', wave: clk }, { name: 'cs_n', wave: '1.0' + '.'.repeat(addrBits + dataBits - 1) + '1' }, { name: 'mosi', wave: mosi, data: addrLabels }, { name: 'miso', wave: miso, data: dataLabels } ], config: { hscale: 2 } }; } console.log(JSON.stringify(buildSpiRead(8, 8), null, 2));

几个参数的对照关系：total是总列数，clk 的 wave 长度、cs_n 的 wave 长度都必须等于它；addrCell和dataCell各占 addrBits、dataBits 列；data 数组的生成顺序从高到低，符合 SPI 高位先发的习惯。改协议时只改位宽参数，输出的 JSON 结构不会变。

5.2 与文档工程联动：JSON 即唯一事实源

把这份 JSON 模板放进文档仓库，把每次生成的输出提交到 Git。协议变更时，改一个位宽参数，重新跑脚本，再拖进 v2.3.2 复核一遍，重点看数据和时钟的列对齐，以及 data 标注是否落在预期拍上。评审时直接 diff JSON，比对着两张 PNG 猜改动点高效得多。

这套链路我用在接口手册和验证报告两类文档上，最大的收益是「图不再怕改」。从那以后，我每次更新接口时序都强制走一遍「参数化 JSON → 编辑器复核 → 导出 SVG 提交」的流程，改协议不再是重画一张图，而是几行 JSON 的版本 diff。如果你正好在找 Windows 下能直接跑的 WaveDrom 编辑器，v2.3.2 win-x64 这个桌面打包版值得收进工具链，配合脚本生成，效率比纯手绘高出一截。希望帮到你。

本文还有配套的精品资源，点击获取