WaveJSON Timing Diagram Generator

Generate WaveJSON format timing diagrams for WaveDrom rendering. Perfect for documenting hardware interfaces, signal timing, protocol sequences, and any digital signal visualization.

Format Reference: This skill uses the WaveJSON specification and WaveDrom rendering engine, both licensed under MIT.

Additional Resources:

•reference.md - Quick reference card with wave characters, common patterns, detailed signal pattern examples, and validation checklist

Important

•Keep signal names short, space is at a premium

WaveJSON Format Overview

WaveJSON uses JSON to describe timing diagrams with these key components:

Signal Object Structure

json

{
  "signal": [
    { "name": "clk",  "wave": "p......." },
    { "name": "data", "wave": "x.345x..", "data": ["head", "body", "tail"] },
    { "name": "req",  "wave": "0.1...0." }
  ]
}

Wave Characters

Clock waves:

•p - positive edge clock (rising edge)
•n - negative edge clock (falling edge)
•P - positive edge with arrow
•N - negative edge with arrow

Logic levels:

•0 - low level
•1 - high level
•. - extends previous state

Data values:

•= - data value (color 2)
•2, 3, 4, 5 - data values with different colors
•x - undefined/don't care
•z - high impedance (tri-state)
•u - pull-up
•d - pull-down

Special:

•| - extend cycle and add gap

Signal Properties

•name - Signal label (string)
•wave - Timing pattern (string, one char per cycle)
•data - Array of labels for data values (corresponds to =, 2-5 in wave)
•period - Signal repetition period (number)
•phase - Phase shift, positive=future, negative=delay (number)
•node - Markers for arrows: . (none), A-Z (invisible), others (visible)

Signal Groups

Create hierarchical groups by using arrays with a label string:

json

{
  "signal": [
    ["Control Signals",
      { "name": "LE",  "wave": "01.0...." },
      { "name": "WR",  "wave": "1..01.0." }
    ],
    ["Data Bus",
      { "name": "D[7:0]", "wave": "x.3.4..x", "data": ["CTRL", "DATA"] }
    ]
  ]
}

Edges (Arrows)

Add dependency arrows between signal markers:

json

{
  "signal": [...],
  "edge": [
    "a~>b Setup time",
    "c-~d Hold time",
    "e~|~f Pulse width"
  ]
}

Edge syntax:

•First char: source node (from node property)
•Last char: destination node
•> before last char: arrow head
•Shape: - (horizontal), | (vertical), ~ (curvy), / (diagonal)
•# marks label position
•Text after first word: arrow label

Config

json

{
  "signal": [...],
  "config": { "hscale": 2 }
}

•hscale - Horizontal scale (≥1, default 1)

Generating HTML Viewers

Create local HTML files to render WaveJSON diagrams using the WaveDrom library.

When to Generate HTML Viewers

Generate an HTML viewer when:

•User wants to "view", "display", "render", or "visualize" a diagram locally
•User wants to save diagrams for documentation
•User needs to see multiple diagrams on one page
•User wants an offline/local viewer instead of online editor

HTML Template Structure

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>WaveDrom Timing Diagram</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/3.1.0/skins/default.js" type="text/javascript"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/3.1.0/wavedrom.min.js" type="text/javascript"></script>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 20px;
      background-color: #f5f5f5;
    }
    h1, h2 {
      color: #333;
    }
    .diagram-container {
      background: white;
      padding: 20px;
      margin: 20px 0;
      border-radius: 5px;
      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
    }
  </style>
</head>
<body onload="WaveDrom.ProcessAll()">
  <h1>Timing Diagrams</h1>

  <div class="diagram-container">
    <h2>Diagram Title Here</h2>
    <script type="WaveDrom">
    {
      "signal": [
        { "name": "clk", "wave": "p......." },
        { "name": "data", "wave": "x.345x..", "data": ["head", "body", "tail"] }
      ]
    }
    </script>
  </div>

  <!-- Add more diagrams by adding more diagram-container divs -->

</body>
</html>

Multi-Diagram HTML Template

