Reviewer's Guide to Easy WiFi

This guide is intended to help an evaluator of Easy WiFi understand the functionality of the consumer clients versus the functionality available to licensees.

Easy WiFi is available in two main versions: As a full-featured licensed product available to OEMs manufacturing CE / Handset products, and as a consumer ready download for various popular platforms.

For OEMs, Easy WiFi is designed-in and tightly integrated into the final device – the feature set and behavior is determined by the manufacturer or network operator.

For consumers, a series of downloadable free versions are available that typically implement a subset of the available Easy WiFi functionality.

Quick Start

Here are the basics:

1. Download and install the app (see what is available).
2. First ensure you have an active connection to the Internet, then start the app.  You need a network connection because the device is going to register with the Easy WiFi servers (licensed clients do not need to enforce device/user registration).
3. Currently Android, S60, and iPhone OS clients ask you to register by providing an email address and password.  Windows, Windows Mobile, and Mac OS X do not require this step, instead anonymously registering (they can be registered to a named account later, if required).  The email address is not currently verified.  If you forget your password you can recover it through the web interface at easywifi.com.
4. At this point you are setup to use the Easy WiFi Network (read more).  If you have any network credentials, you can add them using easywifi.com or the app's "add network provider" capability.  See Entering Credentials for instructions.  This will add the capability to login automatically at these locations, and any of their roaming partners.
5. You can see all of your network locations on easywifi.com or on the device's map view (on Android, S60, and iPhone OS).  Accessible locations are shown as blue (verified) and amber (unverified) "pins".  You can switch on "other networks" and see those pins in red.  Note: to see your personal map on easywifi.com you need to be logged in, otherwise you will see the default view only of the base Easy WiFi Network.
6. Now, the client will connect you automatically at your locations.  On iPhone and iPod touch you have two additional steps: (1) you will need to run the app at a location to log you in, and (2) you will need to join the network first.  On S60, you may need to select the Easy WiFi Access Point or Internet Destination when asked.  On Windows, Windows Mobile, Android and Mac the client will log you in automatically, provided it is running in the background.

Read more below to help you understand the functionality of Easy WiFi compared with the full product.

Differences Between Consumer Clients and Full Package

The Easy WiFi consumer clients are representative of much of the functionality available in the full package, but differ in several important areas:

1. Integration Limitations - the underlying OS platform often places limitations of the level of functionality available to Easy WiFi (this is particularly true of the iPhone OS). The Capabilities section below describes this on a platform by platform basis.
2. Subset of Easy WiFi Client - the licensed Easy WiFi client is modular and offers rich WiFi security (supplicant, WPS, available CCX), hotspot client, and network services (including the Easy WiFi Network). Typically the consumer clients focus on hotspot integration, network services and the Easy WiFi Network.
3. User Account and Interaction - the consumer clients require users to create an account and optionally to add hotspot provider credentials.  In a licensed design these are optional steps, as devices can self register and be configured transparently and dynamically.
4. Easy WiFi Network - the consumer clients include the Devicescape virtual network by default, and are implemented in order to encourage the collection and verification of new networks and locations.  In a licensed design, the Easy WiFi Network can be completely customized, allowing it to be disabled or offer a specialized footprint (e.g. to offer locations with a higher service level, more recently used, biased towards certain types of venues, etc).
5. New Open Network treatment - the consumer clients are not "WiFi scanners" and typically will not try to utilize newly discovered open networks.  This functionality can be customized in the licensed design.  See more below in Missing Locations.
6. Reporting - consumer clients report GPS coordinates and other information to Devicescape's web service, to enable growth and monitoring of the virtual network.  This can be disabled in licensed designs.
7. Size and UI - Easy WiFi is designed to bring connectivity to a wide range of WiFi enabled products. Compared to the "minimum possible implementation" available to licensees the consumer clients are relatively rich in UI and resources used.  In particular, the consumer clients may show maps, allow for users to see network interactions, allow the users to select network providers, view history, etc.  All of this is unessential to the core functionality of connecting to networks.  Licensed clients can use a very small footprint (<300k) with little or no UI, DRAM, nor data store, and still connect to the full Easy WiFi hotspot footprint. Setup and management can take place on the web, or "behind the scenes" via Easy WiFi management APIs. This allows for Easy WiFi to be deployed on the smallest and simplest devices.

