MultiTech / MTS-Cellular

Cellular library for MTS Socket Modem Arduino Shield devices from Multi-Tech Systems

Dependents:   mtsas mtsas mtsas mtsas

Cellular/EasyIP.h@52:2cb58398a4f9, 2014-08-11 (annotated)

Committer:
Vanger
Date:
Mon Aug 11 16:03:19 2014 +0000
Revision:
52:2cb58398a4f9
Parent:
49:1fc51c53cebf
Child:
56:43205bd2752a
Removed parse response '>' from sendCommand() under Cellular.cpp, changed sendSMS() to verify sending SMS message under Cellular.cpp, changed disconnect() to have better flow under EasyIP.cpp, changed isConnected() to be simpler under EasyIP.cpp

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vanger 52:2cb58398a4f9 1 #ifndef EASYIP_H
Vanger 52:2cb58398a4f9 2 #define EASYIP_H
Mike Fiore 1:f155d94d6f3a 3
Vanger 26:2b769ed8de4f 4 #include <string>
Vanger 26:2b769ed8de4f 5 #include <vector>
Vanger 26:2b769ed8de4f 6
Vanger 26:2b769ed8de4f 7 #include "MTSBufferedIO.h"
Vanger 26:2b769ed8de4f 8 #include "Cellular.h"
Vanger 26:2b769ed8de4f 9
Vanger 26:2b769ed8de4f 10 namespace mts
Vanger 26:2b769ed8de4f 11 {
Vanger 49:1fc51c53cebf 12 /** This class implements the same interface used for UIP version radios on an Easy IP radio
Vanger 49:1fc51c53cebf 13 * using the Hayes AT command set.
Vanger 33:3b6f3904dde0 14 * (See the UIP class and documentation, "UIP.h")
Vanger 33:3b6f3904dde0 15 * This class supports four main types of cellular radio interactions including:
Vanger 33:3b6f3904dde0 16 * configuration and status AT-command processing, SMS processing, TCP Socket data connections,
Vanger 33:3b6f3904dde0 17 * and UDP data connections. It should be noted that the radio can not process commands or
Vanger 33:3b6f3904dde0 18 * SMS messages while having an open data connection at the same time. The concurrent
Vanger 33:3b6f3904dde0 19 * capability may be added in a future release. This class also inherits from IPStack
Vanger 33:3b6f3904dde0 20 * providing a common set of commands for communication devices that have an onboard
Vanger 33:3b6f3904dde0 21 * IP Stack. It is also integrated with the standard mbed Sockets package and can therefore
Vanger 33:3b6f3904dde0 22 * be used seamlessly with clients and services built on top of this interface already within
Vanger 33:3b6f3904dde0 23 * the mbed library.
Vanger 33:3b6f3904dde0 24 * The default baud rate for the cellular radio is 115200 bps.
Vanger 43:91c5e53f508f 25 *
Vanger 52:2cb58398a4f9 26 * Example code is found under Cellular.h
Vanger 33:3b6f3904dde0 27 */
Vanger 33:3b6f3904dde0 28 class EasyIP : public Cellular
Vanger 26:2b769ed8de4f 29 {
Vanger 26:2b769ed8de4f 30 public:
Vanger 33:3b6f3904dde0 31 /** This static function is used to create or get a reference to a
Vanger 26:2b769ed8de4f 32 * Cellular object. Cellular uses the singleton pattern, which means
Vanger 26:2b769ed8de4f 33 * that you can only have one existing at a time. The first time you
Vanger 26:2b769ed8de4f 34 * call getInstance this method creates a new uninitialized Cellular
Vanger 26:2b769ed8de4f 35 * object and returns it. All future calls to this method will return
Vanger 26:2b769ed8de4f 36 * a reference to the instance created during the first call. Note that
Vanger 26:2b769ed8de4f 37 * you must call init on the returned instance before mnaking any other
Vanger 26:2b769ed8de4f 38 * calls. If using this class's bindings to any of the Socket package
Vanger 26:2b769ed8de4f 39 * classes like TCPSocketConnection, you must call this method and the
Vanger 26:2b769ed8de4f 40 * init method on the returned object first, before even creating the
Vanger 26:2b769ed8de4f 41 * other objects.
Vanger 26:2b769ed8de4f 42 *
Vanger 26:2b769ed8de4f 43 * @returns a reference to the single Cellular obect that has been created.
Vanger 26:2b769ed8de4f 44 */
Vanger 26:2b769ed8de4f 45 EasyIP(Radio type);
Vanger 34:7d412c989964 46
Vanger 26:2b769ed8de4f 47 /** Destructs a Cellular object and frees all related resources.
Vanger 26:2b769ed8de4f 48 */
Vanger 26:2b769ed8de4f 49 ~EasyIP();
Vanger 34:7d412c989964 50
Vanger 33:3b6f3904dde0 51 /** Initializes the MTS IO buffer
Vanger 33:3b6f3904dde0 52 */
Vanger 26:2b769ed8de4f 53 virtual bool init(MTSBufferedIO* io);
Vanger 33:3b6f3904dde0 54
Vanger 33:3b6f3904dde0 55 /** PPP connect command.
Vanger 33:3b6f3904dde0 56 * Connects the radio to the cellular network.
Vanger 33:3b6f3904dde0 57 *
Vanger 33:3b6f3904dde0 58 * @returns true if PPP connection to the network succeeded,
Vanger 33:3b6f3904dde0 59 * false if the PPP connection failed.
Vanger 33:3b6f3904dde0 60 */
Vanger 26:2b769ed8de4f 61 virtual bool connect();
Vanger 33:3b6f3904dde0 62
Vanger 33:3b6f3904dde0 63 /** PPP disconnect command.
Vanger 33:3b6f3904dde0 64 * Disconnects from the PPP network, and will also close active socket
Vanger 33:3b6f3904dde0 65 * connection if open.
Vanger 33:3b6f3904dde0 66 */
Vanger 26:2b769ed8de4f 67 virtual void disconnect();
Vanger 33:3b6f3904dde0 68
Vanger 33:3b6f3904dde0 69 /** Checks if the radio is connected to the cell network.
Vanger 33:3b6f3904dde0 70 * Checks antenna signal, cell tower registration, and context activation
Vanger 33:3b6f3904dde0 71 * before finally pinging (4 pings, 32 bytes each) to confirm PPP connection
Vanger 33:3b6f3904dde0 72 * to network. Will return true if there is an open socket connection as well.
Vanger 33:3b6f3904dde0 73 *
Vanger 33:3b6f3904dde0 74 * @returns true if there is a PPP connection to the cell network, false
Vanger 33:3b6f3904dde0 75 * if there is no PPP connection to the cell network.
Vanger 33:3b6f3904dde0 76 */
Vanger 26:2b769ed8de4f 77 virtual bool isConnected();
Vanger 33:3b6f3904dde0 78
Vanger 33:3b6f3904dde0 79 /** Resets the radio/modem.
Vanger 33:3b6f3904dde0 80 * Disconnects all active PPP and socket connections to do so.
Vanger 33:3b6f3904dde0 81 */
Vanger 26:2b769ed8de4f 82 virtual void reset();
Vanger 26:2b769ed8de4f 83
Vanger 26:2b769ed8de4f 84 // TCP and UDP Socket related commands
Vanger 26:2b769ed8de4f 85 // For behavior of the following methods refer to IPStack.h documentation
Vanger 26:2b769ed8de4f 86 virtual bool bind(unsigned int port);
Vanger 26:2b769ed8de4f 87 virtual bool open(const std::string& address, unsigned int port, Mode mode);
Vanger 26:2b769ed8de4f 88 virtual bool isOpen();
Vanger 26:2b769ed8de4f 89 virtual bool close();
Vanger 31:529db15abda7 90 virtual int read(char* data, int max, int timeout = -1);
Vanger 26:2b769ed8de4f 91 virtual int write(const char* data, int length, int timeout = -1);
Vanger 26:2b769ed8de4f 92 virtual unsigned int readable();
Vanger 26:2b769ed8de4f 93 virtual unsigned int writeable();
Vanger 52:2cb58398a4f9 94
Vanger 52:2cb58398a4f9 95 /** Pings specified DNS or IP address
Vanger 52:2cb58398a4f9 96 * Google DNS server used as default ping address
Vanger 52:2cb58398a4f9 97 * @returns true if ping received alive response else false
Vanger 52:2cb58398a4f9 98 */
Vanger 52:2cb58398a4f9 99 virtual bool ping(const std::string& address = "8.8.8.8");
Vanger 26:2b769ed8de4f 100 virtual std::string getDeviceIP();
Vanger 33:3b6f3904dde0 101 virtual bool setDeviceIP(std::string address = "DHCP");
Vanger 26:2b769ed8de4f 102
Vanger 33:3b6f3904dde0 103 /** Sets the APN
Vanger 33:3b6f3904dde0 104 *
Vanger 33:3b6f3904dde0 105 * @param apn c-string of the APN to use
Vanger 33:3b6f3904dde0 106 *
Vanger 33:3b6f3904dde0 107 * @returns MTS_SUCCESS if the APN was set, or is not needed, else it
Vanger 33:3b6f3904dde0 108 * returns the result of the AT command sent to the radio to set the APN
Vanger 33:3b6f3904dde0 109 */
Vanger 26:2b769ed8de4f 110 virtual Code setApn(const std::string& apn);
Vanger 33:3b6f3904dde0 111
Vanger 26:2b769ed8de4f 112 /** A method for configuring command ehco capability on the radio. This command
Vanger 26:2b769ed8de4f 113 * sets whether sent characters are echoed back from the radio, in which case you
Vanger 26:2b769ed8de4f 114 * will receive back every command you send.
Vanger 26:2b769ed8de4f 115 *
Vanger 26:2b769ed8de4f 116 * @param state if true echo will be turned off, otherwise it will be turned on.
Vanger 26:2b769ed8de4f 117 * @returns the standard AT Code enumeration.
Vanger 26:2b769ed8de4f 118 */
Vanger 27:ec44d5a9544f 119 virtual Code echo(bool state);
Vanger 26:2b769ed8de4f 120
Vanger 26:2b769ed8de4f 121 /** This method can be used to trade socket functionality for performance.
Vanger 33:3b6f3904dde0 122 * Can disable checking socket closed messages from the data socket, and thus the socket
Vanger 33:3b6f3904dde0 123 * will only be visibly closed to the local side if the radio is explicitly checked, or
Vanger 33:3b6f3904dde0 124 * the socket is closed by the local side through the use of physical pin manipulation.
Vanger 33:3b6f3904dde0 125 *
Vanger 33:3b6f3904dde0 126 * Uses the Hayes escape sequence (1 second pause, "+++", 1 second pause) to exit the socket
Vanger 33:3b6f3904dde0 127 * connection to check if a received "NO CARRIER" string is from the radio indicating the socket
Vanger 33:3b6f3904dde0 128 * has been closed, or is merely part of the data stream. Should not occur very often, however, if
Vanger 33:3b6f3904dde0 129 * data carrying the string "NO CARRIER" is going to be transmitted frequently, then the socket should
Vanger 33:3b6f3904dde0 130 * be set closeable and physical-socket-closing-means be used instead to reduce the large amount of
Vanger 33:3b6f3904dde0 131 * overhead switching from checking the validity of the "NO CARRIER" message being and indication of
Vanger 33:3b6f3904dde0 132 * the socket connection being closed.
Vanger 26:2b769ed8de4f 133 *
Vanger 26:2b769ed8de4f 134 * @param enabled set to true if you want the socket closeable, otherwise false. The default
Vanger 26:2b769ed8de4f 135 * is true.
Vanger 26:2b769ed8de4f 136 * @returns the standard AT Code enumeration.
Vanger 26:2b769ed8de4f 137 */
Vanger 33:3b6f3904dde0 138 virtual Code setSocketCloseable(bool enabled = true);
Vanger 33:3b6f3904dde0 139
Vanger 33:3b6f3904dde0 140 private:
Vanger 33:3b6f3904dde0 141 /** Function that sends +++ to the radio to exit data mode
Vanger 33:3b6f3904dde0 142 * returns true if it successfully exits from online mode, else
Vanger 33:3b6f3904dde0 143 * it returns false. Used due to the fact that AT commands
Vanger 33:3b6f3904dde0 144 * cannot be sent while in data mode.
Vanger 33:3b6f3904dde0 145 *
Vanger 33:3b6f3904dde0 146 * @returns true if the radio dropped from data mode to commande mode
Vanger 33:3b6f3904dde0 147 * or is already in command mode (socket is still open in the background),
Vanger 33:3b6f3904dde0 148 * and false if the radio failed to switch to command mode.
Vanger 33:3b6f3904dde0 149 */
Vanger 33:3b6f3904dde0 150 virtual bool sendEscapeCommand();
Vanger 33:3b6f3904dde0 151
Vanger 33:3b6f3904dde0 152 /** Switches to command mode, queries the status of the socket connection,
Vanger 33:3b6f3904dde0 153 * and then returns back to the active socket connection (if still open)
Vanger 33:3b6f3904dde0 154 *
Vanger 33:3b6f3904dde0 155 * @returns true if a socket is currently open, otherwise it returns false
Vanger 33:3b6f3904dde0 156 */
Vanger 33:3b6f3904dde0 157 virtual bool socketCheck();
Vanger 26:2b769ed8de4f 158 };
Vanger 26:2b769ed8de4f 159
Vanger 26:2b769ed8de4f 160 }
Vanger 26:2b769ed8de4f 161
Vanger 52:2cb58398a4f9 162 #endif /* EASYIP_H */