OP-35 GCS/Qymodem_lib Clean up, documented, and gave credits to some sources.

Qymodem library is used by the Uploader plugin in order to upload files via Y-Modem protocol to the Openpilot's HW bootloader.
It has been tested with MS Hyperterminal. 
I'm still waiting for feedback about usage with real HW.

git-svn-id: svn://svn.openpilot.org/OpenPilot/trunk@494 ebee16cc-31ac-478f-84a7-5cbb03baadba

ground/src/libs/qymodem/src/qymodem.cpp

@@ -1,3 +1,14 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodem.cpp
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief      Implementation of base class for QymodemTx.
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
 /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -13,10 +24,11 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
-/**
-@file
 
-@brief Implementation of base class for YModemRx and YModemTx.
+/*!
+*   \section Credits
+*   This implementation is based on J.D.Medhurst (a.k.a. Tixy) work from
+*   <a href="http://yxit.co.uk">Tixy's source code</a>.
 */
 
 #include "qymodem.h"

ground/src/libs/qymodem/src/qymodem.h

@@ -1,3 +1,14 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodem.h
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
 /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -14,20 +25,47 @@
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
 
+/*!
+*   \section Credits
+*   This implementation is based on J.D.Medhurst (a.k.a. Tixy) work from
+*   <a href="http://yxit.co.uk">Tixy's source code</a>.
+*/
+
 #ifndef YMODEM_H
 #define YMODEM_H
 #include <qextserialport/src/qextserialport.h>
 #include <QThread>
 
-
+/**
+Base Class for QymodemTx.
+*/
 class QymodemBase: public QThread
 {
     Q_OBJECT
 signals:
-    void Error(QString,int);
+    /*!
-    void Information(QString,int);
+      An error has ocorred.
-    ///
+
-    void Percent(int);
+      \param errorString A string containing the error that has occurred.
+
+      \param errorNumber The error code.
+    */
+    void Error(QString errorString,int errorNumber);
+    /*!
+      Information regarding a change of state in the transmission process.
+
+      \param infoString A string containing the information of the new state.
+
+      \param infoNumber The information number of the new state.
+    */
+    void Information(QString infoString,int infoNumber);
+    /*!
+      Percentage of the file already sent.
+
+      \param percentSent The percentage of the file already sent.
+
+    */
+    void Percent(int percentSent);
 
 protected:
 

ground/src/libs/qymodem/src/qymodem_tx.cpp

@@ -1,3 +1,14 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodem_tx.cpp
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief      Implementation of base class for QymodemSend.
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
 /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -13,16 +24,14 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
-/**
-@file
 
-@brief Implementation of Y-Modem transmit protocol.
+/*!
+*   \section Credits
+*   This implementation is based on J.D.Medhurst (a.k.a. Tixy) work from
+*   <a href="http://yxit.co.uk">Tixy's source code</a>.
 */
 
-
 #include "qymodem_tx.h"
-
-
 #include <string.h> // for memcpy and memset
 
 
@@ -366,15 +375,6 @@ QymodemTx::QymodemTx(QextSerialPort& port)
         }
 
 
-int QymodemTx::SendX(InStream& in, unsigned timeout, bool kMode)
-        {
-        Use1KBlocks = kMode;
-        int result = SendInitialise(timeout);
-        if(result<0)
-                return result;
-        return SendAll(in);
-        }
-
 
 int QymodemTx::SendY(const char* fileName, size_t size, InStream& in, unsigned timeout)
         {
@@ -418,4 +418,3 @@ int QymodemTx::SendY(const char* fileName, size_t size, InStream& in, unsigned t
         return 0;
         }
 
-

ground/src/libs/qymodem/src/qymodem_tx.h

@@ -1,3 +1,14 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodem_tx.h
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
 /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -14,18 +25,18 @@
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
 
-/**
+/*!
-@file
+*   \section Credits
-
+*   This implementation is based on J.D.Medhurst (a.k.a. Tixy) work from
-@brief Y-Modem transmit protocol.
+*   <a href="http://yxit.co.uk">Tixy's source code</a>.
 */
+
 #ifndef YMODEM_TX_H
 #define YMODEM_TX_H
 #include "qymodem.h"
 
 /**
-@brief Y-Modem transmiter object.
+Base Class for QymodemSend.
-@ingroup ymodem
 */
 class QymodemTx : public QymodemBase
         {
@@ -61,15 +72,6 @@ public:
                 inline virtual ~InStream() {}
                 };
 
-        /**
-        Send data using X-Modem.
-
-        @param in		The stream of data to send.
-        @param timeout	Time in milliseconds to wait receiver to become ready.
-        @param kMode	False to use 128 byte blocks, true to use 1kB blocks
-        @return Zero if transfer was successful, or a negative error value if failed.
-        */
-        int SendX(InStream& in, unsigned timeout, bool kMode);
 
         /**
         Send data using Y-Modem.
@@ -92,16 +94,19 @@ public:
                 ErrorReceiverNotBehaving		= -301,	/**< Unexpected data received */
                 ErrorTranferTerminatedByReceiver= -302,	/**< Transfer was terminated by receiver */
                 ErrorFileNameTooLong			= -303,	/**< File name was too long to be transmitted */
-                ErrorFileNotFound= -303,
+                ErrorFileNotFound                       = -303,/**< Error file not found */
-                ErrorCoulNotOpenPort= -304,
+                ErrorCoulNotOpenPort                    = -304,/**< Error Port could not be open */
-                ErrorFileTransmissionInProgress = -305
+                ErrorFileTransmissionInProgress         = -305/**< Error, user tried to transmit a File while other File transmisssion is in progress */
 
             };
