Here's some notes on my initial experience setting up the Neo Freerunner. I've been meaning to write this post for a while now and most of this is already old stuff but I'm posting it anyhow for reference. I purchased the Neo Freerunner fully aware that it was a developer phone but my hope was that I could at least ssh into the device and make/receive a few phone calls. I'm happy to report that after first booting I was able to get most things functioning within a few hours.

First Boot

There's several distributions for the Freerunner which can get quite confusing but the one that comes stock with the Freerunner is referred to as 2007.2. First time booting up the Freerunner you're presented the home screen for 2007.2. You can also boot into NAND and NOR flash which allows you to update the kernel, root filesystem and the boot loader (U-Boot).

My first mission was to ssh into the device. Followed the instructions on the wiki for setting up USB networking. By default the IP address of the Freerunner is 192.168.0.202. On the desktop side you first have to ifconfig the usb0 interface and setup the correct routes. Here's the script I run on my desktop after connecting the Freerunner:

#!/bin/bash

/sbin/ifconfig usb0 192.168.0.200 netmask 255.255.255.0
/sbin/route add -host 192.168.0.202/32 dev usb0

One extra step I had to do was configure my firewall to allow connections to/from usb0. I'm running Ubuntu hardy 8.04 and using Firestarter. Open up Firestarter:

• Preferences -> Firewall -> Network Settings
• Set 'Local network connected device' to: Unknown device (usb0)
• Check 'Enable internet connection sharing'

Verified usb0 network connections:

$ ping -I usb0 192.168.0.202
$ ssh root@192.168.0.202

Once connected to the Freerunner next step was to get the date to display on the home screen. To do this I just followed the instructions on the wiki for customizing the today page (run these commands on the Neo):

# dbus-launch gconftool-2 -t boolean -s /desktop/poky/interface/reduced false
# /etc/init.d/xserver-nodm restart

Here's a screenshot of the home screen:

Upgrade Software

Once I was able to successfully ssh into the Neo and verifed that I could also connect to the internet from the Neo I wanted to upgrade to the latest software release. To do this you use opgk (package management system based on Ipkg). The first time you upgrade from the software release shipped with the Neo you have to first upgrade dropbear (ssh server) from the terminal on the Neo, then you can ssh back into the Neo and upgrade the rest of the software:

# opkg update
On the Neo, open Terminal and run: # opkg install dropbear
Then ssh to neo and run: # opkg upgrade

At this point I rebooted and inserted my T-Mobile sim card and microSD card. Once back at the home screen it showed I was registered to the T-Mobile network and I opened up the dialer app and placed my first call!

Set up Timezone and correct date/time

To fix the timezone run this from the Neo:

# opkg install tzdata tzdata-americas
# ln -sf /usr/share/zoneinfo/America/New_York /etc/localtime
# /etc/init.d/xserver-nodm restart

To set the correct time using ntp run:

# opkg install ntpclient
# ntpclient -s -h pool.ntp.org
# hwclock --systohc

WLAN

Next up was connecting the Neo to my wireless LAN. The wireless interface on the Neo is eth0. First have to make sure WLAN device is turned on which it seemed to be by default when you first boot. You can check this by holding down the power button for a few seconds which should pop up a menu showing the state of the various devices. Here's the script I use to connect the Neo to my WLAN:

#!/bin/sh

/sbin/ifconfig eth0 down
/sbin/ifconfig eth0 up
/sbin/iwconfig eth0 key restricted 'xxxxx'
/sbin/iwconfig eth0 essid 'xxxx'
/sbin/udhcpc eth0

GPS

tangoGPS rocks. This app is amazing and it worked right out of the box. Followed the directions on the wiki to get it up and running. There was an issue getting a fix with the SD card installed but by the time I tried this out they already had a kernel update which fixed the issue. I had no problem getting a fix and my TTFF was 35s with the SD card in. Here's some screenshots of tangoGPS in action:

I also installed and ran AGPS Test which is a program for testing out GPS on the Neo. It shows some nice graphs of the various satellites you're currently connected to and their signal strengths:

Bugs/Issues

