ocli(1)

💅 ocli(1) — GPS/MQTT utilities, bestie ✨

🌸 NAME 🌸

ocli — OwnTracks command-line interface GPS publisher 💖

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

Okay so ocli is the OwnTracks command-line interface publisher: a small utility (no cap) that connects to gpsd (the interface daemon for GPS receivers) and publishes position info in OwnTracks JSON format to an MQTT broker so compatible software can process location data. It’s giving “location data main character energy.” 💅

It reads GPS data from an installed gpsd daemon, and as soon as it has a fix it publishes an OwnTracks payload — iconic. After that, 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. lowkey convenient.

🎀 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 an element with the key name of the base name of parameter-file. If the file is executable, the line is read from its standard output. 🍓

Like:

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"
          }

Heads up bestie: keys obtained from *parameter-file*s must not overwrite JSON element names defined by ocli. So, for example, a file called lat will be silently ignored as it would clobber the JSON latitude element. 🙈

🎛️ Control 🎛️

You can 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:

• reportLocation — 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. periodt.
• dump — causes the program to publish its internal configuration to the topic basetopic/dump as a _type: configuration message.
• setConfiguration — permits setting some of ocli's internal values (locatorInterval and locatorDisplacement). Note that these do not persist a restart. iykyk.

✨ OPTIONS ✨

• -v — Show version. 👑
• -s — By default, ocli prints informational messages to stdout. This option silences those. 🤫

🌈 ENVIRONMENT 🌈

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

• 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 number 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. no cap, fr fr 😭

🫶 AUTHOR 🫶

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

🦋 SEE ALSO 🦋

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

kisses and slay, jpmens — January 2020 — ocli(1) 🫶💖