Serial-Studio/doc/doxygen/README.md

The hacker's notebook (WIP)

Hi! If you are reading this, you are probably trying to understand how this software works internally. Good for you!

In general, I try to write DOXYGEN comments to explain what each function does. However, this does not help newcomers understand how a program's source code is organized (or how it works). For this reason, I will try to explain what each folder & class does in this document.

Think of this file as an introductory document for colaborators, hackers and geeks.

Of course, if this documentation is not clear enough (or you are a good writer), you are very welcome to fork this project, modify it & create a pull request.

But I'm not a coder!

Don't worry! You can help this project by reporting bugs, providing ideas, creating translations, writing about it in your blog/vlog, etc. You can also donate through PayPal!

Software architecture

Before explaining what each module does, please take a look at the "high-level" architecture of Serial Studio. If you have any doubts, feel free to use any of the support channels provided by the maintainers of the project.

Source code organization

Since there are over 30 source files that compromise this project (not including any libraries or the UI/QML part), it is important to keep the files organized in subdirectories corresponding to the their respective high-level functionalities.

Here is a breakdown of each subdirectory of the source code:

• The CSV directory contains the CSV::Export module and the CSV::Player functionality.
• The IO folder contains the IO::Manager, handlers for device data sources IO::DataSources::Serial, IO::DataSources::Network & IO::Console data handler.
  • The I/O manager & console are implemented as singleton classes.
• The JSON folder contains the following classes:
  • A JSON::Frame object represents the title, groups & datasets of a single frame. The frame object is generated by combining information received from the connected device and the JSON map file.
    • The JSON::Group class represents a group object. Groups contain a title and an array of datasets.
    • The JSON::Dataset class represents a dataset object. Datasets contain a title, a value and the units in which the dataset is measured (e.g. volts, meters, seconds, etc).
  • The JSON::Generator class receives data from the I/O Manager and uses the JSON map file to generate a JSON document that is used to create a Frame object.
  • JSON::FrameInfo (JFI) implements a structure that contains a JSON frame, the RX date/time and the frame ID number.
  • The JSON::Editor provides the necessary logic to allow users to build JSON files directly from the user interface.
• The Misc directory contains several utility classes, such as the global Misc::TimerEvents class, which is used to update the UI elements at a given frequency. Or the Misc::ModuleManager, which is used to initialize the application.
• The MQTT::Client module contains a singleton class that allows Serial Studio to act as an MQTT client.
• The Plugins folder contains a simple Plugins::Server that allows Serial Studio to interact with external applications/plugins.
• The UI folder contains the QML data provider, which provides QML-friendly functions so that the QML user interface can represent the lastest JSON::Frame object.
• The Widgets directory contains several QWidget based controls adapted to be used with a QML interface, most of the user interface elements that display data are implemented here. Most of the widgets are implemented with the help of Qwt.

What about the user interface?

The user interface is written in QtQuick/QML. You can find the "source code" of the user interface in the $PROJ_ROOT/assets/qml folder.

Coding styles

If possible, please follow the coding conventions defined in the .clang-format file. If you are as lazy as me, you can download and install clang-format-all and run the following command before making a commit:

clang-format-all src

This will apply the style defined in the .clang-format file recursively to all C++ headers and sources in the project. No need to worry about writing "ugly" code anymore!

IMPORTANT! Please write explanatory comments to document your changes!