Multi-Hackers / SocketModem

A library for talking to Multi-Tech's Cellular SocketModem Devices.

Dependents:   M2X_dev axeda_wrapper_dev MTS_M2x_Example1 MTS_Cellular_Connect_Example ... more

cellular/Cellular.h@90:b5abba87d9e2, 2013-12-27 (annotated)

Committer:
jengbrecht
Date:
Fri Dec 27 20:34:42 2013 +0000
Revision:
90:b5abba87d9e2
Parent:
89:9e5da66e4f1e
Child:
103:da58d27c15d7
Revamped and tested 3rd example program, still need to look at what echo server to point this to...

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jengbrecht 0:563b70517320 1 #ifndef CELLULAR_H
jengbrecht 0:563b70517320 2 #define CELLULAR_H
jengbrecht 0:563b70517320 3
sgodinez 11:134435d8a2d5 4 #include "IPStack.h"
sgodinez 11:134435d8a2d5 5 #include "MTSBufferedIO.h"
jengbrecht 0:563b70517320 6 #include "mbed.h"
jengbrecht 0:563b70517320 7 #include <string>
sgodinez 4:6561c9128c6f 8 #include <vector>
jengbrecht 0:563b70517320 9
jengbrecht 56:e5e5351f14b3 10 namespace mts
jengbrecht 56:e5e5351f14b3 11 {
mfiore 39:6e94520a3217 12
jengbrecht 36:bb6b293c7495 13 /** This is a class for communicating with a Multi-Tech Systems SocketModem iCell. The
jengbrecht 27:8e6188cbcfd4 14 * SocketModem iCell is a family of carrier certified embedded cellular radio modules with
jengbrecht 27:8e6188cbcfd4 15 * a common hardware footprint and AT command set for built in IP-stack functionality.
jengbrecht 36:bb6b293c7495 16 * This class supports three main types of cellular radio interactions including:
jengbrecht 27:8e6188cbcfd4 17 * configuration and status AT command processing, SMS processing, and TCP/UDP Socket
jengbrecht 36:bb6b293c7495 18 * data connections. It should be noted that the radio can not process commands or
jengbrecht 27:8e6188cbcfd4 19 * SMS messages while having an open data connection at the same time. The concurrent
jengbrecht 27:8e6188cbcfd4 20 * capability may be added in a future release. This class also inherits from IPStack
jengbrecht 27:8e6188cbcfd4 21 * providing a common set of commands for communication devices that have an onboard
jengbrecht 27:8e6188cbcfd4 22 * IP Stack. It is also integrated with the standard Mbed Sockets package and can therefore
jengbrecht 27:8e6188cbcfd4 23 * be used seamlessly with clients and services built on top of this interface already within
jengbrecht 56:e5e5351f14b3 24 * the mbed library.
jengbrecht 36:bb6b293c7495 25 *
jengbrecht 27:8e6188cbcfd4 26 * All of the following examples use the Pin Names for the Freedom KL46Z board coupled with
jengbrecht 36:bb6b293c7495 27 * the SocketModem Shield Arduino compatible board. Please chage Pin Names accordingly to
jengbrecht 27:8e6188cbcfd4 28 * match your hardware configuration. It also assumes the use of RTS/CTS hardware handshaking
jengbrecht 27:8e6188cbcfd4 29 * using GPIOs. To disable this you will need to change settings on the radio module and
jengbrecht 27:8e6188cbcfd4 30 * and use the MTSSerial class instead of MTSSerialFlowControl. The default baud rate for the
jengbrecht 27:8e6188cbcfd4 31 * cellular radio is 115200 bps.
jengbrecht 36:bb6b293c7495 32 *
jengbrecht 27:8e6188cbcfd4 33 * The following set of example code demonstrates how to send and receive configuration and
jengbrecht 62:83ccef1e94db 34 * status AT commands with the radio, create a data connection and test it:
jengbrecht 27:8e6188cbcfd4 35 * @code
jengbrecht 27:8e6188cbcfd4 36 * #include "mbed.h"
jengbrecht 27:8e6188cbcfd4 37 * #include "Cellular.h"
jengbrecht 27:8e6188cbcfd4 38 * #include "MTSSerialFlowControl.h"
jengbrecht 36:bb6b293c7495 39 *
jengbrecht 62:83ccef1e94db 40 * using namespace mts;
jengbrecht 82:5aa75004e553 41 *
jengbrecht 27:8e6188cbcfd4 42 * main() {
jengbrecht 27:8e6188cbcfd4 43 * //Wait for radio to boot up
jengbrecht 87:5db6c084adc7 44 * for (int i = 30; i >= 0; i = i - 5) {
jengbrecht 87:5db6c084adc7 45 * wait(5);
jengbrecht 87:5db6c084adc7 46 * printf("Waiting %d seconds...\n\r", i);
jengbrecht 87:5db6c084adc7 47 * }
jengbrecht 36:bb6b293c7495 48 *
jengbrecht 27:8e6188cbcfd4 49 * //Setup serial interface to radio
jengbrecht 27:8e6188cbcfd4 50 * MTSSerialFlowControl* serial = new MTSSerialFlowControl(PTD3, PTD2, PTA12, PTC8);
jengbrecht 27:8e6188cbcfd4 51 * serial->baud(115200);
jengbrecht 27:8e6188cbcfd4 52 *
jengbrecht 27:8e6188cbcfd4 53 * //Setup Cellular class
jengbrecht 56:e5e5351f14b3 54 * Cellular* cellular = Cellular::getInstance();
jengbrecht 56:e5e5351f14b3 55 * cellular->init(serial);
jengbrecht 36:bb6b293c7495 56 *
jengbrecht 62:83ccef1e94db 57 * //Run status and configuration commands
jengbrecht 87:5db6c084adc7 58 * printf("\n\r////Start Status and Configuration Commands////\n\r");
jengbrecht 87:5db6c084adc7 59 * printf("Command Test: %s\n\r", getCodeNames(cellular->test()).c_str());
jengbrecht 62:83ccef1e94db 60 * printf("Signal Strength: %d\n\r", cellular->getSignalStrength());
jengbrecht 62:83ccef1e94db 61 * printf("Registration State: %s\n\r", Cellular::getRegistrationNames(cellular->getRegistration()).c_str());
jengbrecht 87:5db6c084adc7 62 * printf("Send Basic Command (AT): %s\n\r", getCodeNames(cellular->sendBasicCommand("AT", 1000)).c_str());
jengbrecht 62:83ccef1e94db 63 * printf("Send Command (AT+CSQ): %s\n\r", cellular->sendCommand("AT+CSQ", 1000).c_str());
jengbrecht 82:5aa75004e553 64 *
jengbrecht 27:8e6188cbcfd4 65 * //Start Test
jengbrecht 87:5db6c084adc7 66 * printf("\n\r////Start Network Connectivity Test////\n\r");
jengbrecht 87:5db6c084adc7 67 * printf("Set APN: %s\n\r", getCodeNames(cellular->setApn("wap.cingular")).c_str()); //Use APN from service provider!!!
jengbrecht 36:bb6b293c7495 68 *
jengbrecht 27:8e6188cbcfd4 69 * //Setup a data connection
jengbrecht 87:5db6c084adc7 70 * printf("Attempting to Connect, this may take some time...\n\r");
jengbrecht 87:5db6c084adc7 71 * while (!cellular->connect()) {
jengbrecht 87:5db6c084adc7 72 * printf("Failed to connect... Trying again.\n\r");
jengbrecht 27:8e6188cbcfd4 73 * wait(1);
jengbrecht 27:8e6188cbcfd4 74 * }
jengbrecht 62:83ccef1e94db 75 * printf("Connected to the Network!\n\r");
jengbrecht 36:bb6b293c7495 76 *
jengbrecht 27:8e6188cbcfd4 77 * //Try pinging default server "8.8.8.8"
jengbrecht 27:8e6188cbcfd4 78 * printf("Ping Valid: %s\n\r", cellular->ping() ? "true" : "false");
jengbrecht 36:bb6b293c7495 79 *
jengbrecht 27:8e6188cbcfd4 80 * printf("End Program\n\r");
jengbrecht 27:8e6188cbcfd4 81 * }
jengbrecht 27:8e6188cbcfd4 82 * @endcode
jengbrecht 36:bb6b293c7495 83 *
jengbrecht 62:83ccef1e94db 84 * The following set of example code demonstrates how process SMS messages:
jengbrecht 62:83ccef1e94db 85 * @code
jengbrecht 62:83ccef1e94db 86 * #include "mbed.h"
jengbrecht 62:83ccef1e94db 87 * #include "Cellular.h"
jengbrecht 62:83ccef1e94db 88 * #include "MTSSerialFlowControl.h"
jengbrecht 62:83ccef1e94db 89 *
jengbrecht 62:83ccef1e94db 90 * using namespace mts;
jengbrecht 82:5aa75004e553 91 *
jengbrecht 62:83ccef1e94db 92 * main() {
jengbrecht 62:83ccef1e94db 93 * //Wait for radio to boot up
jengbrecht 89:9e5da66e4f1e 94 * for (int i = 30; i >= 0; i = i - 5) {
jengbrecht 89:9e5da66e4f1e 95 * wait(5);
jengbrecht 89:9e5da66e4f1e 96 * printf("Waiting %d seconds...\n\r", i);
jengbrecht 89:9e5da66e4f1e 97 * }
jengbrecht 62:83ccef1e94db 98 *
jengbrecht 62:83ccef1e94db 99 * //Setup serial interface to radio
jengbrecht 62:83ccef1e94db 100 * MTSSerialFlowControl* serial = new MTSSerialFlowControl(PTD3, PTD2, PTA12, PTC8);
jengbrecht 62:83ccef1e94db 101 * serial->baud(115200);
jengbrecht 62:83ccef1e94db 102 *
jengbrecht 62:83ccef1e94db 103 * //Setup Cellular class
jengbrecht 62:83ccef1e94db 104 * Cellular* cellular = Cellular::getInstance();
jengbrecht 62:83ccef1e94db 105 * cellular->init(serial);
jengbrecht 82:5aa75004e553 106 *
jengbrecht 62:83ccef1e94db 107 * //Start test
jengbrecht 89:9e5da66e4f1e 108 * printf("AT Test: %s\n\r", getCodeNames(cellular->test()).c_str());
jengbrecht 89:9e5da66e4f1e 109 *
jengbrecht 89:9e5da66e4f1e 110 * //Waiting for network registration
jengbrecht 89:9e5da66e4f1e 111 * printf("Checking Network Registration, this may take some time...\n\r");
jengbrecht 89:9e5da66e4f1e 112 * while (cellular->getRegistration() != Cellular::REGISTERED) {
jengbrecht 89:9e5da66e4f1e 113 * printf("Still waiting... Checking again.\n\r");
jengbrecht 89:9e5da66e4f1e 114 * wait(1);
jengbrecht 89:9e5da66e4f1e 115 * }
jengbrecht 89:9e5da66e4f1e 116 * printf("Connected to the Network!\n\r");
jengbrecht 82:5aa75004e553 117 *
jengbrecht 62:83ccef1e94db 118 * //Send SMS Message
jengbrecht 89:9e5da66e4f1e 119 * Code code;
jengbrecht 62:83ccef1e94db 120 * std::string sMsg("Hello from Multi-Tech MBED!");
jengbrecht 62:83ccef1e94db 121 * std::string sPhoneNum("16128675309"); //Put your phone number here or leave Jenny's...
jengbrecht 82:5aa75004e553 122 *
jengbrecht 62:83ccef1e94db 123 * printf("Sending message [%s] to [%s]\r\n", sMsg.c_str(), sPhoneNum.c_str());
jengbrecht 62:83ccef1e94db 124 * code = cellular->sendSMS(sPhoneNum, sMsg);
jengbrecht 82:5aa75004e553 125 *
jengbrecht 89:9e5da66e4f1e 126 * if(code != SUCCESS) {
jengbrecht 89:9e5da66e4f1e 127 * printf("Error during SMS send [%s]\r\n", getCodeNames(code).c_str());
jengbrecht 62:83ccef1e94db 128 * } else {
jengbrecht 62:83ccef1e94db 129 * printf("Success!\r\n");
jengbrecht 62:83ccef1e94db 130 * }
jengbrecht 82:5aa75004e553 131 *
jengbrecht 62:83ccef1e94db 132 * //Try and receive SMS messages
jengbrecht 62:83ccef1e94db 133 * //To determine your radio's phone number send yourself an SMS and check the received #
jengbrecht 62:83ccef1e94db 134 * printf("Checking Received Messages\r\n");
jengbrecht 62:83ccef1e94db 135 * std::vector<Cellular::Sms> vSms = cellular->getReceivedSms();
jengbrecht 62:83ccef1e94db 136 * printf("\r\n");
jengbrecht 62:83ccef1e94db 137 * for(unsigned int i = 0; i < vSms.size(); i++) {
jengbrecht 82:5aa75004e553 138 * printf("[%d][%s][%s][%s]\r\n", i, vSms[i].timestamp.c_str(),
jengbrecht 62:83ccef1e94db 139 * vSms[i].phoneNumber.c_str(), vSms[i].message.c_str());
jengbrecht 62:83ccef1e94db 140 * }
jengbrecht 62:83ccef1e94db 141 * printf("End Program\n\r");
jengbrecht 62:83ccef1e94db 142 * }
jengbrecht 62:83ccef1e94db 143 * @endcode
jengbrecht 62:83ccef1e94db 144 *
jengbrecht 27:8e6188cbcfd4 145 * The following set of example code demonstrates how to setup and use a TCP socket connection
jengbrecht 27:8e6188cbcfd4 146 * using the native commands from this class:
jengbrecht 27:8e6188cbcfd4 147 * @code
jengbrecht 27:8e6188cbcfd4 148 * #include "mbed.h"
jengbrecht 62:83ccef1e94db 149 * #include "Cellular.h"
jengbrecht 62:83ccef1e94db 150 * #include "MTSSerialFlowControl.h"
jengbrecht 62:83ccef1e94db 151 *
jengbrecht 62:83ccef1e94db 152 * using namespace mts;
jengbrecht 82:5aa75004e553 153 *
jengbrecht 62:83ccef1e94db 154 * main() {
jengbrecht 62:83ccef1e94db 155 * //Define connection parameters
jengbrecht 89:9e5da66e4f1e 156 * Code code;
jengbrecht 90:b5abba87d9e2 157 * const int TEST_PORT = 5798;
jengbrecht 90:b5abba87d9e2 158 * const std::string TEST_SERVER("204.26.122.96");
jengbrecht 62:83ccef1e94db 159 *
jengbrecht 62:83ccef1e94db 160 * //Wait for radio to boot up
jengbrecht 89:9e5da66e4f1e 161 * for (int i = 30; i >= 0; i = i - 5) {
jengbrecht 89:9e5da66e4f1e 162 * wait(5);
jengbrecht 89:9e5da66e4f1e 163 * printf("Waiting %d seconds...\n\r", i);
jengbrecht 89:9e5da66e4f1e 164 * }
jengbrecht 62:83ccef1e94db 165 *
jengbrecht 62:83ccef1e94db 166 * //Setup serial interface to radio
jengbrecht 62:83ccef1e94db 167 * MTSSerialFlowControl* serial = new MTSSerialFlowControl(PTD3, PTD2, PTA12, PTC8);
jengbrecht 62:83ccef1e94db 168 * serial->baud(115200);
jengbrecht 62:83ccef1e94db 169 *
jengbrecht 62:83ccef1e94db 170 * //Setup Cellular class
jengbrecht 62:83ccef1e94db 171 * Cellular* cellular = Cellular::getInstance();
jengbrecht 62:83ccef1e94db 172 * cellular->init(serial);
jengbrecht 82:5aa75004e553 173 *
jengbrecht 62:83ccef1e94db 174 * //Start test
jengbrecht 89:9e5da66e4f1e 175 * printf("AT Test: %s\n\r", getCodeNames(cellular->test()).c_str());
jengbrecht 82:5aa75004e553 176 *
jengbrecht 62:83ccef1e94db 177 * printf("Setting APN\r\n");
jengbrecht 89:9e5da66e4f1e 178 * code = cellular->setApn("wap.cingular"); // Use from your service provider!
jengbrecht 89:9e5da66e4f1e 179 * if(code == SUCCESS) {
jengbrecht 62:83ccef1e94db 180 * printf("Success!\r\n");
jengbrecht 62:83ccef1e94db 181 * } else {
jengbrecht 89:9e5da66e4f1e 182 * printf("Error during APN setup [%s]\r\n", getCodeNames(code).c_str());
jengbrecht 62:83ccef1e94db 183 * }
jengbrecht 62:83ccef1e94db 184 *
jengbrecht 62:83ccef1e94db 185 * //Setup a data connection
jengbrecht 89:9e5da66e4f1e 186 * printf("Attempting to Connect, this may take some time...\n\r");
jengbrecht 89:9e5da66e4f1e 187 * while (!cellular->connect()) {
jengbrecht 89:9e5da66e4f1e 188 * printf("Failed to connect... Trying again.\n\r");
jengbrecht 62:83ccef1e94db 189 * wait(1);
jengbrecht 62:83ccef1e94db 190 * }
jengbrecht 82:5aa75004e553 191 * printf("Connected to the Network!\n\r");
jengbrecht 82:5aa75004e553 192 *
jengbrecht 89:9e5da66e4f1e 193 * printf("Opening a TCP Socket...\r\n");
jengbrecht 62:83ccef1e94db 194 * if(cellular->open(TEST_SERVER, TEST_PORT, IPStack::TCP)) {
jengbrecht 82:5aa75004e553 195 * printf("Success!\r\n");
jengbrecht 62:83ccef1e94db 196 * } else {
jengbrecht 62:83ccef1e94db 197 * printf("Error during TCP socket open [%s:%d]\r\n", TEST_SERVER.c_str(), TEST_PORT);
jengbrecht 62:83ccef1e94db 198 * }
jengbrecht 82:5aa75004e553 199 *
jengbrecht 90:b5abba87d9e2 200 * char data[] = "My Test Echo Message";
jengbrecht 90:b5abba87d9e2 201 * int size = sizeof(data);
jengbrecht 90:b5abba87d9e2 202 * printf("WRITE: [%d] [%s]\r\n", size, data);
jengbrecht 90:b5abba87d9e2 203 * int bytesWritten = cellular->write(data, size, 10000);
jengbrecht 90:b5abba87d9e2 204 * if(bytesWritten == size) {
jengbrecht 62:83ccef1e94db 205 * printf("Successfully wrote message!\r\n");
jengbrecht 62:83ccef1e94db 206 * } else {
jengbrecht 82:5aa75004e553 207 * printf("Failed to write message!\r\n");
jengbrecht 62:83ccef1e94db 208 * }
jengbrecht 82:5aa75004e553 209 *
jengbrecht 62:83ccef1e94db 210 * printf("Waiting 5 seconds\r\n");
jengbrecht 62:83ccef1e94db 211 * wait(5);
jengbrecht 62:83ccef1e94db 212 *
jengbrecht 62:83ccef1e94db 213 * printf("Reading from socket for 10 seconds\r\n");
jengbrecht 90:b5abba87d9e2 214 * char response[size];
jengbrecht 90:b5abba87d9e2 215 * int bytesRead = cellular->read(response, size, 10000);
jengbrecht 90:b5abba87d9e2 216 * response[size - 1] = '\0';
jengbrecht 62:83ccef1e94db 217 * printf("READ: [%d] [%s]\r\n", bytesRead, response);
jengbrecht 82:5aa75004e553 218 *
jengbrecht 90:b5abba87d9e2 219 * //Check to see if echo was successful
jengbrecht 90:b5abba87d9e2 220 * if (strcmp(data, response) == 0) {
jengbrecht 90:b5abba87d9e2 221 * printf("Echo Successful!\n\r");
jengbrecht 90:b5abba87d9e2 222 * } else {
jengbrecht 90:b5abba87d9e2 223 * printf("Echo failed!\n\r");
jengbrecht 90:b5abba87d9e2 224 * }
jengbrecht 82:5aa75004e553 225 *
jengbrecht 90:b5abba87d9e2 226 * //Cleaning up the connection
jengbrecht 90:b5abba87d9e2 227 * printf("Closing socket: %s\r\n", cellular->close() ? "Success" : "Failure");
jengbrecht 90:b5abba87d9e2 228 * printf("Disconnecting...\r\n");
jengbrecht 62:83ccef1e94db 229 * cellular->disconnect();
jengbrecht 62:83ccef1e94db 230 * printf("End Program\n\r");
jengbrecht 62:83ccef1e94db 231 * }
jengbrecht 27:8e6188cbcfd4 232 * @endcode
jengbrecht 27:8e6188cbcfd4 233 */
jengbrecht 23:bc6f98a1eb22 234
mfiore 39:6e94520a3217 235 class Cellular : virtual mts::IPStack
jengbrecht 0:563b70517320 236 {
jengbrecht 0:563b70517320 237 public:
jengbrecht 0:563b70517320 238
jengbrecht 27:8e6188cbcfd4 239 /// An enumeration of radio registration states with a cell tower.
jengbrecht 0:563b70517320 240 enum Registration {
jengbrecht 0:563b70517320 241 NOT_REGISTERED, REGISTERED, SEARCHING, DENIED, UNKNOWN, ROAMING
jengbrecht 0:563b70517320 242 };
jengbrecht 0:563b70517320 243
jengbrecht 56:e5e5351f14b3 244 /** This structure contains the data for an SMS message.
jengbrecht 56:e5e5351f14b3 245 */
sgodinez 4:6561c9128c6f 246 struct Sms {
jengbrecht 56:e5e5351f14b3 247 /// Message Phone Number
jengbrecht 27:8e6188cbcfd4 248 std::string phoneNumber;
jengbrecht 56:e5e5351f14b3 249 /// Message Body
jengbrecht 27:8e6188cbcfd4 250 std::string message;
jengbrecht 56:e5e5351f14b3 251 /// Message Timestamp
jengbrecht 27:8e6188cbcfd4 252 std::string timestamp;
sgodinez 4:6561c9128c6f 253 };
jengbrecht 27:8e6188cbcfd4 254
jengbrecht 27:8e6188cbcfd4 255 /** Destructs a Cellular object and frees all related resources.
jengbrecht 27:8e6188cbcfd4 256 */
jengbrecht 0:563b70517320 257 ~Cellular();
jengbrecht 27:8e6188cbcfd4 258
jengbrecht 56:e5e5351f14b3 259 /** This static function is used to create or get a reference to a
jengbrecht 56:e5e5351f14b3 260 * Cellular object. Cellular uses the singleton pattern, which means
jengbrecht 56:e5e5351f14b3 261 * that you can only have one existing at a time. The first time you
jengbrecht 56:e5e5351f14b3 262 * call getInstance this method creates a new uninitialized Cellular
jengbrecht 56:e5e5351f14b3 263 * object and returns it. All future calls to this method will return
jengbrecht 56:e5e5351f14b3 264 * a reference to the instance created during the first call. Note that
jengbrecht 56:e5e5351f14b3 265 * you must call init on the returned instance before mnaking any other
jengbrecht 56:e5e5351f14b3 266 * calls. If using this class'e bindings to any of the Socket package
jengbrecht 56:e5e5351f14b3 267 * classes like TCPSocketConnection, you must call this method and the
jengbrecht 56:e5e5351f14b3 268 * init method on the returned object first, before even creating the
jengbrecht 56:e5e5351f14b3 269 * other objects.
jengbrecht 56:e5e5351f14b3 270 *
jengbrecht 56:e5e5351f14b3 271 * @returns a reference to the single Cellular obect that has been created.
jengbrecht 56:e5e5351f14b3 272 */
sgodinez 19:38794784e009 273 static Cellular* getInstance();
jengbrecht 82:5aa75004e553 274
jengbrecht 56:e5e5351f14b3 275 /** This method initializes the object with the underlying radio
jengbrecht 56:e5e5351f14b3 276 * interface to use. Note that this function MUST be called before
jengbrecht 56:e5e5351f14b3 277 * any other calls will function correctly on an Cellular object. Also
jengbrecht 56:e5e5351f14b3 278 * note that MTSBufferedIO is abstract, so you must use one of
jengbrecht 82:5aa75004e553 279 * its inherited classes like MTSSerial or MTSSerialFlowControl.
jengbrecht 56:e5e5351f14b3 280 *
jengbrecht 56:e5e5351f14b3 281 * @param io the buffered io interface that is attached to the cellular
jengbrecht 56:e5e5351f14b3 282 * radio.
jengbrecht 82:5aa75004e553 283 * @param DCD this is the dcd signal from the radio. If attached the
jengbrecht 82:5aa75004e553 284 * the pin must be passed in here for this class to operate correctly.
jengbrecht 82:5aa75004e553 285 * The default is not connected.
jengbrecht 82:5aa75004e553 286 * @param DTR this is the dtr signal from the radio. If attached the
jengbrecht 82:5aa75004e553 287 * the pin must be passed in here for this class to operate correctly.
jengbrecht 82:5aa75004e553 288 * The default is not connected.
jengbrecht 56:e5e5351f14b3 289 * @returns true if the init was successful, otherwise false.
jengbrecht 56:e5e5351f14b3 290 */
jengbrecht 82:5aa75004e553 291 bool init(MTSBufferedIO* io, PinName DCD = NC, PinName DTR = NC);
jengbrecht 0:563b70517320 292
jengbrecht 36:bb6b293c7495 293 // Radio link related commands
jengbrecht 27:8e6188cbcfd4 294 /** This method establishes a data connection on the cellular radio.
jengbrecht 27:8e6188cbcfd4 295 * Note that before calling you must have an activated radio and if
jengbrecht 27:8e6188cbcfd4 296 * using a SIM card set the APN using the setApn method. The APN can
jengbrecht 27:8e6188cbcfd4 297 * be obtained from your cellular service provider.
jengbrecht 27:8e6188cbcfd4 298 *
jengbrecht 27:8e6188cbcfd4 299 * @returns true if the connection was successfully established, otherwise
jengbrecht 27:8e6188cbcfd4 300 * false on an error.
jengbrecht 27:8e6188cbcfd4 301 */
jengbrecht 27:8e6188cbcfd4 302 virtual bool connect();
jengbrecht 27:8e6188cbcfd4 303
jengbrecht 27:8e6188cbcfd4 304 /** This method is used to stop a previously established cellular data connection.
jengbrecht 27:8e6188cbcfd4 305 */
sgodinez 11:134435d8a2d5 306 virtual void disconnect();
jengbrecht 27:8e6188cbcfd4 307
jengbrecht 27:8e6188cbcfd4 308 /** This method is used to check if the radio currently has a data connection
jengbrecht 27:8e6188cbcfd4 309 * established.
jengbrecht 27:8e6188cbcfd4 310 *
jengbrecht 27:8e6188cbcfd4 311 * @returns true if a data connection exists, otherwise false.
jengbrecht 27:8e6188cbcfd4 312 */
sgodinez 11:134435d8a2d5 313 virtual bool isConnected();
jengbrecht 56:e5e5351f14b3 314
jengbrecht 36:bb6b293c7495 315 // TCP and UDP Socket related commands
jengbrecht 36:bb6b293c7495 316 // For behavior of the following methods refer to IPStack.h documentation
sgodinez 11:134435d8a2d5 317 virtual bool bind(unsigned int port);
sgodinez 11:134435d8a2d5 318 virtual bool open(const std::string& address, unsigned int port, Mode mode);
sgodinez 11:134435d8a2d5 319 virtual bool isOpen();
sgodinez 17:2d7c4ea7491b 320 virtual bool close();
sgodinez 11:134435d8a2d5 321 virtual int read(char* data, int max, int timeout = -1);
sgodinez 41:81d035fb0b6a 322 virtual int write(const char* data, int length, int timeout = -1);
sgodinez 11:134435d8a2d5 323 virtual unsigned int readable();
sgodinez 11:134435d8a2d5 324 virtual unsigned int writeable();
jengbrecht 27:8e6188cbcfd4 325
sgodinez 11:134435d8a2d5 326 //Other
mfiore 29:7408b1bdad37 327 /** A method to reset the Multi-Tech Socket Modem. This command brings down the
mfiore 29:7408b1bdad37 328 * PPP link if it is up. After this function is called, at least 30 seconds should
mfiore 29:7408b1bdad37 329 * be allowed for the cellular radio to come back up before any other Cellular
mfiore 29:7408b1bdad37 330 * functions are called.
mfiore 29:7408b1bdad37 331 */
mfiore 29:7408b1bdad37 332 /** this needs to be investigated. After we tell the radio to reset and wait 30 seconds,
mfiore 29:7408b1bdad37 333 * we can't seem to get it to respond to even a simple signal strength query.
mfiore 29:7408b1bdad37 334 */
jengbrecht 27:8e6188cbcfd4 335 virtual void reset();
sgodinez 11:134435d8a2d5 336
sgodinez 11:134435d8a2d5 337 //Cellular Radio Specific
jengbrecht 27:8e6188cbcfd4 338 /** A method for sending a generic AT command to the radio. Note that you cannot
jengbrecht 27:8e6188cbcfd4 339 * send commands and have a data connection at the same time.
jengbrecht 36:bb6b293c7495 340 *
jengbrecht 27:8e6188cbcfd4 341 * @param command the command to send to the radio without the escape character.
jengbrecht 27:8e6188cbcfd4 342 * @param timeoutMillis the time in millis to wait for a response before returning.
jengbrecht 27:8e6188cbcfd4 343 * @param esc escape character to add at the end of the command, defaults to
sgodinez 71:82205735732b 344 * carriage return (CR). Does not append any character if esc == 0.
jengbrecht 27:8e6188cbcfd4 345 * @returns all data received from the radio after the command as a string.
jengbrecht 27:8e6188cbcfd4 346 */
sgodinez 71:82205735732b 347 std::string sendCommand(const std::string& command, unsigned int timeoutMillis, char esc = CR);
jengbrecht 36:bb6b293c7495 348
jengbrecht 36:bb6b293c7495 349 /** A method for sending a basic AT command to the radio. A basic AT command is
jengbrecht 27:8e6188cbcfd4 350 * one that simply has a response of either OK or ERROR without any other information.
jengbrecht 27:8e6188cbcfd4 351 * Note that you cannot send commands and have a data connection at the same time.
jengbrecht 36:bb6b293c7495 352 *
jengbrecht 27:8e6188cbcfd4 353 * @param command the command to send to the radio without the escape character.
jengbrecht 27:8e6188cbcfd4 354 * @param timeoutMillis the time in millis to wait for a response before returning.
jengbrecht 27:8e6188cbcfd4 355 * @param esc escape character to add at the end of the command, defaults to
jengbrecht 27:8e6188cbcfd4 356 * carriage return (CR).
jengbrecht 27:8e6188cbcfd4 357 * @returns the standard AT Code enumeration.
jengbrecht 27:8e6188cbcfd4 358 */
sgodinez 71:82205735732b 359 Code sendBasicCommand(const std::string& command, unsigned int timeoutMillis, char esc = CR);
sgodinez 11:134435d8a2d5 360
jengbrecht 23:bc6f98a1eb22 361 /** A method for testing command access to the radio. This method sends the
jengbrecht 27:8e6188cbcfd4 362 * command "AT" to the radio, which is a standard radio test to see if you
jengbrecht 23:bc6f98a1eb22 363 * have command access to the radio.
jengbrecht 23:bc6f98a1eb22 364 *
jengbrecht 23:bc6f98a1eb22 365 * @returns the standard AT Code enumeration.
jengbrecht 23:bc6f98a1eb22 366 */
sgodinez 11:134435d8a2d5 367 Code test();
jengbrecht 27:8e6188cbcfd4 368
jengbrecht 23:bc6f98a1eb22 369 /** A method for configuring command ehco capability on the radio. This command
jengbrecht 23:bc6f98a1eb22 370 * sets whether sent characters are echoed back from the radio, in which case you
jengbrecht 23:bc6f98a1eb22 371 * will receive back every command you send.
jengbrecht 23:bc6f98a1eb22 372 *
jengbrecht 23:bc6f98a1eb22 373 * @param state if true echo will be turned off, otherwise it will be turned on.
jengbrecht 23:bc6f98a1eb22 374 * @returns the standard AT Code enumeration.
jengbrecht 23:bc6f98a1eb22 375 */
mfiore 29:7408b1bdad37 376 Code echo(bool state);
jengbrecht 36:bb6b293c7495 377
jengbrecht 23:bc6f98a1eb22 378 /** A method for getting the signal strength of the radio. This method allows you to
jengbrecht 23:bc6f98a1eb22 379 * get a value that maps to signal strength in dBm. Here 0-1 is Poor, 2-9 is Marginal,
jengbrecht 23:bc6f98a1eb22 380 * 10-14 is Ok, 15-19 is Good, and 20+ is Excellent. If you get a result of 99 the
jengbrecht 27:8e6188cbcfd4 381 * signal strength is not known or not detectable.
jengbrecht 23:bc6f98a1eb22 382 *
jengbrecht 23:bc6f98a1eb22 383 * @returns an integer representing the signal strength.
jengbrecht 23:bc6f98a1eb22 384 */
jengbrecht 0:563b70517320 385 int getSignalStrength();
jengbrecht 36:bb6b293c7495 386
jengbrecht 27:8e6188cbcfd4 387 /** This method is used to check the registration state of the radio with the cell tower.
jengbrecht 27:8e6188cbcfd4 388 * If not appropriatley registered with the tower you cannot make a cellular connection.
jengbrecht 27:8e6188cbcfd4 389 *
jengbrecht 27:8e6188cbcfd4 390 * @returns the registration state as an enumeration type.
jengbrecht 27:8e6188cbcfd4 391 */
sgodinez 5:93e889a5abc6 392 Registration getRegistration();
jengbrecht 27:8e6188cbcfd4 393
jengbrecht 27:8e6188cbcfd4 394 /** This method is used to set the radios APN if using a SIM card. Note that the APN
jengbrecht 27:8e6188cbcfd4 395 * must be set correctly before you can make a data connection. The APN for your SIM
jengbrecht 27:8e6188cbcfd4 396 * can be obtained by contacting your cellular service provider.
jengbrecht 27:8e6188cbcfd4 397 *
jengbrecht 27:8e6188cbcfd4 398 * @param the APN as a string.
jengbrecht 27:8e6188cbcfd4 399 * @returns the standard AT Code enumeration.
jengbrecht 27:8e6188cbcfd4 400 */
sgodinez 11:134435d8a2d5 401 Code setApn(const std::string& apn);
jengbrecht 27:8e6188cbcfd4 402
jengbrecht 27:8e6188cbcfd4 403 /** This method is used to set the DNS which enables the use of URLs instead
jengbrecht 27:8e6188cbcfd4 404 * of IP addresses when making a socket connection.
jengbrecht 27:8e6188cbcfd4 405 *
jengbrecht 27:8e6188cbcfd4 406 * @param the DNS server address as a string in form xxx.xxx.xxx.xxx.
jengbrecht 27:8e6188cbcfd4 407 * @returns the standard AT Code enumeration.
jengbrecht 27:8e6188cbcfd4 408 */
sgodinez 41:81d035fb0b6a 409 Code setDns(const std::string& primary, const std::string& secondary = "0.0.0.0");
jengbrecht 27:8e6188cbcfd4 410
jengbrecht 27:8e6188cbcfd4 411 /** This method is used test network connectivity by pinging a server.
jengbrecht 27:8e6188cbcfd4 412 *
jengbrecht 27:8e6188cbcfd4 413 * @param address the address of the server in format xxx.xxx.xxx.xxx.
jengbrecht 27:8e6188cbcfd4 414 * @returns true if the ping was successful, otherwise false.
jengbrecht 27:8e6188cbcfd4 415 */
jengbrecht 23:bc6f98a1eb22 416 bool ping(const std::string& address = "8.8.8.8");
jengbrecht 56:e5e5351f14b3 417
jengbrecht 56:e5e5351f14b3 418 /** This method can be used to trade socket functionality for performance.
jengbrecht 56:e5e5351f14b3 419 * In order to enable a socket connection to be closed by the client side programtically,
jengbrecht 56:e5e5351f14b3 420 * this class must process all read and write data on the socket to guard the special
jengbrecht 56:e5e5351f14b3 421 * escape character used to close an open socket connection. It is recommened that you
jengbrecht 56:e5e5351f14b3 422 * use the default of true unless the overhead of these operations is too significant.
jengbrecht 56:e5e5351f14b3 423 *
jengbrecht 56:e5e5351f14b3 424 * @param enabled set to true if you want the socket closeable, otherwise false. The default
jengbrecht 56:e5e5351f14b3 425 * is true.
jengbrecht 56:e5e5351f14b3 426 * @returns the standard AT Code enumeration.
jengbrecht 56:e5e5351f14b3 427 */
sgodinez 17:2d7c4ea7491b 428 Code setSocketCloseable(bool enabled = true); //ETX closes socket (ETX and DLE in payload are escaped with DLE)
jengbrecht 27:8e6188cbcfd4 429
jengbrecht 27:8e6188cbcfd4 430 /** This method is used to send an SMS message. Note that you cannot send an
jengbrecht 27:8e6188cbcfd4 431 * SMS message and have a data connection open at the same time.
jengbrecht 27:8e6188cbcfd4 432 *
jengbrecht 27:8e6188cbcfd4 433 * @param phoneNumber the phone number to send the message to as a string.
jengbrecht 27:8e6188cbcfd4 434 * @param message the text message to be sent.
jengbrecht 27:8e6188cbcfd4 435 * @returns the standard AT Code enumeration.
jengbrecht 27:8e6188cbcfd4 436 */
jengbrecht 27:8e6188cbcfd4 437 Code sendSMS(const std::string& phoneNumber, const std::string& message);
jengbrecht 36:bb6b293c7495 438
jengbrecht 27:8e6188cbcfd4 439 /** This method is used to send an SMS message. Note that you cannot send an
jengbrecht 27:8e6188cbcfd4 440 * SMS message and have a data connection open at the same time.
jengbrecht 27:8e6188cbcfd4 441 *
jengbrecht 27:8e6188cbcfd4 442 * @param sms an Sms struct that contains all SMS transaction information.
jengbrecht 27:8e6188cbcfd4 443 * @returns the standard AT Code enumeration.
jengbrecht 27:8e6188cbcfd4 444 */
sgodinez 4:6561c9128c6f 445 Code sendSMS(const Sms& sms);
jengbrecht 36:bb6b293c7495 446
jengbrecht 56:e5e5351f14b3 447 /** This method retrieves all of the SMS messages currently available for
jengbrecht 56:e5e5351f14b3 448 * this phone number.
jengbrecht 27:8e6188cbcfd4 449 *
jengbrecht 56:e5e5351f14b3 450 * @returns a vector of existing SMS messages each as an Sms struct.
jengbrecht 27:8e6188cbcfd4 451 */
sgodinez 4:6561c9128c6f 452 std::vector<Cellular::Sms> getReceivedSms();
jengbrecht 56:e5e5351f14b3 453
jengbrecht 56:e5e5351f14b3 454 /** This method can be used to remove/delete all received SMS messages
jengbrecht 56:e5e5351f14b3 455 * even if they have never been retrieved or read.
jengbrecht 56:e5e5351f14b3 456 *
jengbrecht 56:e5e5351f14b3 457 * @returns the standard AT Code enumeration.
jengbrecht 56:e5e5351f14b3 458 */
sgodinez 4:6561c9128c6f 459 Code deleteAllReceivedSms();
jengbrecht 56:e5e5351f14b3 460
jengbrecht 56:e5e5351f14b3 461 /** This method can be used to remove/delete all received SMS messages
jengbrecht 56:e5e5351f14b3 462 * that have been retrieved by the user through the getReceivedSms method.
jengbrecht 56:e5e5351f14b3 463 * Messages that have not been retrieved yet will be unaffected.
jengbrecht 56:e5e5351f14b3 464 *
jengbrecht 56:e5e5351f14b3 465 * @returns the standard AT Code enumeration.
jengbrecht 56:e5e5351f14b3 466 */
sgodinez 4:6561c9128c6f 467 Code deleteOnlyReceivedReadSms();
sgodinez 19:38794784e009 468
jengbrecht 56:e5e5351f14b3 469 /** A static method for getting a string representation for the Registration
jengbrecht 56:e5e5351f14b3 470 * enumeration.
jengbrecht 56:e5e5351f14b3 471 *
jengbrecht 56:e5e5351f14b3 472 * @param code a Registration enumeration.
jengbrecht 56:e5e5351f14b3 473 * @returns the enumeration name as a string.
jengbrecht 56:e5e5351f14b3 474 */
jengbrecht 56:e5e5351f14b3 475 static std::string getRegistrationNames(Registration registration);
jengbrecht 27:8e6188cbcfd4 476
jengbrecht 0:563b70517320 477 private:
jengbrecht 23:bc6f98a1eb22 478 static Cellular* instance; //Static pointer to the single Cellular object.
sgodinez 19:38794784e009 479
jengbrecht 23:bc6f98a1eb22 480 MTSBufferedIO* io; //IO interface obect that the radio is accessed through.
jengbrecht 23:bc6f98a1eb22 481 bool echoMode; //Specifies if the echo mode is currently enabled.
jengbrecht 27:8e6188cbcfd4 482
jengbrecht 23:bc6f98a1eb22 483 bool pppConnected; //Specifies if a PPP session is currently connected.
jengbrecht 23:bc6f98a1eb22 484 std::string apn; //A string that holds the APN for the radio.
jengbrecht 27:8e6188cbcfd4 485
jengbrecht 56:e5e5351f14b3 486 Mode mode; //The current socket Mode.
jengbrecht 23:bc6f98a1eb22 487 bool socketOpened; //Specifies if a Socket is presently opened.
jengbrecht 23:bc6f98a1eb22 488 bool socketCloseable; //Specifies is a Socket can be closed.
jengbrecht 27:8e6188cbcfd4 489 unsigned int local_port; //Holds the local port for socket connections.
jengbrecht 27:8e6188cbcfd4 490 std::string local_address; //Holds the local address for socket connections.
jengbrecht 27:8e6188cbcfd4 491 unsigned int host_port; //Holds the remote port for socket connections.
jengbrecht 27:8e6188cbcfd4 492 std::string host_address; //Holds the remote address for socket connections.
jengbrecht 56:e5e5351f14b3 493 DigitalIn* dcd; //Maps to the radios dcd signal
jengbrecht 56:e5e5351f14b3 494 DigitalOut* dtr; //Maps to the radios dtr signal
sgodinez 11:134435d8a2d5 495
jengbrecht 23:bc6f98a1eb22 496 Cellular(); //Private constructor, use the getInstance() method.
mfiore 29:7408b1bdad37 497 Cellular(MTSBufferedIO* io); //Private constructor, use the getInstance() method.
jengbrecht 0:563b70517320 498 };
jengbrecht 0:563b70517320 499
mfiore 39:6e94520a3217 500 }
mfiore 39:6e94520a3217 501
jengbrecht 0:563b70517320 502 #endif /* CELLULAR_H */