WaveDrom: Digital Timing Diagrams with Markdown

Introduction to WaveDrom

WaveDrom is a JavaScript-based tool for rendering digital timing diagrams from simple text descriptions. It allows engineers and developers to create professional timing diagrams, state charts, and signal flow diagrams using a simple, human-readable syntax without needing specialized diagramming software.

Installation & Setup

For Hugo sites, you typically need to:

1. Include the WaveDrom library in your layout
2. Enable the wavedrom: true parameter in your post’s front matter
3. Use ```wavedrom code blocks in your markdown

Diagram Types & Examples

1. Basic Timing Diagram

A simple timing diagram showing signal transitions:

{
  signal: [
    { name: 'clk', wave: 'p.....|..'},
    { name: 'data', wave: 'x.3.4.5.x', data: ['A', 'B', 'C']},
    { name: 'enable', wave: '0.1...0..'}
  ]
}

2. Multi-Signal Bus

Representing bus signals with multiple bits:

{
  signal: [
    { name: 'address', wave: 'x.3.4.5.x', data: ['0x00', '0x04', '0x08']},
    { name: 'data', wave: 'x.3.4.5.x', data: ['0xAA', '0xBB', '0xCC']},
    { name: 'write_en', wave: '0.1.0.1.0'},
    { name: 'read_en', wave: '0.0.1.0.0'}
  ]
}

3. Memory Access Sequence

Demonstrating a memory read/write cycle:

{
  signal: [
    { name: 'clk', wave: 'p......'},
    { name: 'addr', wave: 'x.2.3.x', data: ['0x1000', '0x1004']},
    { name: 'data_out', wave: 'x.4.5.x', data: ['0x1234', '0x5678']},
    { name: 'we_n', wave: '1.0.1.'},
    { name: 'oe_n', wave: '1.1.0.'}
  ],
  config: { timeScale: 0.5 }
}

4. State Transitions

Showing state changes over time:

{
  signal: [
    { name: 'state', wave: '2...3...4', data: ['IDLE', 'READ', 'WRITE']},
    { name: 'valid', wave: '0.1.0.1.0'},
    { name: 'ready', wave: '1.0.1.0.1'}
  ]
}

5. Protocol with Handshaking

Demonstrating a simple handshake protocol:

{
  signal: [
    { name: 'master_req', wave: '0.1...0'},
    { name: 'slave_ack', wave: '0..1..0'},
    { name: 'data_valid', wave: 'x.2.3.x', data: ['cmd', 'resp']}
  ]
}

6. Complex Pipeline

Multi-stage pipeline with valid/ready signals:

{
  signal: [
    { name: 'clk', wave: 'p.........'},
    { name: 'stage1_valid', wave: '1.0.1.0.1'},
    { name: 'stage2_valid', wave: '0.1.0.1.0'},
    { name: 'stage3_valid', wave: '0.0.1.0.1'},
    { name: 'stage3_ready', wave: '1...0.1..'}
  ]
}

WaveDrom Signal Syntax

Wave Characters

• 0 - Low level
• 1 - High level
• x - Unknown/undefined
• z - High-impedance
• = - Bus value (requires data array)
• 2-9 - Numeric values (requires data array)
• p - Positive clock pulse
• n - Negative clock pulse
• P - Positive pulse
• N - Negative pulse
• . - Time step
• | - Time marker

Benefits of Using WaveDrom

• Precision: Accurate timing diagram representation
• Professional Output: Publication-ready diagrams
• Easy to Learn: Simple, intuitive text syntax
• Version Control: Diagrams can be tracked in Git
• No Special Tools: Just plain text, renders with JavaScript
• Interactive: Web-based, can be edited and viewed online
• Hardware-Friendly: Perfect for digital design documentation

Best Practices

1. Consistent Time Steps: Use regular intervals for clarity
2. Clear Signal Names: Use descriptive names for all signals
3. Add Data Labels: Use data arrays to show values on transitions
4. Group Related Signals: Organize signals logically
5. Use Markers: Add time markers for important events
6. Document Timing: Include timing annotations where needed

Resources

For complete documentation and advanced features, visit the official WaveDrom website:

WaveDrom Official Website

You’ll find:

• Interactive editor and examples
• Complete syntax reference
• Gallery of timing diagrams
• Integration guides for various platforms
• Advanced rendering options

Conclusion

WaveDrom is an essential tool for anyone working with digital logic, hardware design, or protocol documentation. Its simple syntax combined with professional output makes it ideal for technical documentation, tutorials, and design specifications.

Start creating timing diagrams with WaveDrom today and improve your digital design documentation!