Overall I was impressed by how much I was able to get working the first time around however there's definitely a few issues I came across. The most concerning was the GSM buzzing during phone calls. On the Neo side everything sounds fine but the person on the other end hears a very loud buzzing noise. Here's the latest update from the hardware list regarding the issue. I tried tweaking the various alsa settings in /usr/share/openmoko/scenarios/gsmhandset.state with some luck but still wasn't able to find the right balance to completely eliminate the buzzing. Still trying to wrap my head around which alsa settings do what but I found playing with alsamixer during a live call to be helpful. The basic procedure goes something like this:

1. ssh to FreeRunner
2. Make a phone call
3. While call is in progress run alsamixer
4. Tweak settings to minimize buzzing/echo
5. While call is still in progress run: $ alsactl store -f gsmhandset-test1.txt

Now you can diff this new file against the original (/usr/share/openmoko/scenarios/gsmhandset.state) and see which settings were changed. This is really the only thing holding me back from using the Neo as my primary phone so I look forward to a possible fix.

I found using the Terminal on the Neo rather clunky due to the lack of characters available on the keyboard. For example there's no <TAB> or '/'. I'm sure there's ways to customize the keyboard. Looks like only vi is available by default on the Neo so I plan on seeing if I can find a vim package (.ipk) or figuring out how to compile vim for the Neo.

Open. Mobile. Free. That was the tag line printed on the side of the box which housed my shiny new Neo FreeRunner. I finally had some time to sit down and play with this new device and so far it's blown me away. If you're a Linux geek and haven't checked this out yet I highly recommend getting one. It's a truly open platform with a thriving community and is supported by a company which has basically open sourced their internal development. Where else could you get the complete CAD files for your phone? There's a good post about why you might think twice before buying an iPhone and picking up a FreeRunner instead.

Here's a few pics of what the Neo looks like all boxed up..

The Neo came bundled with a USB cable, a nifty stylus + laser pen, AC adapter, battery, and a 512mb microSD card.

The hardware specs for the Neo (GTA02) are impressive, GSM, WiFi, Bluetooth, GPS. All that packed into a full blown Linux distro that fits in the palm of your hand.

I'll be posting more about my experiences using the Neo as my daily phone. More to come..

After wrestling with Maven assemblies for while I finally figured out how to build executable jars. The Maven assembly plugin allows you to define ways to package up your project for distribution by creating various assembly descriptor files. Here's a quick example of a Maven assembly for building an executable jar (uberjar). For this example we'll create a brand new project from scratch but it should be easy to see how to integrate into an existing project.

First step lets create a test project:

Next add a few dependencies to the project. In this example we'll add a few libraries from jakarta commons. The <dependencies/> section in the pom.xml should now look like this:

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>commons-cli</groupId>
      <artifactId>commons-cli</artifactId>
      <version>1.1</version>
    </dependency>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <version>2.3</version>
    </dependency>
  </dependencies>

Create a META-INF/ directory to store the MANIFEST.MF file which defines the main class in the executable jar.

Create a src/assemble directory to store the assembly descriptor files

Next we'll create the actual assembly descriptor file which defines how to package up the jar. Create the file src/assemble/exe.xml with the following xml:

<assembly>
  <id>exe</id>
  <formats>
    <format>jar</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <dependencySets>
    <dependencySet>
      <outputDirectory></outputDirectory>
      <outputFileNameMapping></outputFileNameMapping>
      <unpack>true</unpack>
      <scope>runtime</scope>
      <includes>
        <include>commons-lang:commons-lang</include>
        <include>commons-cli:commons-cli</include>
      </includes>
    </dependencySet>
  </dependencySets>
  <fileSets>
    <fileSet>
      <directory>target/classes</directory>
      <outputDirectory></outputDirectory>
    </fileSet>
  </fileSets>
</assembly>

Inside the <dependecySets/> is where you can add all the libraries you'd like to include in the uberjar. These must also be defined in your pom.

Finally, add the maven-assembly-plugin to the pom:

  <build>
    <finalName>hello-world</finalName>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <configuration>
          <descriptors>
            <descriptor>src/assemble/exe.xml</descriptor>
          </descriptors>
          <archive>
            <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>

