Aaron Parecki 01f971c405 | 3 years ago | |
---|---|---|
compass | 3 years ago | |
.gitignore | 7 years ago | |
CONTRIBUTING.md | 9 years ago | |
README.md | 6 years ago | |
screenshot-mapview.jpg | 7 years ago |
Compass is a GPS tracking server that stores data in flat files.
You'll need to make sure the following PHP extensions are installed. Typically these are installed using the package manager of your operating system.
Compass is built using the Lumen framework. If you have any trouble getting started, you can refer to the Lumen documentation for tips that may have been skipped or assumed in these instructions.
In the compass
directory, copy .env.example
to .env
and fill in the details. Install the dependencies with composer.
$ composer install
Once you've created the database and configured the settings in .env
, run the migrations to set up all the tables.
$ php artisan migrate
Your web server will need to support URL re-routing to the index.php file of compass. This will vary based on your web server.
try_files $uri /index.php?$args;
location /index.php {
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
For the job queue you will either need to have one of the supported options by Lumen. The two most likely options are an SQL database or Redis. You can find other supported options here
If you're using the database queue driver (QUEUE_DRIVER=database
defined in .env
), you'll need to create the migration for that table:
$ php artisan queue:table
$ php artisan migrate
If you're using Redis, make sure you've installed the Redis server and set QUEUE_DRIVER=redis
.
Make sure the storage folder you've defined in STORAGE_DIR
is writable by the web server (or by the PHP process if you're using php-fpm).
To process jobs on the queue, run
$ php artisan queue:listen
For more details on how to configure this to run in the background, see https://lumen.laravel.com/docs/5.1/queues#running-the-queue-listener
After you create a tracking database, you can visit the database's settings page to get a read or write token. These tokens are used with the API to update or retrieve data.
To write to a database, make a POST request in JSON format with the following keys:
POST /api/input
The GeoJSON objects must have at least one property, "timestamp", which is can be any value that can be interpreted as a date. The object can have any additional properties you wish.
The open source iOS Overland will send data in this format by default.
POST /api/input?token=XXXXXXX HTTP/1.1
Content-type: application/json
{
"locations": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-122.621, 45.535]
},
"properties": {
"timestamp": "2017-01-01T10:00:00-0700",
"horizontal_accuracy": 65
}
}
]
}
To read a database, make a GET request as follows:
GET /api/query
GET /api/last
GET /api/find-from-localtime
This API method can help you answer the question "Where was I when my watch read 9:30am on July 15th?".
Timestamps in Exif data do not include the timezone offset, and there is no standard mechanism for including the timezone offset in Exif. Some Canon cameras put the offset in a field, but not all of them do. You can use this method to find your location given an Exif date.
YYYY-mm-dd HH:MM:SS
This will query the database and find the closest matching location for when your clock read that time.
Compass icon by Ryan Spiering from the Noun Project.
Screenshot of the map view by Sebastiaan Andeweg.
Copyright 2015 by Aaron Parecki
Compass is licensed under the Apache 2.0 license
Compass is built using the Lumen framework, which is licensed under the MIT license