Java Smart Config desktop client

I've written a desktop Smart Config user interface in Java for setting up CC3000 enabled devices. It's available under the Apache License, Version 2.0 from GitHub here:

https://github.com/george-hawkins/betaengine

It's also available as a ready to go precompiled binary package here:

https://github.com/george-hawkins/betaengine/releases

Just download the zip file and follow the instructions in the included README.txt file.

Among other things it consists of two executable jar files. You must first run the one called repackage.jar to repackage the included TI Smart Config library into a useable form. This only needs to be done once. Then you can run the main executable jar called net.betaengine.smartconfig-ui.jar.

This is covered in more detail in the README.txt.

The TI Smart Config library depends on Java 7 or later. The README.txt describes you how you can check your Java version. If you don't have Java 7 you should download a suitable JRE or if you plan to develop applications, in addition to just running them, you should instead download a suitable JDK.

This application may not be able to successfully transmit the SSID etc. to a CC3000 if the machine that you're running it on is connected to your wireless access point using 802.11n. If you're using 802.11b or 802.11g then it always seems to work - however if you are using 802.11n then whether it works or not depends on factors that I have yet to determine. If you are using 802.11n then please add a comment and tell me whether it works for you and what setup you're using. See this blog post to determine which 802.11 protocol (b, g or n) you are using:

http://depletionregion.blogspot.ch/2013/09/determining-80211-protocol-b-g-or-n.html

Update Sept 8th 2013: I now believe the main issue as to whether a particular client using 802.11n will work or not is MIMO. This is covered as one of the issues in the limitations section of this TI document. I've covered this in more detail in another post.

The image up above shows how the application looks on Mac OS X, here's how it looks on Ubuntu 12.04 and Windows 8:

More Details

TI provide reference implementations of Smart Config setup applications for iOS, Android and Java here:

http://www.ti.com/tool/smartconfig

However the Java implementation is a signed applet. I'm a Java developer and even I'm amazed whenever I see something shipping as a Java applet. They often fail to work for various reasons that are non-obvious to the end user, even more so when signing is involved. And even Java fans tend to disable the Java browser plugin due to the numerous security issues that it has experienced (note that this is a web-meets-Java-meets-browser issue and not a fundamental Java issue as is sometimes incorrectly claimed).

So I thought it would be nice to have a standard desktop application implementation. I extracted the TI SmartConfig library from version 1.1 of SMARTCONFIG-JAVA. It is covered by the TI Commercial License and the right to redistribute it is established here:

http://e2e.ti.com/support/low_power_rf/f/851/p/286323/1001377.aspx

I've taken the library and added a Swing UI and other features. In later posts I will discuss reimplementing the TI library to provide a completely open source solution.

The TI implementation only provides support for automatically retrieving the network name etc. for Linux and Windows. I've added support for Mac and fixed an issue where the TI logic would fail to determine the wifi frequency on some versions of Linux (e.g. Ubuntu 12.04).

As the TI library comes it is not actually useable as a library by third parties. All the classes it provides are in the default package and so cannot be called from other packages:

http://stackoverflow.com/a/283828/245602

This means you can only use these classes from other classes that are also in the default package. However as the TI library is signed even this is not possible as if some classes in a given package are signed then all classes in that package must be signed by the same signer. As TI have signed their classes in the default package you cannot add further classes in the default package unless you can also sign them as you were TI.

So I used JarJar to move the TI classes out of the default package and given them a sensible package name, i.e. "com.ti.smartconfig". If you download the binary distribution above you will find that it comes with the unmodified TI Smart Config library and the executable jar repackage.jar which the end user can run to automatically do the necessary repackaging. I did this as TI grant the right to redistribute their library but such rights rarely extend to redistributing modified versions of the original, e.g. I presume Microsoft would complain if one tried to sell modified versions of Windows even if one had acquired a suitable number of licenses for the original product.

If you download the source for my project from GitHub the README.md in the top level directory describes how to repackage the TI library in the normal JarJar command line fashion rather than using my repackage logic (which also calls JarJar do all the real work).

A side affect of moving the classes into a properly named package is to cause them to become unsigned. However signing was only necessary for the applet environment in order to gain the increased privileges needed to perform network operations etc. In a normal application environment this is not relevant.

The source for my code can be cloned from GitHub like so:

$ git clone https://github.com/george-hawkins/betaengine.git betaengine

Or if you don't have git you can download the contents of the repository as a zip file here.

All my classes can be found in the package net.betaengine.smartconfig or one of it's subpackages. There's nothing too surprising in the code. I don't like the TI API so I've created a package called tisupport where the few classes of mine that have direct dependencies on TI classes go, these and my interface DesktopSmartConfig isolate the rest of my code base from the TI API.

It should be relatively easy to localize this application for other languages (though I haven't taken care to handle more complex issues like right-to-left scripts). All the text is accessed through a resource bundle called TextBundle. Currently I've only provided a US English TextBundle.properties file.

Note: the wifi image used in the main panel is public domain and comes from openclipart.org.

Reimplementing the TI library in open source

As mentioned above the interface DesktopSmartConfig isolates the TI library from the rest of the code.

In the next few days I will be discussing exactly what the TI library does but not how it does it. I.e. I will provide the requirements needed to do a clean room reimplementation of the TI library, along with tools to test the resulting implementation.

It will be easy to develop a completely open source implementation of this interface. If you take a look at the interface you can see that it's not too complicated. Much of the code in the TI library revolves around platform specific logic for Windows and Linux to retrieve the SSID, wifi network device name, the default gateway address and the current wifi frequency being used. A very small amount of the code is involved in encoding the SSID and passphrase (and optionally encrypting the passphrase with an AES key) and transmitting this information such that a CC3000 enabled device can pick it up, and an even smaller amount of code is involved in waiting for an indication that the device has successfully connected to the network.

In the class net.betaengine.smartconfig.desktop.tisupport.MacNetServices that I wrote for Mac OS X you can see how I retrieved the SSID and other required information. Anyone with any reasonable networking experience should have little trouble doing the same for Windows and Linux with just a little Googling, i.e. they can easily duplicate the logic in the TI library without looking at how TI did things.

I've already discussed how one can detect that a CC3000 enabled device has successfully connected to the network here:

http://depletionregion.blogspot.ch/2013/10/cc3000-advertises-presence-on-network.html

And in following posts I will discuss how the SSID and passphrase are encoded and transmitted.