Diff: Cellular/EasyIP.h

Revision:

33:3b6f3904dde0

Parent:

31:529db15abda7

Child:

34:7d412c989964

--- a/Cellular/EasyIP.h	Tue Jul 15 20:37:08 2014 +0000
+++ b/Cellular/EasyIP.h	Wed Jul 16 14:26:10 2014 +0000
@@ -9,33 +9,24 @@
 
 namespace mts
 {
-/** This is a class for communicating without a Multi-Tech Systems SocketModem iCell. Instead, 
-* it uses the hayes command set to implement the same commands and functions as the UIP class.
-* (See the UIP class and documentation, "UIP.h")
-* This class supports three main types of cellular radio interactions including:
-* configuration and status AT command processing, SMS processing, and TCP Socket
-* data connections. It should be noted that the radio can not process commands or
-* SMS messages while having an open data connection at the same time. The concurrent
-* capability may be added in a future release. This class also inherits from IPStack
-* providing a common set of commands for communication devices that have an onboard
-* IP Stack. It is also integrated with the standard mbed Sockets package and can therefore
-* be used seamlessly with clients and services built on top of this interface already within
-* the mbed library.
-* The default baud rate for the cellular radio is 115200 bps.
-*/
-class EasyIP : public Cellular     //Inherits from Cellular.
+    /** This is a class for communicating without a Multi-Tech Systems SocketModem iCell. Instead, 
+    * it uses the hayes command set to directly implement the same UIP interface to the radio.
+    * (See the UIP class and documentation, "UIP.h")
+    * This class supports four main types of cellular radio interactions including:
+    * configuration and status AT-command processing, SMS processing, TCP Socket data connections,
+    * and UDP data connections. It should be noted that the radio can not process commands or
+    * SMS messages while having an open data connection at the same time. The concurrent
+    * capability may be added in a future release. This class also inherits from IPStack
+    * providing a common set of commands for communication devices that have an onboard
+    * IP Stack. It is also integrated with the standard mbed Sockets package and can therefore
+    * be used seamlessly with clients and services built on top of this interface already within
+    * the mbed library.
+    * The default baud rate for the cellular radio is 115200 bps.
+    */
+class EasyIP : public Cellular
 {
-private:
-    /*Function that sends +++ to radio to exit data mode
-      returns true if successful exit from online mode, else false
-    */
-    virtual bool sendEscapeCommand(); 
-    /*Switches to command mode, queries socket connection status,
-      then returns true if there is an active socket connection, 
-      else it returns false.*/
-    virtual bool socketCheck();
 public:
-/** This static function is used to create or get a reference to a
+    /** This static function is used to create or get a reference to a
     * Cellular object. Cellular uses the singleton pattern, which means
     * that you can only have one existing at a time. The first time you
     * call getInstance this method creates a new uninitialized Cellular
@@ -53,13 +44,38 @@
     /** Destructs a Cellular object and frees all related resources.
     */
     ~EasyIP();
-
+    /** Initializes the MTS IO buffer
+     * INCOMPLETE
+    */
     virtual bool init(MTSBufferedIO* io);
-
-    // Wifi connection based commands derived from CommInterface.h
+    
+    /** PPP connect command.
+    * Connects the radio to the cellular network.
+    *
+    * @returns true if PPP connection to the network succeeded,
+    * false if the PPP connection failed.
+    */
     virtual bool connect();
+    
+    /** PPP disconnect command.
+    * Disconnects from the PPP network, and will also close active socket
+    * connection if open. 
+    */
     virtual void disconnect();
+    
+    /** Checks if the radio is connected to the cell network.
+    * Checks antenna signal, cell tower registration, and context activation
+    * before finally pinging (4 pings, 32 bytes each) to confirm PPP connection
+    * to network. Will return true if there is an open socket connection as well.
+    *
+    * @returns true if there is a PPP connection to the cell network, false
+    * if there is no PPP connection to the cell network.
+    */
     virtual bool isConnected();
+    
+    /** Resets the radio/modem.
+    * Disconnects all active PPP and socket connections to do so.
+    */
     virtual void reset();
 
     // TCP and UDP Socket related commands
@@ -72,12 +88,19 @@
     virtual int write(const char* data, int length, int timeout = -1);
     virtual unsigned int readable();
     virtual unsigned int writeable();
-    virtual bool ping(const std::string& address = "8.8.8.8"); //Google DNS server
+    virtual bool ping(const std::string& address = "8.8.8.8"); //Google DNS server used as default ping address
     virtual std::string getDeviceIP();
-    virtual bool setDeviceIP(std::string address = "DHCP");//Runs DHCP to configure the IP
+    virtual bool setDeviceIP(std::string address = "DHCP");
     
-    //Sets the APN, also sets mode to IP, might need to change
+    /** Sets the APN
+    * 
+    * @param apn c-string of the APN to use
+    *
+    * @returns MTS_SUCCESS if the APN was set, or is not needed, else it
+    * returns the result of the AT command sent to the radio to set the APN
+    */
     virtual Code setApn(const std::string& apn);
+    
     /** A method for configuring command ehco capability on the radio. This command
     * sets whether sent characters are echoed back from the radio, in which case you
     * will receive back every command you send.
@@ -88,18 +111,44 @@
     virtual Code echo(bool state);
 
     /** This method can be used to trade socket functionality for performance.
-    * In order to enable a socket connection to be closed by the client side programtically,
-    * this class must process all read and write data on the socket to guard the special
-    * escape character used to close an open socket connection. It is recommened that you
-    * use the default of true unless the overhead of these operations is too significant.
+    * Can disable checking socket closed messages from the data socket, and thus the socket
+    * will only be visibly closed to the local side if the radio is explicitly checked, or
+    * the socket is closed by the local side through the use of physical pin manipulation.
+    *
+    * Uses the Hayes escape sequence (1 second pause, "+++", 1 second pause) to exit the socket
+    * connection to check if a received "NO CARRIER" string is from the radio indicating the socket
+    * has been closed, or is merely part of the data stream. Should not occur very often, however, if 
+    * data carrying the string "NO CARRIER" is going to be transmitted frequently, then the socket should
+    * be set closeable and physical-socket-closing-means be used instead to reduce the large amount of
+    * overhead switching from checking the validity of the "NO CARRIER" message being and indication of
+    * the socket connection being closed.
     *
     * @param enabled set to true if you want the socket closeable, otherwise false. The default
     * is true.
     * @returns the standard AT Code enumeration.
     */
-    virtual Code setSocketCloseable(bool enabled = true);  //ETX closes socket (ETX and DLE in payload are escaped with DLE)
+    virtual Code setSocketCloseable(bool enabled = true);
+    
+private:
+    /** Function that sends +++ to the radio to exit data mode
+    * returns true if it successfully exits from online mode, else
+    * it returns false. Used due to the fact that AT commands
+    * cannot be sent while in data mode.
+    *
+    * @returns true if the radio dropped from data mode to commande mode
+    * or is already in command mode (socket is still open in the background),
+    * and false if the radio failed to switch to command mode.
+    */
+    virtual bool sendEscapeCommand(); 
+    
+    /** Switches to command mode, queries the status of the socket connection,
+    * and then returns back to the active socket connection (if still open)
+    *
+    * @returns true if a socket is currently open, otherwise it returns false
+    */
+    virtual bool socketCheck();
 };
 
 }
 
-#endif
+#endif /* SMC_H */