+        /**
+        Enumeration of possible information values.
+        */
         enum Info
         {
-            InfoSending= -100,
+            InfoSending                                 = -100,/**< Info, the transmission started and the file is being sent*/
-            InfoSent=-101,
+            InfoSent                                    =-101,/**< Info, transmission finished,the file as been sent */
-            InfoWaitingforReceiver=-102
+            InfoWaitingforReceiver                      =-102/**< Info, the transmission is waiting for the receiver to signal begin of transfer */
         };
 
 private:

ground/src/libs/qymodem/src/qymodemfilestream.cpp

@@ -0,0 +1,126 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodemsend.cpp
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief      Implementation of Class for presenting a file as a input stream.
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+/*!
+*   \section Credits
+*   This implementation is based on J.D.Medhurst (a.k.a. Tixy) work from
+*   <a href="http://yxit.co.uk">Tixy's source code</a>.
+*/
+
+#include "qymodem_tx.h"
+
+/**
+Class for presenting a file as a input stream.
+*/
+class QymodemFileStream : public QymodemTx::InStream
+{
+public    :
+    QymodemFileStream()
+        : File(0)
+    {
+    }
+
+
+    /**
+    Open the file stream.
+
+    @param filename	The name of the file to Open.
+
+    @return Zero if successful, or a negative error value if failed.
+
+    */
+    int Open(const char* fileName)
+    {
+        File = fopen(fileName,"rb");
+        if(!File)
+            return QymodemTx::ErrorInputStreamError;
+        // find file size...
+        if(fseek(File,0,SEEK_END))
+        {
+            fclose(File);
+            return QymodemTx::ErrorInputStreamError;
+        }
+        TotalSize = ftell(File);
+        if(fseek(File,0,SEEK_SET))
+        {
+            fclose(File);
+            return QymodemTx::ErrorInputStreamError;
+        }
+        TransferredSize = 0;
+        return 0;
+    }
+
+    /**
+        Close the stream.
+        */
+    void Close()
+    {
+        if(File)
+        {
+            fclose(File);
+            File = 0;
+        }
+    }
+
+    /**
+        Return the size of the file.
+
+        @return File size.
+        */
+    inline size_t Size()
+    {
+        return TotalSize;
+    }
+
+    /**
+        Read data from the stream.
+
+        @param[out] data	Pointer to buffer to hold data read from stream.
+        @param size			Maximum size of data to read.
+
+        @return Zero if successful, or a negative error value if failed.
+        */
+    int In(quint8* data, size_t size)
+    {
+        percent = TotalSize ? ((quint64)TransferredSize*(quint64)100)/(quint64)TotalSize : 0;
+        fflush(stdout);
+        size=fread(data,sizeof(quint8),size,File);
+        if(size)
+        {
+            TransferredSize += size;
+            return size;
+        }
+        if(TransferredSize!=TotalSize)
+            return QymodemTx::ErrorInputStreamError;
+        return 0;
+    }
+private:
+    FILE* File;
+    size_t TotalSize;
+    size_t TransferredSize;
+
+};

ground/src/libs/qymodem/src/qymodemsend.cpp

@@ -1,3 +1,14 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodemsend.cpp
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief      Implementation of Y-Modem File transmit protocol.
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
 /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -17,122 +28,29 @@
 #include "qymodemsend.h"
 
 
+/**
+Constructor.
+
+@param port	The port to use for File transmission.
+
+
+*/
 QymodemSend::QymodemSend(QextSerialPort& port)
     : QymodemTx(port)
     {
 
     }
 
