back to index

Prototype Application

The prototype application has been developed using the Java programming language, using the Android framework and Android runtime. It has been released as Open Source using version 3 of the GNU General Public License[1] (GPL). In keeping with the Open Source nature of the prototype application the source code is available on a public GitHub repository[2] where interested developers can download the source code and contribute changes if they so choose. It is planned that additional documentation, samples, and other information will be made available as development of the application progresses. It is intended that this thesis will contribute to the set of documents and information.

This chapter examines the prototype application, and considers the design of the application, the development of supporting applications, the users experience when using the application, the format of the network packets used by the application, and lastly the binary map file format used to render the map and cache data on the smartphone.

Design Considerations

As has been stated previously the main use case for the prototype application is to provide an environment that supports collaborative mapping on mobile devices during the response to a disaster or emergency event. It is this use case which has influenced the development of the application to date within the requirements of this exploratory research and the related constraints on time and resources. The primary use case also stipulates that the application must work in the absence of traditional telecommunications infrastructure, as in a disaster or emergency event this infrastructure may be unavailable due to damage or over subscription. For these reasons, the prototype application is designed be installed on a Android powered smartphone and used in conjunction with the main Serval Project software.

The main Serval Project software manages all aspects of the resilient Ad Hoc mesh network: it provides a list of peers to the prototype application, which it then uses to send location and incident packets as the mechanism to share information between instances of the prototype application running on smartphones that are part of the network. Currently the prototype application, uses the User Datagram Protocol (UDP) to send plain text packets. The path that these packets take through the network to reach the other network peers is dependent on the main Serval Project software and the way that it manages the network.

As each location and incident packet is sent as plain text, this has been identified as a security concern, as packets can be intercepted by unauthorised parties and potentially modified in transit, or sent and received by unauthorised applications. The plain text packet format was chosen as it made the initial development of the networking components of the prototype application easier, time and resources could then be spent on other aspects of development, such as gaining an understanding of the Android environment itself. A considerable amount of time and resources was spent on understanding how user interfaces are developed, and the way in which components of an Android application are constructed and managed by the Android framework and runtime. UDP was chosen as the transport for the packets as it is a much more efficient way of transferring small amounts of data, especially when the amount of data is limited to that which can be contained in only one packet. Lastly the use of a plain text packet format allowed for the construction of a number of supporting applications that were used during the initial development phases of the prototype application.

To address these security concerns, a future version of the prototype application will use the encryption functionality of the main Serval Project software which is currently under development, to encrypt the content of packets and ensure that packet content cannot be accessed by unauthorised users or applications. Additionally more advanced measures may be taken, for example using shared encryption keys so that a group of users who have access to the appropriate credentials can decrypt the packet, and the use of cryptographic hash in the content of the packet to ensure that the content is unchanged and was indeed originally sent by the specified user. The main benefit of using the main Serval Project software is that the resilient Ad Hoc mesh network allows the use of the prototype application without relying on traditional telecommunications infrastructure.

The one piece of infrastructure that the prototype application is reliant upon is the Global Positioning System (GPS), as this is the source of geographic information that specifies the location of the smartphone, and by extension the location of the user themselves. Geographic location information is requested using the standard methodology as outlined in the Android developer documentation[3]. Only information sourced from the GPS location provider is used as the other location providers are infrastructure dependent, for example using the cell-id of telecommunications infrastructure to determine an approximate location based on the triangulation of signals from a number of telecommunications towers.

A benefit of this approach is that a more accurate location can be determined using GPS, which has a direct positive influence on the accuracy of the information added to the map. The downside to this approach is that it can take a relatively long time to determine an initial location fix, in testing this was shown to be as much as 3 minutes in some cases depending on the GPS chipset used and environmental conditions. Additionally it was discovered using the GPS hardware exclusively increases the drain on the battery of the smartphone as it is necessary to keep the GPS hardware powered on during the time that the application is in use. Further testing needs to be carried out to determine the optimal model for managing the location requirements of the application.

The data used to construct the underlying map must also be stored on the device. In keeping with the requirement of infrastructure independence it is assumed that there is no reliable Internet connection to source map tiles from third party servers, for example those that power the native Google Maps capabilities. Therefore the maspforge library is used as a replacement for the standard Google Maps component provided as part of the Android framework. This library is able to use data that is stored in a relatively efficient manner on the SD card using a mapsforge specific binary file format. Additionally as the data is sourced from the OpenSteetMap which uses the reuse friendly Open Data Commons Open Database License. This permissive license means that data can be shared amongst users of the application if required using the forthcoming Rhizome component of the main Serval Project software.

Supporting Applications

Three supporting applications were constructed during the early stages of the development of the prototype application. These applications were designed to support testing of components of the prototype application. All three applications have been released as Open Source under the terms of the GPL.

