Geo Location Messaging

1. Overview

1.1. Concept

The Geo Location Messaging enabler consists of a server part and a client part. Its purpose is to enable an application to send messages to registered and subscribed clients that are present in a certain geographic area. This area is specified along with the message when using the server-side interface. The shape of this area may be a circle, an ellipse, a rectangle or a (convex) polygon (currently with the limitation to 20 points). In the following text, this kind of messaging will be referred to as "geocast" (in the style of "broadcast" or "multicast").

Different applications using the API are distinguished by a service ID that the clients subscribe to. When registering for an API key, you have to specify a domain parameter like http://<your.service.domain>. This domain parameter spans a namespace for the service IDs you are allowed to use. Two different formats are supported for the service ID:

• <your.service.domain>/<your.service.name>
• <your.service.name>@<your.service.domain>

The Geo Location Messaging enabler currently employs a server instance per country and you have to configure the correct communication parameters for your country. For the list of supported countries, see Server Configurations. In case your country is not listed, you may indicate interest to the Labs team. In future, we may extend the enabler add an API function to retrieve the communication parameters based on your location.

1.2. Server-Side

In the network, the Geo Location Messaging Server offers an HTTP interface that can be used by a service to send out geocast messages and to receive anonymous uplink messages from its clients. For sending out geocast messages, the server expects an HTTP POST request on resource /geocast. In order to receive uplink messages from clients, the server expects an HTTP GET request on resource /receive.

The HTTP GET request is handled in a long poll manner and answered with an HTTP OK and empty body after a timeout period of 30 seconds if no uplink message is received. The service should keep the connection and issue a new receive request. Pipelining up to 10 requests is supported. In case an uplink message is received, it is returned as body of an HTTP OK reply.

Along with the HTTP requests specific parameters must be provided as HTTP headers. For both request types, GET and POST, the "Geocast-ServiceID:" and "Geocast-Labskey:" headers are required. To post a geocast message, the target area has to be included additionally with the "Geocast-Destination:" header. The successful reply to a geocast message contains the number of targets addressed and a small profile statistic in JSON format and looks like as follows:

{ "targets":0, "profile":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0] }

The "Geocast-Destination:" header contains the target area in JSON format. Supported shapes are "circle", "elipse", "rect", "polygon" and "all". Coordinates are WGS84 and a radius is given in km. A rectangle contains the North-East and South-West corner. Take a look at the following examples:

{ "shape":"all" }
 
{ "shape":"circle", "lng": 6.078186, "lat": 50.772944, "radius": 9.667 }
 
{ "shape":"elipse", "lng": 6.079559, "lat": 50.772944, "rlng": 14.501, "rlat": 4.836 }
 
{ "shape":"rect", "wgs84": [ { "lat": 50.745145, "lng": 5.995788 }, { "lat": 50.788574, "lng": 6.201782 } ] }
 
{ "shape":"polygon", "wgs84": [ { "lat": 50.801595, "lng": 6.091918}, { "lat": 50.747752, "lng": 6.133117 }, { "lat": 50.752097, "lng": 6.052093 } ] }

If the server cannot evaluate the target area, it replies with an HTTP OK and textual problem indication in the reply body. An unsuccessful HTTP reply indicates either connectivity problems or unsuccessful developer key evaluation. The command line tool curl can easily be used to script and test this interface.

1.3. Client-Side

On the client side, the Geo Location Messaging App (currently Android only) offers a similar HTTP interface that can be used by a service app to send uplink messages to the network and to receive geocast messages from the network. For sending uplink messages, the App expects an HTTP POST request on resource /uplink. In order to receive geocast messages from the network, the App expects an HTTP GET request on resource/receive.

The HTTP GET request is handled in a long poll manner and answered with an HTTP OK and empty body after a timeout period of 30 seconds, if no geocast message was received. The service should keep the connection and issue a new receive request. Pipelining up to 10 requests is supported. In case a geocast message was received it is returned as body of an HTTP OK reply. Along with the HTTP requests a specific parameter must be provided as HTTP header. For both request types, GET and POST, the "Geocast-ServiceID:" headers is required. All HTTP requests on the client side are expected on localhost and default port 8070. This port is configurable by App preference "Local Client Port". Notice: On Android the IPv6 address of localhost, [::1], is used.

