1LIBGPS(3) GPSD Documentation LIBGPS(3)
2
6 libgps - C service library for communicating with the GPS daemon
7
9 C:
10 #include <gps.h>
12 int gps_open(char * server, char * port, struct gps_data_t * gpsdata)
14 int gps_send(struct gps_data_t * gpsdata, char * fmt, ...)
16 int gps_read(struct gps_data_t * gpsdata, char * message,
18 int message_size)
19 bool gps_waiting(const struct gps_data_t * gpsdata, int timeout)
21 char * gps_data(const struct gps_data_t * gpsdata)
23 int gps_unpack(char * buf, struct gps_data_t * gpsdata)
25 int gps_close(struct gps_data_t * gpsdata)
27 int gps_stream(struct gps_data_t * gpsdata, unsigned int flags,
29 void * data)
30 int gps_mainloop(struct gps_data_t * gpsdata, int timeout,
32 void (* hook)(struct gps_data_t *gpsdata))
33 const char * gps_errstr(int err)
35 Python:
37 import gps
39 session = gps.gps(host="localhost", port="2947")
40 session.stream(flags=gps.WATCH_JSON)
41 for report in session:
42 process(report) del session
43
45 libgps is a service library which supports communicating with an
46 instance of the gpsd(8), link it with the linker option -lgps. Some
47 systems may also require -lm.
48 Warning
50 Take care to conditionalize your code on the major and minor API
51 version symbols in gps.h; ideally, force a compilation failure if
52 GPSD_API_MAJOR_VERSION is not a version you recognize. See the GPSD
53 project website for more information on the protocol and API
54 changes.
55 All the functions described here use the gps_data_t structure. Consult
57 gps.h to learn more about gps_data_t, its data members, associated
58 structures. associated timestamps. Note that information will
59 accumulate in the session structure over time, and the 'valid' field is
60 not automatically zeroed by each gps_read(). It is up to the client to
61 zero that field when appropriate and to keep an eye on the fix and
62 sentence timestamps.
63 Warning
65 gps_data_t sets floating point variables to NaN when the actual
66 variable value is unknown. Check all floats and doubles with
67 isfinite() before using them. isnan() is not sufficient!
68 gps_open()
70 Calling gps_open() initializes a gps_data_t structure to hold the
71 data collected by the GPS, and sets up access to gpsd(8) via either
72 the socket or shared-memory export. The shared-memory export is
73 faster, but does not carry information about device activation and
74 deactivation events and will not allow you to monitor device packet
75 traffic.
76 gps_open() returns 0 on success, -1 on errors and is re-entrant.
78 errno is set depending on the error returned from the socket or
79 shared-memory interface; see gps.h for values and explanations;
80 also see gps_errstr(). The host address may be a DNS name, an IPv4
81 dotted quad, an IPV6 address, or the special value
82 GPSD_SHARED_MEMORY referring to the shared-memory export; the
83 library will do the right thing for any of these.
84 gps_close()
86 gps_close() ends the session and should only be called after a
87 successful gps_open(). It returns 0 on success, -1 on errors. The
88 shared-memory interface close always returns 0, whereas a socket
89 close can result in an error. For a socket close error it will have
90 set an errno from the call to the system’s close().
91 gps_send()
93 gps_send() writes a command to the gpsd daemon. It does nothing
94 when using the shared-memory export. The second argument must be a
95 format string containing elements from the command set documented
96 at gpsd(8). It may have % elements as for sprintf(3), which will be
97 filled in from any following arguments. This function returns a -1
98 if there was a Unix-level write error, otherwise 0. Please read the
99 LIMITATIONS section for additional information and cautions. See
100 gps_stream() as a possible alternative.
101 gps_read()
103 gps_read() accepts a response, or sequence of responses, from the
104 gpsd daemon and decodes the response into a gps_data_t. By default,
105 this function does either a blocking read for data from the gpsd
106 daemon or a fetch from shared memory; it returns a count of bytes
107 read for success, -1 with errno set on a Unix-level read error, -1
108 with errno not set if the socket to the gpsd daemon has closed or
109 if the shared-memory segment was unavailable, and 0 if no data is
110 available.
111 The second argument to gps_read() is usually NULL, and the third
113 argument is zero. If your application wants to see the raw data
114 from the gpsd daemon then set the second argument to the address of
115 your message buffer, and the third argument is the size of your
116 buffer. Use with care; this may not to be a NUL-terminated string
117 if WATCH_RAW is enabled.
118 gps_waiting()
120 gps_waiting() can be used to check whether there is new data from
121 the gpsd daemon. The second argument is the maximum amount of time
122 to block (in microseconds) waiting on input before returning. It
123 returns true if there is input waiting, false on timeout (no data
124 waiting) or error condition. When using the socket export, this
125 function is a convenience wrapper around a select(2) call, and
126 zeros errno on entry; you can test errno after exit to get more
127 information about error conditions.
128 Warning: under the shared-memory interface there is a tiny race
130 window between gps_waiting() and a following gps_read(); in that
131 context, because the latter does not block, it is probably better
132 to write a simple read loop.
133 gps_mainloop()
135 gps_mainloop() enables the provided hook function to be continually
136 called whenever there is gpsd data. The second argument is the
137 maximum amount of time to wait (in microseconds) on input before
138 exiting the loop (and return a value of -1). It will also return a
139 negative value on various errors.
140 gps_unpack()
142 gps_unpack() parses JSON from the argument buffer into the target
143 of the session structure pointer argument. Included in case your
144 application wishes to manage socket I/O itself.
145 gps_data()
147 gps_data() returns the contents of the client data buffer (it
148 returns NULL when using the shared-memory export). Use with care;
149 this may not to be a NUL-terminated string if WATCH_RAW is enabled.
150 gps_stream()
152 gps_stream() asks gpsd to stream the reports it has at you, to be
153 made available when you poll (not available when using the
154 shared-memory export). The second argument is a flag mask that sets
155 various policy bits; see the list below. Calling gps_stream() more
156 than once with different flag masks is allowed.
157 WATCH_DEVICE
159 Restrict watching to a specified device. The device path string
160 is given as the third argument (data).
161 WATCH_DISABLE
163 Disable the reporting modes specified by the other WATCH_
164 flags.
165 WATCH_ENABLE
167 Enable the reporting modes specified by the other WATCH_ flags.
168 This is the default.
169 WATCH_JSON
171 Enable JSON reporting of data. If WATCH_ENABLE is set, and no
172 other WATCH flags are set, this is the default.
173 WATCH_NEWSTYLE
175 Force issuing a JSON initialization and getting new-style
176 responses. This is the default.
177 WATCH_NMEA
179 Enable generated pseudo-NMEA reporting on binary devices.
180 WATCH_OLDSTYLE
182 Force issuing a W or R command and getting old-style responses.
183 Warning: this flag (and the capability) will be removed in a
184 future release.
185 WATCH_RARE
187 Enable reporting of binary packets in encoded hex.
188 WATCH_RAW
190 Enable literal passthrough of binary packets.
191 WATCH_SCALED
193 When reporting AIS or Subframe data, scale integer quantities
194 to floats if they have a divisor or rendering formula
195 associated with them.
196 gps_errstr()
198 gps_errstr() returns an ASCII string (in English) describing the
199 error indicated by a nonzero return value from gps_open().
200 The Python implementation supports the same facilities as the
202 socket-export calls in the C library; there is no shared-memory
203 interface. gps_open() is replaced by the initialization of a gps
204 session object; the other calls are methods of that object, and have
205 the same names as the corresponding C functions. However, it is simpler
206 just to use the session object as an iterator, as in the example given
207 below. Resources within the session object will be properly released
208 when it is garbage-collected.
209 import gps
211 session = gps.gps(host="localhost", port="2947")
212 session.stream(flags=gps.WATCH_JSON)
213 for report in session:
214 process(report) del session
215
217 By setting the environment variable GPSD_SHM_KEY, you can control the
218 key value used to create shared-memory segment used for communication
219 with gpsd. This will be useful mainly when isolating test instances of
220 gpsd from production ones.
221
223 The following is a fully functional minimal C client. Check the C
224 source for the other gpsd clients for more ideas.
225 // example gpsd client
227 // compile this way:
228 // gcc example.c -o example -lgps -lm
229 #include <gps.h>
230 #include <math.h> // for isfinite()
231 #include <unistd.h> // for sleep()
232 #define MODE_STR_NUM 4
234 static char *mode_str[MODE_STR_NUM] = {
235 "n/a",
236 "None",
237 "2D",
238 "3D"
239 };
240 int main(int argc, char *argv[])
242 {
243 struct gps_data_t gps_data;
244 if (0 != gps_open("localhost", "2947", &gps_data)) {
246 printf("Open error. Bye, bye\n");
247 return 1;
248 }
249 (void)gps_stream(&gps_data, WATCH_ENABLE | WATCH_JSON, NULL);
251 // Wait for data available.
253 while (gps_waiting(&gps_data, 5000000)) {
254 // will not block because we know data is available.
255 if (-1 == gps_read(&gps_data, NULL, 0)) {
256 printf("Read error. Bye, bye\n");
257 break;
258 }
259 if (MODE_SET != (MODE_SET & gps_data.set)) {
260 // did not even get mode, nothing to see here
261 continue;
262 }
263 if (0 > gps_data.fix.mode ||
264 MODE_STR_NUM <= gps_data.fix.mode) {
265 gps_data.fix.mode = 0;
266 }
267 printf("Fix mode: %s (%d) Time: ",
268 mode_str[gps_data.fix.mode],
269 gps_data.fix.mode);
270 if (TIME_SET == (TIME_SET & gps_data.set)) {
271 // not 32 bit safe
272 printf("%ld.%09ld ", gps_data.fix.time.tv_sec,
273 gps_data.fix.time.tv_nsec);
274 } else {
275 puts("n/a ");
276 }
277 if (isfinite(gps_data.fix.latitude) &&
278 isfinite( gps_data.fix.longitude)) {
279 // Display data from the GPS receiver if valid.
280 printf("Lat %.6f Lon %.6f\n",
281 gps_data.fix.latitude, gps_data.fix.longitude);
282 }
283 }
284 // When you are done...
286 (void)gps_stream(&gps_data, WATCH_DISABLE, NULL);
287 (void)gps_close(&gps_data);
288 return 0;
289 }
290
292 On some systems (those which do not support implicit linking in
293 libraries) you may need to add -lm to your link line when you link
294 libgps. It is always safe to do this.
295 In the C API, incautious use of gps_send() may lead to subtle bugs. In
297 order to not bloat struct gps_data_t with space used by responses that
298 are not expected to be shipped in close sequence with each other, the
299 storage for fields associated with certain responses are combined in a
300 union.
301 The risky set of responses includes VERSION, DEVICELIST, RTCM2, RTCM3,
303 SUBFRAME, AIS, GST, and ERROR; it may not be limited to that set. The
304 logic of the gpsd daemon’s watcher mode is careful to avoid dangerous
305 sequences, but you should read and understand the layout of struct
306 gps_data_t before using gps_send() to request any of these responses.
307
309 The gps_query() supported in major versions 1 and 2 of this library has
310 been removed. With the new streaming-oriented wire protocol behind this
311 library, it is extremely unwise to assume that the first transmission
312 from the gpsd daemon after a command is shipped to it will be the
313 response to command.
314 If you must send commands to the gpsd daemon explicitly, use gps_send()
316 but beware that this ties your code to the GPSD wire protocol. It is
317 not recommended.
318 In some versions of the API gps_read() is a blocking call and there was
320 a POLL_NONBLOCK option to make it nonblocking. gps_waiting() was added
321 to reduce the number of wrong ways to code a polling loop.
322 See the comment above the symbol GPSD_API_MAJOR_VERSION in gps.h for
324 recent changes.
325
327 C sample code by Gary E. Miller <gem@rellim.com> and Charles Curley
328 <charlescurley@charlescurley.com>
329
331 gpsd(8), gps(1), gpsd_json(5), libgpsmm(3)
332
334 • GPSD Client Example Code
335 <https://gpsd.io/gpsd-client-example-code.html> An annotated
336 example client.
337 • GPSD Client HOWTO <https://gpsd.io/client-howto.html> A GPS client
339 HOWTO.
340 • Project web site: https://gpsd.io/
342
344 This file is Copyright 2013 by the GPSD project
345 SPDX-License-Identifier: BSD-2-clause
346
348 Eric S. Raymond
349GPSD, Version 3.24 2021-09-20 LIBGPS(3)