Wifi.h

00001 /* Universal Socket Modem Interface Library
00002 * Copyright (c) 2013 Multi-Tech Systems
00003 *
00004 * Licensed under the Apache License, Version 2.0 (the "License");
00005 * you may not use this file except in compliance with the License.
00006 * You may obtain a copy of the License at
00007 *
00008 *     http://www.apache.org/licenses/LICENSE-2.0
00009 *
00010 * Unless required by applicable law or agreed to in writing, software
00011 * distributed under the License is distributed on an "AS IS" BASIS,
00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 * See the License for the specific language governing permissions and
00014 * limitations under the License.
00015 */
00016 
00017 #ifndef WIFI_H
00018 #define WIFI_H
00019 
00020 #include "IPStack.h"
00021 #include "MTSBufferedIO.h"
00022 #include "mbed.h"
00023 #include <string>
00024 #include <vector>
00025 
00026 using namespace mts;
00027 
00028 /** This is a class for communicating with a Roving Networks RN-171 Wifi module. This
00029 * module comes in a variety of form factors including the Multi-Tech SocketShield.
00030 * This class supports two main types of WiFi module interactions including:
00031 * configuration and status command processing and TCP Socket
00032 * data connections. It should be noted that while a data connection is open the module
00033 * must be put in command mode before commands can be sent. This is handled within the class
00034 * automatically for all native commands. This class also inherits from IPStack
00035 * providing a common set of commands for communication devices that have an onboard
00036 * IP Stack. It is also integrated with the standard mbed Sockets package and can therefore
00037 * be used seamlessly with clients and services built on top of this interface already within
00038 * the mbed library.
00039 *
00040 * All of the following examples use the Pin Names for the Freedom KL46Z board coupled with
00041 * the SocketModem Shield Arduino compatible board. Please chage Pin Names accordingly to
00042 * match your hardware configuration. The default baud rate for the WiFi module is 9600 bps.
00043 *
00044 * The following example shows how to connect to a WiFi netork and perform a basic ping test:
00045 * @code
00046 * #include "mbed.h"
00047 * #include "MTSSerial.h"
00048 * #include "Wifi.h"
00049 * using namespace mts;
00050 *
00051 * int main()
00052 * {
00053 *   std::string ssid = "Your SSID goes here";
00054 *   std::string securityKey = "Your secuirty key goes here";
00055 *   Wifi::SecurityType securityType = Wifi::WPA2;
00056 *
00057 *   //Wait for wifi module to boot up
00058 *   for (int i = 10; i >= 0; i = i - 2) {
00059 *       wait(2);
00060 *       printf("Waiting %d seconds...\n\r", i);
00061 *   }
00062 *
00063 *   //Setup serial interface to WiFi module
00064 *   MTSSerial* serial = new MTSSerial(PTD3, PTD2, 256, 256);
00065 *   serial->baud(9600);
00066 *
00067 *   //Setup Wifi class
00068 *   Wifi* wifi = Wifi::getInstance();
00069 *   printf("Init: %s\n\r", wifi->init(serial) ? "SUCCESS" : "FAILURE");
00070 *
00071 *   //Setup and check connection
00072 *   printf("Set Network: %s\n\r", getCodeNames(wifi->setNetwork(ssid, securityType, securityKey)).c_str());
00073 *   printf("Set DHCP: %s\n\r", getCodeNames(wifi->setDeviceIP("DHCP")).c_str());
00074 *   printf("Connect: %s\n\r", wifi->connect() ? "Success" : "Failure");
00075 *   printf("Is Connected: %s\n\r", wifi->isConnected() ? "True" : "False");
00076 *   printf("Ping Server: %s\n\r", wifi->ping("8.8.8.8") ? "Success" : "Failed");
00077 *
00078 *   //Disconnect from network
00079 *   printf("Disconnecting...\n\r");
00080 *   wifi->disconnect();
00081 *   printf("Is Connected: %s\n\r", wifi->isConnected() ? "True" : "False");
00082 *
00083 *   printf("End Program\n\r");
00084 * }
00085 * @endcode
00086 */
00087 class Wifi : public IPStack
00088 {
00089 public:
00090     ///An enumeration for all the supported WiFi security types.
00091     enum SecurityType {
00092         NONE, WEP64, WEP128, WPA, WPA2
00093     };
00094 
00095     /** Destructs a Wifi object and frees all related resources.
00096     */
00097     ~Wifi();
00098 
00099     /** This static function is used to create or get a reference to a
00100     * Wifi object. Wifi uses the singleton pattern, which means
00101     * that you can only have one existing at a time. The first time you
00102     * call getInstance this method creates a new uninitialized Wifi
00103     * object and returns it. All future calls to this method will return
00104     * a reference to the instance created during the first call. Note that
00105     * you must call init on the returned instance before mnaking any other
00106     * calls. If using this class's bindings to any of the Socket package
00107     * classes like TCPSocketConnection, you must call this method and the
00108     * init method on the returned object first, before even creating the
00109     * other objects.
00110     *
00111     * @returns a reference to the single Wifi obect that has been created.
00112     */
00113     static Wifi* getInstance();
00114 
00115     /** This method initializes the object with the underlying Wifi module
00116     * interface to use. Note that this function MUST be called before
00117     * any other calls will function correctly on a Wifi object. Also
00118     * note that MTSBufferedIO is abstract, so you must use one of
00119     * its inherited classes like MTSSerial or MTSSerialFlowControl.
00120     *
00121     * @param io the buffered io interface that is attached to the wifi
00122     * radio module.
00123     * @returns true if the init was successful, otherwise false.
00124     */
00125     bool init(MTSBufferedIO* io);
00126 
00127     /** This method establishes a network connection on the Wif radio module.
00128     * Note that before calling you NEED to first set the network information
00129     * including WiFi SSID and optional security key using the setNetwork
00130     * method.
00131     *
00132     * @returns true if the connection was successfully established, otherwise
00133     * false on an error.
00134     */
00135     virtual bool connect();
00136 
00137     /** This method is used to stop a previously established Wifi network connection.
00138     */
00139     virtual void disconnect();
00140 
00141     /** This method is used to check if the radio currently has a Wifi network
00142     * connection established.
00143     *
00144     * @returns true if a network connection exists, otherwise false.
00145     */
00146     virtual bool isConnected();
00147 
00148     // TCP and UDP Socket related commands
00149     // For behavior of the following methods refer to IPStack.h documentation
00150     virtual bool bind(unsigned int port);
00151     virtual bool open(const std::string& address, unsigned int port, Mode mode);
00152     virtual bool isOpen();
00153     virtual bool close();
00154     virtual int read(char* data, int max, int timeout = -1);
00155     virtual int write(const char* data, int length, int timeout = -1);
00156     virtual unsigned int readable();
00157     virtual unsigned int writeable();
00158 
00159     /** This method performs a soft reboot of the device by issuing the
00160     * reboot command. If the module is not able to respond to commands
00161     * this will not work. This method also waits 10 seconds for the
00162     * module to perform the reset and return.
00163     */
00164     virtual void reset();
00165 
00166     /** A method for sending a generic text command to the radio. Note that you cannot
00167     * send commands and have a socket connection at the same time, unless you first
00168     * switch to command mode.
00169     *
00170     * @param command the command to send to the WiFi module without the escape character.
00171     * @param timeoutMillis the time in millis to wait for a response before returning.
00172     * @param response the text string to look for and to return immediately after finding.
00173     * The default is to look for no specific response.
00174     * @param esc escape character to add at the end of the command, defaults to
00175     * carriage return (CR).  Does not append any character if esc == 0.
00176     * @returns all data received from the radio after the command as a string.
00177     */
00178     std::string sendCommand(std::string command, int timeoutMillis, std::string response = "", char esc = CR);
00179 
00180     /** A method for sending a basic command to the radio. A basic text command is
00181     * one that simply has a response of either AOK or ERR without any other information.
00182     * Note that you cannot send commands and have a tcp connection at the same time
00183     * unless you first switch to command mode.
00184     *
00185     * @param command the command to send to the WiFi module without the escape character.
00186     * @param timeoutMillis the time in millis to wait for a response before returning.
00187     * @param esc escape character to add at the end of the command, defaults to
00188     * carriage return (CR).
00189     * @returns the standard Code enumeration.
00190     */
00191     Code sendBasicCommand(std::string command, int timeoutMillis, char esc = CR);
00192 
00193     /** This method is used to set the network information details. This method must be
00194     * called before connect, which establishes the WiFi network connection.
00195     *
00196     * @param ssid the SSID for the network you want to attached to.
00197     * @param type the type of security used on the network. The default is NONE.
00198     * @param key the security key for the network. The default is no key.
00199     */
00200     Code setNetwork(const std::string& ssid, SecurityType type = NONE, const std::string& key = "");
00201 
00202     /** This method is used to set the IP address or puts the module in DHCP mode.
00203     *
00204     * @param address the IP address you want to use in the form of xxx.xxx.xxx.xxx or DHCP
00205     * if you want to use DHCP. The default is DHCP.
00206     * @returns the standard Code enumeration.
00207     */
00208     Code setDeviceIP(std::string address = "DHCP");
00209 
00210     /** This method is used to get the IP address of the device, which can be
00211     * set either statically or via DHCP after connecting to a network.
00212     *
00213     * @returns the devices IP address.
00214     */
00215     std::string getDeviceIP();
00216 
00217     /** This method is used to set the DNS which enables the use of URLs instead
00218     * of IP addresses when making a socket connection.
00219     *
00220     * @param the DNS server address as a string in form xxx.xxx.xxx.xxx.
00221     * @returns the standard AT Code enumeration.
00222     */
00223     Code setDNS(const std::string& dnsName);
00224 
00225     /** A method for getting the signal strength of the Wifi module. This method allows
00226     * you to get the signal strength in dBm. If you get a result of 99 the signal strength
00227     * is not known or there was an error in reading it. Note that you cannot read the signal
00228     * strength unless you are already attached to a Wifi network.
00229     *
00230     * @returns an integer representing the signal strength in dBm.
00231     */
00232     int getSignalStrength();
00233 
00234     /** This method is used test network connectivity by pinging a server.
00235     *
00236     * @param address the address of the server in format xxx.xxx.xxx.xxx.
00237     * @returns true if the ping was successful, otherwise false.
00238     */
00239     bool ping(const std::string& address = "8.8.8.8");
00240 
00241     /** This method is used to set whether the device is in command mode or data mode.
00242     * In command mode you are able to send configuration and status commands while
00243     * data mode is used for sending data when you have an open socket connection.
00244     * Note that for all other methods in this class the change is handled automatically.
00245     * Only use this methodif you want to send your own commands that are not already
00246     * supported and need to make sure that you are in command mode.
00247     *
00248     * @param on if true sets to command mode, otherwise to data mode.
00249     * @returns true if the change was successful, otherwise false.
00250     */
00251     bool setCmdMode(bool on);
00252 
00253 private:
00254     static Wifi* instance; //Static pointer to the single Cellular object.
00255 
00256     MTSBufferedIO* io; //IO interface obect that the radio is accessed through.
00257 
00258     bool wifiConnected; //Specifies if a Wifi network session is currently connected.
00259     std::string _ssid; //A string that holds the SSID for the Wifi module.
00260 
00261     Mode mode; //The current socket Mode.
00262     bool socketOpened; //Specifies if a Socket is presently opened.
00263     bool socketCloseable; //Specifies is a Socket can be closed.
00264     unsigned int local_port; //Holds the local port for socket connections.
00265     std::string local_address; //Holds the local address for socket connections.
00266     unsigned int host_port; //Holds the remote port for socket connections.
00267     std::string host_address; //Holds the remote address for socket connections.
00268     bool cmdOn; //Determines whether the device is in command mode or not
00269 
00270     Wifi(); //Private constructor, use the getInstance() method.
00271     Wifi(MTSBufferedIO* io); //Private constructor, use the getInstance() method.
00272     bool sortInterfaceMode(void); // module gets in wierd state without IO reset
00273     std::string getHostByName(std::string url); // Gets the IP address for a URL
00274 };
00275 
00276 #endif /* WIFI_H */