Revision 41:8bec5a8ea878, committed 2012-09-21

Comitter:

ashleymills

Date:

Fri Sep 21 11:10:32 2012 +0000

Parent:

40:9c6c87297a37

Child:

42:daa4dd282103

Child:

44:6bbd8952f1c9

Commit message:

Added some descriptive comments to the code.

Changed in this revision

--- a/VodafoneUSBModem.cpp	Thu Sep 20 08:04:43 2012 +0000
+++ b/VodafoneUSBModem.cpp	Fri Sep 21 11:10:32 2012 +0000
@@ -26,11 +26,23 @@
 
 #include "VodafoneUSBModem.h"
 
-VodafoneUSBModem::VodafoneUSBModem(PinName powerGatingPin /*= NC*/, bool powerGatingOnWhenPinHigh /* = true*/) : m_dongle(),
-m_atStream(m_dongle.getSerial(1)), m_pppStream(m_dongle.getSerial(0)), m_at(&m_atStream),
-m_sms(&m_at), m_ussd(&m_at), m_linkMonitor(&m_at), m_ppp(&m_pppStream), 
-m_dongleConnected(false), m_ipInit(false), m_smsInit(false), m_ussdInit(false), m_linkMonitorInit(false), m_atOpen(false),
-m_powerGatingPin(powerGatingPin), m_powerGatingOnWhenPinHigh(powerGatingOnWhenPinHigh)
+VodafoneUSBModem::VodafoneUSBModem(PinName powerGatingPin /*= NC*/, bool powerGatingOnWhenPinHigh /* = true*/) :
+   m_dongle(),                         // Construct WANDongle: USB interface with two serial channels to the modem (USBSerialStream objects)
+   m_atStream(m_dongle.getSerial(1)),  // AT commands are sent down one serial channel.
+   m_pppStream(m_dongle.getSerial(0)), // PPP connections are managed via another serial channel.
+   m_at(&m_atStream),                  // Construct ATCommandsInterface with the AT serial channel
+   m_sms(&m_at),                       // Construct SMSInterface with the ATCommandsInterface
+   m_ussd(&m_at),                      // Construct USSDInterface with the ATCommandsInterface
+   m_linkMonitor(&m_at),               // Construct LinkMonitor with the ATCommandsInterface
+   m_ppp(&m_pppStream),                // Construct PPPIPInterface with the PPP serial channel
+   m_dongleConnected(false),           // Dongle is initially not ready for anything
+   m_ipInit(false),                    // PPIPInterface connection is initially down
+   m_smsInit(false),                   // SMSInterface starts un-initialised
+   m_ussdInit(false),                  // USSDInterface starts un-initialised 
+   m_linkMonitorInit(false),           // LinkMonitor subsystem starts un-initialised
+   m_atOpen(false),                    // ATCommandsInterface starts in a closed state
+   m_powerGatingPin(powerGatingPin),   // set power gating pin
+   m_powerGatingOnWhenPinHigh(powerGatingOnWhenPinHigh) // set state semantics for power gating pin
 {
   if( m_powerGatingPin != NC )
   {

--- a/VodafoneUSBModem.h	Thu Sep 20 08:04:43 2012 +0000
+++ b/VodafoneUSBModem.h	Fri Sep 21 11:10:32 2012 +0000
@@ -105,34 +105,49 @@
   int power(bool enable);
 
 protected:
-  bool power();
+  bool power(); //< Turn power to USB dongle ON.
 
+  /** Initialise dongle.
+   * The following actions are performed:
+   * 1) Power up
+   * 2) Establish USB connection to dongle
+   * 3) Start AT interface thread
+   * 4) Wait for network registration
+   */
   int init();
+  
+  /** De-initialise dongle.
+   * The following actions are performed:
+   * 1) Tear down PPP session
+   * 2) Set SMS,USSD, and LinkMonitor subsystems to un-initialised
+   * 3) Close the AT commands interface
+   * 4) Tear down the USB connection to dongle
+   */
   int cleanup();
 
 private:
-  WANDongle m_dongle;
+  WANDongle m_dongle;          //< Interface to USB connected WAN dongle
   
-  USBSerialStream m_atStream;
-  USBSerialStream m_pppStream;
+  USBSerialStream m_atStream;  //< Serial interface to AT channel on modem
+  USBSerialStream m_pppStream; //< Serial interface to PPP channel on modem
   
-  ATCommandsInterface m_at;
+  ATCommandsInterface m_at;    //< Interface to AT commands processing
   
-  SMSInterface m_sms;
-  USSDInterface m_ussd;
-  LinkMonitor m_linkMonitor;
+  SMSInterface m_sms;          //< Interface to SMS manager (send/receive etc)
+  USSDInterface m_ussd;        //< Interface to USSD manager (send etc)
+  LinkMonitor m_linkMonitor;   //< Interface to link monitor (RSSI)
   
-  PPPIPInterface m_ppp;
+  PPPIPInterface m_ppp;        //< Interface to PPP conection manager (IP assignment etc)
 
-  bool m_dongleConnected;
-  bool m_ipInit;
-  bool m_smsInit;
-  bool m_ussdInit;
-  bool m_linkMonitorInit;
-  bool m_atOpen;
+  bool m_dongleConnected; //< Is the dongle physically connected (does the USB stack respond)? true/false
+  bool m_ipInit;          //< Has PPIPInterface object (m_ppp) been initialised? true/false
+  bool m_smsInit;         //< Has SMSInterface object (m_sms) been initialised? true/false
+  bool m_ussdInit;        //< Has USSDInterface object (m_ussd) been initialised? true/false
+  bool m_linkMonitorInit; //< Has LinkMonitor object (m_linkMonitor) been initialised? true/false
+  bool m_atOpen;          //< Is the interface to the ATCommandsInterface open? true/false
   
-  PinName m_powerGatingPin;
-  bool m_powerGatingOnWhenPinHigh;
+  PinName m_powerGatingPin;        //< Pin which toggles power gating
+  bool m_powerGatingOnWhenPinHigh; //< Semantics of power gating (whether high or low toggles power gating)
 };
 
 

--- a/at/ATCommandsInterface.h	Thu Sep 20 08:04:43 2012 +0000
+++ b/at/ATCommandsInterface.h	Fri Sep 21 11:10:32 2012 +0000
@@ -113,7 +113,8 @@
   void process(); //Processing thread
 
   IOStream* m_pStream;
-  bool m_open;
+  
+  bool m_open; //< TRUE when the AT interface is open, and FALSE when it is not.
 
   const char* m_transactionCommand;
   const char* m_transactionData;