8Motions blog

1) Introduction

In this two parts article, we will introduce mobile positioning with CellID, and the open source database of CellIDs: OpenCellID. We will see how to use it through a simple sample. The second part will demonstrate how to use OpenCellID with OpenStreeMap and the 8Motion library to create a full interactive mobile mapping experience in JavaME, each of these examples being less than 100 lines of code.

2) What is CellID

We all know that GPS will be deployed in the vast majority of phones in the future. But now, only a few high end handsets are GPS enabled.
An alternative, available since a long time, but gaining momentum recently is CellID based location. What is CellID? A CellID is the number given to a specific cell (the radio tower to which your handset is connected) . In most of the case, it’s the closest tower to your location. So by knowing this tower, you know where the user is. But a tower can cover a huge area: from a few hundred meters, in high density area, to several kilometers in lower density area. That’s why CellID accuracy is lower than GPS accuracy, but this present a very good alternative.

CellID has become recently more popular, mainly thanks to his nice integration into GoogleMap mobile.

3) OpenCellID

So this sounds great, let’s just get the phone cellID, so we will have his location. The issue is that the location of cells is not a public information. Operators keep this private, for many reasons:

• They don’t want to give tower location to their competitors
• They use this as an extra revenue income, as they provide paying services to retrieve cell location.

That’s why we have set up a service called “OpenCellID”. OpenCellID.org is an open source database of CellID, serving two purposes:

• Everybody can create an application gathering information about cell locations, and send these information to the OpenCellID server, improving the coverage
• The database can be used by other applications to get the location of a cell, according to his cell id.

How to use OpenCellID (http://www.opencellid.org/api )

The API is a simple REST api. There are only two relevant calls: measure/add and get/cell

measure/add to add a measure of cell. This is used to by application which wants to add information to the database. These application produce content for the OpenCellID database. To use it, you need to require a key to OpenCellID.org. The key is used to track applications providers, and ensure that no fake data are inserted into the system.

Examples:

http://www.opencellid.org/measure/add?key=myapikey&mnc=1&mcc=2&lac=200&cellid=234&lat=3.42&lon=3.12

Replace myKey with the key that you received while registering at OpenCellID. This will tell the serveur that a client found a cell of id 234, for mcc=1, mcc=2 and the position 3.42,3.12 …Be careful: all informations are in decimal, while some handsets (sonyericsson for instance) provides lac and cellid in hexa, so you will need to convert them before calling the API.

Cell/get is used to get the position associated with a cell. You just need to give mcc,mnc,cellid and optionnaly lac.

http://www.opencellid.org/cell/get?mcc=250&mnc=99&cellid=29513&lac=0

You need to provide at least mcc, mnc (mobile country code, and mobile network code of the operator), and cell id. Lac (location area code) is an optional parameter, and will help to find an alternate position if cell is not found.
In return, the API will return a simple XML, like this one:

<rsp stat=“ok”>
<cell lat=“57.8240013122559″ lac=“0″ lon=“28.00119972229″ mcc=“250″ nbsamples=“38″ range=“0″ cellid=“29513″ mnc=“99″>
</cell></rsp>
Lat and lon are the coordinate of the cell, based on 38 samples…

If needed, you can use the optional parameter “fmt” to specify an output format,:

http://www.opencellid.org/cell/get?mcc=250&mnc=99&cellid=29513&lac=0&fmt=txt

will return something like this:

57.8240013122559,28.00119972229,250,99,0,29513,100,38

Same informations than before, but in a much compact form (see the API description for a complete description).

Others API are under development, to retrieve operators from mcc/mnc for instance.

4) Sample program:

So let’s use OpenCellID to create a small program, written in JavaME, which will just get the CellID of the phone , do a request to the OpenCellID server and display the results.

First, let’s get the CellID:

We use SonyEricsson specific properties. There properties are non standard, and only available on some devices.

// These properties are implemented on latest SonyEricsson phone
// This does not work on others (Nokia, etc…)
String cellid=System.getProperty(“com.sonyericsson.net.cellid”);
String mcc  = System.getProperty(“com.sonyericsson.net.cmcc”);
String mnc  = System.getProperty(“com.sonyericsson.net.cmnc”);
String lac  = System.getProperty(“com.sonyericsson.net.lac”);

Cellid is of course the cell id, mcc is mobile country code, mnc is mobile network code and identify the operator and the country (cmcc stands for current mcc). That’s all we need to find our location.

Then, verify if theses properties are supported:

String info=“This phone does not support CellID”;
if(cellid!=null){
   info=“Cell:”+cellid+“ mcc:”+mcc+“ mnc:”+mnc+“ lac:”+lac;
   url=“http://www.opencellid.org/cell/get?cellid=”+Integer.parseInt(cellid,16)+
 “&mcc=”+mcc+“&mnc=”+mnc+“&lac=”+Integer.parseInt(lac,16)+“&fmt=txt”;
   cellInfo.setString(info);       
   Thread t=new Thread(this);
   t.start();
   posInfo.setString(“Requesting position…”);
}

In this part, we have created the URL to request information on the server, and start the fetch of the information in a separate thread:

public void run(){
 try {
   HttpConnection cnx = (HttpConnection)Connector.open(url);
   InputStream is=cnx.openInputStream();
   StringBuffer b=new StringBuffer();
   int car;
   while( (car=is.read())!= -1){
      b.append((char)car);
   }
   is.close();
   cnx.close();
   String res=b.toString();
   if(res.startsWith(“err”)){
      posInfo.setString(“Cell not found!”);
   }else{
      int pos=res.indexOf(‘,’);
      String lat=res.substring(0,pos);
      int pos2=res.indexOf(‘,’,pos+1);
      String lon=res.substring(pos+1,pos2);
      posInfo.setString(lat+“ “+lon);
   }
 } catch (IOException ex) {
   ex.printStackTrace();
   posInfo.setString(ex.toString());
 }
}

If the API call return something starting with err, we are probably in error. Otherwise, we will have our current cell id positioning.

And that’s done. The complete source code is available here.The compiled program is available here, with jad and jar.

So, what happens if the CellID is not in the database? Then the program will display an error. You can improve the accuracy of OpenCellID by discovering more cells. Check OpenCellID to know how to do it.

Next part will improve this first version, by creating an interactive program displaying the location on a map, using J2memap free component…

Ok, following some requests, here is another tutorial on how to use the J2memap library. First, note that if you just want to display a KML file on mobile, you can use 8Motions directly, no need to create your own application.

Anyway, here we are going to show you how to create a very simple app that display a KML file on a cell phone. First, download the J2memap library (you need to be registered to download it), and put thelibraryCLDC11.jar (or 10.jar) as a library of your project. In netbeans, you do Properties,add jar/zip,select the jar file.

Here I take a KML file, but it could be also a GPX file, LOC or GEORSS file….

Then, here is the code:

package com.eightmotions.LoadTrack;
import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
import com.eightmotions.util.*;
import com.eightmotions.map.*;
/**
 *
 * @author tlandspurg
 * @version
 */
public class LoadTrack extends MIDlet implements TrackNotifier {

