Revision 38:e6cab4632d84, committed 2014-04-11

Comitter:

mazgch

Date:

Fri Apr 11 16:30:54 2014 +0000

Parent:

37:cc3433329d66

Child:

39:9b4b9433e220

Commit message:

more docu

Changed in this revision

--- a/GPS.h	Thu Apr 10 13:44:54 2014 +0000
+++ b/GPS.h	Fri Apr 11 16:30:54 2014 +0000
@@ -13,6 +13,8 @@
  #define _C027DEFAULT(name)
 #endif
 
+/** basic gps parser class 
+*/
 class GPSParser
 {
 public:
@@ -44,41 +46,120 @@
     static const char toHex[16];
 };
 
+/** gps class which uses a serial port 
+    as physical interface. 
+*/
 class GPSSerial : public SerialPipe, public GPSParser
 {
 public:
+    /** Constructor
+        \param tx is the serial ports transmit pin (gps to CPU)
+        \param rx is the serial ports receive pin (CPU to gps)
+        \param baudrate the baudrate of the gps use 9600
+        \param rxSize the size of the serial rx buffer
+        \param txSize the size of the serial tx buffer
+    */
     GPSSerial(PinName tx    _C027DEFAULT( GPSTXD ), 
               PinName rx    _C027DEFAULT( GPSRXD ), 
               int baudrate  _C027DEFAULT( GPSBAUD ),
               int rxSize    = 256 , 
               int txSize    = 128 );
+    /** Get a line from the physical interface. 
+        \param buf the buffer to store it
+        \param len size of the buffer
+        \return type and length if something was found, 
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
     virtual int getMessage(char* buf, int len);
 protected:
+    /** Write bytes to the physical interface.
+        \param buf the buffer to write
+        \param len size of the buffer to write
+        \return bytes written
+    */
     virtual int _send(const void* buf, int len);
 };
 
+/** gps class which uses a i2c as physical interface. 
+*/
 class GPSI2C : public I2C, public GPSParser
 {
 public: 
+    /** Constructor
+        \param sda is the I2C SDA pin (between CPU and GPS)
+        \param scl is the I2C SCL pin (CPU to GPS) 
+        \param adr the I2C address of the GPS set to (66<<1)
+        \param rxSize the size of the serial rx buffer
+    */
     GPSI2C(PinName sda          _C027DEFAULT( GPSSDA ), 
            PinName scl          _C027DEFAULT( GPSSCL ),
            unsigned char i2cAdr _C027DEFAULT( GPSADR ), 
            int rxSize           = 256 );
+    /** helper function to probe the i2c device
+        \return true if successfully detected the gps. 
+    */ 
     bool detect(void);
     
+    /** Get a line from the physical interface. 
+        \param buf the buffer to store it
+        \param len size of the buffer
+        \return type and length if something was found, 
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
     virtual int getMessage(char* buf, int len);
+    
+    /** send a buffer
+        \param buf the buffer to write
+        \param len size of the buffer to write
+        \return bytes written
+    */
     virtual int send(const char* buf, int len);
+    
+    /** send a NMEA message, this function just takes the 
+        payload and calculates and adds checksum. ($ and *XX\r\n will be added)
+        \param buf the message payload to write
+        \param len size of the message payload to write
+        \return total bytes written
+    */
     virtual int sendNmea(const char* buf, int len);
+    
+    /** send a UBX message, this function just takes the 
+        payload and calculates and adds checksum.
+        \param cls the UBX class id 
+        \param id the UBX message id
+        \param buf the message payload to write
+        \param len size of the message payload to write
+        \return total bytes written
+    */
     virtual int sendUbx(unsigned char cls, unsigned char id, const void* buf = NULL, int len = 0);
 protected:
+    /** check if the port is writeable (like SerialPipe)
+        \return true if writeable        
+    */
     bool writeable(void) { return true; }
+    /** Write a character (like SerialPipe)
+        \param c  the character to write
+        \return true if succesffully written 
+    */
     bool putc(int c)     { char ch = c; return send(&ch, 1); }
+    /** Write bytes to the physical interface.
+        \param buf the buffer to write
+        \param len size of the buffer to write
+        \return bytes written
+    */
     virtual int _send(const void* buf, int len);
-    int _get(char* buf, int len);                 // read the NMEA or UBX stream
+    /** read bytes from the physical interface.
+        \param buf the buffer to read into
+        \param len size of the read buffer 
+        \return bytes read
+    */
+    int _get(char* buf, int len);
     
-    Pipe<char> _pipe; 
-    bool found;
-    unsigned char _i2cAdr; 
-    static const char REGLEN;
-    static const char REGSTREAM;
+    Pipe<char> _pipe;           //!< the rx pipe
+    bool found;                 //!< flag if device is detected.
+    unsigned char _i2cAdr;      //!< the i2c address
+    static const char REGLEN;   //!< the length i2c register address
+    static const char REGSTREAM;//!< the stream i2c register address
 };

--- a/MDM.h	Thu Apr 10 13:44:54 2014 +0000
+++ b/MDM.h	Fri Apr 11 16:30:54 2014 +0000
@@ -15,6 +15,8 @@
  #define _C027DEFAULT(name)
 #endif
 