For pages with multiple timing diagrams:

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Hardware Timing Reference</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/3.1.0/skins/default.js" type="text/javascript"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/wavedrom/3.1.0/wavedrom.min.js" type="text/javascript"></script>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 20px;
      background-color: #f5f5f5;
    }
    h1 { color: #333; }
    h2 { color: #555; margin-top: 0; }
    .diagram-container {
      background: white;
      padding: 20px;
      margin: 20px 0;
      border-radius: 5px;
      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
    }
    .description {
      color: #666;
      margin: 10px 0;
      font-size: 14px;
    }
  </style>
</head>
<body onload="WaveDrom.ProcessAll()">
  <h1>Project Timing Diagrams</h1>

  <div class="diagram-container">
    <h2>Two-Phase Write Sequence</h2>
    <p class="description">Shows the complete writeByte() operation with control latch and character write.</p>
    <script type="WaveDrom">
    { /* First WaveJSON here */ }
    </script>
  </div>

  <div class="diagram-container">
    <h2>Control Word Timing</h2>
    <p class="description">D7 clear bit requires 1.0µs delay per PD2437 datasheet.</p>
    <script type="WaveDrom">
    { /* Second WaveJSON here */ }
    </script>
  </div>

</body>
</html>

HTML Generation Workflow

When user requests HTML viewer:

•Generate or use existing WaveJSON for the timing diagram(s)
•Create HTML file using the template above
•Embed WaveJSON in <script type="WaveDrom"> tags
•Add descriptive titles (h2) and descriptions for each diagram
•Save to appropriate location (suggest docs/timing_diagrams.html)
•Offer to open in browser using open command (macOS) or xdg-open (Linux)

Opening HTML in Browser

After creating the HTML file:

bash

# macOS
open /path/to/timing_diagrams.html

# Linux
xdg-open /path/to/timing_diagrams.html

# Windows (Git Bash)
start /path/to/timing_diagrams.html

Example HTML Generation

User request: "Create an HTML page showing the SPI transfer timing"

Claude should:

•Generate (or retrieve) the WaveJSON for SPI transfer
•Create HTML file with WaveDrom CDN scripts
•Embed the WaveJSON in <script type="WaveDrom"> tag
•Add meaningful title and description
•Save to docs/spi_transfer_timing.html
•Ask if user wants to open it in browser

Suggested File Locations

•Single diagrams: docs/timing_[description].html
•Protocol reference: docs/protocol_timing.html
•Interface-specific: docs/[interface]_timing.html
•Complete hardware reference: docs/hardware_timing.html

Including Multiple Diagrams

When creating comprehensive timing documentation:

•Group related diagrams: Organize by protocol, interface, or functional block
•Add navigation: Consider adding a table of contents for pages with 5+ diagrams
•Include code references: Link to specific functions or modules in descriptions
•Add context: Explain timing requirements, constraints, and why they matter

Validation Before Opening

Before generating HTML:

•Ensure WaveJSON is valid (proper JSON syntax)
•Test WaveJSON in online editor if uncertain
•Check that all required CDN scripts are included
•Verify onload="WaveDrom.ProcessAll()" is present in <body> tag
•Confirm <script type="WaveDrom"> tags are properly formed

WaveDrom CDN Version

Current stable version: 3.1.0

If user reports rendering issues:

•Check browser console for errors
•Verify internet connection (CDN requires network access)
•Try online editor to isolate WaveJSON vs HTML issues
•Consider downloading WaveDrom for offline use

Common Digital Signal Patterns

For detailed pattern examples (SPI, I2C, Bus Write Cycles, Chip Select Decoding, Clock Domain Crossing, Setup/Hold Timing), see the "Detailed Signal Pattern Examples" section in reference.md.

Instructions for Claude

Generating WaveJSON Only

When asked to generate WaveJSON timing diagrams:

•Understand the sequence: Identify all signals involved and their timing relationships
•Choose appropriate wave characters: Use clocks (p/n) for clocks, logic levels (0/1) for control, data (=, 2-5) for bus values
•Add signal groups: Organize related signals hierarchically for clarity
•Include data labels: Use the data array to label bus values meaningfully
•Add edges/arrows: Show timing relationships (setup, hold, propagation delay) using the edge array
•Set appropriate hscale: Use hscale: 2 or higher for complex timing to make diagrams readable
•Add nodes: Place markers (using node property) where arrows should connect
•Output valid JSON: Ensure proper JSON syntax (double quotes, no trailing commas)
•Test with context: Consider IC datasheets and actual timing constraints from hardware docs

Generating HTML Viewer

When asked to "view", "display", "render", or "visualize" timing diagrams locally:

•Generate WaveJSON first (or retrieve from examples.md if project-specific examples exist)
•Create docs directory if it doesn't exist: mkdir -p docs
•
Write HTML file using the template structure:
- •Include WaveDrom CDN scripts (v3.1.0)
- •Add onload="WaveDrom.ProcessAll()" to body tag
- •Embed WaveJSON in <script type="WaveDrom"> tags
- •Add meaningful titles and descriptions
•Save with descriptive filename in docs/ directory
•Offer to open in browser (macOS: open, Linux: xdg-open, Windows: start)

Decision: WaveJSON vs HTML

•Just WaveJSON: User asks to "generate" or "create" a diagram, wants to paste in online editor
•HTML Viewer: User asks to "view", "display", "show", "render", or wants local/saved documentation

When in doubt, generate WaveJSON and ask: "Would you like me to create an HTML viewer to display this locally?"

Node Placement for Arrows

To draw arrows between events:

•Add node property to signals with timing markers
•Use . for cycles without markers
•Use letters a-z or A-Z for marker positions
•Markers align with wave characters (one char per cycle)

Example:

json

{ "name": "CLK",  "wave": "p....", "node": ".a.b." }
{ "name": "DATA", "wave": "x.2.x", "node": "..c..", "data": ["valid"] }

Then add edges:

json

"edge": [
  "a~>c Setup",
  "b~>c Hold"
]

Output Format

Generate WaveJSON as properly formatted JSON that can be:

•Pasted into WaveDrom Editor for rendering
•Saved as .json files
•Embedded in markdown with WaveDrom plugins

Always validate JSON syntax and test logic before outputting.

Context and Timing Considerations

When generating timing diagrams for hardware projects:

•Setup/Hold times: Show data stability before and after clock edges
•Propagation delays: Illustrate signal delays through logic and buffers
•Bus protocols: Display address/data multiplexing, strobes, and handshaking
•Clock domains: Show synchronization between different clock domains
•Level conversion: Consider voltage level timing when crossing logic families

Reference datasheets, project documentation, and code for actual timing values.

Example Usage

User: "Generate a WaveJSON diagram showing an SPI byte transfer"

Claude should:

•Read relevant code/documentation to understand timing
•Create signals for CLK, MOSI, MISO, CS
•Show chip select assertion
•Show 8 clock cycles with data shifting
•Show chip select de-assertion
•Add appropriate hscale and labels
•Output valid WaveJSON

Validation

Before outputting WaveJSON:

•Check JSON syntax (use linter if needed)
•Verify wave strings match in length (if they should)
•Ensure data array matches number of data values in wave
•Confirm node markers align with cycles
•Test edge references point to existing nodes