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

LogMyGsm is an Android application with these main features:

- logging of cellular network information versus location

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

- a general purpose map viewer including route planning and distance measurement

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

- bookmarking of current location in the log file

============
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, based on standard ASU<->dBm formula)
* MCC/MNC (234 is UK, 10 is O2)
* raw (WGS84) elevation (requires correction to get height above sea level)
* timestamp (seconds since Unix epoch)

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.

LogMyGsm cannot post-process the logfiles.  They are meant to 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, or by sharing/emailing them off the phone through
the 'Cloud'.

Once on the PC, the data in the logfiles can be processed to generate coverage
maps.  (Tools for doing this are not part of the LogMyGsm project.)  The
logfiles can also be processed into GPX files, suitable for use in editing
OpenStreetMap etc.  Any bookmarks in the logfiles become waypoints in the GPX
file.

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

About 50% of screen area is the map.  An example is at

    http://rc0rc0.wordpress.com/2013/05/15/logmygsm-explanation/

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)
* MNC (network operator code); the MCC (country code) is assumed to be known...
* 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 markers are joined by links to aid in route planning.
LogMyGsm will guess which pairs of markers are adjacent for linking purposes.

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.  Support for up to 3 networks' worth
    of coverage tiles are supported.  Tools to do this are outside the scope of
    this project.

* there is *NO* automatic downloading of missing tiles.  This is to avoid the
  use of mobile data, or WiFi data at inconvenient times.  Missing tiles are
  approximated by zooming into a coarser (zoomed-out) tile if available.  Such
  regions of the map are overlayed with a pale blue cross.  If no suitable
  coarser tile is found, a plain gray tile is shown.

* various manual downloading options:
  - 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) - and all zoomed-out levels containing it
  - any missing tiles within screen area at current zoom level and all
    zoomed-out levels containing it
  - same + missing tiles at 1 further level of zoom
  - same + missing tiles at 1+2 further levels of zoom
  - any missing tiles along all links between markers to currently viewed zoom
    level, and all zoomed-out levels.  Half a tile of "fuzz" is downloaded
    around this path, to cover small deviations from the planned route.
  - any missing tiles within 3x3 or 5x5 regions around centre-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 "clear trail" 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
* thick circle centred at current GPS 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.  Directories under /sdcard/external_sd/Maverick/tiles are searched
before /sdcard/Maverick/tiles, to handle the way newer Samsung phones mount the
removable microSD card.

=====
Files
=====

Apart from the (bulky) map tiles, the other files are on "internal" SD card
storage.

/sdcard/LogMyGsm/logs/23410/YYYYMMDD-HHMMSS.log
    This is the path of each logfile when an UK O2 SIM card is in use.  Replace
    "23410" by the MCC-MNC code of your SIM card.  Consult

        http://en.wikipedia.org/wiki/Mobile_Network_Code

/sdcard/LogMyGsm/prefs/cidxy_23410.txt
    This is a text file containing a mapping from LAC+CID to X,Y Web Mercator
    coordinates of the cell tower.  This file could be generated by separate
    tools and copied onto the phone.  For other SIM operators, replace "23410"
    by their MCC-MNC.

/sdcard/LogMyGsm/prefs/cidxy_23410.dat
    Binary compiled form of the above .txt file, to speed up later loading.
    Automatically updated if the .txt file is replaced with a newer version.

/sdcard/LogMyGsm/prefs/markers.txt
    File containing the markers that are edited in the "waypoints" screen

/sdcard/LogMyGsm/prefs/prefs.txt
    Preferences for the "normal" activity (map choice, zoom level, display
    position etc)

/sdcard/LogMyGsm/prefs/prefs.txt
    Preferences for the "waypoint edit" activity

/sdcard/LogMyGsm/prefs/trail.dat
    Binary file containing the points on the trail (shown as alternative black
    and white dots on the map).

/sdcard/external_sd/Maverick/tiles/...
or
/sdcard/Maverick/tiles/...

    Map tile storage.  If you generate custom tiles showing network coverage,
    you have to upload these onto the phone over FTP, via USB cable, or by
    temporarily moving your microSD card to your computer.  There is no
    provision in LogMyGsm to download custom tiles from the Internet.


# vim:et:sw=4:sts=4:ts=4