diff --git a/src/IO/Console.cpp b/src/IO/Console.cpp index 275bbe7c..50e5fcdb 100644 --- a/src/IO/Console.cpp +++ b/src/IO/Console.cpp @@ -287,7 +287,7 @@ void Console::send(const QString &data) { append(dataToString(bin)); m_timestampAdded = false; - if (m_cursor) + if (m_cursor && lineEnding() == LineEnding::NoLineEnding) m_cursor->insertBlock(); } } diff --git a/src/IO/DataSources/Serial.cpp b/src/IO/DataSources/Serial.cpp index 92410093..308b83b5 100644 --- a/src/IO/DataSources/Serial.cpp +++ b/src/IO/DataSources/Serial.cpp @@ -356,9 +356,12 @@ void Serial::setBaudRate(const qint32 rate) LOG_INFO() << "Baud rate set to" << rate; } +/** + * Changes the port index value, this value is later used by the @c openSerialPort() + * function. + */ void Serial::setPortIndex(const quint8 portIndex) { - auto ports = validPorts(); auto portId = portIndex - 1; if (portId >= 0 && portId < validPorts().count()) m_portIndex = portIndex; diff --git a/src/IO/Manager.cpp b/src/IO/Manager.cpp index 2e78cb06..54dc753a 100644 --- a/src/IO/Manager.cpp +++ b/src/IO/Manager.cpp @@ -6,8 +6,14 @@ using namespace IO; +/** + * Pointer to the only instance of the class. + */ static Manager *INSTANCE = nullptr; +/** + * Constructor function + */ Manager::Manager() : m_writeEnabled(true) , m_maxBuzzerSize(1024 * 1024) @@ -20,8 +26,14 @@ Manager::Manager() setWatchdogInterval(15); } +/** + * Destructor function + */ Manager::~Manager() { } +/** + * Returns the only instance of the class + */ Manager *Manager::getInstance() { if (!INSTANCE) @@ -30,16 +42,25 @@ Manager *Manager::getInstance() return INSTANCE; } +/** + * Returns @c true if a device is connected and its open in read-only mode + */ bool Manager::readOnly() { return connected() && !m_writeEnabled; } +/** + * Returns @c true if a device is connected and its open in read/write mode + */ bool Manager::readWrite() { return connected() && m_writeEnabled; } +/** + * Returns @c true if a device is currently selected and opened + */ bool Manager::connected() { if (device()) @@ -48,41 +69,94 @@ bool Manager::connected() return false; } +/** + * Returns @c true if a device is currently selected + */ bool Manager::deviceAvailable() { return device() != nullptr; } +/** + * Returns the interval of the watchdog in milliseconds. The watchdog is used to clear + * the data buffer if no data has been received in more than x milliseconds (default + * 15 ms, tested on a 300 baud rate MCU). + * + * This is useful for: a) Dealing when a device suddenly is disconnected + * b) Removing extra data between received frames + * + * Example: + * + * RRRRRRRRR watchdog clears buf. RRRRRRRRR watchdog clear buf. RRRRRRRR + * [--------] . - . - . - . - . - . [--------] . - . - . - . - . - . [--------] + * Frame A Interval of > 15 ms Frame B Interval of > 15 ms Frame C + * + * Note: in the representation above "R" means that the watchdog is reset, thus, the + * data buffer is not cleared until we wait for another frame or communications + * are interrupted. + * + * TODO: let the JSON project file define the watchdog timeout time. + */ int Manager::watchdogInterval() const { return m_watchdog.interval(); } +/** + * Returns the maximum size of the buffer. This is useful to avoid consuming to much + * memory when a large block of invalid data is received (for example, when the user + * selects an invalid baud rate configuration). + */ int Manager::maxBufferSize() const { return m_maxBuzzerSize; } +/** + * Returns a pointer to the currently selected device. + * + * @warning you need to check this pointer before using it, it can have a @c nullptr + * value during normal operations. + */ QIODevice *Manager::device() { return m_device; } +/** + * Returns the currently selected data source, possible return values: + * - @c DataSource::Serial use a serial port as a data source + * - @c DataSource::Network use a network port as a data source + */ Manager::DataSource Manager::dataSource() const { return m_dataSource; } +/** + * Returns the start sequence string used by the application to know where to consider + * that a frame begins. If the start sequence is empty, then the application shall ignore + * incoming data. The only thing that wont ignore the incoming data will be the console. + */ QString Manager::startSequence() const { return m_startSequence; } +/** + * Returns the finish sequence string used by the application to know where to consider + * that a frame ends. If the start sequence is empty, then the application shall ignore + * incoming data. The only thing that wont ignore the incoming data will be the console. + */ QString Manager::finishSequence() const { return m_finishSequence; } +/** + * Returns the size of the data received (and successfully read) from the device in the + * format of a string. + */ QString Manager::receivedDataLength() const { QString value; @@ -111,6 +185,9 @@ QString Manager::receivedDataLength() const return QString("%1 %2").arg(value).arg(units); } +/** + * Returns a list with the possible data source options. + */ QStringList Manager::dataSourcesList() const { QStringList list; @@ -119,6 +196,12 @@ QStringList Manager::dataSourcesList() const return list; } +/** + * Tries to write the given @a data to the current device. Upon data write, the class + * emits the @a tx() signal for UI updating. + * + * @returns the number of bytes written to the target device + */ qint64 Manager::writeData(const QByteArray &data) { // Write data to device @@ -134,6 +217,10 @@ qint64 Manager::writeData(const QByteArray &data) return bytes; } +/** + * Connects/disconnects the application from the currently selected device. This function + * is used as a convenience for the connect/disconnect button. + */ void Manager::toggleConnection() { if (connected()) @@ -142,12 +229,16 @@ void Manager::toggleConnection() connectDevice(); } +/** + * Closes the currently selected device and tries to open & configure a new connection. + * A data source must be selected before calling this function. + */ void Manager::connectDevice() { // Disconnect previous device (if any) disconnectDevice(); - // Set device handler + // Try to open a serial port connection if (dataSource() == DataSource::Serial) setDevice(DataSources::Serial::getInstance()->openSerialPort()); @@ -178,6 +269,9 @@ void Manager::connectDevice() } } +/** + * Disconnects from the current device and clears temp. data + */ void Manager::disconnectDevice() { if (deviceAvailable()) @@ -200,12 +294,18 @@ void Manager::disconnectDevice() } } +/** + * Enables/disables RW mode + */ void Manager::setWriteEnabled(const bool enabled) { m_writeEnabled = enabled; emit writeEnabledChanged(); } +/** + * Changes the data source type. Check the @c dataSource() funciton for more information. + */ void Manager::setDataSource(const DataSource source) { // Disconnect current device @@ -217,24 +317,40 @@ void Manager::setDataSource(const DataSource source) emit dataSourceChanged(); } +/** + * Changes the maximum permited buffer size. Check the @c maxBufferSize() function for + * more information. + */ void Manager::setMaxBufferSize(const int maxBufferSize) { m_maxBuzzerSize = maxBufferSize; emit maxBufferSizeChanged(); } +/** + * Changes the frame start sequence. Check the @c startSequence() function for more + * information. + */ void Manager::setStartSequence(const QString &sequence) { m_startSequence = sequence; emit startSequenceChanged(); } +/** + * Changes the frame end sequence. Check the @c finishSequence() function for more + * information. + */ void Manager::setFinishSequence(const QString &sequence) { m_finishSequence = sequence; emit finishSequenceChanged(); } +/** + * Changes the expiration interval of the watchdog timer. Check the @c watchdogInterval() + * function for more information. + */ void Manager::setWatchdogInterval(const int interval) { m_watchdog.setInterval(interval); @@ -242,6 +358,13 @@ void Manager::setWatchdogInterval(const int interval) emit watchdogIntervalChanged(); } +/** + * Read frames from temporary buffer, every frame that contains the appropiate start/end + * sequence is removed from the buffer as soon as its read. + * + * This function also checks that the buffer size does not exceed specified size + * limitations. + */ void Manager::readFrames() { // No device connected, abort @@ -279,12 +402,21 @@ void Manager::readFrames() clearTempBuffer(); } +/** + * Resets the watchdog timer before it expires. Check the @c watchdogInterval() function + * for more information. + */ void Manager::feedWatchdog() { m_watchdog.stop(); m_watchdog.start(); } +/** + * Reads incoming data from the serial device, updates the serial console object, + * registers incoming data to temporary buffer & extracts valid data frames from the + * buffer using the @c readFrame() function. + */ void Manager::onDataReceived() { // Verify that device is still valid @@ -313,16 +445,29 @@ void Manager::onDataReceived() emit rx(); } +/** + * Deletes the contents of the temporary buffer. This function is called automatically by + * the class when the temporary buffer size exceeds the limit imposed by the + * @c maxBufferSize() function. + */ void Manager::clearTempBuffer() { m_dataBuffer.clear(); } +/** + * Called when the watchdog timer expires. For the moment, this function only clears the + * temporary data buffer. + */ void Manager::onWatchdogTriggered() { clearTempBuffer(); } +/** + * Changes the target device pointer. Deletion should be handled by the interface + * implementation, not by this class. + */ void Manager::setDevice(QIODevice *device) { disconnectDevice(); diff --git a/src/JSON/Frame.cpp b/src/JSON/Frame.cpp index c90dfb13..f1e8de9a 100644 --- a/src/JSON/Frame.cpp +++ b/src/JSON/Frame.cpp @@ -24,17 +24,28 @@ using namespace JSON; +/** + * Constructor function + */ Frame::Frame(QObject *parent) : QObject(parent) , m_title("") { } +/** + * Destructor function, free memory used by the @c Group objects before destroying an + * instance of this class. + */ Frame::~Frame() { clear(); } +/** + * Resets the frame title and frees the memory used by the @c Group objects associated + * to the instance of the @c Frame object. + */ void Frame::clear() { for (int i = 0; i < groupCount(); ++i) @@ -44,21 +55,36 @@ void Frame::clear() m_groups.clear(); } +/** + * Returns the title of the frame. + */ QString Frame::title() const { return m_title; } +/** + * Returns the number of groups contained in the frame. + */ int Frame::groupCount() const { return groups().count(); } +/** + * Returns a vector of pointers to the @c Group objects associated to this frame. + */ QVector Frame::groups() const { return m_groups; } +/** + * Reads the frame information and all its asociated groups (and datatsets) from the given + * JSON @c object. + * + * @return @c true on success, @c false on failure + */ bool Frame::read(const QJsonObject &object) { // Rest frame data