2. Server API

A back end using the Geo Location Messaging server side API needs HTTP capabilities to be able to communicate with the Enabler. A library written in Java Standard Edition acts as an abstraction layer to provide a third party developer with simple methods to communicate with the Geo Location Messaging Enabler. The following table summarizes the methods and constructor of the API.

The constructor GeocastConnector is used to initialize the service and establish a receive connection to the Geo Location Messaging server. An application using this server side API can create multiple instances of GeocastConnector with one or several service IDs. If the service does not need to receive uplink messages, it should call the connector's stop() method. To actually receive uplink messages the service can either use the receive() or poll() method which will return one message at a time. The getError() method can be used to monitor any error on the receive connection. The send() method is used to post a geocast message to an individual target area. The following code sample illustrates the use of the API.

package com.ericsson.glmserverhello;
 
import com.ericsson.geocastconnector.GeocastConnector;
 
public class SimpleServerTest {
 
	final static String labskey     = "<your personal developer key goes here>";
	final static String serviceID   = "ericsson.net/hello";        // change to your needs
	final static String serviceHost = "<a href="http://glm.labs.ericsson.net:8070";">http://glm.labs.ericsson.net:8070";</a>  // change to your needs
 
	GeocastConnector enabler;
 
	Thread receiver = new Thread (new Runnable () {
		public void run() {
			while (true) {
				byte[] message = null;
				try  { message = enabler.receive(); }
				catch (Exception e) {}
				if (message == null) break;
				System.out.println("Received Geomessage: " + new String(message));
			}
		}
	});
 
	Thread monitor = new Thread (new Runnable () {
		public void run() {
			while (true) {
				String error = null;
				try  { error = enabler.getError(); }
				catch (Exception e) {}
				if (error == null) break;
				System.out.println("Receive error: " + error);
			}
		}
	});
 
	public SimpleServerTest () {
		try   { enabler = new GeocastConnector (serviceID, serviceHost, labskey); }
		catch (MalformedURLException e) { e.printStackTrace(); }
		receiver.start();
		monitor.start();
	}
 
	public void send (String message) {
		final String destination = "{ \"shape\":\"all\" }";
		System.out.println("Geocast result: " + enabler.send(message.getBytes(), destination));
	}
 
	public static void main (String[] args) {
		SimpleServerTest hello = new SimpleServerTest ();
		hello.send ("Hello World!");
		Thread.sleep (60000); // wait one minute for uplink messages
		hello.stop();
	}
 
}

3. Client API

An application client using the Geo Location Messaging client side API needs HTTP capabilities to be able to communicate with the Enabler. A library written in Java Standard Edition acts as an abstraction layer to provide a third party developer with simple methods to communicate with the Geo Location Messaging Enabler. The GeocastConnector class is very similar to the server side implementation. Only the constructor and send method are different. The following table summarizes the methods and constructor of the API.

The constructor GeocastConnector is used to initialize the service and establish a receive connection to the Geo Location Messaging client. One or more client applications using this client side API can create multiple instances of GeocastConnector with one or several service IDs. If the service does not need to receive geocast messages, it is not recommended to call the connector's stop() method; instead geocast messages should be received in vain. To actually receive geocast messages the service can either use the receive() or poll() method which will return one message at a time. The getError() method can be used to monitor any error on the receive connection. The send() method is used to post an uplink message to an individual target area. The following code sample illustrates the use of the API.

package com.ericsson.glmclienthello;
 
import com.ericsson.geocastconnector.GeocastConnector;
 
public class SimpleClientTest {
 
	final static String serviceID = "ericsson.net/hello";        // change to your needs
	final static int port = 8070;  // default client local HTTP port
 
	GeocastConnector enabler;
 
	Thread receiver = new Thread (new Runnable () {
		public void run() {
			while (true) {
				byte[] message = null;
				try  { message = enabler.receive(); }
				catch (Exception e) {}
				if (message == null) break;
				System.out.println("Received Geomessage: " + new String(message));
			}
		}
	});
 
