-
-
Notifications
You must be signed in to change notification settings - Fork 11
/
owntracks-cli-publisher.1
170 lines (169 loc) · 4.73 KB
/
owntracks-cli-publisher.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
.\" ocli.1 Copyright (C) 2016-2020 Jan-Piet Mens <[email protected]>
.\" ===
.TH ocli 1 "January 2020" "jpmens" "GPS/MQTT utilities"
.\"-----------------------------------------------------------
.SH NAME
ocli \- OwnTracks command-line interface GPS publisher
.\"-----------------------------------------------------------
.SH SYNOPSIS
.B ocli
[
-v
]
[
.IR parameter-file ... ]
.\"-----------------------------------------------------------
.SH DESCRIPTION
.B ocli
is the OwnTracks command line interface publisher, a small utility which connects to
.B 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.
.B ocli
reads GPS data from an installed
.B gpsd
daemon, and as soon as it has a fix publishes an OwnTracks payload.
.B ocli
will subsequently publish a message every \fCOCLI_INTERVAL\fR seconds or when it detects it has moved \fCOCLI_DISPLACEMENT\fR meters.
.PP
.B ocli
operates with a number of defaults which you can override using environment variables.
.SS Parameter files
Any number of path names can be passed as
.I parameter-file
arguments to
.B 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
.IR parameter-file .
If the file is executable, the line is read from its standard output.
.sp
.nf
.in 1i
.ft CW
echo 27.2 > temperature
ocli temperature /usr/bin/uname
.ft
.in
.fi
.sp
will produce a payload which might look like
.sp
.nf
.in 1i
.ft CW
{
"_type": "location",
"tst": 1577654651,
"lat": 48.856826,
"temperature" : "27.2",
"uname": "FreeBSD"
}
.ft
.in
.fi
.PP
Keys obtained from
.IR parameter-file s
must not overwrite JSON element names define by
.BR ocli ,
so, for example, a file called \fClat\fR will be silently ignored as it would clobber the JSON
\fClatitude\fR element.
.SS Control
It is possible to control
.B ocli
using a subset of OwnTrack's \fCcmd\fR commands.
.sp
.nf
.in 1i
.ft CW
t=owntracks/jpm/tiggr/cmd
mosquitto_pub -t $t -m "$(jo _type=cmd action=reportLocation)"
.fi
.in
.ft
.sp
The following commands are currently implemented:
.IP reportLocation 1i
causes
.B ocli
to publish its current location (providing
.B gpsd
has a fix).
.B ocli
sets \fCt:m\fR in the JSON to indicate the publish was manually requested.
.IP dump 1i
causes the program to publish its internal configuration to the topic \fC\fIbasetopic\fR\fC/dump\fR as a \fC_type: configuration\fR message.
.IP setConfiguration
permits setting some of
.BR ocli 's
internal values (\fClocatorInterval\fR and \fClocatorDisplacement\fR).
Note that these do not persist a restart.
.\"-----------------------------------------------------------
.SH OPTIONS
.IP -v 1i
Show version.
.IP -s 1i
By default,
.B ocli
prints informational messages to
.IR stdout .
This option silences those.
.\"-----------------------------------------------------------
.SH ENVIRONMENT
.B ocli
is operates with a number of compiled-in defaults which can be overridden using environment variables:
.IP \fCBASE_TOPIC\fR 1i
The MQTT base topic defaults to \fCowntracks/\fIusername\fR\fC/\fIhostname\fR, where
.I username
is the name of the logged in user, and
.I hostname
the short host name.
.IP \fCMQTT_HOST\fR 1i
The MQTT host defaults to \fClocalhost\fR.
.IP \fCMQTT_PORT\fR 1i
The MQTT port is \fC1883\fR.
.IP \fCMQTT_USER\fR 1i
The username to use to authenticate with the MQTT broker.
.IP \fCMQTT_PASS\fR 1i
The password to use to authenticate with the MQTT broker.
.IP \fCOCLI_CLIENTID\fR 1i
The MQTT clientId is set to \fC"ocli-\fIusername\fR\fC-\fIhostname\fR\fC"\fR.
.IP \fCGPSD_HOST\fR 1i
The address/hostname of the host on which
.B gpsd
is listening defaults to \fClocalhost\fR.
.IP \fCGPSD_PORT\fR 1i
The
.B gpsd
port nummber defaults to \fC2947\fR.
.IP \fCOCLI_TID\fR 1i
The two-letter OwnTracks tracker ID defaults to not being used.
.IP \fCOCLI_INTERVAL\fR 1i
The interval after which
.B ocli
will publish a location position defaults to 1 second and can be changed dynamically (see above).
.IP \fCOCLI_DISPLACEMENT\fR 1i
The distance after which
.B ocli
will publish a location position defaults to 0 meters and can be changed dynamically (see above).
.IP \fCOCLI_CACERT\fR 1i
The path to a PEM-encoded CA certificate which
.B ocli
uses to enable TLS/SSL. It is likely that the default MQTT port will need to be changed at the same time.
.\"-----------------------------------------------------------
.SH BUGS
Very likely.
.\"-----------------------------------------------------------
.SH AUTHOR
Jan-Piet Mens, https://jpmens.net
.\"-----------------------------------------------------------
.SH SEE ALSO
.nh
.BR jo (1),
.BR mosquitto_pub (1),
.BR pledge (2),
.BR unveil (2),
.BR gpsd (8),
.BR https://owntracks.org
.\" EOF ocli.1