For more information on differences and limitations, read below, or contact Devicescape.

Available Easy WiFi Clients

Currently Devicescape makes consumer clients for Windows (XP, Vista, 7), Mac OS X, Windows Mobile 5 & 6, S60 3rd & 5th generation (qualified on Nokia S60 phones, but may work on other implementations), Android, and iPhone OS.  These clients are available from the easywifi.com download page and from the Nokia Ovi, Android, and Apple application stores. 

In addition, Easy WiFi has implementations for earlier Nokia Maemo tablets (N770, N800) and some basic Linux implementations.  Contact Devicescape to inquire about these.

An Easy WiFi SDK can also be made available to licensees who wish to perform a test integration into their own products.  The SDK is delivered as source code with various OS integration APIs, including Linux.  Reference implementations for consumer OS platforms are available upon request (essentially the source code for the consumer versions, these are intended for use as a starting point for integration projects).  The SDK can also be requested with an evaluation license from Devicescape.

What does Easy WiFi Do?

The Easy WiFi consumer client provides these main functions:

• Automated login at a hotspot location which is part of the user's footprint profile. By default, the footprint includes the entire Easy WiFi Network. The user can customize their footprint by disabling the Easy WiFi Network and/or adding any number of hotspot providers.
• Easy WiFi supports automated login with thousands of hotspot providers, large and small.  Although Easy WiFi can utilize its own virtual hotspot network - the Easy WiFi Network - it's not essential. And, new hotspot providers can be added quickly without any requirement to upgrade the client, making it easy to future proof the product and avoid mass updating of the installed base.
• Automated login to roaming partner networks.  If a user has extended their footprint with their own hotspot providers then Easy WiFi will automatically process roaming partners.  This means that Easy WiFi will provision the device's preferred network list to associate with the roaming partner networks, AND will perform the correct actions to login, including providing credentials in the correct format.  There is no need for the user to know about roaming partnerships or to select multiple hotspot providers - only the "base provider" which they have an account with.  This works with WISPr and UAM.
• All clients (except iPhone OS) provision the device's preferred network list to ensure the device will associate automatically.  This is used in a number of ways: (1) to associate with the full list of SSIDs in the user's footprint, including the SSIDs of roaming partners, (2) to ease the use of hotspots in the footprint which might be protected with a security key (such as Japanese providers) and (3) to accommodate a user's "private networks" (see more under Private Networks below). 
• A map to see and search for hotspot locations. This is implemented on some of the clients (currently S60 5th edition, Android, and iPhone OS) or available on easywifi.com. Locations within the user's footprint are shown by blue and amber pins. Optionally the user can see locations outside their footprint, which show as red pins. The map is implemented on the client with a mapping service such as Google Maps, and therefore is available only with a current network connection.  The licensed version of Easy WiFi offers an API that allows developers to implement mapping functionality in their own products, however Easy WiFi does not provide the map, only the data to be used with mapping services (such as those from Nokia, Microsoft, and Google).
• Reporting of information to the Easy WiFi web service in order to allow new locations to be discovered, and for network health to be monitored. This is described below in Missing Locations and in How Easy WiFi Works.
• Various other UI capabilities such as settings screens, connection history, ability to edit hotspot providers etc.

Although the consumer clients involve fairly rich UIs, much of the functionality can be implemented in a UI-less design, with mapping and management functions performed via the easywifi.com portal. Further, the management portal can be re-branded and embedded on a licensees website, or completely hidden from the end user through API integration (into another management system or application).

What does Easy WiFi Not Do?

There are some common misconceptions about Easy WiFi, independent of platform limitations.

