EthernetInterface.h

00001 /* EthernetInterface.h */
00002 /* Copyright (C) 2012 mbed.org, MIT License
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00005  * and associated documentation files (the "Software"), to deal in the Software without restriction,
00006  * including without limitation the rights to use, copy, modify, merge, publish, distribute,
00007  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
00008  * furnished to do so, subject to the following conditions:
00009  *
00010  * The above copyright notice and this permission notice shall be included in all copies or
00011  * substantial portions of the Software.
00012  *
00013  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00014  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00015  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00016  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00017  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00018  *
00019  * Changes relative to mbed official version and others as identified
00020  * in the thread http://mbed.org/forum/team-165-components-community/topic/4844/?page=1#comment-24108
00021  * EthernetInterface:
00022  * @li Improve documentation
00023  * @li add setSecurity() api
00024  * @li correct connect() api return value (it was inverted)
00025  * @li derived from 4:0bcec6272784
00026  */
00027 
00028 #ifndef EthernetInterface_H_
00029 #define EthernetInterface_H_
00030 
00031 #include "Wifly.h"
00032 
00033 /** Interface using Wifly to connect to an IP-based network
00034 *
00035 */
00036 class EthernetInterface: public Wifly
00037 {
00038 public:
00039 
00040     /**
00041     * Construct the WiFlyInterface.
00042     *
00043     * API Precedence:
00044     * @verbatim
00045     * EthernetInterface() -->
00046     *            +------------------+              +---------------------------+
00047     *            v                  ^              v                           ^
00048     * -> init() -+----------------->+-> connect() -+-------------------------->+-> disconnect() --|
00049     *            |                  ^              +-> getName() --------------+
00050     *            +-> setName() -----+              +-> getIPAddress() ---------+
00051     *            |                  |              +-> getMACAddress() --------+
00052     *            +-> setSecurity() -+              +-> Wifly APIs -------------+
00053     *                                              +-> get_connection_speed() -+
00054     * @endverbatim
00055     *
00056     * @note The optional ssid, phrase, and sec parameters may be deferred, or
00057     *       overridden prior to the connect().
00058     *
00059     * @param tx mbed pin to use for tx line of Serial interface
00060     * @param rx mbed pin to use for rx line of Serial interface
00061     * @param reset reset pin of the wifi module ()
00062     * @param tcp_status connection status pin of the wifi module (GPIO 6)
00063     * @param ssid optional parameter which is the ssid of the network
00064     * @param phrase optional parameter which is the WEP or WPA key/phrase
00065     * @param sec optional security type (NONE[default], WEP_128 or WPA)
00066     */
00067     EthernetInterface(PinName tx, PinName rx, PinName reset, PinName tcp_status, const char * ssid = NULL, const char * phrase = NULL, Security sec = NONE);
00068 
00069     /** Initialize the interface with DHCP.
00070     * Initialize the interface and configure it to use DHCP (no connection at this point).
00071     * @return 0 on success, a negative number on failure
00072     */
00073     int init(); //With DHCP
00074 
00075     /** Initialize the interface with a static IP address.
00076     *
00077     * Initialize the interface and configure it with the following static
00078     * configuration (no connection at this point).
00079     *
00080     * @param ip the IP address to use
00081     * @param mask the IP address mask
00082     * @param gateway the gateway to use
00083     * @return 0 on success, a negative number on failure
00084     */
00085     int init(const char* ip, const char* mask, const char* gateway);
00086 
00087     /** Set security parameters for the interface.
00088     *
00089     * Prior to connect, this interface permits changing the security parameters. This
00090     * can be most useful when the Wifly module may be used where there are multiple access
00091     * points to be connected to. With this, the interface can be brought online far
00092     * enough to scan for available access points.
00093     *
00094     * @param ssid optional parameter which is the ssid of the network
00095     * @param phrase optional parameter which is the WEP or WPA key/phrase
00096     * @param sec optional security type (NONE[default], WEP_128 or WPA)
00097     */
00098     void setSecurity(const char * ssid = NULL, const char * phrase = NULL, Security sec = NONE);
00099 
00100     /** Connect
00101     * Bring the interface up, start DHCP if needed.
00102     * @return 0 on success, a negative number on failure
00103     */
00104     int connect();
00105 
00106     /** Disconnect
00107     * Bring the interface down
00108     * @return 0 on success, a negative number on failure
00109     */
00110     int disconnect();
00111 
00112     /** Get the MAC address of your Ethernet interface.
00113     *
00114     * @return a pointer to a string containing the MAC address
00115     */
00116     char * getMACAddress();
00117   
00118     /** Get IP address
00119     *
00120     * @return a pointer to a string containing the IP address
00121     */
00122     char * getIPAddress();
00123 
00124     /** setName 
00125     *
00126     * Set the network name for this device. Apply this before
00127     * calling 'connect'.
00128     *
00129     * @example
00130     * EthernetInterface eth;
00131     * ...
00132     *     if (0 == eth.init()) {
00133     *         eth.setName("Sensor 3");
00134     *         if (0 == eth.connect()) {
00135     *             ...
00136     *
00137     * @param myname is the name to assign for this node. 
00138     *        Only the first 32 characters will be used if the 
00139     *        name is longer.
00140     *        Only '0'-'9', 'A'-'Z', 'a'-'z' are accepted,
00141     *        any others are converted to '-'.
00142     * @return 0 on success, a negative number on failure.
00143     */
00144     int setName(const char * myname);
00145     
00146     /** getName
00147     *
00148     * Get the network name for this device.
00149     *
00150     * @return pointer to the name (or null)
00151     */
00152     const char * getName(void);
00153 
00154     /** get the speed of the connection.
00155     *
00156     * @return the connection speed, which can range from 1 to 54 (Mb/s)
00157     * @return 0 if the information could not be acquired.
00158     */
00159     int get_connection_speed(void);
00160 
00161 private:
00162     char ip_string[16];     // "129.168.100.123\0"
00163     bool ip_set;            // true when we have captured the IP address
00164     char mac_string[18];    // "11:22:33:44:55:66\0"
00165     bool mac_set;           // true when we have captured the MAC address
00166 };
00167 
00168 #include "TCPSocketConnection.h"
00169 #include "TCPSocketServer.h"
00170 #include "UDPSocket.h"
00171 
00172 #endif /* EthernetInterface_H_ */