To run the assembly and build the executable jar:

I tested the hello-world example using the latest Maven release (2.0.8) and maven-assembly-plugin-2.2-beta-1. If you run into any issues try and update your Maven plugins by running:

You can download the example hello-world project here.

In this post I'm going to give a quick how-to on creating database schemas with a wonderful tool called Dia. I've often found having a nice visual representation of a database to be quite helpful but can't stand keeping it up to date. As soon as you add a new column or change the design around you end up having to sync your visual diagram with your SQL files. It's tedious having to manage the various SQL for building the database and this can be a larger pain when trying to support different database platforms each with their own SQL syntax. So before you create your next database read on and see how Dia can make your life a bit easier.

Dia is a program for creating diagrams and for this exercise we'll be creating UML diagrams from within Dia. We're also going to use a perl script called tedia2sql which will transform our Dia files directly to SQL for our target database. What's also nice about creating database schemas this way is that you can generate SQL for multiple target databases without the maintenance overhead.

First off, install a copy of Dia as well as tedia2sql. You can download tedia2sql here and download Dia here. I'm not going to cover the install in this post but there should be packages available for most Linux distro's and if your not running Linux now is a great time to start!

Fire up Dia, create a new diagram and save it as "employee.dia". Select the UML sheet from the drop down list. We'll be using various UML objects to represent tables and definitions that make up our database. Here's a quick overview of the main UML objects and their usage:

Class represents a table in the database. A Class has a name which corresponds to the name of the table and attributes which map to the columns of the table. Attributes in classes can have visibility (public, private, protected). Protected attributes are primary keys. More on classes later. Component is a special object that lets you define a list of default values to be inserted into a table. These are equivalent to hard coding "insert into .." statements in your SQL files. Small Package represents a typemap. Typemaps are used for adding custom SQL types such as MySQL tinyint.

Now lets create our first table. Select the "Class" object icon from the UML sheet and click inside the diagram editor window. This will add the class to your diagram. Now right click on the new class and select "Show Properties". This will bring up a rather large and complex property window for the UML class you've just created. We're only going to customize a few properties outlined below.

First, under the "Class" tab enter the name of the table (employee) in the "Class Name: " field. Next click on the "Attributes" tab and enter in the columns of the table as attributes. In the "Name: " field enter in the column name. In the "Type: " field enter in the SQL type for the column. If you want to support multiple database platforms try to be generic here and only use ANSI SQL 1992 or else use a typemap. More on typemaps later. In the "Value: " field enter any default values for the column. For example, this is where you could add in "not null". If the column your adding is a primary key then don't put "not null" here and instead select "Protected" for the "Visibility: " field. Not null will automatically get added to all primary keys on output generation. The screen shot below is an example of the Class property editor window.