• The client will not connect to unknown, open networks, although this feature is under consideration for future releases.  You may, therefore, be confused if you expect Easy WiFi to try to probe for and utilize these types of location.  This is described below and in more detail in How Easy WiFi Works.
• The client will not attempt to navigate new web-based captive portal networks through "artificial intelligence".  Easy WiFi only works with captive portals which are explicitly supported in the Easy WiFi Network service database.  New captive portals are collected automatically by the consumer clients and forwarded to Devicescape for analysis, and users can directly request new networks to be added via the New Provider page. It is quite easy to add such networks, with no change required to existing clients.
• The client does not automatically support every WISPr-based network.  Although WISPr is completely supported by the client, networks must be specifically added as described in the previous section.
• Map locations may not be entirely accurate as they are constructed from GPS readings.  Since GPS does not function well indoors, this means that (a) map pins may be outside and close to the true location of the AP and (b) indoor hotspot locations may never show on the map.  Nonetheless, Easy WiFi will make connections to known networks even if the location cannot be displayed on the map, and accuracy will grow over multiple reports so that locations should be easy to find.
• Easy WiFi will not connect you to account-based networks where you don't have an account.  You need to add these accounts to your Easy WiFi setup, and provide credentials.
• Easy WiFi does not work very conveniently with "walk up" hotspots where you add a temporary code like a voucher or one time password.  It is possible for Easy WiFi to support these hotspots, but since you need a network connection to be able to enter the credential into Easy WiFi, it often negates the value for such temporary uses.  Easy WiFi works best with permanent credentials.

User Guides for the Consumer Clients

Several basic resources are on easywifi.com:

• User guides for iPhone OS (web, PDF), Windows Mobile, S60 (3rd edition, 5th edition).  Currently there is no manual for Android, Windows, or Mac.
• Using the Web Manager.
• Some basics about the Easy WiFi Network.
• More detail on how Easy WiFi Works.
• Technical material and product information can be found on devicescape.com in the product, and white paper areas.

Capabilities and Limitations

The underlying operating system for each consumer client makes it close to impossible for a completely consistent experience.  The full Easy WiFi SDK implements a superset of features and, of course, can be further customized and extended by a licensee.  The following is a list of capabilities and limitations of each of the consumer clients, by platform.

iPhone OS (iPhone and iPod Touch)

Somewhat ironically, the design of the iPhone OS severely limits the convenience of Easy WiFi.  The iPhone OS takes a "black box" approach to any app's use of WiFi, providing little information about the connection and no control of the environment.  In practice, this means that users must "join" each specific network SSID in advance of running the client, and that the client must be active in order to login.  While the requirement to join seems like a small inconvenience as it only needs to be done once, this becomes a major issue for the user as the Easy WiFi Network consists of thousands of aggregated SSIDs, and some providers have large numbers of roaming partners each with their own SSIDs.

For the iPhone OS, Easy WiFi checks to see if a network is available and waits to see whether the OS auto-joins it.  If so, the client will initiate a connection/login attempt.  If not, the user is asked to exit the app, join the network in Settings, and then restart the app.

Capabilities:

• User registration
• Map
• Provider setup (a "provider" is a network operator)
• History page

Limitations:

• User must manually join all SSIDs
• User must run app to login (i.e. it does not run in the background) 

Windows (PC)

Capabilities:

• Anonymous registration (can be converted to named account via "sign up" option)
• Autologin while app is running in background
• Provisions preferred list with provider SSIDs / roaming partners, and personal networks
• Accesses a subset of the Easy WiFi Network
• Will probe and use new open and click-through networks (this behavior can be switched off)

Limitations:

• No map, history, provider setup (use easywifi.com)
• Accesses a subset of the Easy WiFi Network
• May not autostart on Windows 7 

Mac OS X

Capabilities:

• Anonymous registration (can be converted to named account via "sign up" option)
• Autologin while app is running in background
• Provisions preferred list with Easy WiFi Network, providers / roaming partners, and personal networks (Snow Leopard only)

Limitations:

• No map, history, provider setup (use easywifi.com)
• On OS prior to Snow Leopard, does not provision preferred list
• Will not probe and use new open and click-through networks

Windows Mobile

Capabilities:

• Anonymous registration (can be converted to named account via "sign up" option)
• Autologin while app is running in background
• Provisions preferred list with providers / roaming partners, and personal networks
• Accesses a subset of the Easy WiFi Network
• Will probe and use new open and click-through networks (this behavior can be switched off)

Limitations:

• No map, history, provider setup (use easywifi.com)
• Accesses a subset of the Easy WiFi Network
• Jumps into foreground when device starts up 

Android

Capabilities:

