MultiTech / MTS-Cellular

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

Dependents:   mtsas mtsas mtsas mtsas

Cellular/Cellular.h@76:6eeffc10739d, 2015-06-25 (annotated)

Committer:
Mike Fiore
Date:
Thu Jun 25 08:27:35 2015 -0500
Revision:
76:6eeffc10739d
Parent:
69:93dace69ee98
Child:
77:82c0ec0f73ba
add EU and Verizon LTE support, git rev 34875cd9c59aa9191bc3d0af0032ebf2d3ee2c0b

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mfiore 0:830c436480e3 1 #ifndef CELLULAR_H
mfiore 0:830c436480e3 2 #define CELLULAR_H
mfiore 0:830c436480e3 3
Mike Fiore 1:f155d94d6f3a 4 #include <string>
Mike Fiore 1:f155d94d6f3a 5 #include <vector>
Mike Fiore 1:f155d94d6f3a 6
Mike Fiore 1:f155d94d6f3a 7 #include "IPStack.h"
Mike Fiore 1:f155d94d6f3a 8 #include "MTSBufferedIO.h"
Mike Fiore 2:10e72dce251d 9 #include "CellUtils.h"
Mike Fiore 1:f155d94d6f3a 10
Mike Fiore 1:f155d94d6f3a 11 namespace mts
Mike Fiore 1:f155d94d6f3a 12 {
Mike Fiore 1:f155d94d6f3a 13
Mike Fiore 1:f155d94d6f3a 14 /** This is a class for communicating with a Cellular radio device.
Mike Fiore 1:f155d94d6f3a 15 * This class supports three main types of cellular radio interactions including:
Mike Fiore 1:f155d94d6f3a 16 * configuration and status processing, SMS processing, and TCP/UDP Socket
Mike Fiore 1:f155d94d6f3a 17 * data connections. This class also inherits from IPStack providing a common set of commands
Mike Fiore 1:f155d94d6f3a 18 * for communication devices that support IP protocols. It is also integrated with the standard
Mike Fiore 1:f155d94d6f3a 19 * mbed Sockets package and can therefore be used seamlessly with clients and services built
Mike Fiore 1:f155d94d6f3a 20 * on top of this interface already within the mbed library.
Mike Fiore 1:f155d94d6f3a 21 *
Mike Fiore 1:f155d94d6f3a 22 * For all examples below please change Pin Names to match your hardware configuration.
Mike Fiore 1:f155d94d6f3a 23 * It also assumes the use of RTS/CTS hardware handshaking using GPIOs. To disable this
Mike Fiore 1:f155d94d6f3a 24 * you will need to change settings on the radio module and and use the MTSSerial class
Mike Fiore 1:f155d94d6f3a 25 * instead of MTSSerialFlowControl.
Mike Fiore 1:f155d94d6f3a 26 *
Mike Fiore 1:f155d94d6f3a 27 * The following set of example code demonstrates how to send and receive configuration and
Mike Fiore 1:f155d94d6f3a 28 * status AT commands with the radio, create a data connection and test it:
Mike Fiore 1:f155d94d6f3a 29 * @code
Mike Fiore 1:f155d94d6f3a 30 * #include "mbed.h"
Vanger 53:1aee5fe47adb 31 * #include "mtsas.h"
Mike Fiore 1:f155d94d6f3a 32 *
Vanger 53:1aee5fe47adb 33 * int main(){
Vanger 53:1aee5fe47adb 34 * //Modify to match your apn if you are using an HSPA radio with a SIM card
Vanger 53:1aee5fe47adb 35 * const char APN[] = "";
Vanger 53:1aee5fe47adb 36 *
Vanger 53:1aee5fe47adb 37 * //Sets the log level to INFO, higher log levels produce more log output.
Vanger 53:1aee5fe47adb 38 * //Possible levels: NONE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE
Vanger 53:1aee5fe47adb 39 * MTSLog::setLogLevel(MTSLog::INFO_LEVEL);
Vanger 53:1aee5fe47adb 40 *
Vanger 53:1aee5fe47adb 41 * // STMicro Nucelo F401RE
Vanger 53:1aee5fe47adb 42 * // The supported jumper configurations of the MTSAS do not line up with
Vanger 53:1aee5fe47adb 43 * // the pin mapping of the Nucleo F401RE. Therefore, the MTSAS serial TX
Vanger 53:1aee5fe47adb 44 * // pin (JP8 Pin 2) must be manually jumped to Serial1 RX (Shield pin D2)
Vanger 53:1aee5fe47adb 45 * // and the MTSAS serial RX pin (JP9 Pin 2) pin must be manually jumped to
Vanger 53:1aee5fe47adb 46 * // Serial1 TX (Shield pin D8).
Vanger 53:1aee5fe47adb 47 * // Uncomment the following line to use the STMicro Nuceleo F401RE
Vanger 53:1aee5fe47adb 48 * //
Vanger 53:1aee5fe47adb 49 * MTSSerialFlowControl* io = new MTSSerialFlowControl(D8, D2, D3, D6);
Vanger 53:1aee5fe47adb 50 *
Vanger 53:1aee5fe47adb 51 * // Freescale KL46Z
Vanger 53:1aee5fe47adb 52 * // To configure the pins for the Freescale KL46Z board, use configuration B
Vanger 53:1aee5fe47adb 53 * // Uncomment the following line to use the Freescale KL46Z board
Vanger 53:1aee5fe47adb 54 * //
Vanger 53:1aee5fe47adb 55 * //MTSSerialFlowControl* io = new MTSSerialFlowControl(D2, D9, D3, D6);
Vanger 53:1aee5fe47adb 56 *
Vanger 53:1aee5fe47adb 57 * // Freescale K64F
Vanger 53:1aee5fe47adb 58 * // To configure the pins for the Freescale KL46Z board, use configuration A
Vanger 53:1aee5fe47adb 59 * // Uncomment the following line to use the Freescale KL46F board
Vanger 53:1aee5fe47adb 60 * //
Vanger 53:1aee5fe47adb 61 * //MTSSerialFlowControl* io = new MTSSerialFlowControl(D1, D0, D3, D6);
Vanger 53:1aee5fe47adb 62 *
Vanger 53:1aee5fe47adb 63 * //Sets the baud rate for communicating with the radio
Vanger 53:1aee5fe47adb 64 * io->baud(115200);
Vanger 53:1aee5fe47adb 65 *
Vanger 53:1aee5fe47adb 66 * //Create radio object
Vanger 53:1aee5fe47adb 67 * Cellular* radio = CellularFactory::create(io);
Vanger 53:1aee5fe47adb 68 * radio->configureSignals(D4,D7,RESET);
Vanger 53:1aee5fe47adb 69 * Transport::setTransport(radio);
Vanger 53:1aee5fe47adb 70 *
Vanger 53:1aee5fe47adb 71 * if (! radio) {
Vanger 53:1aee5fe47adb 72 * logFatal("Failed to initialize radio");
Vanger 53:1aee5fe47adb 73 * return 1;
Vanger 53:1aee5fe47adb 74 * }
Vanger 53:1aee5fe47adb 75 *
Vanger 53:1aee5fe47adb 76 * //Set radio APN
Vanger 53:1aee5fe47adb 77 * for (int i = 0; i < 10; i++) {
Vanger 53:1aee5fe47adb 78 * if (i >= 10) {
Vanger 53:1aee5fe47adb 79 * logError("Failed to set APN to %s", APN);
Vanger 53:1aee5fe47adb 80 * }
Vanger 53:1aee5fe47adb 81 * if (radio->setApn(APN) == MTS_SUCCESS) {
Vanger 53:1aee5fe47adb 82 * logInfo("Successfully set APN to %s", APN);
Vanger 53:1aee5fe47adb 83 * break;
Vanger 53:1aee5fe47adb 84 * } else {
Vanger 53:1aee5fe47adb 85 * wait(1);
Vanger 53:1aee5fe47adb 86 * }
Vanger 53:1aee5fe47adb 87 * }
Vanger 53:1aee5fe47adb 88 *
Vanger 53:1aee5fe47adb 89 * //Establish PPP link
Vanger 53:1aee5fe47adb 90 * for (int i = 0; i < 10; i++) {
Vanger 53:1aee5fe47adb 91 * if (i >= 10) {
Vanger 53:1aee5fe47adb 92 * logError("Failed to establish PPP link");
Vanger 53:1aee5fe47adb 93 * }
Vanger 53:1aee5fe47adb 94 * if (radio->connect() == true) {
Vanger 53:1aee5fe47adb 95 * logInfo("Successfully established PPP link");
Vanger 53:1aee5fe47adb 96 * break;
Vanger 53:1aee5fe47adb 97 * } else {
Vanger 53:1aee5fe47adb 98 * wait(1);
Vanger 53:1aee5fe47adb 99 * }
Vanger 53:1aee5fe47adb 100 * }
Vanger 53:1aee5fe47adb 101 *
Vanger 53:1aee5fe47adb 102 * //Ping google.com
Vanger 53:1aee5fe47adb 103 * for (int i = 0; i < 10; i++) {
Vanger 53:1aee5fe47adb 104 * if (i >= 10) {
Vanger 53:1aee5fe47adb 105 * logError("Failed to ping www.google.com");
Vanger 53:1aee5fe47adb 106 * }
Vanger 53:1aee5fe47adb 107 * if (radio->ping("www.google.com") == true) {
Vanger 53:1aee5fe47adb 108 * logInfo("Successfully pinged www.google.com");
Vanger 53:1aee5fe47adb 109 * break;
Vanger 53:1aee5fe47adb 110 * } else {
Vanger 53:1aee5fe47adb 111 * wait(1);
Vanger 53:1aee5fe47adb 112 * }
Vanger 53:1aee5fe47adb 113 * }
Vanger 53:1aee5fe47adb 114 *
Vanger 53:1aee5fe47adb 115 * //Disconnect ppp link
Vanger 53:1aee5fe47adb 116 * radio->disconnect();
Vanger 53:1aee5fe47adb 117 *
Vanger 53:1aee5fe47adb 118 * logInfo("End of example code");
Vanger 53:1aee5fe47adb 119 * return 0;
Vanger 53:1aee5fe47adb 120 * }
Mike Fiore 1:f155d94d6f3a 121 *
Mike Fiore 1:f155d94d6f3a 122 * @endcode
Mike Fiore 1:f155d94d6f3a 123 *
Vanger 53:1aee5fe47adb 124 * The following set of example code demonstrates how to process SMS messages:
Mike Fiore 1:f155d94d6f3a 125 * @code
Mike Fiore 1:f155d94d6f3a 126 * #include "mbed.h"
Vanger 53:1aee5fe47adb 127 * #include "mtsas.h"
Mike Fiore 1:f155d94d6f3a 128 *
Vanger 53:1aee5fe47adb 129 * int main(){
Vanger 53:1aee5fe47adb 130 *
Vanger 53:1aee5fe47adb 131 * //Sets the log level to INFO, higher log levels produce more log output.
Vanger 53:1aee5fe47adb 132 * //Possible levels: NONE, FATAL, ERROR, WARNING, INFO, DEBUG, TRACE
Vanger 53:1aee5fe47adb 133 * MTSLog::setLogLevel(MTSLog::INFO_LEVEL);
Vanger 53:1aee5fe47adb 134 *
Vanger 53:1aee5fe47adb 135 * //Modify to match your apn if you are using an HSPA radio with a SIM card
Vanger 53:1aee5fe47adb 136 * const char APN[] = "";
Vanger 53:1aee5fe47adb 137 *
Vanger 53:1aee5fe47adb 138 * //Phone number to send to and receive from. Must be in the form "1xxxxxxxxxx"
Vanger 53:1aee5fe47adb 139 * string PHONE_NUMBER = "";
Vanger 53:1aee5fe47adb 140 *
Vanger 53:1aee5fe47adb 141 * Cellular::Sms txtmsg;
Vanger 53:1aee5fe47adb 142 * txtmsg.phoneNumber = PHONE_NUMBER;
Vanger 53:1aee5fe47adb 143 * txtmsg.message = "Hello World! MTSAS is up and running!";
Vanger 53:1aee5fe47adb 144 *
Vanger 53:1aee5fe47adb 145 * // STMicro Nucelo F401RE
Vanger 53:1aee5fe47adb 146 * // The supported jumper configurations of the MTSAS do not line up with
Vanger 53:1aee5fe47adb 147 * // the pin mapping of the Nucleo F401RE. Therefore, the MTSAS serial TX
Vanger 53:1aee5fe47adb 148 * // pin (JP8 Pin 2) must be manually jumped to Serial1 RX (Shield pin D2)
Vanger 53:1aee5fe47adb 149 * // and the MTSAS serial RX pin (JP9 Pin 2) pin must be manually jumped to
Vanger 53:1aee5fe47adb 150 * // Serial1 TX (Shield pin D8).
Vanger 53:1aee5fe47adb 151 * // Uncomment the following line to use the STMicro Nuceleo F401RE
Vanger 53:1aee5fe47adb 152 * //
Vanger 53:1aee5fe47adb 153 * MTSSerialFlowControl* io = new MTSSerialFlowControl(D8, D2, D3, D6);
Vanger 53:1aee5fe47adb 154 *
Vanger 53:1aee5fe47adb 155 * // Freescale KL46Z
Vanger 53:1aee5fe47adb 156 * // To configure the pins for the Freescale KL46Z board, use configuration B
Vanger 53:1aee5fe47adb 157 * // Uncomment the following line to use the Freescale KL46Z board
Vanger 53:1aee5fe47adb 158 * //
Vanger 53:1aee5fe47adb 159 * //MTSSerialFlowControl* io = new MTSSerialFlowControl(D2, D9, D3, D6);
Vanger 53:1aee5fe47adb 160 *
Vanger 53:1aee5fe47adb 161 * // Freescale K64F
Vanger 53:1aee5fe47adb 162 * // To configure the pins for the Freescale KL46Z board, use configuration A
Vanger 53:1aee5fe47adb 163 * // Uncomment the following line to use the Freescale KL46F board
Vanger 53:1aee5fe47adb 164 * //
Vanger 53:1aee5fe47adb 165 * //MTSSerialFlowControl* io = new MTSSerialFlowControl(D1, D0, D3, D6);
Vanger 53:1aee5fe47adb 166 *
Vanger 53:1aee5fe47adb 167 * //Sets the baudrate for communicating with the radio
Vanger 53:1aee5fe47adb 168 * io->baud(115200);
Vanger 53:1aee5fe47adb 169 *
Vanger 53:1aee5fe47adb 170 * //Creates a radio object
Vanger 53:1aee5fe47adb 171 * Cellular* radio = CellularFactory::create(io);
Vanger 53:1aee5fe47adb 172 * radio->configureSignals(D4,D7,RESET);
Vanger 53:1aee5fe47adb 173 * Transport::setTransport(radio);
Vanger 53:1aee5fe47adb 174 *
Vanger 53:1aee5fe47adb 175 * if (! radio) {
Vanger 53:1aee5fe47adb 176 * logFatal("Failed to initialize radio");
Vanger 53:1aee5fe47adb 177 * return 1;
Vanger 53:1aee5fe47adb 178 * }
Vanger 53:1aee5fe47adb 179 *
Vanger 53:1aee5fe47adb 180 * //Set radio APN
Vanger 53:1aee5fe47adb 181 * for (int i = 0; i < 10; i++) {
Vanger 53:1aee5fe47adb 182 * if (i >= 10) {
Vanger 53:1aee5fe47adb 183 * logError("Failed to set APN\n");
Vanger 53:1aee5fe47adb 184 * }
Vanger 53:1aee5fe47adb 185 * if (radio->setApn(APN) == MTS_SUCCESS) {
Vanger 53:1aee5fe47adb 186 * logInfo("Successfully set APN\n");
Vanger 53:1aee5fe47adb 187 * break;
Vanger 53:1aee5fe47adb 188 * } else {
Vanger 53:1aee5fe47adb 189 * wait(1);
Vanger 53:1aee5fe47adb 190 * }
Vanger 53:1aee5fe47adb 191 * }
Vanger 53:1aee5fe47adb 192 *
Vanger 53:1aee5fe47adb 193 * //Delete any previously received SMS messages
Vanger 53:1aee5fe47adb 194 * for (int i = 0; i < 10; i++) {
Vanger 53:1aee5fe47adb 195 * if (i >= 10) {
Vanger 53:1aee5fe47adb 196 * logError("Failed to delete SMS messages\n");
Vanger 53:1aee5fe47adb 197 * }
Vanger 53:1aee5fe47adb 198 * if (radio->deleteAllReceivedSms() == MTS_SUCCESS) {
Vanger 53:1aee5fe47adb 199 * logInfo("Deleted all SMS messages\n");
Vanger 53:1aee5fe47adb 200 * break;
Vanger 53:1aee5fe47adb 201 * } else {
Vanger 53:1aee5fe47adb 202 * wait(1);
Vanger 53:1aee5fe47adb 203 * }
Vanger 53:1aee5fe47adb 204 * }
Vanger 53:1aee5fe47adb 205 *
Vanger 53:1aee5fe47adb 206 * // Send SMS message to phone
Vanger 53:1aee5fe47adb 207 * for (int i = 1; i < 10; i++) {
Vanger 53:1aee5fe47adb 208 * if(radio->sendSMS(txtmsg) == MTS_SUCCESS) {
Vanger 53:1aee5fe47adb 209 * logInfo("Sent SMS successfully:<%s>\n", txtmsg.message.c_str());
Vanger 53:1aee5fe47adb 210 * break;
Vanger 53:1aee5fe47adb 211 * } else {
Vanger 53:1aee5fe47adb 212 * logError("Failed to send SMS<%s>\n", txtmsg.message.c_str());
Vanger 53:1aee5fe47adb 213 * }
Vanger 53:1aee5fe47adb 214 * }
Vanger 53:1aee5fe47adb 215 *
Vanger 53:1aee5fe47adb 216 * //Checking for received SMS messages
Vanger 53:1aee5fe47adb 217 * while (true) {
Vanger 53:1aee5fe47adb 218 * logInfo("Checking for received messages");
Vanger 53:1aee5fe47adb 219 * vector<Cellular::Sms> recv = radio->getReceivedSms();
Vanger 53:1aee5fe47adb 220 * if(recv.size() > 0) {
Vanger 53:1aee5fe47adb 221 * int size = recv.size();
Vanger 53:1aee5fe47adb 222 * for (int i = 0; i < size; i++) {
Vanger 53:1aee5fe47adb 223 * logInfo("Message %d: [%s] [%s] [%s]", i, recv[i].phoneNumber.c_str(), recv[i].timestamp.c_str(), recv[i].message.c_str());
Vanger 53:1aee5fe47adb 224 * }
Vanger 53:1aee5fe47adb 225 * }
Vanger 53:1aee5fe47adb 226 *
Vanger 53:1aee5fe47adb 227 * if(radio->deleteOnlyReceivedReadSms() != MTS_SUCCESS) {
Vanger 53:1aee5fe47adb 228 * logError("Failed to delete received and read SMS messages");
Vanger 53:1aee5fe47adb 229 * }
Vanger 53:1aee5fe47adb 230 * wait(10);
Vanger 53:1aee5fe47adb 231 * }
Vanger 53:1aee5fe47adb 232 *
Vanger 53:1aee5fe47adb 233 * logDebug("End of example code\n");
Vanger 53:1aee5fe47adb 234 * return 0;
Mike Fiore 1:f155d94d6f3a 235 * }
Mike Fiore 1:f155d94d6f3a 236 * @endcode
Mike Fiore 1:f155d94d6f3a 237 */
Mike Fiore 1:f155d94d6f3a 238
Mike Fiore 1:f155d94d6f3a 239 class Cellular : public IPStack
Mike Fiore 1:f155d94d6f3a 240 {
Mike Fiore 1:f155d94d6f3a 241 public:
Mike Fiore 1:f155d94d6f3a 242 // Class ping paramter constants
Mike Fiore 1:f155d94d6f3a 243 static const unsigned int PINGDELAY = 3; //Time to wait on each ping for a response before timimg out (seconds)
Mike Fiore 1:f155d94d6f3a 244 static const unsigned int PINGNUM = 4; //Number of pings to try on ping command
Mike Fiore 1:f155d94d6f3a 245
Mike Fiore 1:f155d94d6f3a 246 /// Enumeration for different cellular radio types.
Mike Fiore 1:f155d94d6f3a 247 enum Radio {
Mike Fiore 76:6eeffc10739d 248 NA, MTSMC_H5, MTSMC_EV3, MTSMC_G3, MTSMC_C2, MTSMC_H5_IP, MTSMC_EV3_IP, MTSMC_C2_IP, MTSMC_LAT1, MTSMC_LVW2, MTSMC_LEU1
Mike Fiore 1:f155d94d6f3a 249 };
Mike Fiore 1:f155d94d6f3a 250
Mike Fiore 1:f155d94d6f3a 251 /// An enumeration of radio registration states with a cell tower.
Mike Fiore 1:f155d94d6f3a 252 enum Registration {
Mike Fiore 1:f155d94d6f3a 253 NOT_REGISTERED, REGISTERED, SEARCHING, DENIED, UNKNOWN, ROAMING
Mike Fiore 1:f155d94d6f3a 254 };
Mike Fiore 1:f155d94d6f3a 255
Mike Fiore 1:f155d94d6f3a 256 /** This structure contains the data for an SMS message.
Mike Fiore 1:f155d94d6f3a 257 */
Mike Fiore 1:f155d94d6f3a 258 struct Sms {
Mike Fiore 1:f155d94d6f3a 259 /// Message Phone Number
Mike Fiore 1:f155d94d6f3a 260 std::string phoneNumber;
Mike Fiore 1:f155d94d6f3a 261 /// Message Body
Mike Fiore 1:f155d94d6f3a 262 std::string message;
Mike Fiore 1:f155d94d6f3a 263 /// Message Timestamp
Mike Fiore 1:f155d94d6f3a 264 std::string timestamp;
Mike Fiore 1:f155d94d6f3a 265 };
Mike Fiore 1:f155d94d6f3a 266
Mike Fiore 1:f155d94d6f3a 267 /** This method initializes the object with the underlying radio
Mike Fiore 1:f155d94d6f3a 268 * interface to use. Note that this function MUST be called before
Mike Fiore 1:f155d94d6f3a 269 * any other calls will function correctly on a Cellular object. Also
Mike Fiore 1:f155d94d6f3a 270 * note that MTSBufferedIO is abstract, so you must use one of
Mike Fiore 3:04046eebaef5 271 * its inherited classes like MTSSerial, MTSSerialFlowControl or write a class
Mike Fiore 3:04046eebaef5 272 * similar to MTSSerialFlowControl which maps the MTSBufferedIO API
Mike Fiore 3:04046eebaef5 273 * to your favorite serial library.
Mike Fiore 1:f155d94d6f3a 274 *
Mike Fiore 3:04046eebaef5 275 * @param io the io interface that is attached to the cellular radio.
Mike Fiore 1:f155d94d6f3a 276 * The default is not connected.
Mike Fiore 1:f155d94d6f3a 277 * @returns true if the init was successful, otherwise false.
Mike Fiore 1:f155d94d6f3a 278 */
Mike Fiore 8:2d7259d244d1 279 virtual bool init(MTSBufferedIO* io);
Mike Fiore 9:1a03e3f3e7fe 280
Vanger 26:2b769ed8de4f 281 /** Sets up the physical connection pins
Vanger 52:2cb58398a4f9 282 * (DTR,DCD, and RESET)
Mike Fiore 9:1a03e3f3e7fe 283 */
Mike Fiore 9:1a03e3f3e7fe 284 bool configureSignals(unsigned int DCD = NC, unsigned int DTR = NC, unsigned int RESET = NC);
Mike Fiore 1:f155d94d6f3a 285
Mike Fiore 1:f155d94d6f3a 286 /** A method for testing command access to the radio. This method sends the
Mike Fiore 1:f155d94d6f3a 287 * command "AT" to the radio, which is a standard radio test to see if you
Mike Fiore 1:f155d94d6f3a 288 * have command access to the radio. The function returns when it receives
Mike Fiore 1:f155d94d6f3a 289 * the expected response from the radio.
Mike Fiore 1:f155d94d6f3a 290 *
Mike Fiore 1:f155d94d6f3a 291 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 292 */
Mike Fiore 1:f155d94d6f3a 293 virtual Code test();
Mike Fiore 1:f155d94d6f3a 294
Mike Fiore 1:f155d94d6f3a 295 /** A method for getting the signal strength of the radio. This method allows you to
Mike Fiore 1:f155d94d6f3a 296 * get a value that maps to signal strength in dBm. Here 0-1 is Poor, 2-9 is Marginal,
Mike Fiore 1:f155d94d6f3a 297 * 10-14 is Ok, 15-19 is Good, and 20+ is Excellent. If you get a result of 99 the
Mike Fiore 1:f155d94d6f3a 298 * signal strength is not known or not detectable.
Mike Fiore 1:f155d94d6f3a 299 *
Mike Fiore 1:f155d94d6f3a 300 * @returns an integer representing the signal strength.
Mike Fiore 1:f155d94d6f3a 301 */
Mike Fiore 1:f155d94d6f3a 302 virtual int getSignalStrength();
Mike Fiore 1:f155d94d6f3a 303
Mike Fiore 1:f155d94d6f3a 304 /** This method is used to check the registration state of the radio with the cell tower.
Mike Fiore 1:f155d94d6f3a 305 * If not appropriatley registered with the tower you cannot make a cellular connection.
Mike Fiore 1:f155d94d6f3a 306 *
Mike Fiore 1:f155d94d6f3a 307 * @returns the registration state as an enumeration type.
Mike Fiore 1:f155d94d6f3a 308 */
Mike Fiore 1:f155d94d6f3a 309 virtual Registration getRegistration();
Mike Fiore 1:f155d94d6f3a 310
Mike Fiore 1:f155d94d6f3a 311 /** This method is used to set the radios APN if using a SIM card. Note that the APN
Mike Fiore 1:f155d94d6f3a 312 * must be set correctly before you can make a data connection. The APN for your SIM
Mike Fiore 1:f155d94d6f3a 313 * can be obtained by contacting your cellular service provider.
Mike Fiore 1:f155d94d6f3a 314 *
Mike Fiore 1:f155d94d6f3a 315 * @param the APN as a string.
Mike Fiore 1:f155d94d6f3a 316 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 317 */
Vanger 52:2cb58398a4f9 318 virtual Code setApn(const std::string& apn) = 0;
Mike Fiore 1:f155d94d6f3a 319
Mike Fiore 1:f155d94d6f3a 320 /** This method is used to set the DNS which enables the use of URLs instead
Mike Fiore 1:f155d94d6f3a 321 * of IP addresses when making a socket connection.
Mike Fiore 1:f155d94d6f3a 322 *
Mike Fiore 1:f155d94d6f3a 323 * @param the DNS server address as a string in form xxx.xxx.xxx.xxx.
Mike Fiore 1:f155d94d6f3a 324 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 325 */
Mike Fiore 8:2d7259d244d1 326 virtual Code setDns(const std::string& primary, const std::string& secondary = "0.0.0.0");
Mike Fiore 1:f155d94d6f3a 327
Mike Fiore 1:f155d94d6f3a 328 /** This method is used to send an SMS message. Note that you cannot send an
Mike Fiore 1:f155d94d6f3a 329 * SMS message and have a data connection open at the same time.
Mike Fiore 1:f155d94d6f3a 330 *
Mike Fiore 1:f155d94d6f3a 331 * @param phoneNumber the phone number to send the message to as a string.
Mike Fiore 1:f155d94d6f3a 332 * @param message the text message to be sent.
Mike Fiore 1:f155d94d6f3a 333 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 334 */
Mike Fiore 7:0ee8e69a3e9c 335 virtual Code sendSMS(const std::string& phoneNumber, const std::string& message);
Mike Fiore 1:f155d94d6f3a 336
Mike Fiore 1:f155d94d6f3a 337 /** This method is used to send an SMS message. Note that you cannot send an
Mike Fiore 1:f155d94d6f3a 338 * SMS message and have a data connection open at the same time.
Mike Fiore 1:f155d94d6f3a 339 *
Mike Fiore 1:f155d94d6f3a 340 * @param sms an Sms struct that contains all SMS transaction information.
Mike Fiore 1:f155d94d6f3a 341 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 342 */
Mike Fiore 7:0ee8e69a3e9c 343 virtual Code sendSMS(const Sms& sms);
Mike Fiore 1:f155d94d6f3a 344
Mike Fiore 1:f155d94d6f3a 345 /** This method retrieves all of the SMS messages currently available for
Mike Fiore 1:f155d94d6f3a 346 * this phone number.
Mike Fiore 1:f155d94d6f3a 347 *
Mike Fiore 1:f155d94d6f3a 348 * @returns a vector of existing SMS messages each as an Sms struct.
Mike Fiore 1:f155d94d6f3a 349 */
Mike Fiore 7:0ee8e69a3e9c 350 virtual std::vector<Cellular::Sms> getReceivedSms();
Mike Fiore 1:f155d94d6f3a 351
Mike Fiore 1:f155d94d6f3a 352 /** This method can be used to remove/delete all received SMS messages
Mike Fiore 1:f155d94d6f3a 353 * even if they have never been retrieved or read.
Mike Fiore 1:f155d94d6f3a 354 *
Mike Fiore 1:f155d94d6f3a 355 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 356 */
Mike Fiore 7:0ee8e69a3e9c 357 virtual Code deleteAllReceivedSms();
Mike Fiore 1:f155d94d6f3a 358
Mike Fiore 1:f155d94d6f3a 359 /** This method can be used to remove/delete all received SMS messages
Mike Fiore 1:f155d94d6f3a 360 * that have been retrieved by the user through the getReceivedSms method.
Mike Fiore 1:f155d94d6f3a 361 * Messages that have not been retrieved yet will be unaffected.
Mike Fiore 1:f155d94d6f3a 362 *
Mike Fiore 1:f155d94d6f3a 363 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 364 */
Mike Fiore 7:0ee8e69a3e9c 365 virtual Code deleteOnlyReceivedReadSms();
Mike Fiore 1:f155d94d6f3a 366
Mike Fiore 1:f155d94d6f3a 367 //Cellular Radio Specific
Mike Fiore 1:f155d94d6f3a 368 /** A method for sending a generic AT command to the radio. Note that you cannot
Mike Fiore 1:f155d94d6f3a 369 * send commands and have a data connection at the same time.
Mike Fiore 1:f155d94d6f3a 370 *
Mike Fiore 1:f155d94d6f3a 371 * @param command the command to send to the radio without the escape character.
Mike Fiore 1:f155d94d6f3a 372 * @param timeoutMillis the time in millis to wait for a response before returning.
Mike Fiore 1:f155d94d6f3a 373 * @param esc escape character to add at the end of the command, defaults to
Mike Fiore 1:f155d94d6f3a 374 * carriage return (CR). Does not append any character if esc == 0.
Mike Fiore 1:f155d94d6f3a 375 * @returns all data received from the radio after the command as a string.
Mike Fiore 1:f155d94d6f3a 376 */
Mike Fiore 10:c188cc05aed5 377 virtual std::string sendCommand(const std::string& command, unsigned int timeoutMillis, char esc = CR);
Mike Fiore 1:f155d94d6f3a 378
Mike Fiore 1:f155d94d6f3a 379 /** A method for sending a basic AT command to the radio. A basic AT command is
Mike Fiore 1:f155d94d6f3a 380 * one that simply has a response of either OK or ERROR without any other information.
Mike Fiore 1:f155d94d6f3a 381 * Note that you cannot send commands and have a data connection at the same time.
Mike Fiore 1:f155d94d6f3a 382 *
Mike Fiore 1:f155d94d6f3a 383 * @param command the command to send to the radio without the escape character.
Mike Fiore 1:f155d94d6f3a 384 * @param timeoutMillis the time in millis to wait for a response before returning.
Mike Fiore 1:f155d94d6f3a 385 * @param esc escape character to add at the end of the command, defaults to
Mike Fiore 1:f155d94d6f3a 386 * carriage return (CR).
Mike Fiore 1:f155d94d6f3a 387 * @returns the standard Code enumeration.
Mike Fiore 1:f155d94d6f3a 388 */
Mike Fiore 10:c188cc05aed5 389 virtual Code sendBasicCommand(const std::string& command, unsigned int timeoutMillis, char esc = CR);
Mike Fiore 1:f155d94d6f3a 390
Mike Fiore 1:f155d94d6f3a 391 /** A static method for getting a string representation for the Registration
Mike Fiore 1:f155d94d6f3a 392 * enumeration.
Mike Fiore 1:f155d94d6f3a 393 *
Mike Fiore 1:f155d94d6f3a 394 * @param code a Registration enumeration.
Mike Fiore 1:f155d94d6f3a 395 * @returns the enumeration name as a string.
Mike Fiore 1:f155d94d6f3a 396 */
Mike Fiore 1:f155d94d6f3a 397 static std::string getRegistrationNames(Registration registration);
Mike Fiore 3:04046eebaef5 398
Mike Fiore 11:4e428f689069 399 /** A static method for getting a string representation for the Radio
Mike Fiore 11:4e428f689069 400 * enumeration.
Mike Fiore 11:4e428f689069 401 *
Mike Fiore 11:4e428f689069 402 * @param type a Radio enumeration.
Mike Fiore 11:4e428f689069 403 * @returns the enumeration name as a string.
Mike Fiore 11:4e428f689069 404 */
Mike Fiore 11:4e428f689069 405 static std::string getRadioNames(Radio radio);
Vanger 56:43205bd2752a 406
Vanger 27:ec44d5a9544f 407 /** A method for changing the echo commands from radio.
Vanger 27:ec44d5a9544f 408 * @param state Echo mode is off (an argument of 1 turns echos off, anything else turns echo on)
Vanger 27:ec44d5a9544f 409 * @returns standard Code enumeration
Vanger 27:ec44d5a9544f 410 */
Vanger 56:43205bd2752a 411 virtual Code echo(bool state);
Vanger 56:43205bd2752a 412
Vanger 56:43205bd2752a 413 /** This method can be used to trade socket functionality for performance.
Vanger 56:43205bd2752a 414 * Can disable checking socket closed messages from the data socket, and thus the socket
Vanger 56:43205bd2752a 415 * will only be visibly closed to the local side if the radio is explicitly checked, or
Vanger 56:43205bd2752a 416 * the socket is closed by the local side through the use of physical pin manipulation.
Vanger 56:43205bd2752a 417 *
Vanger 56:43205bd2752a 418 * Uses the Hayes escape sequence (1 second pause, "+++", 1 second pause) to exit the socket
Vanger 56:43205bd2752a 419 * connection to check if a received "NO CARRIER" string is from the radio indicating the socket
Vanger 56:43205bd2752a 420 * has been closed, or is merely part of the data stream. Should not occur very often, however, if
Vanger 56:43205bd2752a 421 * data carrying the string "NO CARRIER" is going to be transmitted frequently, then the socket should
Vanger 56:43205bd2752a 422 * be set closeable and physical-socket-closing-means be used instead to reduce the large amount of
Vanger 56:43205bd2752a 423 * overhead switching from checking the validity of the "NO CARRIER" message being and indication of
Vanger 56:43205bd2752a 424 * the socket connection being closed.
Vanger 56:43205bd2752a 425 *
Vanger 56:43205bd2752a 426 * @param enabled set to true if you want the socket closeable, otherwise false. The default
Vanger 56:43205bd2752a 427 * is true.
Vanger 56:43205bd2752a 428 * @returns the standard AT Code enumeration.
Vanger 56:43205bd2752a 429 */
Vanger 56:43205bd2752a 430 virtual Code setSocketCloseable(bool enabled);
Vanger 56:43205bd2752a 431
Vanger 56:43205bd2752a 432
Vanger 56:43205bd2752a 433 /** Binds the socket to a specific port if able
Vanger 56:43205bd2752a 434 * @param port integer to bind the socket to.
Vanger 56:43205bd2752a 435 *
Vanger 56:43205bd2752a 436 * @returns true if successfully bound port, false if bind failed.
Vanger 56:43205bd2752a 437 */
Vanger 56:43205bd2752a 438 virtual bool bind(unsigned int port);
Vanger 56:43205bd2752a 439
Vanger 56:43205bd2752a 440 /** Checks if a socket is open.
Vanger 56:43205bd2752a 441 * @returns true if socket is open, false if socket is closed
Vanger 56:43205bd2752a 442 */
Vanger 56:43205bd2752a 443 virtual bool isOpen();
Vanger 56:43205bd2752a 444
Vanger 56:43205bd2752a 445 /** Checks if there is data available from the socket.
Vanger 56:43205bd2752a 446 * @returns number of bytes of data available to read.
Vanger 56:43205bd2752a 447 */
Vanger 56:43205bd2752a 448 virtual unsigned int readable();
Vanger 56:43205bd2752a 449
Vanger 56:43205bd2752a 450 /** Checks data to output on the socket
Vanger 56:43205bd2752a 451 * @returns number of bytes to be written to the socket.
Vanger 56:43205bd2752a 452 */
Vanger 56:43205bd2752a 453 virtual unsigned int writeable();
Vanger 56:43205bd2752a 454
Vanger 56:43205bd2752a 455 /** Gets the device IP
Vanger 56:43205bd2752a 456 * @returns string containing the IP address
Vanger 56:43205bd2752a 457 */
Vanger 56:43205bd2752a 458 virtual std::string getDeviceIP();
Vanger 56:43205bd2752a 459
Vanger 56:43205bd2752a 460 /** Sets the device IP
Vanger 56:43205bd2752a 461 * (Not implemented, IP address values are assigned by DHCP)
Vanger 56:43205bd2752a 462 * @returns true if the IP was set, false if IP address assignment failed.
Vanger 56:43205bd2752a 463 */
Vanger 56:43205bd2752a 464 virtual bool setDeviceIP(std::string address = "DHCP");
Vanger 63:f46ef5823ab5 465
Vanger 63:f46ef5823ab5 466 /** Get the device IMEI or MEID (whichever is available)
Vanger 63:f46ef5823ab5 467 * @returns string containing the IMEI for GSM, the MEID for CDMA, or an empty string
Vanger 63:f46ef5823ab5 468 * if it failed to parse the number.
Vanger 63:f46ef5823ab5 469 */
Vanger 63:f46ef5823ab5 470 std::string getEquipmentIdentifier();
Mike Fiore 11:4e428f689069 471
Mike Fiore 76:6eeffc10739d 472 /** Get string representation of radio type
Mike Fiore 76:6eeffc10739d 473 * @returns string containing the radio type (MTSMC-H5, etc)
Mike Fiore 76:6eeffc10739d 474 */
Mike Fiore 76:6eeffc10739d 475 std::string getRadioType();
Mike Fiore 76:6eeffc10739d 476
Mike Fiore 3:04046eebaef5 477 protected:
Mike Fiore 3:04046eebaef5 478 MTSBufferedIO* io; //IO interface obect that the radio is accessed through.
Mike Fiore 3:04046eebaef5 479 bool echoMode; //Specifies if the echo mode is currently enabled.
Mike Fiore 3:04046eebaef5 480
Mike Fiore 3:04046eebaef5 481 bool pppConnected; //Specifies if a PPP session is currently connected.
Mike Fiore 3:04046eebaef5 482 std::string apn; //A string that holds the APN for the radio.
Mike Fiore 3:04046eebaef5 483
Mike Fiore 9:1a03e3f3e7fe 484 Radio type; //The type of radio being used
Mike Fiore 9:1a03e3f3e7fe 485
mfiore 19:f6261f1c3dd4 486 Mode socketMode; //The current socket Mode.
Mike Fiore 3:04046eebaef5 487 bool socketOpened; //Specifies if a Socket is presently opened.
Mike Fiore 3:04046eebaef5 488 bool socketCloseable; //Specifies is a Socket can be closed.
Mike Fiore 3:04046eebaef5 489 unsigned int local_port; //Holds the local port for socket connections.
Mike Fiore 3:04046eebaef5 490 std::string local_address; //Holds the local address for socket connections.
Mike Fiore 3:04046eebaef5 491 unsigned int host_port; //Holds the remote port for socket connections.
Mike Fiore 3:04046eebaef5 492 std::string host_address; //Holds the remote address for socket connections.
Mike Fiore 9:1a03e3f3e7fe 493
Mike Fiore 9:1a03e3f3e7fe 494 DigitalIn* dcd; //Maps to the radio's dcd signal
Mike Fiore 9:1a03e3f3e7fe 495 DigitalOut* dtr; //Maps to the radio's dtr signal
Mike Fiore 9:1a03e3f3e7fe 496 DigitalOut* resetLine; //Maps to the radio's reset signal
Mike Fiore 1:f155d94d6f3a 497 };
Mike Fiore 1:f155d94d6f3a 498
Mike Fiore 1:f155d94d6f3a 499 }
Mike Fiore 1:f155d94d6f3a 500
Mike Fiore 2:10e72dce251d 501 #endif /* CELLULAR_H */