mqottrace Files

mqottrace
===============
A daemon to subscribe to an mqtt server that collects "owntracks" data.
For owntracks, see https://owntracks.org/

mqottrace collects location data from the mqtt server and writes it into
an sqlite3 database. You can convert the data into gpx tracks with
mqott2gpx.

You can filter by "topic" which data should be collected. See the
config file mqottrace.json. If you are not sure, use "owntracks/#"
as topic.

Prequisites
-----------
- sqlite3
- perl
- perl modules JSON, DBI, DBD::SQLite, Date::Parse, Net::MQTT::Simple

(Except Net::MQTT::Simple, I'd guess all should be available in your
Linux repository. Use "sudo cpan install Net::MQTT::Simple" to install
the MQTT module).

Quick test
----------

For a quick test, you can run directly from the installation
directory. Do the following:

1. ./create-db
2. cp sample-mqottrace.json mqottrace.json
3. vi mqottrace.json # (or any other editor instead of vi)

In step 3:
- make sure to change the "topics". Use "owntracks/#" for all topics.
- Set '"db": "mqottrace.db"' (without path, this uses the current
working directory)
- Remove all config variables that you do not need. mqottrace will
guess if SSL is required by looking at the port, and the SSL
variables. So if you do not use SSL, remove all SSL stuff and do not
use port 8883.

4. nohup ./mqottrace > mqottrace.out 2>&1 & # to start

"Full" installation
-------------------

For a full install on a Linux system with systemd, do:

1. vi INSTALL-Linux.sh
2. ./INSTALL-Linux.sh
3. vi /etc/mqottrace/mqottrace.json

In step 3
- make sure to change the "topics". Use "owntracks/#" for all topics.
- Remove all config variables that you do not need. mqottrace will
guess if SSL is required by looking at the port, and the SSL
variables. So if you do not use SSL, remove all SSL stuff and do not
use port 8883.

4. service mqottrace start # to start the service.

========================================================================

Converting the data into gpx
----------------------------

Installation: If you want to use mqott2gpx only (like on some other
machine beside the mqottrace "server), you can run
./INSTALL-mqott2gpx.sh

Use "mqott2gpx" to convert the sqlite-DB-data into gpx tracks.

Usage: ./mqott2gpx [-h] [-D DBfile] [-F fromdate] [-T todate] topic
(use '-x' in the dates for the last x days, x any real number, e.g. '-F -1.5')

The DB file defaults to /var/lib/mqottrace/mqottrace.db, use the -D option
to use a different file, or set the environment variable MQOTT2GPX_DB.

If you omit the "topic" argument, the command will list all available topics
in your DB, so in case you don't know which topic to chose, try one
from the list.

The fromdate and todate will be parsed by the perl module Date::Parse,
so if you really want to know the details, check out the moduls's
documentation.
In addition to Date::Parse compatible dates, you can give any real number as
date. This means: Interpret the number as number of days, and add it to
today's date. So your number should be negative, unless you have future data
in your DB (in case you have future data, tell me how you got it, maybe
we can use the same method for e.g. Roulette and make a lot of money ;-)
The default is "-F -7", i.e. the last 7 days.

mqott2gpx will print the gpx to stdout, so you should probably redirect it
to some file.

Example:

./mqott2gpx -D ./mqottrace.db -F -3.5 -T -1 owntracks/user1/devXY > mytrack.gpx

The "topic" argument does not accept any wildcards, this does not make sense,
you want a track of a single topic and not mix it with other topics (ie. other
users or devices).