I wanted to represent a Finite State Machine (FSM) for my sump pump monitor. Grabbing my coding stick, I create the FSM on paper in my project journal. Then I take a photo of this and I’m done.
But not really done because the photo is 3.3 MB. I download it from Google Photos and open it in my Macbook using Preview. I select the portion of the page with the selection tool and copy this part of the image to the clipboard and then I use Preview’s “New from Clipboard” command to create a PNG image file. This file is still 1.7MB.
Now I am glad I installed ImageMagick so I can easily reduce the size of photos.
convert 'spm\_states\_hand\_drawn.png\[800x600\]' \
spm\_states\_hand\_drawn1.png
After that I have this 186 KB file: 
But I am not satisfied with this.
What was that command line utility that I used for drawing graphs when I was working with RDF? Ah, it was "dot". The command is dot and it is contained in the Graphviz package. The site has source and documentation. And there is a Homebrew installation:
$ brew install graphviz
I did this and it works just fine. I bow in the general direction of Homebrew.
So dot allows me to define the FSM in code and create a nice graph for inclusion in documentation.
The Graphviz package implements several languages for drawing graphs. The dot language is for drawing directed graphs. Just what you need for a FSM. The drawing is coded into a file then compiled with the dot command, outputting the kind of image you want.
The FSM concepts from the hand drawing are coded into the dot language:
digraph SPM_states {
Start -> Setup
Setup -> NoEvent
NoEvent -> NoEvent [ label=" 1. A0 < noise"];
NoEvent -> Event [ label=" 2. A0 > noise"];
Event -> Event [ label=" 3. time < limit"];
Event -> NoEvent [ label=" 4. time > limit"];
}
I save the statements as file spm_states.dot and run this command to produce an image file:
$ dot -Tpng spm_states.dot -o spm_states.png
Now I have this 26 KB PNG file:
Perfect for embedding in a document. But what if I am using Markdown to compose my documentation? Check this out: mermaid: text tool for graphs
