Introduction to PlantUML

Introduction

PlantUML is an open-source tool that allows users to create diagrams using plain text.  Although its name includes the acronym "UML", it is hardly restricted to solely making UML diagrams.  PlantUML supports the following diagram types:

Sequence diagram, Use case diagram, Class diagram, Object diagram, Activity diagram, Component diagram, Deployment diagram, State diagram, Timing diagram, JSON data, YAML data, EBNF (Extended Backus-Naur Form), Regex (Regular Expression), Network diagram (nwdiag), Salt (Wireframe graphical interface or UI Mockups), Archimate diagram, SDL (Specification and Description Language), Ditaa diagram, Gantt diagram, Chronology diagram, MindMap diagram, WBS (Work Breakdown Structure), Mathematical Notations (AsciiMath, JLaTeXMath), Information Engineering (IE) diagram, Entity Relationship (ER) diagram (Chen's notation)

Compare PlantUML to a commercial tool like Microsoft Visio—Visio may be great, but it saves diagrams in its own binary format, which means its diagram files are large, not updateable via automation, difficult to version control, and requires anyone wanting to make modifications to have a Visio license.

With PlantUML, diagram definition is in plain text which separates the diagram's definition from its presentation.  A build tool takes the text-based source code and outputs the diagram as an image.  You can think of PlantUML as Markdown for diagrams.  Alternatively, you could think of it like "as laTeX is to Microsoft Word, PlantUML is to Microsoft Visio".

So What's the Point?

Software/Firmware engineers are used to dealing with visualizations of source code.  One example might be an architect creating diagrams to hand-off to a development team; another a developer creating a design specification that lives alongside the source code.  PlantUML makes it easy to:

• keep both the project's source code, and the project's architectural diagrams, together in one place
• version control design diagrams in a git repository, just like source code
• easily track changes to the diagrams from one revision to another
• allow anyone with a text editor to update/improve the diagrams

As such, it's a good tool for any SW/FW developer/architect to have in their toolkit.

Demonstration

As an exercise to demonstrate the tool, I'm going to recreate a diagram of the PCIe Gen5 Link Training State Machine.  (because, fun!)  There are many approaches one could take here—one would be to use the PlantUML extension for Visual Studio Code (VS Code), write the diagram source code, and then let VS Code create the diagram.  A second approach would be to leverage an on-line renderer to create the diagram.  A third approach would be to feed the diagram source to the tool from the command-line to create an image.  I'll take the VS Code approach first, the on-line approach second, then the command-line approach third.

First, I installed the PlantUML extension for VS Code:

Then, I entered the following source code, following the PlantUML Reference Guide, doing my best to mimic what I see in the PCIe Spec:

@startuml Link Training and Status

hide empty description

<style>

    stateDiagram {

        FontName Consolas

        LineColor Red

        FontColor Green

        Arrow {

            FontSize 13

            LineColor Blue

        }

    }

</style>

state Detect

state Polling

state Configuration

state Disabled

state Hot_Reset

state Loopback

state Recovery

state L0

state L0s

state L1

state L2

[*] --> Detect

Detect --> Polling

Polling --> Detect

Polling --> Configuration

Configuration --> Disabled

Configuration --> Detect

Configuration --> Loopback

Configuration --> L0

Configuration --> Recovery

L0 --> L0s

L0 --> L1

L0 --> L2

L0 --> Recovery

L0s --> L0

L0s --> Recovery

L2 --> Detect

L1 --> Recovery

Recovery --> L0

Recovery --> Configuration

Recovery --> Detect

Recovery --> Loopback

Recovery --> Hot_Reset

Recovery --> Disabled

Loopback --> Recovery

Loopback --> Detect

Hot_Reset --> Detect

Disabled --> Detect

@enduml

I pressed Alt+D to view the diagram preview, and got:

Compare my result to the actual diagram in the PCIe Spec:

There is also an on-line, web-based PlantUML renderer, PlantText.  Pasting the same source code into that tool I get the same result:

Finally, you can download the PlantUML tool (it's a Java .jar file), feed it your source, and it will output the diagram as a .png file:

java -jar plantuml.jar src.txt

This takes the diagram's title from the source code, Link Training and Status, and outputs it as Link Training and Status.png.  No surprise, the output is identical to the previous two approaches:

Support

• PlantUML source code is stored on GitHub:  https://github.com/plantuml/plantuml
• Get the latest releases of PlantUML here:  https://github.com/plantuml/plantuml/releases
• Here's the PlantUML Quick Start Guide.
• PlantUML reference guide:  https://plantuml.com/guide
• A wealth of text editors have support for PlantUML.  A partial list includes Atom, Eclipse, Notepad++, Sublime Text, and Visual Studio Code.  (full list)
• PlantUML can be integrated into many other development tools, e.g. Confluence, Sphinx, GitLab, Docker, and the list goes on and on.

All in all, PlantUML is a robust, mature, powerful, open-source tool that is well-supported by the industry.  I encourage you to check it out and try using it in your architectural/development workflows!