• User registration
• Autologin - app is running as a system service, independent of UI
• Provisions preferred list with Easy WiFi Network, providers / roaming partners, and personal networks
• Map
• Provider setup
• History page

Limitations:

• May not support all variations of Android (new platform issue)

S60

Capabilities:

• User registration
• Autologin - app is running as a system service, independent of UI
• Supports the Easy WiFi Network, providers / roaming partners, and personal networks
• Map (on 5th edition devices only)
• Provider setup
• History page (on 5th edition devices only)

Limitations:

• 3rd edition devices do not support the Easy WiFi Network, and do not have a map nor connection history
• Tested on Nokia devices only

Private Networks

Users can use the web manager at easywifi.com to add their own private networks to their account.  These are not true hotspot networks, but instead simple APs such as home networks secured with WPA personal security keys.  Once the user enters the SSID and the security key into their accounts, any devices attached to their account will have their preferred network list provisioned (generally, the next time they make a network connection with the client).  This functionality may seem unnecessary, however it has several benefits:

• It allows for a new device to be added to the user's account and setup with the correct networks and keys
• Security keys and other changes can be made on the user's account and quickly reflected on all devices
• A simple "friends and family" system can be implemented where the user can share her network with others, with less complexity and avoiding exposing security keys
• Future functionality could be implemented allowing for broad-based sharing of secured APs

Note: due to limitations in the iPhone OS, this functionality is not available and the user must manually manage networks.

Entering Credentials

Credentials are typically usernames and passwords provided by a free or paid WiFi network operator.  You add credentials for your accounts using the "add personal hotspot provider" capability on the client or in the account tab of easywifi.com.  Easy WiFi automatically handles roaming relationships, so you only need to enter credentials for your provider. Do not enter your credentials for any of your provider's roaming partners: if you do Easy WiFi will most likely fail to authenticate at these hotspots.  For example, if you have a T-Mobile WiFi account, you will only enter your credentials for T-Mobile: Easy WiFi will supply the correct credentials and login methods whenever you are using a roaming partner like BT Openzone or Softbank.  On most clients, Easy WiFi will provision the preferred network list to associate with partner SSIDs too, making the user experience much simpler.

Incorrectly entered credentials are one common problem area for consumer clients.  Users sometimes add realm information or domain suffixes when they are not needed.  Although most providers are supported by entering the simple username alone, occasionally a username needs additional information. This is particularly true for AT&T in the US, which is one of the few networks which - as the result of consolidation - needs the correct domain to be entered into the username field (e.g. name@attwifi.com or name@sbcglobal.net).  Again, for most providers, only the simple username should be used.  Post a message in the Forum if you need advice.

Troubleshooting

You may encounter some issues and error conditions using Easy WiFi:

Error Messages

• No credentials: You can't use the currently associated hotspot because you haven't added it as a personal hotspot provider, or you may have entered credentials incorrectly (see Entering Credentials).
• Connection Failed: This is a "catch-all" error, and typically is shown when the current hotspot fails to communicate at all. The backhaul may be disconnected, the authentication service may be down, or you may not have a valid IP address from the AP. Check whether you can login manually.

Missing Locations on the Map

The map may not show all locations for providers which are supported by Easy WiFi. Despite this, automated login will still happen at such a location, and when a connection is made the location will be added to the database. Provided that certain conditions are met - such as a solid GPS fix - the map will be updated within a few minutes.

Similarly, open "free WiFi" hotspots which you know are working may not be shown. Except for Windows, the consumer clients do not automatically try to connect to unknown, open hotspots. Instead, these are added to the database and (once enough information has been gathered) these are placed on the map as amber pins. After this, Easy WiFi will attempt connection at these locations, and if successful the locations will be upgraded to blue pins.

The process of network growth is described in more detail at How Easy WiFi Works.

Location Exactness

The map may show pins in odd locations, such as in the middle of the road close by the true location.  This is because of GPS coordinates collected by the client. While coordinates are averaged for accuracy, they will still not be exact indications of the true location of the AP.

Some Expired Network Points May Be Shown

On occasion the map may show network locations which no longer exist.  This is because of the newness of the dataset which is currently set for less aggressive aging.  It is likely that we will adopt a more aggressive aging strategy in the near future, removing old networks more quickly.