MultiTech / MTS-Cellular

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

Dependents:   mtsas mtsas mtsas mtsas

Cellular/EasyIP.h@33:3b6f3904dde0, 2014-07-16 (annotated)

Committer:
Vanger
Date:
Wed Jul 16 14:26:10 2014 +0000
Revision:
33:3b6f3904dde0
Parent:
31:529db15abda7
Child:
34:7d412c989964
Updating and formatting documentation for EasyIP.h and EasyIP.cpp.; Comment tweak for UIP.h

Who changed what in which revision?

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