Print
Category: Downloadable program
Hits: 21826

This page provides a short summary of the steps a potential user of the toolkit should be familiar with before commencing full-scale development. We explain how to build the toolkit from source.  For those wishing to avoid building the toolkit from source, pre-built libraries are available for the most popular development tools on Windows, Android and IOS 3 and 4.

Once the toolkit has been obtained from the HaptiMap website, it can be integrated in projects for all major mobile platforms (IOS, Android, Windows Mobile) and common desktop operation systems (Linux, Windows, Mac OS X). For each individual platform the HaptiMap website provides information about how the toolkit can be built and integrated into an existing or new application. Sections 2.3 to 2.6 of this chapter provide some basic examples of toolkit usage on the most popular platforms.  Potential users of the toolkit can use these examples for experimentation in order to familiarise themselves with the toolkit.

 

Building the Toolkit

The following sections outline the processes by which to obtain and build the toolkit on the most popular platforms for both mobile and desktop applications. 

  

Android

This section outlines the necessary steps in order to build the toolkit for the Android mobile platform using the widely used Eclipse Integrated Development Environment (IDE). There are two options: either you can choose to only use the crust (that is, Android-specific, HCI modules that do not require you to build the ndk environment), or the core or mantle parts (cross-platform HCI-modules and sensor interfaces).

 

Using only Android-specific modules
The HaptiMap toolkit is designed as a library project and can be integrated into an application from the IDE. To accomplish this, you first need to import the HaptiMap toolkit project into Eclipse (File->Import, Existing projects into workspace). You find the project in the HaptiMapToolkit folder (in “Your path”\HaptimapToolkit\crust\android\) that is placed alongside some folders of example projects. Once it has been imported, all non-native Android-specific HCI modules will be compiled automatically, and can be used according to their individual documentation.


To integrate the toolkit into your own project, use the principle of Android external libraries: right-click on your project, choose Properties, then Android in the left-hand tree list, click Add in the Library section of the window and choose HaptiMapToolkit. See also Figure 4.


Using cross-platform modules
If the developer is further interested in using the HaptiMap toolkit core or native cross-platform HCI modules, the native parts of the toolkit need to be compiled as well. As part of its normal functionality, Android provides a developer with the "ndk-build" command.  This command can be used to compile the native parts of the toolkit instead of setting up Android toolkit specific build scripts as illustrated in Figure 5. Once the command has been called, the shared objects containing the core and mantle functionalities will be built and integrated into the "HaptiMapToolkit" library project and will be shipped together with the non-native code.   JNI (Java Native Interface) wrappers are provided for the developers’ convenience and come with the corresponding Javadoc documentation, which a Java developer would be well accomplished at using. 

 

Android development environment

Figure 4: The HaptiMap Toolkit can be integrated into Android applications via the Android External Libraries principle.

 

ndk build screen

Figure 5: A single call of "ndk-build" builds the native parts of the toolkit.

 

Windows

On the Windows platform, the Haptimap toolkit consists of a static library constituting the core functions and tightly integrated mantle modules.  It is also possible to build a number of other libraries for less commonly used mantle modules. Executable programs that demonstrate crust components are built by linking with the core library.

Most problems people encounter when building applications for Windows occur because of incompatibilities among the libraries they need to use.  The Haptimap toolkit on Windows makes use of a large number of external libraries and thus it has been necessary to provide a number of different build files.  Most of the libraries used within the toolkit are freely available open source suites and can be obtained from the appropriate web site. The only exception being the Navteq MapTP library for which the toolkit has a map data plug-in.  For those users of the toolkit we provide build files that do not require the use of the MapTP libraries. 

The primary tool used to build the toolkit on Windows is Microsoft’s Visual Studio 2008.  Included within the toolkit is a solution file that contains projects to build the toolkit for 32/64 bit platforms, with or without MapTP support, with or without Bluetooth support and with or without desktop haptics.  Figure 6 illustrates this project layout and the special ‘config.h’ file that is used to define the parts of the main toolkit library that are included in the core library.

The Visual Studio project file is automatically upgraded for use in Visual Studio 2010.  For mantle modules not included in the main library, separate SLN and VCPROJ files are included in the appropriate folders.

 

Windows build environment

Figure 6: Windows build environment.

 

iPhone

For the iPhone platform all development is implemented using Xcode.  In the iPhone build folder, project files for Xcode 3 /4 will allow static toolkit libraries for the emulator and the device itself. These libraries take the same name but are built into different folders. When building an App with these libraries, both the emulator and device projects must link against the appropriate library. 

The libraries can be built by simply “double clicking” on the ‘.xcodeproj’ bundle file, and pressing the build button on the toolbar.  Very little additional configuration should be required. When developing Apps it will be necessary to have a developer profile installed on the target device.  Figure 7 illustrates an example of the toolkit Xcode development build.

 

XCODE build environment

Figure 7: XCODE development build of Toolkit.

 

Symbian

The Symbian version of the toolkit is built using the Carbide IDE on the Windows platform.  A library project for carbide and MMP project files are provided in the Symbian build folder.  Examples are also built in the same way from Eclipse projects that link with the toolkit library.  Figure 8 illustrates the Carbide development environment showing the MMP configuration file for the toolkit library project. This MMP file can be driven to build libraries for the Symbian emulator and Symbian devices.

 

Symbian build environment

Figure 8: Symbian build environment.

 

Toolkit on-line Resources


The actual toolkit is accompanied by a common open source project infrastructure. To encourage use of the toolkit and subsequent development a SVN centralised version control system, aTrac online project management software with wiki functionality, and a forum to discuss toolkit-related things were all set up. 