The first supporting application was designed to send a UDP packet in order to testing the packet receiving capabilities of the prototype application. The content of the packet can either be sourced directly from the user via the console or alternatively from a packet script. The packet script is essentially a plain text file that specifies a delay, in seconds, and the content of the packet. The specified delay is used to space out the sending of the packets as specified by the script. For example a packet may be sent by the application, then a delay of 10 seconds is observed, and then the next packet is sent. By making the delay part of the script packets could be sent with differing amounts of delay. This application was used primarily to send packets to the prototype application while running within the Android emulator and to observe how the application behaved. It was not used once the testing of the application moved to using actual devices. The source code for the application is available via a GitHub repository[4].

The second application was designed to receive UDP packets and to echo their content to the console and alternatively to a text based log file. The application was used primarily to test the prototype application while running within the Android emulator and to observe how packets were being sent by the prototype. It was not used once the testing of the application moved to using actual devices. The source code for the application is available via a GitHub repository[5].

The third and final supporting application was designed to use a list of geographic coordinates as input and construct a packet script that could be used with the first supporting application. The content of the script was designed to be a series of location packets, each packet using one of the sets of geographic coordinates from the supplied list. This packet script could then be used to test the prototype application while it was running within the Android emulator to see how the application behaved to a stream of incoming location packets. Additionally a number of instances of the first supporting application could be used, each with different packet scripts, to see how the prototype application behaved with multiple incoming streams of location packets. The source code for the application is available via a GitHub repository[6].

Construction of these three supporting applications was made relatively easier due to the use of a plain text packet format, and were used during the early stages of the development of the prototype application. They were not used once testing of the application progressed to using actual smartphone devices and the resilient Ad Hoc mesh network provided by the main Serval Project software. They were also used in undertaking early testing of the user experience of the prototype application.

Prototype Application User Experience

In order for a person to use the prototype application, they must have an Android smartphone that works with the main Serval Project software. As this is Open Source software it is possible to either build the software from source, available via a GitHub repository[7], or download and automatically install the compiled version of the software via the Android Market[8]. The most recent version of the software will always be available via the GitHub repository, while developer only release candidates of the compiled software may also be announced to the Serval Project developer mailing list[9].

The prototype application is available as source code via its own GitHub repository and this is currently the only distribution channel for the software. It is possible that a future release may be made available via the Android Market when it is deemed to be feature complete, or it may be incorporated into the main Serval Project application. Therefore at the moment to install the prototype application on a device a user must download and compile the source code themselves. Additionally to fully experience the capabilities of the prototype application at least one map data file must be copied to an SD card that is installed in the smartphone into a specific directory. Detailed installation instructions are beyond the scope of this document and will be added to the Serval Project wiki when appropriate.

After the main Serval Project software has been installed, configured, and it has been confirmed that the smartphone is capable of forming a resilient Ad Hoc mesh network with at least one other phone, the prototype application can be used. The prototype application is started by the user touching its icon, accessible from the users application launcher. Importantly the prototype application must be started after the main Serval Project software so that the resilient Ad Hoc mesh network is available.

The first screen that the user sees upon application launch is a disclaimer screen. This screen informs the user that this experimental prototype software and also that any data that is sent by the application is in plain text and may be accessed by third parties. Additionally the user is informed that no information collected by the application is collected centrally by the Serval Project. The user is required to acknowledge , and accept the terms of, this disclaimer by choosing the confirmation button before the application will continue. If they do not agree with the terms of the disclaimer they can quit the application at this point.

If more than one map data file is found on the SD card, in a predetermined location, the user is prompted to select which file best suits their current location. Alternatively if there is only one map file available the application will use this file by default. If no files are found the user is asked if they wish to continue without a map data file. In this instance the application will still work, markers will still appear on the screen, but there will be no underlying map information to add context.

The users geographic location is determined by accessing the GPS hardware of the smartphone. Once a fix of acceptable quality and accuracy has been determined a blue coloured marker is added to the map to represent their location. As the user moves around the landscape and the geographic location information from the GPS hardware changes the position of the marker will be changed to reflect the new location. A complete log of the users movements is stored by the application for later possible analysis. At the time a new geographic location is determined for the user a location packet is sent across the mesh network to all of the network peers as identified by the Serval Project software. In this way other users of the prototype application will see the movements of the user around the landscape.

The location of other users on the map are represented on the map by a burnt orange coloured marker. The position of another users marker is changed when new location information is received in the form of a location packet. The user of the prototype application can also add an incident to the map at their current location. Incidents are represented by a yellow marker on the map. When a new incident is added to the map an incident packet is sent to all known peers on the resilient Ad Hoc mesh network as determined by the main Serval Project software. Each type of marker is in a different colour in order to help the user understand the information that is displayed on the map. An example map can be seen in .

