Public:Android library

OpenCellID Services for Android

WARNING! THIS DOCUMENT IS IN DRAFT STATE

General description

OpenCellID Services for Android is a suite of Android components that you can link to your Android apps, which allow you to contribute and/or consume data from the OpenCellID project.

There are 3 main components in the suite, each component has a specific purpose (collect, upload, download). You can link one or more components depending on your needs.

Note: although these components are named Services, they are not really Android services, but rather they implement some more generic concept of service. It might happen that they use Android Services internally, but this is just internal implementation.
We will refer to these components with the term "Services" throughout this document.

The following table lists the available services and their purpose:

OpenCellID main services

Component	Purpose
OpenCellIDCollectService	Collects cell tower and network information and stores it locally on the device
OpenCellIDUploadService	Uploads the collected data to the OpenCellID server as soon as connection is available
OpenCellIDDownloadService	Downloads the OpenCellID data from the server to the local storage

Linking the OpenCellID Services to your project

Link as Library Projects in Eclipse

1. Import the desired service from the repository in your workspace
2. Open your project's properties
3. Goto the "Android" section and add the imported project as Library Project

To use any of the OpenCellID Android services, you need to import the following helper projects too:

OpenCellID helper projects

Project	Purpose
OpenCellIDAccessLibrary	Common OpenCellID code
GPSService	Manage GPS functionalities and filtering
LogService	Manage logging functionalities
BaseService	Base class for generic services

Link as .jar libraries

1. Download the needed services as .jar files from here
2. Put the .jars in the lib directory of your Android project
3. You are done - all the dependent libraries are already included

Distribution as .jar files is not available yet

Using an OpenCellID service

Once you have linked the service to your project, you have to instantiate it and start it.
The example below applies to every OpenCellID service.

• first, in the onCreate() method of your activity, you instantiate the service:

cellCollectService = new OpenCellIDCollectService(this);

• then, the Service can be started and stopped easily at anytime:

cellCollectService.startService();

cellCollectService.stopService();

Configuring an OpenCellID service

Each service can be configured with different specific options.

To configure the service, you call different configuration methods on the service.

Most of the settings are propagated to the service also while it is running, and take effect as soon as possible.

Configuring the service is optional. If you don't configure a service, it will run with default values.

Specific documentation for each configuration method is available in the Javadoc documentation of the service.

Example: create, configure and start a service:

cellCollectService = new OpenCellIDCollectService(this);
cellCollectService.setDbSize(500);
cellCollectService.setMinSameCellDistance(20);
cellCollectService.startService();

Storage

All the OCID service share a common storage, which is located in the device's External Storage Directory (normally SDCARD).

You can find all the data inside a directory named /opencellid.

This directory can contain the following storage files:

Opencellid storage files

Storage	Content
OCID_measurements.db3	SQLite database containing all the measurements that have been ever collected
OCID_cells.db3	SQLite database containing all the unique cells that have been collected, downloaded or imported
apikey.txt	The API key assigned to your device by the OpenCellID server. This is used to identify your contributions to the OCID database.