# Packet and protocol headers

A header diagram is a grid of fields with bit widths, and drawing it by hand is miserable. PacketDiag and Bytefield both generate one from a short text description, and they get the offsets right.

This is the diagram that makes a binary protocol specification readable.

---

## When to reach for one

* Documenting a custom binary protocol or file format.
* Explaining an existing protocol header in a design document.
* Debugging, where the field boundaries are the question.

---

## How to draw it in Capable

| **Route**  | **Use when**                                                      |
| ---------- | ----------------------------------------------------------------- |
| PacketDiag | Network-style headers with bit offsets across a fixed width.      |
| Bytefield  | Byte-oriented structures, including nested and variable sections. |

---

## A worked example

A TCP header, generated from field widths:

![Packet and protocol headers](https://help.gocapable.com/images/att1430880297.svg)

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

```
packetdiag {
  colwidth = 32;
  node_height = 72;

  0-15: Source port;
  16-31: Destination port;
  32-63: Sequence number;
  64-95: Acknowledgement number;
  96-99: Data offset;
  100-105: Reserved;
  106-111: Flags;
  112-127: Window;
  128-143: Checksum;
  144-159: Urgent pointer;
}
```

---

## A few things that catch people out

* Set the column width to the real word size or the offsets will mislead.
* Say whether you are counting bits or bytes, once, at the top.
* Variable-length fields need a note; the grid cannot express them on its own.

---

## Related

[P&ID diagramPiping and instrumentation, with the right symbols.](https://help.gocapable.com/diagrams/p-id-diagram.html)

[Network diagramFrom one office to many sites.](https://help.gocapable.com/diagrams/network-diagram.html)

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

---

_Somebody will read this at 3am. Be kind._