MultiTech / MTS-Cellular

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

Dependents:   mtsas mtsas mtsas mtsas

Cellular/Cellular.h@82:5b33b670adb7, 2018-02-19 (annotated)

Committer:
Leon Lindenfelser
Date:
Mon Feb 19 14:25:58 2018 -0600
Revision:
82:5b33b670adb7
Parent:
81:2e12915f892e 
Add support for MTQ-LAT3(LE910-NA1) adn MTQ-LVW3(LE910-sv1)

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 {
Leon Lindenfelser 81:2e12915f892e 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,
Leon Lindenfelser 82:5b33b670adb7 249 MTQ_LAT3, MTQ_LVW3, MTQ_MAT1, MTQ_MVW1
Mike Fiore 1:f155d94d6f3a 250 };
Mike Fiore 1:f155d94d6f3a 251
Mike Fiore 1:f155d94d6f3a 252 /// An enumeration of radio registration states with a cell tower.
Mike Fiore 1:f155d94d6f3a 253 enum Registration {
Mike Fiore 1:f155d94d6f3a 254 NOT_REGISTERED, REGISTERED, SEARCHING, DENIED, UNKNOWN, ROAMING
Mike Fiore 1:f155d94d6f3a 255 };
Mike Fiore 1:f155d94d6f3a 256
Mike Fiore 1:f155d94d6f3a 257 /** This structure contains the data for an SMS message.
Mike Fiore 1:f155d94d6f3a 258 */
Mike Fiore 1:f155d94d6f3a 259 struct Sms {
Mike Fiore 1:f155d94d6f3a 260 /// Message Phone Number
Mike Fiore 1:f155d94d6f3a 261 std::string phoneNumber;
Mike Fiore 1:f155d94d6f3a 262 /// Message Body
Mike Fiore 1:f155d94d6f3a 263 std::string message;
Mike Fiore 1:f155d94d6f3a 264 /// Message Timestamp
Mike Fiore 1:f155d94d6f3a 265 std::string timestamp;
Mike Fiore 1:f155d94d6f3a 266 };
Mike Fiore 1:f155d94d6f3a 267
mfiore 78:fc9d2b983744 268 /** This structure contains the data for GPS position.
mfiore 78:fc9d2b983744 269 */
mfiore 78:fc9d2b983744 270 struct gpsData {
mfiore 78:fc9d2b983744 271 bool success;
mfiore 78:fc9d2b983744 272 /// Format is ddmm.mmmm N/S. Where: dd - degrees 00..90; mm.mmmm - minutes 00.0000..59.9999; N/S: North/South.
mfiore 78:fc9d2b983744 273 std::string latitude;
mfiore 78:fc9d2b983744 274 /// Format is dddmm.mmmm E/W. Where: ddd - degrees 000..180; mm.mmmm - minutes 00.0000..59.9999; E/W: East/West.
mfiore 78:fc9d2b983744 275 std::string longitude;
mfiore 78:fc9d2b983744 276 /// Horizontal Diluition of Precision.
mfiore 78:fc9d2b983744 277 float hdop;
mfiore 78:fc9d2b983744 278 /// Altitude - mean-sea-level (geoid) in meters.
mfiore 78:fc9d2b983744 279 float altitude;
mfiore 78:fc9d2b983744 280 /// 0 or 1 - Invalid Fix; 2 - 2D fix; 3 - 3D fix.
mfiore 78:fc9d2b983744 281 int fix;
mfiore 78:fc9d2b983744 282 /// Format is ddd.mm - Course over Ground. Where: ddd - degrees 000..360; mm - minutes 00..59.
mfiore 78:fc9d2b983744 283 std::string cog;
mfiore 78:fc9d2b983744 284 /// Speed over ground (Km/hr).
mfiore 78:fc9d2b983744 285 float kmhr;
mfiore 78:fc9d2b983744 286 /// Speed over ground (knots).
mfiore 78:fc9d2b983744 287 float knots;
mfiore 78:fc9d2b983744 288 /// Total number of satellites in use.
mfiore 78:fc9d2b983744 289 int satellites;
mfiore 78:fc9d2b983744 290 /// Date and time in the format YY/MM/DD,HH:MM:SS.
mfiore 78:fc9d2b983744 291 std::string timestamp;
mfiore 78:fc9d2b983744 292 };
mfiore 78:fc9d2b983744 293
Mike Fiore 1:f155d94d6f3a 294 /** This method initializes the object with the underlying radio
Mike Fiore 1:f155d94d6f3a 295 * interface to use. Note that this function MUST be called before
Mike Fiore 1:f155d94d6f3a 296 * any other calls will function correctly on a Cellular object. Also
Mike Fiore 1:f155d94d6f3a 297 * note that MTSBufferedIO is abstract, so you must use one of
Mike Fiore 3:04046eebaef5 298 * its inherited classes like MTSSerial, MTSSerialFlowControl or write a class
Mike Fiore 3:04046eebaef5 299 * similar to MTSSerialFlowControl which maps the MTSBufferedIO API
Mike Fiore 3:04046eebaef5 300 * to your favorite serial library.
Mike Fiore 1:f155d94d6f3a 301 *
Mike Fiore 3:04046eebaef5 302 * @param io the io interface that is attached to the cellular radio.
Mike Fiore 1:f155d94d6f3a 303 * The default is not connected.
Mike Fiore 1:f155d94d6f3a 304 * @returns true if the init was successful, otherwise false.
Mike Fiore 1:f155d94d6f3a 305 */
Mike Fiore 8:2d7259d244d1 306 virtual bool init(MTSBufferedIO* io);
Mike Fiore 9:1a03e3f3e7fe 307
Vanger 26:2b769ed8de4f 308 /** Sets up the physical connection pins
Vanger 52:2cb58398a4f9 309 * (DTR,DCD, and RESET)
Mike Fiore 9:1a03e3f3e7fe 310 */
Mike Fiore 9:1a03e3f3e7fe 311 bool configureSignals(unsigned int DCD = NC, unsigned int DTR = NC, unsigned int RESET = NC);
Mike Fiore 1:f155d94d6f3a 312
Mike Fiore 1:f155d94d6f3a 313 /** A method for testing command access to the radio. This method sends the
Mike Fiore 1:f155d94d6f3a 314 * command "AT" to the radio, which is a standard radio test to see if you
Mike Fiore 1:f155d94d6f3a 315 * have command access to the radio. The function returns when it receives
Mike Fiore 1:f155d94d6f3a 316 * the expected response from the radio.
Mike Fiore 1:f155d94d6f3a 317 *
Mike Fiore 1:f155d94d6f3a 318 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 319 */
Mike Fiore 1:f155d94d6f3a 320 virtual Code test();
Mike Fiore 1:f155d94d6f3a 321
Mike Fiore 1:f155d94d6f3a 322 /** A method for getting the signal strength of the radio. This method allows you to
Mike Fiore 1:f155d94d6f3a 323 * get a value that maps to signal strength in dBm. Here 0-1 is Poor, 2-9 is Marginal,
Mike Fiore 1:f155d94d6f3a 324 * 10-14 is Ok, 15-19 is Good, and 20+ is Excellent. If you get a result of 99 the
Mike Fiore 1:f155d94d6f3a 325 * signal strength is not known or not detectable.
Mike Fiore 1:f155d94d6f3a 326 *
Mike Fiore 1:f155d94d6f3a 327 * @returns an integer representing the signal strength.
Mike Fiore 1:f155d94d6f3a 328 */
Mike Fiore 1:f155d94d6f3a 329 virtual int getSignalStrength();
Mike Fiore 1:f155d94d6f3a 330
Mike Fiore 1:f155d94d6f3a 331 /** This method is used to check the registration state of the radio with the cell tower.
Mike Fiore 1:f155d94d6f3a 332 * If not appropriatley registered with the tower you cannot make a cellular connection.
Mike Fiore 1:f155d94d6f3a 333 *
Mike Fiore 1:f155d94d6f3a 334 * @returns the registration state as an enumeration type.
Mike Fiore 1:f155d94d6f3a 335 */
Mike Fiore 1:f155d94d6f3a 336 virtual Registration getRegistration();
Mike Fiore 1:f155d94d6f3a 337
Mike Fiore 1:f155d94d6f3a 338 /** This method is used to set the radios APN if using a SIM card. Note that the APN
Mike Fiore 1:f155d94d6f3a 339 * must be set correctly before you can make a data connection. The APN for your SIM
Mike Fiore 1:f155d94d6f3a 340 * can be obtained by contacting your cellular service provider.
Mike Fiore 1:f155d94d6f3a 341 *
Mike Fiore 1:f155d94d6f3a 342 * @param the APN as a string.
Mike Fiore 1:f155d94d6f3a 343 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 344 */
Vanger 52:2cb58398a4f9 345 virtual Code setApn(const std::string& apn) = 0;
Mike Fiore 1:f155d94d6f3a 346
Mike Fiore 1:f155d94d6f3a 347 /** This method is used to set the DNS which enables the use of URLs instead
Mike Fiore 1:f155d94d6f3a 348 * of IP addresses when making a socket connection.
Mike Fiore 1:f155d94d6f3a 349 *
Mike Fiore 1:f155d94d6f3a 350 * @param the DNS server address as a string in form xxx.xxx.xxx.xxx.
Mike Fiore 1:f155d94d6f3a 351 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 352 */
Mike Fiore 8:2d7259d244d1 353 virtual Code setDns(const std::string& primary, const std::string& secondary = "0.0.0.0");
Mike Fiore 1:f155d94d6f3a 354
Mike Fiore 1:f155d94d6f3a 355 /** This method is used to send an SMS message. Note that you cannot send an
Mike Fiore 1:f155d94d6f3a 356 * SMS message and have a data connection open at the same time.
Mike Fiore 1:f155d94d6f3a 357 *
Mike Fiore 1:f155d94d6f3a 358 * @param phoneNumber the phone number to send the message to as a string.
Mike Fiore 1:f155d94d6f3a 359 * @param message the text message to be sent.
Mike Fiore 1:f155d94d6f3a 360 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 361 */
Mike Fiore 7:0ee8e69a3e9c 362 virtual Code sendSMS(const std::string& phoneNumber, const std::string& message);
Mike Fiore 1:f155d94d6f3a 363
Mike Fiore 1:f155d94d6f3a 364 /** This method is used to send an SMS message. Note that you cannot send an
Mike Fiore 1:f155d94d6f3a 365 * SMS message and have a data connection open at the same time.
Mike Fiore 1:f155d94d6f3a 366 *
Mike Fiore 1:f155d94d6f3a 367 * @param sms an Sms struct that contains all SMS transaction information.
Mike Fiore 1:f155d94d6f3a 368 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 369 */
Mike Fiore 7:0ee8e69a3e9c 370 virtual Code sendSMS(const Sms& sms);
Mike Fiore 1:f155d94d6f3a 371
Mike Fiore 1:f155d94d6f3a 372 /** This method retrieves all of the SMS messages currently available for
Mike Fiore 1:f155d94d6f3a 373 * this phone number.
Mike Fiore 1:f155d94d6f3a 374 *
Mike Fiore 1:f155d94d6f3a 375 * @returns a vector of existing SMS messages each as an Sms struct.
Mike Fiore 1:f155d94d6f3a 376 */
Mike Fiore 7:0ee8e69a3e9c 377 virtual std::vector<Cellular::Sms> getReceivedSms();
Mike Fiore 1:f155d94d6f3a 378
Mike Fiore 1:f155d94d6f3a 379 /** This method can be used to remove/delete all received SMS messages
Mike Fiore 1:f155d94d6f3a 380 * even if they have never been retrieved or read.
Mike Fiore 1:f155d94d6f3a 381 *
Mike Fiore 1:f155d94d6f3a 382 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 383 */
Mike Fiore 7:0ee8e69a3e9c 384 virtual Code deleteAllReceivedSms();
Mike Fiore 1:f155d94d6f3a 385
Mike Fiore 1:f155d94d6f3a 386 /** This method can be used to remove/delete all received SMS messages
Mike Fiore 1:f155d94d6f3a 387 * that have been retrieved by the user through the getReceivedSms method.
Mike Fiore 1:f155d94d6f3a 388 * Messages that have not been retrieved yet will be unaffected.
Mike Fiore 1:f155d94d6f3a 389 *
Mike Fiore 1:f155d94d6f3a 390 * @returns the standard AT Code enumeration.
Mike Fiore 1:f155d94d6f3a 391 */
Mike Fiore 7:0ee8e69a3e9c 392 virtual Code deleteOnlyReceivedReadSms();
Mike Fiore 1:f155d94d6f3a 393
Mike Fiore 1:f155d94d6f3a 394 //Cellular Radio Specific
Mike Fiore 1:f155d94d6f3a 395 /** A method for sending a generic AT command to the radio. Note that you cannot
Mike Fiore 1:f155d94d6f3a 396 * send commands and have a data connection at the same time.
Mike Fiore 1:f155d94d6f3a 397 *
Mike Fiore 1:f155d94d6f3a 398 * @param command the command to send to the radio without the escape character.
Mike Fiore 1:f155d94d6f3a 399 * @param timeoutMillis the time in millis to wait for a response before returning.
Mike Fiore 1:f155d94d6f3a 400 * @param esc escape character to add at the end of the command, defaults to
Mike Fiore 1:f155d94d6f3a 401 * carriage return (CR). Does not append any character if esc == 0.
Mike Fiore 1:f155d94d6f3a 402 * @returns all data received from the radio after the command as a string.
Mike Fiore 1:f155d94d6f3a 403 */
Mike Fiore 10:c188cc05aed5 404 virtual std::string sendCommand(const std::string& command, unsigned int timeoutMillis, char esc = CR);
Mike Fiore 1:f155d94d6f3a 405
Mike Fiore 1:f155d94d6f3a 406 /** A method for sending a basic AT command to the radio. A basic AT command is
Mike Fiore 1:f155d94d6f3a 407 * one that simply has a response of either OK or ERROR without any other information.
Mike Fiore 1:f155d94d6f3a 408 * Note that you cannot send commands and have a data connection at the same time.
Mike Fiore 1:f155d94d6f3a 409 *
Mike Fiore 1:f155d94d6f3a 410 * @param command the command to send to the radio without the escape character.
Mike Fiore 1:f155d94d6f3a 411 * @param timeoutMillis the time in millis to wait for a response before returning.
Mike Fiore 1:f155d94d6f3a 412 * @param esc escape character to add at the end of the command, defaults to
Mike Fiore 1:f155d94d6f3a 413 * carriage return (CR).
Mike Fiore 1:f155d94d6f3a 414 * @returns the standard Code enumeration.
Mike Fiore 1:f155d94d6f3a 415 */
Mike Fiore 10:c188cc05aed5 416 virtual Code sendBasicCommand(const std::string& command, unsigned int timeoutMillis, char esc = CR);
Mike Fiore 1:f155d94d6f3a 417
Mike Fiore 1:f155d94d6f3a 418 /** A static method for getting a string representation for the Registration
Mike Fiore 1:f155d94d6f3a 419 * enumeration.
Mike Fiore 1:f155d94d6f3a 420 *
Mike Fiore 1:f155d94d6f3a 421 * @param code a Registration enumeration.
Mike Fiore 1:f155d94d6f3a 422 * @returns the enumeration name as a string.
Mike Fiore 1:f155d94d6f3a 423 */
Mike Fiore 1:f155d94d6f3a 424 static std::string getRegistrationNames(Registration registration);
Mike Fiore 3:04046eebaef5 425
Mike Fiore 11:4e428f689069 426 /** A static method for getting a string representation for the Radio
Mike Fiore 11:4e428f689069 427 * enumeration.
Mike Fiore 11:4e428f689069 428 *
Mike Fiore 11:4e428f689069 429 * @param type a Radio enumeration.
Mike Fiore 11:4e428f689069 430 * @returns the enumeration name as a string.
Mike Fiore 11:4e428f689069 431 */
Mike Fiore 11:4e428f689069 432 static std::string getRadioNames(Radio radio);
Vanger 56:43205bd2752a 433
Vanger 27:ec44d5a9544f 434 /** A method for changing the echo commands from radio.
Vanger 27:ec44d5a9544f 435 * @param state Echo mode is off (an argument of 1 turns echos off, anything else turns echo on)
Vanger 27:ec44d5a9544f 436 * @returns standard Code enumeration
Vanger 27:ec44d5a9544f 437 */
Vanger 56:43205bd2752a 438 virtual Code echo(bool state);
Vanger 56:43205bd2752a 439
Vanger 56:43205bd2752a 440 /** This method can be used to trade socket functionality for performance.
Vanger 56:43205bd2752a 441 * Can disable checking socket closed messages from the data socket, and thus the socket
Vanger 56:43205bd2752a 442 * will only be visibly closed to the local side if the radio is explicitly checked, or
Vanger 56:43205bd2752a 443 * the socket is closed by the local side through the use of physical pin manipulation.
Vanger 56:43205bd2752a 444 *
Vanger 56:43205bd2752a 445 * Uses the Hayes escape sequence (1 second pause, "+++", 1 second pause) to exit the socket
Vanger 56:43205bd2752a 446 * connection to check if a received "NO CARRIER" string is from the radio indicating the socket
Vanger 56:43205bd2752a 447 * has been closed, or is merely part of the data stream. Should not occur very often, however, if
Vanger 56:43205bd2752a 448 * data carrying the string "NO CARRIER" is going to be transmitted frequently, then the socket should
Vanger 56:43205bd2752a 449 * be set closeable and physical-socket-closing-means be used instead to reduce the large amount of
Vanger 56:43205bd2752a 450 * overhead switching from checking the validity of the "NO CARRIER" message being and indication of
Vanger 56:43205bd2752a 451 * the socket connection being closed.
Vanger 56:43205bd2752a 452 *
Vanger 56:43205bd2752a 453 * @param enabled set to true if you want the socket closeable, otherwise false. The default
Vanger 56:43205bd2752a 454 * is true.
Vanger 56:43205bd2752a 455 * @returns the standard AT Code enumeration.
Vanger 56:43205bd2752a 456 */
Vanger 56:43205bd2752a 457 virtual Code setSocketCloseable(bool enabled);
Vanger 56:43205bd2752a 458
Vanger 56:43205bd2752a 459 /** Binds the socket to a specific port if able
Vanger 56:43205bd2752a 460 * @param port integer to bind the socket to.
Vanger 56:43205bd2752a 461 *
Vanger 56:43205bd2752a 462 * @returns true if successfully bound port, false if bind failed.
Vanger 56:43205bd2752a 463 */
Vanger 56:43205bd2752a 464 virtual bool bind(unsigned int port);
Vanger 56:43205bd2752a 465
Vanger 56:43205bd2752a 466 /** Checks if a socket is open.
Vanger 56:43205bd2752a 467 * @returns true if socket is open, false if socket is closed
Vanger 56:43205bd2752a 468 */
Vanger 56:43205bd2752a 469 virtual bool isOpen();
Vanger 56:43205bd2752a 470
Vanger 56:43205bd2752a 471 /** Checks if there is data available from the socket.
Vanger 56:43205bd2752a 472 * @returns number of bytes of data available to read.
Vanger 56:43205bd2752a 473 */
Vanger 56:43205bd2752a 474 virtual unsigned int readable();
Vanger 56:43205bd2752a 475
Vanger 56:43205bd2752a 476 /** Checks data to output on the socket
Vanger 56:43205bd2752a 477 * @returns number of bytes to be written to the socket.
Vanger 56:43205bd2752a 478 */
Vanger 56:43205bd2752a 479 virtual unsigned int writeable();
Vanger 56:43205bd2752a 480
Vanger 56:43205bd2752a 481 /** Gets the device IP
Vanger 56:43205bd2752a 482 * @returns string containing the IP address
Vanger 56:43205bd2752a 483 */
Vanger 56:43205bd2752a 484 virtual std::string getDeviceIP();
Vanger 56:43205bd2752a 485
Vanger 56:43205bd2752a 486 /** Sets the device IP
Vanger 56:43205bd2752a 487 * (Not implemented, IP address values are assigned by DHCP)
Vanger 56:43205bd2752a 488 * @returns true if the IP was set, false if IP address assignment failed.
Vanger 56:43205bd2752a 489 */
Vanger 56:43205bd2752a 490 virtual bool setDeviceIP(std::string address = "DHCP");
Vanger 63:f46ef5823ab5 491
Vanger 63:f46ef5823ab5 492 /** Get the device IMEI or MEID (whichever is available)
Vanger 63:f46ef5823ab5 493 * @returns string containing the IMEI for GSM, the MEID for CDMA, or an empty string
Vanger 63:f46ef5823ab5 494 * if it failed to parse the number.
Vanger 63:f46ef5823ab5 495 */
Vanger 63:f46ef5823ab5 496 std::string getEquipmentIdentifier();
Mike Fiore 11:4e428f689069 497
mfiore 80:e66bf5723b98 498 /** Get radio type
mfiore 80:e66bf5723b98 499 * @returns the radio type (MTSMC-H5, etc)
mfiore 80:e66bf5723b98 500 */
mfiore 80:e66bf5723b98 501 int getRadioType();
mfiore 80:e66bf5723b98 502
Mike Fiore 76:6eeffc10739d 503 /** Get string representation of radio type
Mike Fiore 76:6eeffc10739d 504 * @returns string containing the radio type (MTSMC-H5, etc)
Mike Fiore 76:6eeffc10739d 505 */
mfiore 80:e66bf5723b98 506 std::string getRadioTypeString();
Mike Fiore 76:6eeffc10739d 507
mfiore 78:fc9d2b983744 508 /** Enables GPS.
mfiore 78:fc9d2b983744 509 * @returns true if GPS is enabled, false if GPS is not supported.
mfiore 78:fc9d2b983744 510 */
mfiore 78:fc9d2b983744 511 virtual bool GPSenable();
mfiore 78:fc9d2b983744 512
mfiore 78:fc9d2b983744 513 /** Disables GPS.
mfiore 78:fc9d2b983744 514 * @returns true if GPS is disabled, false if GPS does not disable.
mfiore 78:fc9d2b983744 515 */
mfiore 78:fc9d2b983744 516 virtual bool GPSdisable();
mfiore 78:fc9d2b983744 517
mfiore 78:fc9d2b983744 518 /** Checks if GPS is enabled.
mfiore 78:fc9d2b983744 519 * @returns true if GPS is enabled, false if GPS is disabled.
mfiore 78:fc9d2b983744 520 */
mfiore 78:fc9d2b983744 521 virtual bool GPSenabled();
mfiore 78:fc9d2b983744 522
mfiore 78:fc9d2b983744 523 /** Get GPS position.
mfiore 78:fc9d2b983744 524 * @returns a structure containing the GPS data field information.
mfiore 78:fc9d2b983744 525 */
mfiore 78:fc9d2b983744 526 virtual gpsData GPSgetPosition();
mfiore 78:fc9d2b983744 527
mfiore 78:fc9d2b983744 528 /** Check for GPS fix.
mfiore 78:fc9d2b983744 529 * @returns true if there is a fix and false otherwise.
mfiore 78:fc9d2b983744 530 */
mfiore 78:fc9d2b983744 531 virtual bool GPSgotFix();
mfiore 78:fc9d2b983744 532
Mike Fiore 3:04046eebaef5 533 protected:
Mike Fiore 3:04046eebaef5 534 MTSBufferedIO* io; //IO interface obect that the radio is accessed through.
Mike Fiore 3:04046eebaef5 535 bool echoMode; //Specifies if the echo mode is currently enabled.
Mike Fiore 3:04046eebaef5 536
mfiore 78:fc9d2b983744 537 bool gpsEnabled; //true if GPS is enabled, else false.
mfiore 78:fc9d2b983744 538
Mike Fiore 3:04046eebaef5 539 bool pppConnected; //Specifies if a PPP session is currently connected.
Mike Fiore 3:04046eebaef5 540 std::string apn; //A string that holds the APN for the radio.
Mike Fiore 3:04046eebaef5 541
Mike Fiore 9:1a03e3f3e7fe 542 Radio type; //The type of radio being used
Mike Fiore 9:1a03e3f3e7fe 543
mfiore 19:f6261f1c3dd4 544 Mode socketMode; //The current socket Mode.
Mike Fiore 3:04046eebaef5 545 bool socketOpened; //Specifies if a Socket is presently opened.
Mike Fiore 3:04046eebaef5 546 bool socketCloseable; //Specifies is a Socket can be closed.
Mike Fiore 3:04046eebaef5 547 unsigned int local_port; //Holds the local port for socket connections.
Mike Fiore 3:04046eebaef5 548 std::string local_address; //Holds the local address for socket connections.
Mike Fiore 3:04046eebaef5 549 unsigned int host_port; //Holds the remote port for socket connections.
Mike Fiore 3:04046eebaef5 550 std::string host_address; //Holds the remote address for socket connections.
Mike Fiore 9:1a03e3f3e7fe 551
Mike Fiore 9:1a03e3f3e7fe 552 DigitalIn* dcd; //Maps to the radio's dcd signal
Mike Fiore 9:1a03e3f3e7fe 553 DigitalOut* dtr; //Maps to the radio's dtr signal
Mike Fiore 9:1a03e3f3e7fe 554 DigitalOut* resetLine; //Maps to the radio's reset signal
Mike Fiore 1:f155d94d6f3a 555 };
Mike Fiore 1:f155d94d6f3a 556
Mike Fiore 1:f155d94d6f3a 557 }
Mike Fiore 1:f155d94d6f3a 558
Mike Fiore 79:da70f86996a1 559 #endif /* CELLULAR_H */