Arduino FSM

This repository provides an example how to write a Finite-State-Machine (FSM) which can be nested in C++.
It's based on this Wiki-Article: Finite-state_machine and an example by R. Bonderer (HSR) from Embedded Software Engineering.

Table of contents

• Documentation
  • Software
    • Dependency graph
    • Collaboration diagram
• Documentation with Doxygen
  • What is Doxygen?
    • HowTo install Doxygen for Windows
    • HowTo install .dot and graphviz
    • HowTo run Doxygen
    • Doxygen and GitHub-Pages
    • Doxygen and VSCode
• Contributors
• Changelog
• License

Documentation

Software

View the GitHub-Page for the source-code documentation

Dependency graph

Click on image to open doxygen-documentation.

Collaboration diagram

Click on image to open doxygen-documentation.

Documentation with Doxygen

What is Doxygen?

Doxygen is a Open-Source documentation generator. It extracts source code documentation directly from the annotated code. Doxygen supports a lot of popular programming languages such as C++, C , Java, Python, etc.

For Doxygen to detect the documentation, special comments are needed. One example is shown below, but there are many more possible variants as shown in the Doxygen Documentation.

/**
 * @brief A short one line description
 *
 * <Longer description>
 * <May span multiple lines or paragraphs as needed>
 *
 * @param  Description of method's or function's input parameter
 * @param  ...
 * @return Description of the return value
 */

[Source: Wikipedia: Doxygen]
The main benefit of doxygen is, that the documentation can be written directly in the source code itself and is therefore easy to keep up to date. It can also automatically generate the visualization from relations between classes, objects, inheritance and other dependencies.

Doxygen can generate HTML, LaTeX, Man pages, RTF and XML output-files.

If you need more information about Doxygen-comments please refer to: How to Write Doxygen Doc Comments.

HowTo install Doxygen for Windows

Detailed instructions on how to install Doxygen can be found in the Doxygen Installation manual.

1. Download a binary distribution at Doxygen Download. It's called something like "doxygen-X.X.XX-setup.exe"
2. Select "Full Installation" (default option)
3. Go to the Control Panel → System and Security → System, and on the navigation panel on the right side, you will see the link Advanced systems settings.
4. Once in advanced systems settings, a dialogue box will open and show the button Environment Variables. Click on the button Environment Variables.
5. Add "c:/doxygen/bin" (or whatever path was used during the installation) to the System PATH variable to run "doxygen" without providing the full path to the binary.

[Source: PALISADE ]

HowTo install .dot and graphviz

If you like to draw class diagrams, collaboration diagrams, overall class hierarchy and dependency graphs you need to install the GraphViz package. You can download a stable Windows release on the Graphviz Website.

1. Download the installer for Windows (graphviz-X.XX.msi)
2. The default installation path will be C:\Program Files (x86)\GraphvizX.XX\bin (Example: GraphvizX.XX → Graphviz2.38)
3. Open cmd window as administrator and go the location C:\Program Files (x86)\GraphvizX.XX\bin and run the below command:

dot.exe

4. Exit the command window.
5. Go to the Control Panel → System and Security → System, and on the navigation panel on the right side, you will see the link Advanced systems settings.
6. Once in advanced systems settings, a dialogue box will open and show the button Environment Variables. Click on the button Environment Variables.
7. Select the entry "Path" on the system variables section and add C:\Program Files (x86)\Graphviz X.XX \bin to the existing path.

[Source: Atlassin-How to install Graphviz(Windows,Mac,Linux), Generating a callgraph in Doxygen]

HowTo run Doxygen

1. Start doxywizard (Desktop App)
2. Click on File->Open and choose Doxyfile in the folder doxygen
3. In doxywizard switch to the Tab Run and click on Run doxygen
4. When Doxygen has finished, click on Show HTML output.

If you like to generate diagrams make sure, that in the Tab Wizard/Diagrams the button "Use dot tool from GraphViz package" is activated.

You can use doxygen also only in console. Check the Doxygen-Documentation if you need to know more.

Doxygen and GitHub-Pages

1. Generate your doxyfile direct into ./docs.

2. You need to add an .nojekll file in ./docs.
   This is necessary because Jekyll considers directories that start with underscores to be special resources and does not copy them to the final site. [Source: Bypassing Jekyll on GitHub Pages]

3. Under Settings -> GitHub Pages -> Source choose master branche ./docs folder.

4. Save

Doxygen and VSCode

There's a useful extension for VSCode, called: Doxygen Documentation Generator.

You can personalize the apperance of the comments in the config-options: Manage/Settings/User/Extensions/Doxygen Documentation Generator Settings -> Edit in settings.json
It looks something like this:

"doxdocgen.generic.returnTemplate": "@return {type} - ",
​ "doxdocgen.generic.paramTemplate": "@param {param} - ",
​ "doxdocgen.file.versionTag": "@version 1.0 - Description - {author} - {date}",
​ "doxdocgen.file.fileOrder": [
​ "file",
​ "brief",
​ "empty",
​ "author",
​ "empty",
​ "version",
​ "empty",
​ "date",
​ "copyright",
​ "empty",
​ "custom"
​ ],

Contributors

• Luca Mazzoleni

Changelog

V 1.0 - Release BA FS19 - Luca Mazzoleni

License

MIT License