Serial-Studio/src/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](https://www.doxygen.nl/index.html) 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](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).

### 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](https://www.paypal.com/donate?hosted_button_id=XN68J47QJKYDE) 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.

![Architecture](../doc/architecture/architecture.svg)

### Source code organization

Since there are over 30 source files that compromise this project (not including any libraries or the [UI/QML](../assets/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`](CSV) directory contains the CSV [`export`](CSV/Export.h) module and the CSV [`player`](CSV/Player.h) functionality.
- The [`IO`](IO) folder contains the [`I/O Manager`](IO/Manager.h), handlers for device data sources ([`serial port`](IO/DataSources/Serial.h), [`network port`](IO/DataSources/Network.h)) & [`console`](IO/Console.h) handler.
    - The I/O manager & console are implemented as [singleton classes](https://en.wikipedia.org/wiki/Singleton_pattern).
- The [`JSON`](JSON) folder contains the following classes:
	- A [`Frame`](JSON/Frame.h) 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`](JSON/Group.h) class represents a group object. Groups contain a title and an array of datasets.
		- The [`Dataset`](JSON/Dataset.h) 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`](JSON/Generator.h) class receives data from the [`I/O Manager`](IO/Manager.h) and uses the JSON map file to generate a JSON document that is used to create a [`Frame`](JSON/Frame.h) object.
	- [`FrameInfo`](JSON/FrameInfo.h) (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`](JSON/Generator.h) class builds each frame in a different thread (to avoid freezing the UI thread at high baud-rates).
	- The JSON [`Editor`](JSON/Editor.h) provides the necessary logic to allow users to build JSON files directly from the user interface.
- The [`Misc`](Misc) directory contains several utility classes, such as the global [`TimerEvents`](Misc/TimerEvents.h) class, which is used to update the UI elements at a given frequency.
- [`MQTT`](MQTT) contains a singleton class that allows Serial Studio to act as an [MQTT](https://en.wikipedia.org/wiki/MQTT) client.
- The [`Plugins`](Plugins) folder contains a simple [`TCP server`](Plugins/Bridge.h) that allows Serial Studio to interact with external applications/plugins.
- Finally, the [`UI`](UI) folder contains the QML data providers, which provide QML-friendly functions so that the QML user interface can represent the lastest [`Frame`](JSON/Frame.h) object in the form of [`data-boxes`](UI/DataProvider.h), [`graphs`](UI/GraphProvider.h) & [`widgets`](UI/WidgetProvider.h). 
	- The [`QmlPlainTextEdit`](UI/QmlPlainTextEdit.h) class implements a simple read-only text editor with [VT-100](https://en.wikipedia.org/wiki/VT100) emulation that can be used within QML.

**What about the user interface?** 

The user interface is written in [QtQuick/QML](https://doc.qt.io/qt-5/qtquick-index.html). You can find the "source code" of the user interface in the [`$PROJ_ROOT/assets/qml`](../assets/qml) folder.

## Coding styles

If possible, please follow the coding conventions defined in the [`.clang-format`](../.clang-format) file. If you are as lazy as me, you can download and install [clang-format-all](https://github.com/eklitzke/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`](../.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