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@120:3051dd49fa3a, 2013-12-31 (annotated)

Committer:
jengbrecht
Date:
Tue Dec 31 22:58:53 2013 +0000
Revision:
120:3051dd49fa3a
Parent:
108:554585370b4a
Child:
121:5a7fba896c98
Updated Wifi documentation

Who changed what in which revision?

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