+/** basic modem parser class 
+*/
 class MDMParser
 {
 public:
@@ -24,9 +26,13 @@
     // ----------------------------------------------------------------
     // Types 
     // ----------------------------------------------------------------
-    typedef enum { DEV_UNKNOWN, DEV_SARA_G350, DEV_LISA_U200, DEV_LISA_C200 } Dev; //!< MT Device Types 
-    typedef enum { SIM_UNKNOWN, SIM_PIN, SIM_READY } Sim; //!< SIM Status
-    typedef enum { LPM_DISABLED, LPM_ENABLED, LPM_ACTIVE, LPM_SLEEP } Lpm; //!< SIM Status
+    //! MT Device Types 
+    typedef enum { DEV_UNKNOWN, DEV_SARA_G350, DEV_LISA_U200, DEV_LISA_C200 } Dev; 
+    //! SIM Status
+    typedef enum { SIM_UNKNOWN, SIM_PIN, SIM_READY } Sim;
+    //! SIM Status
+    typedef enum { LPM_DISABLED, LPM_ENABLED, LPM_ACTIVE, LPM_SLEEP } Lpm; 
+    //! Device status
     typedef struct { 
         Dev dev;            //!< Device Type
         Lpm lpm;            //!< Power Saving 
@@ -38,17 +44,21 @@
         char manu[16];      //!< Manufacturer (u-blox)
         char model[16];     //!< Model Name (LISA-U200, LISA-C200 or SARA-G350)
         char ver[16];       //!< Software Version
-    } DevStatus;            //!< Device status
-    typedef enum { REG_UNKNOWN, REG_DENIED, REG_NONE, REG_HOME, REG_ROAMING } Reg; //!< Registration Status
-    typedef enum { ACT_UNKNOWN, ACT_GSM, ACT_EDGE, ACT_UTRAN, ACT_CDMA } AcT; //!< Access Technology
+    } DevStatus;
+    //! Registration Status
+    typedef enum { REG_UNKNOWN, REG_DENIED, REG_NONE, REG_HOME, REG_ROAMING } Reg; 
+    //! Access Technology
+    typedef enum { ACT_UNKNOWN, ACT_GSM, ACT_EDGE, ACT_UTRAN, ACT_CDMA } AcT; 
+    //! Network Status
     typedef struct { 
         Reg reg;        //!< Registration Status
         AcT act;        //!< Access Technology
         int rssi;       //!< Received Signal Strength Indication (in dBm, range -113..-53)
         char opr[16+1]; //!< Operator Name
         char num[32];   //!< Mobile Directory Number
-    } NetStatus;        //!< Network Status
-    typedef uint32_t IP; //!< An IP v4 address
+    } NetStatus;
+    //! An IP v4 address
+    typedef uint32_t IP;
     #define NOIP ((MDMParser::IP)0) //!< No IP address
     // ip number formating and conversion
     #define IPSTR           "%d.%d.%d.%d"
@@ -232,11 +242,11 @@
     */
     bool ussdCommand(const char* cmd, char* buf);
     
-     // ----------------------------------------------------------------
+    // ----------------------------------------------------------------
     // Parseing
     // ----------------------------------------------------------------
     
-   // waitFinalResp Responses
+    // waitFinalResp Responses
     #define NOT_FOUND    0
     #define WAIT        -1 // TIMEOUT
     #define OK          -2 
@@ -382,7 +392,7 @@
     typedef struct { int* ix; int num; } CMGLparam;
     static int _cbCMGL(int type, const char* buf, int len, CMGLparam* param);
     static int _cbCMGR(int type, const char* buf, int len, CMGRparam* param);
-    // 
+    // variables
     DevStatus   _dev; //!< collected device information
     NetStatus   _net; //!< collected network information 
     IP          _ip;  //!< assigned ip address
@@ -394,9 +404,24 @@
 
 // -----------------------------------------------------------------------
 
+/** modem class which uses a serial port 
+    as physical interface. 
+*/
 class MDMSerial :  public SerialPipe, public MDMParser
 {
 public: 
+    /** Constructor
+    
+        \param tx is the serial ports transmit pin (modem to CPU)
+        \param rx is the serial ports receive pin (CPU to modem)
+        \param baudrate the baudrate of the modem use 115200
+        \param rts is the serial ports ready to send pin (CPU to modem) 
+               this pin is optional 
+        \param cts is the serial ports clear to send pin (modem to CPU) 
+               this pin is optional, but required for power saving to be enabled
+        \param rxSize the size of the serial rx buffer
+        \param txSize the size of the serial tx buffer
+    */
     MDMSerial(PinName tx    _C027DEFAULT(MDMTXD), 
               PinName rx    _C027DEFAULT(MDMRXD), 
               int baudrate  _C027DEFAULT(MDMBAUD),
@@ -406,14 +431,26 @@
  #endif
               int rxSize    = 256 , 
               int txSize    = 128 );
+    /** Get a line from the physical interface. 
+        \param buf the buffer to store it
+        \param buf size of the buffer
+        \return type and length if something was found, 
+                WAIT if not enough data is available
+                NOT_FOUND if nothing was found
+    */ 
     virtual int getLine(char* buffer, int length);
 protected:
+    /** Write bytes to the physical interface.
+        \param buf the buffer to write
+        \param buf size of the buffer to write
+        \return bytes written
+    */
     virtual int _send(const void* buf, int len);
 };
 
 // -----------------------------------------------------------------------
 
-#define HAVE_MDMUSB
+//#define HAVE_MDMUSB
 #ifdef HAVE_MDMUSB
 class MDMUsb :  /*public UsbSerial,*/ public MDMParser
 {