============
Introduction
============

LogMyGsm is an Android application with 3 main features:

- logging of cellular network information versus location

- on-screen display of cell and location -related information

- a general purpose map viewer

- a menu option to share the current location (as an OS grid reference) with
  any other application (e.g. messaging, Twitter, Evernote etc)

============
Data logging
============

LogMyGsm will write logfiles automatically once it has a GPS fix.  The files
are written to the /sdcard/LogMyGsm/logs directory.  Each line in the logfile
has the following format

  51.3383821   -2.9814906   6 A U     410939      35490 -101 23410 76.3 1347211290

The columns are
* latitude
* longitude
* GPS estimated accuracy (metres)
* cell connection state (A = in coverage, X = out of coverage or emergency calls only)
* connection type (G = GPRS (2G), E = EDGE (2.5G), U = UMTS (3G), H = HSDPA (3.5G))
* cell ID
* LAC
* signal power level (in dBm)
* MCC/MNC (234 is UK, 10 is O2)
* raw (WGS84) elevation (requires correction to get height above sea level)
* timestamp (seconds since Unix epoch)

Logfiles could be retrieved to a PC by FTP (e.g. using the SwiFTP application to
enable an FTP server on the phone), or over a USB cable.

Once on the PC, the data can be processed to generate coverage maps.

The logging function continues to run even if the application is put into the
background with the Back or Home buttons.  This allows other applications to be
used on the phone whilst data continues to be gathered.  An Exit option on the
main menu must be used to exit from the application completely.

=================
On-screen display
=================

About 50% of screen area is the map (see below).  The text area displays the
following:

* cell ID (coloured red if the phone currently has no service or emergency calls only)
* signal power level (in ASU)
* LAC
* the range and bearing from the centre of the map to the tower location, if known
* connection type (GPRS, EDGE, UMTS, HSDPA)
* MCC and MNC (country and operator codes)
* history of recently used cells (showing cell ID, time since last use)
* number of points logged to file this session

* X and Y coordinates of the map tile at the centre of the map display
* OS grid reference of the point at the centre of the map display (UK only)

If the GPS is locked:
* latitude and longitude of current position
* estimated height above sea level (UK only - the approximation will be bogus
  elsewhere)
* GPS position accuracy as reported by the system
* speed (in miles per hour, if the map is NOT panned away from the current
  location)
* heading (degrees clockwise round from north)
* distance between current location and the point at the centre of the map (if
  the map is panned away from the current location)
* number of satellites used for estimate, number with ephemeris, number with
  almanac, total

There is a large map mode (selected as "waypoints" from the menu).  On this
screen a larger map is shown, and markers can be added to and deleted from the
map.  Markers are shown in a deep ruby colour, which seems to stand out against
the supported maps.

The normal and waypoints maps have separate preferences.  So for example,
different maps or zoom levels can be left open on the two maps.

===========
Map Viewing
===========

The map view has the following features:

* zoom in (+) and out (-) by touching buttons at the top of the map.  Note:
  there is *NO* pinch to zoom function

* pan the map by touching and dragging it around

* choice of tile sets:
  - OpenStreetMap (Mapnik)
  - Open Cycle Map
  - UK Ordnance Survey
  - custom tiles.  Suitable tiles could be generated by processing the logfiles
    and uploading them on to the SD card.  Tools to do this are outside the
    scope of this project.

* force download of the tile covering the centre of the display - useful if the
  tile is believed to be out of date (e.g. due to constant improvements to
  OpenStreetMap)

* download recently accessed tiles that were not found on the SD card - such
  tiles are rendered grey on-screen

* the map shows the path the phone has covered as alternating black and white
  dots against a semi-opaque purple background.  The trail can be cleared
  through a menu option on the "waypoints map" screen.

* recentre by touching centre circle
  - if GPS is locked, recentre jumps to current GPS location
  - otherwise, recentre jumps to estimated position of the tower currently
    being accessed, if known (using /sdcard/logmygsm/prefs/cidxy.txt file)
  - otherwise recentre does nothing

If GPS is locked
* cross-hair centred at current location (which may be away from centre of
  display if the map has been dragged, and may even be off-screen)
* a triangle showing the current heading

The map tiles use the same directory structure as the Maverick and Maverick Pro
applications, so the storage is shared if those applications are also in use on
the phone.