Scroll to navigation

ocli(1) GPS/MQTT utilities ocli(1)


ocli - OwnTracks command-line interface GPS publisher


ocli [ -v ] [ parameter-file...]


ocli is the OwnTracks command line interface publisher, a small utility which connects to gpsd (the interface daemon for GPS receivers) and publishes position information in OwnTracks JSON format to an MQTT broker in order for compatible software to process location data. ocli reads GPS data from an installed gpsd daemon, and as soon as it has a fix publishes an OwnTracks payload. ocli will subsequently publish a message every OCLI_INTERVAL seconds or when it detects it has moved OCLI_DISPLACEMENT meters.

ocli operates with a number of defaults which you can override using environment variables.

Parameter files

Any number of path names can be passed as parameter-file arguments to ocli . A single line is read from each of the files and added to the OwnTracks JSON payload as elements with the key name of base name of parameter-file. If the file is executable, the line is read from its standard output.

echo 27.2 > temperature ocli temperature /usr/bin/uname

will produce a payload which might look like

"_type": "location",
"tst": 1577654651,
"lat": 48.856826,
"temperature" : "27.2",
"uname": "FreeBSD" }

Keys obtained from parameter-files must not overwrite JSON element names define by ocli, so, for example, a file called lat will be silently ignored as it would clobber the JSON latitude element.


It is possible to control ocli 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:

causes ocli to publish its current location (providing gpsd has a fix). ocli sets t:m in the JSON to indicate the publish was manually requested.
causes the program to publish its internal configuration to the topic basetopic/dump as a _type: configuration message.
permits setting some of ocli's internal values (locatorInterval and locatorDisplacement). Note that these do not persist a restart.


Show version.
By default, ocli prints informational messages to stdout. This option silences those.


ocli is operates with a number of compiled-in defaults which can be overridden using environment variables:

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.
The MQTT host defaults to localhost.
The MQTT port is 1883.
The MQTT clientId is set to "ocli-username-hostname".
The address/hostname of the host on which gpsd is listening defaults to localhost.
The gpsd port nummber defaults to 2947.
The two-letter OwnTracks tracker ID defaults to not being used.
The interval after which ocli will publish a location position defaults to 1 second and can be changed dynamically (see above).
The distance after which ocli will publish a location position defaults to 0 meters and can be changed dynamically (see above).
The path to a PEM-encoded CA certificate which ocli uses to enable TLS/SSL.It is likely that the default MQTT port will need to be changed at the same time.


Very likely.


Jan-Piet Mens,


jo(1), mosquitto_pub(1), pledge(2), unveil(2), gpsd(8),

January 2020 jpmens