This is the OwnTracks command line interface publisher, a.k.a. owntracks-cli-publisher, a small utility which connects to gpsd and publishes position information in OwnTracks JSON to an MQTT broker in order for compatible software to process location data. (Read up on what OwnTracks does if you're new to it.)
gpsd is a daemon that receives data from one or more GPS receivers and provides data to multiple applications via a TCP/IP service. GPS data thus obtained is processed by owntracks-cli-publisher and published via MQTT.
We've been successful with a number of GPS receivers, some of which are very affordable. The small USB stick receiver in the above photo is called a VK172 and costs roughly โฌ16.
Determining which USB port was obtained by the receiver can be challenging, but dmesg is useful to find out. Once you know the port, cross your fingers that it remains identical after a reboot, and ensure your gpsd service is running. For testing, we've found that launching it from a terminal is useful:
$ gpsd -n -D 2 -N /dev/tty.usbmodem1A121201
owntracks-cli-publisher operates with a number of defaults which you can override using environment variables.
The following defaults are used:
- The MQTT base topic defaults to
owntracks/<username>/<hostname>
, where username is the name of the logged in user, and hostname the short host name. This base topic can be overridden by settingBASE_TOPIC
in the environment. - The MQTT host and port are
localhost
and1883
respectively, and can be set usingMQTT_HOST
andMQTT_PORT
. - The MQTT clientId is set to
"ocli-<username>-<hostname>"
, but it can be overridden by settingOCLI_CLIENTID
in the environment. - TCP is used to connect to gpsd with
localhost
and2947
being the default host and port, overridden by settingGPSD_HOST
andGPSD_PORT
. - The two-letter OwnTracks tracker ID can be configured by setting
OCLI_TID
; it defaults to not being used. OCLI_INTERVAL
defaults to 60 seconds.OCLI_DISPLACEMENT
defaults to 0 meters.- TLS can be enabled for the MQTT connection by specifying the path to a PEM CA certificate with which to verify peers in
OCLI_CACERT
. Note, that you'll likely need to also specify a differentMQTT_PORT
from the default.
owntracks-cli-publisher reads GPS data from gpsd and as soon as it has a fix it publishes an OwnTracks payload (see below). owntracks-cli-publisher will subsequently publish a message every OCLI_INTERVAL
seconds or when it detects it has moved OCLI_DISPLACEMENT
meters.
Any number of path names can be passed as arguments to owntracks-cli-publisher which interprets each in terms of an element which will be added to the OwnTracks JSON. The element name is the base name of the path. If a path points to an executable file the first line of stdout produced by that executable will be used as the key's value, otherwise the first line read from the file. In both cases, trailing newlines are removed from values.
$ echo 27.2 > parms/temp
$ owntracks-cli-publisher parms/temp contrib/platform
In this example, we use a file and a program. When owntracks-cli-publisher produces its JSON we'll see something like this:
{
"_type": "location",
"tst": 1577654651,
"lat": 48.856826,
"temp" : "27.2",
"platform": "FreeBSD"
}
Note that a key may not overwrite JSON keys defined by owntracks-cli-publisher, so for example, a file called lat
will not be accepted as it would clobber the latitude JSON element.
It is possible to control owntracks-cli-publisher using a subset of OwnTrack's cmd
commands.
$ t=owntracks/jpm/tiggr/cmd
$ mosquitto_pub -t $t -m "$(jo _type=cmd action=reportLocation)"
The following commands are currently implemented:
-
reportLocation
causes owntracks-cli-publisher to publish its current location (providing gpsd has a fix). owntracks-cli-publisher setst:m
in the JSON indicating the publish was manually requested. -
dump
causes owntracks-cli-publisher to publish its internal configuration to the topic<basetopic>/dump
as a_type: configuration
message.{ "_type": "configuration", "_npubs": 47, "clientId": "owntracks-ocli", "locatorInterval": 60, "locatorDisplacement": 0, "pubTopicBase": "owntracks/jpm/tiggr", "tid": "OC", "username": "jpm", "deviceId": "tiggr" }
-
setConfiguration
permits setting some of owntracks-cli-publisher's internal values. Note that these do not persist a restart.$ mosquitto_pub -t $t -m "$(jo _type=cmd action=setConfiguration configuration=$(jo _type=configuration locatorInterval=10 locatorDisplacement=0))"
{ "_type": "cmd", "action": "setConfiguration", "configuration": { "_type": "configuration", "locatorInterval": 10, "locatorDisplacement": 0 } }
There is a small set of scripts with which you can test owntracks-cli-publisher without having a real GPS receiver. Please check contrib/fake/ for more information.
owntracks-cli-publisher should compile easily once you extract the source code and have the prerequisite libraries installed for linking against gpsd and the mosquitto library.
Systems we've tested on require the following packages in order to build owntracks-cli-publisher.
# pkg install mosquitto gpsd
$ make
# pkg_add mosquitto gpsd
$ make
$ brew install mosquitto gpsd
$ make
# apt-get install libmosquitto-dev libgps-dev
$ make
# yum install openssl-devel
$ wget https://mosquitto.org/files/source/mosquitto-1.6.8.tar.gz
$ tar xf mosquitto-1.6.8.tar.gz
$ cd mosquitto-1.6.8/
$ make
# make install
# echo /usr/local/lib > /etc/ld.so.conf.d/mosquitto.conf
# ldconfig
# yum install python3-scons
$ wget http://download-mirror.savannah.gnu.org/releases/gpsd/gpsd-3.19.tar.gz
$ tar xf gpsd-3.19.tar.gz
$ cd gpsd-3.19/
$ /usr/bin/scons-3
# /usr/bin/scons-3 udev-install
$ cd ocli
$ make
This may be a way of getting owntracks-cli-publisher working on machines with systemd. Basically we need two things:
-
an environment file,
owntracks-cli-publisher.env
:name="Testing" fixlog="/tmp/fix.log" BASE_TOPIC="m/bus/b001" MQTT_HOST="localhost" MQTT_PORT=1888 GPSD_HOST="localhost" GPSD_PORT="2947" OCLI_TID="OC"
-
a systemd Unit file:
[Unit] Description=OwnTracks cli Requires=mosquitto.service [Service] Type=simple EnvironmentFile=/home/jpm/owntracks-cli-publisher.env ExecStartPre=/usr/bin/touch /tmp/ocli-started-${name} ExecStart=/home/jpm/bin/owntracks-cli-publisher Restart=always RestartSec=60 User=mosquitto Group=mosquitto [Install] WantedBy=multi-user.target
Packages are available for select operating systems from the Github releases page. Note that the RPM packages do not contain an owntracks-cli-publisher.env
file for systemd.
- Idea and initial implementation by Jan-Piet Mens
- gpsd
- mosquitto
- utarray
- utstring
- packaging work by Andreas Motl