More complex iconography is planned for a future release, for example where different categories of incident are used a different marker will be used. Additionally different iconography will be explored to see if it is possible to impart additional information to the user such as the age of the information used to put the marker on the map, so that the user can readily determine what is old information and what is new information.

If a user touches the marker for another user on the map they are presented with a screen that allows them to contact the user either via a phone call over the resilient Ad Hoc mesh network or via a Short Message Service (SMS) style message. If a user touches the marker for an incident the details of the incident are displayed. A sample incident can be seen in . This screen is similar to the one used to solicit the information from a user when they add an incident to the map except the incident details are not editable. Additionally the user is able to use familiar touch controls in order to pan and zoom the map, similar to the way that users can use popular mapping application such as Google Maps.

When a new packet is received by the application it is first validated to ensure that it is valid. Validation rules include checking to ensure that the right number of fields are present and that the right data type is used for each field. For example the fields used to represent geographic coordinates are checked to ensure they are numeric values that are within the bounds of valid geographic coordinates using the decimal degree notation. Once validated the content of the packet is stored in an SQLite database: one database is used for location information and another for incidents, using the standard content provider model[10] that is part of the Android framework. These same databases are used by other portions of the application, for example when the map refreshes.

It is planned for a future release that some of this information be made available to third party applications using the content provider mechanism if this is found to be useful. Additionally it is planned to provide a mechanism for third party applications to add content to the map by using a content provider. For example the main Serval Project application could use such a mechanism to add information to the map such as the signal strength related to network peers, in particular peers which may not be running the mapping application such as mesh potato network nodes. Location and incident data can be exported from these databases to a plain text file on the SD card for further analysis should that be required. The user can also delete all data in the databases at their discretion.

The map display updates every thirty seconds redrawing the map with the updated location of markers by sourcing data from the aforementioned databases. Any marker information that is more than twenty minutes old is not displayed. A planned future release of the prototype application will make this timeout value a user configurable option. Additionally as a means of spreading incident data as far as possible through the resilient Ad Hoc mesh network an incident data record is randomly selected every thirty seconds by each device for retransmission across the network.

Initially it was intended to use UDP broadcast packets for the transmission of information by the prototype application, however this was found not to be viable and an alternative strategy developed. It is believed that the root cause of this issue is the way in which the main Serval Project software must configure the network interface to support the resilient Ad Hoc mesh network. This is a non standard network configuration from the perspective of the Android framework which is higher up the software stack and can cause some issues. As an alternative every thirty seconds the main Serval Project software is polled for a list of known network peers. This list is iterated over one record at a time when a new packet needs to be sent over the network. Further investigation will need to be undertaken to determine a more efficient mechanism for sending packets at the same time that the packet format is reconsidered.

Packet Format

As outlined earlier location and incident information is shared between instanced of the prototype application by sending packets across the resilient Ad Hoc mesh network using UDP. The packets are constructed using plain text and contain a number of fields, each field is separated by a delimiter. Care has been taken in the development of the fields to take into account planned future enhancements. This includes the additional encryption and security features mentioned earlier as well as matching the incident fields to those used by the Ushahidi system. In this way it will be easier to integrate the prototype application with a Ushahidi instance should that become a required feature.

One type of packet is used for geographic location information, the other contains incident information. Each field is separated by a pipe character and some fields are common to both packet types, while some fields are not actively used by the prototype application at this time. The common fields are as follows:

1. The phone number and subscribe ID fields are sourced directly from the main Serval Project software. These are used to identify a user a on the resilient Ad Hoc mesh network;
2. The latitude and longitude fields are expressed using the decimal degree notation;
3. The timestamp field is used to represent the local time as determined by the smartphone when the location was determined or the original incident packet sent. The time is expressed as the number of seconds since January 1, 1970 00:00:00 UTC; and
4. The timezone field represents the local timezone as determined by the smartphone. The field contains one of the timezone identifiers as defined by the Android framework.

The timestamp and timezone fields are used to represent the local time of the original device that sent the packet. This information is used to convert the time to UTC internally before any comparisons are made between time values. For example determining the age of incident information while refreshing the map.

As already discussed the signature field is not currently used by the prototype application. This field is designed to contain a cryptographic hash of the packet content specific to the original user who sent it. It is anticipated this field will be used in a future release once the encryption functionality provided by the main Serval Project software is available and integrated with the application. The fields contained in both packet types are outlined in the following two sections.

Location Packets

A location packet contains the geographic coordinates that represents the geographic location for the specified user at a specific point in time. Each packet is sent using UDP on port 4012 to all of the known resilient Ad Hoc mesh network peers as determined by the main Serval Project software. A location packet contains each of the fields as outlined in the table below.

