Multi-Hackers / SocketModem

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   M2X_dev axeda_wrapper_dev MTS_M2x_Example1 MTS_Cellular_Connect_Example ... more

cellular/Cellular.h@56:e5e5351f14b3, 2013-12-20 (annotated)

Committer:
jengbrecht
Date:
Fri Dec 20 20:26:46 2013 +0000
Revision:
56:e5e5351f14b3
Parent:
43:3cacf019ed7d
Child:
62:83ccef1e94db
Added more documentation to the Cellular class, along with static methods for converting some enums to strings. Also, removed one of the getInstance functions and changed it to an init function.

Who changed what in which revision?

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