Skip to content

libstumbler design doc

Jump to bottom
Garvan Keeley edited this page Jan 30, 2015 · 5 revisions

libstumbler (a.k.a. stumbler service)

The service is being transitioned into a stand-alone stumbler library. Because libstumbler is used in Fennec, it is required to be extremely low impact (no discernible battery consumption, no database, no active GPS scanning).

The library has two modes of operation:

  1. Actively Polling Locations. This is how Mozilla Stumbler app uses the library. The GPS is polled every few seconds. And on each new location, Wi-Fi and Cell scans take place.

  2. Passive Location Listening. This is how Fennec uses the library. The service listens passively for locations, when a GPS location is received (because another app requested this) then scans take place.

Stumbler Components

Scanners

  • Wi-Fi and Cell scanners, that broadcast their results.

Scanner Listener / Report Generator

  • Listens for the scanner broadcasts, and bundles into single report.
  • A single report is a gps location, and the Wi-Fi and Cell scans for this location.
  • The report window is the time from one GPS location to the next. A new blank report is created when a GPS location arrives, and it is closed when the next GPS location arrives (and another new report is created).
  • The single report is sent to the Storage component.

Storage

  • Single reports are received by the above component, they are collected in memory, then flushed to disk as compressed json files.
  • Has a time window and a report count limit to decide when to write the reports to disk. When either are reached, reports are flushed to disk as a new zipped json file, and the in-memory report list is cleared.

Upload

  • Uploads the zipped json files created by the storage component.
  • Looks in the storage directory, and uploads all the files consecutively.
  • On successful upload of a file, deletes it from disk.

Motion Detection

  • Two parts, the detection of stopped motion, which uses the GPS, and the detection of start motion, which uses the device sensors.

  • (1) When GPS locations stop arriving for 2 mins, or the user has not moved 50 meters in 2 mins, the user is considered stopped. The stumbler becomes idle, and listens only to the motion sensor. (2 mins and 50 meters are the defaults.)

  • (2) The motion sensor triggers when the user moves, and attempts the activate the GPS. Go back to (1).

  • Motion Sensor Details

  • On Android 4.4, the AOSP has code for a significant motion sensor, which is a software sensor that aggregates hardware sensors to notify if the user has moved 'significantly'. On Nexus 4 and 5, we found that changing from sitting to walking ~5m would reliably trigger this sensor. Unfortunately, we are now finding that this sensor functions poorly on devices such as the Samsung S5 -it rarely triggers on these devices.

  • On <Android 4.4, we use the accelerometer, with a highly sensitive threshold, so that the device will trigger motion on any movement. This is useful for putting the app to sleep when the user puts the phone down overnight, or on a desk. In the app UI, we call this the 'Legacy Motion Sensor'.

  • Note that Google Play Services also has a significant motion sensor API. The app does not use this library, as we are avoiding close-source components.

Clone this wiki locally