# Digital timing diagram

Timing diagrams show signals against time: clock edges, when a bus is valid, and what changes in response to what. WaveDrom generates them from a compact JSON description.

It is the clearest way to document a protocol where the answer to every question is "it depends when".

---

## When to reach for one

* Hardware and firmware interface documentation.
* Protocol specifications where setup and hold times matter.
* Debugging notes: what you expected against what the analyser showed.

---

## How to draw it in Capable

| **Route** | **Use when**                                       |
| --------- | -------------------------------------------------- |
| WaveDrom  | Purpose-built; clocks, buses, gaps and arrows.     |
| draw.io   | Teaching diagrams where you want heavy annotation. |

---

## A worked example

An SPI-style transfer with a clock, chip select and data:

![Digital timing diagram](https://help.gocapable.com/images/att1417609303.svg)

The source, which you can paste into a new diagram and edit:

```
{ "signal": [
  { "name": "clk",  "wave": "p......." },
  { "name": "cs_n", "wave": "10......1" },
  { "name": "mosi", "wave": "x.2345x.", "data": ["cmd", "a1", "a0", "len"] },
  { "name": "miso", "wave": "x.....67", "data": ["d0", "d1"] },
  { "name": "busy", "wave": "0.1....0" }
]}
```

---

## A few things that catch people out

* Show the clock, even when the point is the data. Everything is measured against it.
* Mark don't-care periods as x rather than leaving them flat; flat implies a value.
* Annotate setup and hold requirements if the diagram is a specification rather than a trace.

---

## Related

[HDL block diagramComponent symbols generated from your HDL.](https://help.gocapable.com/diagrams/hdl-block-diagram.html)

[Memory layout diagramOffsets, widths and nested structures.](https://help.gocapable.com/diagrams/memory-layout-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Approximately right is wrong here._