The source of the toolkit and other essential file resources are provided via SVN (Subversion), an established server-based version management system. This allows internal and external developers of the library to make use of all the diverse versioning functionalities.  For example, it is possible to instantly branch the current version of the toolkit (i.e. trunk) in order to integrate and test functionality.

It was decided to use Trac because as one of the state of the art project management web-frameworks, it integrates seamlessly with the SVN management. Using Trac it is possible to follow any recent code changes, find and resolve bugs, manage responsibility, and have discussions in a Wiki-like manner.  Figure 9 illustrates Trac in action.  With this tight integration, the actual documentation can refer to certain classes, functions or fields in the code.  It is believed that this integration will help external developers to quickly understand and adapt the essentials of the HaptiMap toolkit.

 

 trac screen shot trac screen shot

Figure 9: Two screenshots of the Trac project management software.

 

 The online discussion (see Figure 10) forum was set up primarily to support the less experienced developers, who perhaps require only a quick answer to a specific question and don't want to read all the documentation. In comparison to a wiki, a forum invites the users to discuss various things, even if they are vague or incomplete. From other projects, it has also been shown that a forum is also often used to raise ideas for future developments. This helps to maintain and continue the development of the toolkit according to what toolkit users are expecting.

 

Haptimap forum

Figure 10: A screenshot of the HaptiMap forum.

 

A starter application for Android


To allow external developers to quickly understand the HaptiMap design patterns, the toolkit comes complete with a sample application tutorial.  For the sample application, we envision that a developer wants to highlight an arbitrary location visually as well as non-visually. This application extends the Google "Hello Map" tutorial, where a developer learns to set up a visual map and set visual markers for a destination. Our HaptiMap extension tutorial shows how this destination can be displayed in two non-visual ways. Firstly, it is shown how the destination can be displayed through the Tactile Compass vibration patterns. Secondly, it is shown how the destination can also be highlighted with audio feedback in a Geiger counter style. Therefore this demo application showcases two of the toolkit’s most tested and highly relevant HCI modules. Since other HCI modules work in almost similar ways, the aim is that the developer will quickly become accustomed to the HaptiMap design patterns and can further extend the starter application.

The starter example is found at: https://haptimap.ee.qub.ac.uk/dev/wiki/UsingToolkitonAndroid

 

A starter application for Windows

A simple example illustrating the use of the toolkit on the Windows platform is one in which the toolkit library is used to prime the internal cache with some mapping data from the OpenStreetMap map server

To construct the application begin by copying the template “starter.vcproj” to a different folder and rename it to a new project.  Now double click on it.  Visual Studio 2008 will open and invite you to create a SLN container for the project; allow it.   You are now in a position to build your project by adding the source files.

Using this project file as a template allows the user to set up all the include paths and library references they will require to build a Haptimap toolkit application.

 The project setup will take the appearance of the screen shot shown in Figure 11.

 

Windows starter application

Figure 11: An empty VCPROJ file ready to be used to build a Haptimap toolkit project.

The next stage is to include the source file.  To do this add the file DATAIN.C  to the source files and inspect the include paths in the settings dialog as shown in Figure 12.  Note carefully the include paths as it might be necessary to adjust some of these to match the preferred build environment.   It is the settings of these include and library paths that we find cause most build problems so it is imperative that the user of the system checks that they have set them to match their own system.

The second most common cause of problems on Windows is that some of the 3rd party libraries were built using different calling conventions (i.e. DLL versus static libraries or using different library versions.)  This can be overcome by re-building the 3rd party libraries – one of the main reasons why it is desirable to only use open source libraries in the toolkit.

 

Visual studio project setup

Figure 12: The Visual Studio 2008 project after inclusion of the source file.

 

Once these steps are complete, the project is ready to be built and executed.  Build it and run it. Once this starter application is running then ANY other toolkit application chould be readily built using the same starting template as has just been described.

 

A starter application for the iPhone

In this example a simple application is created that adds a linestring into the toolkit internal storage. A button will be set up on the iPhone screen that writes an arbitrary polygon linestring into the storage and updates a label on the display saying how many linestrings are in storage. Note that on the iPhone/iPod/iPad that each application has its own sandbox storage which is unique to that application and so any data downloaded by this application, while it persists between invocations, cannot be accessed by any other application.

To get the applications up and running it is necessary to copy the files in the starter application folder to a new folder. This is done so that all the required libraries and frameworks used by the Haptimap toolkit are available to the user of it.  The Project Edit Active Target command can be used to change the Project and Product names to something meaningful to the user.

This starter application contains all the code to test the toolkit and the program can be built and run on the emulator. If the program is run via the Xcode console then toolkit messages will appear on the lag when “Write Linestring” button is clicked. (See Figure 13.)

XCODE project setup

Figure 13:  The Xcode Consle and iPhone emulator for the Starter project.

 

All the coding details are basically the same as those a toolkit developer would be familiar with from most iPhone projects. The Write Linestring button has a handler function in the ViewController derived class. The functions that use the toolkit are all contained in a separate “C” file that is added to the Xcode project. The file Test.h contains the include directives for the toolkit and the file test.c contains the code for the functions themselves.

The code for the button handler is self explanatory; it also includes some calls to the message logs and a call to the external “testMemoryMappedFiles() which handles the toolkit connection.

 

Other starter applications


Each supported platform has a similar starter application that can be used for priming a new development thread. All of these are contained in the Crust folder under the appropriate platform header.

 

Deliverables


Much more detail can be obtained by reading the project deliverables that explain the design of the tooolkit and expand this page:

Deliverable 4.3

Deliverable 4.2

 

Full details and up-to-date information information is available via these links:


The latter two are currently password-protected (restricted to the HaptiMap consortium).