Next, repeat the process for as many tables as you need in your database. For this example, create two tables "employee" and "department" with the columns as shown in the screenshot below (note the '#' in front of an attribute indicates that it's visibility is "Protected" thus making it a Primary Key):

This is a simple example of a database which stores employee data along with the department they belong to. Now suppose we have a default list of departments that we'd like to load into the department table when our database is created. To do this we'll use the "Component" object from the UML sheet. Select the "Component" object and add it to your diagram editor window. Right click and select "Properties".

In the "Stereotype: " field you basically enter in the first part of an "insert into .." SQL statement. For this example, to insert a default list of departments we'd normally write the following SQL:

insert into department (department_id, name) values (1, 'Marketing');
insert into department (department_id, name) values (2, 'Production');
insert into department (department_id, name) values (3, 'Design');

So in this case, for the "Stereotype: " field we'd enter in "department (department_id, name)". Click OK to close the properties dialog. Now in the Component object box enter in the values you'd like to insert, one per line. Here's what our diagram should look like now:

Now lets add in a typemap. Typemaps are used for when you'd like to configure custom types which are specific to a database platform. A good example of this is MySQL auto_increment. This is a feature specific to MySQL and not supported in all databases. Lets suppose we'd like to have a primary key column which gets auto incremented upon each insert. But we also want to support both MySQL and Apache Derby without having to maintain separate SQL files. To achieve this we'll create a custom typemap and define the specific SQL for each target db.

Typemaps are created using a Small Package so select the "Small Package" object and add it to your diagram editor window. Right click and select "Properties".

In the "Stereotype: " field you enter in the target database. So for example "mysql: typemap". For a list of supported target databases see tedia2sql --help. Some common ones are: postgres, mysql, sybase, oracle, db2, and innodb. Click OK to close the properties dialog. Now inside the Small package box you can enter custom types one per line. For this example we'll create a custom type with a name of "identity". This means that when we generate our SQL files, tedia2sql will replace the column type with our custom type. Here's a few examples:

identity: int unsigned auto_increment
bigid: bigint unsigned auto_increment

identity: int generated by default as identity
bigid: long generated by default as identity

Repeat the process for Apache Derby using "db2: typemap". Now that we've defined our custom identity typemap we can change the employee_id column from type "int" to type "identity". We can also do the same for our department table. Now these columns will be auto incrementing columns and depending on which target database we select on output the correct SQL will be generated. Our diagram should now look like this:

At this point we have created our database schema and defined a default list of departments to be inserted. We also created a typemap called "identity" which defines auto incrementing columns for both MySQL and Apache derby. Now lets generate the SQL files to create the database using tedia2sql. Before we run tedia2sql we need to apply a small patch to the tedia2sql script. This fixes a very small formatting issue in tedia2sql related to the typemaps we created. Edit the tedia2sql script (/usr/bin/tedia2sql) and comment out the line inside the parseTypeMap(..) subroutine that looks like this:

$defStr =~ s/s//g; # ignore spaces
     -- change to --
#   $defStr =~ s/s//g; # ignore spaces

or just apply the patch I created here (works for version 1.2.12):

$ patch /usr/bin/tedia2sql < tedia2sql-typemap-1.2.12.patch

Now we can generate the SQL files for our target databases:

$ tedia2sql -i employee.dia -o employee-mysql.sql -t mysql -d
$ tedia2sql -i employee.dia -o employee-derby.sql -t db2 -d

This will generate two SQL files for building the database in both MySQL and Apache derby. If you view these files you can see how tedia2sql handled our typemaps for the auto incrementing columns in each target database:

MySQL

-- employee
create table employee (
  employee_id                int unsigned auto_increment not null,
  department_id             int not null,
  first_name                varchar(255) not null,
  last_name                 varchar(255),
  start_date                date,
  constraint pk_Employee primary key (employee_id)
) ;

Apache Derby

-- employee
create table employee (
  employee_id                int generated by default as identity  not null,
  department_id             int not null,
  first_name                varchar(255) not null,
  last_name                 varchar(255),
  start_date                date,
  constraint pk_Employee primary key (employee_id)
) ;

You can download the files generated as well as the employee.dia file I used in this tutorial here:

• employee.dia
• employee-mysql.sql
• employee-derby.sql

You can test the SQL files generated by tedia2sql and create the employee database as follows:

MySQL

$ mysql -u user -p dbname < employee-mysql.sql

Apache Derby

$ java -cp derby.jar:derbytools.jar \
       -Dderby.system.home=/path/to/dbroot \
       -Dij.protocol=jdbc:derby: \
       -Dij.database='employee;create=true'
    org.apache.derby.tools.ij employee-derby.sql

A quick Makefile will help out a lot in testing out your database schema:

all:
      tedia2sql -i employee.dia -o employee-mysql.sql -t mysql -d
      tedia2sql -i employee.dia -o employee-derby.sql -t db2 -d
clean:
      rm -f *.sql

I've found that for small to moderate size projects creating database schemas in Dia and using tedia2sql for SQL generation to be a lifesaver. You can also make use of Dia's export feature to export your database schema to a number of different formats such as jpg, png, eps, tiff, etc. I really only scratched the surface of what can be done using these great tools. tedia2sql has support for lots of cool features like indexes, foreign key constraints, views and much more. For more information check out using tedia2sql and Dia's manual.

Happy Diagramming!