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@152:9a2c7ed27744, 2014-09-02 (annotated)

Committer:
mfiore
Date:
Tue Sep 02 18:38:55 2014 +0000
Revision:
152:9a2c7ed27744
Parent:
143:c7d8fe37981b 
Wifi: fix compatibility break with old shields by checking for both old and new style responses to "show connection" command

Who changed what in which revision?

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