Skip to content
MermaidViewer

Software diagram

Mermaid packet diagram

Mermaid packet diagram syntax for bit ranges and header fields, with a TCP header example.

By MermaidViewer editorsPublished Updated

Basic packet diagram example

Basic packet diagram example diagram
mermaid
packet
    title UDP header
    0-15: "Source port"
    16-31: "Destination port"
    32-47: "Length"
    48-63: "Checksum"
    64-95: "Data (variable length)"
Open in the live editor

Packet diagrams show the layout of a network packet or binary structure: which bits hold which field. They're the familiar header diagrams from RFCs, generated from a short list of bit ranges.

Use them in protocol documentation, networking courses and embedded systems docs.

When to use a packet diagram

  • Protocol and RFC-style documentation
  • Networking courses
  • Binary file format specs
  • Embedded register layouts

Packet Diagram syntax reference

SyntaxWhat it does
packet (or packet-beta)Start a packet diagram.
title TextDiagram title.
0-15: "Field"A field covering bits 0 to 15.
16: "Flag"A single-bit field.
+8: "Field"A field of the given width placed after the previous one (newer versions).

Packet Diagram examples

TCP header (first rows)

Single-bit flags sit next to multi-bit fields.

TCP header (first rows) diagram
mermaid
packet
    title TCP header
    0-15: "Source port"
    16-31: "Destination port"
    32-63: "Sequence number"
    64-95: "Acknowledgment number"
    96-99: "Offset"
    100-105: "Reserved"
    106: "URG"
    107: "ACK"
    108: "PSH"
    109: "RST"
    110: "SYN"
    111: "FIN"
    112-127: "Window"
Open in the live editor

Bit ranges, in order, are the diagram. A mermaid packet diagram draws a header the way an RFC does: a row of fields, each covering a span of bits. It's not a sequence of messages, and it's not a byte dump. The syntax is a list of ranges under packet-beta.

Ranges and rows

Each field is 0-15: "Src". The numbers are bit indexes, inclusive, and the next field should start where the previous one ended plus one. 0-15 then 16-31 is contiguous. 0-15 then 10-20 fails, because 10 is inside the field you already drew. 16-31 before 0-15 also fails. The file wants ascending, touching ranges, starting at 0.

The label is quoted. Short labels fit. A 4-bit field can't display "Destination port" inside the cell, so the label spills or shrinks. Abbreviate on the diagram and gloss the abbreviation in the paragraph under it.

Rows break on a width you can think of as 32 bits, which is why 0-15 and 16-31 sit on one row and 32-47 starts the next. You don't place the row breaks yourself. You place the ranges, and the row follows the numbers. If a field crosses the row boundary, split it into the pieces you actually want on each row, or accept the layout the bit numbers imply.

A title is optional and useful when the doc has more than one header. title Mini header sits above the bits. It doesn't change the ranges.

Worked example

A tiny header has a source, a destination, and a length. Each field is 16 bits.

Mermaid diagram
mermaid
packet-beta
    title Mini header
    0-15: "Src"
    16-31: "Dst"
    32-47: "Len"
Open in the live editor

Bits 0 through 15 are the source. Bits 16 through 31 are the destination, still on the first row if the row is 32 bits wide. Bits 32 through 47 are the length, which opens the next row. The picture is the spec. A reader can implement the parse by reading the numbers, not by measuring pixels.

Len is a 16-bit count of something you still have to define in prose. The diagram doesn't say bytes versus words. Say it under the figure. If the length included the header, say that too. Those sentences are the part the bit diagram can't carry.

Adding a flag means inserting a range without leaving a hole and without overlap. A one-bit flag at bit 48 is 48-48: "F", and the following field must start at 49. Count on paper before you edit. The parser's contiguity check is stricter than a quick glance. If a field is reserved and unused, still give it a range and a label such as "Rsv". A gap isn't a way to say "reserved." The next real field has to begin at the next free bit.

When this is the wrong diagram

A sequence diagram is the better picture when the question is which message is sent first, not which bits sit inside one message. A block diagram is the better picture of components that aren't a flat header. Use a packet diagram when the reader is counting bits.

Common mistakes

  1. An overlapping range, such as 0-15 followed by 10-20. The parser stops because the next block should start at 16.
  2. Ranges out of order, such as the destination before the source. Start at bit 0 and climb. Later fields begin at the previous end plus one.
  3. A long label on a narrow field. Use "Dst" on the diagram and explain "destination port" in the caption.
  4. Describing two messages in one diagram by stacking unrelated headers. One packet diagram is one layout. A second header is a second figure.

Where to go next

The AI packet diagram generator will draft ranges from a field list. Recount the spans in the editor before you trust them, and the cheat sheet has the range line. The IPv4 header template is a full header if this three-field example is only a warm-up.

Bits have to sum to the width

A packet diagram is a header layout. Each field has a bit width, and the widths on a row have to fill the row. A 16-bit field drawn as if it were 8 bits will teach the wrong offset to whoever implements the parser. Write the width you would use in a struct, then read the row left to right and add.

Field names should match the spec you are citing, including the boring ones (Reserved, Checksum). Renaming TTL to "hops" because it sounds clearer breaks the search from the RFC to the diagram. The IPv4 header template follows the header people already know, which makes a wrong width obvious.

Add a one-line comment above the diagram with the RFC or header version, so the widths have a source.

Tips and best practices

  • Ranges must be contiguous and in order.
  • Rows wrap every 32 bits by default, matching RFC diagrams.
  • Keep labels short so they fit narrow fields.

Generate a packet diagram with AI

Not sure where to start? Describe what you need and the AI packet diagram generator writes the Mermaid code for you. Try prompts like:

  • “IPv4 header”
  • “Custom binary message format for an IoT sensor”
  • “DNS message header”

Packet Diagram templates

Packet Diagram FAQ

How many bits per row does a Mermaid packet diagram show?

32 bits per row by default, like classic RFC header diagrams. This can be changed with the bitsPerRow configuration option.