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. Maybe there are superior and more "pure" ways of doing this, but I really like the simplicity of markdown & git.

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 I/O Manager, handlers for device data sources (serial port, network port) & console handler.
- The I/O manager & console are implemented as singleton classes.
The JSON folder contains the following classes:
- A 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 Group class represents a group object. Groups contain a title and an array of datasets.
  - The 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 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.
- FrameInfo (JFI) implements a structure that contains a JSON frame, the RX date/time and the frame ID number. This structure is needed because the Generator class builds each frame in a different thread (to avoid freezing the UI thread at high baud-rates).
- 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 TimerEvents class, which is used to update the UI elements at a given frequency.
MQTT contains a singleton class that allows Serial Studio to act as an MQTT client.
The Plugins folder contains a simple TCP 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 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.

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!

TODOs for this document

Add README.md files for each subdirectory of this project