-/**
-Class for presenting a file as a input stream.
-*/
-class QymodemSend::InFile : public QymodemTx::InStream
-{
-public:
-    InFile()
-        : File(0)
-    {
-    }
-    /**
-        Open stream for reading a file.
-
-        @param fileName		Name of the file to read.
-
-        @return Zero if successful, or a negative error value if failed.
-        */
-
-
-    int Open(const char* fileName)
-    {
-        File = fopen(fileName,"rb");
-        if(!File)
-            return QymodemTx::ErrorInputStreamError;
-        // find file size...
-        if(fseek(File,0,SEEK_END))
-        {
-            fclose(File);
-            return QymodemTx::ErrorInputStreamError;
-        }
-        TotalSize = ftell(File);
-        if(fseek(File,0,SEEK_SET))
-        {
-            fclose(File);
-            return QymodemTx::ErrorInputStreamError;
-        }
-        TransferredSize = 0;
-        return 0;
-    }
-
-    /**
-        Close the stream.
-        */
-    void Close()
-    {
-        if(File)
-        {
-            fclose(File);
-            File = 0;
-        }
-    }
-
-    /**
-        Return the size of the file.
-
-        @return File size.
-        */
-    inline size_t Size()
-    {
-        return TotalSize;
-    }
-
-    /**
-        Read data from the stream.
-
-        @param[out] data	Pointer to buffer to hold data read from stream.
-        @param size			Maximum size of data to read.
-
-        @return Zero if successful, or a negative error value if failed.
-        */
-    int In(quint8* data, size_t size)
-    {
-       // mutex.lock();
-        percent = TotalSize ? ((quint64)TransferredSize*(quint64)100)/(quint64)TotalSize : 0;
-        //mutex.unlock();
-        fflush(stdout);
-        size=fread(data,sizeof(quint8),size,File);
-        if(size)
-        {
-            TransferredSize += size;
-            return size;
-        }
-        if(TransferredSize!=TotalSize)
-            return QymodemTx::ErrorInputStreamError;
-        return 0;
-    }
-private:
-  //  QMutex mutex;
-    FILE* File;
-    size_t TotalSize;
-    size_t TransferredSize;
-
-};
-
-
-/**
-Class for presenting a file as a output stream.
-*/
-
 
 
 /**
 Send the file.
 
-@param port	The serial port to use.
 */
 void QymodemSend::Send()
 {
 
-    InFile source;
+    QymodemFileStream source;
     int error = source.Open(FileName);
     if(error)
         emit Error("Can't open file " + QString(FileName),error);
@@ -151,7 +69,14 @@ void QymodemSend::Send()
     }
     source.Close();
 }
+/**
+Send file.
 
+@param filename	The name of the file to Send.
+
+@return Zero if successful, or a negative error value if failed.
+
+*/
 int QymodemSend::SendFile(QString filename)
 {
     QFile file;
@@ -172,7 +97,14 @@ int QymodemSend::SendFile(QString filename)
         return 0;
 
 }
+/**
+Send file on a new Thread.
 
+@param filename	The name of the file to Send.
+
+@return Zero if successful, or a negative error value if failed.
+
+*/
 int QymodemSend::SendFileT(QString filename)
 {
     if(!isRunning())
@@ -186,6 +118,7 @@ int QymodemSend::SendFileT(QString filename)
     }
     return 0;
 }
+
 void QymodemSend::run()
 {
     QFile file;

ground/src/libs/qymodem/src/qymodemsend.h

@@ -1,3 +1,14 @@
+/**
+ ******************************************************************************
+ *
+ * @file       qymodemsend.h
+ * @author     The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
+ * @brief
+ * @see        The GNU Public License (GPL) Version 3
+ * @defgroup   ymodem_lib
+ * @{
+ *
+ *****************************************************************************/
 /*
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -14,11 +25,13 @@
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
 
+
 #ifndef QYMODEMSEND_H
 #define QYMODEMSEND_H
 #include "qymodem_tx.h"
 #include <QString>
 #include <QFile>
+#include "qymodemfilestream.cpp"
 
 #ifdef Q_OS_WIN
 #define _DEVICE_SET_ QIODevice::ReadWrite|QIODevice::Unbuffered
@@ -26,6 +39,9 @@
 #define _DEVICE_SET_ QIODevice::ReadWrite
 #endif
 
+/**
+Class for sending a file via Y-Modem transmit protocol.
+*/
 class QymodemSend:public QymodemTx
 {
 
@@ -38,7 +54,7 @@ private:
     void run();
     const char* FileName;
     void Send();
-    class InFile;
+    QymodemFileStream InFile;
     QString FileNameT;
 
 };

ground/src/libs/qymodem/src/src.pro

@@ -6,13 +6,12 @@ include(../../../openpilotgcslibrary.pri)
 # CONFIG                 += staticlib
 SOURCES += qymodem.cpp \
     qymodem_tx.cpp \
+    qymodemfilestream.cpp \
     qymodemsend.cpp
 HEADERS += qymodem_tx.h \
     qymodem.h \
     qymodemsend.h
-
 LIBS += -l$$qtLibraryTarget(QExtSerialPort)
 
-#CONFIG(debug, debug|release):LIBS += -lqextserialportd
+
-#else:LIBS += -lqextserialport
 win32:LIBS += -lsetupapi