README.md 2.98 KB
Newer Older
James Westman's avatar
James Westman committed
1
# GeoClueless
James Westman's avatar
James Westman committed
2
A location faking tool for GeoClue2
James Westman's avatar
James Westman committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

## What it does
GeoClueless allows you to fake your computer's geographical location for
debugging purposes. While it is running, applications that use GeoClue can
be fed coordinates of your choosing rather than your actual location.

One of the most useful features is GPX track replaying. This allows you to
record a track on your phone with an app like OsmAnd, then copy it to your
computer and replay it in real time. This way, you can pretend to drive the
same route over and over again without leaving your chair.

## How it works
GeoClueless implements the GeoClue D-Bus API, but with debug data instead of
real data. When you run it, it kills the existing GeoClue process if necessary,
then sets itself up on the `org.freedesktop.GeoClue2` name.

## Requirements/Installation
- Python 3
- [PyGObject](https://pypi.org/project/PyGObject/) (probably also available
    through your distro's package repositories)

To install, simply clone this repository with git. Then run the program with
`sudo ./geoclueless.py`.

## Usage
James Westman's avatar
James Westman committed
28 29 30 31 32 33

### General Options
- `-q`, `--quiet`: Do not output coordinates as they are replayed
- `-l`, `--loop`: Go back to the beginning instead of stopping at the end of
the track

James Westman's avatar
James Westman committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
### Data Sources
You can manually input coordinates, source them from a CSV file, or replay a
GPX track file.

#### Manually
`sudo ./geoclueless.py coords <lat> <lon>`

Other options:
- `--altitude`: The altitude (meters) of the point
- `--accuracy`: The accuracy (meters) to report
- `--heading`: The heading to report, in degrees clockwise from due north

#### CSV
`sudo ./geoclueless.py csv <file>`

Other options:
- `--rate`: Number of points per second

#### GPX
`sudo ./geoclueless.py gpx <file>`

Other options:
- `--speed`: The speed at which to replay the track. 1 is real time, .5 is half
speed, etc.

James Westman's avatar
James Westman committed
59 60 61 62
## Examples
There are example input files in the examples/ directory:
- london.csv: A simple, 60-line CSV file that goes in a square around London

James Westman's avatar
James Westman committed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
## Notes
- For CSV and GPX options, replay will not start until at least one client has
connected on D-Bus.
- You must run GeoClueless with `sudo` so it can register itself the system bus.
- GeoClueless does not perfectly replicate the behavior of GeoClue. In
particular, it ignores the authorization and accuracy scrambling features of
GeoClue. If you need these features emulated in GeoClueless, please file an
issue or (preferably) a merge request.
- So far, I've only tested the GPX feature with tracks generated in OsmAnd. If
you have a different app and it doesn't work, please file an issue.

## License
GeoClueless is licensed under the GNU General Public License, version 3 or
later. See COPYING.

GeoClueless contains a few files adapted from the original GeoClue. See
geoclueless/interfaces/README.md.

Untangle is a simple XML parsing library for Python. Its source code has been
copied to geoclueless/untangle.py. Untangle is licensed under the MIT license
and its source code is at https://github.com/stchris/untangle.