    MapCanvas m_map;
    Display m_display;
    public void startApp() {
        UtilMidp.checkMIDP(this); //Initialise the utility library…

        // Initialize the map, get the display, and put the map on it
        m_map=new MapCanvas();
        m_display=Display.getDisplay(this);
        m_display.setCurrent(m_map);     

        // Load a track, and display this track to a map
        Track track=Track.getTrack(m_display,“http://www.8motions.com/map/showKml/107″,“Loading Track”,m_map);
        // Listen for track loaded event…
        track.setNotifier(this);
    }

    public void pauseApp() { }

    public void destroyApp(boolean unconditional) {   }

    /* When the track has been loaded, display it… */
    public void onTrackLoaded(Track tr) {
        m_map.displayTrack(tr,true);
    }

    public void onTrackCreated(Track t) { };

    public void onTrackSaved(Track t) {};
}

Here is the result:

One of the most interesting feature of 8Motions, is the ability to view a KML file on mobile. Here is a step by step to help you to do so.

Here is how.

So, lest use this KML sample, created using MyMaps from Google:

(you can see this page using this direct link ).
The KML link is link under the “show in google earh” button

You have two options:

First option:

You just want to see one single track, and are ready to type this URL on your mobile. Then start 8Motions (you can download it at http://www.8motions.com or directly from your mobile at http://www.8motions.com/m ) and go to “track” -> options -> import -> from internet and then put the URL of the KML file you want to import.

Here is the result on 8Motions:

 Note that if you use GoogleMyMaps, the URL can be sometime very long, like this: http://maps.google.com/maps/ms?ie=UTF8&hl=fr&msa=0&output=nl&msid=100794107530973749779.000434a046c54077b3580 and hard to type. You can use a service like tinyurl ( http://tinyurl.com ) to transform it into a shorter link, this one in that case: http://tinyurl.com/34k738

Other option, if you want ot manage several track: put then as “Mapz” in your account:

First, go to 8motions and create your account (http://www.8motions.com).
Go to “Mapz”, then, “create a new mapz”,

Then, put the name of your maps, like “My first KML file ” and in the field “url if it’s a KML file” just put the URL of the KML file and press apply once it’s ok. You can eventually add extra info, like a specific icon to be displayed on mobile or to setup a public/private flag. A public mapz will be visible by everybody (but can not be changed by them) while a private will be only visible by you.

Then, if you go to the “Mapz” menu of your 8Motion mobile client, you will see the newly created mapz.

You can create as many mapz as you want…

Note: do not forget to set up your username/password on mobile if you want to be synched with your web account.

Just a short reminder, about what is supported as type of file for j2memap (both the library and the program):

- .loc

Used by geocaching application

- .gpx

Used by many gps related program. A subset of GPX1.1 is available, mainly include support for waypoint, trackpoint, track, ….

- .kml

Google Earth format (and used by many mapping application).

viewformat
viewrefreshmode
name
styleurl
style
iconstyle
color
coordinates

and a few others

- geoRSS

The following geoRSS tag are supported:
geo:lat
geo:long
georss:point
georss:line

(note that pubdate ,title and description are displayed)

- Others XML variant

As I’ve made a lot of interconnection with various XML providers, there are much more tags supported, a few of them:
address  : the address of the point
tel         : telphone number (usefull, as you have the ability to call this number directly)
photoUrl

So it’s already an impressive list, that can help you to create or use some cool mashup.

Also, as a new features, if the description contains an img reference, this description is displayed as an icon,like this:

And remember, as you have the ability to load KML created by Google MyMaps, you just can load them directly, like this one:

Another example, with different markers:

Technorati Tags: j2memap, 8motions, kml, mobile, gmap, gmap mobile, gpx, mymaps, where

In the latest release of J2memap library, a new interface has been defined: MapCustomOverlay

If you create a class that implements MapCustomOverlay, you will have the ability to dsiplay new layers on top of an existing map.

The implementation is easy, there are two methods:

   String getTileURL(int x,int y,int z,int sizeSq,boolean isSat);

and

    public boolean isTransparent();

  The last one just have to return true if transparent, or false otherwhise. The getTitleUrl must return to URL of a tile to be loaded at the corresponding x,y positions. sizeSq is the size of a square, usually 256, while isSat is true if the user is currently displaying a satellite image.

  To convert x “pixels values” into longitude, you can use MapCanvas.LonFromX() and MapCanvas.LatFromY() for y value.
  To display this layer, call the setOverlay(MapCustomOverlay) function (with null parameter to remove it). Just one overlay can be displayed at a time.
  This can be used to easily create WMS overlay, if you know the URL of a WMS server.

  Latest question, is: great, but what happens if I do not want to program and I want to be able to display a custom layer? Well, something good is coming, but if you want to test it, just drop me an email

I will start a series of tutorial around J2memap as a powerful library to be used to display gelocalized content.

This first tutorial will focus on the easiest thing to do: display a map on a phone! With a few line of codes, you will have the equivalent of GoogleMap on your PC…

That’s quite easy. You can do this using Java Wireless Tool Kit. Create a new project (in that case “HelloMap“), give the midlet class name (in this example net.landspurg.test.HelloMap ). Just put the library (you need to contact me to get it) in the “libs” folder of this project.

The steps are pretty simple:

* intialize utilities:

UtilMidp.checkMidp(Midlet)

* Then, create a map canvas:

MapCanvas m_map=new MapCanvas();
m_map.init();


* Now, display it:

display.setDisplay(m_map);

Now, you have a fully fonctional GoogleMap/Yahoo/Ask.com/MSN Live interface, with scrolling, zooming, etc…

All these default behavior can be changed, will see this later on….

The complete source code is here:


/*
 * HelloMap.java
 *
 * Created on 11 janvier 2007, 20:10
 */

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
import net.landspurg.util.*;
import net.landspurg.map.*;
/**
 *
 * @author  tlandspurg
 * @version
 */
public class HelloMap extends MIDlet {
    MapCanvas m_map;
    public void startApp() {
                // DO NOT FORGET TO INITIALISE UtilMidp! contains some static function
                // used by MapCanvas….
                //
        UtilMidp.checkMIDP(this);  //Initialise the utility library…
        m_map=new MapCanvas();
         m_map.init();
                Display d=Display.getDisplay(this);
                d.setCurrent(m_map);
    }
   
    public void pauseApp() {
    }
   
    public void destroyApp(boolean unconditional) {
    }
}


Technorati Tags: j2memap, tutorial, java, googlemap, mobile