Location Packet Field List

Field Name	Description
Type	The type of location packet
Phone Number	The phone number associated with the users device
Subscriber ID	The subscriber ID associated with the users device
Latitude	The latitude geographic coordinate in decimal degree notation
Longitude	The longitude geographic coordinate in decimal degree notation
Timestamp	The local time reported by the device when the coordinate information was determined
Timezone	The timezone id reported by the device
Signature	A cryptographic hash of the packet content

The type field is specific to location packets and it is envisaged that this field will, in a future release, represent different location information in order to facilitate new functionality. For example it is envisaged that a user could configure the application to send a location packet with a different type when they arrive a specific destination. In this way fellow users of the application could be alerted to the fact that the individual had arrived. This could be extended with the encryption functionality to ensure that only a subset of users saw the alert, for example members of the same disaster or emergency response team.

Incident Packets

An incident packet is designed to contain the details of an incident that the user has added to the map that represents a particular event or condition at a specified time and geographic location. Each packet is sent using UDP on port 4013 to all of the known resilient Ad Hoc mesh network peers as determined by the main Serval Project software. A location packet contains each of the fields as outlined in the table below.

Incident Packet Field List

Field Name	Description
Phone Number	The phone number associated with the users device
Subscriber ID	The subscriber ID associated with the users device
Title	The title of an incident
Description	The description of an incident
Category	The category of an incident
Latitude	The latitude geographic coordinate in decimal degree notation
Longitude	The longitude geographic coordinate in decimal degree notation
Timestamp	The time reported by the device when the coordinate information was determined
Timezone	The timezone id reported by the device
Signature	A cryptographic hash of the packet content

In the current implementation of the prototype application the category field of an incident packet is not used. It is envisaged that this field will be used, in a future release, to distinguish between different types of incidents. For example in the case of environmental monitoring, the field may be used to distinguish between a location where a large cactus infestation has occurred, as opposed to a small cactus infestation. It is also possible, given the broadening scope of the prototype application that these packets will be renamed as Point of Interest (POI) packets to recognise the increased scope and numerous use cases for the application.

Cached Map Data

To achieve the goal of infrastructure independence the prototype application must be able to render a map on the smartphone using map data that is stored on the device. To this end the prototype application uses the mapsforge library to render the map and manage the various aspects of user interaction. For example the library provides the necessary functionality to add markers to a map and be able to respond when a user touches one of them. The mapsforge library uses its own binary format [11] for its map data. The data used to construct these files is sourced from the OpenStreetMap which provides data under a reuse friendly Open Data Commons Open Database License.

The conversion process from the OpenStreetMap format to the mapsforge binary format requires two pieces of software. The first is the Osmosis[12] application, this is officially supported software from OpenStreetMap which is used to read, write and manipulate data from the OpenStreetMap. For example the application is capable of taking an export from the OpenStreetMap data and constructing a local version of source PostgreSQL database. Crucially the Osmosis application employs a plugin based architecture that allows its functionality to be extended by including additional optional component in the data manipulation pipeline. One such component is the mapfile-writer plugin[13], which is used to create the binary map files for use with mapsforge.

With the Osmosis application, the mapfile-writer plugin and supporting libraries installed it is possible to convert data from the OpenStreetMap format to the binary format used by the mapsforge library. It is important to remember that smartphones have comparatively limited processing power and storage capacity and therefore it is necessary to keep the map data files as small as possible. The easiest way to achieve this, in the context of the primary use case, is to convert only the data required to represent the area affected by the disaster or emergency event. Additionally smaller files are easier to transfer across a resilient Ad Hoc mesh network.

Therefore the simplest approach is to download one of the many country or area extracts from one of the OpenStreetMap mirrors[14] and use this as the basis for the conversion. Testing has revealed it is possible to convert areas as large as New Zealand or South Africa or as small as the Flinders University campus. If converting a small area it is possible to start with a larger country or area extract of the OpenStreetMap data and select a smaller portion for the inclusion in the binary map file.

One the binary map file is converted it can copied to the SD card used with the smartphone into a specific location so that it can be found by the prototype application. As previously mentioned more than one file can be stored on the SD card and the user will be prompted to select which file they wish to use when they start the application. A future planned feature is to have the application dynamically chose the most appropriate map file based on the current location of the user and in particular change map data files if necessary between map rendering cycle and the next. This would be particularly useful where the Rhizome component of the main Serval Project software was used to share map data among network peers. In this way if a particular user didn’t have the map data for their location they could request the data from another peer who did have it.

Importantly the prototype application has shown that it is possible to build an application that supports collaborative mapping activities in an infrastructure independent manner and this has been successfully tested in small scale experiments. The testing of the application, and future testing plans is the topic of the next chapter.