Multi-Hackers / SocketModem

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

Dependents:   M2X_dev axeda_wrapper_dev MTS_M2x_Example1 MTS_Cellular_Connect_Example ... more

wifi/Wifi.h@141:571e0ef6c8dc, 2014-01-04 (annotated)

Committer:
kranjan
Date:
Sat Jan 04 05:28:45 2014 +0000
Revision:
141:571e0ef6c8dc
Parent:
139:73a7d1cd2e9c 
Added licensing header to all files in the library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kranjan 141:571e0ef6c8dc 1 /* Universal Socket Modem Interface Library
kranjan 141:571e0ef6c8dc 2 * Copyright (c) 2013 Multi-Tech Systems
kranjan 141:571e0ef6c8dc 3 *
kranjan 141:571e0ef6c8dc 4 * Licensed under the Apache License, Version 2.0 (the "License");
kranjan 141:571e0ef6c8dc 5 * you may not use this file except in compliance with the License.
kranjan 141:571e0ef6c8dc 6 * You may obtain a copy of the License at
kranjan 141:571e0ef6c8dc 7 *
kranjan 141:571e0ef6c8dc 8 * http://www.apache.org/licenses/LICENSE-2.0
kranjan 141:571e0ef6c8dc 9 *
kranjan 141:571e0ef6c8dc 10 * Unless required by applicable law or agreed to in writing, software
kranjan 141:571e0ef6c8dc 11 * distributed under the License is distributed on an "AS IS" BASIS,
kranjan 141:571e0ef6c8dc 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kranjan 141:571e0ef6c8dc 13 * See the License for the specific language governing permissions and
kranjan 141:571e0ef6c8dc 14 * limitations under the License.
kranjan 141:571e0ef6c8dc 15 */
kranjan 141:571e0ef6c8dc 16
jengbrecht 69:f3e696bbb0d5 17 #ifndef WIFI_H
jengbrecht 69:f3e696bbb0d5 18 #define WIFI_H
jengbrecht 69:f3e696bbb0d5 19
jengbrecht 69:f3e696bbb0d5 20 #include "IPStack.h"
jengbrecht 69:f3e696bbb0d5 21 #include "MTSBufferedIO.h"
jengbrecht 69:f3e696bbb0d5 22 #include "mbed.h"
jengbrecht 69:f3e696bbb0d5 23 #include <string>
jengbrecht 138:a233b9775f93 24 #include <vector>
jengbrecht 69:f3e696bbb0d5 25
jengbrecht 69:f3e696bbb0d5 26 using namespace mts;
jengbrecht 69:f3e696bbb0d5 27
jengbrecht 108:554585370b4a 28 /** This is a class for communicating with a Roving Networks RN-171 Wifi module. This
jengbrecht 108:554585370b4a 29 * module comes in a variety of form factors including the Multi-Tech SocketShield.
jengbrecht 108:554585370b4a 30 * This class supports two main types of WiFi module interactions including:
jengbrecht 139:73a7d1cd2e9c 31 * configuration and status command processing and TCP Socket
jengbrecht 108:554585370b4a 32 * data connections. It should be noted that while a data connection is open the module
jengbrecht 108:554585370b4a 33 * must be put in command mode before commands can be sent. This is handled within the class
jengbrecht 108:554585370b4a 34 * automatically for all native commands. This class also inherits from IPStack
jengbrecht 108:554585370b4a 35 * providing a common set of commands for communication devices that have an onboard
jengbrecht 108:554585370b4a 36 * IP Stack. It is also integrated with the standard mbed Sockets package and can therefore
jengbrecht 108:554585370b4a 37 * be used seamlessly with clients and services built on top of this interface already within
jengbrecht 108:554585370b4a 38 * the mbed library.
jengbrecht 108:554585370b4a 39 *
jengbrecht 108:554585370b4a 40 * All of the following examples use the Pin Names for the Freedom KL46Z board coupled with
jengbrecht 108:554585370b4a 41 * the SocketModem Shield Arduino compatible board. Please chage Pin Names accordingly to
jengbrecht 108:554585370b4a 42 * match your hardware configuration. The default baud rate for the WiFi module is 9600 bps.
jengbrecht 108:554585370b4a 43 *
jengbrecht 120:3051dd49fa3a 44 * The following example shows how to connect to a WiFi netork and perform a basic ping test:
jengbrecht 120:3051dd49fa3a 45 * @code
jengbrecht 120:3051dd49fa3a 46 * #include "mbed.h"
jengbrecht 120:3051dd49fa3a 47 * #include "MTSSerial.h"
jengbrecht 120:3051dd49fa3a 48 * #include "Wifi.h"
jengbrecht 120:3051dd49fa3a 49 * using namespace mts;
jengbrecht 120:3051dd49fa3a 50 *
jengbrecht 120:3051dd49fa3a 51 * int main()
jengbrecht 120:3051dd49fa3a 52 * {
jengbrecht 120:3051dd49fa3a 53 * std::string ssid = "Your SSID goes here";
jengbrecht 120:3051dd49fa3a 54 * std::string securityKey = "Your secuirty key goes here";
jengbrecht 120:3051dd49fa3a 55 * Wifi::SecurityType securityType = Wifi::WPA2;
jengbrecht 138:a233b9775f93 56 *
jengbrecht 120:3051dd49fa3a 57 * //Wait for wifi module to boot up
jengbrecht 120:3051dd49fa3a 58 * for (int i = 10; i >= 0; i = i - 2) {
jengbrecht 120:3051dd49fa3a 59 * wait(2);
jengbrecht 120:3051dd49fa3a 60 * printf("Waiting %d seconds...\n\r", i);
jengbrecht 138:a233b9775f93 61 * }
jengbrecht 120:3051dd49fa3a 62 *
jengbrecht 120:3051dd49fa3a 63 * //Setup serial interface to WiFi module
jengbrecht 120:3051dd49fa3a 64 * MTSSerial* serial = new MTSSerial(PTD3, PTD2, 256, 256);
jengbrecht 120:3051dd49fa3a 65 * serial->baud(9600);
jengbrecht 138:a233b9775f93 66 *
jengbrecht 120:3051dd49fa3a 67 * //Setup Wifi class
jengbrecht 120:3051dd49fa3a 68 * Wifi* wifi = Wifi::getInstance();
jengbrecht 120:3051dd49fa3a 69 * printf("Init: %s\n\r", wifi->init(serial) ? "SUCCESS" : "FAILURE");
jengbrecht 138:a233b9775f93 70 *
jengbrecht 120:3051dd49fa3a 71 * //Setup and check connection
jengbrecht 120:3051dd49fa3a 72 * printf("Set Network: %s\n\r", getCodeNames(wifi->setNetwork(ssid, securityType, securityKey)).c_str());
jengbrecht 120:3051dd49fa3a 73 * printf("Set DHCP: %s\n\r", getCodeNames(wifi->setDeviceIP("DHCP")).c_str());
jengbrecht 120:3051dd49fa3a 74 * printf("Connect: %s\n\r", wifi->connect() ? "Success" : "Failure");
jengbrecht 120:3051dd49fa3a 75 * printf("Is Connected: %s\n\r", wifi->isConnected() ? "True" : "False");
jengbrecht 120:3051dd49fa3a 76 * printf("Ping Server: %s\n\r", wifi->ping("8.8.8.8") ? "Success" : "Failed");
jengbrecht 138:a233b9775f93 77 *
jengbrecht 120:3051dd49fa3a 78 * //Disconnect from network
jengbrecht 120:3051dd49fa3a 79 * printf("Disconnecting...\n\r");
jengbrecht 120:3051dd49fa3a 80 * wifi->disconnect();
jengbrecht 120:3051dd49fa3a 81 * printf("Is Connected: %s\n\r", wifi->isConnected() ? "True" : "False");
jengbrecht 138:a233b9775f93 82 *
jengbrecht 120:3051dd49fa3a 83 * printf("End Program\n\r");
jengbrecht 120:3051dd49fa3a 84 * }
jengbrecht 120:3051dd49fa3a 85 * @endcode
jengbrecht 108:554585370b4a 86 */
jengbrecht 69:f3e696bbb0d5 87 class Wifi : public IPStack
jengbrecht 69:f3e696bbb0d5 88 {
jengbrecht 69:f3e696bbb0d5 89 public:
jengbrecht 103:da58d27c15d7 90 ///An enumeration for all the supported WiFi security types.
jengbrecht 69:f3e696bbb0d5 91 enum SecurityType {
jengbrecht 69:f3e696bbb0d5 92 NONE, WEP64, WEP128, WPA, WPA2
jengbrecht 69:f3e696bbb0d5 93 };
jengbrecht 69:f3e696bbb0d5 94
jengbrecht 103:da58d27c15d7 95 /** Destructs a Wifi object and frees all related resources.
jengbrecht 103:da58d27c15d7 96 */
jengbrecht 69:f3e696bbb0d5 97 ~Wifi();
jengbrecht 69:f3e696bbb0d5 98
jengbrecht 103:da58d27c15d7 99 /** This static function is used to create or get a reference to a
jengbrecht 103:da58d27c15d7 100 * Wifi object. Wifi uses the singleton pattern, which means
jengbrecht 103:da58d27c15d7 101 * that you can only have one existing at a time. The first time you
jengbrecht 103:da58d27c15d7 102 * call getInstance this method creates a new uninitialized Wifi
jengbrecht 103:da58d27c15d7 103 * object and returns it. All future calls to this method will return
jengbrecht 103:da58d27c15d7 104 * a reference to the instance created during the first call. Note that
jengbrecht 103:da58d27c15d7 105 * you must call init on the returned instance before mnaking any other
jengbrecht 103:da58d27c15d7 106 * calls. If using this class's bindings to any of the Socket package
jengbrecht 103:da58d27c15d7 107 * classes like TCPSocketConnection, you must call this method and the
jengbrecht 103:da58d27c15d7 108 * init method on the returned object first, before even creating the
jengbrecht 103:da58d27c15d7 109 * other objects.
jengbrecht 103:da58d27c15d7 110 *
jengbrecht 103:da58d27c15d7 111 * @returns a reference to the single Wifi obect that has been created.
jengbrecht 103:da58d27c15d7 112 */
jengbrecht 69:f3e696bbb0d5 113 static Wifi* getInstance();
jengbrecht 103:da58d27c15d7 114
jengbrecht 103:da58d27c15d7 115 /** This method initializes the object with the underlying Wifi module
jengbrecht 103:da58d27c15d7 116 * interface to use. Note that this function MUST be called before
jengbrecht 103:da58d27c15d7 117 * any other calls will function correctly on a Wifi object. Also
jengbrecht 103:da58d27c15d7 118 * note that MTSBufferedIO is abstract, so you must use one of
jengbrecht 103:da58d27c15d7 119 * its inherited classes like MTSSerial or MTSSerialFlowControl.
jengbrecht 103:da58d27c15d7 120 *
jengbrecht 103:da58d27c15d7 121 * @param io the buffered io interface that is attached to the wifi
jengbrecht 103:da58d27c15d7 122 * radio module.
jengbrecht 103:da58d27c15d7 123 * @returns true if the init was successful, otherwise false.
jengbrecht 103:da58d27c15d7 124 */
jengbrecht 69:f3e696bbb0d5 125 bool init(MTSBufferedIO* io);
jengbrecht 69:f3e696bbb0d5 126
jengbrecht 103:da58d27c15d7 127 /** This method establishes a network connection on the Wif radio module.
jengbrecht 103:da58d27c15d7 128 * Note that before calling you NEED to first set the network information
jengbrecht 103:da58d27c15d7 129 * including WiFi SSID and optional security key using the setNetwork
jengbrecht 103:da58d27c15d7 130 * method.
jengbrecht 103:da58d27c15d7 131 *
jengbrecht 103:da58d27c15d7 132 * @returns true if the connection was successfully established, otherwise
jengbrecht 103:da58d27c15d7 133 * false on an error.
jengbrecht 103:da58d27c15d7 134 */
jengbrecht 69:f3e696bbb0d5 135 virtual bool connect();
jengbrecht 103:da58d27c15d7 136
jengbrecht 103:da58d27c15d7 137 /** This method is used to stop a previously established Wifi network connection.
jengbrecht 103:da58d27c15d7 138 */
jengbrecht 69:f3e696bbb0d5 139 virtual void disconnect();
jengbrecht 103:da58d27c15d7 140
jengbrecht 103:da58d27c15d7 141 /** This method is used to check if the radio currently has a Wifi network
jengbrecht 103:da58d27c15d7 142 * connection established.
jengbrecht 103:da58d27c15d7 143 *
jengbrecht 103:da58d27c15d7 144 * @returns true if a network connection exists, otherwise false.
jengbrecht 103:da58d27c15d7 145 */
jengbrecht 69:f3e696bbb0d5 146 virtual bool isConnected();
jengbrecht 69:f3e696bbb0d5 147
jengbrecht 69:f3e696bbb0d5 148 // TCP and UDP Socket related commands
jengbrecht 69:f3e696bbb0d5 149 // For behavior of the following methods refer to IPStack.h documentation
jengbrecht 69:f3e696bbb0d5 150 virtual bool bind(unsigned int port);
jengbrecht 69:f3e696bbb0d5 151 virtual bool open(const std::string& address, unsigned int port, Mode mode);
jengbrecht 69:f3e696bbb0d5 152 virtual bool isOpen();
jengbrecht 69:f3e696bbb0d5 153 virtual bool close();
jengbrecht 69:f3e696bbb0d5 154 virtual int read(char* data, int max, int timeout = -1);
jengbrecht 69:f3e696bbb0d5 155 virtual int write(const char* data, int length, int timeout = -1);
jengbrecht 69:f3e696bbb0d5 156 virtual unsigned int readable();
jengbrecht 69:f3e696bbb0d5 157 virtual unsigned int writeable();
jengbrecht 69:f3e696bbb0d5 158
jengbrecht 121:5a7fba896c98 159 /** This method performs a soft reboot of the device by issuing the
jengbrecht 121:5a7fba896c98 160 * reboot command. If the module is not able to respond to commands
jengbrecht 121:5a7fba896c98 161 * this will not work. This method also waits 10 seconds for the
jengbrecht 121:5a7fba896c98 162 * module to perform the reset and return.
jengbrecht 121:5a7fba896c98 163 */
jengbrecht 69:f3e696bbb0d5 164 virtual void reset();
jengbrecht 69:f3e696bbb0d5 165
jengbrecht 106:358972176b89 166 /** A method for sending a generic text command to the radio. Note that you cannot
jengbrecht 106:358972176b89 167 * send commands and have a socket connection at the same time, unless you first
jengbrecht 106:358972176b89 168 * switch to command mode.
jengbrecht 106:358972176b89 169 *
jengbrecht 106:358972176b89 170 * @param command the command to send to the WiFi module without the escape character.
jengbrecht 106:358972176b89 171 * @param timeoutMillis the time in millis to wait for a response before returning.
jengbrecht 106:358972176b89 172 * @param response the text string to look for and to return immediately after finding.
jengbrecht 106:358972176b89 173 * The default is to look for no specific response.
jengbrecht 106:358972176b89 174 * @param esc escape character to add at the end of the command, defaults to
jengbrecht 106:358972176b89 175 * carriage return (CR). Does not append any character if esc == 0.
jengbrecht 106:358972176b89 176 * @returns all data received from the radio after the command as a string.
jengbrecht 106:358972176b89 177 */
jengbrecht 93:aa7a48e65974 178 std::string sendCommand(std::string command, int timeoutMillis, std::string response = "", char esc = CR);
jengbrecht 106:358972176b89 179
jengbrecht 106:358972176b89 180 /** A method for sending a basic command to the radio. A basic text command is
jengbrecht 106:358972176b89 181 * one that simply has a response of either AOK or ERR without any other information.
jengbrecht 106:358972176b89 182 * Note that you cannot send commands and have a tcp connection at the same time
jengbrecht 106:358972176b89 183 * unless you first switch to command mode.
jengbrecht 106:358972176b89 184 *
jengbrecht 106:358972176b89 185 * @param command the command to send to the WiFi module without the escape character.
jengbrecht 106:358972176b89 186 * @param timeoutMillis the time in millis to wait for a response before returning.
jengbrecht 106:358972176b89 187 * @param esc escape character to add at the end of the command, defaults to
jengbrecht 106:358972176b89 188 * carriage return (CR).
jengbrecht 106:358972176b89 189 * @returns the standard Code enumeration.
jengbrecht 106:358972176b89 190 */
sgodinez 73:bb5bbca971ae 191 Code sendBasicCommand(std::string command, int timeoutMillis, char esc = CR);
jengbrecht 69:f3e696bbb0d5 192
jengbrecht 103:da58d27c15d7 193 /** This method is used to set the network information details. This method must be
jengbrecht 103:da58d27c15d7 194 * called before connect, which establishes the WiFi network connection.
jengbrecht 103:da58d27c15d7 195 *
jengbrecht 103:da58d27c15d7 196 * @param ssid the SSID for the network you want to attached to.
jengbrecht 103:da58d27c15d7 197 * @param type the type of security used on the network. The default is NONE.
jengbrecht 103:da58d27c15d7 198 * @param key the security key for the network. The default is no key.
jengbrecht 103:da58d27c15d7 199 */
jengbrecht 103:da58d27c15d7 200 Code setNetwork(const std::string& ssid, SecurityType type = NONE, const std::string& key = "");
jengbrecht 138:a233b9775f93 201
jengbrecht 106:358972176b89 202 /** This method is used to set the IP address or puts the module in DHCP mode.
jengbrecht 106:358972176b89 203 *
jengbrecht 106:358972176b89 204 * @param address the IP address you want to use in the form of xxx.xxx.xxx.xxx or DHCP
jengbrecht 106:358972176b89 205 * if you want to use DHCP. The default is DHCP.
jengbrecht 106:358972176b89 206 * @returns the standard Code enumeration.
jengbrecht 106:358972176b89 207 */
jengbrecht 106:358972176b89 208 Code setDeviceIP(std::string address = "DHCP");
jengbrecht 138:a233b9775f93 209
jengbrecht 106:358972176b89 210 /** This method is used to get the IP address of the device, which can be
jengbrecht 106:358972176b89 211 * set either statically or via DHCP after connecting to a network.
jengbrecht 106:358972176b89 212 *
jengbrecht 106:358972176b89 213 * @returns the devices IP address.
jengbrecht 106:358972176b89 214 */
jengbrecht 106:358972176b89 215 std::string getDeviceIP();
jengbrecht 103:da58d27c15d7 216
jengbrecht 103:da58d27c15d7 217 /** This method is used to set the DNS which enables the use of URLs instead
jengbrecht 103:da58d27c15d7 218 * of IP addresses when making a socket connection.
jengbrecht 103:da58d27c15d7 219 *
jengbrecht 103:da58d27c15d7 220 * @param the DNS server address as a string in form xxx.xxx.xxx.xxx.
jengbrecht 103:da58d27c15d7 221 * @returns the standard AT Code enumeration.
jengbrecht 103:da58d27c15d7 222 */
jengbrecht 94:1baa587e89ae 223 Code setDNS(const std::string& dnsName);
jengbrecht 103:da58d27c15d7 224
jengbrecht 103:da58d27c15d7 225 /** A method for getting the signal strength of the Wifi module. This method allows
jengbrecht 103:da58d27c15d7 226 * you to get the signal strength in dBm. If you get a result of 99 the signal strength
jengbrecht 103:da58d27c15d7 227 * is not known or there was an error in reading it. Note that you cannot read the signal
jengbrecht 103:da58d27c15d7 228 * strength unless you are already attached to a Wifi network.
jengbrecht 103:da58d27c15d7 229 *
jengbrecht 103:da58d27c15d7 230 * @returns an integer representing the signal strength in dBm.
jengbrecht 103:da58d27c15d7 231 */
jengbrecht 69:f3e696bbb0d5 232 int getSignalStrength();
jengbrecht 103:da58d27c15d7 233
jengbrecht 103:da58d27c15d7 234 /** This method is used test network connectivity by pinging a server.
jengbrecht 103:da58d27c15d7 235 *
jengbrecht 103:da58d27c15d7 236 * @param address the address of the server in format xxx.xxx.xxx.xxx.
jengbrecht 103:da58d27c15d7 237 * @returns true if the ping was successful, otherwise false.
jengbrecht 103:da58d27c15d7 238 */
jengbrecht 95:4fdf968b5b37 239 bool ping(const std::string& address = "8.8.8.8");
jengbrecht 103:da58d27c15d7 240
jengbrecht 103:da58d27c15d7 241 /** This method is used to set whether the device is in command mode or data mode.
jengbrecht 103:da58d27c15d7 242 * In command mode you are able to send configuration and status commands while
jengbrecht 103:da58d27c15d7 243 * data mode is used for sending data when you have an open socket connection.
jengbrecht 103:da58d27c15d7 244 * Note that for all other methods in this class the change is handled automatically.
jengbrecht 103:da58d27c15d7 245 * Only use this methodif you want to send your own commands that are not already
jengbrecht 103:da58d27c15d7 246 * supported and need to make sure that you are in command mode.
jengbrecht 103:da58d27c15d7 247 *
jengbrecht 103:da58d27c15d7 248 * @param on if true sets to command mode, otherwise to data mode.
jengbrecht 103:da58d27c15d7 249 * @returns true if the change was successful, otherwise false.
jengbrecht 103:da58d27c15d7 250 */
jengbrecht 79:f356009dbc12 251 bool setCmdMode(bool on);
jengbrecht 69:f3e696bbb0d5 252
jengbrecht 69:f3e696bbb0d5 253 private:
jengbrecht 69:f3e696bbb0d5 254 static Wifi* instance; //Static pointer to the single Cellular object.
jengbrecht 69:f3e696bbb0d5 255
jengbrecht 69:f3e696bbb0d5 256 MTSBufferedIO* io; //IO interface obect that the radio is accessed through.
jengbrecht 69:f3e696bbb0d5 257
jengbrecht 69:f3e696bbb0d5 258 bool wifiConnected; //Specifies if a Wifi network session is currently connected.
jengbrecht 69:f3e696bbb0d5 259 std::string _ssid; //A string that holds the SSID for the Wifi module.
jengbrecht 69:f3e696bbb0d5 260
jengbrecht 69:f3e696bbb0d5 261 Mode mode; //The current socket Mode.
jengbrecht 69:f3e696bbb0d5 262 bool socketOpened; //Specifies if a Socket is presently opened.
jengbrecht 69:f3e696bbb0d5 263 bool socketCloseable; //Specifies is a Socket can be closed.
jengbrecht 69:f3e696bbb0d5 264 unsigned int local_port; //Holds the local port for socket connections.
jengbrecht 69:f3e696bbb0d5 265 std::string local_address; //Holds the local address for socket connections.
jengbrecht 69:f3e696bbb0d5 266 unsigned int host_port; //Holds the remote port for socket connections.
jengbrecht 69:f3e696bbb0d5 267 std::string host_address; //Holds the remote address for socket connections.
jengbrecht 103:da58d27c15d7 268 bool cmdOn; //Determines whether the device is in command mode or not
jengbrecht 69:f3e696bbb0d5 269
jengbrecht 69:f3e696bbb0d5 270 Wifi(); //Private constructor, use the getInstance() method.
jengbrecht 69:f3e696bbb0d5 271 Wifi(MTSBufferedIO* io); //Private constructor, use the getInstance() method.
sam_grove 131:da8f0e1c264a 272 bool sortInterfaceMode(void); // module gets in wierd state without IO reset
jengbrecht 138:a233b9775f93 273 std::string getHostByName(std::string url); // Gets the IP address for a URL
jengbrecht 69:f3e696bbb0d5 274 };
jengbrecht 69:f3e696bbb0d5 275
jengbrecht 69:f3e696bbb0d5 276 #endif /* WIFI_H */