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

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!

Next
This is the most recent post.
Previous
Older Post

Post a Comment

Be sure to select an account profile (e.g. Google, OpenID, etc.) before typing your comment!