1. Manuals
  2. Tumbleweed
  3. ocli
  4. owntracks-cli-publisher(1)

Scroll to navigation

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

NAME

ocli - OwnTracks command-line interface GPS publisher

SYNOPSIS

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

DESCRIPTION

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.

Control

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.

OPTIONS

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

ENVIRONMENT

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

BASE_TOPIC
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.
MQTT_HOST
The MQTT host defaults to localhost.
MQTT_PORT
The MQTT port is 1883.
OCLI_CLIENTID
The MQTT clientId is set to "ocli-username-hostname".
GPSD_HOST
The address/hostname of the host on which gpsd is listening defaults to localhost.
GPSD_PORT
The gpsd port nummber defaults to 2947.
OCLI_TID
The two-letter OwnTracks tracker ID defaults to not being used.
OCLI_INTERVAL
The interval after which ocli will publish a location position defaults to 1 second and can be changed dynamically (see above).
OCLI_DISPLACEMENT
The distance after which ocli will publish a location position defaults to 0 meters and can be changed dynamically (see above).
OCLI_CACERT
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.

BUGS

Very likely.

AUTHOR

Jan-Piet Mens, https://jpmens.net

SEE ALSO

jo(1), mosquitto_pub(1), pledge(2), unveil(2), gpsd(8), https://owntracks.org

January 2020 jpmens