	Thread monitor = new Thread (new Runnable () {
		public void run() {
			while (true) {
				String error = null;
				try  { error = enabler.getError(); }
				catch (Exception e) {}
				if (error == null) break;
				System.out.println("Receive error: " + error);
			}
		}
	});
 
	public SimpleClientTest () {
		try   { enabler = new GeocastConnector (serviceID, port); }
		catch (MalformedURLException e) { e.printStackTrace(); }
		receiver.start();
		monitor.start();
	}
 
	public void uplink (String message) {
		System.out.println("Geocast result: " + enabler.send(message.getBytes()));
	}
 
	public static void main (String[] args) {
		SimpleClientTest hello = new SimpleClientTest ();
		hello.uplink ("Hello World!");
		Thread.sleep (60000); // wait one minute for geocast messages
		hello.stop();
	}
 
}

4. Tutorial

4.1. Before You Start

Before you start with the tutorial, make sure you have done the following.

• Choose your service domain name
• Request a developer key (have your service domain name ready)
• Download and install the Geo Location Messaging app for Android onto your device
• Download the GLM Sample Client source code or if you don't want to build, install the APK file
• Download the GLM Sample Backend source code
• Prepare an Android development environment for the GLM Sample Client (eclipse recommended)
• Prepare an JavaSE development environment for the GLM Sample Backend (eclipse recommended)

4.2. The GLM Sample Backend

To try the example yourself, import the JavaSE project into your eclipse environment. In file MainForm.java fill in your developer key, change the serviceID variable to your registered service domain name and alter the port number in serviceHost to the port number for your country, see Server Configurations.

public class MainForm {
	final static String labskey     = "<your personal developer key goes here>";
	final static String serviceID   = "ericsson.net/hello";        // change to your needs
	final static String serviceHost = "<a href="http://glm.labs.ericsson.net:8070";">http://glm.labs.ericsson.net:8070";</a>  // change to your needs
	...
}

When you run the GLM Sample Backend application, it connects to the server and establishes a "receive" connection and displays any received uplink message in the Inbox. If you select a message in the Inbox the complete content is shown in the Read message section. The sample application only uses plain text messages whereas the Geo Location Messaging enabler itself is transparent for the payload which may also be binary. When you first run the backend sample you should not see any message being received. If you do, there is an error with connecting to the server, authorizing your developer key or a service domain name mismatch.

If you click Compose Geomessage, a new window opens and you first click Set target area. On the opening map you navigate to your location and select an appropriate target area for your message and click OK. Back in the previous window, you type in your message to send and click on Send. If your message is sent successfully, you will see the following result:

{ "targets":0, "profile":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0] }

This result means you have sucessfully sent the message to zero targets. The number of targets reached will later change when you have one or more clients attached to the system and roaming in the target area.

4.3. The GLM Sample Client

Before you try the GLM Sample Client, download and install the Geo Location Messaging app for Android onto your device. When you first run it, you have to accept the legal disclaimer in order to use your location. Thereafter, you are able to enable and disable the service by a checkbox preference. Alternatively, you can add a Geo Location Messaging Widget to your screen to enable and disable the service. A colored icon means Enabled and a gray-scale icon means Disabled service.

Only when the service is disabled can you change the other preferences. The GeoCast Server preference should be glm.labs.ericsson.net:7770 with the right port for your country, see Server Configurations. The GeoCast Local Port preference only needs to be changed if you want to use a specific local port number for outgoing connections to the server. The Local Client Port preference contains the default value 8070 and doesn't need to be changed. If you do change it, you have to use the same port in the GLM Sample Client.

The GLM Sample Client can be used now to test the Android client enabler. It provides an interface to set preferences and offers the possibility to send uplink messages. Either simply download and install the APK file or download the source code, import the Android project in your eclipse environment and run it on your device. In the Service Identifier preference, you have to use the same service ID as in your backend application. You do not need to change the default Local Client Port preference. When the service is enabled by the checkbox preference and you alter the Uplink Message preference, then this message is sent to the server and any connected backend application for configured service ID. Any received geocast message is displayed as a notification.

5. Server Configurations

The server hostname for all countries is glm.labs.ericsson.net. Currently we support United States of America, United Kingdom and Irleand, Germany, Sweden, Japan and Brazil.